From c0dbe3bc414627c260c005854e52a5751d575c6d Mon Sep 17 00:00:00 2001 From: dongsheng123132 <90887123+dongsheng123132@users.noreply.github.com> Date: Fri, 13 Mar 2026 17:33:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20=E7=BB=B4=E6=8A=A4=E4=B8=8E?= =?UTF-8?q?=E5=8D=B8=E8=BD=BD=20section=20to=20guide.html?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive maintenance & uninstall guide covering menu options 9-15: kill processes, view logs, factory reset, full uninstall (USB/Electron/npm), check updates, clean space, plugin management. Update FAQ with uninstall and improved update answers. --- website/guide.html | 503 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 499 insertions(+), 4 deletions(-) diff --git a/website/guide.html b/website/guide.html index f4c97cb..3354d84 100644 --- a/website/guide.html +++ b/website/guide.html @@ -41,6 +41,7 @@ pre code{background:none;padding:0} .card{background:var(--card);border:1px solid var(--border);border-radius:10px;padding:20px;margin:16px 0} .tip{border-left:4px solid var(--green);padding:12px 16px;margin:16px 0;background:rgba(74,222,128,.06);border-radius:0 8px 8px 0} .warn{border-left:4px solid var(--yellow);padding:12px 16px;margin:16px 0;background:rgba(250,204,21,.06);border-radius:0 8px 8px 0} +.danger{border-left:4px solid var(--red);padding:12px 16px;margin:16px 0;background:rgba(248,113,113,.06);border-radius:0 8px 8px 0} table{width:100%;border-collapse:collapse;margin:16px 0} th,td{text-align:left;padding:10px 12px;border-bottom:1px solid var(--border)} th{color:var(--cyan);font-weight:600} @@ -102,6 +103,8 @@ ul{padding-left:20px} 国内镜像源 首次配置向导 网页控制台 + Linux 启动盘模式 + 中国区原生安装教程 @@ -143,6 +146,7 @@ ul{padding-left:20px} 命令速查 环境变量 诊断修复 + 维护与卸载 @@ -191,7 +195,8 @@ ul{padding-left:20px}
2
双击启动脚本 -
系统双击打开
macOSMac-Start.command
WindowsWindows-Start.bat
+WindowsWindows-Start.bat +Linuxbash Linux-Start.sh
3
首次配置

浏览器自动打开 Config.html → 选择 AI 模型 → 填写 API Key

4
开始使用

控制台自动打开 http://127.0.0.1:18789

@@ -217,6 +222,7 @@ cd u-claw/u-claw-app && bash setup.sh 
# 便携版
 bash Mac-Start.command   # Mac
 Windows-Start.bat        # Windows
+bash Linux-Start.sh      # Linux
 
 # 桌面版
 npm run dev
@@ -236,6 +242,9 @@ npm run dev Mac-Menu.commandmacOS 功能菜单（8 项：配置、QQ、备份等） Windows-Start.batWindows 一键启动 Windows-Menu.batWindows 功能菜单 +Linux-Start.shLinux 一键启动（bash Linux-Start.sh） +Linux-Menu.shLinux 功能菜单（8 项：配置、QQ、备份等） +Linux-Install.sh安装到 Linux 电脑 Config.html首次配置页面（选模型、填 API Key） U-Claw.html导航首页 setup.sh开发者搭建脚本（自动下载运行时） @@ -247,14 +256,15 @@ npm run dev │ ├── core/ OpenClaw + 依赖 + QQ 插件 │ └── runtime/ │ ├── node-mac-arm64/ Mac Apple Silicon -│ └── node-win-x64/ Windows 64-bit +│ ├── node-win-x64/ Windows 64-bit +│ └── node-linux-x64/ Linux x86_64 ├── data/ ← 用户数据（配置、记忆、备份） │ ├── .openclaw/ openclaw.json 配置文件 │ ├── memory/ AI 记忆 │ └── backups/ 备份 └── [启动脚本和HTML页面] -
注意：目前支持 Mac Apple Silicon (M1-M4)。Windows 版开发中，Mac Intel 暂不支持。
+
注意：目前支持 Mac Apple Silicon (M1-M4) 和 Linux x86_64。Windows 版开发中，Mac Intel 暂不支持。
@@ -297,6 +307,15 @@ npm run build:win # Windows → release/U-Claw-x.x.x.exe（需在 Windows 适合临时电脑、公共电脑个人电脑长期使用 +

方法三：从 U 盘安装到 Linux

+
1
插入 U-Claw U 盘，打开终端
+
2
运行安装脚本： +
cd /media/$USER/你的U盘/U-Claw
+bash Linux-Install.sh
+

安装到 ~/.uclaw/，优先使用 U 盘离线资源，缺失时从国内镜像下载

+
+
3
启动：终端运行 bash ~/.uclaw/start.sh 或在应用菜单搜索 U-Claw
+
安全提醒：共享电脑、公司电脑建议用 U 盘便携模式，不要安装到电脑。
@@ -728,6 +747,166 @@ openclaw logs + +
+

维护与卸载

+

U-Claw 的菜单脚本（Mac-Menu / Linux-Menu / Windows-Menu）内置了完整的维护功能，选择对应编号即可操作。

+ +
启动方式：双击 Mac-Menu.command（macOS）、Linux-Menu.sh（Linux）或 Windows-Menu.bat（Windows），在菜单中选择 9-15 进入维护功能。
+ +

[9] 杀死残留进程

+
+

什么时候需要？

+ +

操作方式

+

在菜单中选择 9，脚本会自动查找并终止所有 OpenClaw 相关进程（node、gateway 等），然后释放端口。

+
提示：如果显示"没有找到残留进程"说明后台已经是干净的。
+
+ +

[10] 查看日志

+
+

三个子功能

+ +

日志文件位置

+
data/logs/gateway.log
+

每次启动（通过 Start 脚本）都会自动将网关输出捕获到此文件，方便排查问题。

+
+ +

[11] 恢复出厂设置

+
+

什么时候需要？

+ +

会做什么？

+
    +
  1. 自动备份当前配置到 data/backups/
    2. +
  2. 删除配置文件（openclaw.json）
    3. +
  3. 删除记忆和对话历史
    4. +
  4. 恢复为初始默认状态
    5. +
+
⚠️ 需要输入 RESET 确认！此操作会清除你的 API Key 配置和对话记录。虽然会自动备份，但请确认你真的需要重置。
+
+ +

[12] 完整卸载指南

+
卸载前请先备份：如果你有重要的对话记录或配置，先手动复制 data/ 目录到安全位置。
+ +
+

U 盘便携版卸载

+
1
关闭所有 U-Claw 窗口

确保浏览器中没有打开的 U-Claw 页面

+
2
杀死残留进程

运行菜单选项 9，或关闭终端窗口

+
3
安全弹出 U 盘

右键 U 盘 → 弹出（不要直接拔！）

+
4
完毕

所有数据都在 U 盘上，电脑无任何残留

+
注意：如果曾经用 Mac-Install.command 安装到电脑，还需要手动删除 ~/.uclaw/ 目录。
+
+ +
+

桌面安装版（Electron）卸载

+

macOS：

+
    +
  1. 将 U-Claw.app 从「应用程序」拖到废纸篓
    2. +
  2. 删除用户数据：
    3. +
+
rm -rf ~/Library/Application\ Support/U-Claw/
+ +

Windows：

+
    +
  1. 设置 → 应用 → 找到 U-Claw → 卸载
    2. +
  2. 删除用户数据：
    3. +
+
rd /s /q "%APPDATA%\U-Claw"
+ +

Linux：

+
    +
  1. 删除 .desktop 文件和应用目录
    2. +
  2. 删除用户数据：
    3. +
+
rm -rf ~/.config/U-Claw/
+
+ +
+

原生安装版（npm 全局安装）卸载

+
# 卸载 OpenClaw
+npm uninstall -g openclaw
+
+# 删除配置和数据
+rm -rf ~/.openclaw/
+
+ +
+

残留清理检查清单

+

卸载后如果想确认电脑上完全没有 U-Claw 的痕迹，检查以下目录是否还存在：

+ + + + + + + +
路径说明系统
~/.uclaw/从 U 盘安装到电脑的版本macOS / Linux
~/.openclaw/npm 全局安装的配置所有系统
~/Library/Application Support/U-Claw/Electron 桌面版数据macOS
%APPDATA%\U-Claw\Electron 桌面版数据Windows
~/.config/U-Claw/Electron 桌面版数据Linux
+
⚠️ 删除这些目录后，所有配置和对话记录将永久丢失，无法恢复。
+
+ +

[13] 检查更新

+
+

在菜单中选择 13，脚本会自动检查当前 OpenClaw 版本并与最新版对比。如果有新版本可用，会提示你是否立即更新。

+

手动更新（备用）

+
# U 盘便携版
+cd app/core && npm update openclaw
+
+# npm 全局安装版
+npm update -g openclaw
+
+# 查看当前版本
+openclaw --version
+
+ +

[14] 清理空间

+
+

在菜单中选择 14，脚本会扫描并清理以下内容：

+ +

手动清理路径

+
# npm 缓存
+npm cache clean --force
+
+# 日志
+rm -f data/logs/gateway.log
+
+# 备份
+rm -rf data/backups/
+
+ +

[15] 插件管理

+
+

在菜单中选择 15，可以查看已安装的插件、安装新插件或卸载不需要的插件。

+

命令行备用

+
# 查看已安装插件
+openclaw plugin list
+
+# 安装插件
+openclaw plugin install <插件名>
+
+# 卸载插件
+openclaw plugin uninstall <插件名>
+
推荐插件：QQ 渠道插件（@nicepkg/openclaw-plugin-qq）是国内用户最常用的插件。
+
+
+

常见问题

@@ -741,7 +920,9 @@ openclaw logs

Q: Windows 需要 WSL 吗？

不需要。自带 Windows 版 Node.js。

Q: 怎么更新？

-

U 盘模式：替换 openclaw/ 目录。安装模式：openclaw update

+

最简单的方式：运行菜单脚本（Mac-Menu / Linux-Menu / Windows-Menu）选择 [13] 检查更新，自动完成。手动方式：U 盘模式运行 cd app/core && npm update openclaw，安装模式运行 npm update -g openclaw。详见 维护与卸载 页面。

+

Q: 怎么完整卸载？

+

根据你的安装方式不同，卸载步骤也不同。U 盘便携版只需弹出 U 盘即可；桌面版和 npm 版需要额外删除配置目录。详见 维护与卸载 页面的完整卸载指南。

Q: 配置文件在哪？

U 盘：portable-home/.openclaw/openclaw.json
安装：~/.openclaw/openclaw.json

Q: 和原版 OpenClaw 的区别？

@@ -779,6 +960,320 @@ openclaw logs
开源贡献：欢迎提交 PR！特别需要：修复脚本、教程文档、聊天平台桥接、实用技能。
Fork → Branch → Commit → PR，详见 GitHub 仓库
+ +
+

Linux 启动盘模式

+

把整个 Linux 系统 + OpenClaw 刻到 U 盘，开机从 USB 启动直接进入 Linux 桌面 + AI 助手。

+ +
+

启动盘模式 vs 普通便携模式

+ + + + + + + +
普通便携模式Linux 启动盘模式
原理在已有系统上运行 U 盘里的脚本直接从 U 盘启动整个 Linux 系统
依赖需要电脑已有 macOS / Windows / Linux不依赖任何已安装系统
适用有系统的电脑，临时用无系统 / 不想碰原系统 / 专用 AI 工作站
U 盘大小4GB+64GB+ 推荐（系统 + 持久化 + OpenClaw）
速度取决于 U 盘读写必须 USB 3.0+（USB 2.0 会很卡）
+
+ +

准备材料

+ + + + + +
材料要求说明
U 盘64GB+ USB 3.0最低 32GB，推荐 64GB USB 3.0+（USB 2.0 太慢不推荐）
Linux Mint ISOCinnamon 版下载: 清华镜像 或 中科大镜像
Rufusv4.0+下载: rufus.ie（仅 Windows 制作启动盘用）
+
为什么选 Linux Mint？界面最接近 Windows，中文支持好，硬件兼容性强，适合新手。
+ +

制作启动盘步骤

+ +
1
打开 Rufus +

插入 U 盘，打开 Rufus，选择你的 U 盘设备

+
+ +
2
选择 ISO 镜像 +

点击"选择"，找到下载的 Linux Mint ISO 文件

+
+ +
3
关键设置 + + + + + +
选项设置
分区类型GPT（新电脑）或 MBR（老电脑）
目标系统UEFI（新电脑）或 BIOS（老电脑）
Persistent Partition Size8-16 GB（重要！这是持久化存储空间）
+
Persistent Storage 必须开启！否则重启后所有安装和配置都会丢失。Rufus 4.0+ 支持此功能。
+
+ +
4
开始制作 +

点击"开始"，等待完成（约 5-10 分钟）

+
+ +

BIOS/UEFI 设置 USB 启动

+ +
1
插入 U 盘，重启电脑
+ +
2
进入 BIOS 启动菜单 +

开机时连续按启动键（不同品牌不同）：

+ + + + + + + + + + +
品牌启动菜单键BIOS 设置键
联想 LenovoF12F2
戴尔 DellF12F2
惠普 HPF9F10
华硕 ASUSF8F2 / Del
宏碁 AcerF12F2
小米F12F2
华为F12F2
自组装F11 / F12Del
+
+ +
3
选择 USB 设备启动 +

在启动菜单中选择你的 U 盘（通常显示为 USB 或 U 盘品牌名）

+
+ +
Secure Boot 问题：如果无法从 USB 启动，进入 BIOS 设置关闭 Secure Boot。路径通常是 Security → Secure Boot → Disabled。
+ +

首次启动 Linux Mint

+ +
1
选择 "Start Linux Mint" +

启动菜单中选择第一项，等待进入桌面（约 1-2 分钟）

+
+ +
2
连接网络 +

点击右下角网络图标，连接 WiFi 或插入网线

+
+ +
3
设置中文（可选） +
# 打开终端 (Ctrl+Alt+T)
+sudo apt update
+sudo apt install -y language-pack-zh-hans fonts-wqy-microhei
+
+ +

安装 OpenClaw

+ +
1
下载安装脚本 +
# 打开终端 (Ctrl+Alt+T)
+curl -O https://raw.githubusercontent.com/dongsheng123132/u-claw/main/portable/setup-linux-usb.sh
+bash setup-linux-usb.sh
+

脚本自动下载 Node.js + OpenClaw + QQ 插件，全部使用国内镜像

+
+ +
2
或手动安装 +
# 1. 安装 Node.js
+curl -# -L https://npmmirror.com/mirrors/node/v22.14.0/node-v22.14.0-linux-x64.tar.gz -o /tmp/node.tar.gz
+mkdir -p ~/node && tar -xzf /tmp/node.tar.gz -C ~/node --strip-components=1
+export PATH="$HOME/node/bin:$PATH"
+
+# 2. 安装 OpenClaw
+mkdir -p ~/openclaw && cd ~/openclaw
+npm init -y
+npm install openclaw@latest --registry=https://registry.npmmirror.com
+
+# 3. 启动
+node node_modules/openclaw/openclaw.mjs gateway run --port 18789
+
+ +

日常使用

+ + +

常见问题

+ +

USB 启动不了

+ + +

持久化不生效（重启后配置丢失）

+ + +

运行很慢

+ +
+ + +
+

中国区原生安装教程

+

不用 U 盘，直接在中国网络环境下从零安装 OpenClaw。全程使用国内镜像，无需翻墙。

+ +
+

适用场景：你已经有一台能联网的电脑（Mac / Windows / Linux），想直接安装 OpenClaw，不需要 U 盘。

+
+ +

第一步：安装 Node.js

+

OpenClaw 需要 Node.js v22 或以上版本。

+ +

方法 A：官网直接下载（最简单）

+ + +

方法 B：使用 nvm 版本管理器（推荐开发者）

+
# 1. 安装 nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
+
+# 2. 设置 Node.js 国内镜像（关键！否则下载很慢）
+export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
+echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc
+
+# 3. 安装 Node.js 22
+nvm install 22
+nvm use 22
+
+# 4. 验证
+node -v   # 应显示 v22.x.x
+ +

方法 C：使用 fnm（更快的版本管理器，基于 Rust）

+
# Mac/Linux:
+curl -fsSL https://fnm.vercel.app/install | bash
+
+# Windows (PowerShell):
+winget install Schniz.fnm
+
+# 设置国内镜像
+export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node
+echo 'export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc
+
+# 安装 Node.js 22
+fnm install 22 && fnm use 22
+ +

第二步：设置 npm 国内镜像

+

安装完 Node.js 后，必须先换镜像源，否则安装 OpenClaw 会超时。

+ +
# 推荐：淘宝 npmmirror（最稳定，速度最快）
+npm config set registry https://registry.npmmirror.com
+
+# 验证
+npm config get registry
+# 应返回: https://registry.npmmirror.com/
+ +

国内可用的 npm 镜像源

+ + + + + + + + +
镜像源地址说明
淘宝 npmmirrorhttps://registry.npmmirror.com首选，最快最稳
腾讯云https://mirrors.cloud.tencent.com/npm/腾讯云加速
华为云https://mirrors.huaweicloud.com/repository/npm/华为云加速
阿里云https://npm.aliyun.com阿里云加速
中科大https://mirrors.ustc.edu.cn/高校镜像
清华大学https://mirrors.tuna.tsinghua.edu.cn/高校镜像
+ +
注意：旧域名 registry.npm.taobao.org 已于 2024 年 1 月停止服务，请使用新域名 registry.npmmirror.com。
+ +

使用 nrm 快速切换镜像

+
# 安装 nrm 镜像源管理工具
+npm install -g nrm
+
+nrm ls          # 查看所有可用镜像源
+nrm use taobao  # 一键切换淘宝源
+nrm test        # 测速，看哪个最快
+ +

第三步：安装 OpenClaw

+
# 全局安装
+npm install -g openclaw@latest
+
+# 如果超时，手动指定镜像：
+npm install -g openclaw@latest --registry=https://registry.npmmirror.com
+
+# 验证
+openclaw --version
+ +

第四步：配置国产 AI 模型

+

启动配置向导：

+
# 启动引导向导 + 安装后台守护进程
+openclaw onboard --install-daemon
+
+# 或只启动引导向导
+openclaw onboard
+ +

国产模型注册与配置

+ + + + + + + + +
模型注册地址API Base URL推荐场景
DeepSeekplatform.deepseek.comhttps://api.deepseek.com/v1编程首选，极便宜
Kimiplatform.moonshot.cnhttps://api.moonshot.cn/v1长文档，256K 上下文
通义千问dashscope.console.aliyun.com配置向导选 Qwen免费额度大
智谱 GLMopen.bigmodel.cn配置向导选 Zhipu学术场景
豆包console.volcengine.com/ark配置向导选 Volcano火山引擎生态
MiniMaxplatform.minimaxi.com配置向导选 MiniMax语音多模态
+ +
推荐首选 DeepSeek：注册即送免费额度，API 无需翻墙，编程能力强，价格约 1 元/百万 tokens。
+ +

配置示例（DeepSeek）

+
# 在配置向导中：
+# 1. 选择 Custom Provider
+# 2. 填写：
+#    API Base URL: https://api.deepseek.com/v1
+#    API Key: sk-xxxxxxxx（在 platform.deepseek.com 获取）
+#    Model: deepseek-chat
+ +

第五步：启动与验证

+
# 启动网关
+openclaw gateway run
+
+# 查看状态
+openclaw gateway status
+
+# 浏览器打开控制台
+# http://127.0.0.1:18789
+ +

常见问题

+ +

npm install 超时 / ECONNREFUSED

+
# 1. 确认镜像源已切换
+npm config get registry
+# 应该是 https://registry.npmmirror.com/
+
+# 2. 如果还超时，试其他镜像
+npm config set registry https://mirrors.cloud.tencent.com/npm/
+
+# 3. 清除缓存重试
+npm cache clean --force
+npm install -g openclaw@latest
+ +

node: command not found

+
# 重新打开终端，或手动加载配置
+source ~/.zshrc   # macOS
+source ~/.bashrc  # Linux
+ +

openclaw onboard 报错

+
# 确认 Node.js 版本
+node -v  # 需要 v22+
+
+# 如果版本太低
+nvm install 22 && nvm use 22
+# 或
+fnm install 22 && fnm use 22
+ +

API 调用失败

+ + +
运行诊断：openclaw doctor --repair 可以自动检测和修复常见问题。
+
+