359509d146
- 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
78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# 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
|