@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/channels/zalouser.md

@@ -0,0 +1,147 @@
+---
+read_when:
+  - 为 QuantumClaw 设置 Zalo Personal
+  - 调试 Zalo Personal 登录或消息流程
+summary: 通过 zca-cli（QR 登录）支持 Zalo 个人账户、功能和配置
+title: Zalo Personal
+x-i18n:
+  generated_at: "2026-02-03T07:44:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2a249728d556e5cc52274627bdaf390fa10e815afa04f4497feb57a2a0cb9261
+  source_path: channels/zalouser.md
+  workflow: 15
+---
+
+# Zalo Personal（非官方）
+
+状态：实验性。此集成通过 `zca-cli` 自动化**个人 Zalo 账户**。
+
+> **警告：**这是一个非官方集成，可能导致账户被暂停/封禁。使用风险自负。
+
+## 需要插件
+
+Zalo Personal 作为插件提供，不包含在核心安装中。
+
+- 通过 CLI 安装：`quantumclaw plugins install @quantumclaw/zalouser`
+- 或从源码检出安装：`quantumclaw plugins install ./extensions/zalouser`
+- 详情：[插件](/tools/plugin)
+
+## 前置条件：zca-cli
+
+Gateway 网关机器必须在 `PATH` 中有可用的 `zca` 二进制文件。
+
+- 验证：`zca --version`
+- 如果缺失，请安装 zca-cli（参见 `extensions/zalouser/README.md` 或上游 zca-cli 文档）。
+
+## 快速设置（新手）
+
+1. 安装插件（见上文）。
+2. 登录（QR，在 Gateway 网关机器上）：
+   - `quantumclaw channels login --channel zalouser`
+   - 用 Zalo 手机应用扫描终端中的二维码。
+3. 启用渠道：
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+4. 重启 Gateway 网关（或完成新手引导）。
+5. 私信访问默认为配对模式；首次联系时批准配对码。
+
+## 这是什么
+
+- 使用 `zca listen` 接收入站消息。
+- 使用 `zca msg ...` 发送回复（文本/媒体/链接）。
+- 专为"个人账户"使用场景设计，适用于 Zalo Bot API 不可用的情况。
+
+## 命名
+
+渠道 ID 为 `zalouser`，以明确表示这是自动化**个人 Zalo 用户账户**（非官方）。我们保留 `zalo` 用于未来可能的官方 Zalo API 集成。
+
+## 查找 ID（目录）
+
+使用目录 CLI 发现联系人/群组及其 ID：
+
+```bash
+quantumclaw directory self --channel zalouser
+quantumclaw directory peers list --channel zalouser --query "name"
+quantumclaw directory groups list --channel zalouser --query "work"
+```
+
+## 限制
+
+- 出站文本分块为约 2000 字符（Zalo 客户端限制）。
+- 默认阻止流式传输。
+
+## 访问控制（私信）
+
+`channels.zalouser.dmPolicy` 支持：`pairing | allowlist | open | disabled`（默认：`pairing`）。
+`channels.zalouser.allowFrom` 接受用户 ID 或名称。向导会在可用时通过 `zca friend find` 将名称解析为 ID。
+
+通过以下方式批准：
+
+- `quantumclaw pairing list zalouser`
+- `quantumclaw pairing approve zalouser <code>`
+
+## 群组访问（可选）
+
+- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。使用 `channels.defaults.groupPolicy` 在未设置时覆盖默认值。
+- 通过以下方式限制为允许列表：
+  - `channels.zalouser.groupPolicy = "allowlist"`
+  - `channels.zalouser.groups`（键为群组 ID 或名称）
+- 阻止所有群组：`channels.zalouser.groupPolicy = "disabled"`。
+- 配置向导可以提示输入群组允许列表。
+- 启动时，QuantumClaw 将允许列表中的群组/用户名称解析为 ID 并记录映射；未解析的条目保持原样。
+
+示例：
+
+```json5
+{
+  channels: {
+    zalouser: {
+      groupPolicy: "allowlist",
+      groups: {
+        "123456789": { allow: true },
+        "Work Chat": { allow: true },
+      },
+    },
+  },
+}
+```
+
+## 多账户
+
+账户映射到 zca 配置文件。示例：
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      defaultAccount: "default",
+      accounts: {
+        work: { enabled: true, profile: "work" },
+      },
+    },
+  },
+}
+```
+
+## 故障排除
+
+**找不到 `zca`：**
+
+- 安装 zca-cli 并确保它在 Gateway 网关进程的 `PATH` 中。
+
+**登录不保持：**
+
+- `quantumclaw channels status --probe`
+- 重新登录：`quantumclaw channels logout --channel zalouser && quantumclaw channels login --channel zalouser`

package/docs/zh-CN/cli/acp.md

@@ -0,0 +1,173 @@
+---
+read_when:
+  - 设置基于 ACP 的 IDE 集成
+  - 调试到 Gateway 网关的 ACP 会话路由
+summary: 运行用于 IDE 集成的 ACP 桥接器
+title: acp
+x-i18n:
+  generated_at: "2026-02-03T07:44:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0c09844297da250bc1a558423e7e534d6b6be9045de12d797c07ecd64a0c63ed
+  source_path: cli/acp.md
+  workflow: 15
+---
+
+# acp
+
+运行与 QuantumClaw Gateway 网关通信的 ACP（Agent Client Protocol）桥接器。
+
+此命令通过 stdio 使用 ACP 协议与 IDE 通信，并通过 WebSocket 将提示转发到 Gateway 网关。它将 ACP 会话映射到 Gateway 网关会话键。
+
+## 用法
+
+```bash
+quantumclaw acp
+
+# Remote Gateway
+quantumclaw acp --url wss://gateway-host:18789 --token <token>
+
+# Attach to an existing session key
+quantumclaw acp --session agent:main:main
+
+# Attach by label (must already exist)
+quantumclaw acp --session-label "support inbox"
+
+# Reset the session key before the first prompt
+quantumclaw acp --session agent:main:main --reset-session
+```
+
+## ACP 客户端（调试）
+
+使用内置 ACP 客户端在没有 IDE 的情况下检查桥接器的安装完整性。
+它会启动 ACP 桥接器并让你交互式输入提示。
+
+```bash
+quantumclaw acp client
+
+# Point the spawned bridge at a remote Gateway
+quantumclaw acp client --server-args --url wss://gateway-host:18789 --token <token>
+
+# Override the server command (default: quantumclaw)
+quantumclaw acp client --server "node" --server-args quantumclaw.mjs acp --url ws://127.0.0.1:19001
+```
+
+## 如何使用
+
+当 IDE（或其他客户端）使用 Agent Client Protocol 并且你希望它驱动 QuantumClaw Gateway 网关会话时，请使用 ACP。
+
+1. 确保 Gateway 网关正在运行（本地或远程）。
+2. 配置 Gateway 网关目标（配置或标志）。
+3. 将你的 IDE 配置为通过 stdio 运行 `quantumclaw acp`。
+
+示例配置（持久化）：
+
+```bash
+quantumclaw config set gateway.remote.url wss://gateway-host:18789
+quantumclaw config set gateway.remote.token <token>
+```
+
+示例直接运行（不写入配置）：
+
+```bash
+quantumclaw acp --url wss://gateway-host:18789 --token <token>
+```
+
+## 选择智能体
+
+ACP 不直接选择智能体。它通过 Gateway 网关会话键进行路由。
+
+使用智能体作用域的会话键来定位特定智能体：
+
+```bash
+quantumclaw acp --session agent:main:main
+quantumclaw acp --session agent:design:main
+quantumclaw acp --session agent:qa:bug-123
+```
+
+每个 ACP 会话映射到单个 Gateway 网关会话键。一个智能体可以有多个会话；除非你覆盖键或标签，否则 ACP 默认使用隔离的 `acp:<uuid>` 会话。
+
+## Zed 编辑器设置
+
+在 `~/.config/zed/settings.json` 中添加自定义 ACP 智能体（或使用 Zed 的设置界面）：
+
+```json
+{
+  "agent_servers": {
+    "QuantumClaw ACP": {
+      "type": "custom",
+      "command": "quantumclaw",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+要定位特定的 Gateway 网关或智能体：
+
+```json
+{
+  "agent_servers": {
+    "QuantumClaw ACP": {
+      "type": "custom",
+      "command": "quantumclaw",
+      "args": [
+        "acp",
+        "--url",
+        "wss://gateway-host:18789",
+        "--token",
+        "<token>",
+        "--session",
+        "agent:design:main"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+在 Zed 中，打开 Agent 面板并选择"QuantumClaw ACP"来开始一个会话。
+
+## 会话映射
+
+默认情况下，ACP 会话获得一个带有 `acp:` 前缀的隔离 Gateway 网关会话键。
+要重用已知会话，请传递会话键或标签：
+
+- `--session <key>`：使用特定的 Gateway 网关会话键。
+- `--session-label <label>`：通过标签解析现有会话。
+- `--reset-session`：为该键生成新的会话 ID（相同键，新对话记录）。
+
+如果你的 ACP 客户端支持元数据，你可以按会话覆盖：
+
+```json
+{
+  "_meta": {
+    "sessionKey": "agent:main:main",
+    "sessionLabel": "support inbox",
+    "resetSession": true
+  }
+}
+```
+
+在 [/concepts/session](/concepts/session) 了解更多关于会话键的信息。
+
+## 选项
+
+- `--url <url>`：Gateway 网关 WebSocket URL（配置后默认为 gateway.remote.url）。
+- `--token <token>`：Gateway 网关认证令牌。
+- `--password <password>`：Gateway 网关认证密码。
+- `--session <key>`：默认会话键。
+- `--session-label <label>`：要解析的默认会话标签。
+- `--require-existing`：如果会话键/标签不存在则失败。
+- `--reset-session`：在首次使用前重置会话键。
+- `--no-prefix-cwd`：不在提示前添加工作目录前缀。
+- `--verbose, -v`：向 stderr 输出详细日志。
+
+### `acp client` 选项
+
+- `--cwd <dir>`：ACP 会话的工作目录。
+- `--server <command>`：ACP 服务器命令（默认：`quantumclaw`）。
+- `--server-args <args...>`：传递给 ACP 服务器的额外参数。
+- `--server-verbose`：启用 ACP 服务器的详细日志。
+- `--verbose, -v`：详细客户端日志。

package/docs/zh-CN/cli/agent.md

@@ -0,0 +1,30 @@
+---
+read_when:
+  - 你想从脚本运行一个智能体回合（可选发送回复）
+summary: "`quantumclaw agent` 的 CLI 参考（通过 Gateway 网关发送一个智能体回合）"
+title: agent
+x-i18n:
+  generated_at: "2026-02-03T07:44:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: dcf12fb94e207c68645f58235792596d65afecf8216b8f9ab3acb01e03b50a33
+  source_path: cli/agent.md
+  workflow: 15
+---
+
+# `quantumclaw agent`
+
+通过 Gateway 网关运行智能体回合（使用 `--local` 进行嵌入式运行）。使用 `--agent <id>` 直接指定已配置的智能体。
+
+相关内容：
+
+- 智能体发送工具：[Agent send](/tools/agent-send)
+
+## 示例
+
+```bash
+quantumclaw agent --to +15555550123 --message "status update" --deliver
+quantumclaw agent --agent ops --message "Summarize logs"
+quantumclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
+quantumclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+```

package/docs/zh-CN/cli/agents.md

@@ -0,0 +1,82 @@
+---
+read_when:
+  - 你需要多个隔离的智能体（工作区 + 路由 + 认证）
+summary: "`quantumclaw agents` 的 CLI 参考（列出/添加/删除/设置身份）"
+title: agents
+x-i18n:
+  generated_at: "2026-02-01T19:58:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 30556d81636a9ad8972573cc6b498e620fd266e1dfb16eef3f61096ea62f9896
+  source_path: cli/agents.md
+  workflow: 14
+---
+
+# `quantumclaw agents`
+
+管理隔离的智能体（工作区 + 认证 + 路由）。
+
+相关内容：
+
+- 多智能体路由：[多智能体路由](/concepts/multi-agent)
+- 智能体工作区：[智能体工作区](/concepts/agent-workspace)
+
+## 示例
+
+```bash
+quantumclaw agents list
+quantumclaw agents add work --workspace ~/.quantumclaw/workspace-work
+quantumclaw agents set-identity --workspace ~/.quantumclaw/workspace --from-identity
+quantumclaw agents set-identity --agent main --avatar avatars/quantumclaw.png
+quantumclaw agents delete work
+```
+
+## 身份文件
+
+每个智能体工作区可以在工作区根目录包含一个 `IDENTITY.md`：
+
+- 示例路径：`~/.quantumclaw/workspace/IDENTITY.md`
+- `set-identity --from-identity` 从工作区根目录读取（或从显式指定的 `--identity-file` 读取）
+
+头像路径相对于工作区根目录解析。
+
+## 设置身份
+
+`set-identity` 将字段写入 `agents.list[].identity`：
+
+- `name`
+- `theme`
+- `emoji`
+- `avatar`（工作区相对路径、http(s) URL 或 data URI）
+
+从 `IDENTITY.md` 加载：
+
+```bash
+quantumclaw agents set-identity --workspace ~/.quantumclaw/workspace --from-identity
+```
+
+显式覆盖字段：
+
+```bash
+quantumclaw agents set-identity --agent main --name "QuantumClaw" --emoji "🦞" --avatar avatars/quantumclaw.png
+```
+
+配置示例：
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "QuantumClaw",
+          theme: "space lobster",
+          emoji: "🦞",
+          avatar: "avatars/quantumclaw.png",
+        },
+      },
+    ],
+  },
+}
+```

package/docs/zh-CN/cli/approvals.md

@@ -0,0 +1,57 @@
+---
+read_when:
+  - 你想通过 CLI 编辑执行审批
+  - 你需要管理 Gateway 网关或节点主机上的允许列表
+summary: CLI 参考：`quantumclaw approvals`（Gateway 网关或节点主机的执行审批）
+title: approvals
+x-i18n:
+  generated_at: "2026-02-03T10:04:09Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4329cdaaec2c5f5d619415b6431196512d4834dc1ccd7363576f03dd9b845130
+  source_path: cli/approvals.md
+  workflow: 15
+---
+
+# `quantumclaw approvals`
+
+管理**本地主机**、**Gateway 网关主机**或**节点主机**的执行审批。
+默认情况下，命令针对磁盘上的本地审批文件。使用 `--gateway` 可针对 Gateway 网关，使用 `--node` 可针对特定节点。
+
+相关内容：
+
+- 执行审批：[执行审批](/tools/exec-approvals)
+- 节点：[节点](/nodes)
+
+## 常用命令
+
+```bash
+quantumclaw approvals get
+quantumclaw approvals get --node <id|name|ip>
+quantumclaw approvals get --gateway
+```
+
+## 从文件替换审批
+
+```bash
+quantumclaw approvals set --file ./exec-approvals.json
+quantumclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
+quantumclaw approvals set --gateway --file ./exec-approvals.json
+```
+
+## 允许列表辅助命令
+
+```bash
+quantumclaw approvals allowlist add "~/Projects/**/bin/rg"
+quantumclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
+quantumclaw approvals allowlist add --agent "*" "/usr/bin/uname"
+
+quantumclaw approvals allowlist remove "~/Projects/**/bin/rg"
+```
+
+## 注意事项
+
+- `--node` 使用与 `quantumclaw nodes` 相同的解析器（id、name、ip 或 id 前缀）。
+- `--agent` 默认为 `"*"`，表示适用于所有智能体。
+- 节点主机必须公开 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
+- 审批文件按主机存储在 `~/.quantumclaw/exec-approvals.json`。

package/docs/zh-CN/cli/browser.md

@@ -0,0 +1,114 @@
+---
+read_when:
+  - 你使用 `quantumclaw browser` 并想要常见任务的示例
+  - 你想通过 node host 控制在另一台机器上运行的浏览器
+  - 你想使用 Chrome 扩展中继（通过工具栏按钮附加/分离）
+summary: "`quantumclaw browser` 的 CLI 参考（配置文件、标签页、操作、扩展中继）"
+title: browser
+x-i18n:
+  generated_at: "2026-02-03T07:44:49Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: af35adfd68726fd519c704d046451effd330458c2b8305e713137fb07b2571fd
+  source_path: cli/browser.md
+  workflow: 15
+---
+
+# `quantumclaw browser`
+
+管理 QuantumClaw 的浏览器控制服务器并运行浏览器操作（标签页、快照、截图、导航、点击、输入）。
+
+相关：
+
+- 浏览器工具 + API：[浏览器工具](/tools/browser)
+- Chrome 扩展中继：[Chrome 扩展](/tools/chrome-extension)
+
+## 通用标志
+
+- `--url <gatewayWsUrl>`：Gateway 网关 WebSocket URL（默认从配置获取）。
+- `--token <token>`：Gateway 网关令牌（如果需要）。
+- `--timeout <ms>`：请求超时（毫秒）。
+- `--browser-profile <name>`：选择浏览器配置文件（默认从配置获取）。
+- `--json`：机器可读输出（在支持的地方）。
+
+## 快速开始（本地）
+
+```bash
+quantumclaw browser --browser-profile chrome tabs
+quantumclaw browser --browser-profile quantumclaw start
+quantumclaw browser --browser-profile quantumclaw open https://example.com
+quantumclaw browser --browser-profile quantumclaw snapshot
+```
+
+## 配置文件
+
+配置文件是命名的浏览器路由配置。实际上：
+
+- `quantumclaw`：启动/附加到专用的 QuantumClaw 管理的 Chrome 实例（隔离的用户数据目录）。
+- `chrome`：通过 Chrome 扩展中继控制你现有的 Chrome 标签页。
+
+```bash
+quantumclaw browser profiles
+quantumclaw browser create-profile --name work --color "#FF5A36"
+quantumclaw browser delete-profile --name work
+```
+
+使用特定配置文件：
+
+```bash
+quantumclaw browser --browser-profile work tabs
+```
+
+## 标签页
+
+```bash
+quantumclaw browser tabs
+quantumclaw browser open https://docs.quantumclaw.ai
+quantumclaw browser focus <targetId>
+quantumclaw browser close <targetId>
+```
+
+## 快照 / 截图 / 操作
+
+快照：
+
+```bash
+quantumclaw browser snapshot
+```
+
+截图：
+
+```bash
+quantumclaw browser screenshot
+```
+
+导航/点击/输入（基于 ref 的 UI 自动化）：
+
+```bash
+quantumclaw browser navigate https://example.com
+quantumclaw browser click <ref>
+quantumclaw browser type <ref> "hello"
+```
+
+## Chrome 扩展中继（通过工具栏按钮附加）
+
+此模式让智能体控制你手动附加的现有 Chrome 标签页（不会自动附加）。
+
+将未打包的扩展安装到稳定路径：
+
+```bash
+quantumclaw browser extension install
+quantumclaw browser extension path
+```
+
+然后 Chrome → `chrome://extensions` → 启用"开发者模式" → "加载已解压的扩展程序" → 选择打印的文件夹。
+
+完整指南：[Chrome 扩展](/tools/chrome-extension)
+
+## 远程浏览器控制（node host 代理）
+
+如果 Gateway 网关与浏览器运行在不同的机器上，在有 Chrome/Brave/Edge/Chromium 的机器上运行 **node host**。Gateway 网关会将浏览器操作代理到该节点（无需单独的浏览器控制服务器）。
+
+使用 `gateway.nodes.browser.mode` 控制自动路由，使用 `gateway.nodes.browser.node` 在连接多个节点时固定特定节点。
+
+安全 + 远程设置：[浏览器工具](/tools/browser)、[远程访问](/gateway/remote)、[Tailscale](/gateway/tailscale)、[安全](/gateway/security)

package/docs/zh-CN/cli/channels.md

@@ -0,0 +1,86 @@
+---
+read_when:
+  - 你想添加/删除渠道账户（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage）
+  - 你想检查渠道状态或跟踪渠道日志
+summary: "`quantumclaw channels` 的 CLI 参考（账户、状态、登录/登出、日志）"
+title: channels
+x-i18n:
+  generated_at: "2026-02-03T07:44:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 16ab1642f247bfa96e8e08dfeb1eedfccb148f40d91099f5423f971df2b54e20
+  source_path: cli/channels.md
+  workflow: 15
+---
+
+# `quantumclaw channels`
+
+管理 Gateway 网关上的聊天渠道账户及其运行时状态。
+
+相关文档：
+
+- 渠道指南：[渠道](/channels/index)
+- Gateway 网关配置：[配置](/gateway/configuration)
+
+## 常用命令
+
+```bash
+quantumclaw channels list
+quantumclaw channels status
+quantumclaw channels capabilities
+quantumclaw channels capabilities --channel discord --target channel:123
+quantumclaw channels resolve --channel slack "#general" "@jane"
+quantumclaw channels logs --channel all
+```
+
+## 添加/删除账户
+
+```bash
+quantumclaw channels add --channel telegram --token <bot-token>
+quantumclaw channels remove --channel telegram --delete
+```
+
+提示：`quantumclaw channels add --help` 显示每个渠道的标志（token、app token、signal-cli 路径等）。
+
+## 登录/登出（交互式）
+
+```bash
+quantumclaw channels login --channel whatsapp
+quantumclaw channels logout --channel whatsapp
+```
+
+## 故障排除
+
+- 运行 `quantumclaw status --deep` 进行全面探测。
+- 使用 `quantumclaw doctor` 获取引导式修复。
+- `quantumclaw channels list` 输出 `Claude: HTTP 403 ... user:profile` → 用量快照需要 `user:profile` 权限范围。使用 `--no-usage`，或提供 claude.ai 会话密钥（`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`），或通过 Claude Code CLI 重新授权。
+
+## 能力探测
+
+获取提供商能力提示（可用的 intents/scopes）以及静态功能支持：
+
+```bash
+quantumclaw channels capabilities
+quantumclaw channels capabilities --channel discord --target channel:123
+```
+
+说明：
+
+- `--channel` 是可选的；省略它可列出所有渠道（包括扩展）。
+- `--target` 接受 `channel:<id>` 或原始数字频道 id，仅适用于 Discord。
+- 探测是特定于提供商的：Discord intents + 可选的频道权限；Slack bot + user scopes；Telegram bot 标志 + webhook；Signal daemon 版本；MS Teams app token + Graph roles/scopes（在已知处标注）。没有探测功能的渠道报告 `Probe: unavailable`。
+
+## 解析名称为 ID
+
+使用提供商目录将渠道/用户名称解析为 ID：
+
+```bash
+quantumclaw channels resolve --channel slack "#general" "@jane"
+quantumclaw channels resolve --channel discord "My Server/#support" "@someone"
+quantumclaw channels resolve --channel matrix "Project Room"
+```
+
+说明：
+
+- 使用 `--kind user|group|auto` 强制指定目标类型。
+- 当多个条目共享相同名称时，解析优先选择活跃的匹配项。