docs: 翻掉我上轮漏掉的三处,并修正发布说明里一条错误建议
Some checks failed
Tests / test (push) Has been cancelled

上一轮我说"剩余中文都合理",说得太满。这三处不合理:

1. bootable/linux-setup/test-installation.sh —— 在用户的 Linux 机器上跑的
   自检脚本,输出中英混杂(check "安装目录存在" ... "Directory $INSTALL_DIR")

2. issue / PR 模板 —— 贡献者第一眼看到的东西,而 CONTRIBUTING.md 已经是
   英文了。顺带修掉模板里指向上游官网和上游微信的链接(那些我们控制不了),
   改为指向本仓库。PR 模板加了一条"说明你在哪个平台跑过" —— 只在 Mac 上
   验证过的 .bat 改动一直是本项目最主要的故障来源。

3. release.yml 的发布说明正文 —— 那是用户在 release 页面读到的文字,内容
   还停留在旧产品(DeepSeek/通义、预装微信 QQ 钉钉飞书企微)。

第 3 项里还有一条**和事实相反**的建议:它让用户把 U 盘格式化成 NTFS。
macOS 对 NTFS 只读,照做正好会让"配置跟着盘走"这个核心卖点在 Mac 上
彻底失效。改为 exFAT,并说明为什么慢、以及我们如何用本机缓存补偿。

track-upstream.yml 的输入描述和输出也翻了 —— 它们会显示给手动触发
workflow 的人。
This commit is contained in:
2026-08-17 19:24:55 +08:00
parent 3221856d50
commit 45026b9d35
7 changed files with 175 additions and 149 deletions

View File

@@ -1,42 +1,42 @@
---
name: 🐛 Bug / 安装问题
about: 运行出错、安装失败、功能异常
name: 🐛 Something is broken
about: It errors, will not install, or behaves wrongly
title: "[Bug] "
labels: bug
assignees: ''
---
## 问题描述
## What happened
<!-- 简单描述遇到了什么问题 -->
<!-- One or two sentences. What did you expect, and what happened instead? -->
## 环境信息
## The error, as text
| 项目 | 填写 |
|------|------|
| 操作系统 | macOS / Windows 10 / Windows 11 |
| Node.js 版本 | `node -v` 的输出 |
| 使用方式 | 便携 U 盘版 / 一键安装版 / Electron 桌面版 / Linux 可启动版 |
| 出错步骤 | setup.bat / setup.sh / Windows-Start.bat / Mac-Start.command / 其他 |
<!--
Paste the actual output. Not a screenshot of it — nobody can search or copy
from a screenshot, and the useful part is usually the line that got cropped.
## 完整报错信息
<!-- 请完整贴出终端/命令行的报错,不要只截图 -->
If U-Claw failed to start, there is a report at:
data/.openclaw/diagnostics.txt
API keys are already stripped from it. Read it before attaching it.
-->
```
粘贴报错信息到这里
paste here
```
## 复现步骤
## Where
1.
2.
3.
- **OS and version**: <!-- macOS 14.5 / Windows 11 23H2 / Ubuntu 24.04 -->
- **Which build**: <!-- portable USB / one-line install / bootable USB -->
- **Version**: <!-- contents of OPENCLAW_VERSION, or the commit hash -->
## 已尝试的方法
## Steps to reproduce
<!-- 描述你试过哪些方法,避免重复建议 -->
1.
2.
3.
## 截图(可选)
## What you already tried
<!-- 如果有截图可以附上 -->
<!-- Saves everyone repeating it. -->

View File

@@ -1,11 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: 📖 完整教程
url: https://u-claw.org/tutorial.html
about: 从零开始的安装教程,含模型配置、平台接入
- name: 🔍 查看 FAQ
- name: 📖 Getting started
url: https://gitea.fanghe.it.com/zhenghy/u-claw#get-started
about: Three steps from plugging in the drive to talking to it.
- name: ❓ Common questions
url: https://gitea.fanghe.it.com/zhenghy/u-claw#faq
about: 常见问题解答,先看这里
- name: 💬 联系作者(微信)
url: https://u-claw.org/guide.html#remote-support
about: 远程协助安装,微信 hecare888
about: Where settings live, offline use, which file system to use.
- name: 🔒 Security
url: https://gitea.fanghe.it.com/zhenghy/u-claw/src/branch/main/SECURITY.md
about: Found a vulnerability? Read this before opening a public issue.

View File

@@ -1,23 +1,29 @@
---
name: 💡 功能建议
about: 建议新功能或改进现有功能
name: 💡 Suggest something
about: A new capability, or a change to an existing one
title: "[Feature] "
labels: enhancement
assignees: ''
---
## 建议描述
## What are you trying to do
<!-- 你希望增加什么功能?解决什么问题? -->
<!--
The situation first, the feature second.
## 使用场景
"I'd like X" is hard to act on. "I'm doing Y, I need X, because Z" can be
discussed — and quite often there is already a way to do Y that we can point
you at, or a better X than the one either of us thought of.
-->
<!-- 在什么情况下会用到这个功能? -->
## What is in the way now
## 期望的效果
<!-- How do you handle it today, and what does that cost you? -->
<!-- 描述理想的使用方式或界面 -->
## What you have in mind
## 补充信息
<!-- Optional. If you have a shape in mind, describe it. -->
<!-- 其他相关背景、截图、参考项目等 -->
## Anything else
<!-- Related tools that do this well, screenshots, links. -->

View File

@@ -1,51 +1,53 @@
<!--
感谢贡献 U-Claw请按以下模板填写方便维护者审阅。
空白或仅有标题的 PR 通常会被关闭,请勿提交无说明的改动。
Thanks for sending this.
A PR with a title and no description usually gets closed — not out of
strictness, but because nobody can tell whether it is safe to merge.
-->
## 改动类型 / Type
## What this changes
<!-- 勾选适用的([x] -->
<!-- One or two sentences. What is different afterwards? -->
- [ ] 🐛 Bug 修复
- [ ] ✨ 新功能
- [ ] 📝 文档/README
- [ ] 🔧 脚本/构建portable, install, bootable, u-claw-app
- [ ] 🎨 技能 (skills/)
- [ ] ♻️ 重构(不改变行为)
- [ ] 🧪 测试
## Why
## 改动了什么 / What
<!-- The problem it solves. Link an issue if there is one. -->
<!-- 一两句话说清楚这个 PR 做了什么。不要复制 git diff。 -->
## Type
## 为什么 / Why
- [ ] 🐛 Fix
- [ ] ✨ New capability
- [ ] 📝 Docs
- [ ] 🎨 Skill content (`skills/`)
- [ ] ♻️ Refactor — no behaviour change
- [ ] 🔧 Build, CI or tooling
<!-- 哪个 issue / 哪个使用场景驱动了这次改动?关联 issue: #xxx -->
## Which builds this touches
## 测试方式 / How to verify
- [ ] `portable/` — the USB build
- [ ] `install/` — one-line install
- [ ] `bootable/` — Linux USB
- [ ] Shared (`lib/`, `skills/`, tests)
## How you tested it
<!--
告诉维护者怎么验证。比如:
- 在 macOS Apple Silicon 上跑 `bash install/install.sh`,安装成功
- 双击 `portable/Mac-Start.command`,能正常打开 dashboard
- Windows 11 PowerShell 跑 `irm https://u-claw.org/install.ps1 | iex`,安装成功
Not decoration. Say what you actually ran.
node --test # NOT `node --test tests/` — that runs nothing
And for anything touching a launcher or an installer, say which platform you
ran it on. A change to a .bat verified only on a Mac is worth saying so about —
that has been the main source of breakage here.
-->
## 影响范围 / Scope
- [ ] `node --test` passes
- [ ] Ran it on: <!-- macOS / Windows / Linux -->
<!-- 勾选受影响的模块 -->
## Checklist
- [ ] portable/ (便携 USB)
- [ ] u-claw-app/ (Electron 桌面)
- [ ] bootable/ (Linux 可启动 U 盘)
- [ ] install/ (一键安装脚本)
- [ ] skills/ (技能内容与 manifest)
- [ ] 仅文档
## 自检 / Checklist
- [ ] 我已经在本地实际跑过相关脚本/功能
- [ ] 没有提交 `node_modules/``app/``data/` 等运行时产物
- [ ] 没有把任何 API Key、Token 写进文件
- [ ] commit message 能说清楚改了什么
- [ ] No `node_modules/`, `app/`, `data/`, `*.dmg`, `*.exe` in the diff
- [ ] No API keys, tokens or passwords in any file
- [ ] User-facing text is in `lib/messages/*.json`, not hardcoded in a script
- [ ] `.bat` files stay pure ASCII with CRLF; `.command` files stay LF-only
- [ ] Unrelated files are not reformatted

View File

@@ -119,7 +119,7 @@ jobs:
--registry="$mirror_npm" \
--ignore-scripts \
--no-audit \
--no-fund || echo "WARN: $cn_pkg install failed, skipping (便携版仍可用其它渠道)"
--no-fund || echo "WARN: $cn_pkg install failed, skipping — the drive still works with the other channels"
done
# 6) Install skills from the manifest.
@@ -256,18 +256,36 @@ jobs:
body: |
## U-Claw ${{ steps.tag.outputs.tag }}
- 打开 Config 选模型、填入自己的 API Key 即可使用,支持 DeepSeek / 通义 / Claude / GPT 等国内外大模型
- 想用「虾盘云」中转站(一个 Key 调用国内外全部模型、免翻墙):先到 https://cloud.u-claw.org 注册并创建 Key
- **聊天渠道开箱即用**:便携版已离线预装 微信 / QQ / 钉钉 / 飞书 / 企业微信 插件,无需自己 npm 安装
An AI assistant on a USB drive. Plug it into any Mac or Windows
machine — no installer, no admin rights, nothing left behind.
- Paste one API key and you are running. U-Claw works out the
provider from the key itself and checks it before accepting it.
- Your settings, keys and memory live on the drive, so they travel
with you between machines.
- OpenClaw runtime: `${{ steps.openclaw_version.outputs.version }}`
### 下载
### Downloads
- **Windows 便携完整版U 盘版)**`u-claw-portable-windows-*.zip`(约 150-200 MB,已预装 Node.js + OpenClaw**解压即用,零网络依赖**)。解压到 U 盘后双击 `START HERE - Windows.bat` 启动。
- **macOS 便携版**:源码在 `portable/` 目录,`bash setup.sh` 自动下载 Node + OpenClaw约 1 分钟),双击 `START HERE - Mac.command` 启动。
- **Windows** — `u-claw-portable-windows-*.zip`, roughly 150200 MB
with Node.js and OpenClaw already inside. Unzip onto the drive and
double-click `START HERE - Windows.bat`. No network needed to start.
- **macOS** — clone the repo, run `bash portable/advanced/setup.sh`
(about a minute to fetch Node and OpenClaw), then double-click
`START HERE - Mac.command`.
Each asset has a `.sha256` next to it. Check it before you run it.
### Format the drive as exFAT
Not NTFS. **macOS can only read NTFS, not write to it**, so an
NTFS drive silently breaks the one thing this product is for —
your settings will not follow you to a Mac.
exFAT is slower with many small files, which is why U-Claw moves its
rebuildable caches onto the host's local disk at startup. Your actual
data stays on the drive.
> **U 盘格式建议**:请用 **NTFS** 格式化 U 盘NOT exFAT/FAT32。Node.js 在 exFAT 上 IO 极慢且不支持符号链接,可能导致启动失败。
> Windows 下右键 U 盘 → 格式化 → 文件系统选择 NTFS。
files: |
artifacts/portable-windows-full/*
fail_on_unmatched_files: false

View File

@@ -22,11 +22,11 @@ on:
workflow_dispatch:
inputs:
force_version:
description: '强制使用的上游 OpenClaw 版本(留空=用 npm latest'
description: 'Pin a specific upstream OpenClaw version (blank = whatever npm says is latest)'
required: false
default: ''
dry_run:
description: '只检测不改动(true/false'
description: 'Check only, change nothing (true/false)'
required: false
default: 'false'
@@ -58,13 +58,13 @@ jobs:
force="${{ github.event.inputs.force_version }}"
if [ -n "$force" ]; then
latest="${force#v}"
echo "强制指定上游版本: $latest"
echo "Forced upstream version: $latest"
else
latest="$(npm view openclaw version --registry=https://registry.npmjs.org 2>/dev/null | tr -d '[:space:]')"
echo "npm latest openclaw: $latest"
fi
if [ -z "$latest" ]; then
echo "::error::无法获取上游 openclaw 版本(npm view 失败)"
echo "::error::Could not read the upstream openclaw version — npm view failed"
exit 1
fi
echo "latest=$latest" >> "$GITHUB_OUTPUT"
@@ -76,7 +76,7 @@ jobs:
shell_ver="$(node -p "require('./u-claw-app/package.json').version")"
echo "pinned=$pinned" >> "$GITHUB_OUTPUT"
echo "shell_ver=$shell_ver" >> "$GITHUB_OUTPUT"
echo "当前 pin: $pinned | 壳版本: $shell_ver"
echo "Currently pinned: $pinned | shell version: $shell_ver"
- name: Decide whether to bump
id: decide
@@ -84,18 +84,18 @@ jobs:
latest="${{ steps.upstream.outputs.latest }}"
pinned="${{ steps.current.outputs.pinned }}"
if [ "$latest" = "$pinned" ]; then
echo "✅ 已是最新pin=$pinned无需发版。"
echo "Already up to date (pinned=$pinned) — nothing to release."
echo "changed=false" >> "$GITHUB_OUTPUT"
exit 0
fi
# 只在 latest 严格 > pinned 时发版(避免上游撤版导致回退)
newer="$(printf '%s\n%s\n' "$pinned" "$latest" | sort -V | tail -1)"
if [ "$newer" != "$latest" ]; then
echo "⚠️ npm latest ($latest) 不比当前 pin ($pinned) 新,跳过。"
echo "npm latest ($latest) is not newer than the pin ($pinned) — skipping."
echo "changed=false" >> "$GITHUB_OUTPUT"
exit 0
fi
echo "🆕 发现上游新版: $pinned $latest"
echo "Upstream has moved: $pinned -> $latest"
echo "changed=true" >> "$GITHUB_OUTPUT"
- name: Compute next shell version (patch bump)
@@ -106,7 +106,7 @@ jobs:
IFS='.' read -r MA MI PA <<< "$cur"
PA=$((PA + 1))
next="${MA}.${MI}.${PA}"
echo "壳版本 bump: $cur $next"
echo "Bumping shell version: $cur -> $next"
echo "next=$next" >> "$GITHUB_OUTPUT"
- name: Apply changes (pin + version files)
@@ -123,7 +123,7 @@ jobs:
# 这里写一份让 main 分支也保持一致。
node -e "const f='u-claw-app/package.json';const p=require('./'+f);p.version='$next';require('fs').writeFileSync(f, JSON.stringify(p,null,2)+'\n')"
echo "已写入: OPENCLAW_VERSION=$latest, 壳版本=$next"
echo "Wrote OPENCLAW_VERSION=$latest, shell version=$next"
- name: Commit, tag & push
if: steps.decide.outputs.changed == 'true' && github.event.inputs.dry_run != 'true'
@@ -135,10 +135,10 @@ jobs:
git config user.email "bot@u-claw.org"
git add OPENCLAW_VERSION portable/OPENCLAW_VERSION u-claw-app/package.json
git commit -m "chore(upstream): 跟随 OpenClaw $latest,发布 v$next
git commit -m "chore(upstream): follow OpenClaw $latest, release v$next
自动跟踪上游OpenClaw npm latest 升到 $latest
自动 bump 壳版本到 $next 并打 tag 触发发版。"
Automated: upstream OpenClaw moved to $latest, so the shell version
is bumped to $next and tagged, which triggers a release."
git push origin HEAD:main
@@ -146,10 +146,10 @@ jobs:
git tag "v$next"
git push origin "v$next"
echo "✅ 已推送 v$nextrelease.yml 将自动构建并发布。"
echo "Pushed v$nextrelease.yml will build and publish it."
- name: Dry-run summary
if: steps.decide.outputs.changed == 'true' && github.event.inputs.dry_run == 'true'
run: |
echo "🔍 DRY RUN — 不改动。"
echo "若执行将:OPENCLAW_VERSION ${{ steps.current.outputs.pinned }} ${{ steps.upstream.outputs.latest }},发布 v${{ steps.nextver.outputs.next }}"
echo "DRY RUN — nothing changed."
echo "Would set OPENCLAW_VERSION ${{ steps.current.outputs.pinned }} -> ${{ steps.upstream.outputs.latest }} and release v${{ steps.nextver.outputs.next }}"

View File

@@ -46,128 +46,128 @@ warn() {
((WARNINGS++))
}
echo "1. 检查基本目录结构..."
check "安装目录存在" "[ -d '$INSTALL_DIR' ]" "Directory $INSTALL_DIR"
check "runtime目录" "[ -d '$INSTALL_DIR/runtime' ]" "Runtime directory"
check "core目录" "[ -d '$INSTALL_DIR/core' ]" "Core directory"
check "data目录" "[ -d '$INSTALL_DIR/data' ]" "Data directory"
echo "1. Folder layout"
check "install directory" "[ -d '$INSTALL_DIR' ]" "Directory $INSTALL_DIR"
check "runtime/" "[ -d '$INSTALL_DIR/runtime' ]" "Runtime directory"
check "core/" "[ -d '$INSTALL_DIR/core' ]" "Core directory"
check "data/" "[ -d '$INSTALL_DIR/data' ]" "Data directory"
echo ""
echo "2. 检查Node.js安装..."
echo "2. Node.js"
NODE_BIN="$INSTALL_DIR/runtime/node-linux-x64/bin/node"
if [ -x "$NODE_BIN" ]; then
NODE_VERSION=$("$NODE_BIN" --version 2>/dev/null || echo "")
echo -e " Node.js版本: ${GREEN}$NODE_VERSION${NC}"
echo -e "[OK] Node.js ${GREEN}$NODE_VERSION${NC}"
if [ "$NODE_VERSION" != "v22.22.1" ]; then
warn "Node.js版本" "Expected v22.22.1, found $NODE_VERSION"
warn "Node.js version" "Expected v22.22.1, found $NODE_VERSION"
fi
else
echo -e "${RED} Node.js未找到或不可执行${NC}"
echo -e "${RED}[!!] Node.js is missing or will not run${NC}"
((ERRORS++))
fi
echo ""
echo "3. 检查OpenClaw安装..."
echo "3. OpenClaw"
if [ -d "$INSTALL_DIR/core/node_modules/openclaw" ]; then
echo -e " OpenClaw已安装"
echo -e "[OK] OpenClaw is installed"
# 检查主要文件
OPENCLAW_ENTRY=$(find "$INSTALL_DIR/core/node_modules/openclaw" -name "openclaw.mjs" -maxdepth 2 2>/dev/null | head -1)
if [ -n "$OPENCLAW_ENTRY" ]; then
echo -e "✓ OpenClaw入口文件: ${GREEN}$OPENCLAW_ENTRY${NC}"
echo -e "[OK] entry point: ${GREEN}$OPENCLAW_ENTRY${NC}"
else
echo -e "${RED}✗ 未找到openclaw.mjs${NC}"
echo -e "${RED}[!!] openclaw.mjs not found${NC}"
((ERRORS++))
fi
else
echo -e "${RED} OpenClaw未安装${NC}"
echo -e "${RED}[!!] OpenClaw is not installed${NC}"
((ERRORS++))
fi
echo ""
echo "4. 检查配置文件..."
echo "4. Configuration"
CONFIG_FILE="$INSTALL_DIR/data/.openclaw/openclaw.json"
if [ -f "$CONFIG_FILE" ]; then
echo -e "✓ 配置文件存在"
echo -e "[OK] config file present"
# 检查配置格式
if python3 -m json.tool "$CONFIG_FILE" >/dev/null 2>&1; then
echo -e "✓ 配置文件格式正确"
echo -e "[OK] config parses"
else
warn "配置文件" "JSON格式可能有问题"
warn "config file" "may not be valid JSON"
fi
else
echo -e "${YELLOW}⚠ 配置文件不存在(首次运行正常)${NC}"
echo -e "${YELLOW}[ ?] no config file yet — normal before the first run${NC}"
((WARNINGS++))
fi
echo ""
echo "5. 检查启动脚本..."
echo "5. Launcher"
START_SCRIPT="$INSTALL_DIR/start-openclaw.sh"
if [ -x "$START_SCRIPT" ]; then
echo -e "✓ 启动脚本存在且可执行"
echo -e "[OK] start script present and executable"
else
if [ -f "$START_SCRIPT" ]; then
echo -e "${YELLOW}⚠ 启动脚本存在但不可执行${NC}"
chmod +x "$START_SCRIPT" 2>/dev/null && echo " 已添加执行权限"
echo -e "${YELLOW}[ ?] start script is present but not executable${NC}"
chmod +x "$START_SCRIPT" 2>/dev/null && echo " added the executable bit"
else
echo -e "${RED}✗ 启动脚本未找到${NC}"
echo -e "${RED}[!!] start script not found${NC}"
((ERRORS++))
fi
fi
echo ""
echo "6. 检查端口可用性..."
echo "6. Ports"
PORT_FOUND=false
for port in $(seq 18789 18799); do
if ! ss -tlnp 2>/dev/null | grep -q ":$port "; then
echo -e "✓ 端口 $port 可用"
echo -e "[OK] port $port is free"
PORT_FOUND=true
break
fi
done
if [ "$PORT_FOUND" = false ]; then
warn "端口" "所有端口18789-18799都被占用"
warn "ports" "18789-18799 are all in use — U-Claw may already be running"
fi
echo ""
echo "7. 检查桌面快捷方式..."
echo "7. Desktop shortcut"
if [ -f "$HOME/Desktop/openclaw.desktop" ] || [ -f "$HOME/.local/share/applications/openclaw.desktop" ]; then
echo -e "✓ 桌面快捷方式已创建"
echo -e "[OK] shortcut created"
else
warn "桌面快捷方式" "未找到桌面快捷方式"
warn "desktop shortcut" "not found"
fi
echo ""
echo "============================================"
echo " 测试结果汇总"
echo " Results"
echo "============================================"
echo ""
if [ $ERRORS -eq 0 ]; then
echo -e "${GREEN}✅ 所有关键检查通过!${NC}"
echo " 安装看起来是成功的。"
echo -e "${GREEN}[OK] Everything essential checks out.${NC}"
echo " The install looks good."
echo ""
echo " 启动命令:"
echo " Start it with:"
echo " bash /opt/u-claw/start-openclaw.sh"
echo ""
echo " 或双击桌面上的 'U-Claw AI Assistant' 图标"
echo " Or double-click the U-Claw AI Assistant icon on the desktop."
else
echo -e "${RED}❌ 发现 $ERRORS 个错误${NC}"
echo " 请检查上述失败的项目。"
echo -e "${RED}[!!] $ERRORS problem(s) found${NC}"
echo " Look at the failed checks above."
echo ""
echo " 常见解决方案:"
echo " 1. 重新运行安装脚本:"
echo " Usually one of these:"
echo " 1. Run the install script again:"
echo " sudo bash /opt/u-claw/setup-openclaw.sh"
echo " 2. 检查网络连接"
echo " 3. 查看详细日志"
echo " 2. Check the network"
echo " 3. Read the log"
fi
if [ $WARNINGS -gt 0 ]; then
echo -e "${YELLOW}⚠ 有 $WARNINGS 个警告${NC}"
echo " 这些可能不会影响基本功能,但建议修复。"
echo -e "${YELLOW}[ ?] $WARNINGS warning(s)${NC}"
echo " These probably will not stop it working, but are worth fixing."
fi
echo ""
@@ -176,25 +176,25 @@ echo "============================================"
# 提供快速修复选项
if [ $ERRORS -gt 0 ]; then
echo ""
read -rp "是否尝试自动修复问题? (y/N): " FIX
read -rp "Try to fix these automatically? (y/N): " FIX
if [[ "$FIX" =~ ^[Yy]$ ]]; then
echo ""
echo "尝试修复..."
echo "Fixing…"
# 修复启动脚本权限
if [ -f "$START_SCRIPT" ] && [ ! -x "$START_SCRIPT" ]; then
echo " 修复启动脚本权限..."
echo " Restoring the start script permissions"
sudo chmod +x "$START_SCRIPT"
fi
# 重新安装OpenClaw
if [ ! -d "$INSTALL_DIR/core/node_modules/openclaw" ]; then
echo " 重新安装OpenClaw..."
echo " Reinstalling OpenClaw"
cd "$INSTALL_DIR/core"
sudo npm install --registry=https://registry.npmjs.org openclaw@latest 2>/dev/null || true
fi
echo ""
echo "修复完成。请重新运行此测试脚本。"
echo "Done. Run this check again to confirm."
fi
fi