Files

Tests / test (push) Has been cancelled

Details

按 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 拆到私有仓库，无权限

2026-08-17 18:37:49 +08:00

5.1 KiB

Raw Blame History

U-Claw Bootable USB 故障排除指南

常见问题与解决方案

1. Ventoy安装失败

问题: Ventoy安装时提示"Access Denied"或无法写入U盘 解决方案:

以管理员身份运行PowerShell
关闭所有可能占用U盘的程序（文件资源管理器、杀毒软件等）
尝试使用Ventoy的"只读模式"安装
如果U盘有写保护开关，请关闭它

2. Ubuntu ISO下载缓慢或失败

问题: 下载Ubuntu ISO时速度慢或中断 解决方案:

脚本会自动尝试多个国内镜像（清华、阿里、中科大）
如果全部失败，可以手动下载：
- 访问 https://mirrors.tuna.tsinghua.edu.cn/ubuntu-releases/24.04/
- 下载 ubuntu-24.04.4-desktop-amd64.iso
- 放到 bootable/.download-cache/ 目录
重新运行 2-download-iso.ps1

3. 持久化存储创建失败

问题: 3-create-persistence.ps1 提示磁盘空间不足 解决方案:

确保U盘至少有32GB空间
默认持久化大小为20GB，可以修改脚本中的 $PersistenceSizeGB 变量
最小建议值：8GB

4. Linux启动后无法进入桌面

问题: 从U盘启动后黑屏或卡住 解决方案:

启动时按 F6 或 Esc 进入引导选项
添加内核参数：
- nomodeset - 禁用显卡驱动
- quiet splash - 禁用启动画面
如果使用NVIDIA显卡，尝试 nouveau.modeset=0

5. OpenClaw安装失败

问题: setup-openclaw.sh 执行失败 解决方案:

网络问题:

# 测试网络连接
ping -c 3 npmmirror.com

# 如果网络有问题，使用代理
export http_proxy=http://your-proxy:port
export https_proxy=http://your-proxy:port

权限问题:

# 确保以root运行
sudo bash setup-openclaw.sh

依赖问题:

# 手动安装依赖
sudo apt-get update
sudo apt-get install curl xdg-utils

6. OpenClaw无法启动

问题: start-openclaw.sh 启动失败 解决方案:

检查Node.js:

/opt/u-claw/runtime/node-linux-x64/bin/node --version
# 应该显示 v22.14.0

检查OpenClaw安装:

ls -la /opt/u-claw/core/node_modules/openclaw/

端口冲突:

# 检查端口占用
ss -tlnp | grep :18789

# 如果端口被占用，手动指定端口
cd /opt/u-claw/core
node node_modules/openclaw/openclaw.mjs gateway run --port 18800

7. 浏览器无法打开

问题: 启动后浏览器没有自动打开 解决方案:

手动打开浏览器:
- 访问 http://localhost:18789
- 或 http://127.0.0.1:18789

检查防火墙:

# Ubuntu Live通常没有防火墙，但可以检查
sudo ufw status

8. 持久化数据丢失

问题: 重启后安装的软件或数据丢失 解决方案:

确保启动时选择了"Ubuntu (persistence)"选项

检查持久化文件大小:

ls -lh /media/ubuntu/persistence.dat
# 应该显示约20GB

如果持久化损坏，重新创建:

# 在Windows上重新运行 3-create-persistence.ps1

9. 性能问题

问题: 系统运行缓慢 解决方案:

使用USB 3.0接口（蓝色接口）

关闭不必要的特效:

# 安装gnome-tweaks调整性能
sudo apt-get install gnome-tweaks

增加swap空间（仅限持久化模式）:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

10. 硬件兼容性问题

问题: 某些硬件不工作（WiFi、蓝牙、声卡等） 解决方案:

更新内核（仅限持久化模式）:

sudo apt-get update
sudo apt-get install linux-generic-hwe-24.04

安装额外驱动:

# 检查可用驱动
ubuntu-drivers devices

# 安装推荐驱动
sudo ubuntu-drivers autoinstall

调试技巧

查看日志

# OpenClaw日志
tail -f /opt/u-claw/data/logs/openclaw.log

# 系统日志
dmesg | tail -20
journalctl -xe

测试网络

# 测试国内镜像
curl -I https://registry.npmmirror.com
curl -I https://npmmirror.com/mirrors/node

# 测试AI API
curl https://api.deepseek.com/health

检查磁盘使用

# 查看U盘使用情况
df -h /media/ubuntu

# 查看大文件
du -sh /opt/u-claw/*

紧急恢复

如果系统完全无法启动：

从其他电脑访问U盘:
- 在Windows/Mac上插入U盘
- 备份 u-claw-linux/ 目录下的重要数据
重新制作U盘:
- 格式化U盘
- 重新运行所有4个PowerShell脚本
寻求帮助:
- GitHub Issues: https://gitea.fanghe.it.com/zhenghy/u-claw/issues
- 微信: hecare888

性能优化建议

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

5.1 KiB Raw Blame History Unescape Escape