zheng
b076815171
Some checks failed
Tests / test (push) Has been cancelled
按 U-Claw-海外化改造方案.md 与 范围决策记录.md 实施。这是 fork，不回上游： 海外版删掉的正是上游的中国市场默认值。 阶段 0 地基 - 下载源全部改国际：脚本/CI 61 处 + lockfile 880 条 npmmirror URL 归零 （lockfile 那 880 条是 npm 的 resolved 字段，脚本层参数化根本绕不过它） - 移除 install.ps1 里三个第三方 GitHub 加速代理，bundle 改直连 + SHA256 校验 （原来只检查"文件大于 1MB"就解压运行） - 技能内容与分发分离：skills/manifest.json 单一来源，install.sh 1170→658 行、 install.ps1 721→546 行，两者技能内容归零 实测原来是三份不一致：skills-cn 完整、install.sh 约 40%、install.ps1 约 17%， 且 7 个通用技能只有 U 盘版有 —— 一键安装的用户一个能用的技能都没有 - Node 版本三种（v22.14/16/22.1）统一，新建 NODE_VERSION 单一来源 - Config 页三份合一。portable/Config.html 用根相对路径调 API 却只从 file:// 打开， 保存功能已静默失效两个月；现缩为 120 行重定向壳 - 测试接入 CI（此前 node --test 无人运行，所有断言形同虚设） 阶段 1 双语可用 - 浏览器侧 i18n：JSON 为源、生成经典 script（file:// 下 fetch 本地 JSON 被拦） 语言跟盘走不跟机器走：启动器写 data/.openclaw/locale.js - 8 处硬编码 lang="zh-CN" 归零，data-i18n 覆盖 213 处，词条 en/zh 各 279 条 - B3 单框 Key：12 张模型卡 → 一个输入框，前缀识别 provider， 服务端 /api/test-key 发 1-token 请求实测，错误映射成人话 Key 填错到得知：从"直到对话失败"降到 ≤1 秒 - 区域格式 SG：DD/MM/YYYY、12 小时、S$、Asia/Singapore （ICU 在 en-SG 下把 SGD 渲染成裸 $，与美元无法区分，故自行拼 S$） - README 内容分叉而非翻译，§1.3 证据清单逐条清零 阶段 2 降门槛 - 启动逻辑上移 lib/start.mjs：Windows-Start.bat 220→28 行、 Mac-Start.command 235→33 行 修掉 Mac 侧两个 bug：控制台端口硬编码 18788（回落时打开死页）、 微信插件从未在 Mac 上安装 - U 盘根目录 23 → 3 个可点文件，其余进 advanced/ - 首启向导：语言 → 用途（7 角色，manifest 驱动）→ 密钥，答过不再问 - 三档界面，Simple 档隐藏一切技术名词 - 自动自愈：启动失败先自查自修，修不好导出脱敏诊断包 （Doctor 从"用户要知道去点的工具"变成后台机制） 阶段 3 技能库 - 19 个英文技能，planned 归零。sg-weather / sg-transport 的端点均实测过 - SkillHub 从 56 张手写第三方卡片改为 manifest 生成：703→125 行，中文归零 其他 - origin.json 收拢所有运行时地址，tests/origin.test.mjs 保证迁移不会漏 - portable/ 下用户可见中文归零（由断言保证） - 82 项测试 未验证（本机无 Windows / 无 pwsh）： - install.ps1、setup.ps1 约 210 行改动从未经 PowerShell 解析器 - 完整启动路径仅在假 node + 假 openclaw 上冒烟 - 8 个 .bat 的盘根推导仅静态断言 详见 U盘实测清单.md 受阻： - 隐藏黑窗口 —— 需代码签名证书（.vbs 已被 Windows 弃用，替代方案都要签名） - 场景卡 —— OpenClaw 上游 Dashboard 无预填 prompt 接口 - 官网 36 条 —— 上游 2026-04-14 拆到私有仓库，无权限
U-Claw Bootable USB (Linux)
把任意电脑变成 AI 工作站 — 插上 U 盘，开机即用
Turn any computer into an AI workstation — just boot from USB
独立性说明
本目录 (bootable/) 在 u-claw 主仓库中保持目录级别的独立：
- 不依赖仓库内
portable/、u-claw-app/、website/中的任何文件 - 所有脚本内部硬编码了 URL 和路径，完全自包含
- 出问题只影响
bootable/自身，不会波及其他模块 - 同时维护了一份独立仓库：u-claw-linux，内容一致
这是什么
制作一个可启动的 Linux AI U 盘：
- 插上任意电脑，从 U 盘启动，直接进入 Ubuntu 桌面
- 一键安装 OpenClaw AI 助手，桌面图标双击即用
- 内置持久化存储，安装的软件和数据重启后保留
- 不需要目标电脑有任何操作系统
与便携版（
portable/）的区别：便携版需要电脑已有 Windows/Mac 系统，可启动版连系统都不需要。
技术方案
┌────────────────────────────────────────────┐
│ 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 1.0.99 | ISO 文件直接丢进去就能启动，不用烧录，可放多个系统 |
| Ubuntu 24.04 LTS | 长期支持版，驱动兼容性最好，社区最大 |
| casper-rw 持久化 | 让 Live USB 也能保存数据，重启不丢失 |
硬件要求
| 项目 | 要求 |
|---|---|
| U 盘 | 32GB+，强烈推荐 USB 3.0（蓝色接口） |
| 制作环境 | Windows 10/11，PowerShell 5.1+ |
| 目标电脑 | x86_64（Intel / AMD），任意品牌 |
| 网络 | 首次安装 OpenClaw 时需要联网 |
快速制作（4 步）
在 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
自动脚本失败时的手动兜底流程
由 @wzf9 在 issue #28 反馈整理，适合 Ventoy/ISO 自动下载失败、网络不稳定或需要离线制作的场景。
-
Ventoy 下载或安装失败
- 手动下载 Ventoy Windows 版：https://github.com/ventoy/Ventoy/releases
- 解压后运行
Ventoy2Disk.exe - 选择目标 U 盘并点击 Install
- 注意：这一步会格式化 U 盘，先备份数据
-
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 校验哈希：
(Get-FileHash -Algorithm SHA256 ".\.download-cache\ubuntu-24.04.4-desktop-amd64.iso").Hash -eq "3a4c9877b483ab46d7c3fbe165a0db275e1ae3cfe56a5657e5a47c2f99a99d1e"
- 继续创建持久化文件
.\3-create-persistence.ps1
如果脚本提示没有 WSL 或只能创建空文件，首次进入 Ubuntu 后需要手动格式化：
sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
格式化完成后重启，持久化才会生效。
- 拷贝到 U 盘
- 优先运行：
.\4-copy-to-usb.ps1
- 如果自动拷贝失败，也可以手动放到 Ventoy 数据分区根目录：
| 本地路径 | 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 |
- 目标电脑启动
- 从 U 盘启动，Ventoy 菜单选择 Ubuntu
- 如遇 Secure Boot 拦截，进 BIOS 关闭 Secure Boot
- 进入 Ubuntu 桌面后运行：
sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
每一步做了什么
Step 1: 写入 Ventoy 引导 (1-prepare-usb.ps1)
- 列出所有 USB 设备，让你确认
- 从 GitHub 下载 Ventoy 1.0.99
- 启动 Ventoy2Disk.exe GUI
- 你在 GUI 中选择 U 盘 → 点 Install
- 注意：会格式化 U 盘，数据全丢！提前备份！
Step 2: 下载 Ubuntu ISO (2-download-iso.ps1)
- 从国内镜像下载 Ubuntu 24.04.4 桌面版（~5.8GB）
- 镜像优先级：清华 → 阿里 → 中科大 → 官方
- SHA256 校验确保文件完整
- 有缓存，不会重复下载
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、安装脚本
使用方法
首次使用
- 将 U 盘插入目标电脑
- 开机按启动键：
| 品牌 | 启动键 |
|---|---|
| Dell 戴尔 | F12 |
| Lenovo 联想 | F12 |
| HP 惠普 | F9 |
| ASUS 华硕 | F2 或 DEL |
| Acer 宏碁 | F12 |
| MSI 微星 | F11 |
| Huawei 华为 | F12 |
| Xiaomi 小米 | F12 |
- 启动菜单选择 USB 设备
- Ventoy 菜单 → 选择 Ubuntu
- 等待 Ubuntu 桌面加载
- 连接 Wi-Fi
- 打开终端（
Ctrl+Alt+T或右键桌面 → Open Terminal） - 运行安装命令：
sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
- 桌面出现 "U-Claw AI Assistant" 图标
- 双击图标 → 浏览器打开 → 配置 AI 模型
日常使用
- 插入 U 盘 → 开机选 USB → Ubuntu 桌面
- 双击桌面图标
- 所有数据自动保留
安装脚本详解 (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
{
"persistence": [
{
"image": "/ubuntu-24.04.4-desktop-amd64.iso",
"backend": "/persistence.dat",
"autosel": 1
}
]
}
告诉 Ventoy：启动 Ubuntu ISO 时自动加载 persistence.dat。autosel: 1 = 不弹确认框。
Linux 端环境变量
| 变量 | 值 |
|---|---|
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 |
文件结构
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 盘
├── linux-setup/
│ ├── format-persistence.sh 格式化持久化镜像
│ ├── setup-openclaw.sh 一键安装 OpenClaw
│ ├── start-openclaw.sh 启动脚本
│ └── openclaw.desktop 桌面快捷方式
└── ventoy/
└── ventoy.json Ventoy 持久化配置
实践经验与注意事项
制作阶段
-
U 盘选择很重要
- 必须 32GB+（ISO 5.8GB + 持久化 20GB + 系统开销）
- 强烈建议 USB 3.0，否则启动和运行都会很慢
- 推荐品牌：闪迪、金士顿、三星（杂牌盘容易出问题）
- 避免使用 USB Hub，直接插主板接口
-
Step 1 会清空 U 盘
- Ventoy 安装会格式化整个 U 盘，务必提前备份
- 脚本会列出所有 USB 设备让你确认，看清楚再操作
-
Step 3 持久化镜像（重要教训）
- 有标准 WSL（Ubuntu 等）→ 自动创建 ext4 镜像（最省事）
- 只有 docker-desktop WSL → 脚本会尝试用
/sbin/mkfs.ext4格式化（2026-03-17 修复） - 完全没有 WSL → 创建空文件，必须首次进 Linux 后手动格式化：
格式化后必须重启才能生效
sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat - 踩坑记录：空的 persistence.dat（无 ext4 文件系统）会导致 Ventoy 挂载失败，
Ubuntu 启动直接掉进 initramfs。验证方法：读取文件 offset 1080 处的 2 字节，
应为
0x53 0xEF（ext4 magic number0xEF53的 little-endian 表示） - 大小建议：32GB U 盘选 20GB，64GB U 盘可选 40GB+
-
ISO 下载失败
- 脚本默认走清华/阿里/中科大国内镜像，无需翻墙
- 如果全部失败，手动下载 Ubuntu ISO 放到
.download-cache/目录即可
启动阶段
-
Secure Boot 问题
- 部分电脑需要关闭 Secure Boot 才能从 U 盘启动
- 进 BIOS → Security → Secure Boot → Disabled
- 不同品牌进 BIOS 的方式不同（通常 DEL 或 F2）
-
找不到 USB 启动项
- 换个 USB 口试试
- 有些电脑默认禁用了 USB 启动，需要在 BIOS 中开启
- Legacy/CSM 模式和 UEFI 模式都试试
-
Ubuntu 桌面加载慢
- 正常现象，Live USB 从 U 盘读取比硬盘慢
- USB 3.0 U 盘 + USB 3.0 接口会快很多
- 首次加载约 1-3 分钟
使用阶段
-
Wi-Fi 连接
- Ubuntu 24.04 支持大多数 Wi-Fi 芯片
- 不行的话用手机 USB 共享网络，或 USB 无线网卡
-
OpenClaw 安装需要网络
- 国内镜像优先，无需翻墙
- 安装过程约 1-2 分钟
-
端口冲突
- OpenClaw 使用端口 18789-18799
- 提示端口占用 → 关闭终端窗口再重新打开
-
数据位置
- 安装目录：
/opt/u-claw/ - 配置文件：
/opt/u-claw/data/.openclaw/openclaw.json - 所有数据保存在持久化镜像中，重启不丢
- 安装目录：
-
性能预期
- 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 - 完整的问题排查步骤和解决方案