不是翻译 —— 多数文档描述的行为已经不存在了。 先修一个更基本的问题：我们不拥有 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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user