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