@captain-app/openclaw 2026.2.4

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

@@ -0,0 +1,32 @@
+---
+read_when:
+  - 你想将 Gmail Pub/Sub 事件接入 OpenClaw
+  - 你需要 Webhook 辅助命令
+summary: "`openclaw webhooks`（Webhook 辅助工具 + Gmail Pub/Sub）的 CLI 参考"
+title: webhooks
+x-i18n:
+  generated_at: "2026-02-01T20:21:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 785ec62afe6631b340ce4a4541ceb34cd6b97704cf7a9889762cb4c1f29a5ca0
+  source_path: cli/webhooks.md
+  workflow: 14
+---
+
+# `openclaw webhooks`
+
+Webhook 辅助工具和集成（Gmail Pub/Sub、Webhook 辅助工具）。
+
+相关内容：
+
+- Webhook：[Webhook](/automation/webhook)
+- Gmail Pub/Sub：[Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gmail
+
+```bash
+openclaw webhooks gmail setup --account you@example.com
+openclaw webhooks gmail run
+```
+
+详情请参阅 [Gmail Pub/Sub 文档](/automation/gmail-pubsub)。

package/docs/zh-CN/concepts/agent-loop.md

@@ -0,0 +1,146 @@
+---
+read_when:
+  - 你需要智能体循环或生命周期事件的详细说明
+summary: 智能体循环生命周期、流和等待语义
+title: 智能体循环
+x-i18n:
+  generated_at: "2026-02-03T10:05:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0775b96eb3451e137297661a1095eaefb2bafeebb5f78123174a46290e18b014
+  source_path: concepts/agent-loop.md
+  workflow: 15
+---
+
+# 智能体循环（OpenClaw）
+
+智能体循环是智能体的完整"真实"运行：接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。这是将消息转化为操作和最终回复的权威路径，同时保持会话状态的一致性。
+
+在 OpenClaw 中，循环是每个会话的单次序列化运行，在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档解释了这个真实循环是如何端到端连接的。
+
+## 入口点
+
+- Gateway 网关 RPC：`agent` 和 `agent.wait`。
+- CLI：`agent` 命令。
+
+## 工作原理（高层次）
+
+1. `agent` RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 `{ runId, acceptedAt }`。
+2. `agentCommand` 运行智能体：
+   - 解析模型 + 思考/详细模式默认值
+   - 加载 Skills 快照
+   - 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时）
+   - 如果嵌入式循环未发出**生命周期结束/错误**事件，则发出该事件
+3. `runEmbeddedPiAgent`：
+   - 通过每会话 + 全局队列序列化运行
+   - 解析模型 + 认证配置文件并构建 pi 会话
+   - 订阅 pi 事件并流式传输助手/工具增量
+   - 强制执行超时 -> 超时则中止运行
+   - 返回有效负载 + 使用元数据
+4. `subscribeEmbeddedPiSession` 将 pi-agent-core 事件桥接到 OpenClaw `agent` 流：
+   - 工具事件 => `stream: "tool"`
+   - 助手增量 => `stream: "assistant"`
+   - 生命周期事件 => `stream: "lifecycle"`（`phase: "start" | "end" | "error"`）
+5. `agent.wait` 使用 `waitForAgentJob`：
+   - 等待 `runId` 的**生命周期结束/错误**
+   - 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }`
+
+## 队列 + 并发
+
+- 运行按会话键（会话通道）序列化，可选择通过全局通道。
+- 这可以防止工具/会话竞争并保持会话历史的一致性。
+- 消息渠道可以选择队列模式（collect/steer/followup）来馈送此通道系统。参见[命令队列](/concepts/queue)。
+
+## 会话 + 工作区准备
+
+- 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。
+- 加载 Skills（或从快照中复用）并注入到环境和提示中。
+- 解析引导/上下文文件并注入到系统提示报告中。
+- 获取会话写锁；在流式传输之前打开并准备 `SessionManager`。
+
+## 提示组装 + 系统提示
+
+- 系统提示由 OpenClaw 的基础提示、Skills 提示、引导上下文和每次运行的覆盖构建。
+- 强制执行模型特定的限制和压缩保留令牌。
+- 参见[系统提示](/concepts/system-prompt)了解模型看到的内容。
+
+## 钩子点（可以拦截的位置）
+
+OpenClaw 有两个钩子系统：
+
+- **内部钩子**（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。
+- **插件钩子**：智能体/工具生命周期和 Gateway 网关管道中的扩展点。
+
+### 内部钩子（Gateway 网关钩子）
+
+- **`agent:bootstrap`**：在系统提示最终确定之前构建引导文件时运行。用于添加/删除引导上下文文件。
+- **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见钩子文档）。
+
+参见[钩子](/hooks)了解设置和示例。
+
+### 插件钩子（智能体 + Gateway 网关生命周期）
+
+这些在智能体循环或 Gateway 网关管道内运行：
+
+- **`before_agent_start`**：在运行开始前注入上下文或覆盖系统提示。
+- **`agent_end`**：在完成后检查最终消息列表和运行元数据。
+- **`before_compaction` / `after_compaction`**：观察或注释压缩周期。
+- **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。
+- **`tool_result_persist`**：在工具结果写入会话记录之前同步转换它们。
+- **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。
+- **`session_start` / `session_end`**：会话生命周期边界。
+- **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。
+
+参见[插件](/plugin#plugin-hooks)了解钩子 API 和注册详情。
+
+## 流式传输 + 部分回复
+
+- 助手增量从 pi-agent-core 流式传输并作为 `assistant` 事件发出。
+- 分块流式传输可以在 `text_end` 或 `message_end` 时发出部分回复。
+- 推理流式传输可以作为单独的流或作为块回复发出。
+- 参见[流式传输](/concepts/streaming)了解分块和块回复行为。
+
+## 工具执行 + 消息工具
+
+- 工具开始/更新/结束事件在 `tool` 流上发出。
+- 工具结果在记录/发出之前会对大小和图像有效负载进行清理。
+- 消息工具发送会被跟踪以抑制重复的助手确认。
+
+## 回复整形 + 抑制
+
+- 最终有效负载由以下内容组装：
+  - 助手文本（和可选的推理）
+  - 内联工具摘要（当详细模式 + 允许时）
+  - 模型出错时的助手错误文本
+- `NO_REPLY` 被视为静默令牌，从出站有效负载中过滤。
+- 消息工具重复项从最终有效负载列表中移除。
+- 如果没有剩余可渲染的有效负载且工具出错，则发出回退工具错误回复（除非消息工具已经发送了用户可见的回复）。
+
+## 压缩 + 重试
+
+- 自动压缩发出 `compaction` 流事件，可以触发重试。
+- 重试时，内存缓冲区和工具摘要会重置以避免重复输出。
+- 参见[压缩](/concepts/compaction)了解压缩管道。
+
+## 事件流（当前）
+
+- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（以及作为 `agentCommand` 的回退）
+- `assistant`：从 pi-agent-core 流式传输的增量
+- `tool`：从 pi-agent-core 流式传输的工具事件
+
+## 聊天渠道处理
+
+- 助手增量被缓冲到聊天 `delta` 消息中。
+- 在**生命周期结束/错误**时发出聊天 `final`。
+
+## 超时
+
+- `agent.wait` 默认：30 秒（仅等待）。`timeoutMs` 参数可覆盖。
+- 智能体运行时：`agents.defaults.timeoutSeconds` 默认 600 秒；在 `runEmbeddedPiAgent` 中止计时器中强制执行。
+
+## 可能提前结束的情况
+
+- 智能体超时（中止）
+- AbortSignal（取消）
+- Gateway 网关断开连接或 RPC 超时
+- `agent.wait` 超时（仅等待，不会停止智能体）

package/docs/zh-CN/concepts/agent-workspace.md

@@ -0,0 +1,219 @@
+---
+read_when:
+  - 你需要解释智能体工作区或其文件布局
+  - 你想备份或迁移智能体工作区
+summary: 智能体工作区：位置、布局和备份策略
+title: 智能体工作区
+x-i18n:
+  generated_at: "2026-02-03T07:45:49Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 84c550fd89b5f2474aeae586795485fd29d36effbb462f13342b31540fc18b82
+  source_path: concepts/agent-workspace.md
+  workflow: 15
+---
+
+# 智能体工作区
+
+工作区是智能体的家。它是文件工具和工作区上下文使用的唯一工作目录。请保持其私密性并将其视为记忆。
+
+这与 `~/.openclaw/` 是分开的，后者存储配置、凭证和会话。
+
+**重要：** 工作区是**默认 cwd**，而不是硬性沙箱。工具会根据工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱隔离。如果你需要隔离，请使用
+[`agents.defaults.sandbox`](/gateway/sandboxing)（和/或每智能体沙箱配置）。
+当启用沙箱隔离且 `workspaceAccess` 不是 `"rw"` 时，工具在 `~/.openclaw/sandboxes` 下的沙箱工作区内操作，而不是你的主机工作区。
+
+## 默认位置
+
+- 默认：`~/.openclaw/workspace`
+- 如果设置了 `OPENCLAW_PROFILE` 且不是 `"default"`，默认值变为
+  `~/.openclaw/workspace-<profile>`。
+- 在 `~/.openclaw/openclaw.json` 中覆盖：
+
+```json5
+{
+  agent: {
+    workspace: "~/.openclaw/workspace",
+  },
+}
+```
+
+`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 将创建工作区并在缺失时填充引导文件。
+
+如果你已经自己管理工作区文件，可以禁用引导文件创建：
+
+```json5
+{ agent: { skipBootstrap: true } }
+```
+
+## 额外的工作区文件夹
+
+旧版安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致混乱的认证或状态漂移，因为同一时间只有一个工作区是活动的。
+
+**建议：** 保持单个活动工作区。如果你不再使用额外的文件夹，请归档或移至废纸篓（例如 `trash ~/openclaw`）。
+如果你有意保留多个工作区，请确保 `agents.defaults.workspace` 指向活动的那个。
+
+`openclaw doctor` 在检测到额外工作区目录时会发出警告。
+
+## 工作区文件映射（每个文件的含义）
+
+这些是 OpenClaw 在工作区内期望的标准文件：
+
+- `AGENTS.md`
+  - 智能体的操作指南以及它应该如何使用记忆。
+  - 在每个会话开始时加载。
+  - 适合放置规则、优先级和"如何行为"的详细信息。
+
+- `SOUL.md`
+  - 人设、语气和边界。
+  - 每个会话加载。
+
+- `USER.md`
+  - 用户是谁以及如何称呼他们。
+  - 每个会话加载。
+
+- `IDENTITY.md`
+  - 智能体的名称、风格和表情符号。
+  - 在引导仪式期间创建/更新。
+
+- `TOOLS.md`
+  - 关于你本地工具和惯例的注释。
+  - 不控制工具可用性；仅作为指导。
+
+- `HEARTBEAT.md`
+  - 可选的心跳运行小型检查清单。
+  - 保持简短以避免 token 消耗。
+
+- `BOOT.md`
+  - 当启用内部 hooks 时，在 Gateway 网关重启时执行的可选启动检查清单。
+  - 保持简短；使用 message 工具进行出站发送。
+
+- `BOOTSTRAP.md`
+  - 一次性首次运行仪式。
+  - 仅为全新工作区创建。
+  - 仪式完成后删除它。
+
+- `memory/YYYY-MM-DD.md`
+  - 每日记忆日志（每天一个文件）。
+  - 建议在会话开始时读取今天 + 昨天的内容。
+
+- `MEMORY.md`（可选）
+  - 精选的长期记忆。
+  - 仅在主私密会话中加载（不在共享/群组上下文中）。
+
+参见 [记忆](/concepts/memory) 了解工作流程和自动记忆刷新。
+
+- `skills/`（可选）
+  - 工作区特定的 Skills。
+  - 当名称冲突时覆盖托管/捆绑的 Skills。
+
+- `canvas/`（可选）
+  - 用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。
+
+如果任何引导文件缺失，OpenClaw 会在会话中注入"缺失文件"标记并继续。大型引导文件在注入时会被截断；使用 `agents.defaults.bootstrapMaxChars` 调整限制（默认：20000）。
+`openclaw setup` 可以重新创建缺失的默认值而不覆盖现有文件。
+
+## 工作区中不包含的内容
+
+这些位于 `~/.openclaw/` 下，不应提交到工作区仓库：
+
+- `~/.openclaw/openclaw.json`（配置）
+- `~/.openclaw/credentials/`（OAuth token、API 密钥）
+- `~/.openclaw/agents/<agentId>/sessions/`（会话记录 + 元数据）
+- `~/.openclaw/skills/`（托管的 Skills）
+
+如果你需要迁移会话或配置，请单独复制它们并将它们排除在版本控制之外。
+
+## Git 备份（推荐，私有）
+
+将工作区视为私密记忆。将其放入**私有** git 仓库以便备份和恢复。
+
+在运行 Gateway 网关的机器上执行这些步骤（工作区就在那里）。
+
+### 1）初始化仓库
+
+如果安装了 git，全新工作区会自动初始化。如果此工作区还不是仓库，请运行：
+
+```bash
+cd ~/.openclaw/workspace
+git init
+git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
+git commit -m "Add agent workspace"
+```
+
+### 2）添加私有远程（适合初学者的选项）
+
+选项 A：GitHub 网页界面
+
+1. 在 GitHub 上创建新的**私有**仓库。
+2. 不要用 README 初始化（避免合并冲突）。
+3. 复制 HTTPS 远程 URL。
+4. 添加远程并推送：
+
+```bash
+git branch -M main
+git remote add origin <https-url>
+git push -u origin main
+```
+
+选项 B：GitHub CLI（`gh`）
+
+```bash
+gh auth login
+gh repo create openclaw-workspace --private --source . --remote origin --push
+```
+
+选项 C：GitLab 网页界面
+
+1. 在 GitLab 上创建新的**私有**仓库。
+2. 不要用 README 初始化（避免合并冲突）。
+3. 复制 HTTPS 远程 URL。
+4. 添加远程并推送：
+
+```bash
+git branch -M main
+git remote add origin <https-url>
+git push -u origin main
+```
+
+### 3）持续更新
+
+```bash
+git status
+git add .
+git commit -m "Update memory"
+git push
+```
+
+## 不要提交密钥
+
+即使在私有仓库中，也要避免在工作区中存储密钥：
+
+- API 密钥、OAuth token、密码或私有凭证。
+- `~/.openclaw/` 下的任何内容。
+- 聊天的原始转储或敏感附件。
+
+如果你必须存储敏感引用，请使用占位符并将真正的密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
+
+建议的 `.gitignore` 起始配置：
+
+```gitignore
+.DS_Store
+.env
+**/*.key
+**/*.pem
+**/secrets*
+```
+
+## 将工作区迁移到新机器
+
+1. 将仓库克隆到所需路径（默认 `~/.openclaw/workspace`）。
+2. 在 `~/.openclaw/openclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。
+3. 运行 `openclaw setup --workspace <path>` 来填充任何缺失的文件。
+4. 如果你需要会话，请单独从旧机器复制 `~/.openclaw/agents/<agentId>/sessions/`。
+
+## 高级注意事项
+
+- 多智能体路由可以为每个智能体使用不同的工作区。参见
+  [渠道路由](/concepts/channel-routing) 了解路由配置。
+- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用每会话沙箱工作区。

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

@@ -0,0 +1,115 @@
+---
+read_when:
+  - 更改智能体运行时、工作区引导或会话行为时
+summary: 智能体运行时（嵌入式 pi-mono）、工作区契约和会话引导
+title: 智能体运行时
+x-i18n:
+  generated_at: "2026-02-03T10:04:53Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 04b4e0bc6345d2afd9a93186e5d7a02a393ec97da2244e531703cb6a1c182325
+  source_path: concepts/agent.md
+  workflow: 15
+---
+
+# 智能体运行时 🤖
+
+OpenClaw 运行一个源自 **pi-mono** 的嵌入式智能体运行时。
+
+## 工作区（必需）
+
+OpenClaw 使用单一智能体工作区目录（`agents.defaults.workspace`）作为智能体**唯一**的工作目录（`cwd`），用于工具和上下文。
+
+建议：使用 `openclaw setup` 在缺失时创建 `~/.openclaw/openclaw.json` 并初始化工作区文件。
+
+完整工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
+
+如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话隔离的工作区覆盖此设置（参见 [Gateway 网关配置](/gateway/configuration)）。
+
+## 引导文件（注入）
+
+在 `agents.defaults.workspace` 内，OpenClaw 期望以下用户可编辑的文件：
+
+- `AGENTS.md` — 操作指令 + "记忆"
+- `SOUL.md` — 人设、边界、语气
+- `TOOLS.md` — 用户维护的工具说明（例如 `imsg`、`sag`、约定）
+- `BOOTSTRAP.md` — 一次性首次运行仪式（完成后删除）
+- `IDENTITY.md` — 智能体名称/风格/表情
+- `USER.md` — 用户档案 + 偏好称呼
+
+在新会话的第一轮，OpenClaw 将这些文件的内容直接注入智能体上下文。
+
+空文件会被跳过。大文件会被修剪和截断并添加标记，以保持提示词精简（阅读文件获取完整内容）。
+
+如果文件缺失，OpenClaw 会注入一行"文件缺失"标记（`openclaw setup` 将创建安全的默认模板）。
+
+`BOOTSTRAP.md` 仅在**全新工作区**（没有其他引导文件存在）时创建。如果你在完成仪式后删除它，后续重启不应重新创建。
+
+要完全禁用引导文件创建（用于预置工作区），请设置：
+
+```json5
+{ agent: { skipBootstrap: true } }
+```
+
+## 内置工具
+
+核心工具（read/exec/edit/write 及相关系统工具）始终可用，受工具策略约束。`apply_patch` 是可选的，由 `tools.exec.applyPatch` 控制。`TOOLS.md` **不**控制哪些工具存在；它是关于*你*希望如何使用它们的指导。
+
+## Skills
+
+OpenClaw 从三个位置加载 Skills（名称冲突时工作区优先）：
+
+- 内置（随安装包提供）
+- 托管/本地：`~/.openclaw/skills`
+- 工作区：`<workspace>/skills`
+
+Skills 可通过配置/环境变量控制（参见 [Gateway 网关配置](/gateway/configuration) 中的 `skills`）。
+
+## pi-mono 集成
+
+OpenClaw 复用 pi-mono 代码库的部分内容（模型/工具），但**会话管理、设备发现和工具连接由 OpenClaw 负责**。
+
+- 无 pi-coding 智能体运行时。
+- 不读取 `~/.pi/agent` 或 `<workspace>/.pi` 设置。
+
+## 会话
+
+会话记录以 JSONL 格式存储在：
+
+- `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
+
+会话 ID 是稳定的，由 OpenClaw 选择。
+**不**读取旧版 Pi/Tau 会话文件夹。
+
+## 流式传输中的引导
+
+当队列模式为 `steer` 时，入站消息会注入当前运行。
+队列在**每次工具调用后**检查；如果存在排队消息，当前助手消息的剩余工具调用将被跳过（工具结果显示错误"Skipped due to queued user message."），然后在下一个助手响应前注入排队的用户消息。
+
+当队列模式为 `followup` 或 `collect` 时，入站消息会保留到当前轮次结束，然后使用排队的载荷开始新的智能体轮次。参见 [队列](/concepts/queue) 了解模式 + 防抖/上限行为。
+
+分块流式传输在助手块完成后立即发送；默认为**关闭**（`agents.defaults.blockStreamingDefault: "off"`）。
+通过 `agents.defaults.blockStreamingBreak` 调整边界（`text_end` 与 `message_end`；默认为 text_end）。
+使用 `agents.defaults.blockStreamingChunk` 控制软块分块（默认 800–1200 字符；优先段落分隔，其次换行；最后是句子）。
+使用 `agents.defaults.blockStreamingCoalesce` 合并流式块以减少单行刷屏（发送前基于空闲的合并）。非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 以启用分块回复。
+工具启动时发出详细工具摘要（无防抖）；Control UI 在可用时通过智能体事件流式传输工具输出。
+更多详情：[流式传输 + 分块](/concepts/streaming)。
+
+## 模型引用
+
+配置中的模型引用（例如 `agents.defaults.model` 和 `agents.defaults.models`）通过在**第一个** `/` 处分割来解析。
+
+- 配置模型时使用 `provider/model`。
+- 如果模型 ID 本身包含 `/`（OpenRouter 风格），请包含提供商前缀（例如：`openrouter/moonshotai/kimi-k2`）。
+- 如果省略提供商，OpenClaw 将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
+
+## 配置（最小）
+
+至少需要设置：
+
+- `agents.defaults.workspace`
+- `channels.whatsapp.allowFrom`（强烈建议）
+
+---
+
+_下一篇：[群聊](/concepts/group-messages)_ 🦞

package/docs/zh-CN/concepts/architecture.md

@@ -0,0 +1,123 @@
+---
+read_when:
+  - 正在开发 Gateway 网关协议、客户端或传输层
+summary: WebSocket Gateway 网关架构、组件和客户端流程
+title: Gateway 网关架构
+x-i18n:
+  generated_at: "2026-02-03T07:45:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c636d5d8a5e628067432b30671466309e3d630b106d413f1708765bf2a9399a1
+  source_path: concepts/architecture.md
+  workflow: 15
+---
+
+# Gateway 网关架构
+
+最后更新：2026-01-22
+
+## 概述
+
+- 单个长期运行的 **Gateway 网关**拥有所有消息平台（通过 Baileys 的 WhatsApp、通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
+- 控制平面客户端（macOS 应用、CLI、Web 界面、自动化）通过配置的绑定主机（默认 `127.0.0.1:18789`）上的 **WebSocket** 连接到 Gateway 网关。
+- **节点**（macOS/iOS/Android/无头设备）也通过 **WebSocket** 连接，但声明 `role: node` 并带有明确的能力/命令。
+- 每台主机一个 Gateway 网关；它是唯一打开 WhatsApp 会话的位置。
+- **canvas 主机**（默认 `18793`）提供智能体可编辑的 HTML 和 A2UI。
+
+## 组件和流程
+
+### Gateway 网关（守护进程）
+
+- 维护提供商连接。
+- 暴露类型化的 WS API（请求、响应、服务器推送事件）。
+- 根据 JSON Schema 验证入站帧。
+- 发出事件如 `agent`、`chat`、`presence`、`health`、`heartbeat`、`cron`。
+
+### 客户端（mac 应用 / CLI / web 管理）
+
+- 每个客户端一个 WS 连接。
+- 发送请求（`health`、`status`、`send`、`agent`、`system-presence`）。
+- 订阅事件（`tick`、`agent`、`presence`、`shutdown`）。
+
+### 节点（macOS / iOS / Android / 无头设备）
+
+- 以 `role: node` 连接到**同一个 WS 服务器**。
+- 在 `connect` 中提供设备身份；配对是**基于设备**的（角色为 `node`），批准存储在设备配对存储中。
+- 暴露命令如 `canvas.*`、`camera.*`、`screen.record`、`location.get`。
+
+协议详情：
+
+- [Gateway 网关协议](/gateway/protocol)
+
+### WebChat
+
+- 静态界面，使用 Gateway 网关 WS API 获取聊天历史和发送消息。
+- 在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接。
+
+## 连接生命周期（单个客户端）
+
+```
+Client                    Gateway
+  |                          |
+  |---- req:connect -------->|
+  |<------ res (ok) ---------|   (or res error + close)
+  |   (payload=hello-ok carries snapshot: presence + health)
+  |                          |
+  |<------ event:presence ---|
+  |<------ event:tick -------|
+  |                          |
+  |------- req:agent ------->|
+  |<------ res:agent --------|   (ack: {runId,status:"accepted"})
+  |<------ event:agent ------|   (streaming)
+  |<------ res:agent --------|   (final: {runId,status,summary})
+  |                          |
+```
+
+## 线路协议（摘要）
+
+- 传输：WebSocket，带 JSON 载荷的文本帧。
+- 第一帧**必须**是 `connect`。
+- 握手后：
+  - 请求：`{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
+  - 事件：`{type:"event", event, payload, seq?, stateVersion?}`
+- 如果设置了 `OPENCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token` 必须匹配，否则套接字关闭。
+- 有副作用的方法（`send`、`agent`）需要幂等键以安全重试；服务器保持短期去重缓存。
+- 节点必须在 `connect` 中包含 `role: "node"` 以及能力/命令/权限。
+
+## 配对 + 本地信任
+
+- 所有 WS 客户端（操作员 + 节点）在 `connect` 时包含**设备身份**。
+- 新设备 ID 需要配对批准；Gateway 网关为后续连接颁发**设备令牌**。
+- **本地**连接（loopback 或 Gateway 网关主机自身的 tailnet 地址）可以自动批准以保持同主机用户体验流畅。
+- **非本地**连接必须签名 `connect.challenge` nonce 并需要明确批准。
+- Gateway 网关认证（`gateway.auth.*`）仍适用于**所有**连接，无论本地还是远程。
+
+详情：[Gateway 网关协议](/gateway/protocol)、[配对](/start/pairing)、[安全](/gateway/security)。
+
+## 协议类型和代码生成
+
+- TypeBox 模式定义协议。
+- 从这些模式生成 JSON Schema。
+- 从 JSON Schema 生成 Swift 模型。
+
+## 远程访问
+
+- 推荐：Tailscale 或 VPN。
+- 替代方案：SSH 隧道
+  ```bash
+  ssh -N -L 18789:127.0.0.1:18789 user@host
+  ```
+- 相同的握手 + 认证令牌适用于隧道连接。
+- 远程设置中可以为 WS 启用 TLS + 可选的证书固定。
+
+## 操作快照
+
+- 启动：`openclaw gateway`（前台，日志输出到 stdout）。
+- 健康检查：通过 WS 的 `health`（也包含在 `hello-ok` 中）。
+- 监控：使用 launchd/systemd 自动重启。
+
+## 不变量
+
+- 每台主机恰好一个 Gateway 网关控制单个 Baileys 会话。
+- 握手是强制的；任何非 JSON 或非 connect 的第一帧都会导致硬关闭。
+- 事件不会重放；客户端必须在出现间隙时刷新。