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/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 — just boot from USB**
+> Turn any computer into an AI workstation — boot from the drive, no operating
+> system required on the machine itself.

-## 独立性说明
+## 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/` 中的任何文件
- 所有脚本内部硬编码了 URL 和路径，完全自包含
- 出问题只影响 `bootable/` 自身，不会波及其他模块
- 同时维护了一份**独立仓库**：[u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux)，内容一致
+That makes it the answer for a machine that is locked down, wiped, or running
+something you cannot install onto.

-## 这是什么
+## 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 桌面
- 一键安装 OpenClaw AI 助手，桌面图标双击即用
- 内置持久化存储，安装的软件和数据重启后保留
- **不需要目标电脑有任何操作系统**
+There is also a standalone mirror at
+[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

 ```
-┌────────────────────────────────────────────┐
-│                U 盘结构                      │
-│                                            │
-│  Ventoy 引导区（隐藏分区）                   │
-│    - BIOS + UEFI 双模式启动                  │
-│    - 开源引导管理器 v1.0.99                  │
-│                                            │
-│  Ventoy 数据分区（可见）                     │
-│    ubuntu-24.04.4-desktop-amd64.iso  5.8GB │
-│    persistence.dat                   20GB  │
-│    ventoy/ventoy.json                配置   │
-│    u-claw-linux/                     脚本   │
-│      ├── setup-openclaw.sh                 │
-│      └── start-openclaw.sh                 │
-└────────────────────────────────────────────┘
+Ventoy boot area (hidden partition)
+  BIOS + UEFI dual-mode boot, Ventoy 1.0.99
+
+Ventoy data partition (visible)
+  ubuntu-24.04.4-desktop-amd64.iso   5.8 GB
+  persistence.dat                    20 GB
+  ventoy/ventoy.json                 config
+  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 |

-| 技术 | 为什么选它 |
-|------|-----------|
-| **Ventoy 1.0.99** | ISO 文件直接丢进去就能启动，不用烧录，可放多个系统 |
-| **Ubuntu 24.04 LTS** | 长期支持版，驱动兼容性最好，社区最大 |
-| **casper-rw 持久化** | 让 Live USB 也能保存数据，重启不丢失 |
+## What you need

-## 硬件要求
+| | |
+|---|---|
+| 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 |

-| 项目 | 要求 |
-|------|------|
-| U 盘 | **32GB+**，强烈推荐 USB 3.0（蓝色接口） |
-| 制作环境 | Windows 10/11，PowerShell 5.1+ |
-| 目标电脑 | x86_64（Intel / AMD），任意品牌 |
-| 网络 | 首次安装 OpenClaw 时需要联网 |
+## Building it — four steps

-## 快速制作（4 步）
-
-在 Windows 上以**管理员身份**打开 PowerShell：
+Open PowerShell **as Administrator** on Windows:

 ```powershell
 cd path\to\u-claw\bootable

-# Step 1: 下载 Ventoy 并写入 U 盘（会格式化！）
-.\1-prepare-usb.ps1
-
-# Step 2: 下载 Ubuntu 24.04 ISO（~5.8GB，国内镜像）
-.\2-download-iso.ps1
-
-# Step 3: 创建持久化镜像（默认 20GB）
-.\3-create-persistence.ps1
-
-# Step 4: 拷贝所有文件到 U 盘
-.\4-copy-to-usb.ps1
+.\1-prepare-usb.ps1          # Write Ventoy to the drive — THIS FORMATS IT
+.\2-download-iso.ps1         # Download Ubuntu 24.04 (~5.8 GB)
+.\3-create-persistence.ps1   # Create the persistence image (20 GB default)
+.\4-copy-to-usb.ps1          # Copy everything onto the drive
 ```

-## 自动脚本失败时的手动兜底流程
+### 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 下载或安装失败**
-   - 手动下载 Ventoy Windows 版：https://github.com/ventoy/Ventoy/releases
-   - 解压后运行 `Ventoy2Disk.exe`
-   - 选择目标 U 盘并点击 Install
-   - 注意：这一步会格式化 U 盘，先备份数据
+**2 · Download Ubuntu** — fetches the 24.04.4 desktop ISO from
+`releases.ubuntu.com`, verifies its SHA256, and caches it so a retry does not
+re-download 5.8 GB.

-2. **Ubuntu ISO 自动下载失败**
-   - 手动下载 Ubuntu 24.04.4 Desktop ISO：
-     https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso
-   - 手动下载 SHA256SUMS：
-     https://releases.ubuntu.com/24.04/SHA256SUMS
-   - 将 ISO 放到 `bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso`
-   - 可用 PowerShell 校验哈希：
+**3 · Create persistence** — the step that actually decides whether this works.
+
+- **With WSL installed** → creates a properly formatted ext4 image directly
+- **With only docker-desktop's WSL** → falls back to `/sbin/mkfs.ext4`
+- **With no WSL at all** → creates an empty sparse file that **you must format
+  by hand** on first boot (see below)
+
+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
-.\3-create-persistence.ps1
-```
-
-如果脚本提示没有 WSL 或只能创建空文件，首次进入 Ubuntu 后需要手动格式化：
+Boot into Ubuntu once, then:

 ```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
-.\4-copy-to-usb.ps1
-```
+Put these on the Ventoy data partition by hand:

-   - 如果自动拷贝失败，也可以手动放到 Ventoy 数据分区根目录：
-
-| 本地路径 | U 盘目标 |
-|---------|----------|
+| From | To (drive root) |
+|---|---|
 | `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. **目标电脑启动**
-   - 从 U 盘启动，Ventoy 菜单选择 Ubuntu
-   - 如遇 Secure Boot 拦截，进 BIOS 关闭 Secure Boot
-   - 进入 Ubuntu 桌面后运行：
+## Using it
+
+### First time
+
+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 设备，让你确认
- 从 GitHub 下载 Ventoy 1.0.99
- 启动 Ventoy2Disk.exe GUI
- 你在 GUI 中选择 U 盘 → 点 Install
- **注意：会格式化 U 盘，数据全丢！提前备份！**
+Plug in, boot, double-click the icon. Everything you set up is still there.

-### Step 2: 下载 Ubuntu ISO (`2-download-iso.ps1`)
+## What `setup-openclaw.sh` does

- 从国内镜像下载 Ubuntu 24.04.4 桌面版（~5.8GB）
- 镜像优先级：清华 → 阿里 → 中科大 → 官方
- SHA256 校验确保文件完整
- 有缓存，不会重复下载
+| Step | |
+|---|---|
+| 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`)
-
-这是整个方案**最关键**的一步：
-
- 检测是否安装了 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 | 创建桌面快捷方式 | 可选开机自启 |
-
-## 核心配置文件
+## Configuration

 ### `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                      本文件
-├── 1-prepare-usb.ps1              Step 1: Ventoy 写入
-├── 2-download-iso.ps1             Step 2: Ubuntu ISO 下载
-├── 3-create-persistence.ps1       Step 3: 持久化镜像
-├── 4-copy-to-usb.ps1              Step 4: 拷贝到 U 盘
+├── README.md                    this file
+├── 1-prepare-usb.ps1            write Ventoy
+├── 2-download-iso.ps1           download Ubuntu
+├── 3-create-persistence.ps1     create the persistence image
+├── 4-copy-to-usb.ps1            copy onto the drive
 ├── linux-setup/
-│   ├── format-persistence.sh      格式化持久化镜像
-│   ├── setup-openclaw.sh          一键安装 OpenClaw
-│   ├── start-openclaw.sh          启动脚本
-│   └── openclaw.desktop           桌面快捷方式
+│   ├── format-persistence.sh    format the persistence image
+│   ├── setup-openclaw.sh        install OpenClaw
+│   ├── start-openclaw.sh        launcher
+│   └── 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 盘选择很重要**
-   - 必须 32GB+（ISO 5.8GB + 持久化 20GB + 系统开销）
-   - 强烈建议 USB 3.0，否则启动和运行都会很慢
-   - 推荐品牌：闪迪、金士顿、三星（杂牌盘容易出问题）
-   - 避免使用 USB Hub，直接插主板接口
+**Formatting requires a reboot.** Running `mkfs.ext4` and continuing in the same
+session looks like it worked and silently does not persist.

-2. **Step 1 会清空 U 盘**
-   - Ventoy 安装会格式化整个 U 盘，**务必提前备份**
-   - 脚本会列出所有 USB 设备让你确认，看清楚再操作
+**Drive quality matters more than you would expect.** Cheap unbranded drives fail
+in ways that look like software problems. Use USB 3.0, plug into the board
+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 持久化镜像（重要教训）**
-   - 有标准 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+
+**Sizing**: 20 GB persistence on a 32 GB drive, 40 GB+ on a 64 GB drive.

-4. **ISO 下载失败**
-   - 脚本默认走清华/阿里/中科大国内镜像，无需翻墙
-   - 如果全部失败，手动下载 Ubuntu ISO 放到 `.download-cache/` 目录即可
+## Troubleshooting

-### 启动阶段
+| 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 问题**
-   - 部分电脑需要关闭 Secure Boot 才能从 U 盘启动
-   - 进 BIOS → Security → Secure Boot → Disabled
-   - 不同品牌进 BIOS 的方式不同（通常 DEL 或 F2）
+**Performance**: running off a USB drive is slower than a disk — that is
+physics, not a bug. Inference happens at your model provider, so conversation
+speed is unaffected; only startup and file operations are slower.

-6. **找不到 USB 启动项**
-   - 换个 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) - 完整的问题排查步骤和解决方案
+For anything not covered here, see [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盘
-**解决方案**:
-1. 以管理员身份运行PowerShell
-2. 关闭所有可能占用U盘的程序（文件资源管理器、杀毒软件等）
-3. 尝试使用Ventoy的"只读模式"安装
-4. 如果U盘有写保护开关，请关闭它
+*"Access Denied", or it cannot write to the drive.*

-### 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时速度慢或中断
-**解决方案**:
-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`
+### The ISO download is slow or fails

-### 3. 持久化存储创建失败
+The script pulls from `releases.ubuntu.com` and verifies the SHA256. If it keeps
+failing, download it yourself:

-**问题**: `3-create-persistence.ps1` 提示磁盘空间不足
-**解决方案**:
-1. 确保U盘至少有32GB空间
-2. 默认持久化大小为20GB，可以修改脚本中的 `$PersistenceSizeGB` 变量
-3. 最小建议值：8GB
+- https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso

-### 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盘启动后黑屏或卡住
-**解决方案**:
-1. 启动时按 `F6` 或 `Esc` 进入引导选项
-2. 添加内核参数：
-   - `nomodeset` - 禁用显卡驱动
-   - `quiet splash` - 禁用启动画面
-3. 如果使用NVIDIA显卡，尝试 `nouveau.modeset=0`
+### Not enough space for the persistence image

-### 5. OpenClaw安装失败
+`3-create-persistence.ps1` needs room for a 20 GB file alongside a 5.8 GB ISO.

-**问题**: `setup-openclaw.sh` 执行失败
-**解决方案**:
-1. **网络问题**:
-   ```bash
-   # 测试网络连接
-   ping -c 3 npmmirror.com
-   
-   # 如果网络有问题，使用代理
-   export http_proxy=http://your-proxy:port
-   export https_proxy=http://your-proxy:port
-   ```
+- A 32 GB drive is the practical minimum
+- Change `$PersistenceSizeGB` in the script to use less
+- Below about 8 GB there is not enough room to install anything meaningful

-2. **权限问题**:
-   ```bash
-   # 确保以root运行
-   sudo bash setup-openclaw.sh
-   ```
+## While booting

-3. **依赖问题**:
-   ```bash
-   # 手动安装依赖
-   sudo apt-get update
-   sudo apt-get install curl xdg-utils
-   ```
+### Black screen, or it hangs before the desktop

-### 6. OpenClaw无法启动
+Press `F6` or `Esc` at the boot menu to add kernel parameters:

-**问题**: `start-openclaw.sh` 启动失败
-**解决方案**:
-1. **检查Node.js**:
-   ```bash
-   /opt/u-claw/runtime/node-linux-x64/bin/node --version
-   # 应该显示 v22.14.0
-   ```
+| 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 |

-2. **检查OpenClaw安装**:
-   ```bash
-   ls -la /opt/u-claw/core/node_modules/openclaw/
-   ```
+### It drops into an initramfs prompt

-3. **端口冲突**:
-   ```bash
-   # 检查端口占用
-   ss -tlnp | grep :18789
-   
-   # 如果端口被占用，手动指定端口
-   cd /opt/u-claw/core
-   node node_modules/openclaw/openclaw.mjs gateway run --port 18800
-   ```
+`persistence.dat` has no ext4 filesystem in it. This is the single most common
+build failure, and the error message says nothing about the real cause.

-### 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
-```

-### 测试网络
-```bash
-# 测试国内镜像
-curl -I https://registry.npmmirror.com
-curl -I https://npmmirror.com/mirrors/node
+# is the network reachable
+curl -I https://registry.npmjs.org

-# 测试AI API
-curl https://api.deepseek.com/health
-```
-
-### 检查磁盘使用
-```bash
-# 查看U盘使用情况
-df -h /media/ubuntu
-
-# 查看大文件
+# where the space went
+df -h /media/*/Ventoy
 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盘**:
-   - 在Windows/Mac上插入U盘
-   - 备份 `u-claw-linux/` 目录下的重要数据
+## Getting a better result

-2. **重新制作U盘**:
-   - 格式化U盘
-   - 重新运行所有4个PowerShell脚本
+**When building**: use a good USB 3.0 drive, give persistence at least 20 GB,
+and turn off real-time antivirus scanning for the build — it slows the ISO write
+enormously and occasionally corrupts it.

-3. **寻求帮助**:
-   - GitHub Issues: https://gitea.fanghe.it.com/zhenghy/u-claw/issues
-   - 微信: hecare888
+**On first boot**: run the system updates and install the recommended drivers
+once, while you have network. With persistence on, you only do it once.

-## 性能优化建议
-
-1. **制作时**:
-   - 使用高质量的USB 3.0 U盘
-   - 分配足够的持久化空间（建议20GB+）
-   - 关闭杀毒软件实时扫描
-
-2. **使用时**:
-   - 首次启动后运行系统更新
-   - 安装推荐驱动
-   - 定期清理缓存
-
-3. **长期使用**:
-   - 考虑安装到硬盘（双系统）
-   - 定期备份重要数据
-   - 关注Ubuntu安全更新
+**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.