docs: 文档改为英文，并修正过时内容

不是翻译 —— 多数文档描述的行为已经不存在了。先修一个更基本的问题：我们不拥有 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：能问的产品才是不需要学的产品。
2026-08-17 19:12:07 +08:00
parent 46a1218fc8
commit 3221856d50
20 changed files with 937 additions and 883 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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）
+working folder    = the drive's contents — skeleton + Node.js + OpenClaw
-     ↓ 拷贝到 U 盘
+     ↓ copy onto a USB drive
-U 盘 = 插上就能用
+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 盘模块（完全独立，不依赖其他模块）
+bootable/           Linux bootable USB. Fully self-contained — references nothing
-                    4 步 PowerShell 脚本 (Windows 上制作)
+                    from the other modules, on purpose.
-                    Ventoy 1.0.99 + Ubuntu 24.04 LTS + casper-rw 持久化
+                    Four PowerShell scripts, run on Windows, in order.
-                    linux-setup/ — setup-openclaw.sh 安装到 /opt/u-claw/
+                    Ventoy 1.0.99 + Ubuntu 24.04 LTS + casper-rw persistence
-                    独立仓库镜像: gitea.fanghe.it.com/zhenghy/u-claw-linux
+                    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) → 模型配置 → 启动脚本
+                    Detect → Node.js → OpenClaw → QQ plugin → skills (from
-                    安装到 ~/.uclaw/，与 Mac-Install.command 结果相同
+                    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 盘照常启动。 |
+| `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` | gateway 首轮预热：端口就绪后后台静默 GET `/ready`→`/status`→`/models`（带 `x-openclaw-token`），把 config/model 子系统在 runtime 内存里热起来，用户首次点发送不再等。零依赖、短超时、后台 detach。 |
+| `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` | 启动首屏（splash）：双击启动后立刻打开，给即时反馈消除"黑窗假死"。本页每秒 fetch `/ready`，gateway 真就绪后自动 `location.replace` 跳 Dashboard——天然规避"gateway 没起就开 Dashboard 拒连"(issue #46/#48)。端口经 `?port=` 传入。 |
+| `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` | **启动主逻辑（2026-08-17 起）**：运行时检测、数据目录、缓存加速、默认配置、依赖安装、NO_PROXY、微信插件、config-server 启动与端口发现、gateway 端口扫描、首屏与控制台打开、预热、兜底轮询、退出清理。`.bat`/`.command` 退化为 ~30 行的启动壳。这样两平台不会再漂，且所有面向用户的文案可翻译。 |
+| `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` | 启动器与本地页面的词条。语言优先级：显式覆盖 > 盘内配置 `uclaw.locale` > 系统 locale > en —— **语言跟盘走，不跟机器走**。key 用语义命名，缺失自动回落英文。 |
+| `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. |
-| ~~`wait-gateway.bat`~~ | 已移除（2026-08-17）。兜底轮询并入 `start.mjs` 的 `watchGatewayReady()`，现在 macOS 也有了 —— 此前只有 Windows 有。 |
+| `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. |
-| `maintain.sh` | Maintenance/diagnostics script. |
+| `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: 换盘符仍命中同一份本机缓存。
+1. **Move the caches to local disk** (`portable-cache.mjs`). The browser profile
-2. **Node 编译缓存**：`openclaw.mjs` 本就调 `module.enableCompileCache()`，但默认落系统 temp（可能被清）。启动脚本显式把 `NODE_COMPILE_CACHE` 指向本机固定目录，二次启动稳定命中。
+   is the worst offender — OpenClaw hardcodes it at `CONFIG_DIR/browser/` with no
-3. **启动首屏**（`loading.html`）：双击即弹，自轮询自跳转。
+   environment variable to move it, so we redirect it with a junction (Windows)
-4. **首轮预热**（`prewarm.mjs`）：后台唤醒 config/model。
+   or symlink (macOS). The V8 compile cache goes the same way via
-5. **动态探测**：Windows 把写死的 `timeout /t 2`（等 config-server）改成轮询 18788，省掉白等。
+   `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`)
+Settings is `config-server/public/index.html`. `Config.html` in `advanced/` is a
-——一个 Key 调用 DeepSeek / Claude / GPT / 通义 等全部模型,但和其它 provider 一样**需要用户自己去
+redirect shim to it — the old standalone copy called the API on a root-relative
-`https://u-claw.org/cloud.html` 注册拿 Key**,不再自动开户。其余 provider (DeepSeek/通义/Kimi/智谱/
+path while only ever being opened from `file://`, so its Save button had been
-豆包/MiniMax/OpenAI/Claude/Groq/硅基流动/自定义) 填各家官方 Key 即可。配置只写本地
+failing silently.
-`data/.openclaw/openclaw.json`。
+
 **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）
+- Mac Intel (x64): ✅ Working — run `setup.sh` first to fetch `node-mac-x64`
- Windows x64: 🚧 In development
+- Windows x64: 🚧 **Carries unverified changes.** A large amount of PowerShell and
- Linux x64 (Bootable USB): ✅ `bootable/` 目录 + 独立仓库 [u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux)
+  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 步脚本
+- **Built on**: Windows 10/11, PowerShell as Administrator, four scripts in order
- **U 盘要求**: 32GB+ USB 3.0
+- **Drive**: 32 GB or larger, USB 3.0
- **技术栈**: Ventoy 1.0.99 引导 → Ubuntu 24.04 ISO → casper-rw 持久化 → OpenClaw 安装到 /opt/u-claw/
+- **Stack**: Ventoy 1.0.99 → Ubuntu 24.04 ISO → casper-rw persistence → OpenClaw in /opt/u-claw/
- **下载源**: ISO 走 releases.ubuntu.com，Node.js 走 nodejs.org，npm 走 registry.npmjs.org
+- **Sources**: ISO from releases.ubuntu.com, Node.js from nodejs.org, packages from registry.npmjs.org
- **Linux 环境变量**: `OPENCLAW_HOME=/opt/u-claw/data/.openclaw`
+- **Environment**: `OPENCLAW_HOME=/opt/u-claw/data/.openclaw`
- **bootable/ 完全独立**: 不引用 portable/、u-claw-app/ 的任何文件，修改互不影响
+- **Self-contained**: references nothing from `portable/` or `u-claw-app/`, so a change here cannot break them or vice versa
- **同步**: bootable/ 内容与 u-claw-linux 仓库保持一致，改一边要记得同步另一边
+- **Mirrored**: kept identical to the u-claw-linux repo — a change in one needs the same change in the other
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,164 +1,147 @@
-# 贡献指南 / Contributing to U-Claw
+# Contributing
-感谢有兴趣参与 U-Claw 开发！这份文档会告诉你怎么开始、怎么提 issue、怎么提 PR。
+## The mental model, first
-## TL;DR
+> **This repository is the USB drive's contents** — scripts, HTML, small files.
 > **After `setup.sh` it is a working drive** — the above plus Node.js and OpenClaw.
- **报 bug** → 用 [Bug 模板](.github/ISSUE_TEMPLATE/bug_report.md)，**贴完整报错**，不要只发截图
+It is not a build tool that produces a drive. It *is* the drive. That one idea
- **提需求** → 用 [Feature 模板](.github/ISSUE_TEMPLATE/feature_request.md)，先说清楚使用场景
+explains most of the layout.
 - **写代码** → fork → 改 → 自己跑过 → 提 PR，PR 说明照模板填，不要空白 PR
 - **改文档** → 直接 PR 即可
-## 项目结构（记住这个心智模型）
+Four distribution forms, deliberately independent — changing one does not touch
 the others:
-> **本仓库 = U 盘骨架**：脚本 + HTML + 小文件
+| Directory | Form | Entry point |
-> **`bash setup.sh` 之后 = U 盘内容**：骨架 + Node.js + OpenClaw
+|---|---|---|
 | `portable/` | USB drive — **the main product** | `advanced/setup.sh` → `START HERE - Mac.command` |
 | `bootable/` | Linux USB that boots a machine with no OS | `1-prepare-usb.ps1` → `4-copy-to-usb.ps1` |
 | `install/` | One-line network install | `install.sh` / `install.ps1` |
 | `u-claw-app/` | Electron desktop — **deprecated**, archive only | not built |
-四种发布形态，互相独立，改其中一个不影响其它：
+## This is a fork
-| 目录 | 形态 | 入口 |
+Upstream is `github.com/dongsheng123132/u-claw`. We host at
-|------|------|------|
+`gitea.fanghe.it.com/zhenghy/u-claw` and **do not send changes back**: this build
-| `portable/` | 便携 USB | `setup.sh` → `Mac-Start.command` / `Windows-Start.bat` |
+removes the China-market defaults that are the point of the upstream project.
 | `u-claw-app/` | Electron 桌面 | `npm run dev` / `npm run build:mac-arm64` |
 | `bootable/` | Linux 可启动 U 盘 | `1-prepare-usb.ps1` → `4-copy-to-usb.ps1` |
 | `install/` | 一键在线安装 | `install.sh` (Mac/Linux) / `install.ps1` (Windows) |
-## 开发环境
+If you are fixing something we inherited unchanged, consider telling them too.
 ## Getting set up
 ```bash
-# 1. Clone
+git clone ssh://git@gitea.fanghe.it.com:222/zhenghy/u-claw.git
 git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
 cd u-claw
-# 2. 选一个形态调试。最快的是 portable/
+# Enable the pre-push hook. Nothing installs it for you, and it is the only
-cd portable
+# thing reliably running the tests — see below.
-bash setup.sh                    # 下载 Node.js + OpenClaw 到 app/
+git config core.hooksPath .githooks
-bash Mac-Start.command           # macOS 启动
+
-# 或 Windows: 双击 Windows-Start.bat
+# The fastest thing to iterate on is the portable build
 cd portable/advanced && bash setup.sh    # fetches Node.js + OpenClaw into ../app/
 cd .. && bash "START HERE - Mac.command"
 ```
-平台支持现状：
+| Platform | State |
 |---|---|
 | macOS Apple Silicon | ✅ main development platform |
 | macOS Intel | ✅ works — `setup.sh` fetches `node-mac-x64` first |
 | Windows x64 | 🚧 **needs verification** — see below |
 | Linux x64 | ✅ via `bootable/` |
- macOS Apple Silicon (ARM64)：✅ 主开发平台
+> **Windows currently carries unverified changes.** A large amount of PowerShell
- macOS Intel：✅ 工作（需先跑 setup.sh 下 node-mac-x64）
+> and several `.bat` path-resolution changes were written on a Mac with no
- Windows x64：🚧 持续完善
+> PowerShell available, so they have never been through a parser. If you have a
- Linux x64 (Bootable USB)：✅ 用 `bootable/`
+> Windows machine, running that check is the single most useful thing you can do
 > right now. `U盘实测清单.md` in the workspace root has the exact commands.
-## 提 Issue 的好习惯
+## Tests
 ### 报 bug
 **至少包含这四样**：
 1. 操作系统 + 版本（如 macOS 14.5 / Windows 11 23H2）
 2. 使用的形态（portable / install / bootable / u-claw-app）
 3. **完整的错误日志**（贴文字，不要只截图）
 4. 你试过哪些步骤
 不写复现步骤的 issue，维护者通常没办法处理。
 ### 提需求
 - 先说**使用场景**，再说功能。
 - "我希望能 X" → 不够。"我在做 Y，需要 X，因为 Z" → 才能讨论。
 ## 提 PR 的好习惯
 ### 提交前先想清楚
 1. **改动是不是真的有人需要？** 大改动建议先开 issue 讨论。
 2. **改动会不会破坏其它形态？** 比如改 `portable/` 不要影响 `bootable/`。
 3. **你跑过吗？** PR 模板里要求列出测试方式，不是装饰。
 ### 不要做的事
 - ❌ 提交 `node_modules/`、`app/`、`data/`、`*.dmg`、`*.exe`（已在 `.gitignore`）
 - ❌ 把 API Key、Token、密码写进任何文件
 - ❌ 改 README 加自己的推广链接
 - ❌ 提空白 PR（只有标题没说明）—— 会直接关闭
 - ❌ 大规模格式化无关代码（"顺手 prettier 全仓"这种）
 ### Commit message
 短、说人话、能让维护者一眼看懂改了什么：
 ```
 fix(portable): node-extract path missing intermediate dir
 fix(install.sh): npm wrapper不能用 node 直接执行
 docs: 补充 Windows 11 ARM64 支持说明
 feat(skills): 增加 linkedin-post 技能
 ```
 不接受："update"、"fix"、"修改若干文件" 这种。
 ### 分支与 PR 流程
 ```bash
-# 1. fork → clone 你的 fork
+node --test                     # everything
-git clone https://github.com/<你的用户名>/u-claw.git
+node --test tests/windows-launchers.test.mjs   # one file
 # 2. 创建分支（不要在 main 上直接改）
 git checkout -b fix/install-sh-npm-path
 # 3. 改 → 自己跑过 → 提交
 git add <具体文件>          # 不要 git add .
 git commit -m "fix(install): ..."
 # 4. 推到你的 fork
 git push origin fix/install-sh-npm-path
 # 5. 在 GitHub 上发起 PR，填好模板
 ```
-## 修改各形态时的注意事项
+**Not `node --test tests/`.** Node reads that path as a module to load and dies
 with "Cannot find module" — zero tests run, exit code 1. That form was the
 documented command here for a long time, which is a good part of why the suite
 went unrun for the life of the project.
-### `portable/`
+The suite asserts on the *text and behaviour* of scripts rather than spawning
 OpenClaw: that `.bat` files stay pure ASCII (Chinese Windows `cmd.exe` reads
 non-ASCII as GBK and mis-parses), that `.command` files stay LF-only, that no
 China-routed download source comes back, that both installers resolve skills
 identically, that every UI string exists in every language, and that nothing
 points at a host `origin.json` does not declare.
- **不要在仓库里提交 `app/` 或 `data/`**，那是 `setup.sh` 下载/生成的
+CI runs it where a runner exists (`.gitea/workflows/tests.yml`, mirrored to
- Mac 启动脚本要 `chmod +x`，并清理 quarantine 属性
+`.github/`). On our Gitea there is currently no registered runner, so the
- Windows 启动脚本要正确处理 `cd /d "%DIR%core"`
+pre-push hook is doing the work. Install it.
 - 配置文件放 `data/.openclaw/openclaw.json`，便携属性靠这个
-### `u-claw-app/` (Electron)
+## Filing an issue
- `main.js` 大约 400 行，改前先理解整体流程
+**A bug report needs four things**, or nobody can act on it:
 - Node.js 要找 `resources/runtime/node-{platform}-{arch}`，找不到再 fall back 到系统 node
 - 用户配置在 `app.getPath('userData')/.openclaw/`，不要硬编码路径
-### `bootable/`
+1. OS and version — `macOS 14.5`, `Windows 11 23H2`
 2. Which form — portable / install / bootable
 3. **The full error as text.** Not a screenshot of text.
 4. What you already tried
- 4 步 PowerShell 脚本必须**按顺序**跑
+**A feature request needs a situation, not a feature.** "I'd like X" is not
- ISO 下载走清华/阿里/中科大镜像，不要直接用 ubuntu.com
+enough to discuss. "I'm doing Y, I need X, because Z" is.
 - `bootable/` 与独立仓库 `zhenghy/u-claw-linux` 内容保持同步，改一边记得同步另一边
-### `install/`
+## Sending a change
- Mac/Linux 走 `install.sh`，Windows 走 `install.ps1`
+Before you write it:
 - 全部走 npmmirror.com 镜像，不能假设用户能访问 GitHub/npm 官方
 - 安装目录固定为 `~/.uclaw/`（Mac/Linux）或 `%USERPROFILE%\.uclaw\`（Windows）
 - 启动脚本要找空闲端口（18789-18799），不要写死
-### `skills/`
+- **Does anyone need this?** For anything large, open an issue first.
 - **Does it break another form?** A change in `portable/` should not affect
  `bootable/`.
 - **Did you run it?** Not just the tests — the actual thing.
- 技能格式是 `<skill-name>/SKILL.md`，frontmatter 里有 `name`、`description`、`metadata`
+Do not:
 - 技能内容用中文写，给中国用户看
 - 提交新技能前先看现有技能（小红书/微博/B 站等）的写法
-## 行为准则
+- Commit `node_modules/`, `app/`, `data/`, `*.dmg`, `*.exe` — all in `.gitignore`
 - Put an API key, token or password in any file
 - Reformat unrelated code ("ran prettier over everything" makes review impossible)
 - Open a PR with a title and no description
-简单说：
+Commit messages: say what changed and why, in a sentence someone can act on.
- 对人有礼貌，对事可以严格
+```
- 不要在 issue 里互相攻击
+fix(install.sh): npm wrapper cannot be run through node directly
- 维护者可能回复慢（这是开源副业），请耐心
+feat(skills): add linkedin-post
- 不接受任何形式的歧视、骚扰、钓鱼
+docs: note Windows 11 ARM64 support
 ```
-## 联系
+Not `update`, `fix`, or `changed some files`.
- Issue 区：日常问题、bug、需求
+```bash
- 官网：[u-claw.org](https://u-claw.org)
+git switch -c fix/something      # never work on main
- 邮件（仅紧急安全问题）：见 README
+git add <specific files>         # not git add .
 git push -u origin fix/something
 ```
---
+## Notes per form
-再次感谢！🦞
+**`portable/`**
 - Never commit `app/` or `data/` — `setup.sh` produces them
 - `.command` files need the executable bit and LF endings
 - `.bat` files must be pure ASCII with CRLF, and must not contain an unescaped
  `)` inside an `IF (...)` block — that closes the block early and the window
  flash-exits. There is a test for it, and it has caught real regressions.
 - User config lives in `data/.openclaw/openclaw.json`. That file being on the
  drive is the entire portability story; do not move it.
 - User-facing text belongs in `lib/messages/*.json`, never in a script
 **`bootable/`**
 - The four PowerShell scripts must run **in order**
 - Fully self-contained: it references nothing from `portable/` on purpose
 **`install/`**
 - These run through `curl | bash` with **no checkout**, so they cannot read
  `origin.json` and carry URLs as literals. `tests/origin.test.mjs` fails if
  those literals drift from `origin.json` — that is what stops a host migration
  from half-happening.
 - Neither script may contain skill text. Both call `lib/install-skills.mjs`.
 **`u-claw-app/`** — deprecated 2026-06-19, kept for archive. Do not add to it.
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -1,77 +1,51 @@
-# Handoff Document — U-Claw Linux Remote Access
+# Post-mortem: an unformatted persistence file bricks the boot
-## Current Status
+*2026-03-17. Kept because the failure gives no useful signal about its own
 cause, and it will happen again to whoever builds the next drive.*
- U盘已就绪：Ventoy + Ubuntu 24.04 ISO + persistence + u-claw-linux scripts
+## What happened
 - 所有源码已推送到 GitHub main 分支
 - website/guide.html 已添加快速命令参考卡片
 - enable-ssh.sh 已添加到 bootable/linux-setup/
-## Linux 启动后需要做的事
+A freshly built bootable USB dropped straight into an initramfs prompt instead
 of booting Ubuntu. Nothing on screen pointed at the real problem.
-1. 从 U 盘启动 → Ventoy 菜单选 Ubuntu
+`persistence.dat` on the drive was a 20 GB **empty** file with no ext4
-2. 如果首次使用，格式化持久化：
+filesystem in it. `3-create-persistence.ps1` had found no standard WSL, taken
-   ```
+its fallback path, and produced a sparse file it never formatted. Ventoy read
-   sudo bash /media/*/Ventoy/u-claw-linux/format-persistence.sh
+`ventoy.json`, tried to mount that file, failed, and the boot collapsed into
-   ```
+initramfs.
   然后重启
 3. 连接 WiFi
 4. 安装 OpenClaw：
   ```
   sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
   ```
 5. 启用 SSH（让 Mac mini 远程控制）：
   ```
   sudo bash /media/*/Ventoy/u-claw-linux/enable-ssh.sh
   ```
-## SSH 连接信息
+The chain is silent at every step: the build script reports success, Ventoy
 reports nothing, and initramfs says only that it has no root.
- **用户名**: ubuntu (Live USB 默认用户)
+## The fix at the time
 - **密码**: 运行 enable-ssh.sh 时设置
 - **IP 地址**: 运行 enable-ssh.sh 后会显示，格式类似 192.168.x.x
 - **前提**: 两台机器在同一个 WiFi/局域网下
-## Mac mini Claude Code 接手方法
+Formatted it using docker-desktop's WSL, which has `mkfs.ext4` even though it is
 not a standard WSL distribution:
-1. 用户在 Linux 上运行 `enable-ssh.sh`，获取 IP 和设置密码
+```bash
-2. 用户告诉 Mac mini 上的 Claude Code：IP 地址和密码
+dd if=/dev/zero of=/tmp/persistence.dat bs=1M count=0 seek=20480
-3. Mac mini Claude Code 通过 Bash 工具执行：
+/sbin/mkfs.ext4 -F -L casper-rw /tmp/persistence.dat
-   ```
+```
   ssh ubuntu@<IP> 'command'
   ```
   或建立持久连接进行调试
-## 文件位置（Linux 上）
+Then copied it to `C:` and moved it onto the drive — docker-desktop's WSL cannot
 reach other drive letters directly.
-| 路径 | 说明 |
+## How to tell a persistence file is real
 |------|------|
 | `/media/*/Ventoy/u-claw-linux/` | U 盘上的脚本 |
 | `/opt/u-claw/` | 安装后的 OpenClaw |
 | `/opt/u-claw/start-openclaw.sh` | 启动脚本 |
 | `/opt/u-claw/data/.openclaw/openclaw.json` | 配置文件 |
-## 注意事项
+Read two bytes at offset 1080. They should be `53 EF` — the little-endian form
 of the ext4 magic number `0xEF53`. An empty file has zeros there.
- Live USB 每次重启后，除了持久化分区内的数据，其他都会重置
+This is the check worth keeping: it takes a second and distinguishes "built
- SSH server 需要每次重启后重新安装（除非持久化生效）
+correctly" from "built, and will fail at boot on someone else's desk".
 - 持久化生效后，apt 安装的包会保留
-## 2026-03-17 修复：persistence.dat 未格式化导致启动失败
+## What changed in the scripts
-### 问题
+- `3-create-persistence.ps1` now tries docker-desktop's WSL before giving up
- U 盘上的 `persistence.dat`（20GB）是空文件，没有 ext4 文件系统
+- It verifies the ext4 magic number after formatting
- `3-create-persistence.ps1` 因无可用标准 WSL，走了 Method B，只创建了稀疏空文件
+- It only falls back to an unformatted sparse file when there is no WSL at all,
- Ventoy 启动 Ubuntu → 读 ventoy.json → 尝试挂载空的 persistence.dat → mount 失败 → 卡在 initramfs
+  and says so loudly — that path requires the user to run `mkfs.ext4` by hand on
  first boot, and then reboot
-### 修复过程
+The user-facing version of this is in
-1. 用 docker-desktop WSL 的 `/sbin/mkfs.ext4` 格式化：
+[`bootable/README.md`](bootable/README.md) and
-   - 在 WSL 内创建稀疏文件：`dd if=/dev/zero of=/tmp/persistence.dat bs=1M count=0 seek=20480`
+[`bootable/TROUBLESHOOTING.md`](bootable/TROUBLESHOOTING.md).
   - 格式化：`/sbin/mkfs.ext4 -F -L casper-rw /tmp/persistence.dat`
   - 复制到 C: → 移动到 E:（因为 docker-desktop WSL 无法直接访问 E: 盘）
 2. 验证：offset 1080 处读到 `53 EF`（little-endian `0xEF53`），确认 ext4 有效
 ### 代码改进
 - `3-create-persistence.ps1` Method B 现在会尝试 docker-desktop WSL 格式化
 - 添加了 ext4 magic number 验证步骤
 - 只有在完全没有任何 WSL 时才降级为未格式化的空文件
--- a/README.md
+++ b/README.md
@@ -140,8 +140,7 @@ exFAT. macOS can only read NTFS, not write to it, which would break the whole "y
 ## Contact
- Email — help@u-claw.org
+- Issues — [gitea.fanghe.it.com/zhenghy/u-claw/issues](https://gitea.fanghe.it.com/zhenghy/u-claw/issues)
 - Issues — [GitHub](https://gitea.fanghe.it.com/zhenghy/u-claw/issues)
 - Site — [u-claw.org](https://u-claw.org)
 ---
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,61 +1,71 @@
-# 安全策略 / Security Policy
+# Security policy
-感谢你关注 U-Claw 的安全性。本文档说明如何向我们报告安全漏洞，以及我们当前支持的版本。
+## Reporting a vulnerability
-## 报告漏洞 / Reporting a Vulnerability
+**Please do not put details in a public issue.**
-**请不要在公开 issue 里发布安全漏洞细节。**
+Open a report at
 https://gitea.fanghe.it.com/zhenghy/u-claw/issues — mark it clearly as a
 security report and keep the details minimal until we can arrange a private
 channel.
-如果你发现了 U-Claw 的安全问题，请通过以下任一渠道私下联系：
+> **This is a fork.** Upstream is `github.com/dongsheng123132/u-claw`. If the
 > issue is in code we inherited unchanged, it affects their users too — please
 > tell them as well. If it is in something this fork changed (the launcher, the
 > i18n layer, the skill installer, the key-check endpoint, the self-heal
 > routines), it is ours.
 >
 > We do not yet have a dedicated security address of our own. `origin.json`
 > records that gap; until it is filled, the issue tracker is the route.
- 邮件：`hefangsheng@u-claw.org`（建议附 PoC、影响范围、复现步骤）
+We will acknowledge within **3 working days** and give a first assessment within
- GitHub 私密漏洞报告：在 [u-claw 仓库](https://gitea.fanghe.it.com/zhenghy/u-claw) 的 Security 标签页 → "Report a vulnerability"
+**14 days**. Please give us a chance to fix it before disclosing publicly.
-我们会在 **3 个工作日内** 确认收到，并在 **14 天内** 给出初步评估。请允许我们在公开披露前修复问题。
+### What helps
-### 报告内容建议
+- Which module — `portable/`, `install/`, `bootable/`
 - Version or commit hash
 - How it is triggered, and from where: local, LAN, or the internet
 - Steps to reproduce, or a proof of concept
 - What you think the fix looks like, if you have a view
- 受影响的模块（portable / install / bootable / u-claw-app）
+## What is in scope
 - 受影响的版本或 commit hash
 - 触发条件、攻击面（本地 / 局域网 / 互联网）
 - 复现步骤或 PoC 代码
 - 你建议的缓解或修复方向
-## 支持的版本 / Supported Versions
+- Command injection, path traversal, arbitrary write or code execution in
  U-Claw's own scripts
 - Injection through the loading or writing of `data/.openclaw/openclaw.json`
 - Launchers (`START HERE - *`, `lib/start.mjs`) being hijacked through a
  malicious directory name or environment variable
 - Man-in-the-middle exposure on the one-line install path
  (`curl | bash`, `irm | iex`)
 - Privilege escalation in what the bootable USB scripts produce
 - The key-check endpoint (`/api/test-key`) — it handles API keys server-side
 - The diagnostics report leaking a secret it should have redacted
-| 模块 | 版本 | 状态 |
+## What is not
 |------|------|------|
 | `portable/` | 当前 main | ✅ 接受报告 |
 | `install/` (`install.sh` / `install.ps1`) | 当前 main | ✅ 接受报告 |
 | `bootable/` (Linux U 盘) | 当前 main | ✅ 接受报告 |
 | `u-claw-app/` Electron | 当前 main | ✅ 接受报告 |
 | 历史 release tag | — | ⚠️ 仅做严重等级评估，不一定回滚补丁 |
-我们暂未发布稳定版本号，所有修复直接在 main 分支推送。
+- **Upstream dependencies** — Node.js, OpenClaw, Electron, Ventoy, Ubuntu.
  Report those to their projects; we track and upgrade versions.
 - **A user publishing their own API key** in a screenshot or a public repo.
 - **Physical access to the drive.** If someone has the drive, they have the
  data — that is the trade a portable product makes, and it is stated plainly
  in the README rather than defended against.
 - **What an attacker can do once they already have admin or root** on the
  machine.
-## 范围 / In-Scope vs Out-of-Scope
+## Supported
-### 在范围内（请报告）
+| Module | Status |
 |---|---|
 | `portable/` | current `main` — reports accepted |
 | `install/` | current `main` — reports accepted |
 | `bootable/` | current `main` — reports accepted |
 | `u-claw-app/` | **deprecated 2026-06-19**, no longer built or published |
 | older tags | severity assessed, but no backported patches |
- U-Claw 自身脚本中的命令注入、路径穿越、任意写入、代码执行
+There are no stable version numbers yet; fixes go straight to `main`.
 - `data/.openclaw/openclaw.json` 配置加载/写入逻辑中的注入
 - 启动脚本（`Mac-Start.command` / `Windows-Start.bat` / `start.sh`）
  在恶意目录名/环境变量下被劫持的可能
 - 一键安装 (`curl | bash` / `irm | iex`) 链路上的 MITM 风险
 - Bootable USB 制作脚本生成的产物在 Linux Live 环境下的提权问题
-### 不在范围内
+## Credit
- 上游依赖（Node.js / OpenClaw / Electron / Ventoy / Ubuntu）的漏洞 —
+Anyone who reports responsibly is credited in the fixing commit and the release
-  请直接报给上游项目；我们只跟踪并升级版本。
+notes, unless you would rather not be.
 - 用户主动把自己的 API Key 写到公开仓库 / 截图泄露，不属于本项目缺陷。
 - 物理接触 USB 后的所有攻击（含偷换 USB、键盘记录等），属于硬件安全场景。
 - 在用户已经获得 admin/root 权限的情况下能做的进一步动作。
 ## 致谢 / Acknowledgements
 发现并负责任披露安全问题的研究者，将在修复发布的 commit message 和 release notes 中署名感谢（除非你要求匿名）。
 ---
 > 本策略借鉴了 GitHub 推荐的开源安全披露格式，未来会随项目成熟度更新。
--- a/bootable/IMPROVEMENTS_SUMMARY.md
+++ b/bootable/IMPROVEMENTS_SUMMARY.md
@@ -1,3 +1,18 @@
 > **Historical, upstream, and left in Chinese on purpose.**
 >
 > This is a record of improvements the upstream project made to the bootable
 > module before we forked. Nothing references it, and it describes work already
 > done rather than how anything currently behaves — translating it would imply
 > it is current documentation, which it is not.
 >
 > For how the bootable USB actually works now, see
 > [README.md](README.md) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 > The one lesson from here that still matters — an unformatted `persistence.dat`
 > silently bricking the boot — is carried forward in both, and in
 > [`../HANDOFF.md`](../HANDOFF.md).
 ---
 # U-Claw Linux Bootable USB 改进总结
 ## 改进概述
--- a/bootable/README.md
+++ b/bootable/README.md
@@ -1,235 +1,184 @@
-# U-Claw Bootable USB (Linux)
+# Bootable Linux USB
-> **把任意电脑变成 AI 工作站 — 插上 U 盘，开机即用**
+> Turn any computer into an AI workstation — boot from the drive, no operating
->
+> system required on the machine itself.
 > **Turn any computer into an AI workstation — just boot from USB**
-## 独立性说明
+## How this differs from the portable build
-本目录 (`bootable/`) 在 u-claw 主仓库中保持**目录级别的独立**：
+The portable build (`portable/`) needs the computer to already run Windows or
 macOS. This one does not need the machine to have an operating system at all:
 it boots Ubuntu off the drive and runs U-Claw inside it.
- 不依赖仓库内 `portable/`、`u-claw-app/`、`website/` 中的任何文件
+That makes it the answer for a machine that is locked down, wiped, or running
- 所有脚本内部硬编码了 URL 和路径，完全自包含
+something you cannot install onto.
 - 出问题只影响 `bootable/` 自身，不会波及其他模块
 - 同时维护了一份**独立仓库**：[u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux)，内容一致
-## 这是什么
+## Self-contained on purpose
-制作一个**可启动的 Linux AI U 盘**：
+This directory does not reference `portable/`, `u-claw-app/` or anything else in
 the repository. Every script hardcodes its own URLs and paths. A change here
 cannot break another module, and a change elsewhere cannot break this.
- 插上任意电脑，从 U 盘启动，直接进入 Ubuntu 桌面
+There is also a standalone mirror at
- 一键安装 OpenClaw AI 助手，桌面图标双击即用
+[u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux) with the same
- 内置持久化存储，安装的软件和数据重启后保留
+contents, for cloning it on its own.
 - **不需要目标电脑有任何操作系统**
-> 与便携版（`portable/`）的区别：便携版需要电脑已有 Windows/Mac 系统，可启动版连系统都不需要。
+## What ends up on the drive
 ## 技术方案
 ```
-┌────────────────────────────────────────────┐
+Ventoy boot area (hidden partition)
-│                U 盘结构                      │
+  BIOS + UEFI dual-mode boot, Ventoy 1.0.99
-│                                            │
+
-│  Ventoy 引导区（隐藏分区）                   │
+Ventoy data partition (visible)
-│    - BIOS + UEFI 双模式启动                  │
+  ubuntu-24.04.4-desktop-amd64.iso   5.8 GB
-│    - 开源引导管理器 v1.0.99                  │
+  persistence.dat                    20 GB
-│                                            │
+  ventoy/ventoy.json                 config
-│  Ventoy 数据分区（可见）                     │
+  u-claw-linux/
-│    ubuntu-24.04.4-desktop-amd64.iso  5.8GB │
+    ├── setup-openclaw.sh
-│    persistence.dat                   20GB  │
+    └── start-openclaw.sh
 │    ventoy/ventoy.json                配置   │
 │    u-claw-linux/                     脚本   │
 │      ├── setup-openclaw.sh                 │
 │      └── start-openclaw.sh                 │
 └────────────────────────────────────────────┘
 ```
-**三个核心技术选型：**
+| Choice | Why |
 |---|---|
 | **Ventoy 1.0.99** | Drop an ISO in and it boots — no burning, and several systems can share the drive |
 | **Ubuntu 24.04 LTS** | Long-term support, the widest hardware driver coverage |
 | **casper-rw persistence** | Lets a live USB keep data across reboots |
-| 技术 | 为什么选它 |
+## What you need
 |------|-----------|
 | **Ventoy 1.0.99** | ISO 文件直接丢进去就能启动，不用烧录，可放多个系统 |
 | **Ubuntu 24.04 LTS** | 长期支持版，驱动兼容性最好，社区最大 |
 | **casper-rw 持久化** | 让 Live USB 也能保存数据，重启不丢失 |
-## 硬件要求
+| | |
 |---|---|
 | USB drive | **32 GB or larger.** USB 3.0 strongly recommended — on 2.0 everything is painful |
 | Build machine | Windows 10/11, PowerShell 5.1+ |
 | Target machine | x86_64 (Intel or AMD), any brand |
 | Network | Needed once, when installing OpenClaw |
-| 项目 | 要求 |
+## Building it — four steps
 |------|------|
 | U 盘 | **32GB+**，强烈推荐 USB 3.0（蓝色接口） |
 | 制作环境 | Windows 10/11，PowerShell 5.1+ |
 | 目标电脑 | x86_64（Intel / AMD），任意品牌 |
 | 网络 | 首次安装 OpenClaw 时需要联网 |
-## 快速制作（4 步）
+Open PowerShell **as Administrator** on Windows:
 在 Windows 上以**管理员身份**打开 PowerShell：
 ```powershell
 cd path\to\u-claw\bootable
-# Step 1: 下载 Ventoy 并写入 U 盘（会格式化！）
+.\1-prepare-usb.ps1          # Write Ventoy to the drive — THIS FORMATS IT
-.\1-prepare-usb.ps1
+.\2-download-iso.ps1         # Download Ubuntu 24.04 (~5.8 GB)
-
+.\3-create-persistence.ps1   # Create the persistence image (20 GB default)
-# Step 2: 下载 Ubuntu 24.04 ISO（~5.8GB，国内镜像）
+.\4-copy-to-usb.ps1          # Copy everything onto the drive
 .\2-download-iso.ps1
 # Step 3: 创建持久化镜像（默认 20GB）
 .\3-create-persistence.ps1
 # Step 4: 拷贝所有文件到 U 盘
 .\4-copy-to-usb.ps1
 ```
-## 自动脚本失败时的手动兜底流程
+### What each step does
-> 由 @wzf9 在 issue #28 反馈整理，适合 Ventoy/ISO 自动下载失败、网络不稳定或需要离线制作的场景。
+**1 · Write Ventoy** — lists your USB devices for confirmation, downloads Ventoy,
 then hands you its GUI to pick the drive and click Install.
 **This erases the drive. Back it up first.**
-1. **Ventoy 下载或安装失败**
+**2 · Download Ubuntu** — fetches the 24.04.4 desktop ISO from
-   - 手动下载 Ventoy Windows 版：https://github.com/ventoy/Ventoy/releases
+`releases.ubuntu.com`, verifies its SHA256, and caches it so a retry does not
-   - 解压后运行 `Ventoy2Disk.exe`
+re-download 5.8 GB.
   - 选择目标 U 盘并点击 Install
   - 注意：这一步会格式化 U 盘，先备份数据
-2. **Ubuntu ISO 自动下载失败**
+**3 · Create persistence** — the step that actually decides whether this works.
-   - 手动下载 Ubuntu 24.04.4 Desktop ISO：
+
-     https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso
+- **With WSL installed** → creates a properly formatted ext4 image directly
-   - 手动下载 SHA256SUMS：
+- **With only docker-desktop's WSL** → falls back to `/sbin/mkfs.ext4`
-     https://releases.ubuntu.com/24.04/SHA256SUMS
+- **With no WSL at all** → creates an empty sparse file that **you must format
-   - 将 ISO 放到 `bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso`
+  by hand** on first boot (see below)
-   - 可用 PowerShell 校验哈希：
+
 The volume label must be `casper-rw` — that is the name Ubuntu looks for.
 **4 · Copy to the drive** — finds the Ventoy drive by its label, checks free
 space, copies the ISO, `persistence.dat`, `ventoy.json` and the setup scripts.
 ## When the scripts fail
 Reported by @wzf9 in issue #28. Useful when a download fails, the network is
 unreliable, or you are building offline.
 **Ventoy would not download or install**
 Get the Windows build from https://github.com/ventoy/Ventoy/releases, unzip,
 run `Ventoy2Disk.exe`, pick the drive, click Install. It formats the drive.
 **The ISO would not download**
 Fetch it yourself:
 - https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso
 - https://releases.ubuntu.com/24.04/SHA256SUMS
 Put the ISO at `bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso`, then
 check it:
 ```powershell
 (Get-FileHash -Algorithm SHA256 ".\.download-cache\ubuntu-24.04.4-desktop-amd64.iso").Hash -eq "3a4c9877b483ab46d7c3fbe165a0db275e1ae3cfe56a5657e5a47c2f99a99d1e"
 ```
-3. **继续创建持久化文件**
+**The persistence file is empty (no WSL)**
-```powershell
+Boot into Ubuntu once, then:
 .\3-create-persistence.ps1
 ```
 如果脚本提示没有 WSL 或只能创建空文件，首次进入 Ubuntu 后需要手动格式化：
 ```bash
 sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
 ```
-格式化完成后重启，持久化才会生效。
+**Reboot after formatting** — persistence does not take effect until you do.
-4. **拷贝到 U 盘**
+**The copy step failed**
   - 优先运行：
-```powershell
+Put these on the Ventoy data partition by hand:
 .\4-copy-to-usb.ps1
 ```
-   - 如果自动拷贝失败，也可以手动放到 Ventoy 数据分区根目录：
+| From | To (drive root) |
-
+|---|---|
 | 本地路径 | U 盘目标 |
 |---------|----------|
 | `bootable\linux-setup\` | `u-claw-linux\` |
 | `bootable\ventoy\` | `ventoy\` |
 | `bootable\.download-cache\persistence.dat` | `persistence.dat` |
-| `bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso` | `ubuntu-24.04.4-desktop-amd64.iso` |
+| `bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso` | (same name) |
-5. **目标电脑启动**
+## Using it
-   - 从 U 盘启动，Ventoy 菜单选择 Ubuntu
+
-   - 如遇 Secure Boot 拦截，进 BIOS 关闭 Secure Boot
+### First time
-   - 进入 Ubuntu 桌面后运行：
+
 1. Plug the drive into the target machine
 2. Power on and press the boot-menu key:
 | Brand | Key |
 |---|---|
 | Dell | F12 |
 | Lenovo | F12 |
 | HP | F9 |
 | ASUS | F2 or DEL |
 | Acer | F12 |
 | MSI | F11 |
 | Others | F12 or F2 usually; check the splash screen |
 3. Choose the USB device, then Ubuntu from the Ventoy menu
 4. Wait for the desktop — one to three minutes off a USB drive is normal
 5. Connect to Wi-Fi
 6. Open a terminal (`Ctrl+Alt+T`) and run:
 ```bash
 sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
 ```
-## 每一步做了什么
+7. A **U-Claw AI Assistant** icon appears on the desktop
 8. Double-click it, then paste an API key in the browser
-### Step 1: 写入 Ventoy 引导 (`1-prepare-usb.ps1`)
+### After that
- 列出所有 USB 设备，让你确认
+Plug in, boot, double-click the icon. Everything you set up is still there.
 - 从 GitHub 下载 Ventoy 1.0.99
 - 启动 Ventoy2Disk.exe GUI
 - 你在 GUI 中选择 U 盘 → 点 Install
 - **注意：会格式化 U 盘，数据全丢！提前备份！**
-### Step 2: 下载 Ubuntu ISO (`2-download-iso.ps1`)
+## What `setup-openclaw.sh` does
- 从国内镜像下载 Ubuntu 24.04.4 桌面版（~5.8GB）
+| Step | |
- 镜像优先级：清华 → 阿里 → 中科大 → 官方
+|---|---|
- SHA256 校验确保文件完整
+| 1 | Check it is running as root — it needs `sudo` |
- 有缓存，不会重复下载
+| 2 | Install `curl` and `xdg-utils` |
 | 3 | Create `/opt/u-claw/{runtime,core,data}` |
 | 4 | Download Node.js from `nodejs.org` |
 | 5 | Write `package.json` |
 | 6 | Install OpenClaw and the QQ plugin from `registry.npmjs.org` |
 | 7 | Write the default config — gateway and token |
 | 8 | Install the start script into `/opt/u-claw/` |
 | 9 | Create the desktop shortcut, optionally starting on login |
-### Step 3: 创建持久化镜像 (`3-create-persistence.ps1`)
+## Configuration
 这是整个方案**最关键**的一步：
 - 检测是否安装了 WSL（Windows 子系统 Linux）
 - **有 WSL** → 用 `mkfs.ext4` 直接创建格式化好的 ext4 镜像
 - **没 WSL** → 创建稀疏文件，首次进 Linux 后需手动格式化
 - 卷标必须是 `casper-rw`（Ubuntu 持久化的约定）
 - 默认 20GB，可选 1-28GB
 ### Step 4: 拷贝到 U 盘 (`4-copy-to-usb.ps1`)
 - 自动识别 Ventoy U 盘（通过卷标）
 - 检查剩余空间
 - 拷贝 4 样东西：ISO、persistence.dat、ventoy.json、安装脚本
 ## 使用方法
 ### 首次使用
 1. 将 U 盘插入目标电脑
 2. 开机按启动键：
 | 品牌 | 启动键 |
 |------|--------|
 | Dell 戴尔 | F12 |
 | Lenovo 联想 | F12 |
 | HP 惠普 | F9 |
 | ASUS 华硕 | F2 或 DEL |
 | Acer 宏碁 | F12 |
 | MSI 微星 | F11 |
 | Huawei 华为 | F12 |
 | Xiaomi 小米 | F12 |
 3. 启动菜单选择 USB 设备
 4. Ventoy 菜单 → 选择 Ubuntu
 5. 等待 Ubuntu 桌面加载
 6. 连接 Wi-Fi
 7. 打开终端（`Ctrl+Alt+T` 或右键桌面 → Open Terminal）
 8. 运行安装命令：
 ```bash
 sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
 ```
 9. 桌面出现 **"U-Claw AI Assistant"** 图标
 10. 双击图标 → 浏览器打开 → 配置 AI 模型
 ### 日常使用
 1. 插入 U 盘 → 开机选 USB → Ubuntu 桌面
 2. 双击桌面图标
 3. 所有数据自动保留
 ## 安装脚本详解 (`setup-openclaw.sh`)
 9 个步骤，完全自包含：
 | 步骤 | 操作 | 说明 |
 |------|------|------|
 | 1 | 检查 root 权限 | 必须 `sudo` 运行 |
 | 2 | 安装系统依赖 | `curl`, `xdg-utils` |
 | 3 | 创建目录 | `/opt/u-claw/{runtime,core,data}` |
 | 4 | 下载 Node.js v22 | 国内镜像优先，官方回退 |
 | 5 | 创建 package.json | — |
 | 6 | 安装 OpenClaw + QQ 插件 | npm 国内镜像 |
 | 7 | 写默认配置 | gateway + token |
 | 8 | 安装启动脚本 | → `/opt/u-claw/` |
 | 9 | 创建桌面快捷方式 | 可选开机自启 |
 ## 核心配置文件
 ### `ventoy/ventoy.json`
@@ -245,126 +194,71 @@ sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
 }
 ```
-告诉 Ventoy：启动 Ubuntu ISO 时自动加载 `persistence.dat`。`autosel: 1` = 不弹确认框。
+Tells Ventoy to attach `persistence.dat` when booting that ISO. `autosel: 1`
 skips the confirmation prompt.
-### Linux 端环境变量
+### Environment on Linux
-| 变量 | 值 |
+| Variable | Value |
-|------|-----|
+|---|---|
 | `OPENCLAW_HOME` | `/opt/u-claw/data/.openclaw` |
 | `OPENCLAW_STATE_DIR` | `/opt/u-claw/data/.openclaw` |
 | `OPENCLAW_CONFIG_PATH` | `/opt/u-claw/data/.openclaw/openclaw.json` |
-## 文件结构
+## Files
 ```
 bootable/
-├── README.md                      本文件
+├── README.md                    this file
-├── 1-prepare-usb.ps1              Step 1: Ventoy 写入
+├── 1-prepare-usb.ps1            write Ventoy
-├── 2-download-iso.ps1             Step 2: Ubuntu ISO 下载
+├── 2-download-iso.ps1           download Ubuntu
-├── 3-create-persistence.ps1       Step 3: 持久化镜像
+├── 3-create-persistence.ps1     create the persistence image
-├── 4-copy-to-usb.ps1              Step 4: 拷贝到 U 盘
+├── 4-copy-to-usb.ps1            copy onto the drive
 ├── linux-setup/
-│   ├── format-persistence.sh      格式化持久化镜像
+│   ├── format-persistence.sh    format the persistence image
-│   ├── setup-openclaw.sh          一键安装 OpenClaw
+│   ├── setup-openclaw.sh        install OpenClaw
-│   ├── start-openclaw.sh          启动脚本
+│   ├── start-openclaw.sh        launcher
-│   └── openclaw.desktop           桌面快捷方式
+│   └── openclaw.desktop         desktop shortcut
 └── ventoy/
-    └── ventoy.json                Ventoy 持久化配置
+    └── ventoy.json              persistence config
 ```
-## 实践经验与注意事项
+## Things learned the hard way
-### 制作阶段
+**An unformatted `persistence.dat` drops Ubuntu into initramfs.** Ventoy cannot
 mount a file with no ext4 filesystem in it, and the boot fails in a way that
 gives no hint about the cause. To check whether a file is actually formatted,
 read two bytes at offset 1080 — they should be `0x53 0xEF`, the little-endian
 form of the ext4 magic number `0xEF53`.
-1. **U 盘选择很重要**
+**Formatting requires a reboot.** Running `mkfs.ext4` and continuing in the same
-   - 必须 32GB+（ISO 5.8GB + 持久化 20GB + 系统开销）
+session looks like it worked and silently does not persist.
   - 强烈建议 USB 3.0，否则启动和运行都会很慢
   - 推荐品牌：闪迪、金士顿、三星（杂牌盘容易出问题）
   - 避免使用 USB Hub，直接插主板接口
-2. **Step 1 会清空 U 盘**
+**Drive quality matters more than you would expect.** Cheap unbranded drives fail
-   - Ventoy 安装会格式化整个 U 盘，**务必提前备份**
+in ways that look like software problems. Use USB 3.0, plug into the board
-   - 脚本会列出所有 USB 设备让你确认，看清楚再操作
+directly rather than through a hub, and prefer 32 GB+ (5.8 GB ISO + 20 GB
 persistence + overhead leaves little room otherwise).
-3. **Step 3 持久化镜像（重要教训）**
+**Sizing**: 20 GB persistence on a 32 GB drive, 40 GB+ on a 64 GB drive.
   - 有标准 WSL（Ubuntu 等）→ 自动创建 ext4 镜像（最省事）
   - 只有 docker-desktop WSL → 脚本会尝试用 `/sbin/mkfs.ext4` 格式化（2026-03-17 修复）
   - 完全没有 WSL → 创建空文件，**必须**首次进 Linux 后手动格式化：
     ```bash
     sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
     ```
     格式化后**必须重启**才能生效
   - **踩坑记录**：空的 persistence.dat（无 ext4 文件系统）会导致 Ventoy 挂载失败，
     Ubuntu 启动直接掉进 initramfs。验证方法：读取文件 offset 1080 处的 2 字节，
     应为 `0x53 0xEF`（ext4 magic number `0xEF53` 的 little-endian 表示）
   - 大小建议：32GB U 盘选 20GB，64GB U 盘可选 40GB+
-4. **ISO 下载失败**
+## Troubleshooting
   - 脚本默认走清华/阿里/中科大国内镜像，无需翻墙
   - 如果全部失败，手动下载 Ubuntu ISO 放到 `.download-cache/` 目录即可
-### 启动阶段
+| Problem | Fix |
 |---|---|
 | Will not boot from USB | In BIOS: disable Secure Boot, enable USB boot. Try both UEFI and Legacy/CSM |
 | No Ubuntu in the Ventoy menu | The ISO must be in the root of the Ventoy data partition |
 | Boot stops at initramfs | `persistence.dat` is not formatted. `mkfs.ext4 -F -L casper-rw`, then reboot |
 | Data lost on reboot | Same cause — check the file is ext4 and the label is exactly `casper-rw` |
 | No USB boot entry at all | Try another port; some machines disable USB boot in BIOS by default |
 | Desktop takes ages to load | Normal off a USB drive. USB 3.0 on a USB 3.0 port helps a lot |
 | OpenClaw install fails | Check the network — it needs `nodejs.org` and `registry.npmjs.org` |
 | Wi-Fi does not work | Ubuntu 24.04 covers most chipsets; otherwise tether over USB from a phone |
 | Browser does not open | Go to `http://localhost:18789` yourself |
 | Port already in use | OpenClaw uses 18789–18799. Close the terminal window and open it again |
 | Wrong screen resolution | Settings → Displays |
-5. **Secure Boot 问题**
+**Performance**: running off a USB drive is slower than a disk — that is
-   - 部分电脑需要关闭 Secure Boot 才能从 U 盘启动
+physics, not a bug. Inference happens at your model provider, so conversation
-   - 进 BIOS → Security → Secure Boot → Disabled
+speed is unaffected; only startup and file operations are slower.
   - 不同品牌进 BIOS 的方式不同（通常 DEL 或 F2）
-6. **找不到 USB 启动项**
+For anything not covered here, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
   - 换个 USB 口试试
   - 有些电脑默认禁用了 USB 启动，需要在 BIOS 中开启
   - Legacy/CSM 模式和 UEFI 模式都试试
 7. **Ubuntu 桌面加载慢**
   - 正常现象，Live USB 从 U 盘读取比硬盘慢
   - USB 3.0 U 盘 + USB 3.0 接口会快很多
   - 首次加载约 1-3 分钟
 ### 使用阶段
 8. **Wi-Fi 连接**
   - Ubuntu 24.04 支持大多数 Wi-Fi 芯片
   - 不行的话用手机 USB 共享网络，或 USB 无线网卡
 9. **OpenClaw 安装需要网络**
   - 国内镜像优先，无需翻墙
   - 安装过程约 1-2 分钟
 10. **端口冲突**
    - OpenClaw 使用端口 18789-18799
    - 提示端口占用 → 关闭终端窗口再重新打开
 11. **数据位置**
    - 安装目录：`/opt/u-claw/`
    - 配置文件：`/opt/u-claw/data/.openclaw/openclaw.json`
    - 所有数据保存在持久化镜像中，重启不丢
 12. **性能预期**
    - U 盘运行比硬盘慢，这是物理限制
    - AI 推理在云端，本地只跑网关，对话速度不受影响
 ## 常见故障排查
 | 问题 | 解决方案 |
 |------|---------|
 | 无法从 U 盘启动 | BIOS 关闭 Secure Boot，开启 USB Boot |
 | Ventoy 菜单无 Ubuntu | ISO 文件是否在 Ventoy 数据分区根目录 |
 | 启动卡在 initramfs | persistence.dat 未格式化为 ext4，用 `mkfs.ext4 -F -L casper-rw` 格式化后重启 |
 | 持久化不生效（重启丢数据） | persistence.dat 是否已格式化为 ext4，卷标是否为 `casper-rw` |
 | OpenClaw 安装失败 | 检查网络，确认能访问 npmmirror.com |
 | 浏览器打不开 | 手动打开浏览器访问 `http://localhost:18789` |
 | 屏幕分辨率不对 | Settings → Displays → Resolution |
 ## 技术说明
 - **Ventoy**: 开源引导管理器，ISO/WIM/VHD 直接启动，更新 ISO 不用重新格式化
 - **Persistence**: Ventoy persistence 插件 + `casper-rw` 标签 ext4 镜像
 - **Node.js**: v22.14.0 LTS，npmmirror.com（国内）或 nodejs.org
 - **OpenClaw**: npm latest，安装到 `/opt/u-claw/`
 - **完全独立**: 不引用仓库内 `portable/`、`u-claw-app/`、`website/` 的任何文件
 ## 详细故障排除
 遇到问题请参考详细故障排除指南：
 - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - 完整的问题排查步骤和解决方案
--- a/bootable/TROUBLESHOOTING.md
+++ b/bootable/TROUBLESHOOTING.md
@@ -1,224 +1,206 @@
-# U-Claw Bootable USB 故障排除指南
+# Troubleshooting the bootable USB
-## 常见问题与解决方案
+## While building the drive
-### 1. Ventoy安装失败
+### Ventoy will not install
-**问题**: Ventoy安装时提示"Access Denied"或无法写入U盘
+*"Access Denied", or it cannot write to the drive.*
 **解决方案**:
 1. 以管理员身份运行PowerShell
 2. 关闭所有可能占用U盘的程序（文件资源管理器、杀毒软件等）
 3. 尝试使用Ventoy的"只读模式"安装
 4. 如果U盘有写保护开关，请关闭它
-### 2. Ubuntu ISO下载缓慢或失败
+1. Run PowerShell **as Administrator**
 2. Close anything holding the drive open — File Explorer, antivirus, backup tools
 3. Try Ventoy's read-only install mode
 4. Check for a physical write-protect switch on the drive
-**问题**: 下载Ubuntu ISO时速度慢或中断
+### The ISO download is slow or fails
 **解决方案**:
 1. 脚本会自动尝试多个国内镜像（清华、阿里、中科大）
 2. 如果全部失败，可以手动下载：
   - 访问 https://mirrors.tuna.tsinghua.edu.cn/ubuntu-releases/24.04/
   - 下载 `ubuntu-24.04.4-desktop-amd64.iso`
   - 放到 `bootable/.download-cache/` 目录
 3. 重新运行 `2-download-iso.ps1`
-### 3. 持久化存储创建失败
+The script pulls from `releases.ubuntu.com` and verifies the SHA256. If it keeps
 failing, download it yourself:
-**问题**: `3-create-persistence.ps1` 提示磁盘空间不足
+- https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso
 **解决方案**:
 1. 确保U盘至少有32GB空间
 2. 默认持久化大小为20GB，可以修改脚本中的 `$PersistenceSizeGB` 变量
 3. 最小建议值：8GB
-### 4. Linux启动后无法进入桌面
+Put it in `bootable/.download-cache/` and run `2-download-iso.ps1` again — it
 finds the cached file and verifies it rather than downloading again.
-**问题**: 从U盘启动后黑屏或卡住
+### Not enough space for the persistence image
 **解决方案**:
 1. 启动时按 `F6` 或 `Esc` 进入引导选项
 2. 添加内核参数：
   - `nomodeset` - 禁用显卡驱动
   - `quiet splash` - 禁用启动画面
 3. 如果使用NVIDIA显卡，尝试 `nouveau.modeset=0`
-### 5. OpenClaw安装失败
+`3-create-persistence.ps1` needs room for a 20 GB file alongside a 5.8 GB ISO.
-**问题**: `setup-openclaw.sh` 执行失败
+- A 32 GB drive is the practical minimum
-**解决方案**:
+- Change `$PersistenceSizeGB` in the script to use less
-1. **网络问题**:
+- Below about 8 GB there is not enough room to install anything meaningful
   ```bash
   # 测试网络连接
   ping -c 3 npmmirror.com
-   # 如果网络有问题，使用代理
+## While booting
   export http_proxy=http://your-proxy:port
   export https_proxy=http://your-proxy:port
   ```
-2. **权限问题**:
+### Black screen, or it hangs before the desktop
   ```bash
   # 确保以root运行
   sudo bash setup-openclaw.sh
   ```
-3. **依赖问题**:
+Press `F6` or `Esc` at the boot menu to add kernel parameters:
   ```bash
   # 手动安装依赖
   sudo apt-get update
   sudo apt-get install curl xdg-utils
   ```
-### 6. OpenClaw无法启动
+| Parameter | What it does |
 |---|---|
 | `nomodeset` | Skips the graphics driver — the usual fix |
 | `nouveau.modeset=0` | For NVIDIA cards specifically |
 | `quiet splash` | Removes the splash screen so you can see where it stops |
-**问题**: `start-openclaw.sh` 启动失败
+### It drops into an initramfs prompt
 **解决方案**:
 1. **检查Node.js**:
   ```bash
   /opt/u-claw/runtime/node-linux-x64/bin/node --version
   # 应该显示 v22.14.0
   ```
-2. **检查OpenClaw安装**:
+`persistence.dat` has no ext4 filesystem in it. This is the single most common
-   ```bash
+build failure, and the error message says nothing about the real cause.
   ls -la /opt/u-claw/core/node_modules/openclaw/
   ```
 3. **端口冲突**:
   ```bash
   # 检查端口占用
   ss -tlnp | grep :18789
   # 如果端口被占用，手动指定端口
   cd /opt/u-claw/core
   node node_modules/openclaw/openclaw.mjs gateway run --port 18800
   ```
 ### 7. 浏览器无法打开
 **问题**: 启动后浏览器没有自动打开
 **解决方案**:
 1. **手动打开浏览器**:
   - 访问 http://localhost:18789
   - 或 http://127.0.0.1:18789
 2. **检查防火墙**:
   ```bash
   # Ubuntu Live通常没有防火墙，但可以检查
   sudo ufw status
   ```
 ### 8. 持久化数据丢失
 **问题**: 重启后安装的软件或数据丢失
 **解决方案**:
 1. 确保启动时选择了"Ubuntu (persistence)"选项
 2. 检查持久化文件大小:
   ```bash
   ls -lh /media/ubuntu/persistence.dat
   # 应该显示约20GB
   ```
 3. 如果持久化损坏，重新创建:
   ```bash
   # 在Windows上重新运行 3-create-persistence.ps1
   ```
 ### 9. 性能问题
 **问题**: 系统运行缓慢
 **解决方案**:
 1. **使用USB 3.0接口**（蓝色接口）
 2. **关闭不必要的特效**:
   ```bash
   # 安装gnome-tweaks调整性能
   sudo apt-get install gnome-tweaks
   ```
 3. **增加swap空间**（仅限持久化模式）:
   ```bash
   sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   ```
 ### 10. 硬件兼容性问题
 **问题**: 某些硬件不工作（WiFi、蓝牙、声卡等）
 **解决方案**:
 1. **更新内核**（仅限持久化模式）:
   ```bash
   sudo apt-get update
   sudo apt-get install linux-generic-hwe-24.04
   ```
 2. **安装额外驱动**:
   ```bash
   # 检查可用驱动
   ubuntu-drivers devices
   # 安装推荐驱动
   sudo ubuntu-drivers autoinstall
   ```
 ## 调试技巧
 ### 查看日志
 ```bash
-# OpenClaw日志
+sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
 ```
 Then **reboot** — formatting does not take effect in the same session.
 To check whether a file is actually formatted, read two bytes at offset 1080;
 they should be `0x53 0xEF`.
 ### No USB entry in the boot menu
 - Try a different port
 - In BIOS: disable Secure Boot, enable USB boot
 - Try both UEFI and Legacy/CSM modes
 ## After booting
 ### The OpenClaw install fails
 **Network** — it needs to reach `nodejs.org` and `registry.npmjs.org`:
 ```bash
 curl -I https://registry.npmjs.org
 curl -I https://nodejs.org/dist
 # behind a corporate proxy
 export http_proxy=http://your-proxy:port
 export https_proxy=http://your-proxy:port
 ```
 **Permissions** — it has to run as root:
 ```bash
 sudo bash setup-openclaw.sh
 ```
 **Missing packages**:
 ```bash
 sudo apt-get update && sudo apt-get install curl xdg-utils
 ```
 ### U-Claw will not start
 Check Node.js is there and is the version we pin:
 ```bash
 /opt/u-claw/runtime/node-linux-x64/bin/node --version
 ```
 Check OpenClaw landed:
 ```bash
 ls -la /opt/u-claw/core/node_modules/openclaw/
 ```
 Check for a port conflict — U-Claw uses 18789 to 18799:
 ```bash
 ss -tlnp | grep :18789
 # start it somewhere else if something else owns the range
 cd /opt/u-claw/core
 node node_modules/openclaw/openclaw.mjs gateway run --port 18800
 ```
 ### The browser does not open by itself
 Go to `http://localhost:18789` yourself. Ubuntu Live normally has no firewall,
 but if you suspect one:
 ```bash
 sudo ufw status
 ```
 ### Data disappears after a reboot
 1. Make sure you picked the persistence entry in the Ventoy menu
 2. Check the file is the size you expect:
 ```bash
 ls -lh /media/*/Ventoy/persistence.dat
 ```
 3. If it is corrupt, re-run `3-create-persistence.ps1` on the Windows machine
 ### Everything is slow
 Some of this is unavoidable — a USB drive is slower than a disk. What helps:
 - **USB 3.0 drive in a USB 3.0 port.** The largest single difference by far.
 - Turn down desktop effects: `sudo apt-get install gnome-tweaks`
 - Add swap, if you are running with persistence:
 ```bash
 sudo fallocate -l 2G /swapfile
 sudo chmod 600 /swapfile
 sudo mkswap /swapfile
 sudo swapon /swapfile
 ```
 Inference happens at your model provider, so conversation speed is not affected
 by any of this — only startup and file operations are.
 ### Wi-Fi, Bluetooth or sound does not work
 With persistence enabled you can install drivers and keep them:
 ```bash
 sudo apt-get update
 sudo apt-get install linux-generic-hwe-24.04    # newer kernel
 ubuntu-drivers devices                          # what is available
 sudo ubuntu-drivers autoinstall                 # install the recommended ones
 ```
 If Wi-Fi still will not come up, tether over USB from a phone — it needs no
 drivers.
 ## Digging deeper
 ```bash
 # U-Claw's own log
 tail -f /opt/u-claw/data/logs/openclaw.log
-# 系统日志
+# kernel and system
 dmesg | tail -20
 journalctl -xe
 ```
-### 测试网络
+# is the network reachable
-```bash
+curl -I https://registry.npmjs.org
 # 测试国内镜像
 curl -I https://registry.npmmirror.com
 curl -I https://npmmirror.com/mirrors/node
-# 测试AI API
+# where the space went
-curl https://api.deepseek.com/health
+df -h /media/*/Ventoy
 ```
 ### 检查磁盘使用
 ```bash
 # 查看U盘使用情况
 df -h /media/ubuntu
 # 查看大文件
 du -sh /opt/u-claw/*
 ```
-## 紧急恢复
+## If it will not boot at all
-如果系统完全无法启动：
+1. **Get your data off first.** Plug the drive into any Windows or Mac machine —
   the Ventoy data partition is readable, so back up anything under
   `u-claw-linux/` before you touch anything else.
 2. **Rebuild.** Format the drive and run the four PowerShell scripts again.
 3. **Ask.** Open an issue at
   https://gitea.fanghe.it.com/zhenghy/u-claw/issues with what you saw on screen
   and which step it failed at.
-1. **从其他电脑访问U盘**:
+## Getting a better result
   - 在Windows/Mac上插入U盘
   - 备份 `u-claw-linux/` 目录下的重要数据
-2. **重新制作U盘**:
+**When building**: use a good USB 3.0 drive, give persistence at least 20 GB,
-   - 格式化U盘
+and turn off real-time antivirus scanning for the build — it slows the ISO write
-   - 重新运行所有4个PowerShell脚本
+enormously and occasionally corrupts it.
-3. **寻求帮助**:
+**On first boot**: run the system updates and install the recommended drivers
-   - GitHub Issues: https://gitea.fanghe.it.com/zhenghy/u-claw/issues
+once, while you have network. With persistence on, you only do it once.
   - 微信: hecare888
-## 性能优化建议
+**Long term**: if you find yourself using it daily on the same machine, a real
-
+dual-boot install will be faster than any USB drive can be.
 1. **制作时**:
   - 使用高质量的USB 3.0 U盘
   - 分配足够的持久化空间（建议20GB+）
   - 关闭杀毒软件实时扫描
 2. **使用时**:
   - 首次启动后运行系统更新
   - 安装推荐驱动
   - 定期清理缓存
 3. **长期使用**:
   - 考虑安装到硬盘（双系统）
   - 定期备份重要数据
   - 关注Ubuntu安全更新
--- a/install/README.md
+++ b/install/README.md
@@ -1,132 +1,102 @@
-# U-Claw 一键安装 / One-Line Install
+# One-line install
-> 一行命令安装 OpenClaw + 技能包 + 模型配置
+Installs OpenClaw, the skills and a model configuration in a single command,
-> One command to install OpenClaw + skills + model config
+without a USB drive.
-## 安装 / Install
+## Install
-### Mac / Linux
+**Mac / Linux**
 ```bash
 curl -fsSL https://u-claw.org/install.sh | bash
 ```
-### Windows (PowerShell 管理员)
+**Windows** (PowerShell)
 ```powershell
 irm https://u-claw.org/install.ps1 | iex
 ```
-### 本地运行
+**From a checkout**
 ```bash
-# Mac/Linux
+bash install/install.sh                                          # Mac / Linux
-bash install/install.sh
+powershell -ExecutionPolicy Bypass -File install\install.ps1     # Windows
 # Windows
 powershell -ExecutionPolicy Bypass -File install\install.ps1
 ```
-## 安装流程
+> These pipe a script from the network straight into a shell. That pattern is
 > widely warned about, and on a managed corporate machine an EDR agent will
 > often block it outright. If you are on a work laptop, use the USB build
 > instead — that is what it is for.
-### Mac / Linux（7 步）
+## What it does
-| 步骤 | 内容 | 说明 |
+| Step | Mac / Linux | Windows |
-|------|------|------|
+|---|---|---|
-| 1 | Node.js v22 | 安装到 `~/.uclaw/runtime/`，系统有 v20+ 则复用 |
+| 1 | Node.js — into `~/.uclaw/runtime/`, or reuses the system copy if it is v20+ | same, under `%USERPROFILE%\.uclaw\` |
-| 2 | OpenClaw | npm 安装到 `~/.uclaw/core/` |
+| 2 | OpenClaw via npm | downloads a pre-built bundle, **checksum verified** |
-| 3 | QQ 插件 | 非致命，失败不影响主功能 |
+| 3 | QQ plugin — optional, a failure here does not stop anything else | same |
-| 4 | 10 个中国技能 | 小红书、B站、微博等内容创作技能 |
+| 4 | Skills — read from `skills/manifest.json`, fetched from the repo | same |
-| 5 | 模型配置 | 中文交互菜单，默认 DeepSeek |
+| 5 | Model — pick one and paste a key | same |
-| 6 | 启动脚本 | 生成 start.command (Mac) / start.sh (Linux) |
+| 6 | Start script — `start.command` / `start.sh` | `start.bat` |
-| 7 | 验证 | 检查各组件安装状态 |
+| 7 | Verify what landed | same |
-### Windows（6 步）
+Neither script contains any skill text of its own. Both call
 `lib/install-skills.mjs`, which is the same installer the USB build and the
 release pipeline use — that is what keeps the two platforms from drifting apart,
 which they had badly done before.
-| 步骤 | 内容 | 说明 |
+## Models
 |------|------|------|
 | 1 | Node.js v22 | 下载到 `%USERPROFILE%\.uclaw\runtime\`，系统有 v20+ 则复用 |
 | 2 | OpenClaw + QQ 插件 | 下载预打包 bundle，走国内镜像 |
 | 3 | 10 个中国技能 | 小红书、B站、微博等内容创作技能 |
 | 4 | 模型配置 | 交互菜单，默认 DeepSeek |
 | 5 | 启动脚本 | 生成 start.bat |
 | 6 | 验证 | 检查各组件安装状态 |
-## 支持的 AI 模型
+The menu leads with what is easiest to get working:
-### 国内（无需翻墙）
+| | Model | Why |
 |---|---|---|
 | 1 | **Gemini** | Easiest key to obtain — Google account, no card, free tier |
 | 2 | **Claude** | Best all-rounder |
 | 3 | **GPT** | Most widely used |
 | 4 | **OpenRouter** | One key across many models |
 | 5 | **SEA-LION** | Malay, Tamil and Singlish. Free, but rate-limited to 10 requests a minute |
 | 6 | **Local** | Runs offline through Ollama |
 | 7 | Other | Paste your own endpoint and model name |
-| 编号 | 模型 | 说明 |
+Others — DeepSeek, Kimi, Qwen, GLM and so on — work fine through option 7.
 |------|------|------|
 | 1 | DeepSeek | ⭐ 推荐，性价比最高 |
 | 2 | Kimi/月之暗面 | 长文档 |
 | 3 | 通义千问 | 有免费额度 |
 | 4 | 智谱GLM | 学术场景 |
 | 5 | MiniMax | 多模态 |
 | 6 | 豆包 | 火山引擎 |
 | 7 | 硅基流动 | 聚合多模型 |
-### 海外
+## Where things land
 | 编号 | 模型 |
 |------|------|
 | 8 | Claude |
 | 9 | GPT |
 ### 本地
 | 编号 | 模型 |
 |------|------|
 | 10 | Ollama |
 ## 安装目录结构
 ```
 ~/.uclaw/
-├── runtime/node-{platform}/     # Node.js v22
+├── runtime/node-{platform}/       Node.js
-├── core/                        # OpenClaw + QQ 插件
+├── core/                          OpenClaw and plugins
-│   ├── package.json
+│   └── node_modules/openclaw/skills/     installed skills
 │   └── node_modules/
 │       └── openclaw/skills/     ← 技能在这里
 ├── data/
-│   ├── .openclaw/openclaw.json  ← 模型配置
+│   ├── .openclaw/openclaw.json    your model and key
-│   ├── memory/                  ← AI 记忆
+│   ├── memory/                    what the AI remembers
-│   └── backups/                 ← 备份
+│   └── backups/
-├── start.command (Mac)          ← 启动脚本
+└── start.command | start.sh | start.bat
 └── start.bat (Windows)          ← 启动脚本
 ```
-## 技术细节
+## Notes
- **Node.js**: 只装到 `~/.uclaw/runtime/`，不动系统 Node；系统已有 v20+ 则复用
+- **Nothing touches your system Node.** It installs into `~/.uclaw/runtime/`, and
- **下载源**: Node 二进制走 `nodejs.org`，npm 包走 `registry.npmjs.org`；Windows bundle 直连 GitHub Releases
+  reuses a system copy only if it is already v20 or newer.
- **Windows 编码**: `chcp 65001` + UTF8 输出确保中文显示
+- **Download sources** are `nodejs.org` and `registry.npmjs.org`; the Windows
- **管道模式**: `curl | bash` 时自动跳过交互，使用默认配置
+  bundle comes from our own releases and its SHA256 is checked before it is
- **卸载**: `rm -rf ~/.uclaw` (Mac/Linux) 或删除 `%USERPROFILE%\.uclaw` (Windows)
+  unpacked. Until recently the only check was "is the file bigger than 1MB",
  which is not a check.
 - **Piped mode**: under `curl | bash` there is no terminal to prompt on, so it
  takes the defaults and you set the model afterwards.
 - **Uninstall**: `rm -rf ~/.uclaw`, or delete `%USERPROFILE%\.uclaw` on Windows.
-## 包含技能
+## How this relates to the other builds
 | 技能 | 用途 |
 |------|------|
 | xiaohongshu-writer | 小红书笔记写作 |
 | bilibili-helper | B站视频优化 |
 | weibo-poster | 微博内容创作 |
 | wechat-article | 微信公众号文章 |
 | zhihu-writer | 知乎回答/文章 |
 | douyin-script | 抖音短视频脚本 |
 | china-search | 国内搜索引擎 |
 | china-translate | 中英互译 |
 | china-weather | 天气查询 |
 | deepseek-helper | DeepSeek API 助手 |
 ## 与其他分发形式的关系
 ```
-install/     ← 一键在线安装（本模块）
+install/     one-line install over the network — this module
-portable/    ← U 盘便携版
+portable/    the USB build, the main product
-u-claw-app/  ← Electron 桌面版
+bootable/    a Linux USB that boots a machine with no OS
-bootable/    ← Linux 可启动 U 盘
+u-claw-app/  Electron desktop app — deprecated, kept for archive
 ```
-install/ 安装的结果与 portable/ 的 Mac-Install.command 相同，
+The result is the same as running `advanced/Mac-Install.command` from the USB
-区别是不需要 U 盘，直接从网络下载所有组件。
+build. The difference is only that everything is fetched from the network rather
 than copied off a drive.
--- a/origin.json
+++ b/origin.json
@@ -31,14 +31,18 @@
    "website": "https://u-claw.org"
  },
  "support": {
-    "help": "help@u-claw.org",
+    "issues": "https://gitea.fanghe.it.com/zhenghy/u-claw/issues",
-    "security": "hefangsheng@u-claw.org",
+    "email": null,
-    "author": "hello@u-claw.org",
+    "note": "We do not own u-claw.org — it is the upstream project's domain, so every @u-claw.org address in this tree reaches them, not us. Until we have our own address, support routes to the issue tracker above, which we do control. Set email here when we have one; tests/origin.test.mjs will find every place that still needs updating."
    "ciBot": "bot@u-claw.org",
    "note": "website, security and author still point at the upstream project. Vulnerability reports currently reach someone who did not write this code and cannot fix it. Replace them once we have our own, and tests/origin.test.mjs will confirm nothing was missed."
  },
  "upstream": {
    "repo": "https://github.com/dongsheng123132/u-claw",
-    "note": "Kept for reference only. We do not send changes back — the overseas fork removes the China-market defaults that are the point of the upstream project."
+    "note": "Kept for reference only. We do not send changes back — the overseas fork removes the China-market defaults that are the point of the upstream project.",
    "addresses": {
      "security": "hefangsheng@u-claw.org",
      "author": "hello@u-claw.org",
      "ciBot": "bot@u-claw.org",
      "note": "Upstream's, left in place where they are factually about upstream."
    }
  }
 }
--- a/portable/advanced/U-Claw.html
+++ b/portable/advanced/U-Claw.html
@@ -152,7 +152,7 @@ body { font-family: -apple-system, "Microsoft YaHei", sans-serif; background: #0
    <div class="grid">
        <div class="grid-item" onclick="window.open('../Read me first.html')" style="cursor:pointer"><h4>📖 <span data-i18n="nav.link_guide">Getting started</span></h4><p data-i18n="nav.link_guide_d">The three-step walkthrough</p></div>
        <div class="grid-item" onclick="window.open('SkillHub.html')" style="cursor:pointer"><h4>🎯 <span data-i18n="nav.link_skills">Skills</span></h4><p data-i18n="nav.link_skills_d">Browse what U-Claw can do</p></div>
-        <div class="grid-item"><h4>💬 <span data-i18n="nav.link_contact">Contact</span></h4><p><a href="mailto:help@u-claw.org" style="color:#ff6b35">help@u-claw.org</a></p></div>
+        <div class="grid-item"><h4>💬 <span data-i18n="nav.link_contact">Contact</span></h4><p><a href="https://gitea.fanghe.it.com/zhenghy/u-claw/issues" target="_blank" rel="noopener" style="color:#ff6b35" data-i18n="nav.link_contact_d">Open an issue</a></p></div>
        <div class="grid-item"><h4>🌐 <span data-i18n="nav.link_site">Website</span></h4><p><a href="https://u-claw.org" target="_blank" rel="noopener" style="color:#ff6b35">u-claw.org</a></p></div>
    </div>
 </div>
--- a/portable/lib/i18n/messages.js
+++ b/portable/lib/i18n/messages.js
@@ -230,7 +230,7 @@ window.UCLAW_I18N_MESSAGES = {
    "start.checking": "Something went wrong — checking…",
    "start.repaired": "Fixed. Trying again.",
    "start.diagnostics_written": "A report of what happened was saved to: {path}",
-    "start.diagnostics_hint": "API keys have been removed from it. Send it to help@u-claw.org if you want a hand.",
+    "start.diagnostics_hint": "API keys have been removed from it. Attach it to an issue at https://gitea.fanghe.it.com/zhenghy/u-claw/issues if you want a hand.",
    "skill.excel-helper.name": "Spreadsheets",
    "skill.excel-helper.desc": "Formulas, pivot tables, charts, cleaning messy data",
    "skill.word-writer.name": "Documents",
@@ -282,7 +282,11 @@ window.UCLAW_I18N_MESSAGES = {
    "hub.lede": "These are on this drive already. Just ask for what you want — you do not have to name the skill.",
    "hub.all": "All",
    "hub.none": "Nothing in this category.",
-    "hub.add_note": "Skills live in the skills/ folder on this drive. Dropping a SKILL.md in there adds one."
+    "hub.add_note": "Skills live in the skills/ folder on this drive. Dropping a SKILL.md in there adds one.",
    "nav.link_contact_d": "Open an issue",
    "skill.uclaw-help.name": "About U-Claw",
    "skill.uclaw-help.desc": "How it works, where things are, what to do when something breaks",
    "cat.uclaw": "U-Claw"
  },
  "zh-CN": {
    "start.banner": "U-Claw · 便携 AI 助手",
@@ -509,7 +513,7 @@ window.UCLAW_I18N_MESSAGES = {
    "start.checking": "出了点问题，正在检查…",
    "start.repaired": "已修复，重试一次。",
    "start.diagnostics_written": "已把情况记录到：{path}",
-    "start.diagnostics_hint": "里面的密钥已被去掉。需要帮忙的话，把它发到 help@u-claw.org。",
+    "start.diagnostics_hint": "里面的密钥已被去掉。需要帮忙的话，把它附到 https://gitea.fanghe.it.com/zhenghy/u-claw/issues 的 issue 里。",
    "skill.excel-helper.name": "表格",
    "skill.excel-helper.desc": "公式、透视表、图表、清洗乱数据",
    "skill.word-writer.name": "文档",
@@ -561,6 +565,10 @@ window.UCLAW_I18N_MESSAGES = {
    "hub.lede": "这些已经在盘上了。直接说你想做什么就行，不用记技能名。",
    "hub.all": "全部",
    "hub.none": "这个分类下暂时没有。",
-    "hub.add_note": "技能放在盘上的 skills/ 目录里。丢一个 SKILL.md 进去就多一个。"
+    "hub.add_note": "技能放在盘上的 skills/ 目录里。丢一个 SKILL.md 进去就多一个。",
    "nav.link_contact_d": "提 issue",
    "skill.uclaw-help.name": "关于 U-Claw",
    "skill.uclaw-help.desc": "它怎么用、东西在哪、出问题了怎么办",
    "cat.uclaw": "U-Claw"
  }
 };
--- a/portable/lib/i18n/skills-data.js
+++ b/portable/lib/i18n/skills-data.js
@@ -48,6 +48,22 @@ window.UCLAW_SKILLS = {
    }
  ],
  "skills": [
    {
      "id": "uclaw-help",
      "categories": [
        "uclaw"
      ],
      "personas": [
        "developer",
        "admin",
        "sales",
        "marketing",
        "finance",
        "boss",
        "general"
      ],
      "emoji": "🦞"
    },
    {
      "id": "excel-helper",
      "categories": [
--- a/portable/lib/messages/en.json
+++ b/portable/lib/messages/en.json
@@ -223,7 +223,7 @@
  "start.checking": "Something went wrong — checking…",
  "start.repaired": "Fixed. Trying again.",
  "start.diagnostics_written": "A report of what happened was saved to: {path}",
-  "start.diagnostics_hint": "API keys have been removed from it. Send it to help@u-claw.org if you want a hand.",
+  "start.diagnostics_hint": "API keys have been removed from it. Attach it to an issue at https://gitea.fanghe.it.com/zhenghy/u-claw/issues if you want a hand.",
  "skill.excel-helper.name": "Spreadsheets",
  "skill.excel-helper.desc": "Formulas, pivot tables, charts, cleaning messy data",
  "skill.word-writer.name": "Documents",
@@ -275,5 +275,9 @@
  "hub.lede": "These are on this drive already. Just ask for what you want — you do not have to name the skill.",
  "hub.all": "All",
  "hub.none": "Nothing in this category.",
-  "hub.add_note": "Skills live in the skills/ folder on this drive. Dropping a SKILL.md in there adds one."
+  "hub.add_note": "Skills live in the skills/ folder on this drive. Dropping a SKILL.md in there adds one.",
  "nav.link_contact_d": "Open an issue",
  "skill.uclaw-help.name": "About U-Claw",
  "skill.uclaw-help.desc": "How it works, where things are, what to do when something breaks",
  "cat.uclaw": "U-Claw"
 }
--- a/portable/lib/messages/zh-CN.json
+++ b/portable/lib/messages/zh-CN.json
@@ -223,7 +223,7 @@
  "start.checking": "出了点问题，正在检查…",
  "start.repaired": "已修复，重试一次。",
  "start.diagnostics_written": "已把情况记录到：{path}",
-  "start.diagnostics_hint": "里面的密钥已被去掉。需要帮忙的话，把它发到 help@u-claw.org。",
+  "start.diagnostics_hint": "里面的密钥已被去掉。需要帮忙的话，把它附到 https://gitea.fanghe.it.com/zhenghy/u-claw/issues 的 issue 里。",
  "skill.excel-helper.name": "表格",
  "skill.excel-helper.desc": "公式、透视表、图表、清洗乱数据",
  "skill.word-writer.name": "文档",
@@ -275,5 +275,9 @@
  "hub.lede": "这些已经在盘上了。直接说你想做什么就行，不用记技能名。",
  "hub.all": "全部",
  "hub.none": "这个分类下暂时没有。",
-  "hub.add_note": "技能放在盘上的 skills/ 目录里。丢一个 SKILL.md 进去就多一个。"
+  "hub.add_note": "技能放在盘上的 skills/ 目录里。丢一个 SKILL.md 进去就多一个。",
  "nav.link_contact_d": "提 issue",
  "skill.uclaw-help.name": "关于 U-Claw",
  "skill.uclaw-help.desc": "它怎么用、东西在哪、出问题了怎么办",
  "cat.uclaw": "U-Claw"
 }
--- a/skills/en/uclaw-help/SKILL.md
+++ b/skills/en/uclaw-help/SKILL.md
@@ -0,0 +1,117 @@
 ---
 name: uclaw-help
 description: "Answer questions about U-Claw itself — how it works, where things are, what went wrong"
 metadata: { "openclaw": { "emoji": "🦞" } }
 ---
 # About U-Claw
 You are running inside U-Claw. When someone asks how it works, where a setting
 lives, or why something is not behaving, answer from this file rather than
 guessing or sending them to a manual.
 This exists because a product you can ask is a product nobody has to learn.
 ## What U-Claw is
 An AI assistant that lives on a USB drive. Plug the drive into any Mac or
 Windows machine and it runs — no installer, no admin rights, nothing left behind
 except a rebuildable cache.
 The three reasons it is on a drive at all:
 1. **Work computers often will not let you install software.** A drive needs no
   installer and no admin rights.
 2. **Your setup travels with you.** Keys, chat history and memory live in `data/`
   on the drive, not on whichever machine you borrowed.
 3. **Nothing meaningful is left on the host.** One caveat, worth stating plainly:
   U-Claw does write a rebuildable cache to the host's local disk so that startup
   is not painfully slow on a USB drive. There is a clean-up in `advanced/`.
 ## What is on the drive
 ```
 START HERE - Windows.bat   double-click this
 START HERE - Mac.command   or this
 Read me first.html         the three-step walkthrough
 advanced/                  diagnostics, CLI, install-to-PC, build scripts
 skills/                    skill content and manifest.json
 lib/                       launcher, i18n, helpers
 app/                       Node.js and OpenClaw (not in git)
 data/                      settings, memory, backups — this is the user's data
 ```
 Only three things in the root are clickable. Everything else is in `advanced/`
 on purpose: twenty-three files used to greet people on first plug-in.
 ## Where things live
 | Thing | Where |
 |---|---|
 | API key and model choice | `data/.openclaw/openclaw.json` |
 | What the AI remembers | `data/memory/` |
 | Chosen language | `uclaw.locale` in the same config |
 | Chosen role and interface tier | `uclaw.personas` and `uclaw.tier` |
 | Diagnostics report | `data/.openclaw/diagnostics.txt` |
 | Skills | `skills/` on the drive; installed copies under `app/core/` |
 ## Common questions
 **How do I change the model or key?**
 Open Settings — the launcher opens it on first run, and `Config.html` in
 `advanced/` redirects there any time. Paste a different key; U-Claw works out
 the provider from the key itself. A model dropdown appears once the key checks
 out.
 **How do I switch language?**
 Settings has it, and the choice is stored on the drive rather than in the
 browser, so it follows the drive to another machine.
 **I want to see more (or fewer) options.**
 Settings has a "how much do you want to see" control with three levels. Simple
 hides endpoints, model names and config files entirely.
 **Where did my settings go on the other computer?**
 They did not — they are on the drive. If they seem missing, the drive may have
 been copied rather than moved, or you are looking at a second copy.
 **Can I use it without internet?**
 Yes, with a local model — `advanced/Mac-LocalModel.command` or
 `Windows-LocalModel.bat` sets one up against Ollama or a self-hosted endpoint.
 Everything else needs to reach your model provider.
 **Is my data being uploaded?**
 Your key and conversations stay in `data/` on the drive. There is no telemetry,
 no device fingerprinting and no account. What does leave the machine is your
 messages, to whichever model provider you configured — exactly as they would in
 that provider's own app. If that is not acceptable, use the local model option.
 **Which file system should the drive use?**
 exFAT. macOS can only read NTFS, not write to it, which would break the whole
 "your settings travel with you" idea.
 ## When something is wrong
 U-Claw checks and repairs itself before complaining. If startup failed and could
 not be fixed, it writes `data/.openclaw/diagnostics.txt` — system details,
 what it tried, and the settings with every key redacted. The user can read it
 before deciding to share it.
 Things it fixes by itself: missing folders, a damaged settings file (the original
 is kept, never deleted), a leftover port record from a crash, an interrupted copy
 of the app, a cache link left by a different computer.
 Things it will not do: kill a process it did not start. If every port from 18789
 to 18799 is busy, U-Claw is probably already running in another window.
 ## Answering well
 - **Do it rather than describe it** where you can. "How do I switch to Chinese?"
  is better answered by changing it than by explaining which menu to open.
 - **Say when you do not know.** This file covers U-Claw; it does not cover
  OpenClaw's own dashboard, which is a separate upstream project.
 - **Do not invent paths or settings.** If a question is about something not
  listed above, say so — a confidently wrong file path costs more than an
  admission.
 - Keep answers to the length the question deserves. Most are one or two
  sentences.
--- a/skills/manifest.json
+++ b/skills/manifest.json
@@ -46,6 +46,26 @@
    }
  ],
  "skills": [
    {
      "id": "uclaw-help",
      "status": "shipping",
      "locales": [
        "en"
      ],
      "categories": [
        "uclaw"
      ],
      "personas": [
        "developer",
        "admin",
        "sales",
        "marketing",
        "finance",
        "boss",
        "general"
      ],
      "emoji": "🦞"
    },
    {
      "id": "excel-helper",
      "status": "shipping",
--- a/tests/origin.test.mjs
+++ b/tests/origin.test.mjs
@@ -110,11 +110,11 @@ test('install-skills.mjs reads origin.json rather than hardcoding the host', ()
  assert.equal(fallback, origin.urls.rawTemplate, 'the fallback template disagrees with origin.json');
 });
-test('every u-claw.org address in the tree is one origin.json accounts for', () => {
+test('we do not tell users to email a domain we do not own', () => {
-  // Not "all the same" — they legitimately differ by role. The point is that no
+  // u-claw.org is the upstream project's domain. Any address on it reaches them,
-  // address exists that nobody has thought about, because on a fork some of
+  // not us — so a support line pointing there sends our users' problems to
-  // these route to the upstream maintainer rather than to us.
+  // someone with no reason to answer.
-  const known = new Set(Object.values(origin.support).filter((v) => /@/.test(v)));
+  const OURS = new Set(Object.values(origin.upstream?.addresses ?? {}).filter((v) => /@/.test(v)));
  const offenders = [];
  for (const file of walk(repoRoot)) {
    if (!SCANNED.has(extname(file))) continue;
@@ -122,23 +122,22 @@ test('every u-claw.org address in the tree is one origin.json accounts for', ()
    if (rel === 'origin.json' || SKIPPED_FILES.has(rel.split('/').pop())) continue;
    readFileSync(file, 'utf8').split(/\r?\n/).forEach((line, i) => {
      for (const [found] of line.matchAll(/[\w.+-]+@u-claw\.org/g)) {
-        if (!known.has(found)) offenders.push(`${rel}:${i + 1} uses ${found}`);
+        // Upstream's own addresses may appear where the text is about upstream.
        if (OURS.has(found)) continue;
        offenders.push(`${rel}:${i + 1} offers ${found}, a domain we do not control`);
      }
    });
  }
-  assert.deepEqual(offenders, [], `addresses origin.json does not account for:\n${offenders.join('\n')}`);
+  assert.deepEqual(offenders, [], offenders.join('\n'));
 });
-test('origin.json flags the addresses that still belong to upstream', () => {
+test('support routes somewhere we actually control', () => {
-  // This is the thing that is easy to ship without noticing: a fork whose
+  assert.match(origin.support.issues, /^https:\/\//, 'there has to be a working support route');
  // SECURITY.md sends vulnerability reports to someone who did not write the
  // code, and cannot fix it.
  assert.ok(origin.support.note, 'origin.json should say which addresses are not ours yet');
  assert.match(origin.support.note, /security/i);
  const security = readFileSync(join(repoRoot, 'SECURITY.md'), 'utf8');
  assert.ok(
-    security.includes(origin.support.security),
+    origin.support.issues.includes(origin.repo.host),
-    'SECURITY.md and origin.json disagree about where to report a vulnerability',
+    'support should point at our own host, not the upstream project',
  );
  // Until we have an address of our own, saying so beats leaving a stale one.
  assert.ok('email' in origin.support, 'origin.json should record whether we have an address yet');
  assert.match(origin.support.note, /do not own u-claw\.org/i);
 });
--- a/tests/self-heal.test.mjs
+++ b/tests/self-heal.test.mjs
@@ -135,6 +135,11 @@ test('startup heals before it complains, and never dead-ends', () => {
  assert.match(start, /start\.diagnostics_written/, 'the user should be told where the report is');
  const en = JSON.parse(readFileSync(join(repoRoot, 'portable', 'lib', 'messages', 'en.json'), 'utf8'));
-  assert.match(en['start.diagnostics_hint'], /help@u-claw\.org/, 'the report needs somewhere to go');
+  const origin = JSON.parse(readFileSync(join(repoRoot, 'origin.json'), 'utf8'));
  // A report with nowhere to go is just a file on a drive.
  assert.ok(
    en['start.diagnostics_hint'].includes(origin.support.issues),
    'the report should point at the support route origin.json declares',
  );
  assert.match(en['start.diagnostics_hint'], /removed/i, 'say that keys were stripped, or nobody will send it');
 });
--- a/tests/windows-launchers.test.mjs
+++ b/tests/windows-launchers.test.mjs
@@ -145,7 +145,7 @@ test('message catalogues have no untranslated leftovers', () => {
  assert.deepEqual(extra, [], `zh-CN.json has keys English does not: ${extra.join(', ')}`);
  // Product names and technical identifiers are the same in every language.
  // Everything else being identical means a string was copied, not translated.
-  const NOT_TRANSLATED_BY_DESIGN = new Set(['start.node_version']);
+  const NOT_TRANSLATED_BY_DESIGN = new Set(['start.node_version', 'cat.uclaw']);
  const identical = Object.keys(en).filter(
    (key) =>
      !NOT_TRANSLATED_BY_DESIGN.has(key) &&