zhenghy/u-claw
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
45026b9d35a1c1255116588f5c631be17d6c152e
u-claw/README.zh-CN.md
zheng b076815171
Some checks failed
Tests / test (push) Has been cancelled
Details
feat: 海外化改造（新加坡市场）—— 阶段 0-3 
按 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

313 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<p align="center">
<img src="assets/readme/hero.svg" alt="U-Claw：随身携带的 AI 工作空间" width="100%" />
</p>
<h1 align="center">U-Claw（虾盘）</h1>
<p align="center"><strong>把 AI 工作空间装进 U 盘：插上任意电脑，配置、记忆和工具都跟着走。</strong></p>
<p align="center">
<a href="https://gitea.fanghe.it.com/zhenghy/u-claw/releases">下载便携版</a> ·
<a href="https://u-claw.org/tutorial.html">完整教程</a> ·
<a href="#快速开始制作便携版-u-盘">从源码制作</a> ·
<a href="README.md">English</a>
</p>
<p align="center">
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1f7a8c?style=flat-square" alt="MIT License" /></a>
<img src="https://img.shields.io/badge/Portable-USB%20first-123343?style=flat-square" alt="USB first" />
<img src="https://img.shields.io/badge/Runtime-OpenClaw-48d1c1?style=flat-square" alt="OpenClaw runtime" />
</p>
> [!IMPORTANT]
> 这不是 U 盘制作工具。这个仓库就是 U 盘的文件骨架：运行一次 `setup.sh` 补齐运行时，再把整个 `portable/` 拷到盘里即可。
## 三步开始
1. 从 [Releases](https://gitea.fanghe.it.com/zhenghy/u-claw/releases) 下载 Windows 便携版，解压到 U 盘后双击 `START HERE - Windows.bat`。
2. 或克隆仓库，在 `portable/` 运行 `bash setup.sh`，下载 Node.js 与 OpenClaw。
3. 首次启动在本地配置模型 Key；配置只保存在 U 盘的 `data/.openclaw/openclaw.json`。
| 你得到什么 | 为什么重要 |
| --- | --- |
| 随身 AI 工作空间 | 换电脑时带走配置、记忆与工具，不在主机残留用户数据。 |
| 本地优先 | 不绑定设备、不打指纹、不上传本地配置。 |
| 多种使用方式 | 便携 U 盘、在线一键安装、可启动 Linux U 盘各自独立。 |
> [!TIP]
> ### 👑 同作者新品：U-King · AI 装机管家
> 一键装好 **Claude Code / Codex / OpenClaw / Hermes** 四大 AI 神器，驱动自动配好——一个 Key 直用 Claude、GPT、DeepSeek、Kimi 等 24+ 全球模型，免翻墙。绿色版仅几 MB，双击即用，还带 AI 作图 / 视频 / 本地大模型 / 多终端工作台。
>
> **免费下载：[www.u-king.org](https://www.u-king.org)**（国内镜像 [cloud.u-claw.org/uking](https://cloud.u-claw.org/uking/)）
>
> *U-Claw 让 AI 住进 U 盘；U-King 帮你把全套 AI 编程神器装进电脑。*
> *EN: U-King — one-click installer for Claude Code / Codex / OpenClaw, with one API key for 24+ global models → [u-king.org](https://www.u-king.org)*
---
<a id="中文"></a>
## 中文
### 这是什么
U-Claw（虾盘）是一个**制作教程 + 全套源代码**，教你把 [OpenClaw](https://github.com/openclaw/openclaw)（开源 AI 助手框架）做成 U 盘——插上任意电脑，双击就能用 AI。为什么叫虾盘？U-Claw = USB + Claw（虾钳），U 盘 + AI = 虾盘。
代码库本身就是 U 盘的文件骨架，运行 `setup.sh` 补齐大依赖后，整个 `portable/` 目录直接拷贝到 U 盘即可。
> 📖 **[完整教程](https://u-claw.org/tutorial.html)** — 从零开始的手工安装指南、模型配置、聊天平台接入，小白也能看懂。
### 🧩 模型随便选：国内外大模型都能用
U-Claw 是纯开源工具，**不绑定设备、不打指纹、不上传任何数据**。首次启动会自动打开 Config 页面，选一个模型、填入自己的 API Key 即可一键启动：
- **虾盘云（首选 · 中转站）**：一个 Key 调用 DeepSeek / Claude / GPT / 通义 等国内外全部大模型，无需翻墙。注册并充值：[u-claw.org/cloud.html](https://u-claw.org/cloud.html)
- **各家官方 Key 也行**：DeepSeek、通义千问、Kimi、智谱 GLM、豆包、MiniMax（国内）/ OpenAI、Claude、Groq（国外）/ 硅基流动、任意 OpenAI 兼容地址（自定义）
- **配置只存在本地** `data/.openclaw/openclaw.json`，拔盘不留痕
### 一键安装（推荐）
不需要 U 盘，一行命令直接装到电脑：
```bash
# Mac / Linux
curl -fsSL https://u-claw.org/install.sh | bash
# Windows (PowerShell 管理员)
irm https://u-claw.org/install.ps1 | iex
```
自动完成: Node.js 下载 → OpenClaw 安装 → 10 个中国技能 → 模型配置 → 启动脚本生成。全程国内镜像，无需翻墙。
详见 [`install/README.md`](install/README.md)。
### 快速开始：制作便携版 U 盘
```bash
# 1. 克隆代码
git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
# 2. 补齐大依赖（Node.js + OpenClaw，国内镜像，约 1 分钟）
cd u-claw/portable/advanced && bash setup.sh
# 3. 拷贝到 U 盘
cp -R portable/ /Volumes/你的U盘/U-Claw/ # Mac
# 或 Windows 资源管理器直接拖过去
```
**完成！** 插上 U 盘，双击启动脚本就能用。
### U 盘功能一览
| 功能 | Mac | Windows |
|------|-----|---------|
| **免安装运行** | `START HERE - Mac.command` | `START HERE - Windows.bat` |
| **功能菜单** | `Mac-Menu.command` | `Windows-Menu.bat` |
| **安装到电脑** | `Mac-Install.command` | `Windows-Install.bat` |
| **首次配置** | `Config.html` | `Config.html` |
### U 盘文件结构
```
U-Claw/ ← 整个拷到 U 盘
├── START HERE - Mac.command Mac 免安装运行
├── Mac-Menu.command Mac 功能菜单
├── Mac-Install.command 安装到 Mac
├── START HERE - Windows.bat Windows 免安装运行
├── Windows-Menu.bat Windows 功能菜单
├── Windows-Install.bat 安装到 Windows
├── Config.html 首次配置页面
├── setup.sh 补齐依赖（开发者用）
├── app/ ← 大依赖（setup.sh 下载，不进 git）
│ ├── core/ OpenClaw + QQ 插件
│ └── runtime/
│ ├── node-mac-arm64/ Mac Apple Silicon
│ ├── node-mac-x64/ Mac Intel
│ └── node-win-x64/ Windows 64-bit
└── data/ ← 用户数据（不进 git）
├── .openclaw/ 配置文件
├── memory/ AI 记忆
└── backups/ 备份
```
### Linux 可启动版
连操作系统都没有？没关系。可启动版可以让任意电脑从 U 盘直接启动 Ubuntu + AI：
- 本仓库内：[`bootable/`](bootable/) 目录（与其他模块完全独立，互不影响）
- 独立仓库：[u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux)（内容一致，方便单独克隆）
基于 Ventoy + Ubuntu 24.04 LTS + 持久化存储，在 Windows 上运行 4 步 PowerShell 脚本即可制作。详见 [`bootable/README.md`](bootable/README.md)。
> **关于桌面安装版（Electron）**：`u-claw-app/` 的 Electron 桌面版（`.exe` 安装版 / 绿色版 / `.dmg`）**已于 2026-06-19 停止发布并归档**，原因见 [`u-claw-app/DEPRECATED.md`](u-claw-app/DEPRECATED.md)。U-Claw 现在只发布「便携 U 盘版」——这才是产品的本质：插上 U 盘、解压即用。
### 直接下载发行版
[GitHub Releases](https://gitea.fanghe.it.com/zhenghy/u-claw/releases) 提供便携 U 盘版：
- `u-claw-portable-windows-vX.Y.Z.zip` — Windows 便携完整版（已预装 Node + OpenClaw，**解压到 U 盘双击 `START HERE - Windows.bat` 即用**）
- **Mac**：源码在 [`portable/`](portable/) 目录，`bash setup.sh` 自动下载 Node + OpenClaw（国内镜像约 1 分钟），双击 `START HERE - Mac.command` 启动
> ⚠️ **U 盘请用 NTFS 格式**（不要 exFAT/FAT32）：Node.js 在 exFAT 上 IO 极慢且不支持符号链接，可能导致启动失败。
### 支持的 AI 模型
**国产模型（无需翻墙）：**
| 模型 | 推荐场景 |
|------|----------|
| DeepSeek | 编程首选，极便宜 |
| Kimi K2.5 | 长文档，256K 上下文 |
| 通义千问 Qwen | 免费额度大 |
| 智谱 GLM | 学术场景 |
| MiniMax | 语音多模态 |
| 豆包 Doubao | 火山引擎 |
**国际模型：** Claude · GPT · Gemini（需翻墙或中转）
### 支持的聊天平台
| 平台 | 状态 | 说明 |
|------|------|------|
| QQ | ✅ 已预装 | 输入 AppID + Secret 即可 |
| 飞书 | ✅ 内置 | 企业首选 |
| Telegram | ✅ 内置 | 海外推荐 |
| WhatsApp | ✅ 内置 | Baileys 协议 |
| Discord | ✅ 内置 | — |
| 微信 | ✅ 社区插件 | iPad 协议 |
### 国内镜像
所有脚本默认走国内镜像，无需翻墙：
| 资源 | 镜像 |
|------|------|
| npm 包 | `registry.npmmirror.com` |
| Node.js | `npmmirror.com/mirrors/node` |
| Electron | `npmmirror.com/mirrors/electron` |
### 开发 & 贡献
```bash
git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
cd u-claw/portable/advanced && bash setup.sh
bash "START HERE - Mac.command" # Mac 测试
```
**平台支持：**
| 平台 | 状态 | 说明 |
|------|------|------|
| Mac Apple Silicon (M1-M4) | ✅ | 便携版 |
| Mac Intel (x64) | ✅ | 便携版 |
| Windows x64 | 🚧 开发中 | 便携版 |
| Linux x64（可启动 U 盘） | ✅ | [`bootable/`](bootable/) 目录 |
欢迎 PR！特别需要：Windows 脚本完善、教程翻译。
### 🦞 寻找技术伙伴
U-Claw 是一个快速成长的开源项目，目前已有不少商业合作机会。
我们正在寻找：
- **技术伙伴** — 全栈 / Node.js / Electron / 脚本自动化
- **资源合作** — 渠道、内容、社区运营
如果你对 AI 工具的落地和商业化感兴趣，欢迎联系：
- 微信: hecare888
- Telegram: [@dsds8848](https://t.me/dsds8848)
- Twitter/X: [@Bitplus888](https://x.com/Bitplus888)
- Email: [hefangsheng@gmail.com](mailto:hefangsheng@gmail.com)
- GitHub: [@dongsheng123132](https://github.com/dongsheng123132)
- 官网: [u-claw.org](https://u-claw.org)
### FAQ
**Q: 需要翻墙吗？**
不需要。安装和运行全程使用国内镜像，国产模型 API 直连。
**Q: U 盘需要多大？**
4GB+（完整约 2.3GB）。
**Q: 能分发吗？**
MIT 协议，随便复制分发。
**Q: Mac 提示"未验证的开发者"？**
右键脚本 → 打开。
**Q: setup.bat / setup.sh 执行失败，提示模块找不到？**
通常是 npm install 过程中网络中断导致 `node_modules` 不完整。解决步骤：
1. 删除不完整的依赖：`rmdir /s /q portable\app\core\node_modules`（Windows）或 `rm -rf portable/app/core/node_modules`（Mac）
2. 切换淘宝镜像重新安装：`cd portable/app/core && npm install --registry=https://registry.npmmirror.com`
**Q: 系统已有 Node.js v24，安装失败？**
Node.js v24 是最新开发版，部分依赖尚不兼容。需要 **v20 或 v22 LTS**。删除已下载的 runtime 目录后重新运行 setup，它会自动下载内置的 Node v22：
```bash
# Windows
rmdir /s /q portable\app\runtime\node-win-x64
setup.bat
# Mac
rm -rf portable/app/runtime/node-mac-arm64
bash setup.sh
```
**Q: Mac 上提示 `.toSorted is not a function`？**
系统旧版 Node.js 被检测到并跳过了内置版本下载，但旧版 Node 不支持 `.toSorted()`（需要 v20+）。删除 runtime 目录让脚本重新下载内置 Node v22：
```bash
rm -rf portable/app/runtime/node-mac-arm64
bash setup.sh
```
**Q: 如何同时配置多个 AI 模型并切换？**
支持同时配置多个 provider！打开 `Config.html` → 在 Providers 区域点击「添加」，逐个填入各模型的 API Key 和地址（如 DeepSeek、Kimi、通义等）→ 保存后，在聊天界面左上角下拉菜单随时切换。配置持久保存在 U 盘上。
**Q: U 盘安装后无法创建文件 / 写入失败？**
两种可能：① U 盘侧面有物理写保护开关，拨到解锁位置；② U 盘格式不兼容，建议格式化为 **exFAT**（Mac/Windows/Linux 三端均支持读写）。
**Q: 从 Ubuntu 向 U 盘复制时符号链接丢失？**
`node_modules/.bin/` 下有大量符号链接，FAT32/exFAT 在直接 `cp -R` 时会跳过。用 `rsync -aL` 可将符号链接展开为真实文件：
```bash
rsync -aL --progress portable/ /media/YOUR_USB/U-Claw/
```
**Q: QQbot 报错 `Unknown channel: qqbot`？**
Bundle 里的 `@sliverp/qqbot` 是未编译的 TypeScript 源码，需要先编译：
```bash
cd portable/app/core/node_modules/@sliverp/qqbot
npm install && npm run build
```
正式 Release 包已修复此问题，建议从 [Releases](https://gitea.fanghe.it.com/zhenghy/u-claw/releases) 下载最新版。
### 联系 & 合作
<img src="assets/wechat-qr.jpg" width="220" alt="微信二维码 — 贺去病 ai 工作室" align="right" />
- 微信: hecare888（或扫右侧二维码）
- Telegram: [@dsds8848](https://t.me/dsds8848)
- Twitter/X: [@Bitplus888](https://x.com/Bitplus888)
- Email: [hefangsheng@gmail.com](mailto:hefangsheng@gmail.com)
- GitHub: [@dongsheng123132](https://github.com/dongsheng123132)
- 官网: [u-claw.org](https://u-claw.org)
**🤝 招募代理 / 带货合作**
虾盘 3.0 体验极佳，退货率极低，售后由我们负责——你只管卖货：
- **抖店 / 直播带货**：提供最高佣金比例，产品已在多个直播间验证转化
- **代理分销**：买断或按单分润均可谈，支持定制版本
- **技术合作**：有开发能力者欢迎深度合作
- **👑 U-King 装机管家分销（新）**：[U-King](https://www.u-king.org) 软件本身免费送客户，客户按用量给 AI 模型 API 充值，你拿**持续分润**——不压货、零售后（我们负责），赚的是长期流水。适合装机店、AI 培训、社群主理人
有意向请微信联系（备注「代理合作」优先处理）。
---
<a id="english"></a>
---
<p align="center"><a href="README.md">English</a> · <strong>中文</strong></p>
Reference in New Issue View Git Blame Copy Permalink