@captain-app/openclaw 2026.2.4

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

@@ -0,0 +1,257 @@
+---
+read_when:
+  - 开发 Google Chat 渠道功能时
+summary: Google Chat 应用支持状态、功能和配置
+title: Google Chat
+x-i18n:
+  generated_at: "2026-02-03T07:43:39Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3b2bb116cdd12614c3d5afddd0879e9deb05c3606e3a2385cbc07f23552b357e
+  source_path: channels/googlechat.md
+  workflow: 15
+---
+
+# Google Chat（Chat API）
+
+状态：已支持通过 Google Chat API webhooks（仅 HTTP）使用私信和空间。
+
+## 快速设置（新手）
+
+1. 创建一个 Google Cloud 项目并启用 **Google Chat API**。
+   - 前往：[Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
+   - 如果 API 尚未启用，请启用它。
+2. 创建一个**服务账号**：
+   - 点击 **Create Credentials** > **Service Account**。
+   - 随意命名（例如 `openclaw-chat`）。
+   - 权限留空（点击 **Continue**）。
+   - 有访问权限的主账号留空（点击 **Done**）。
+3. 创建并下载 **JSON 密钥**：
+   - 在服务账号列表中，点击刚刚创建的账号。
+   - 前往 **Keys** 标签页。
+   - 点击 **Add Key** > **Create new key**。
+   - 选择 **JSON** 并点击 **Create**。
+4. 将下载的 JSON 文件存储在 Gateway 网关主机上（例如 `~/.openclaw/googlechat-service-account.json`）。
+5. 在 [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建一个 Google Chat 应用：
+   - 填写 **Application info**：
+     - **App name**：（例如 `OpenClaw`）
+     - **Avatar URL**：（例如 `https://openclaw.ai/logo.png`）
+     - **Description**：（例如 `Personal AI Assistant`）
+   - 启用 **Interactive features**。
+   - 在 **Functionality** 下，勾选 **Join spaces and group conversations**。
+   - 在 **Connection settings** 下，选择 **HTTP endpoint URL**。
+   - 在 **Triggers** 下，选择 **Use a common HTTP endpoint URL for all triggers** 并将其设置为你的 Gateway 网关公网 URL 后加 `/googlechat`。
+     - _提示：运行 `openclaw status` 查看你的 Gateway 网关公网 URL。_
+   - 在 **Visibility** 下，勾选 **Make this Chat app available to specific people and groups in <Your Domain>**。
+   - 在文本框中输入你的邮箱地址（例如 `user@example.com`）。
+   - 点击底部的 **Save**。
+6. **启用应用状态**：
+   - 保存后，**刷新页面**。
+   - 找到 **App status** 部分（通常在保存后位于顶部或底部附近）。
+   - 将状态更改为 **Live - available to users**。
+   - 再次点击 **Save**。
+7. 使用服务账号路径和 webhook audience 配置 OpenClaw：
+   - 环境变量：`GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
+   - 或配置：`channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。
+8. 设置 webhook audience 类型和值（与你的 Chat 应用配置匹配）。
+9. 启动 Gateway 网关。Google Chat 将向你的 webhook 路径发送 POST 请求。
+
+## 添加到 Google Chat
+
+Gateway 网关运行后，且你的邮箱已添加到可见性列表中：
+
+1. 前往 [Google Chat](https://chat.google.com/)。
+2. 点击 **Direct Messages** 旁边的 **+**（加号）图标。
+3. 在搜索栏（通常用于添加联系人的位置）中，输入你在 Google Cloud Console 中配置的 **App name**。
+   - **注意**：该机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。
+4. 从结果中选择你的机器人。
+5. 点击 **Add** 或 **Chat** 开始一对一对话。
+6. 发送"Hello"来触发助手！
+
+## 公网 URL（仅 Webhook）
+
+Google Chat webhooks 需要一个公网 HTTPS 端点。为了安全起见，**只将 `/googlechat` 路径暴露到互联网**。将 OpenClaw 仪表板和其他敏感端点保留在你的私有网络上。
+
+### 方案 A：Tailscale Funnel（推荐）
+
+使用 Tailscale Serve 提供私有仪表板，使用 Funnel 提供公网 webhook 路径。这样可以保持 `/` 私有，同时只暴露 `/googlechat`。
+
+1. **检查你的 Gateway 网关绑定的地址：**
+
+   ```bash
+   ss -tlnp | grep 18789
+   ```
+
+   记下 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。
+
+2. **仅将仪表板暴露给 tailnet（端口 8443）：**
+
+   ```bash
+   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
+   tailscale serve --bg --https 8443 http://127.0.0.1:18789
+
+   # 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
+   tailscale serve --bg --https 8443 http://100.106.161.80:18789
+   ```
+
+3. **仅公开暴露 webhook 路径：**
+
+   ```bash
+   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
+   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
+
+   # 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
+   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
+   ```
+
+4. **授权节点访问 Funnel：**
+   如果出现提示，请访问输出中显示的授权 URL，以在你的 tailnet 策略中为此节点启用 Funnel。
+
+5. **验证配置：**
+   ```bash
+   tailscale serve status
+   tailscale funnel status
+   ```
+
+你的公网 webhook URL 将是：
+`https://<node-name>.<tailnet>.ts.net/googlechat`
+
+你的私有仪表板仅限 tailnet 访问：
+`https://<node-name>.<tailnet>.ts.net:8443/`
+
+在 Google Chat 应用配置中使用公网 URL（不带 `:8443`）。
+
+> 注意：此配置在重启后会保留。如需稍后移除，请运行 `tailscale funnel reset` 和 `tailscale serve reset`。
+
+### 方案 B：反向代理（Caddy）
+
+如果你使用像 Caddy 这样的反向代理，只代理特定路径：
+
+```caddy
+your-domain.com {
+    reverse_proxy /googlechat* localhost:18789
+}
+```
+
+使用此配置，任何发往 `your-domain.com/` 的请求将被忽略或返回 404，而 `your-domain.com/googlechat` 会安全地路由到 OpenClaw。
+
+### 方案 C：Cloudflare Tunnel
+
+配置你的隧道入口规则，只路由 webhook 路径：
+
+- **路径**：`/googlechat` -> `http://localhost:18789/googlechat`
+- **默认规则**：HTTP 404（未找到）
+
+## 工作原理
+
+1. Google Chat 向 Gateway 网关发送 webhook POST 请求。每个请求都包含一个 `Authorization: Bearer <token>` 头。
+2. OpenClaw 根据配置的 `audienceType` + `audience` 验证令牌：
+   - `audienceType: "app-url"` → audience 是你的 HTTPS webhook URL。
+   - `audienceType: "project-number"` → audience 是 Cloud 项目编号。
+3. 消息按空间路由：
+   - 私信使用会话键 `agent:<agentId>:googlechat:dm:<spaceId>`。
+   - 空间使用会话键 `agent:<agentId>:googlechat:group:<spaceId>`。
+4. 私信访问默认为配对模式。未知发送者会收到配对码；使用以下命令批准：
+   - `openclaw pairing approve googlechat <code>`
+5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 `botUser`。
+
+## 目标标识符
+
+使用这些标识符进行消息投递和允许列表：
+
+- 私信：`users/<userId>` 或 `users/<email>`（接受邮箱地址）。
+- 空间：`spaces/<spaceId>`。
+
+## 配置要点
+
+```json5
+{
+  channels: {
+    googlechat: {
+      enabled: true,
+      serviceAccountFile: "/path/to/service-account.json",
+      audienceType: "app-url",
+      audience: "https://gateway.example.com/googlechat",
+      webhookPath: "/googlechat",
+      botUser: "users/1234567890", // 可选；帮助提及检测
+      dm: {
+        policy: "pairing",
+        allowFrom: ["users/1234567890", "name@example.com"],
+      },
+      groupPolicy: "allowlist",
+      groups: {
+        "spaces/AAAA": {
+          allow: true,
+          requireMention: true,
+          users: ["users/1234567890"],
+          systemPrompt: "Short answers only.",
+        },
+      },
+      actions: { reactions: true },
+      typingIndicator: "message",
+      mediaMaxMb: 20,
+    },
+  },
+}
+```
+
+注意事项：
+
+- 服务账号凭证也可以通过 `serviceAccount`（JSON 字符串）内联传递。
+- 如果未设置 `webhookPath`，默认 webhook 路径为 `/googlechat`。
+- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用表情回应。
+- `typingIndicator` 支持 `none`、`message`（默认）和 `reaction`（reaction 需要用户 OAuth）。
+- 附件通过 Chat API 下载并存储在媒体管道中（大小受 `mediaMaxMb` 限制）。
+
+## 故障排除
+
+### 405 Method Not Allowed
+
+如果 Google Cloud Logs Explorer 显示如下错误：
+
+```
+status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
+```
+
+这意味着 webhook 处理程序未注册。常见原因：
+
+1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。使用以下命令验证：
+
+   ```bash
+   openclaw config get channels.googlechat
+   ```
+
+   如果返回"Config path not found"，请添加配置（参见[配置要点](#配置要点)）。
+
+2. **插件未启用**：检查插件状态：
+
+   ```bash
+   openclaw plugins list | grep googlechat
+   ```
+
+   如果显示"disabled"，请在配置中添加 `plugins.entries.googlechat.enabled: true`。
+
+3. **Gateway 网关未重启**：添加配置后，重启 Gateway 网关：
+   ```bash
+   openclaw gateway restart
+   ```
+
+验证渠道是否正在运行：
+
+```bash
+openclaw channels status
+# 应显示：Google Chat default: enabled, configured, ...
+```
+
+### 其他问题
+
+- 检查 `openclaw channels status --probe` 以查看认证错误或缺少 audience 配置。
+- 如果没有收到消息，请确认 Chat 应用的 webhook URL 和事件订阅。
+- 如果提及门控阻止了回复，请将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。
+- 在发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway 网关。
+
+相关文档：
+
+- [Gateway 网关配置](/gateway/configuration)
+- [安全](/gateway/security)
+- [表情回应](/tools/reactions)

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

@@ -0,0 +1,38 @@
+---
+read_when:
+  - 开发 Telegram 或 grammY 相关功能时
+summary: 通过 grammY 集成 Telegram Bot API，附设置说明
+title: grammY
+x-i18n:
+  generated_at: "2026-02-03T10:03:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ea7ef23e6d77801f4ef5fc56685ef4470f79f5aecab448d644a72cbab53521b7
+  source_path: channels/grammy.md
+  workflow: 15
+---
+
+# grammY 集成（Telegram Bot API）
+
+# 为什么选择 grammY
+
+- 以 TS 为核心的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理和速率限制器。
+- 媒体处理辅助工具比手动编写 fetch + FormData 更简洁；支持所有 Bot API 方法。
+- 可扩展：通过自定义 fetch 支持代理，可选的会话中间件，类型安全的上下文。
+
+# 我们发布的内容
+
+- **单一客户端路径：** 移除了基于 fetch 的实现；grammY 现在是唯一的 Telegram 客户端（发送 + Gateway 网关），默认启用 grammY throttler。
+- **Gateway 网关：** `monitorTelegramProvider` 构建 grammY `Bot`，接入 mention/allowlist 网关控制，通过 `getFile`/`download` 下载媒体，并使用 `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument` 发送回复。通过 `webhookCallback` 支持长轮询或 webhook。
+- **代理：** 可选的 `channels.telegram.proxy` 通过 grammY 的 `client.baseFetch` 使用 `undici.ProxyAgent`。
+- **Webhook 支持：** `webhook-set.ts` 封装了 `setWebhook/deleteWebhook`；`webhook.ts` 托管回调，支持健康检查和优雅关闭。当设置了 `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` 时，Gateway 网关启用 webhook 模式（否则使用长轮询）。
+- **会话：** 私聊折叠到智能体主会话（`agent:<agentId>:<mainKey>`）；群组使用 `agent:<agentId>:telegram:group:<chatId>`；回复路由回同一渠道。
+- **配置选项：** `channels.telegram.botToken`、`channels.telegram.dmPolicy`、`channels.telegram.groups`（allowlist + mention 默认值）、`channels.telegram.allowFrom`、`channels.telegram.groupAllowFrom`、`channels.telegram.groupPolicy`、`channels.telegram.mediaMaxMb`、`channels.telegram.linkPreview`、`channels.telegram.proxy`、`channels.telegram.webhookSecret`、`channels.telegram.webhookUrl`。
+- **草稿流式传输：** 可选的 `channels.telegram.streamMode` 在私有话题聊天中使用 `sendMessageDraft`（Bot API 9.3+）。这与渠道分块流式传输是分开的。
+- **测试：** grammY mock 覆盖了私信 + 群组 mention 网关控制和出站发送；欢迎添加更多媒体/webhook 测试用例。
+
+待解决问题
+
+- 如果遇到 Bot API 429 错误，考虑使用可选的 grammY 插件（throttler）。
+- 添加更多结构化媒体测试（贴纸、语音消息）。
+- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway 网关配置）。

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

@@ -0,0 +1,302 @@
+---
+read_when:
+  - 设置 iMessage 支持
+  - 调试 iMessage 发送/接收
+summary: 通过 imsg（基于 stdio 的 JSON-RPC）实现 iMessage 支持、设置及 chat_id 路由
+title: iMessage
+x-i18n:
+  generated_at: "2026-02-03T07:44:18Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bc19756a42ead80a0845f18c4830c3f1f40948f69b2b016a4026598cfb8fef0d
+  source_path: channels/imessage.md
+  workflow: 15
+---
+
+# iMessage (imsg)
+
+状态：外部 CLI 集成。Gateway 网关生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。
+
+## 快速设置（新手）
+
+1. 确保在此 Mac 上已登录"信息"。
+2. 安装 `imsg`：
+   - `brew install steipete/tap/imsg`
+3. 配置 OpenClaw 的 `channels.imessage.cliPath` 和 `channels.imessage.dbPath`。
+4. 启动 Gateway 网关并批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。
+
+最小配置：
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "/usr/local/bin/imsg",
+      dbPath: "/Users/<you>/Library/Messages/chat.db",
+    },
+  },
+}
+```
+
+## 简介
+
+- 基于 macOS 上 `imsg` 的 iMessage 渠道。
+- 确定性路由：回复始终返回到 iMessage。
+- 私信共享智能体的主会话；群组是隔离的（`agent:<agentId>:imessage:group:<chat_id>`）。
+- 如果多参与者会话以 `is_group=false` 到达，你仍可使用 `channels.imessage.groups` 按 `chat_id` 隔离（参见下方"类群组会话"）。
+
+## 配置写入
+
+默认情况下，iMessage 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。
+
+禁用方式：
+
+```json5
+{
+  channels: { imessage: { configWrites: false } },
+}
+```
+
+## 要求
+
+- 已登录"信息"的 macOS。
+- OpenClaw + `imsg` 的完全磁盘访问权限（访问"信息"数据库）。
+- 发送时需要自动化权限。
+- `channels.imessage.cliPath` 可以指向任何代理 stdin/stdout 的命令（例如，通过 SSH 连接到另一台 Mac 并运行 `imsg rpc` 的包装脚本）。
+
+## 设置（快速路径）
+
+1. 确保在此 Mac 上已登录"信息"。
+2. 配置 iMessage 并启动 Gateway 网关。
+
+### 专用机器人 macOS 用户（用于隔离身份）
+
+如果你希望机器人从**独立的 iMessage 身份**发送（并保持你的个人"信息"整洁），请使用专用 Apple ID + 专用 macOS 用户。
+
+1. 创建专用 Apple ID（例如：`my-cool-bot@icloud.com`）。
+   - Apple 可能需要电话号码进行验证 / 2FA。
+2. 创建 macOS 用户（例如：`openclawhome`）并登录。
+3. 在该 macOS 用户中打开"信息"并使用机器人 Apple ID 登录 iMessage。
+4. 启用远程登录（系统设置 → 通用 → 共享 → 远程登录）。
+5. 安装 `imsg`：
+   - `brew install steipete/tap/imsg`
+6. 设置 SSH 使 `ssh <bot-macos-user>@localhost true` 无需密码即可工作。
+7. 将 `channels.imessage.accounts.bot.cliPath` 指向以机器人用户身份运行 `imsg` 的 SSH 包装脚本。
+
+首次运行注意事项：发送/接收可能需要在*机器人 macOS 用户*中进行 GUI 批准（自动化 + 完全磁盘访问权限）。如果 `imsg rpc` 看起来卡住或退出，请登录该用户（屏幕共享很有帮助），运行一次 `imsg chats --limit 1` / `imsg send ...`，批准提示，然后重试。
+
+示例包装脚本（`chmod +x`）。将 `<bot-macos-user>` 替换为你的实际 macOS 用户名：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run an interactive SSH once first to accept host keys:
+#   ssh <bot-macos-user>@localhost true
+exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
+  "/usr/local/bin/imsg" "$@"
+```
+
+示例配置：
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      accounts: {
+        bot: {
+          name: "Bot",
+          enabled: true,
+          cliPath: "/path/to/imsg-bot",
+          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
+        },
+      },
+    },
+  },
+}
+```
+
+对于单账户设置，使用扁平选项（`channels.imessage.cliPath`、`channels.imessage.dbPath`）而不是 `accounts` 映射。
+
+### 远程/SSH 变体（可选）
+
+如果你想在另一台 Mac 上使用 iMessage，请将 `channels.imessage.cliPath` 设置为通过 SSH 在远程 macOS 主机上运行 `imsg` 的包装脚本。OpenClaw 只需要 stdio。
+
+示例包装脚本：
+
+```bash
+#!/usr/bin/env bash
+exec ssh -T gateway-host imsg "$@"
+```
+
+**远程附件：** 当 `cliPath` 通过 SSH 指向远程主机时，"信息"数据库中的附件路径引用的是远程机器上的文件。OpenClaw 可以通过设置 `channels.imessage.remoteHost` 自动通过 SCP 获取这些文件：
+
+```json5
+{
+  channels: {
+    imessage: {
+      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
+      remoteHost: "user@gateway-host", // for SCP file transfer
+      includeAttachments: true,
+    },
+  },
+}
+```
+
+如果未设置 `remoteHost`，OpenClaw 会尝试通过解析包装脚本中的 SSH 命令自动检测。建议显式配置以提高可靠性。
+
+#### 通过 Tailscale 连接远程 Mac（示例）
+
+如果 Gateway 网关运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上，Tailscale 是最简单的桥接方式：Gateway 网关通过 tailnet 与 Mac 通信，通过 SSH 运行 `imsg`，并通过 SCP 获取附件。
+
+架构：
+
+```
+┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
+│ Gateway host (Linux/VM)      │──────────────────────────────────▶│ Mac with Messages + imsg │
+│ - openclaw gateway           │          SCP (attachments)        │ - Messages signed in     │
+│ - channels.imessage.cliPath  │◀──────────────────────────────────│ - Remote Login enabled   │
+└──────────────────────────────┘                                   └──────────────────────────┘
+              ▲
+              │ Tailscale tailnet (hostname or 100.x.y.z)
+              ▼
+        user@gateway-host
+```
+
+具体配置示例（Tailscale 主机名）：
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "~/.openclaw/scripts/imsg-ssh",
+      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
+      includeAttachments: true,
+      dbPath: "/Users/bot/Library/Messages/chat.db",
+    },
+  },
+}
+```
+
+示例包装脚本（`~/.openclaw/scripts/imsg-ssh`）：
+
+```bash
+#!/usr/bin/env bash
+exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
+```
+
+注意事项：
+
+- 确保 Mac 已登录"信息"，并已启用远程登录。
+- 使用 SSH 密钥使 `ssh bot@mac-mini.tailnet-1234.ts.net` 无需提示即可工作。
+- `remoteHost` 应与 SSH 目标匹配，以便 SCP 可以获取附件。
+
+多账户支持：使用 `channels.imessage.accounts` 配置每个账户及可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解共享模式。不要提交 `~/.openclaw/openclaw.json`（它通常包含令牌）。
+
+## 访问控制（私信 + 群组）
+
+私信：
+
+- 默认：`channels.imessage.dmPolicy = "pairing"`。
+- 未知发送者会收到配对码；消息在批准前会被忽略（配对码在 1 小时后过期）。
+- 批准方式：
+  - `openclaw pairing list imessage`
+  - `openclaw pairing approve imessage <CODE>`
+- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/start/pairing)
+
+群组：
+
+- `channels.imessage.groupPolicy = open | allowlist | disabled`。
+- 设置 `allowlist` 时，`channels.imessage.groupAllowFrom` 控制谁可以在群组中触发。
+- 提及检测使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`），因为 iMessage 没有原生提及元数据。
+- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
+
+## 工作原理（行为）
+
+- `imsg` 流式传输消息事件；Gateway 网关将它们规范化为共享渠道信封。
+- 回复始终路由回相同的 chat id 或 handle。
+
+## 类群组会话（`is_group=false`）
+
+某些 iMessage 会话可能有多个参与者，但根据"信息"存储聊天标识符的方式，仍以 `is_group=false` 到达。
+
+如果你在 `channels.imessage.groups` 下显式配置了 `chat_id`，OpenClaw 会将该会话视为"群组"用于：
+
+- 会话隔离（独立的 `agent:<agentId>:imessage:group:<chat_id>` 会话键）
+- 群组允许列表 / 提及检测行为
+
+示例：
+
+```json5
+{
+  channels: {
+    imessage: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15555550123"],
+      groups: {
+        "42": { requireMention: false },
+      },
+    },
+  },
+}
+```
+
+当你想为特定会话使用隔离的个性/模型时这很有用（参见[多智能体路由](/concepts/multi-agent)）。关于文件系统隔离，参见[沙箱隔离](/gateway/sandboxing)。
+
+## 媒体 + 限制
+
+- 通过 `channels.imessage.includeAttachments` 可选附件摄取。
+- 通过 `channels.imessage.mediaMaxMb` 设置媒体上限。
+
+## 限制
+
+- 出站文本按 `channels.imessage.textChunkLimit` 分块（默认 4000）。
+- 可选换行分块：设置 `channels.imessage.chunkMode="newline"` 在长度分块前按空行（段落边界）分割。
+- 媒体上传受 `channels.imessage.mediaMaxMb` 限制（默认 16）。
+
+## 寻址 / 投递目标
+
+优先使用 `chat_id` 进行稳定路由：
+
+- `chat_id:123`（推荐）
+- `chat_guid:...`
+- `chat_identifier:...`
+- 直接 handle：`imessage:+1555` / `sms:+1555` / `user@example.com`
+
+列出聊天：
+
+```
+imsg chats --limit 20
+```
+
+## 配置参考（iMessage）
+
+完整配置：[配置](/gateway/configuration)
+
+提供商选项：
+
+- `channels.imessage.enabled`：启用/禁用渠道启动。
+- `channels.imessage.cliPath`：`imsg` 路径。
+- `channels.imessage.dbPath`："信息"数据库路径。
+- `channels.imessage.remoteHost`：当 `cliPath` 指向远程 Mac 时用于 SCP 附件传输的 SSH 主机（例如 `user@gateway-host`）。如未设置则从 SSH 包装脚本自动检测。
+- `channels.imessage.service`：`imessage | sms | auto`。
+- `channels.imessage.region`：短信区域。
+- `channels.imessage.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
+- `channels.imessage.allowFrom`：私信允许列表（handle、邮箱、E.164 号码或 `chat_id:*`）。`open` 需要 `"*"`。iMessage 没有用户名；使用 handle 或聊天目标。
+- `channels.imessage.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。
+- `channels.imessage.groupAllowFrom`：群组发送者允许列表。
+- `channels.imessage.historyLimit` / `channels.imessage.accounts.*.historyLimit`：作为上下文包含的最大群组消息数（0 禁用）。
+- `channels.imessage.dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`channels.imessage.dms["<handle>"].historyLimit`。
+- `channels.imessage.groups`：每群组默认值 + 允许列表（使用 `"*"` 作为全局默认值）。
+- `channels.imessage.includeAttachments`：将附件摄取到上下文。
+- `channels.imessage.mediaMaxMb`：入站/出站媒体上限（MB）。
+- `channels.imessage.textChunkLimit`：出站分块大小（字符）。
+- `channels.imessage.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。
+
+相关全局选项：
+
+- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
+- `messages.responsePrefix`。

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

@@ -0,0 +1,53 @@
+---
+read_when:
+  - 你想为 OpenClaw 选择一个聊天渠道
+  - 你需要快速了解支持的消息平台
+summary: OpenClaw 可连接的消息平台
+title: 聊天渠道
+x-i18n:
+  generated_at: "2026-02-03T07:43:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2632863def6dee97e0fa8b931762f0969174fd4fb22303a00dcd46527fe4a141
+  source_path: channels/index.md
+  workflow: 15
+---
+
+# 聊天渠道
+
+OpenClaw 可以在你已经使用的任何聊天应用上与你交流。每个渠道通过 Gateway 网关连接。
+所有渠道都支持文本；媒体和表情回应的支持因渠道而异。
+
+## 支持的渠道
+
+- [WhatsApp](/channels/whatsapp) — 最受欢迎；使用 Baileys，需要二维码配对。
+- [Telegram](/channels/telegram) — 通过 grammY 使用 Bot API；支持群组。
+- [Discord](/channels/discord) — Discord Bot API + Gateway；支持服务器、频道和私信。
+- [Slack](/channels/slack) — Bolt SDK；工作区应用。
+- [飞书](/channels/feishu) — 飞书（Lark）机器人（插件，需单独安装）。
+- [Google Chat](/channels/googlechat) — 通过 HTTP webhook 的 Google Chat API 应用。
+- [Mattermost](/channels/mattermost) — Bot API + WebSocket；频道、群组、私信（插件，需单独安装）。
+- [Signal](/channels/signal) — signal-cli；注重隐私。
+- [BlueBubbles](/channels/bluebubbles) — **推荐用于 iMessage**；使用 BlueBubbles macOS 服务器 REST API，功能完整（编辑、撤回、特效、回应、群组管理——编辑功能在 macOS 26 Tahoe 上目前不可用）。
+- [iMessage（旧版）](/channels/imessage) — 通过 imsg CLI 的旧版 macOS 集成（已弃用，新设置请使用 BlueBubbles）。
+- [Microsoft Teams](/channels/msteams) — Bot Framework；企业支持（插件，需单独安装）。
+- [LINE](/channels/line) — LINE Messaging API 机器人（插件，需单独安装）。
+- [Nextcloud Talk](/channels/nextcloud-talk) — 通过 Nextcloud Talk 的自托管聊天（插件，需单独安装）。
+- [Matrix](/channels/matrix) — Matrix 协议（插件，需单独安装）。
+- [Nostr](/channels/nostr) — 通过 NIP-04 的去中心化私信（插件，需单独安装）。
+- [Tlon](/channels/tlon) — 基于 Urbit 的消息应用（插件，需单独安装）。
+- [Twitch](/channels/twitch) — 通过 IRC 连接的 Twitch 聊天（插件，需单独安装）。
+- [Zalo](/channels/zalo) — Zalo Bot API；越南流行的消息应用（插件，需单独安装）。
+- [Zalo Personal](/channels/zalouser) — 通过二维码登录的 Zalo 个人账号（插件，需单独安装）。
+- [WebChat](/web/webchat) — 基于 WebSocket 的 Gateway 网关 WebChat 界面。
+
+## 注意事项
+
+- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。
+- 最快的设置方式通常是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对，
+  并在磁盘上存储更多状态。
+- 群组行为因渠道而异；参见[群组](/concepts/groups)。
+- 为安全起见，私信配对和允许列表会被强制执行；参见[安全](/gateway/security)。
+- Telegram 内部机制：[grammY 说明](/channels/grammy)。
+- 故障排除：[渠道故障排除](/channels/troubleshooting)。
+- 模型提供商单独记录；参见[模型提供商](/providers/models)。