@gguf/claw 2026.2.1 → 2026.2.3

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,150 @@
+---
+read_when:
+  - 你需要智能体循环或生命周期事件的详细说明
+summary: 智能体循环生命周期、流和等待语义
+title: 智能体循环
+x-i18n:
+  generated_at: "2026-02-01T20:22:03Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0775b96eb3451e137297661a1095eaefb2bafeebb5f78123174a46290e18b014
+  source_path: concepts/agent-loop.md
+  workflow: 14
+---
+
+# 智能体循环（OpenClaw）
+
+智能体循环是智能体的一次完整"真实"运行：接收 → 上下文组装 → 模型推理 →
+工具执行 → 流式回复 → 持久化。它是将消息转化为操作和最终回复的权威路径，同时保持会话状态的一致性。
+
+在 OpenClaw 中，循环是每个会话的单次序列化运行，在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档解释了这个完整循环是如何端到端连接的。
+
+## 入口点
+
+- Gateway网关 RPC：`agent` 和 `agent.wait`。
+- CLI：`agent` 命令。
+
+## 工作原理（高层概述）
+
+1. `agent` RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 `{ runId, acceptedAt }`。
+2. `agentCommand` 运行智能体：
+   - 解析模型 + thinking/verbose 默认值
+   - 加载 Skills 快照
+   - 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时）
+   - 如果嵌入式循环未发出**生命周期 end/error** 事件，则补充发出
+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` 的**生命周期 end/error**
+   - 返回 `{ 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)了解分块和块回复行为。
+
+## 工具执行 + 消息工具
+
+- 工具的 start/update/end 事件在 `tool` 流上发出。
+- 工具结果在记录/发出之前会针对大小和图片载荷进行清理。
+- 消息工具的发送会被跟踪，以抑制重复的助手确认。
+
+## 回复整形 + 抑制
+
+- 最终载荷由以下内容组装：
+  - 助手文本（及可选的推理内容）
+  - 内联工具摘要（当 verbose + 允许时）
+  - 模型出错时的助手错误文本
+- `NO_REPLY` 被视为静默令牌，从传出载荷中过滤。
+- 消息工具的重复项从最终载荷列表中移除。
+- 如果没有可渲染的载荷且工具出错，则发出回退的工具错误回复
+  （除非消息工具已发送了用户可见的回复）。
+
+## 压缩 + 重试
+
+- 自动压缩发出 `compaction` 流事件，并可能触发重试。
+- 重试时，内存缓冲区和工具摘要会被重置以避免重复输出。
+- 参见[压缩](/concepts/compaction)了解压缩管道。
+
+## 事件流（当前）
+
+- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（以及作为 `agentCommand` 的回退）
+- `assistant`：来自 pi-agent-core 的流式增量
+- `tool`：来自 pi-agent-core 的流式工具事件
+
+## 聊天渠道处理
+
+- 助手增量被缓冲为聊天 `delta` 消息。
+- 在**生命周期 end/error** 时发出聊天 `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,214 @@
+---
+read_when:
+  - 你需要解释智能体工作区或其文件布局
+  - 你想要备份或迁移智能体工作区
+summary: 智能体工作区：位置、布局和备份策略
+title: 智能体工作区
+x-i18n:
+  generated_at: "2026-02-01T20:22:05Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 84c550fd89b5f2474aeae586795485fd29d36effbb462f13342b31540fc18b82
+  source_path: concepts/agent-workspace.md
+  workflow: 14
+---
+
+# 智能体工作区
+
+工作区是智能体的主目录。它是文件工具和工作区上下文使用的唯一工作目录。请将其保持私密，并视为记忆来对待。
+
+它与 `~/.openclaw/` 是分开的，后者存储配置、凭据和会话。
+
+**重要提示：** 工作区是**默认工作目录**，而非硬性沙箱。工具会基于工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱。如果你需要隔离，请使用 [`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`
+  - 可选的心跳运行小清单。
+  - 保持简短以避免消耗令牌。
+
+- `BOOT.md`
+  - 可选的启动清单，在启用内部钩子时于 Gateway网关重启时执行。
+  - 保持简短；使用消息工具进行外发。
+
+- `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 令牌、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 令牌、密码或私有凭据。
+- `~/.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,114 @@
+---
+read_when:
+  - 更改智能体运行时、工作区引导或会话行为
+summary: 智能体运行时（嵌入式 pi-mono）、工作区契约和会话引导
+title: 智能体运行时
+x-i18n:
+  generated_at: "2026-02-01T20:22:02Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 04b4e0bc6345d2afd9a93186e5d7a02a393ec97da2244e531703cb6a1c182325
+  source_path: concepts/agent.md
+  workflow: 14
+---
+
+# 智能体运行时 🤖
+
+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-01T20:22:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c636d5d8a5e628067432b30671466309e3d630b106d413f1708765bf2a9399a1
+  source_path: concepts/architecture.md
+  workflow: 14
+---
+
+# Gateway网关架构
+
+最后更新：2026-01-22
+
+## 概述
+
+- 单个长生命周期的 **Gateway网关** 管理所有消息接入面（通过 Baileys 接入 WhatsApp、通过 grammY 接入 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
+- 控制面客户端（macOS 应用、CLI、Web UI、自动化）通过 **WebSocket** 连接到 Gateway网关，使用配置的绑定地址（默认 `127.0.0.1:18789`）。
+- **节点**（macOS/iOS/Android/无头模式）也通过 **WebSocket** 连接，但声明 `role: node` 并显式指定能力/命令。
+- 每台主机一个 Gateway网关；它是唯一打开 WhatsApp 会话的位置。
+- **画布主机**（默认 `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 / 无头模式）
+
+- 连接到**同一个 WS 服务器**，声明 `role: node`。
+- 在 `connect` 中提供设备身份；配对是**基于设备**的（角色为 `node`），审批信息存储在设备配对存储中。
+- 暴露 `canvas.*`、`camera.*`、`screen.record`、`location.get` 等命令。
+
+协议详情：
+
+- [Gateway网关协议](/gateway/protocol)
+
+### WebChat
+
+- 静态 UI，使用 Gateway网关 WS API 获取聊天历史和发送消息。
+- 在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接。
+
+## 连接生命周期（单个客户端）
+
+```
+Client                    Gateway网关
+  |                          |
+  |---- req:connect -------->|
+  |<------ res (ok) ---------|   （或 res error + 关闭）
+  |   （payload=hello-ok 携带快照：presence + health）
+  |                          |
+  |<------ event:presence ---|
+  |<------ event:tick -------|
+  |                          |
+  |------- req:agent ------->|
+  |<------ res:agent --------|   （确认：{runId,status:"accepted"}）
+  |<------ event:agent ------|   （流式传输）
+  |<------ res:agent --------|   （最终：{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网关颁发**设备令牌**用于后续连接。
+- **本地**连接（local loopback 或 Gateway网关主机自身的 tailnet 地址）可以自动审批，以保持同主机用户体验的流畅性。
+- **非本地**连接必须对 `connect.challenge` nonce 签名，并需要显式审批。
+- Gateway网关认证（`gateway.auth.*`）仍适用于**所有**连接，无论本地还是远程。
+
+详情：[Gateway网关协议](/gateway/protocol)、[配对](/start/pairing)、[安全](/gateway/security)。
+
+## 协议类型定义与代码生成
+
+- TypeBox schema 定义协议。
+- 从这些 schema 生成 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 的首帧将导致硬关闭。
+- 事件不会重放；客户端必须在出现间隙时刷新。