docs: add CLAUDE.md, rewrite llms.txt with accurate install/config guide

- CLAUDE.md: architecture, dev setup, branding rules for AI agents - llms.txt: update version to 2.0, fix platform support, add developer quick start, env vars, config format, correct script names
2026-03-12 11:54:25 +08:00
parent 50fb41fc1c
commit 359509d146
2 changed files with 138 additions and 33 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+U-Claw wraps [OpenClaw](https://github.com/openclaw/openclaw) into two distribution forms: a USB portable version (bash/batch scripts + HTML config UI) and an Electron desktop app. Both share the same OpenClaw core dependency and Config.html interface. The repo contains only source code — runtime binaries (Node.js, node_modules, build artifacts) are downloaded at dev time and excluded from git.
+
+## Development Setup
+
+```bash
+# Portable version
+cd portable && bash setup.sh    # Downloads Node.js v22 + OpenClaw + QQ plugin to app/
+bash Mac-Start.command          # Launch (Mac ARM64 only currently)
+
+# Electron desktop app
+cd u-claw-app
+npm install --registry=https://registry.npmmirror.com
+npm start                       # Dev mode (electron . --dev)
+npm run build:mac-arm64         # Build Mac ARM64 DMG
+npm run build:win               # Build Windows NSIS + portable
+```
+
+Testing should be done in a separate clone at `~/uclaw-dev/u-claw/`, not in this dev repo. This repo stays clean (no node_modules, no app/ runtime).
+
+## Architecture
+
+```
+portable/           Bash/Batch scripts + HTML pages
+                    Expects app/core/ (OpenClaw) and app/runtime/ (Node.js) at runtime
+                    Config stored in data/.openclaw/openclaw.json (relative, on USB)
+
+u-claw-app/         Electron app (main.js 419 lines)
+                    Bundles Node.js in resources/runtime/node-{platform}-{arch}
+                    Config stored in app.getPath('userData')/.openclaw/
+                    Spawns openclaw.mjs gateway as child process
+
+website/            Static HTML deployed to u-claw.org via Vercel
+                    vercel.json sets outputDirectory: "website"
+
+usb-scripts/        Extract U-Claw.tar.gz + launch (for USB distribution)
+```
+
+Both portable and desktop versions auto-find a free port in range 18789–18799 and start the OpenClaw gateway. On first run, they detect whether a model is configured — if not, they open Config.html; otherwise, they open the dashboard.
+
+## Key Technical Details
+
+- **Node.js discovery**: Portable looks at `app/runtime/node-mac-arm64/bin/node`; Electron looks at `resources/runtime/node-{platform}-{arch}` then falls back to system `node`
+- **China mirrors**: All downloads use `npmmirror.com` — Node.js binaries from `npmmirror.com/mirrors/node`, npm packages from `registry.npmmirror.com`
+- **Environment variables**: `OPENCLAW_HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH` control where OpenClaw reads config
+- **macOS quarantine**: Mac scripts run `xattr -rd com.apple.quarantine` to remove Gatekeeper blocks
+- **Config format**: `{"gateway":{"mode":"local","auth":{"token":"uclaw"}},"agent":{"model":"...","apiKey":"..."}}`
+- **Config hot-reload**: OpenClaw watches `openclaw.json` and applies changes without restart
+
+## What NOT to Commit
+
+Never commit runtime dependencies or build artifacts. These are all in .gitignore:
+- `portable/app/` and `portable/data/` (runtime + user data)
+- `u-claw-app/node_modules/`, `u-claw-app/release/`, `u-claw-app/resources/runtime/`
+- `*.dmg`, `*.exe`, `*.blockmap`
+
+Release artifacts go to GitHub Releases, not the repo.
+
+## Branding Rules
+
+- Use only official `openclaw` (not `openclaw-cn` or any community fork)
+- All npm installs reference `openclaw@latest` (official package)
+- External links point to `u-claw.org` (our site) or `github.com/openclaw/openclaw` (upstream)
+- No references to competitor products (Qclaw, AutoClaw) in any tracked files
+- Skill marketplace links point to `skillhub.tencent.com` or `github.com/openclaw/clawhub`
+
+## Platform Support Status
+
+- Mac Apple Silicon (ARM64): ✅ Working
+- Windows x64: 🚧 In development
+- Mac Intel (x64): ❌ Not yet
+- Linux: ❌ Not yet