@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,274 @@
+---
+read_when:
+  - 调整心跳频率或消息时
+  - 在心跳和 cron 之间选择定时任务方案时
+summary: 心跳轮询消息和通知规则
+title: 心跳
+x-i18n:
+  generated_at: "2026-02-03T07:48:57Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 18b017066aa2c41811b985564dd389834906f4576e85b576fb357a0eff482e69
+  source_path: gateway/heartbeat.md
+  workflow: 15
+---
+
+# 心跳（Gateway 网关）
+
+> **心跳 vs Cron？** 参见 [Cron vs 心跳](/automation/cron-vs-heartbeat) 了解何时使用哪种方案。
+
+心跳在主会话中运行**周期性智能体轮次**，使模型能够在不打扰你的情况下提醒需要关注的事项。
+
+## 快速开始（新手）
+
+1. 保持心跳启用（默认 `30m`，Anthropic OAuth/setup-token 为 `1h`）或设置你自己的频率。
+2. 在智能体工作区创建一个简单的 `HEARTBEAT.md` 检查清单（可选但推荐）。
+3. 决定心跳消息发送到哪里（默认 `target: "last"`）。
+4. 可选：启用心跳推理内容发送以提高透明度。
+5. 可选：将心跳限制在活动时段（本地时间）。
+
+配置示例：
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m",
+        target: "last",
+        // activeHours: { start: "08:00", end: "24:00" },
+        // includeReasoning: true, // 可选：同时发送单独的 `Reasoning:` 消息
+      },
+    },
+  },
+}
+```
+
+## 默认值
+
+- 间隔：`30m`（当检测到的认证模式为 Anthropic OAuth/setup-token 时为 `1h`）。设置 `agents.defaults.heartbeat.every` 或单智能体 `agents.list[].heartbeat.every`；使用 `0m` 禁用。
+- 提示内容（可通过 `agents.defaults.heartbeat.prompt` 配置）：
+  `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.`
+- 心跳提示**原样**作为用户消息发送。系统提示包含"Heartbeat"部分，运行在内部被标记。
+- 活动时段（`heartbeat.activeHours`）按配置的时区检查。在时段外，心跳会被跳过直到下一个时段内的时钟周期。
+
+## 心跳提示的用途
+
+默认提示故意设计得比较宽泛：
+
+- **后台任务**："Consider outstanding tasks"促使智能体审查待办事项（收件箱、日历、提醒、排队工作）并提醒任何紧急事项。
+- **人类签到**："Checkup sometimes on your human during day time"促使偶尔发送轻量级的"有什么需要帮助的吗？"消息，但通过使用你配置的本地时区避免夜间打扰（参见 [/concepts/timezone](/concepts/timezone)）。
+
+如果你希望心跳执行非常具体的任务（例如"检查 Gmail PubSub 统计"或"验证 Gateway 网关健康状态"），将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义内容（原样发送）。
+
+## 响应约定
+
+- 如果没有需要关注的事项，回复 **`HEARTBEAT_OK`**。
+- 在心跳运行期间，当 `HEARTBEAT_OK` 出现在回复的**开头或结尾**时，QuantumClaw 将其视为确认。该标记会被移除，如果剩余内容 **≤ `ackMaxChars`**（默认：300），则回复被丢弃。
+- 如果 `HEARTBEAT_OK` 出现在回复的**中间**，则不会被特殊处理。
+- 对于警报，**不要**包含 `HEARTBEAT_OK`；只返回警报文本。
+
+在心跳之外，消息开头/结尾的意外 `HEARTBEAT_OK` 会被移除并记录日志；仅包含 `HEARTBEAT_OK` 的消息会被丢弃。
+
+## 配置
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m", // 默认：30m（0m 禁用）
+        model: "anthropic/claude-opus-4-5",
+        includeReasoning: false, // 默认：false（可用时发送单独的 Reasoning: 消息）
+        target: "last", // last | none | <channel id>（核心或插件，例如 "bluebubbles"）
+        to: "+15551234567", // 可选的渠道特定覆盖
+        prompt: "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.",
+        ackMaxChars: 300, // HEARTBEAT_OK 后允许的最大字符数
+      },
+    },
+  },
+}
+```
+
+### 作用域和优先级
+
+- `agents.defaults.heartbeat` 设置全局心跳行为。
+- `agents.list[].heartbeat` 在其之上合并；如果任何智能体有 `heartbeat` 块，**只有这些智能体**运行心跳。
+- `channels.defaults.heartbeat` 为所有渠道设置可见性默认值。
+- `channels.<channel>.heartbeat` 覆盖渠道默认值。
+- `channels.<channel>.accounts.<id>.heartbeat`（多账户渠道）覆盖单渠道设置。
+
+### 单智能体心跳
+
+如果任何 `agents.list[]` 条目包含 `heartbeat` 块，**只有这些智能体**运行心跳。单智能体块在 `agents.defaults.heartbeat` 之上合并（因此你可以设置一次共享默认值，然后按智能体覆盖）。
+
+示例：两个智能体，只有第二个智能体运行心跳。
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m",
+        target: "last",
+      },
+    },
+    list: [
+      { id: "main", default: true },
+      {
+        id: "ops",
+        heartbeat: {
+          every: "1h",
+          target: "whatsapp",
+          to: "+15551234567",
+          prompt: "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.",
+        },
+      },
+    ],
+  },
+}
+```
+
+### 字段说明
+
+- `every`：心跳间隔（时长字符串；默认单位 = 分钟）。
+- `model`：心跳运行的可选模型覆盖（`provider/model`）。
+- `includeReasoning`：启用时，也会发送单独的 `Reasoning:` 消息（如果可用）（与 `/reasoning on` 格式相同）。
+- `session`：心跳运行的可选会话键。
+  - `main`（默认）：智能体主会话。
+  - 显式会话键（从 `quantumclaw sessions --json` 或 [sessions CLI](/cli/sessions) 复制）。
+  - 会话键格式：参见[会话](/concepts/session)和[群组](/channels/groups)。
+- `target`：
+  - `last`（默认）：发送到最后使用的外部渠道。
+  - 显式渠道：`whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`。
+  - `none`：运行心跳但**不发送**到外部。
+- `to`：可选的收件人覆盖（渠道特定 ID，例如 WhatsApp 的 E.164 或 Telegram 聊天 ID）。
+- `prompt`：覆盖默认提示内容（不合并）。
+- `ackMaxChars`：`HEARTBEAT_OK` 后在发送前允许的最大字符数。
+
+## 发送行为
+
+- 心跳默认在智能体主会话中运行（`agent:<id>:<mainKey>`），或当 `session.scope = "global"` 时在 `global` 中运行。设置 `session` 可覆盖为特定渠道会话（Discord/WhatsApp 等）。
+- `session` 只影响运行上下文；发送由 `target` 和 `to` 控制。
+- 要发送到特定渠道/收件人，设置 `target` + `to`。使用 `target: "last"` 时，发送使用该会话的最后一个外部渠道。
+- 如果主队列繁忙，心跳会被跳过并稍后重试。
+- 如果 `target` 解析为无外部目标，运行仍会发生但不会发送出站消息。
+- 仅心跳回复**不会**保持会话活跃；最后的 `updatedAt` 会被恢复，因此空闲过期正常工作。
+
+## 可见性控制
+
+默认情况下，`HEARTBEAT_OK` 确认会被抑制，而警报内容会被发送。你可以按渠道或按账户调整：
+
+```yaml
+channels:
+  defaults:
+    heartbeat:
+      showOk: false # 隐藏 HEARTBEAT_OK（默认）
+      showAlerts: true # 显示警报消息（默认）
+      useIndicator: true # 发出指示器事件（默认）
+  telegram:
+    heartbeat:
+      showOk: true # 在 Telegram 上显示 OK 确认
+  whatsapp:
+    accounts:
+      work:
+        heartbeat:
+          showAlerts: false # 为此账户抑制警报发送
+```
+
+优先级：单账户 → 单渠道 → 渠道默认值 → 内置默认值。
+
+### 各标志的作用
+
+- `showOk`：当模型返回仅 OK 的回复时，发送 `HEARTBEAT_OK` 确认。
+- `showAlerts`：当模型返回非 OK 回复时，发送警报内容。
+- `useIndicator`：为 UI 状态界面发出指示器事件。
+
+如果**所有三个**都为 false，QuantumClaw 会完全跳过心跳运行（不调用模型）。
+
+### 单渠道 vs 单账户示例
+
+```yaml
+channels:
+  defaults:
+    heartbeat:
+      showOk: false
+      showAlerts: true
+      useIndicator: true
+  slack:
+    heartbeat:
+      showOk: true # 所有 Slack 账户
+    accounts:
+      ops:
+        heartbeat:
+          showAlerts: false # 仅为 ops 账户抑制警报
+  telegram:
+    heartbeat:
+      showOk: true
+```
+
+### 常见模式
+
+| 目标                          | 配置                                                                                     |
+| ----------------------------- | ---------------------------------------------------------------------------------------- |
+| 默认行为（静默 OK，警报开启） | _（无需配置）_                                                                           |
+| 完全静默（无消息，无指示器）  | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
+| 仅指示器（无消息）            | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`  |
+| 仅在一个渠道显示 OK           | `channels.telegram.heartbeat: { showOk: true }`                                          |
+
+## HEARTBEAT.md（可选）
+
+如果工作区中存在 `HEARTBEAT.md` 文件，默认提示会告诉智能体读取它。把它想象成你的"心跳检查清单"：小巧、稳定，可以安全地每 30 分钟包含一次。
+
+如果 `HEARTBEAT.md` 存在但实际上是空的（只有空行和 markdown 标题如 `# Heading`），QuantumClaw 会跳过心跳运行以节省 API 调用。如果文件不存在，心跳仍会运行，由模型决定做什么。
+
+保持它小巧（简短的检查清单或提醒）以避免提示膨胀。
+
+`HEARTBEAT.md` 示例：
+
+```md
+# Heartbeat checklist
+
+- Quick scan: anything urgent in inboxes?
+- If it's daytime, do a lightweight check-in if nothing else is pending.
+- If a task is blocked, write down _what is missing_ and ask Peter next time.
+```
+
+### 智能体可以更新 HEARTBEAT.md 吗？
+
+可以 — 如果你要求它这样做。
+
+`HEARTBEAT.md` 只是智能体工作区中的普通文件，所以你可以在普通聊天中告诉智能体：
+
+- "更新 `HEARTBEAT.md` 添加每日日历检查。"
+- "重写 `HEARTBEAT.md`，使其更短并专注于收件箱跟进。"
+
+如果你希望这主动发生，你也可以在心跳提示中包含明确的一行，如："If the checklist becomes stale, update HEARTBEAT.md with a better one."
+
+安全提示：不要在 `HEARTBEAT.md` 中放置密钥（API 密钥、电话号码、私有令牌）— 它会成为提示上下文的一部分。
+
+## 手动唤醒（按需）
+
+你可以排队一个系统事件并触发即时心跳：
+
+```bash
+quantumclaw system event --text "Check for urgent follow-ups" --mode now
+```
+
+如果多个智能体配置了 `heartbeat`，手动唤醒会立即运行每个智能体的心跳。
+
+使用 `--mode next-heartbeat` 等待下一个计划的时钟周期。
+
+## 推理内容发送（可选）
+
+默认情况下，心跳只发送最终的"答案"负载。
+
+如果你想要透明度，请启用：
+
+- `agents.defaults.heartbeat.includeReasoning: true`
+
+启用后，心跳还会发送一条以 `Reasoning:` 为前缀的单独消息（与 `/reasoning on` 格式相同）。当智能体管理多个会话/代码库并且你想了解它为什么决定联系你时，这很有用 — 但它也可能泄露比你想要的更多内部细节。在群聊中建议保持关闭。
+
+## 成本意识
+
+心跳运行完整的智能体轮次。更短的间隔消耗更多 token。保持 `HEARTBEAT.md` 小巧，如果你只想要内部状态更新，考虑使用更便宜的 `model` 或 `target: "none"`。

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

@@ -0,0 +1,335 @@
+---
+read_when:
+  - 运行或调试 Gateway 网关进程时
+summary: Gateway 网关服务、生命周期和运维的运行手册
+title: Gateway 网关运行手册
+x-i18n:
+  generated_at: "2026-02-03T07:50:03Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 497d58090faaa6bdae62780ce887b40a1ad81e2e99ff186ea2a5c2249c35d9ba
+  source_path: gateway/index.md
+  workflow: 15
+---
+
+# Gateway 网关服务运行手册
+
+最后更新：2025-12-09
+
+## 是什么
+
+- 拥有单一 Baileys/Telegram 连接和控制/事件平面的常驻进程。
+- 替代旧版 `gateway` 命令。CLI 入口点：`quantumclaw gateway`。
+- 运行直到停止；出现致命错误时以非零退出码退出，以便 supervisor 重启它。
+
+## 如何运行（本地）
+
+```bash
+quantumclaw gateway --port 18789
+# 在 stdio 中获取完整的调试/追踪日志：
+quantumclaw gateway --port 18789 --verbose
+# 如果端口被占用，终止监听器然后启动：
+quantumclaw gateway --force
+# 开发循环（TS 更改时自动重载）：
+pnpm gateway:watch
+```
+
+- 配置热重载监视 `~/.quantumclaw/quantumclaw.json`（或 `QUANTUMCLAW_CONFIG_PATH`）。
+  - 默认模式：`gateway.reload.mode="hybrid"`（热应用安全更改，关键更改时重启）。
+  - 热重载在需要时通过 **SIGUSR1** 使用进程内重启。
+  - 使用 `gateway.reload.mode="off"` 禁用。
+- 将 WebSocket 控制平面绑定到 `127.0.0.1:<port>`（默认 18789）。
+- 同一端口也提供 HTTP 服务（控制界面、hooks、A2UI）。单端口多路复用。
+  - OpenAI Chat Completions（HTTP）：[`/v1/chat/completions`](/gateway/openai-http-api)。
+  - OpenResponses（HTTP）：[`/v1/responses`](/gateway/openresponses-http-api)。
+  - Tools Invoke（HTTP）：[`/tools/invoke`](/gateway/tools-invoke-http-api)。
+- 默认在 `canvasHost.port`（默认 `18793`）上启动 Canvas 文件服务器，从 `~/.quantumclaw/workspace/canvas` 提供 `http://<gateway-host>:18793/__quantumclaw__/canvas/`。使用 `canvasHost.enabled=false` 或 `QUANTUMCLAW_SKIP_CANVAS_HOST=1` 禁用。
+- 输出日志到 stdout；使用 launchd/systemd 保持运行并轮转日志。
+- 故障排除时传递 `--verbose` 以将调试日志（握手、请求/响应、事件）从日志文件镜像到 stdio。
+- `--force` 使用 `lsof` 查找所选端口上的监听器，发送 SIGTERM，记录它终止了什么，然后启动 Gateway 网关（如果缺少 `lsof` 则快速失败）。
+- 如果你在 supervisor（launchd/systemd/mac 应用子进程模式）下运行，stop/restart 通常发送 **SIGTERM**；旧版本可能将其显示为 `pnpm` `ELIFECYCLE` 退出码 **143**（SIGTERM），这是正常关闭，不是崩溃。
+- **SIGUSR1** 在授权时触发进程内重启（Gateway 网关工具/配置应用/更新，或启用 `commands.restart` 以进行手动重启）。
+- 默认需要 Gateway 网关认证：设置 `gateway.auth.token`（或 `QUANTUMCLAW_GATEWAY_TOKEN`）或 `gateway.auth.password`。客户端必须发送 `connect.params.auth.token/password`，除非使用 Tailscale Serve 身份。
+- 向导现在默认生成令牌，即使在 loopback 上也是如此。
+- 端口优先级：`--port` > `QUANTUMCLAW_GATEWAY_PORT` > `gateway.port` > 默认 `18789`。
+
+## 远程访问
+
+- 首选 Tailscale/VPN；否则使用 SSH 隧道：
+  ```bash
+  ssh -N -L 18789:127.0.0.1:18789 user@host
+  ```
+- 然后客户端通过隧道连接到 `ws://127.0.0.1:18789`。
+- 如果配置了令牌，即使通过隧道，客户端也必须在 `connect.params.auth.token` 中包含它。
+
+## 多个 Gateway 网关（同一主机）
+
+通常不需要：一个 Gateway 网关可以服务多个消息渠道和智能体。仅在需要冗余或严格隔离（例如：救援机器人）时使用多个 Gateway 网关。
+
+如果你隔离状态 + 配置并使用唯一端口，则支持。完整指南：[多个 Gateway 网关](/gateway/multiple-gateways)。
+
+服务名称是配置文件感知的：
+
+- macOS：`bot.molt.<profile>`（旧版 `com.quantumclaw.*` 可能仍然存在）
+- Linux：`quantumclaw-gateway-<profile>.service`
+- Windows：`QuantumClaw Gateway (<profile>)`
+
+安装元数据嵌入在服务配置中：
+
+- `QUANTUMCLAW_SERVICE_MARKER=quantumclaw`
+- `QUANTUMCLAW_SERVICE_KIND=gateway`
+- `QUANTUMCLAW_SERVICE_VERSION=<version>`
+
+救援机器人模式：保持第二个 Gateway 网关隔离，使用自己的配置文件、状态目录、工作区和基础端口间隔。完整指南：[救援机器人指南](/gateway/multiple-gateways#rescue-bot-guide)。
+
+### Dev 配置文件（`--dev`）
+
+快速路径：运行完全隔离的 dev 实例（配置/状态/工作区）而不触及你的主设置。
+
+```bash
+quantumclaw --dev setup
+quantumclaw --dev gateway --allow-unconfigured
+# 然后定位到 dev 实例：
+quantumclaw --dev status
+quantumclaw --dev health
+```
+
+默认值（可通过 env/flags/config 覆盖）：
+
+- `QUANTUMCLAW_STATE_DIR=~/.quantumclaw-dev`
+- `QUANTUMCLAW_CONFIG_PATH=~/.quantumclaw-dev/quantumclaw.json`
+- `QUANTUMCLAW_GATEWAY_PORT=19001`（Gateway 网关 WS + HTTP）
+- 浏览器控制服务端口 = `19003`（派生：`gateway.port+2`，仅 loopback）
+- `canvasHost.port=19005`（派生：`gateway.port+4`）
+- 当你在 `--dev` 下运行 `setup`/`onboard` 时，`agents.defaults.workspace` 默认变为 `~/.quantumclaw/workspace-dev`。
+
+派生端口（经验法则）：
+
+- 基础端口 = `gateway.port`（或 `QUANTUMCLAW_GATEWAY_PORT` / `--port`）
+- 浏览器控制服务端口 = 基础 + 2（仅 loopback）
+- `canvasHost.port = 基础 + 4`（或 `QUANTUMCLAW_CANVAS_HOST_PORT` / 配置覆盖）
+- 浏览器配置文件 CDP 端口从 `browser.controlPort + 9 .. + 108` 自动分配（按配置文件持久化）。
+
+每个实例的检查清单：
+
+- 唯一的 `gateway.port`
+- 唯一的 `QUANTUMCLAW_CONFIG_PATH`
+- 唯一的 `QUANTUMCLAW_STATE_DIR`
+- 唯一的 `agents.defaults.workspace`
+- 单独的 WhatsApp 号码（如果使用 WA）
+
+按配置文件安装服务：
+
+```bash
+quantumclaw --profile main gateway install
+quantumclaw --profile rescue gateway install
+```
+
+示例：
+
+```bash
+QUANTUMCLAW_CONFIG_PATH=~/.quantumclaw/a.json QUANTUMCLAW_STATE_DIR=~/.quantumclaw-a quantumclaw gateway --port 19001
+QUANTUMCLAW_CONFIG_PATH=~/.quantumclaw/b.json QUANTUMCLAW_STATE_DIR=~/.quantumclaw-b quantumclaw gateway --port 19002
+```
+
+## 协议（运维视角）
+
+- 完整文档：[Gateway 网关协议](/gateway/protocol) 和 [Bridge 协议（旧版）](/gateway/bridge-protocol)。
+- 客户端必须发送的第一帧：`req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }`。
+- Gateway 网关回复 `res {type:"res", id, ok:true, payload:hello-ok }`（或 `ok:false` 带错误，然后关闭）。
+- 握手后：
+  - 请求：`{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
+  - 事件：`{type:"event", event, payload, seq?, stateVersion?}`
+- 结构化 presence 条目：`{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`（对于 WS 客户端，`instanceId` 来自 `connect.client.instanceId`）。
+- `agent` 响应是两阶段的：首先 `res` 确认 `{runId,status:"accepted"}`，然后在运行完成后发送最终 `res` `{runId,status:"ok"|"error",summary}`；流式输出作为 `event:"agent"` 到达。
+
+## 方法（初始集）
+
+- `health` — 完整健康快照（与 `quantumclaw health --json` 形状相同）。
+- `status` — 简短摘要。
+- `system-presence` — 当前 presence 列表。
+- `system-event` — 发布 presence/系统注释（结构化）。
+- `send` — 通过活跃渠道发送消息。
+- `agent` — 运行智能体轮次（在同一连接上流回事件）。
+- `node.list` — 列出已配对 + 当前连接的节点（包括 `caps`、`deviceFamily`、`modelIdentifier`、`paired`、`connected` 和广播的 `commands`）。
+- `node.describe` — 描述节点（能力 + 支持的 `node.invoke` 命令；适用于已配对节点和当前连接的未配对节点）。
+- `node.invoke` — 在节点上调用命令（例如 `canvas.*`、`camera.*`）。
+- `node.pair.*` — 配对生命周期（`request`、`list`、`approve`、`reject`、`verify`）。
+
+另见：[Presence](/concepts/presence) 了解 presence 如何产生/去重以及为什么稳定的 `client.instanceId` 很重要。
+
+## 事件
+
+- `agent` — 来自智能体运行的流式工具/输出事件（带 seq 标记）。
+- `presence` — presence 更新（带 stateVersion 的增量）推送到所有连接的客户端。
+- `tick` — 定期保活/无操作以确认活跃。
+- `shutdown` — Gateway 网关正在退出；payload 包括 `reason` 和可选的 `restartExpectedMs`。客户端应重新连接。
+
+## WebChat 集成
+
+- WebChat 是原生 SwiftUI UI，直接与 Gateway 网关 WebSocket 通信以获取历史记录、发送、中止和事件。
+- 远程使用通过相同的 SSH/Tailscale 隧道；如果配置了 Gateway 网关令牌，客户端在 `connect` 期间包含它。
+- macOS 应用通过单个 WS 连接（共享连接）；它从初始快照填充 presence 并监听 `presence` 事件以更新 UI。
+
+## 类型和验证
+
+- 服务器使用 AJV 根据从协议定义发出的 JSON Schema 验证每个入站帧。
+- 客户端（TS/Swift）消费生成的类型（TS 直接使用；Swift 通过仓库的生成器）。
+- 协议定义是真实来源；使用以下命令重新生成 schema/模型：
+  - `pnpm protocol:gen`
+  - `pnpm protocol:gen:swift`
+
+## 连接快照
+
+- `hello-ok` 包含带有 `presence`、`health`、`stateVersion` 和 `uptimeMs` 的 `snapshot`，以及 `policy {maxPayload,maxBufferedBytes,tickIntervalMs}`，这样客户端无需额外请求即可立即渲染。
+- `health`/`system-presence` 仍可用于手动刷新，但在连接时不是必需的。
+
+## 错误码（res.error 形状）
+
+- 错误使用 `{ code, message, details?, retryable?, retryAfterMs? }`。
+- 标准码：
+  - `NOT_LINKED` — WhatsApp 未认证。
+  - `AGENT_TIMEOUT` — 智能体未在配置的截止时间内响应。
+  - `INVALID_REQUEST` — schema/参数验证失败。
+  - `UNAVAILABLE` — Gateway 网关正在关闭或依赖项不可用。
+
+## 保活行为
+
+- `tick` 事件（或 WS ping/pong）定期发出，以便客户端知道即使没有流量时 Gateway 网关也是活跃的。
+- 发送/智能体确认保持为单独的响应；不要为发送重载 tick。
+
+## 重放 / 间隙
+
+- 事件不会重放。客户端检测 seq 间隙，应在继续之前刷新（`health` + `system-presence`）。WebChat 和 macOS 客户端现在会在间隙时自动刷新。
+
+## 监管（macOS 示例）
+
+- 使用 launchd 保持服务存活：
+  - Program：`quantumclaw` 的路径
+  - Arguments：`gateway`
+  - KeepAlive：true
+  - StandardOut/Err：文件路径或 `syslog`
+- 失败时，launchd 重启；致命的配置错误应保持退出，以便运维人员注意到。
+- LaunchAgents 是按用户的，需要已登录的会话；对于无头设置，使用自定义 LaunchDaemon（未随附）。
+  - `quantumclaw gateway install` 写入 `~/Library/LaunchAgents/bot.molt.gateway.plist`
+    （或 `bot.molt.<profile>.plist`；旧版 `com.quantumclaw.*` 会被清理）。
+  - `quantumclaw doctor` 审计 LaunchAgent 配置，可以将其更新为当前默认值。
+
+## Gateway 网关服务管理（CLI）
+
+使用 Gateway 网关 CLI 进行 install/start/stop/restart/status：
+
+```bash
+quantumclaw gateway status
+quantumclaw gateway install
+quantumclaw gateway stop
+quantumclaw gateway restart
+quantumclaw logs --follow
+```
+
+注意事项：
+
+- `gateway status` 默认使用服务解析的端口/配置探测 Gateway 网关 RPC（使用 `--url` 覆盖）。
+- `gateway status --deep` 添加系统级扫描（LaunchDaemons/系统单元）。
+- `gateway status --no-probe` 跳过 RPC 探测（在网络故障时有用）。
+- `gateway status --json` 对脚本是稳定的。
+- `gateway status` 将 **supervisor 运行时**（launchd/systemd 运行中）与 **RPC 可达性**（WS 连接 + status RPC）分开报告。
+- `gateway status` 打印配置路径 + 探测目标以避免"localhost vs LAN 绑定"混淆和配置文件不匹配。
+- `gateway status` 在服务看起来正在运行但端口已关闭时包含最后一行 Gateway 网关错误。
+- `logs` 通过 RPC 尾随 Gateway 网关文件日志（无需手动 `tail`/`grep`）。
+- 如果检测到其他类似 Gateway 网关的服务，CLI 会发出警告，除非它们是 QuantumClaw 配置文件服务。
+  我们仍然建议大多数设置**每台机器一个 Gateway 网关**；使用隔离的配置文件/端口进行冗余或救援机器人。参见[多个 Gateway 网关](/gateway/multiple-gateways)。
+  - 清理：`quantumclaw gateway uninstall`（当前服务）和 `quantumclaw doctor`（旧版迁移）。
+- `gateway install` 在已安装时是无操作的；使用 `quantumclaw gateway install --force` 重新安装（配置文件/env/路径更改）。
+
+捆绑的 mac 应用：
+
+- QuantumClaw.app 可以捆绑基于 Node 的 Gateway 网关中继并安装标记为
+  `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.quantumclaw.*` 标签仍能干净卸载）的按用户 LaunchAgent。
+- 要干净地停止它，使用 `quantumclaw gateway stop`（或 `launchctl bootout gui/$UID/bot.molt.gateway`）。
+- 要重启，使用 `quantumclaw gateway restart`（或 `launchctl kickstart -k gui/$UID/bot.molt.gateway`）。
+  - `launchctl` 仅在 LaunchAgent 已安装时有效；否则先使用 `quantumclaw gateway install`。
+  - 运行命名配置文件时，将标签替换为 `bot.molt.<profile>`。
+
+## 监管（systemd 用户单元）
+
+QuantumClaw 在 Linux/WSL2 上默认安装 **systemd 用户服务**。我们
+建议单用户机器使用用户服务（更简单的 env，按用户配置）。
+对于多用户或常驻服务器使用**系统服务**（无需 lingering，
+共享监管）。
+
+`quantumclaw gateway install` 写入用户单元。`quantumclaw doctor` 审计
+单元并可以将其更新以匹配当前推荐的默认值。
+
+创建 `~/.config/systemd/user/quantumclaw-gateway[-<profile>].service`：
+
+```
+[Unit]
+Description=QuantumClaw Gateway (profile: <profile>, v<version>)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/quantumclaw gateway --port 18789
+Restart=always
+RestartSec=5
+Environment=QUANTUMCLAW_GATEWAY_TOKEN=
+WorkingDirectory=/home/youruser
+
+[Install]
+WantedBy=default.target
+```
+
+启用 lingering（必需，以便用户服务在登出/空闲后继续存活）：
+
+```
+sudo loginctl enable-linger youruser
+```
+
+新手引导在 Linux/WSL2 上运行此命令（可能提示输入 sudo；写入 `/var/lib/systemd/linger`）。
+然后启用服务：
+
+```
+systemctl --user enable --now quantumclaw-gateway[-<profile>].service
+```
+
+**替代方案（系统服务）** - 对于常驻或多用户服务器，你可以
+安装 systemd **系统**单元而不是用户单元（无需 lingering）。
+创建 `/etc/systemd/system/quantumclaw-gateway[-<profile>].service`（复制上面的单元，
+切换 `WantedBy=multi-user.target`，设置 `User=` + `WorkingDirectory=`），然后：
+
+```
+sudo systemctl daemon-reload
+sudo systemctl enable --now quantumclaw-gateway[-<profile>].service
+```
+
+## Windows（WSL2）
+
+Windows 安装应使用 **WSL2** 并遵循上面的 Linux systemd 部分。
+
+## 运维检查
+
+- 存活检查：打开 WS 并发送 `req:connect` → 期望收到带有 `payload.type="hello-ok"`（带快照）的 `res`。
+- 就绪检查：调用 `health` → 期望 `ok: true` 并在 `linkChannel` 中有已关联的渠道（适用时）。
+- 调试：订阅 `tick` 和 `presence` 事件；确保 `status` 显示已关联/认证时间；presence 条目显示 Gateway 网关主机和已连接的客户端。
+
+## 安全保证
+
+- 默认假设每台主机一个 Gateway 网关；如果你运行多个配置文件，隔离端口/状态并定位到正确的实例。
+- 不会回退到直接 Baileys 连接；如果 Gateway 网关关闭，发送会快速失败。
+- 非 connect 的第一帧或格式错误的 JSON 会被拒绝并关闭 socket。
+- 优雅关闭：关闭前发出 `shutdown` 事件；客户端必须处理关闭 + 重新连接。
+
+## CLI 辅助工具
+
+- `quantumclaw gateway health|status` — 通过 Gateway 网关 WS 请求 health/status。
+- `quantumclaw message send --target <num> --message "hi" [--media ...]` — 通过 Gateway 网关发送（对 WhatsApp 是幂等的）。
+- `quantumclaw agent --message "hi" --to <num>` — 运行智能体轮次（默认等待最终结果）。
+- `quantumclaw gateway call <method> --params '{"k":"v"}'` — 用于调试的原始方法调用器。
+- `quantumclaw gateway stop|restart` — 停止/重启受监管的 Gateway 网关服务（launchd/systemd）。
+- Gateway 网关辅助子命令假设 `--url` 上有运行中的 Gateway 网关；它们不再自动生成一个。
+
+## 迁移指南
+
+- 淘汰 `quantumclaw gateway` 和旧版 TCP 控制端口的使用。
+- 更新客户端以使用带有强制 connect 和结构化 presence 的 WS 协议。