@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/install/macos-vm.md

@@ -0,0 +1,288 @@
+---
+read_when:
+  - 你希望 QuantumClaw 与你的主 macOS 环境隔离
+  - 你希望在沙箱中集成 iMessage（BlueBubbles）
+  - 你希望拥有一个可重置且可克隆的 macOS 环境
+  - 你希望比较本地与托管 macOS VM 选项
+summary: 在沙箱化的 macOS VM（本地或托管）中运行 QuantumClaw，适用于你需要隔离或 iMessage 的场景
+title: macOS VM
+x-i18n:
+  generated_at: "2026-03-16T06:23:59Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 4d1c85a5e4945f9f0796038cd5960edecb71ec4dffb6f9686be50adb75180716
+  source_path: install/macos-vm.md
+  workflow: 15
+---
+
+# 在 macOS VM 上运行 QuantumClaw（沙箱隔离）
+
+## 推荐默认方案（适用于大多数用户）
+
+- **小型 Linux VPS**：适合始终在线的 Gateway 网关，且成本较低。参见 [VPS hosting](/vps)。
+- **专用硬件**（Mac mini 或 Linux 主机）：如果你希望完全控制，并为浏览器自动化获得一个**住宅 IP**。许多网站会屏蔽数据中心 IP，因此本地浏览通常效果更好。
+- **混合方案：** 将 Gateway 网关放在便宜的 VPS 上，当你需要浏览器/UI 自动化时，再将你的 Mac 作为一个 **node** 连接进来。参见 [Nodes](/nodes) 和 [Gateway remote](/gateway/remote)。
+
+当你明确需要 macOS 独有能力（iMessage/BlueBubbles），或希望与你的日常 Mac 严格隔离时，再使用 macOS VM。
+
+## macOS VM 选项
+
+### 在你的 Apple Silicon Mac 上运行本地 VM（Lume）
+
+使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱化 macOS VM 中运行 QuantumClaw。
+
+这样你将获得：
+
+- 完全隔离的 macOS 环境（你的宿主机保持干净）
+- 通过 BlueBubbles 获得 iMessage 支持（在 Linux/Windows 上无法实现）
+- 通过克隆 VM 实现即时重置
+- 无需额外硬件或云成本
+
+### 托管 Mac 提供商（云端）
+
+如果你希望在云中使用 macOS，托管 Mac 提供商同样可行：
+
+- [MacStadium](https://www.macstadium.com/)（托管 Mac）
+- 其他托管 Mac 供应商也可以；请遵循它们的 VM + SSH 文档
+
+一旦你获得了对 macOS VM 的 SSH 访问权限，就继续执行下面的第 6 步。
+
+---
+
+## 快速路径（Lume，适合有经验的用户）
+
+1. 安装 Lume
+2. `lume create quantumclaw --os macos --ipsw latest`
+3. 完成设置助理，启用远程登录（SSH）
+4. `lume run quantumclaw --no-display`
+5. SSH 登录，安装 QuantumClaw，配置渠道
+6. 完成
+
+---
+
+## 你需要准备的内容（Lume）
+
+- Apple Silicon Mac（M1/M2/M3/M4）
+- 宿主机运行 macOS Sequoia 或更高版本
+- 每个 VM 大约 60 GB 可用磁盘空间
+- 约 20 分钟
+
+---
+
+## 1）安装 Lume
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+```
+
+如果 `~/.local/bin` 不在你的 PATH 中：
+
+```bash
+echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
+```
+
+验证：
+
+```bash
+lume --version
+```
+
+文档： [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
+
+---
+
+## 2）创建 macOS VM
+
+```bash
+lume create quantumclaw --os macos --ipsw latest
+```
+
+这会下载 macOS 并创建 VM。VNC 窗口会自动打开。
+
+注意：下载可能需要一些时间，具体取决于你的网络连接。
+
+---
+
+## 3）完成设置助理
+
+在 VNC 窗口中：
+
+1. 选择语言和地区
+2. 跳过 Apple ID（或者如果你之后想使用 iMessage，也可以登录）
+3. 创建一个用户账号（记住用户名和密码）
+4. 跳过所有可选功能
+
+设置完成后，启用 SSH：
+
+1. 打开“系统设置”→“通用”→“共享”
+2. 启用“远程登录”
+
+---
+
+## 4）获取 VM 的 IP 地址
+
+```bash
+lume get quantumclaw
+```
+
+查找 IP 地址（通常为 `192.168.64.x`）。
+
+---
+
+## 5）通过 SSH 连接到 VM
+
+```bash
+ssh youruser@192.168.64.X
+```
+
+将 `youruser` 替换为你创建的账号，并将 IP 替换为你的 VM IP。
+
+---
+
+## 6）安装 QuantumClaw
+
+在 VM 内：
+
+```bash
+npm install -g quantumclaw@latest
+quantumclaw onboard --install-daemon
+```
+
+按照新手引导提示设置你的模型提供商（Anthropic、OpenAI 等）。
+
+---
+
+## 7）配置渠道
+
+编辑配置文件：
+
+```bash
+nano ~/.quantumclaw/quantumclaw.json
+```
+
+添加你的渠道：
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "dmPolicy": "allowlist",
+      "allowFrom": ["+15551234567"]
+    },
+    "telegram": {
+      "botToken": "YOUR_BOT_TOKEN"
+    }
+  }
+}
+```
+
+然后登录 WhatsApp（扫描 QR 码）：
+
+```bash
+quantumclaw channels login
+```
+
+---
+
+## 8）以无界面方式运行 VM
+
+停止 VM，然后在无显示模式下重启：
+
+```bash
+lume stop quantumclaw
+lume run quantumclaw --no-display
+```
+
+VM 会在后台运行。QuantumClaw 的守护进程会保持 Gateway 网关持续运行。
+
+检查状态：
+
+```bash
+ssh youruser@192.168.64.X "quantumclaw status"
+```
+
+---
+
+## 加分项：iMessage 集成
+
+这是在 macOS 上运行的杀手级特性。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 QuantumClaw。
+
+在 VM 内：
+
+1. 从 bluebubbles.app 下载 BlueBubbles
+2. 使用你的 Apple ID 登录
+3. 启用 Web API 并设置一个密码
+4. 将 BlueBubbles webhook 指向你的 gateway（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
+
+添加到你的 QuantumClaw 配置中：
+
+```json
+{
+  "channels": {
+    "bluebubbles": {
+      "serverUrl": "http://localhost:1234",
+      "password": "your-api-password",
+      "webhookPath": "/bluebubbles-webhook"
+    }
+  }
+}
+```
+
+重启 Gateway 网关。现在你的智能体就可以发送和接收 iMessage 了。
+
+完整设置细节： [BlueBubbles channel](/channels/bluebubbles)
+
+---
+
+## 保存黄金镜像
+
+在进一步自定义之前，为你的干净状态创建快照：
+
+```bash
+lume stop quantumclaw
+lume clone quantumclaw quantumclaw-golden
+```
+
+随时重置：
+
+```bash
+lume stop quantumclaw && lume delete quantumclaw
+lume clone quantumclaw-golden quantumclaw
+lume run quantumclaw --no-display
+```
+
+---
+
+## 7×24 运行
+
+通过以下方式保持 VM 持续运行：
+
+- 让你的 Mac 保持通电
+- 在“系统设置”→“节能”中禁用睡眠
+- 如有需要，使用 `caffeinate`
+
+如果你需要真正始终在线，请考虑使用专用 Mac mini 或小型 VPS。参见 [VPS hosting](/vps)。
+
+---
+
+## 故障排除
+
+| 问题                    | 解决方案                                                          |
+| ----------------------- | ----------------------------------------------------------------- |
+| 无法通过 SSH 连接到 VM  | 检查 VM 的“系统设置”中是否已启用“远程登录”                        |
+| 未显示 VM IP            | 等待 VM 完全启动后，再次运行 `lume get quantumclaw`                  |
+| 找不到 `lume` 命令      | 将 `~/.local/bin` 添加到你的 PATH                                 |
+| 无法扫描 WhatsApp QR 码 | 运行 `quantumclaw channels login` 时，确保你登录的是 VM 而不是宿主机 |
+
+---
+
+## 相关文档
+
+- [VPS hosting](/vps)
+- [Nodes](/nodes)
+- [Gateway remote](/gateway/remote)
+- [BlueBubbles channel](/channels/bluebubbles)
+- [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart)
+- [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
+- [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
+- [Docker Sandboxing](/install/docker)（另一种隔离方案）

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

@@ -0,0 +1,199 @@
+---
+read_when:
+  - 你正在将 QuantumClaw 迁移到新的笔记本电脑/服务器
+  - 你想保留会话、认证和渠道登录（WhatsApp 等）
+summary: 将 QuantumClaw 安装从一台机器迁移到另一台
+title: 迁移指南
+x-i18n:
+  generated_at: "2026-02-03T07:49:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 604d862c4bf86e7924d09028db8cc2514ca6f1d64ebe8bb7d1e2dde57ef70caa
+  source_path: install/migrating.md
+  workflow: 15
+---
+
+# 将 QuantumClaw 迁移到新机器
+
+本指南将 QuantumClaw Gateway 网关从一台机器迁移到另一台，**无需重新进行新手引导**。
+
+迁移在概念上很简单：
+
+- 复制**状态目录**（`$QUANTUMCLAW_STATE_DIR`，默认：`~/.quantumclaw/`）— 这包括配置、认证、会话和渠道状态。
+- 复制你的**工作区**（默认 `~/.quantumclaw/workspace/`）— 这包括你的智能体文件（记忆、提示等）。
+
+但在**配置文件**、**权限**和**部分复制**方面有常见的陷阱。
+
+## 开始之前（你要迁移什么）
+
+### 1）确定你的状态目录
+
+大多数安装使用默认值：
+
+- **状态目录：** `~/.quantumclaw/`
+
+但如果你使用以下方式，可能会不同：
+
+- `--profile <name>`（通常变成 `~/.quantumclaw-<profile>/`）
+- `QUANTUMCLAW_STATE_DIR=/some/path`
+
+如果你不确定，在**旧**机器上运行：
+
+```bash
+quantumclaw status
+```
+
+在输出中查找 `QUANTUMCLAW_STATE_DIR` / profile 的提及。如果你运行多个 Gateway 网关，对每个配置文件重复此操作。
+
+### 2）确定你的工作区
+
+常见默认值：
+
+- `~/.quantumclaw/workspace/`（推荐的工作区）
+- 你创建的自定义文件夹
+
+你的工作区是 `MEMORY.md`、`USER.md` 和 `memory/*.md` 等文件所在的位置。
+
+### 3）了解你将保留什么
+
+如果你复制**两者**——状态目录和工作区，你将保留：
+
+- Gateway 网关配置（`quantumclaw.json`）
+- 认证配置文件 / API 密钥 / OAuth 令牌
+- 会话历史 + 智能体状态
+- 渠道状态（例如 WhatsApp 登录/会话）
+- 你的工作区文件（记忆、Skills 笔记等）
+
+如果你**只**复制工作区（例如通过 Git），你**不会**保留：
+
+- 会话
+- 凭证
+- 渠道登录
+
+这些存储在 `$QUANTUMCLAW_STATE_DIR` 下。
+
+## 迁移步骤（推荐）
+
+### 步骤 0 — 备份（旧机器）
+
+在**旧**机器上，首先停止 Gateway 网关，这样文件不会在复制过程中发生变化：
+
+```bash
+quantumclaw gateway stop
+```
+
+（可选但推荐）归档状态目录和工作区：
+
+```bash
+# 如果你使用配置文件或自定义位置，请调整路径
+cd ~
+tar -czf quantumclaw-state.tgz .quantumclaw
+
+tar -czf quantumclaw-workspace.tgz .quantumclaw/workspace
+```
+
+如果你有多个配置文件/状态目录（例如 `~/.quantumclaw-main`、`~/.quantumclaw-work`），分别归档每个。
+
+### 步骤 1 — 在新机器上安装 QuantumClaw
+
+在**新**机器上，安装 CLI（如果需要还有 Node）：
+
+- 参见：[安装](/install)
+
+在这个阶段，如果新手引导创建了一个新的 `~/.quantumclaw/` 也没关系 — 你将在下一步覆盖它。
+
+### 步骤 2 — 将状态目录 + 工作区复制到新机器
+
+复制**两者**：
+
+- `$QUANTUMCLAW_STATE_DIR`（默认 `~/.quantumclaw/`）
+- 你的工作区（默认 `~/.quantumclaw/workspace/`）
+
+常见方法：
+
+- `scp` 压缩包并解压
+- 通过 SSH 使用 `rsync -a`
+- 外部驱动器
+
+复制后，确保：
+
+- 包含了隐藏目录（例如 `.quantumclaw/`）
+- 文件所有权对于运行 Gateway 网关的用户是正确的
+
+### 步骤 3 — 运行 Doctor（迁移 + 服务修复）
+
+在**新**机器上：
+
+```bash
+quantumclaw doctor
+```
+
+Doctor 是"安全可靠"的命令。它修复服务、应用配置迁移，并警告不匹配问题。
+
+然后：
+
+```bash
+quantumclaw gateway restart
+quantumclaw status
+```
+
+## 常见陷阱（以及如何避免）
+
+### 陷阱：配置文件/状态目录不匹配
+
+如果你在旧 Gateway 网关上使用了配置文件（或 `QUANTUMCLAW_STATE_DIR`），而新 Gateway 网关使用了不同的配置，你会看到如下症状：
+
+- 配置更改不生效
+- 渠道丢失/已登出
+- 会话历史为空
+
+修复：使用你迁移的**相同**配置文件/状态目录运行 Gateway 网关/服务，然后重新运行：
+
+```bash
+quantumclaw doctor
+```
+
+### 陷阱：只复制 `quantumclaw.json`
+
+`quantumclaw.json` 是不够的。许多提供商在以下位置存储状态：
+
+- `$QUANTUMCLAW_STATE_DIR/credentials/`
+- `$QUANTUMCLAW_STATE_DIR/agents/<agentId>/...`
+
+始终迁移整个 `$QUANTUMCLAW_STATE_DIR` 文件夹。
+
+### 陷阱：权限/所有权
+
+如果你以 root 身份复制或更改了用户，Gateway 网关可能无法读取凭证/会话。
+
+修复：确保状态目录 + 工作区由运行 Gateway 网关的用户拥有。
+
+### 陷阱：在远程/本地模式之间迁移
+
+- 如果你的 UI（WebUI/TUI）指向**远程** Gateway 网关，远程主机拥有会话存储 + 工作区。
+- 迁移你的笔记本电脑不会移动远程 Gateway 网关的状态。
+
+如果你处于远程模式，请迁移 **Gateway 网关主机**。
+
+### 陷阱：备份中的密钥
+
+`$QUANTUMCLAW_STATE_DIR` 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭证）。将备份视为生产密钥：
+
+- 加密存储
+- 避免通过不安全的渠道共享
+- 如果怀疑泄露，轮换密钥
+
+## 验证检查清单
+
+在新机器上，确认：
+
+- `quantumclaw status` 显示 Gateway 网关正在运行
+- 你的渠道仍然连接（例如 WhatsApp 不需要重新配对）
+- 仪表板打开并显示现有会话
+- 你的工作区文件（记忆、配置）存在
+
+## 相关内容
+
+- [Doctor](/gateway/doctor)
+- [Gateway 网关故障排除](/gateway/troubleshooting)
+- [QuantumClaw 在哪里存储数据？](/help/faq#where-does-quantumclaw-store-its-data)

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

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 你想要可复现、可回滚的安装
+  - 你已经在使用 Nix/NixOS/Home Manager
+  - 你想要所有内容都固定并以声明式管理
+summary: 使用 Nix 声明式安装 QuantumClaw
+title: Nix
+x-i18n:
+  generated_at: "2026-02-03T07:49:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f1452194cfdd74613b5b3ab90b0d506eaea2d16b147497987710d6ad658312ba
+  source_path: install/nix.md
+  workflow: 15
+---
+
+# Nix 安装
+
+使用 Nix 运行 QuantumClaw 的推荐方式是通过 **[nix-quantumclaw](https://github.com/quantumclaw/nix-quantumclaw)** — 一个开箱即用的 Home Manager 模块。
+
+## 快速开始
+
+将此粘贴给你的 AI 智能体（Claude、Cursor 等）：
+
+```text
+I want to set up nix-quantumclaw on my Mac.
+Repository: github:quantumclaw/nix-quantumclaw
+
+What I need you to do:
+1. Check if Determinate Nix is installed (if not, install it)
+2. Create a local flake at ~/code/quantumclaw-local using templates/agent-first/flake.nix
+3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
+4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
+5. Fill in the template placeholders and run home-manager switch
+6. Verify: launchd running, bot responds to messages
+
+Reference the nix-quantumclaw README for module options.
+```
+
+> **📦 完整指南：[github.com/quantumclaw/nix-quantumclaw](https://github.com/quantumclaw/nix-quantumclaw)**
+>
+> nix-quantumclaw 仓库是 Nix 安装的权威来源。本页只是一个快速概述。
+
+## 你将获得
+
+- Gateway 网关 + macOS 应用 + 工具（whisper、spotify、cameras）— 全部固定版本
+- 重启后仍能运行的 Launchd 服务
+- 带有声明式配置的插件系统
+- 即时回滚：`home-manager switch --rollback`
+
+---
+
+## Nix 模式运行时行为
+
+当设置 `QUANTUMCLAW_NIX_MODE=1` 时（nix-quantumclaw 会自动设置）：
+
+QuantumClaw 支持 **Nix 模式**，使配置确定性并禁用自动安装流程。
+通过导出以下环境变量启用：
+
+```bash
+QUANTUMCLAW_NIX_MODE=1
+```
+
+在 macOS 上，GUI 应用不会自动继承 shell 环境变量。你也可以通过 defaults 启用 Nix 模式：
+
+```bash
+defaults write bot.molt.mac quantumclaw.nixMode -bool true
+```
+
+### 配置 + 状态路径
+
+QuantumClaw 从 `QUANTUMCLAW_CONFIG_PATH` 读取 JSON5 配置，并将可变数据存储在 `QUANTUMCLAW_STATE_DIR` 中。
+
+- `QUANTUMCLAW_STATE_DIR`（默认：`~/.quantumclaw`）
+- `QUANTUMCLAW_CONFIG_PATH`（默认：`$QUANTUMCLAW_STATE_DIR/quantumclaw.json`）
+
+在 Nix 下运行时，将这些显式设置为 Nix 管理的位置，以便运行时状态和配置不会进入不可变存储。
+
+### Nix 模式下的运行时行为
+
+- 自动安装和自我修改流程被禁用
+- 缺失的依赖会显示 Nix 特定的修复消息
+- 存在时 UI 会显示只读 Nix 模式横幅
+
+## 打包注意事项（macOS）
+
+macOS 打包流程期望在以下位置有一个稳定的 Info.plist 模板：
+
+```
+apps/macos/Sources/QuantumClaw/Resources/Info.plist
+```
+
+[`scripts/package-mac-app.sh`](https://github.com/quantumclaw/quantumclaw/blob/main/scripts/package-mac-app.sh) 将此模板复制到应用包中并修补动态字段（bundle ID、版本/构建号、Git SHA、Sparkle 密钥）。这使 plist 对于 SwiftPM 打包和 Nix 构建保持确定性（它们不依赖完整的 Xcode 工具链）。
+
+## 相关内容
+
+- [nix-quantumclaw](https://github.com/quantumclaw/nix-quantumclaw) — 完整设置指南
+- [向导](/start/wizard) — 非 Nix CLI 设置
+- [Docker](/install/docker) — 容器化设置

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

@@ -0,0 +1,8 @@
+---
+summary: Node.js 安装与配置（QuantumClaw 版本要求、安装方式与 PATH 排错）
+title: Node.js
+---
+
+# Node.js
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Node.js](/install/node)。

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

@@ -0,0 +1,60 @@
+---
+title: 在 Northflank 上部署
+x-i18n:
+  generated_at: "2026-02-01T21:19:03Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ad0be8dda41c51d0b6424259316db1b22be5216434f5879f21a5e8c60e0a2ee0
+  source_path: northflank.mdx
+  workflow: 15
+---
+
+通过一键模板在 Northflank 上部署 OpenClaw，然后在浏览器中完成设置。
+这是最简单的"无需在服务器上使用终端"的方式：Northflank 为你运行 Gateway网关，
+你通过 `/setup` 网页向导配置一切。
+
+## 如何开始
+
+1. 点击 [Deploy OpenClaw](https://northflank.com/stacks/deploy-openclaw) 打开模板。
+2. 如果你还没有账户，请创建一个 [Northflank 账户](https://app.northflank.com/signup)。
+3. 点击 **Deploy OpenClaw now**。
+4. 设置必需的环境变量：`SETUP_PASSWORD`。
+5. 点击 **Deploy stack** 构建并运行 OpenClaw 模板。
+6. 等待部署完成，然后点击 **View resources**。
+7. 打开 OpenClaw 服务。
+8. 打开公开的 OpenClaw URL，在 `/setup` 完成设置。
+9. 在 `/openclaw` 打开控制面板 UI。
+
+## 你将获得
+
+- 托管的 OpenClaw Gateway网关 + 控制面板 UI
+- `/setup` 处的网页设置向导（无需终端命令）
+- 通过 Northflank Volume（`/data`）实现持久化存储，配置/凭据/工作区在重新部署后不会丢失
+
+## 设置流程
+
+1. 访问 `https://<your-northflank-domain>/setup` 并输入你的 `SETUP_PASSWORD`。
+2. 选择模型/认证提供商并粘贴你的密钥。
+3. （可选）添加 Telegram/Discord/Slack 令牌。
+4. 点击 **Run setup**。
+5. 在 `https://<your-northflank-domain>/openclaw` 打开控制面板 UI。
+
+如果 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；权限范围：`bot`、`applications.commands`）