@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/install/railway.mdx

@@ -0,0 +1,106 @@
+---
+title: 在 Railway 上部署
+x-i18n:
+  generated_at: "2026-02-01T21:36:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6d5c2ec2f779bb240e778b5e18ffb8138ce175c4bbdf58b2064a6ad200bf4d1b
+  source_path: railway.mdx
+  workflow: 15
+---
+
+通过一键模板在 Railway 上部署 OpenClaw，并在浏览器中完成设置。
+这是最简单的"无需在服务器上使用终端"的方式：Railway 为你运行 Gateway网关，
+你只需通过 `/setup` 网页向导完成所有配置。
+
+## 快速检查清单（新用户）
+
+1. 点击下方的 **Deploy on Railway**。
+2. 添加一个挂载到 `/data` 的 **Volume**。
+3. 设置必需的**变量**（至少需要 `SETUP_PASSWORD`）。
+4. 在端口 `8080` 上启用 **HTTP Proxy**。
+5. 打开 `https://<your-railway-domain>/setup` 并完成向导。
+
+## 一键部署
+
+<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">
+  Deploy on Railway
+</a>
+
+部署完成后，在 **Railway → 你的服务 → Settings → Domains** 中找到你的公开 URL。
+
+Railway 会：
+
+- 为你生成一个域名（通常是 `https://<something>.up.railway.app`），或者
+- 使用你绑定的自定义域名。
+
+然后打开：
+
+- `https://<your-railway-domain>/setup` — 设置向导（需密码保护）
+- `https://<your-railway-domain>/openclaw` — 控制面板 UI
+
+## 你将获得
+
+- 托管的 OpenClaw Gateway网关 + 控制面板 UI
+- `/setup` 网页设置向导（无需终端命令）
+- 通过 Railway Volume（`/data`）实现持久化存储，配置/凭证/工作区在重新部署后不会丢失
+- 在 `/setup/export` 导出备份，方便日后从 Railway 迁移
+
+## 必需的 Railway 设置
+
+### 公共网络
+
+为服务启用 **HTTP Proxy**。
+
+- 端口：`8080`
+
+### Volume（必需）
+
+挂载一个 Volume 到：
+
+- `/data`
+
+### 变量
+
+在服务上设置以下变量：
+
+- `SETUP_PASSWORD`（必需）
+- `PORT=8080`（必需 — 必须与公共网络中的端口一致）
+- `OPENCLAW_STATE_DIR=/data/.openclaw`（推荐）
+- `OPENCLAW_WORKSPACE_DIR=/data/workspace`（推荐）
+- `OPENCLAW_GATEWAY_TOKEN`（推荐；请视为管理员密钥）
+
+## 设置流程
+
+1. 访问 `https://<your-railway-domain>/setup` 并输入你的 `SETUP_PASSWORD`。
+2. 选择模型/认证提供商并粘贴你的密钥。
+3. （可选）添加 Telegram/Discord/Slack 令牌。
+4. 点击 **Run setup**。
+
+如果 Telegram 私信设置为配对模式，设置向导可以批准配对码。
+
+## 获取聊天令牌
+
+### Telegram 机器人令牌
+
+1. 在 Telegram 中给 `@BotFather` 发消息
+2. 执行 `/newbot`
+3. 复制令牌（格式类似 `123456789:AA...`）
+4. 将其粘贴到 `/setup` 中
+
+### Discord 机器人令牌
+
+1. 前往 https://discord.com/developers/applications
+2. **New Application** → 选择一个名称
+3. **Bot** → **Add Bot**
+4. 在 Bot → Privileged Gateway Intents 下**启用 MESSAGE CONTENT INTENT**（必需，否则机器人启动时会崩溃）
+5. 复制 **Bot Token** 并粘贴到 `/setup` 中
+6. 邀请机器人加入你的服务器（OAuth2 URL Generator；scopes：`bot`、`applications.commands`）
+
+## 备份与迁移
+
+在以下地址下载备份：
+
+- `https://<your-railway-domain>/setup/export`
+
+这会导出你的 OpenClaw 状态和工作区，方便你迁移到其他主机而不丢失配置或记忆。

package/docs/zh-CN/install/render.mdx

@@ -0,0 +1,169 @@
+---
+title: 在 Render 上部署
+x-i18n:
+  generated_at: "2026-02-01T21:38:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 03f0f277145daf6012ce33a9e8447d2eaaf346dfdb0df57a61ebf90b18b67c65
+  source_path: render.mdx
+  workflow: 15
+---
+
+使用基础设施即代码方式在 Render 上部署 OpenClaw。内置的 `render.yaml` Blueprint 以声明式方式定义了你的整个技术栈——服务、磁盘、环境变量，让你只需一键即可完成部署，并将基础设施与代码一同进行版本管理。
+
+## 前提条件
+
+- 一个 [Render 账户](https://render.com)（提供免费套餐）
+- 来自你首选[模型提供商](/providers)的 API 密钥
+
+## 使用 Render Blueprint 部署
+
+<a
+  href="https://render.com/deploy?repo=https://github.com/openclaw/openclaw"
+  target="_blank"
+  rel="noreferrer"
+>
+  部署到 Render
+</a>
+
+点击此链接将会：
+
+1. 根据本仓库根目录下的 `render.yaml` Blueprint 创建一个新的 Render 服务。
+2. 提示你设置 `SETUP_PASSWORD`
+3. 构建 Docker 镜像并部署
+
+部署完成后，你的服务 URL 格式为 `https://<service-name>.onrender.com`。
+
+## 了解 Blueprint
+
+Render Blueprint 是定义基础设施的 YAML 文件。本仓库中的 `render.yaml` 配置了运行 OpenClaw 所需的一切：
+
+```yaml
+services:
+  - type: web
+    name: openclaw
+    runtime: docker
+    plan: starter
+    healthCheckPath: /health
+    envVars:
+      - key: PORT
+        value: "8080"
+      - key: SETUP_PASSWORD
+        sync: false # prompts during deploy
+      - key: OPENCLAW_STATE_DIR
+        value: /data/.openclaw
+      - key: OPENCLAW_WORKSPACE_DIR
+        value: /data/workspace
+      - key: OPENCLAW_GATEWAY_TOKEN
+        generateValue: true # auto-generates a secure token
+    disk:
+      name: openclaw-data
+      mountPath: /data
+      sizeGB: 1
+```
+
+使用的关键 Blueprint 功能：
+
+| 功能                  | 用途                                     |
+| --------------------- | ---------------------------------------- |
+| `runtime: docker`     | 从仓库的 Dockerfile 进行构建             |
+| `healthCheckPath`     | Render 监控 `/health` 并重启不健康的实例 |
+| `sync: false`         | 在部署时提示输入值（用于密钥）           |
+| `generateValue: true` | 自动生成加密安全的值                     |
+| `disk`                | 持久化存储，在重新部署后数据仍然保留     |
+
+## 选择套餐
+
+| 套餐      | 休眠机制           | 磁盘   | 适用场景         |
+| --------- | ------------------ | ------ | ---------------- |
+| Free      | 空闲 15 分钟后休眠 | 不可用 | 测试、演示       |
+| Starter   | 永不休眠           | 1GB+   | 个人使用、小团队 |
+| Standard+ | 永不休眠           | 1GB+   | 生产环境、多渠道 |
+
+Blueprint 默认使用 `starter`。如需使用免费套餐，请在你 fork 的 `render.yaml` 中将 `plan: free`（但请注意：没有持久化磁盘意味着每次部署后配置都会重置）。
+
+## 部署完成后
+
+### 完成设置向导
+
+1. 访问 `https://<your-service>.onrender.com/setup`
+2. 输入你的 `SETUP_PASSWORD`
+3. 选择模型提供商并粘贴你的 API 密钥
+4. 可选配置消息渠道（Telegram、Discord、Slack）
+5. 点击 **Run setup**
+
+### 访问控制面板
+
+Web 管理面板位于 `https://<your-service>.onrender.com/openclaw`。
+
+## Render 仪表盘功能
+
+### 日志
+
+在 **Dashboard → 你的服务 → Logs** 中查看实时日志。可按以下类型筛选：
+
+- 构建日志（Docker 镜像创建）
+- 部署日志（服务启动）
+- 运行时日志（应用输出）
+
+### Shell 访问
+
+如需调试，可通过 **Dashboard → 你的服务 → Shell** 打开 shell 会话。持久化磁盘挂载在 `/data`。
+
+### 环境变量
+
+在 **Dashboard → 你的服务 → Environment** 中修改变量。更改会触发自动重新部署。
+
+### 自动部署
+
+如果你使用的是原始 OpenClaw 仓库，Render 不会自动部署你的 OpenClaw。要更新它，请在仪表盘中手动执行 Blueprint 同步。
+
+## 自定义域名
+
+1. 前往 **Dashboard → 你的服务 → Settings → Custom Domains**
+2. 添加你的域名
+3. 按照指引配置 DNS（CNAME 指向 `*.onrender.com`）
+4. Render 会自动配置 TLS 证书
+
+## 扩展
+
+Render 支持水平和垂直扩展：
+
+- **垂直扩展**：更改套餐以获取更多 CPU/内存
+- **水平扩展**：增加实例数量（Standard 套餐及以上）
+
+对于 OpenClaw，垂直扩展通常就足够了。水平扩展需要粘性会话或外部状态管理。
+
+## 备份与迁移
+
+随时导出你的配置和工作区：
+
+```
+https://<your-service>.onrender.com/setup/export
+```
+
+这将下载一个可移植的备份文件，你可以在任何 OpenClaw 主机上恢复。
+
+## 故障排除
+
+### 服务无法启动
+
+在 Render 仪表盘中检查部署日志。常见问题：
+
+- 缺少 `SETUP_PASSWORD` — Blueprint 会提示输入此值，但请确认已设置
+- 端口不匹配 — 确保 `PORT=8080` 与 Dockerfile 暴露的端口一致
+
+### 冷启动缓慢（免费套餐）
+
+免费套餐的服务在 15 分钟无活动后会休眠。休眠后的首次请求需要几秒钟等待容器启动。升级到 Starter 套餐可实现始终在线。
+
+### 重新部署后数据丢失
+
+这发生在免费套餐上（无持久化磁盘）。升级到付费套餐，或通过 `/setup/export` 定期导出你的配置。
+
+### 健康检查失败
+
+Render 期望在 30 秒内从 `/health` 获得 200 响应。如果构建成功但部署失败，可能是服务启动耗时过长。请检查：
+
+- 构建日志中是否有错误
+- 容器是否能通过 `docker build && docker run` 在本地正常运行

package/docs/zh-CN/install/uninstall.md

@@ -0,0 +1,135 @@
+---
+read_when:
+  - 你想从机器上移除 QuantumClaw
+  - 卸载后 Gateway 网关服务仍在运行
+summary: 完全卸载 QuantumClaw（CLI、服务、状态、工作区）
+title: 卸载
+x-i18n:
+  generated_at: "2026-02-03T07:50:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6673a755c5e1f90a807dd8ac92a774cff6d1bc97d125c75e8bf72a40e952a777
+  source_path: install/uninstall.md
+  workflow: 15
+---
+
+# 卸载
+
+两种方式：
+
+- 如果 `quantumclaw` 仍已安装，使用**简单方式**。
+- 如果 CLI 已删除但服务仍在运行，使用**手动服务移除**。
+
+## 简单方式（CLI 仍已安装）
+
+推荐：使用内置卸载程序：
+
+```bash
+quantumclaw uninstall
+```
+
+非交互式（自动化 / npx）：
+
+```bash
+quantumclaw uninstall --all --yes --non-interactive
+npx -y quantumclaw uninstall --all --yes --non-interactive
+```
+
+手动步骤（效果相同）：
+
+1. 停止 Gateway 网关服务：
+
+```bash
+quantumclaw gateway stop
+```
+
+2. 卸载 Gateway 网关服务（launchd/systemd/schtasks）：
+
+```bash
+quantumclaw gateway uninstall
+```
+
+3. 删除状态 + 配置：
+
+```bash
+rm -rf "${QUANTUMCLAW_STATE_DIR:-$HOME/.quantumclaw}"
+```
+
+如果你将 `QUANTUMCLAW_CONFIG_PATH` 设置为状态目录外的自定义位置，也请删除该文件。
+
+4. 删除你的工作区（可选，移除智能体文件）：
+
+```bash
+rm -rf ~/.quantumclaw/workspace
+```
+
+5. 移除 CLI 安装（选择你使用的那个）：
+
+```bash
+npm rm -g quantumclaw
+pnpm remove -g quantumclaw
+bun remove -g quantumclaw
+```
+
+6. 如果你安装了 macOS 应用：
+
+```bash
+rm -rf /Applications/QuantumClaw.app
+```
+
+注意事项：
+
+- 如果你使用了配置文件（`--profile` / `QUANTUMCLAW_PROFILE`），对每个状态目录重复步骤 3（默认为 `~/.quantumclaw-<profile>`）。
+- 在远程模式下，状态目录位于 **Gateway 网关主机**上，因此也需要在那里运行步骤 1-4。
+
+## 手动服务移除（CLI 未安装）
+
+如果 Gateway 网关服务持续运行但 `quantumclaw` 缺失，请使用此方法。
+
+### macOS（launchd）
+
+默认标签是 `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.quantumclaw.*` 可能仍然存在）：
+
+```bash
+launchctl bootout gui/$UID/bot.molt.gateway
+rm -f ~/Library/LaunchAgents/bot.molt.gateway.plist
+```
+
+如果你使用了配置文件，请将标签和 plist 名称替换为 `bot.molt.<profile>`。如果存在任何旧版 `com.quantumclaw.*` plist，请将其移除。
+
+### Linux（systemd 用户单元）
+
+默认单元名称是 `quantumclaw-gateway.service`（或 `quantumclaw-gateway-<profile>.service`）：
+
+```bash
+systemctl --user disable --now quantumclaw-gateway.service
+rm -f ~/.config/systemd/user/quantumclaw-gateway.service
+systemctl --user daemon-reload
+```
+
+### Windows（计划任务）
+
+默认任务名称是 `QuantumClaw Gateway`（或 `QuantumClaw Gateway (<profile>)`）。
+任务脚本位于你的状态目录下。
+
+```powershell
+schtasks /Delete /F /TN "QuantumClaw Gateway"
+Remove-Item -Force "$env:USERPROFILE\.quantumclaw\gateway.cmd"
+```
+
+如果你使用了配置文件，请删除匹配的任务名称和 `~\.quantumclaw-<profile>\gateway.cmd`。
+
+## 普通安装 vs 源码检出
+
+### 普通安装（install.sh / npm / pnpm / bun）
+
+如果你使用了 `https://quantumclaw.ai/install.sh` 或 `install.ps1`，CLI 是通过 `npm install -g quantumclaw@latest` 安装的。
+使用 `npm rm -g quantumclaw` 移除（或 `pnpm remove -g` / `bun remove -g`，如果你是用那种方式安装的）。
+
+### 源码检出（git clone）
+
+如果你从仓库检出运行（`git clone` + `quantumclaw ...` / `bun run quantumclaw ...`）：
+
+1. 在删除仓库**之前**卸载 Gateway 网关服务（使用上面的简单方式或手动服务移除）。
+2. 删除仓库目录。
+3. 按上述方式移除状态 + 工作区。

package/docs/zh-CN/install/updating.md

@@ -0,0 +1,233 @@
+---
+read_when:
+  - 更新 QuantumClaw
+  - 更新后出现问题
+summary: 安全更新 QuantumClaw（全局安装或源码），以及回滚策略
+title: 更新
+x-i18n:
+  generated_at: "2026-02-03T07:50:25Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 38cccac0839f0f22403b6508cd94ba1b401133ffc1d92d4f7640b8d04e082317
+  source_path: install/updating.md
+  workflow: 15
+---
+
+# 更新
+
+QuantumClaw 发展迅速（尚未到"1.0"）。将更新视为发布基础设施：更新 → 运行检查 → 重启（或使用会重启的 `quantumclaw update`）→ 验证。
+
+## 推荐：重新运行网站安装程序（原地升级）
+
+**首选**的更新路径是重新运行网站上的安装程序。它会检测现有安装、原地升级，并在需要时运行 `quantumclaw doctor`。
+
+```bash
+curl -fsSL https://quantumclaw.ai/install.sh | bash
+```
+
+说明：
+
+- 如果你不想再次运行新手引导向导，添加 `--no-onboard`。
+- 对于**源码安装**，使用：
+  ```bash
+  curl -fsSL https://quantumclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
+  ```
+  安装程序**仅**在仓库干净时才会执行 `git pull --rebase`。
+- 对于**全局安装**，脚本底层使用 `npm install -g quantumclaw@latest`。
+- 旧版说明：`clawdbot` 仍可作为兼容性垫片使用。
+
+## 更新之前
+
+- 了解你的安装方式：**全局**（npm/pnpm）还是**源码**（git clone）。
+- 了解你的 Gateway 网关运行方式：**前台终端**还是**受管理服务**（launchd/systemd）。
+- 快照你的定制内容：
+  - 配置：`~/.quantumclaw/quantumclaw.json`
+  - 凭证：`~/.quantumclaw/credentials/`
+  - 工作区：`~/.quantumclaw/workspace`
+
+## 更新（全局安装）
+
+全局安装（选择一个）：
+
+```bash
+npm i -g quantumclaw@latest
+```
+
+```bash
+pnpm add -g quantumclaw@latest
+```
+
+我们**不**推荐将 Bun 用于 Gateway 网关运行时（WhatsApp/Telegram 有 bug）。
+
+切换更新渠道（git + npm 安装）：
+
+```bash
+quantumclaw update --channel beta
+quantumclaw update --channel dev
+quantumclaw update --channel stable
+```
+
+使用 `--tag <dist-tag|version>` 进行一次性安装指定标签/版本。
+
+渠道语义和发布说明参见[开发渠道](/install/development-channels)。
+
+注意：在 npm 安装上，Gateway 网关在启动时会记录更新提示（检查当前渠道标签）。通过 `update.checkOnStart: false` 禁用。
+
+然后：
+
+```bash
+quantumclaw doctor
+quantumclaw gateway restart
+quantumclaw health
+```
+
+说明：
+
+- 如果你的 Gateway 网关作为服务运行，`quantumclaw gateway restart` 优于杀死 PID。
+- 如果你固定在特定版本，参见下面的"回滚/固定"。
+
+## 更新（`quantumclaw update`）
+
+对于**源码安装**（git checkout），首选：
+
+```bash
+quantumclaw update
+```
+
+它运行一个相对安全的更新流程：
+
+- 需要干净的工作树。
+- 切换到选定的渠道（标签或分支）。
+- 获取并 rebase 到配置的上游（dev 渠道）。
+- 安装依赖、构建、构建控制 UI，并运行 `quantumclaw doctor`。
+- 默认重启 Gateway 网关（使用 `--no-restart` 跳过）。
+
+如果你通过 **npm/pnpm** 安装（没有 git 元数据），`quantumclaw update` 将尝试通过你的包管理器更新。如果无法检测到安装，请改用"更新（全局安装）"。
+
+## 更新（控制 UI / RPC）
+
+控制 UI 有**更新并重启**（RPC：`update.run`）。它：
+
+1. 运行与 `quantumclaw update` 相同的源码更新流程（仅限 git checkout）。
+2. 写入带有结构化报告（stdout/stderr 尾部）的重启哨兵。
+3. 重启 Gateway 网关并向最后活跃的会话 ping 报告。
+
+如果 rebase 失败，Gateway 网关会中止并在不应用更新的情况下重启。
+
+## 更新（从源码）
+
+从仓库 checkout：
+
+首选：
+
+```bash
+quantumclaw update
+```
+
+手动（大致等效）：
+
+```bash
+git pull
+pnpm install
+pnpm build
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+quantumclaw doctor
+quantumclaw health
+```
+
+说明：
+
+- 当你运行打包的 `quantumclaw` 二进制文件（[`quantumclaw.mjs`](https://github.com/quantumclaw/quantumclaw/blob/main/quantumclaw.mjs)）或使用 Node 运行 `dist/` 时，`pnpm build` 很重要。
+- 如果你从仓库 checkout 运行而没有全局安装，CLI 命令使用 `pnpm quantumclaw ...`。
+- 如果你直接从 TypeScript 运行（`pnpm quantumclaw ...`），通常不需要重新构建，但**配置迁移仍然适用** → 运行 doctor。
+- 在全局和 git 安装之间切换很容易：安装另一种方式，然后运行 `quantumclaw doctor` 以便将 Gateway 网关服务入口点重写为当前安装。
+
+## 始终运行：`quantumclaw doctor`
+
+Doctor 是"安全更新"命令。它故意很无聊：修复 + 迁移 + 警告。
+
+注意：如果你是**源码安装**（git checkout），`quantumclaw doctor` 会提供先运行 `quantumclaw update`。
+
+它通常做的事情：
+
+- 迁移已弃用的配置键/旧版配置文件位置。
+- 审计私信策略并对有风险的"开放"设置发出警告。
+- 检查 Gateway 网关健康状况，可以提供重启。
+- 检测并将旧版 Gateway 网关服务（launchd/systemd；旧版 schtasks）迁移到当前 QuantumClaw 服务。
+- 在 Linux 上，确保 systemd 用户 lingering（这样 Gateway 网关在登出后仍能存活）。
+
+详情：[Doctor](/gateway/doctor)
+
+## 启动/停止/重启 Gateway 网关
+
+CLI（无论操作系统都适用）：
+
+```bash
+quantumclaw gateway status
+quantumclaw gateway stop
+quantumclaw gateway restart
+quantumclaw gateway --port 18789
+quantumclaw logs --follow
+```
+
+如果你使用受管理服务：
+
+- macOS launchd（应用捆绑的 LaunchAgent）：`launchctl kickstart -k gui/$UID/bot.molt.gateway`（使用 `bot.molt.<profile>`；旧版 `com.quantumclaw.*` 仍然有效）
+- Linux systemd 用户服务：`systemctl --user restart quantumclaw-gateway[-<profile>].service`
+- Windows（WSL2）：`systemctl --user restart quantumclaw-gateway[-<profile>].service`
+  - `launchctl`/`systemctl` 仅在服务已安装时有效；否则运行 `quantumclaw gateway install`。
+
+运行手册 + 确切的服务标签：[Gateway 网关运行手册](/gateway)
+
+## 回滚/固定（当出问题时）
+
+### 固定（全局安装）
+
+安装已知良好的版本（将 `<version>` 替换为最后可用的版本）：
+
+```bash
+npm i -g quantumclaw@<version>
+```
+
+```bash
+pnpm add -g quantumclaw@<version>
+```
+
+提示：要查看当前发布的版本，运行 `npm view quantumclaw version`。
+
+然后重启 + 重新运行 doctor：
+
+```bash
+quantumclaw doctor
+quantumclaw gateway restart
+```
+
+### 按日期固定（源码）
+
+选择某个日期的提交（示例："2026-01-01 时 main 的状态"）：
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+```
+
+然后重新安装依赖 + 重启：
+
+```bash
+pnpm install
+pnpm build
+quantumclaw gateway restart
+```
+
+如果你之后想回到最新版本：
+
+```bash
+git checkout main
+git pull
+```
+
+## 如果你卡住了
+
+- 再次运行 `quantumclaw doctor` 并仔细阅读输出（它通常会告诉你修复方法）。
+- 查看：[故障排除](/gateway/troubleshooting)
+- 在 Discord 上提问：https://discord.gg/clawd