@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,57 @@
+---
+read_when:
+  - 你想以非交互方式读取或编辑配置
+summary: "`quantumclaw config` 的 CLI 参考（获取/设置/取消设置配置值）"
+title: config
+x-i18n:
+  generated_at: "2026-02-03T10:04:13Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d60a35f5330f22bc99a0df090590586109d329ddd2ca294aeed191a22560c1c2
+  source_path: cli/config.md
+  workflow: 15
+---
+
+# `quantumclaw config`
+
+配置辅助命令：通过路径获取/设置/取消设置值。不带子命令运行将打开
+配置向导（与 `quantumclaw configure` 相同）。
+
+## 示例
+
+```bash
+quantumclaw config get browser.executablePath
+quantumclaw config set browser.executablePath "/usr/bin/google-chrome"
+quantumclaw config set agents.defaults.heartbeat.every "2h"
+quantumclaw config set agents.list[0].tools.exec.node "node-id-or-name"
+quantumclaw config unset plugins.entries.brave.config.webSearch.apiKey
+```
+
+## 路径
+
+路径使用点号或括号表示法：
+
+```bash
+quantumclaw config get agents.defaults.workspace
+quantumclaw config get agents.list[0].id
+```
+
+使用智能体列表索引来定位特定智能体：
+
+```bash
+quantumclaw config get agents.list
+quantumclaw config set agents.list[1].tools.exec.node "node-id-or-name"
+```
+
+## 值
+
+值会尽可能解析为 JSON5；否则将被视为字符串。
+使用 `--json` 强制要求 JSON5 解析。
+
+```bash
+quantumclaw config set agents.defaults.heartbeat.every "0m"
+quantumclaw config set gateway.port 19001 --json
+quantumclaw config set channels.whatsapp.groups '["*"]' --json
+```
+
+编辑后请重启 Gateway 网关。

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

@@ -0,0 +1,38 @@
+---
+read_when:
+  - 你想交互式地调整凭证、设备或智能体默认设置
+summary: "`quantumclaw configure` 的 CLI 参考（交互式配置提示）"
+title: configure
+x-i18n:
+  generated_at: "2026-02-03T07:44:46Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9cb2bb5237b02b3a2dca71b5e43b11bd6b9939b9e4aa9ce1882457464b51efd2
+  source_path: cli/configure.md
+  workflow: 15
+---
+
+# `quantumclaw configure`
+
+用于设置凭证、设备和智能体默认值的交互式提示。
+
+注意：**模型**部分现在包含一个用于 `agents.defaults.models` 允许列表的多选项（显示在 `/model` 和模型选择器中的内容）。
+
+提示：不带子命令的 `quantumclaw config` 会打开相同的向导。使用 `quantumclaw config get|set|unset` 进行非交互式编辑。
+
+相关内容：
+
+- Gateway 网关配置参考：[配置](/gateway/configuration)
+- Config CLI：[Config](/cli/config)
+
+注意事项：
+
+- 选择 Gateway 网关运行位置始终会更新 `gateway.mode`。如果这是你唯一需要的，可以不选择其他部分直接选择"继续"。
+- 面向渠道的服务（Slack/Discord/Matrix/Microsoft Teams）在设置期间会提示输入频道/房间允许列表。你可以输入名称或 ID；向导会尽可能将名称解析为 ID。
+
+## 示例
+
+```bash
+quantumclaw configure
+quantumclaw configure --section models --section channels
+```

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

@@ -0,0 +1,43 @@
+---
+read_when:
+  - 你需要定时作业和唤醒功能
+  - 你正在调试 cron 执行和日志
+summary: "`quantumclaw cron` 的 CLI 参考（调度和运行后台作业）"
+title: cron
+x-i18n:
+  generated_at: "2026-02-03T07:44:47Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bc9317c824f3b6339df657cc269961d9b5f121da65ec2b23a07d454e6d611135
+  source_path: cli/cron.md
+  workflow: 15
+---
+
+# `quantumclaw cron`
+
+管理 Gateway 网关调度器的 cron 作业。
+
+相关内容：
+
+- Cron 作业：[Cron 作业](/automation/cron-jobs)
+
+提示：运行 `quantumclaw cron --help` 查看完整的命令集。
+
+说明：隔离式 `cron add` 任务默认使用 `--announce` 投递摘要。使用 `--no-deliver` 仅内部运行。
+`--deliver` 仍作为 `--announce` 的弃用别名保留。
+
+说明：一次性（`--at`）任务成功后默认删除。使用 `--keep-after-run` 保留。
+
+## 常见编辑
+
+更新投递设置而不更改消息：
+
+```bash
+quantumclaw cron edit <job-id> --announce --channel telegram --to "123456789"
+```
+
+为隔离的作业禁用投递：
+
+```bash
+quantumclaw cron edit <job-id> --no-deliver
+```

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

@@ -0,0 +1,23 @@
+---
+read_when:
+  - 想要使用当前令牌打开控制界面
+  - 想要打印 URL 而不启动浏览器
+summary: "`quantumclaw dashboard` 的 CLI 参考（打开控制界面）"
+title: dashboard
+x-i18n:
+  generated_at: "2026-02-01T19:58:50Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 242a3b35ea43149be12ee2b8f2bc81b6dc24cea546a15f422dcfd0cf2e7724db
+  source_path: cli/dashboard.md
+  workflow: 14
+---
+
+# `quantumclaw dashboard`
+
+使用当前认证信息打开控制界面。
+
+```bash
+quantumclaw dashboard
+quantumclaw dashboard --no-open
+```

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

@@ -0,0 +1,74 @@
+---
+read_when:
+  - 你正在批准设备配对请求
+  - 你需要轮换或撤销设备 token
+summary: "`quantumclaw devices` 的 CLI 参考（设备配对 + token 轮换/撤销）"
+title: devices
+x-i18n:
+  generated_at: "2026-02-03T07:44:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 52f903817d2886c1dc29b85d30168d1edff7944bd120a1e139159c9d99a1f517
+  source_path: cli/devices.md
+  workflow: 15
+---
+
+# `quantumclaw devices`
+
+管理设备配对请求和设备范围的 token。
+
+## 命令
+
+### `quantumclaw devices list`
+
+列出待处理的配对请求和已配对的设备。
+
+```
+quantumclaw devices list
+quantumclaw devices list --json
+```
+
+### `quantumclaw devices approve <requestId>`
+
+批准待处理的设备配对请求。
+
+```
+quantumclaw devices approve <requestId>
+```
+
+### `quantumclaw devices reject <requestId>`
+
+拒绝待处理的设备配对请求。
+
+```
+quantumclaw devices reject <requestId>
+```
+
+### `quantumclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
+
+为特定角色轮换设备 token（可选更新 scope）。
+
+```
+quantumclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
+```
+
+### `quantumclaw devices revoke --device <id> --role <role>`
+
+为特定角色撤销设备 token。
+
+```
+quantumclaw devices revoke --device <deviceId> --role node
+```
+
+## 通用选项
+
+- `--url <url>`：Gateway 网关 WebSocket URL（配置后默认使用 `gateway.remote.url`）。
+- `--token <token>`：Gateway 网关 token（如需要）。
+- `--password <password>`：Gateway 网关密码（密码认证）。
+- `--timeout <ms>`：RPC 超时。
+- `--json`：JSON 输出（推荐用于脚本）。
+
+## 注意事项
+
+- Token 轮换会返回新 token（敏感信息）。请像对待密钥一样对待它。
+- 这些命令需要 `operator.pairing`（或 `operator.admin`）scope。

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

@@ -0,0 +1,70 @@
+---
+read_when:
+  - 你想查找某个渠道的联系人/群组/自身 ID
+  - 你正在开发渠道目录适配器
+summary: "`quantumclaw directory` 的 CLI 参考（self、peers、groups）"
+title: directory
+x-i18n:
+  generated_at: "2026-02-01T19:58:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 7c878d9013aeaa22c8a21563fac30b465a86be85d8c917c5d4591b5c3d4b2025
+  source_path: cli/directory.md
+  workflow: 14
+---
+
+# `quantumclaw directory`
+
+对支持目录功能的渠道进行查找（联系人/对等方、群组和"我"）。
+
+## 通用参数
+
+- `--channel <name>`：渠道 ID/别名（配置了多个渠道时为必填；仅配置一个渠道时自动选择）
+- `--account <id>`：账号 ID（默认：渠道默认账号）
+- `--json`：输出 JSON 格式
+
+## 说明
+
+- `directory` 用于帮助你查找可粘贴到其他命令中的 ID（特别是 `quantumclaw message send --target ...`）。
+- 对于许多渠道，结果来源于配置（允许列表/已配置的群组），而非实时的提供商目录。
+- 默认输出为以制表符分隔的 `id`（有时包含 `name`）；脚本中请使用 `--json`。
+
+## 将结果用于 `message send`
+
+```bash
+quantumclaw directory peers list --channel slack --query "U0"
+quantumclaw message send --channel slack --target user:U012ABCDEF --message "hello"
+```
+
+## ID 格式（按渠道）
+
+- WhatsApp：`+15551234567`（私聊），`1234567890-1234567890@g.us`（群组）
+- Telegram：`@username` 或数字聊天 ID；群组为数字 ID
+- Slack：`user:U…` 和 `channel:C…`
+- Discord：`user:<id>` 和 `channel:<id>`
+- Matrix（插件）：`user:@user:server`、`room:!roomId:server` 或 `#alias:server`
+- Microsoft Teams（插件）：`user:<id>` 和 `conversation:<id>`
+- Zalo（插件）：用户 ID（Bot API）
+- Zalo Personal / `zalouser`（插件）：来自 `zca` 的会话 ID（私聊/群组）（`me`、`friend list`、`group list`）
+
+## Self（"我"）
+
+```bash
+quantumclaw directory self --channel zalouser
+```
+
+## Peers（联系人/用户）
+
+```bash
+quantumclaw directory peers list --channel zalouser
+quantumclaw directory peers list --channel zalouser --query "name"
+quantumclaw directory peers list --channel zalouser --limit 50
+```
+
+## 群组
+
+```bash
+quantumclaw directory groups list --channel zalouser
+quantumclaw directory groups list --channel zalouser --query "work"
+quantumclaw directory groups members --channel zalouser --group-id <id>
+```

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

@@ -0,0 +1,30 @@
+---
+read_when:
+  - 你想通过 Tailscale + CoreDNS 实现广域设备发现（DNS-SD）
+  - You’re setting up split DNS for a custom discovery domain (example: quantumclaw.internal)
+summary: "`quantumclaw dns` 的 CLI 参考（广域设备发现辅助工具）"
+title: dns
+x-i18n:
+  generated_at: "2026-02-03T07:44:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d2011e41982ffb4b71ab98211574529bc1c8b7769ab1838abddd593f42b12380
+  source_path: cli/dns.md
+  workflow: 15
+---
+
+# `quantumclaw dns`
+
+用于广域设备发现（Tailscale + CoreDNS）的 DNS 辅助工具。目前专注于 macOS + Homebrew CoreDNS。
+
+相关内容：
+
+- Gateway 网关设备发现：[设备发现](/gateway/discovery)
+- 广域设备发现配置：[配置](/gateway/configuration)
+
+## 设置
+
+```bash
+quantumclaw dns setup
+quantumclaw dns setup --apply
+```

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

@@ -0,0 +1,22 @@
+---
+read_when:
+  - 你想从终端搜索实时 QuantumClaw 文档
+summary: "`quantumclaw docs` 的 CLI 参考（搜索实时文档索引）"
+title: docs
+x-i18n:
+  generated_at: "2026-02-03T07:44:50Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 7a4000e91f7c6ed1140f684e2d1849577651e9389c5c90532a74db58c0b86d47
+  source_path: cli/docs.md
+  workflow: 15
+---
+
+# `quantumclaw docs`
+
+搜索实时文档索引。
+
+```bash
+quantumclaw docs browser extension
+quantumclaw docs sandbox allowHostControl
+```

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

@@ -0,0 +1,48 @@
+---
+read_when:
+  - 你遇到连接/认证问题，需要引导式修复
+  - 你更新后想进行完整性检查
+summary: "`quantumclaw doctor` 的 CLI 参考（健康检查 + 引导式修复）"
+title: doctor
+x-i18n:
+  generated_at: "2026-02-03T10:04:15Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 92310aa3f3d111e91a74ce1150359d5d8a8d70a856666d9419e16c60d78209f2
+  source_path: cli/doctor.md
+  workflow: 15
+---
+
+# `quantumclaw doctor`
+
+Gateway 网关和渠道的健康检查 + 快速修复。
+
+相关内容：
+
+- 故障排除：[故障排除](/gateway/troubleshooting)
+- 安全审计：[安全](/gateway/security)
+
+## 示例
+
+```bash
+quantumclaw doctor
+quantumclaw doctor --repair
+quantumclaw doctor --deep
+```
+
+注意事项：
+
+- 交互式提示（如钥匙串/OAuth 修复）仅在 stdin 是 TTY 且**未**设置 `--non-interactive` 时运行。无头运行（cron、Telegram、无终端）将跳过提示。
+- `--fix`（`--repair` 的别名）会将备份写入 `~/.quantumclaw/quantumclaw.json.bak`，并删除未知的配置键，同时列出每个删除项。
+
+## macOS：`launchctl` 环境变量覆盖
+
+如果你之前运行过 `launchctl setenv QUANTUMCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），该值会覆盖你的配置文件，并可能导致持续的"未授权"错误。
+
+```bash
+launchctl getenv QUANTUMCLAW_GATEWAY_TOKEN
+launchctl getenv QUANTUMCLAW_GATEWAY_PASSWORD
+
+launchctl unsetenv QUANTUMCLAW_GATEWAY_TOKEN
+launchctl unsetenv QUANTUMCLAW_GATEWAY_PASSWORD
+```

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

@@ -0,0 +1,206 @@
+---
+read_when:
+  - 从 CLI 运行 Gateway 网关（开发或服务器）
+  - 调试 Gateway 网关认证、绑定模式和连接性
+  - 通过 Bonjour 发现 Gateway 网关（局域网 + tailnet）
+summary: QuantumClaw Gateway 网关 CLI（`quantumclaw gateway`）— 运行、查询和发现 Gateway 网关
+title: gateway
+x-i18n:
+  generated_at: "2026-02-03T07:45:15Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 054dd48056e4784f153c6511c8eb35b56f239db8d4e629661841a00259e9abbf
+  source_path: cli/gateway.md
+  workflow: 15
+---
+
+# Gateway 网关 CLI
+
+Gateway 网关是 QuantumClaw 的 WebSocket 服务器（渠道、节点、会话、hooks）。
+
+本页中的子命令位于 `quantumclaw gateway …` 下。
+
+相关文档：
+
+- [/gateway/bonjour](/gateway/bonjour)
+- [/gateway/discovery](/gateway/discovery)
+- [/gateway/configuration](/gateway/configuration)
+
+## 运行 Gateway 网关
+
+运行本地 Gateway 网关进程：
+
+```bash
+quantumclaw gateway
+```
+
+前台运行别名：
+
+```bash
+quantumclaw gateway run
+```
+
+注意事项：
+
+- 默认情况下，除非在 `~/.quantumclaw/quantumclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关将拒绝启动。使用 `--allow-unconfigured` 进行临时/开发运行。
+- 在没有认证的情况下绑定到 loopback 之外的地址会被阻止（安全护栏）。
+- `SIGUSR1` 在授权时触发进程内重启（启用 `commands.restart` 或使用 gateway 工具/config apply/update）。
+- `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。
+
+### 选项
+
+- `--port <port>`：WebSocket 端口（默认来自配置/环境变量；通常为 `18789`）。
+- `--bind <loopback|lan|tailnet|auto|custom>`：监听器绑定模式。
+- `--auth <token|password>`：认证模式覆盖。
+- `--token <token>`：令牌覆盖（同时为进程设置 `QUANTUMCLAW_GATEWAY_TOKEN`）。
+- `--password <password>`：密码覆盖（同时为进程设置 `QUANTUMCLAW_GATEWAY_PASSWORD`）。
+- `--tailscale <off|serve|funnel>`：通过 Tailscale 暴露 Gateway 网关。
+- `--tailscale-reset-on-exit`：关闭时重置 Tailscale serve/funnel 配置。
+- `--allow-unconfigured`：允许在配置中没有 `gateway.mode=local` 的情况下启动 Gateway 网关。
+- `--dev`：如果缺失则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。
+- `--reset`：重置开发配置 + 凭证 + 会话 + 工作区（需要 `--dev`）。
+- `--force`：启动前杀死所选端口上的任何现有监听器。
+- `--verbose`：详细日志。
+- `--claude-cli-logs`：仅在控制台显示 claude-cli 日志（并启用其 stdout/stderr）。
+- `--ws-log <auto|full|compact>`：WebSocket 日志样式（默认 `auto`）。
+- `--compact`：`--ws-log compact` 的别名。
+- `--raw-stream`：将原始模型流事件记录到 jsonl。
+- `--raw-stream-path <path>`：原始流 jsonl 路径。
+
+## 查询运行中的 Gateway 网关
+
+所有查询命令使用 WebSocket RPC。
+
+输出模式：
+
+- 默认：人类可读（TTY 中带颜色）。
+- `--json`：机器可读 JSON（无样式/进度指示器）。
+- `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI 但保持人类可读布局。
+
+共享选项（在支持的地方）：
+
+- `--url <url>`：Gateway 网关 WebSocket URL。
+- `--token <token>`：Gateway 网关令牌。
+- `--password <password>`：Gateway 网关密码。
+- `--timeout <ms>`：超时/预算（因命令而异）。
+- `--expect-final`：等待"最终"响应（智能体调用）。
+
+### `gateway health`
+
+```bash
+quantumclaw gateway health --url ws://127.0.0.1:18789
+```
+
+### `gateway status`
+
+`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks）以及可选的 RPC 探测。
+
+```bash
+quantumclaw gateway status
+quantumclaw gateway status --json
+```
+
+选项：
+
+- `--url <url>`：覆盖探测 URL。
+- `--token <token>`：探测的令牌认证。
+- `--password <password>`：探测的密码认证。
+- `--timeout <ms>`：探测超时（默认 `10000`）。
+- `--no-probe`：跳过 RPC 探测（仅服务视图）。
+- `--deep`：也扫描系统级服务。
+
+### `gateway probe`
+
+`gateway probe` 是"调试一切"命令。它始终探测：
+
+- 你配置的远程 Gateway 网关（如果设置了），以及
+- localhost（loopback）**即使配置了远程也会探测**。
+
+如果多个 Gateway 网关可达，它会打印所有。当你使用隔离的配置文件/端口（例如救援机器人）时支持多个 Gateway 网关，但大多数安装仍然运行单个 Gateway 网关。
+
+```bash
+quantumclaw gateway probe
+quantumclaw gateway probe --json
+```
+
+#### 通过 SSH 远程（Mac 应用对等）
+
+macOS 应用的"通过 SSH 远程"模式使用本地端口转发，因此远程 Gateway 网关（可能仅绑定到 loopback）变得可以通过 `ws://127.0.0.1:<port>` 访问。
+
+CLI 等效命令：
+
+```bash
+quantumclaw gateway probe --ssh user@gateway-host
+```
+
+选项：
+
+- `--ssh <target>`：`user@host` 或 `user@host:port`（端口默认为 `22`）。
+- `--ssh-identity <path>`：身份文件。
+- `--ssh-auto`：选择第一个发现的 Gateway 网关主机作为 SSH 目标（仅限局域网/WAB）。
+
+配置（可选，用作默认值）：
+
+- `gateway.remote.sshTarget`
+- `gateway.remote.sshIdentity`
+
+### `gateway call <method>`
+
+低级 RPC 辅助工具。
+
+```bash
+quantumclaw gateway call status
+quantumclaw gateway call logs.tail --params '{"sinceMs": 60000}'
+```
+
+## 管理 Gateway 网关服务
+
+```bash
+quantumclaw gateway install
+quantumclaw gateway start
+quantumclaw gateway stop
+quantumclaw gateway restart
+quantumclaw gateway uninstall
+```
+
+注意事项：
+
+- `gateway install` 支持 `--port`、`--runtime`、`--token`、`--force`、`--json`。
+- 生命周期命令接受 `--json` 用于脚本。
+
+## 发现 Gateway 网关（Bonjour）
+
+`gateway discover` 扫描 Gateway 网关信标（`_quantumclaw-gw._tcp`）。
+
+- 组播 DNS-SD：`local.`
+- 单播 DNS-SD（广域 Bonjour）：选择一个域（示例：`quantumclaw.internal.`）并设置分割 DNS + DNS 服务器；参见 [/gateway/bonjour](/gateway/bonjour)
+
+只有启用了 Bonjour 发现（默认）的 Gateway 网关才会广播信标。
+
+广域发现记录包括（TXT）：
+
+- `role`（Gateway 网关角色提示）
+- `transport`（传输提示，例如 `gateway`）
+- `gatewayPort`（WebSocket 端口，通常为 `18789`）
+- `sshPort`（SSH 端口；如果不存在则默认为 `22`）
+- `tailnetDns`（MagicDNS 主机名，如果可用）
+- `gatewayTls` / `gatewayTlsSha256`（TLS 启用 + 证书指纹）
+- `cliPath`（远程安装的可选提示）
+
+### `gateway discover`
+
+```bash
+quantumclaw gateway discover
+```
+
+选项：
+
+- `--timeout <ms>`：每个命令的超时（浏览/解析）；默认 `2000`。
+- `--json`：机器可读输出（同时禁用样式/进度指示器）。
+
+示例：
+
+```bash
+quantumclaw gateway discover --timeout 4000
+quantumclaw gateway discover --json | jq '.beacons[].wsUrl'
+```

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

@@ -0,0 +1,28 @@
+---
+read_when:
+  - 你想快速检查运行中的 Gateway 网关健康状态
+summary: "`quantumclaw health` 的 CLI 参考（通过 RPC 获取 Gateway 网关健康端点）"
+title: health
+x-i18n:
+  generated_at: "2026-02-03T07:44:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 82a78a5a97123f7a5736699ae8d793592a736f336c5caced9eba06d14d973fd7
+  source_path: cli/health.md
+  workflow: 15
+---
+
+# `quantumclaw health`
+
+从运行中的 Gateway 网关获取健康状态。
+
+```bash
+quantumclaw health
+quantumclaw health --json
+quantumclaw health --verbose
+```
+
+注意：
+
+- `--verbose` 运行实时探测，并在配置了多个账户时打印每个账户的耗时。
+- 当配置了多个智能体时，输出包括每个智能体的会话存储。