zhenghy/u-claw
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: 文档改为英文，并修正过时内容
Some checks failed
Tests / test (push) Has been cancelled
Details

Browse Source 
不是翻译 —— 多数文档描述的行为已经不存在了。

先修一个更基本的问题：我们不拥有 u-claw.org 域名，那是上游的。所以之前写在
README、诊断包提示、联系方式里的 help@u-claw.org 全都会把用户的问题发给
上游 —— 一个没有理由回复的人。改为指向我们自己的 issue tracker，并加断言
禁止再出现指向该域名的支持入口。

重写（内容过时，不是语言问题）：
- install/README.md —— 还写着 10 个中国技能、DeepSeek 优先、国内镜像。
  现在按实际流程写：技能读 manifest、模型菜单 Gemini 优先、bundle 有
  SHA256 校验。并如实写明 curl|bash 在受管企业电脑上会被 EDR 拦。
- CLAUDE.md 的模型配置整节 —— 还在描述虾盘云首选卡片和 12 个 provider，
  那个界面已经换成单框 Key 输入了。
- SECURITY.md —— 安全报告原本指向上游维护者个人邮箱。fork 之后那条路由
  是错的：漏洞会发给写不了这份代码、也修不了的人。
- CONTRIBUTING.md —— 补上 fork 关系、pre-push 钩子怎么装、以及
  `node --test tests/` 为什么不能用。

翻译并保留：
- bootable/README.md、TROUBLESHOOTING.md —— 面向用户，顺带把
  「国内镜像」「小米/华为 BIOS 按键」等换成目标市场的实际情况

HANDOFF.md 重写为一份事故复盘：原文一半是过时的一次性交接笔记（引用的
website/guide.html 已不在本仓库），另一半是 persistence.dat 未格式化导致
启动失败的排查记录 —— 后者有长期价值，尤其是「读 offset 1080 的两字节
验证 ext4」这个判断方法，已同时写进 bootable/README.md。

bootable/IMPROVEMENTS_SUMMARY.md 保留中文，加了说明：它是上游 fork 前的
历史改进记录，没人引用，描述的是已完成的工作而非当前行为。翻译它反而会
让人误以为是现行文档。

新增 skills/en/uclaw-help —— 把「怎么用、东西在哪、出问题怎么办」做成
内置知识，每个角色都装。方案 C10.8：能问的产品才是不需要学的产品。
This commit is contained in:
zheng
2026-08-17 19:12:07 +08:00
parent 46a1218fc8
commit 3221856d50
20 changed files with 937 additions and 883 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
CLAUDE.md
View File

@@ -7,11 +7,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
**This repo IS the USB drive content**, minus large dependencies. The relationship:
```
代码库（git）= U 盘骨架（脚本 + HTML + 小文件）
repository (git) = the drive's skeleton — scripts, HTML, small files
↓ bash setup.sh
完整文件夹 = U 盘内容（骨架 + Node.js + OpenClaw）
↓ 拷贝到 U 盘
U 盘 = 插上就能用
working folder = the drive's contents — skeleton + Node.js + OpenClaw
↓ copy onto a USB drive
USB drive = plug in and go
```
The repo is NOT a "build tool" or "generator" — it IS the USB structure. `setup.sh` only fills in large deps that can't go in git. After `setup.sh`, the `portable/` folder is directly copyable to a USB drive.
@@ -127,16 +127,21 @@ u-claw-app/ [DEPRECATED 2026-06-19, archived — not built/published] El
(main.js ~400 lines). Kept for archive only; see u-claw-app/DEPRECATED.md.
Bundles Node.js in resources/runtime/node-{platform}-{arch}
bootable/ Linux 可启动 U 盘模块（完全独立，不依赖其他模块）
4 步 PowerShell 脚本 (Windows 上制作)
Ventoy 1.0.99 + Ubuntu 24.04 LTS + casper-rw 持久化
linux-setup/ — setup-openclaw.sh 安装到 /opt/u-claw/
独立仓库镜像: gitea.fanghe.it.com/zhenghy/u-claw-linux
bootable/ Linux bootable USB. Fully self-contained — references nothing
from the other modules, on purpose.
Four PowerShell scripts, run on Windows, in order.
Ventoy 1.0.99 + Ubuntu 24.04 LTS + casper-rw persistence
linux-setup/setup-openclaw.sh installs into /opt/u-claw/
Mirror: gitea.fanghe.it.com/zhenghy/u-claw-linux
install/ 一键在线安装模块（curl | bash / irm | iex）
install/ One-line network install (curl | bash / irm | iex).
install.sh (Mac/Linux) + install.ps1 (Windows)
7 步流程: 系统检测 → Node.js → OpenClaw → QQ插件 → 技能(读 skills/manifest.json) → 模型配置 → 启动脚本
安装到 ~/.uclaw/，与 Mac-Install.command 结果相同
Detect → Node.js → OpenClaw → QQ plugin → skills (from
skills/manifest.json) → model → start script → verify.
Installs to ~/.uclaw/; same result as advanced/Mac-Install.command.
These run with no checkout, so they cannot read origin.json
and carry URLs as literals — tests/origin.test.mjs keeps the
two in step.
```
@@ -173,35 +178,76 @@ Pure-Node, zero-dependency `.mjs` modules (use `fetch` + `node:zlib` only). All
| File | Purpose |
|------|---------|
| `check-update.mjs` / `publish-latest.mjs` | Portable self-update: check installed vs latest `OPENCLAW_VERSION`; publish helper. |
| `portable-cache.mjs` | **启动加速核心**：把"重 IO、可重建"的缓存从 U 盘搬到本机硬盘。算出本机缓存根（win `%LOCALAPPDATA%\U-Claw\<slot>` / mac `~/Library/Caches/U-Claw` / linux `$XDG_CACHE_HOME`，UUID 隔离让换盘符仍复用），输出 `NODE_COMPILE_CACHE` 路径，并把 `data/.openclaw/browser` 做成 junction(win)/symlink(mac) 指向本机盘——浏览器 user-data 的海量随机小写不再砸 U 盘。CLI 打印 `KEY=VALUE` 供启动脚本 source。静默失败：取不到就缓存留 U 盘照常启动。 |
| `prewarm.mjs` | gateway 首轮预热：端口就绪后后台静默 GET `/ready`→`/status`→`/models`（带 `x-openclaw-token`），把 config/model 子系统在 runtime 内存里热起来，用户首次点发送不再等。零依赖、短超时、后台 detach。 |
| `loading.html` | 启动首屏（splash）：双击启动后立刻打开，给即时反馈消除"黑窗假死"。本页每秒 fetch `/ready`，gateway 真就绪后自动 `location.replace` 跳 Dashboard——天然规避"gateway 没起就开 Dashboard 拒连"(issue #46/#48)。端口经 `?port=` 传入。 |
| `start.mjs` | **启动主逻辑（2026-08-17 起）**：运行时检测、数据目录、缓存加速、默认配置、依赖安装、NO_PROXY、微信插件、config-server 启动与端口发现、gateway 端口扫描、首屏与控制台打开、预热、兜底轮询、退出清理。`.bat`/`.command` 退化为 ~30 行的启动壳。这样两平台不会再漂，且所有面向用户的文案可翻译。 |
| `i18n.mjs` + `messages/{en,zh-CN}.json` | 启动器与本地页面的词条。语言优先级：显式覆盖 > 盘内配置 `uclaw.locale` > 系统 locale > en —— **语言跟盘走，不跟机器走**。key 用语义命名，缺失自动回落英文。 |
| ~~`wait-gateway.bat`~~ | 已移除（2026-08-17）。兜底轮询并入 `start.mjs` 的 `watchGatewayReady()`，现在 macOS 也有了 —— 此前只有 Windows 有。 |
| `maintain.sh` | Maintenance/diagnostics script. |
| `portable-cache.mjs` | **The startup-speed core.** Moves the heavy, rebuildable caches off the USB drive onto local disk: works out a cache root (win `%LOCALAPPDATA%\U-Claw\<slot>`, mac `~/Library/Caches/U-Claw`, linux `$XDG_CACHE_HOME`), keyed by a UUID so the same cache is reused when the drive gets a different letter. Emits `NODE_COMPILE_CACHE`, and redirects `data/.openclaw/browser` to local disk via a junction (Windows) or symlink (macOS) — the browser profile's endless small random writes are what makes a USB drive feel broken. Prints `KEY=VALUE` for the launcher to read. Fails silently: if it cannot, the cache stays on the drive and startup continues. |
| `prewarm.mjs` | Wakes the gateway once it is listening: background `GET /ready` → `/status` → `/models` with the auth token, so the config and model subsystems are warm before the user's first message. Zero dependencies, short timeout, detached. |
| `loading.html` | The splash. Opens the instant the launcher starts, so a slow first run looks like progress rather than a frozen black window. Polls `/ready` once a second and moves on when the gateway answers — which sidesteps the old "dashboard opened before the gateway existed, connection refused" failure (issues #46, #48). Port arrives as `?port=`. |
| `start.mjs` | **All startup logic (since 2026-08-17).** Runtime detection, data folders, cache acceleration, default config, dependency install, NO_PROXY, WeChat plugin, config-server launch and port discovery, gateway port scan, opening the splash and Settings, prewarm, the fallback watcher, and cleanup on exit. The `.bat` and `.command` files are ~30-line shells over it. Two reasons: the platforms cannot drift apart again, and every user-facing string becomes translatable — neither is possible while the logic lives in a `.bat` that must stay pure ASCII. |
| `i18n.mjs` + `messages/{en,zh-CN}.json` | Strings for the launcher and the local pages. Resolution order: explicit override > `uclaw.locale` on the drive > system locale > `en`. **The language follows the drive, not the machine** — someone who set it up in Chinese and plugs it into a colleague's English Windows still gets Chinese. Keys are semantic, and a missing one falls back to readable English rather than leaking the key. |
| `self-heal.mjs` | Checks and repairs run when startup fails, before the user is told anything. Missing folders, a damaged settings file (moved aside, never deleted), a leftover port record, an interrupted copy, a dangling cache link. What it cannot fix produces a redacted diagnostics report. Every repair must be safe on a healthy drive — they all run whenever startup fails, including for reasons none of them explain. |
| `provider-detect.mjs` | Maps an API key prefix to its provider, so nobody has to know what a Base URL is. `sk-ant-` must be checked before the plain `sk-` catch-all. |
| ~~`wait-gateway.bat`~~ | Removed 2026-08-17. The fallback watcher moved into `start.mjs` as `watchGatewayReady()`, so macOS has it too — it was Windows-only before. |
### 启动加速（吸收自 v2 u-clawx 4.0 的工程经验，2026-06-17）
### Why startup is fast off a slow drive (2026-06-17)
便携版从 U 盘启动慢，瓶颈在 **U 盘随机小写 IO** + **首屏无反馈** + **首轮冷启动**。移植 4.0 的 4 个可在纯脚本层复刻的手段：
Running from a USB drive is slow for three separate reasons, and each needed its
own fix: **small random writes on the drive**, **no feedback on the first
screen**, and **a genuinely cold first run**.
1. **缓存搬本机**（`portable-cache.mjs`）：浏览器 user-data（OpenClaw 硬编码在 `CONFIG_DIR/browser/`，无单独环境变量，故用 junction/symlink 重定向）+ V8 编译缓存（`NODE_COMPILE_CACHE`）落本机 SSD。业务数据（`openclaw.json`、`memory`、账号）仍留 U 盘，便携性不变。UUID 隔离让 D:→E: 换盘符仍命中同一份本机缓存。
2. **Node 编译缓存**：`openclaw.mjs` 本就调 `module.enableCompileCache()`，但默认落系统 temp（可能被清）。启动脚本显式把 `NODE_COMPILE_CACHE` 指向本机固定目录，二次启动稳定命中。
3. **启动首屏**（`loading.html`）：双击即弹，自轮询自跳转。
4. **首轮预热**（`prewarm.mjs`）：后台唤醒 config/model。
5. **动态探测**：Windows 把写死的 `timeout /t 2`（等 config-server）改成轮询 18788，省掉白等。
1. **Move the caches to local disk** (`portable-cache.mjs`). The browser profile
is the worst offender — OpenClaw hardcodes it at `CONFIG_DIR/browser/` with no
environment variable to move it, so we redirect it with a junction (Windows)
or symlink (macOS). The V8 compile cache goes the same way via
`NODE_COMPILE_CACHE`. **Business data stays on the drive** — `openclaw.json`,
`memory`, accounts — so portability is unaffected. A UUID key means the same
cache is reused when the drive comes up as `E:` instead of `D:`.
2. **Pin the compile cache.** `openclaw.mjs` already calls
`module.enableCompileCache()`, but it defaults to system temp, which gets
cleaned. Pointing `NODE_COMPILE_CACHE` at a stable local directory makes the
second launch reliably fast rather than occasionally fast.
3. **Show something immediately** (`loading.html`). It opens on double-click and
polls for readiness itself.
4. **Warm the gateway** (`prewarm.mjs`) in the background once the port answers.
5. **Poll instead of guessing.** Windows used to `timeout /t 2` waiting for the
config server; it now polls the port and proceeds the moment it is up.
> 注：OpenClaw 自身的临时/lock/chrome-mcp 文件已走 `os.tmpdir()`（系统 temp，**不在 U 盘**），无需处理；真正落 U 盘的只有 `OPENCLAW_HOME=data/` 下的内容。
> OpenClaw's own temp, lock and chrome-mcp files already go to `os.tmpdir()` —
> system temp, **not the drive** — so they need no handling. The only thing that
> genuinely lands on the drive is what lives under `OPENCLAW_HOME=data/`.
> **纯开源,无追踪**: 这个开源版**不含**设备指纹 (`fingerprint.mjs`)、自动开户 (`bootstrap-xiapan.mjs`/`xiapan-client.mjs`)、崩溃上报 (`report-bug.mjs`) 等商业版逻辑——这些已在 2026-06-17 移除。U-Claw 不绑定设备、不打指纹、不向 `api.u-claw.org` 上传任何数据。
> **No tracking.** This build contains none of the commercial-version logic —
> no device fingerprinting (`fingerprint.mjs`), no automatic account creation
> (`bootstrap-xiapan.mjs` / `xiapan-client.mjs`), no crash reporting
> (`report-bug.mjs`). Upstream removed them on 2026-06-17. Nothing is bound to a
> device and nothing is uploaded to `api.u-claw.org`.
### 模型配置 ("选模型填 Key")
### Choosing a model (rewritten 2026-08-17)
设置页（`config-server/public/index.html`，旧入口 `Config.html` 会重定向过来）列出模型供用户挑选。首选卡片是 **虾盘云** (Xiapan Cloud 中转站,`api.u-claw.org/v1`)
——一个 Key 调用 DeepSeek / Claude / GPT / 通义 等全部模型,但和其它 provider 一样**需要用户自己去
`https://u-claw.org/cloud.html` 注册拿 Key**,不再自动开户。其余 provider (DeepSeek/通义/Kimi/智谱/
豆包/MiniMax/OpenAI/Claude/Groq/硅基流动/自定义) 填各家官方 Key 即可。配置只写本地
`data/.openclaw/openclaw.json`。
Settings is `config-server/public/index.html`. `Config.html` in `advanced/` is a
redirect shim to it — the old standalone copy called the API on a root-relative
path while only ever being opened from `file://`, so its Save button had been
failing silently.
**The first screen asks for one thing: an API key.** It used to lay out twelve
provider cards and then demand a Base URL and a model name — three technical
fields on the first screen a non-technical user ever saw.
The key itself says which provider it belongs to (`lib/provider-detect.mjs`
maps the prefix), so:
1. Paste the key
2. After an 800ms pause, `POST /api/test-key` sends a 1-token request and reports
what actually happened — "connected in 340ms", or a sentence saying what to do
3. A model dropdown appears once it works, so the choice is not locked to
whatever the first key implied
The check runs server-side deliberately: the browser cannot reach most model
endpoints cross-origin, and doing it in the config server means the key never
leaves the machine by any path the page controls.
Endpoint and model name still exist, under a collapsed *Advanced* section that
only opens by itself when the key is not one we recognise.
Everything is written to `data/.openclaw/openclaw.json` on the drive.
## What NOT to Commit
@@ -210,29 +256,33 @@ Never commit runtime dependencies or build artifacts. These are all in .gitignor
- `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.
Release artifacts go to the release page, 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)
- External links go to `origin.json`'s `urls`, or to `github.com/openclaw/openclaw` for the runtime.
We do **not** own `u-claw.org` — that is the upstream project's domain, so never
offer an address on it as a support route.
- 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
- Mac Intel (x64): ✅ Working（portable 需先运行 setup.sh 下载 node-mac-x64）
- Windows x64: 🚧 In development
- Linux x64 (Bootable USB): ✅ `bootable/` 目录 + 独立仓库 [u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux)
- Mac Intel (x64): ✅ Working — run `setup.sh` first to fetch `node-mac-x64`
- Windows x64: 🚧 **Carries unverified changes.** A large amount of PowerShell and
the `.bat` path resolution were written on a Mac with no PowerShell available and
have never been through a parser. See `U盘实测清单.md` in the workspace root.
- Linux x64 (bootable USB): ✅ see `bootable/`, mirrored at [u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux)
## Bootable Linux Key Details
- **制作环境**: Windows 10/11 + PowerShell (Admin)，4 步脚本
- **U 盘要求**: 32GB+ USB 3.0
- **技术栈**: Ventoy 1.0.99 引导 → Ubuntu 24.04 ISO → casper-rw 持久化 → OpenClaw 安装到 /opt/u-claw/
- **下载源**: ISO 走 releases.ubuntu.com，Node.js 走 nodejs.org，npm 走 registry.npmjs.org
- **Linux 环境变量**: `OPENCLAW_HOME=/opt/u-claw/data/.openclaw`
- **bootable/ 完全独立**: 不引用 portable/、u-claw-app/ 的任何文件，修改互不影响
- **同步**: bootable/ 内容与 u-claw-linux 仓库保持一致，改一边要记得同步另一边
- **Built on**: Windows 10/11, PowerShell as Administrator, four scripts in order
- **Drive**: 32 GB or larger, USB 3.0
- **Stack**: Ventoy 1.0.99 → Ubuntu 24.04 ISO → casper-rw persistence → OpenClaw in /opt/u-claw/
- **Sources**: ISO from releases.ubuntu.com, Node.js from nodejs.org, packages from registry.npmjs.org
- **Environment**: `OPENCLAW_HOME=/opt/u-claw/data/.openclaw`
- **Self-contained**: references nothing from `portable/` or `u-claw-app/`, so a change here cannot break them or vice versa
- **Mirrored**: kept identical to the u-claw-linux repo — a change in one needs the same change in the other