@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/start/openclaw.md

@@ -0,0 +1,248 @@
+---
+read_when:
+  - 新手引导新助手实例时
+  - 审查安全/权限影响时
+summary: 将 QuantumClaw 作为个人助手运行的端到端指南，包含安全注意事项
+title: 个人助手设置
+x-i18n:
+  generated_at: "2026-02-03T07:54:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2763668c053abe34ea72c40d1306d3d1143099c58b1e3ef91c2e5a20cb2769e0
+  source_path: start/quantumclaw.md
+  workflow: 15
+---
+
+# 使用 QuantumClaw 构建个人助手
+
+QuantumClaw 是 **Pi** 智能体的 WhatsApp + Telegram + Discord + iMessage Gateway 网关。插件可添加 Mattermost。本指南是"个人助手"设置：一个专用的 WhatsApp 号码，表现得像你的常驻智能体。
+
+## ⚠️ 安全第一
+
+你正在让智能体处于可以：
+
+- 在你的机器上运行命令（取决于你的 Pi 工具设置）
+- 在你的工作区读/写文件
+- 通过 WhatsApp/Telegram/Discord/Mattermost（插件）发送消息
+
+从保守开始：
+
+- 始终设置 `channels.whatsapp.allowFrom`（永远不要在你的个人 Mac 上对全世界开放）。
+- 为助手使用专用的 WhatsApp 号码。
+- 心跳现在默认每 30 分钟一次。在你信任设置之前，通过设置 `agents.defaults.heartbeat.every: "0m"` 来禁用。
+
+## 先决条件
+
+- Node **22+**
+- QuantumClaw 在 PATH 中可用（推荐：全局安装）
+- 助手的第二个手机号码（SIM/eSIM/预付费）
+
+```bash
+npm install -g quantumclaw@latest
+# 或：pnpm add -g quantumclaw@latest
+```
+
+从源代码（开发）：
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+pnpm install
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+pnpm build
+pnpm link --global
+```
+
+## 双手机设置（推荐）
+
+你需要这样：
+
+```
+你的手机（个人）               第二部手机（助手）
+┌─────────────────┐           ┌─────────────────┐
+│  你的 WhatsApp  │  ──────▶  │   助手 WA       │
+│  +1-555-YOU     │  消息     │  +1-555-ASSIST  │
+└─────────────────┘           └────────┬────────┘
+                                       │ 通过二维码关联
+                                       ▼
+                              ┌─────────────────┐
+                              │  你的 Mac       │
+                              │  (quantumclaw)     │
+                              │    Pi 智能体    │
+                              └─────────────────┘
+```
+
+如果你将个人 WhatsApp 关联到 QuantumClaw，发给你的每条消息都会变成"智能体输入"。这通常不是你想要的。
+
+## 5 分钟快速开始
+
+1. 配对 WhatsApp Web（显示二维码；用助手手机扫描）：
+
+```bash
+quantumclaw channels login
+```
+
+2. 启动 Gateway 网关（保持运行）：
+
+```bash
+quantumclaw gateway --port 18789
+```
+
+3. 在 `~/.quantumclaw/quantumclaw.json` 中放置最小配置：
+
+```json5
+{
+  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
+}
+```
+
+现在从你允许列表中的手机向助手号码发消息。
+
+新手引导完成后，我们会自动打开带有 Gateway 网关令牌的仪表板并打印带令牌的链接。稍后重新打开：`quantumclaw dashboard`。
+
+## 给智能体一个工作区（AGENTS）
+
+QuantumClaw 从其工作区目录读取操作指令和"记忆"。
+
+默认情况下，QuantumClaw 使用 `~/.quantumclaw/workspace` 作为智能体工作区，并会在设置/首次智能体运行时自动创建它（加上起始的 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`）。`BOOTSTRAP.md` 仅在工作区是全新的时候创建（删除后不应再出现）。
+
+提示：将此文件夹视为 QuantumClaw 的"记忆"，并将其设为 git 仓库（最好是私有的），这样你的 `AGENTS.md` + 记忆文件就有了备份。如果安装了 git，全新的工作区会自动初始化。
+
+```bash
+quantumclaw setup
+```
+
+完整工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
+记忆工作流：[记忆](/concepts/memory)
+
+可选：使用 `agents.defaults.workspace` 选择不同的工作区（支持 `~`）。
+
+```json5
+{
+  agent: {
+    workspace: "~/.quantumclaw/workspace",
+  },
+}
+```
+
+如果你已经从仓库提供了自己的工作区文件，可以完全禁用引导文件创建：
+
+```json5
+{
+  agent: {
+    skipBootstrap: true,
+  },
+}
+```
+
+## 将其变成"助手"的配置
+
+QuantumClaw 默认为良好的助手设置，但你通常需要调整：
+
+- `SOUL.md` 中的人设/指令
+- 思考默认值（如果需要）
+- 心跳（一旦你信任它）
+
+示例：
+
+```json5
+{
+  logging: { level: "info" },
+  agent: {
+    model: "anthropic/claude-opus-4-5",
+    workspace: "~/.quantumclaw/workspace",
+    thinkingDefault: "high",
+    timeoutSeconds: 1800,
+    // 从 0 开始；稍后启用。
+    heartbeat: { every: "0m" },
+  },
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  },
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@quantumclaw", "quantumclaw"],
+    },
+  },
+  session: {
+    scope: "per-sender",
+    resetTriggers: ["/new", "/reset"],
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 10080,
+    },
+  },
+}
+```
+
+## 会话和记忆
+
+- 会话文件：`~/.quantumclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl`
+- 会话元数据（token 使用量、最后路由等）：`~/.quantumclaw/agents/<agentId>/sessions/sessions.json`（旧版：`~/.quantumclaw/sessions/sessions.json`）
+- `/new` 或 `/reset` 为该聊天启动新会话（可通过 `resetTriggers` 配置）。如果单独发送，智能体会回复一个简短的问候来确认重置。
+- `/compact [instructions]` 压缩会话上下文并报告剩余的上下文预算。
+
+## 心跳（主动模式）
+
+默认情况下，QuantumClaw 每 30 分钟运行一次心跳，提示词为：
+`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
+设置 `agents.defaults.heartbeat.every: "0m"` 来禁用。
+
+- 如果 `HEARTBEAT.md` 存在但实际上是空的（只有空行和 markdown 标题如 `# Heading`），QuantumClaw 会跳过心跳运行以节省 API 调用。
+- 如果文件不存在，心跳仍然运行，模型决定做什么。
+- 如果智能体回复 `HEARTBEAT_OK`（可选带有短填充；参见 `agents.defaults.heartbeat.ackMaxChars`），QuantumClaw 会为该心跳抑制出站投递。
+- 心跳运行完整的智能体轮次 — 更短的间隔会消耗更多 token。
+
+```json5
+{
+  agent: {
+    heartbeat: { every: "30m" },
+  },
+}
+```
+
+## 媒体输入和输出
+
+入站附件（图片/音频/文档）可以通过模板暴露给你的命令：
+
+- `{{MediaPath}}`（本地临时文件路径）
+- `{{MediaUrl}}`（伪 URL）
+- `{{Transcript}}`（如果启用了音频转录）
+
+来自智能体的出站附件：在单独一行包含 `MEDIA:<path-or-url>`（无空格）。示例：
+
+```
+这是截图。
+MEDIA:https://example.com/screenshot.png
+```
+
+QuantumClaw 会提取这些并将它们作为媒体与文本一起发送。
+
+## 运维检查清单
+
+```bash
+quantumclaw status          # 本地状态（凭证、会话、排队事件）
+quantumclaw status --all    # 完整诊断（只读，可粘贴）
+quantumclaw status --deep   # 添加 Gateway 网关健康探测（Telegram + Discord）
+quantumclaw health --json   # Gateway 网关健康快照（WS）
+```
+
+日志位于 `/tmp/quantumclaw/`（默认：`quantumclaw-YYYY-MM-DD.log`）。
+
+## 下一步
+
+- WebChat：[WebChat](/web/webchat)
+- Gateway 网关运维：[Gateway 网关运行手册](/gateway)
+- 定时任务 + 唤醒：[定时任务](/automation/cron-jobs)
+- macOS 菜单栏配套应用：[QuantumClaw macOS 应用](/platforms/macos)
+- iOS 节点应用：[iOS 应用](/platforms/ios)
+- Android 节点应用：[Android 应用](/platforms/android)
+- Windows 状态：[Windows (WSL2)](/platforms/windows)
+- Linux 状态：[Linux 应用](/platforms/linux)
+- 安全：[安全](/gateway/security)

package/docs/zh-CN/start/quickstart.md

@@ -0,0 +1,88 @@
+---
+read_when:
+  - 你希望以最快的方式从安装到运行一个可用的 Gateway 网关
+summary: 安装 QuantumClaw，完成 Gateway 网关新手引导，并配对你的第一个渠道。
+title: 快速开始
+x-i18n:
+  generated_at: "2026-02-04T17:53:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3c5da65996f89913cd115279ae21dcab794eadd14595951b676d8f7864fbbe2d
+  source_path: start/quickstart.md
+  workflow: 15
+---
+
+<Note>
+QuantumClaw 需要 Node 22 或更新版本。
+</Note>
+
+## 安装
+
+<Tabs>
+  <Tab title="npm">
+    ```bash
+    npm install -g quantumclaw@latest
+    ```
+  </Tab>
+  <Tab title="pnpm">
+    ```bash
+    pnpm add -g quantumclaw@latest
+    ```
+  </Tab>
+</Tabs>
+
+## 新手引导并运行 Gateway 网关
+
+<Steps>
+  <Step title="新手引导并安装服务">
+    ```bash
+    quantumclaw onboard --install-daemon
+    ```
+  </Step>
+  <Step title="配对 WhatsApp">
+    ```bash
+    quantumclaw channels login
+    ```
+  </Step>
+  <Step title="启动 Gateway 网关">
+    ```bash
+    quantumclaw gateway --port 18789
+    ```
+  </Step>
+</Steps>
+
+完成新手引导后，Gateway 网关将通过用户服务运行。你也可以使用 `quantumclaw gateway` 手动启动。
+
+<Info>
+之后在 npm 安装和 git 安装之间切换非常简单。安装另一种方式后，运行
+`quantumclaw doctor` 即可更新 Gateway 网关服务入口点。
+</Info>
+
+## 从源码安装（开发）
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+pnpm install
+pnpm ui:build # 首次运行时会自动安装 UI 依赖
+pnpm build
+quantumclaw onboard --install-daemon
+```
+
+如果你还没有全局安装，可以在仓库目录中通过 `pnpm quantumclaw ...` 运行新手引导。
+
+## 多实例快速开始（可选）
+
+```bash
+QUANTUMCLAW_CONFIG_PATH=~/.quantumclaw/a.json \
+QUANTUMCLAW_STATE_DIR=~/.quantumclaw-a \
+quantumclaw gateway --port 19001
+```
+
+## 发送测试消息
+
+需要一个正在运行的 Gateway 网关。
+
+```bash
+quantumclaw message send --target +15555550123 --message "Hello from QuantumClaw"
+```

package/docs/zh-CN/start/setup.md

@@ -0,0 +1,153 @@
+---
+read_when:
+  - 设置新机器
+  - 你想要"最新最好的"而不破坏你的个人设置
+summary: 设置指南：在保持最新的同时保持你的 QuantumClaw 设置个性化
+title: 设置
+x-i18n:
+  generated_at: "2026-02-03T07:54:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b7f4bd657d0df4feb5035c9f5ee727f9c67b991e9cedfc7768f99d010553fa01
+  source_path: start/setup.md
+  workflow: 15
+---
+
+# 设置
+
+最后更新：2026-01-01
+
+## 太长不看
+
+- **个性化设置存放在仓库之外：** `~/.quantumclaw/workspace`（工作区）+ `~/.quantumclaw/quantumclaw.json`（配置）。
+- **稳定工作流：** 安装 macOS 应用；让它运行内置的 Gateway 网关。
+- **前沿工作流：** 通过 `pnpm gateway:watch` 自己运行 Gateway 网关，然后让 macOS 应用以本地模式连接。
+
+## 先决条件（从源码）
+
+- Node `>=22`
+- `pnpm`
+- Docker（可选；仅用于容器化设置/e2e — 参阅 [Docker](/install/docker)）
+
+## 个性化策略（让更新不会造成问题）
+
+如果你想要"100% 为我定制"*并且*易于更新，将你的自定义内容保存在：
+
+- **配置：** `~/.quantumclaw/quantumclaw.json`（JSON/JSON5 格式）
+- **工作区：** `~/.quantumclaw/workspace`（Skills、提示、记忆；将其设为私有 git 仓库）
+
+引导一次：
+
+```bash
+quantumclaw setup
+```
+
+在此仓库内部，使用本地 CLI 入口：
+
+```bash
+quantumclaw setup
+```
+
+如果你还没有全局安装，通过 `pnpm quantumclaw setup` 运行它。
+
+## 稳定工作流（macOS 应用优先）
+
+1. 安装并启动 **QuantumClaw.app**（菜单栏）。
+2. 完成新手引导/权限检查清单（TCC 提示）。
+3. 确保 Gateway 网关是**本地**并正在运行（应用管理它）。
+4. 链接表面（示例：WhatsApp）：
+
+```bash
+quantumclaw channels login
+```
+
+5. 完整性检查：
+
+```bash
+quantumclaw health
+```
+
+如果你的构建版本中没有新手引导：
+
+- 运行 `quantumclaw setup`，然后 `quantumclaw channels login`，然后手动启动 Gateway 网关（`quantumclaw gateway`）。
+
+## 前沿工作流（在终端中运行 Gateway 网关）
+
+目标：开发 TypeScript Gateway 网关，获得热重载，保持 macOS 应用 UI 连接。
+
+### 0)（可选）也从源码运行 macOS 应用
+
+如果你也想让 macOS 应用保持前沿：
+
+```bash
+./scripts/restart-mac.sh
+```
+
+### 1) 启动开发 Gateway 网关
+
+```bash
+pnpm install
+pnpm gateway:watch
+```
+
+`gateway:watch` 以监视模式运行 Gateway 网关，并在 TypeScript 更改时重新加载。
+
+### 2) 将 macOS 应用指向你正在运行的 Gateway 网关
+
+在 **QuantumClaw.app** 中：
+
+- 连接模式：**本地**
+  应用将连接到在配置端口上运行的 Gateway 网关。
+
+### 3) 验证
+
+- 应用内 Gateway 网关状态应显示 **"Using existing gateway …"**
+- 或通过 CLI：
+
+```bash
+quantumclaw health
+```
+
+### 常见陷阱
+
+- **端口错误：** Gateway 网关 WS 默认为 `ws://127.0.0.1:18789`；保持应用 + CLI 在同一端口上。
+- **状态存储位置：**
+  - 凭证：`~/.quantumclaw/credentials/`
+  - 会话：`~/.quantumclaw/agents/<agentId>/sessions/`
+  - 日志：`/tmp/quantumclaw/`
+
+## 凭证存储映射
+
+在调试认证或决定备份什么时使用此映射：
+
+- **WhatsApp**：`~/.quantumclaw/credentials/whatsapp/<accountId>/creds.json`
+- **Telegram bot token**：配置/环境变量或 `channels.telegram.tokenFile`
+- **Discord bot token**：配置/环境变量（尚不支持令牌文件）
+- **Slack tokens**：配置/环境变量（`channels.slack.*`）
+- **配对允许列表**：`~/.quantumclaw/credentials/<channel>-allowFrom.json`
+- **模型认证配置文件**：`~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`
+- **旧版 OAuth 导入**：`~/.quantumclaw/credentials/oauth.json`
+  更多详情：[安全](/gateway/security#credential-storage-map)。
+
+## 更新（不破坏你的设置）
+
+- 将 `~/.quantumclaw/workspace` 和 `~/.quantumclaw/` 保持为"你的东西"；不要将个人提示/配置放入 `quantumclaw` 仓库。
+- 更新源码：`git pull` + `pnpm install`（当锁文件更改时）+ 继续使用 `pnpm gateway:watch`。
+
+## Linux（systemd 用户服务）
+
+Linux 安装使用 systemd **用户**服务。默认情况下，systemd 在注销/空闲时停止用户服务，这会终止 Gateway 网关。新手引导会尝试为你启用 lingering（可能提示 sudo）。如果仍然关闭，运行：
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+对于常驻或多用户服务器，考虑使用**系统**服务而不是用户服务（不需要 lingering）。参阅 [Gateway 网关运行手册](/gateway) 了解 systemd 说明。
+
+## 相关文档
+
+- [Gateway 网关运行手册](/gateway)（标志、监督、端口）
+- [Gateway 网关配置](/gateway/configuration)（配置模式 + 示例）
+- [Discord](/channels/discord) 和 [Telegram](/channels/telegram)（回复标签 + replyToMode 设置）
+- [QuantumClaw 助手设置](/start/quantumclaw)
+- [macOS 应用](/platforms/macos)（Gateway 网关生命周期）