不是翻译 —— 多数文档描述的行为已经不存在了。 先修一个更基本的问题：我们不拥有 u-claw.org 域名，那是上游的。所以之前写在 README、诊断包提示、联系方式里的 help@u-claw.org 全都会把用户的问题发给 上游 —— 一个没有理由回复的人。改为指向我们自己的 issue tracker，并加断言 禁止再出现指向该域名的支持入口。 重写（内容过时，不是语言问题）： - install/README.md —— 还写着 10 个中国技能、DeepSeek 优先、国内镜像。 现在按实际流程写：技能读 manifest、模型菜单 Gemini 优先、bundle 有 SHA256 校验。并如实写明 curl|bash 在受管企业电脑上会被 EDR 拦。 - CLAUDE.md 的模型配置整节 —— 还在描述虾盘云首选卡片和 12 个 provider， 那个界面已经换成单框 Key 输入了。 - SECURITY.md —— 安全报告原本指向上游维护者个人邮箱。fork 之后那条路由 是错的：漏洞会发给写不了这份代码、也修不了的人。 - CONTRIBUTING.md —— 补上 fork 关系、pre-push 钩子怎么装、以及 `node --test tests/` 为什么不能用。 翻译并保留： - bootable/README.md、TROUBLESHOOTING.md —— 面向用户，顺带把 「国内镜像」「小米/华为 BIOS 按键」等换成目标市场的实际情况 HANDOFF.md 重写为一份事故复盘：原文一半是过时的一次性交接笔记（引用的 website/guide.html 已不在本仓库），另一半是 persistence.dat 未格式化导致 启动失败的排查记录 —— 后者有长期价值，尤其是「读 offset 1080 的两字节 验证 ext4」这个判断方法，已同时写进 bootable/README.md。 bootable/IMPROVEMENTS_SUMMARY.md 保留中文，加了说明：它是上游 fork 前的 历史改进记录，没人引用，描述的是已完成的工作而非当前行为。翻译它反而会 让人误以为是现行文档。 新增 skills/en/uclaw-help —— 把「怎么用、东西在哪、出问题怎么办」做成 内置知识，每个角色都装。方案 C10.8：能问的产品才是不需要学的产品。
This commit is contained in:
98
HANDOFF.md
98
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
|
||||
- 所有源码已推送到 GitHub main 分支
|
||||
- website/guide.html 已添加快速命令参考卡片
|
||||
- enable-ssh.sh 已添加到 bootable/linux-setup/
|
||||
## What happened
|
||||
|
||||
## 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
|
||||
2. 如果首次使用，格式化持久化：
|
||||
```
|
||||
sudo bash /media/*/Ventoy/u-claw-linux/format-persistence.sh
|
||||
```
|
||||
然后重启
|
||||
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
|
||||
```
|
||||
`persistence.dat` on the drive was a 20 GB **empty** file with no ext4
|
||||
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
|
||||
`ventoy.json`, tried to mount that file, failed, and the boot collapsed into
|
||||
initramfs.
|
||||
|
||||
## 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 默认用户)
|
||||
- **密码**: 运行 enable-ssh.sh 时设置
|
||||
- **IP 地址**: 运行 enable-ssh.sh 后会显示，格式类似 192.168.x.x
|
||||
- **前提**: 两台机器在同一个 WiFi/局域网下
|
||||
## The fix at the time
|
||||
|
||||
## 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 和设置密码
|
||||
2. 用户告诉 Mac mini 上的 Claude Code：IP 地址和密码
|
||||
3. Mac mini Claude Code 通过 Bash 工具执行：
|
||||
```
|
||||
ssh ubuntu@<IP> 'command'
|
||||
```
|
||||
或建立持久连接进行调试
|
||||
```bash
|
||||
dd if=/dev/zero of=/tmp/persistence.dat bs=1M count=0 seek=20480
|
||||
/sbin/mkfs.ext4 -F -L casper-rw /tmp/persistence.dat
|
||||
```
|
||||
|
||||
## 文件位置（Linux 上）
|
||||
Then copied it to `C:` and moved it onto the drive — docker-desktop's WSL cannot
|
||||
reach other drive letters directly.
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| `/media/*/Ventoy/u-claw-linux/` | U 盘上的脚本 |
|
||||
| `/opt/u-claw/` | 安装后的 OpenClaw |
|
||||
| `/opt/u-claw/start-openclaw.sh` | 启动脚本 |
|
||||
| `/opt/u-claw/data/.openclaw/openclaw.json` | 配置文件 |
|
||||
## How to tell a persistence file is real
|
||||
|
||||
## 注意事项
|
||||
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 每次重启后，除了持久化分区内的数据，其他都会重置
|
||||
- SSH server 需要每次重启后重新安装（除非持久化生效）
|
||||
- 持久化生效后，apt 安装的包会保留
|
||||
This is the check worth keeping: it takes a second and distinguishes "built
|
||||
correctly" from "built, and will fail at boot on someone else's desk".
|
||||
|
||||
## 2026-03-17 修复：persistence.dat 未格式化导致启动失败
|
||||
## What changed in the scripts
|
||||
|
||||
### 问题
|
||||
- U 盘上的 `persistence.dat`（20GB）是空文件，没有 ext4 文件系统
|
||||
- `3-create-persistence.ps1` 因无可用标准 WSL，走了 Method B，只创建了稀疏空文件
|
||||
- Ventoy 启动 Ubuntu → 读 ventoy.json → 尝试挂载空的 persistence.dat → mount 失败 → 卡在 initramfs
|
||||
- `3-create-persistence.ps1` now tries docker-desktop's WSL before giving up
|
||||
- It verifies the ext4 magic number after formatting
|
||||
- It only falls back to an unformatted sparse file when there is no WSL at all,
|
||||
and says so loudly — that path requires the user to run `mkfs.ext4` by hand on
|
||||
first boot, and then reboot
|
||||
|
||||
### 修复过程
|
||||
1. 用 docker-desktop WSL 的 `/sbin/mkfs.ext4` 格式化：
|
||||
- 在 WSL 内创建稀疏文件：`dd if=/dev/zero of=/tmp/persistence.dat bs=1M count=0 seek=20480`
|
||||
- 格式化：`/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 时才降级为未格式化的空文件
|
||||
The user-facing version of this is in
|
||||
[`bootable/README.md`](bootable/README.md) and
|
||||
[`bootable/TROUBLESHOOTING.md`](bootable/TROUBLESHOOTING.md).
|
||||
|
||||
Reference in New Issue
Block a user