farcasclaudiu/openclaw
1
0
Fork 0
mirror of https://github.com/farcasclaudiu/openclaw.git synced 2026-06-28 17:01:53 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs: update zh-CN translations and pipeline

Browse Source 
What:
- update zh-CN glossary, TM, and translator prompt
- regenerate zh-CN docs and apply targeted fixes
- add zh-CN AGENTS pipeline guidance

Why:
- address terminology/spacing feedback from #6995

Tests:
- pnpm build && pnpm check && pnpm test
This commit is contained in:
Josh Palmer
2026-02-03 13:23:00 -08:00
parent 9f03791aa9
commit a3ec2d0734
228 changed files with 10651 additions and 10475 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh-CN/channels/bluebubbles.md
+69 -69
View File
@@ -3,36 +3,36 @@ read_when:
- 设置 BlueBubbles 渠道
- 排查 webhook 配对问题
- 在 macOS 上配置 iMessage
summary: 通过 BlueBubbles macOS 服务器集成 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。
summary: 通过 BlueBubbles macOS 服务器使用 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。
title: BlueBubbles
x-i18n:
generated_at: "2026-02-01T19:41:18Z"
generated_at: "2026-02-03T10:04:52Z"
model: claude-opus-4-5
provider: pi
source_hash: ac9a9d71f3bbc661da6cb2897ea32d290bbd16b35925250601cfff53bc85de8c
source_hash: 3aae277a8bec479800a7f6268bfbca912c65a4aadc6e513694057fb873597b69
source_path: channels/bluebubbles.md
workflow: 14
workflow: 15
---
# BlueBubbles（macOS REST）
状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。**推荐用于 iMessage 集成**，因为相比旧版 imsg 渠道，其 API 更丰富且更易于设置。
状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其更丰富的 API 和更简便的设置，**推荐用于 iMessage 集成**，优于旧版 imsg 渠道。
## 概述
- 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。
- 推荐/已测试：macOS Sequoia (15)。macOS Tahoe (26) 可用；编辑功能目前在 Tahoe 上不可用，群组图标更新可能报告成功但不会同步。
- 推荐/已测试版本：macOS Sequoia (15)。macOS Tahoe (26) 可用；但在 Tahoe 上编辑功能目前不可用，群组图标更新可能显示成功但实际未同步。
- OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
- 收到的消息通过 webhooks 到达；发出的回复、输入指示器、已读回执和 tapback 回应均为 REST 调用。
- 附件和贴纸作为入站媒体被接收（在可能的情况下呈现给智能体）。
- 配对/允许列表与其他渠道的工作方式相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
- 回应作为系统事件呈现，与 Slack/Telegram 相同，因此智能体可以在回复前"提及"它们。
- 高级功能：编辑、撤回、回复线程、消息特效、群组管理。
- 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。
- 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。
- 配对/白名单的工作方式与其他渠道相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
- 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。
- 高级功能：编辑、撤回、回复线程、消息效果、群组管理。
## 快速开始
1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 的说明操作）。
2. 在 BlueBubbles 配置中，启用 Web API 并设置密码。
2. 在 BlueBubbles 配置中，启用 web API 并设置密码。
3. 运行 `openclaw onboard` 并选择 BlueBubbles，或手动配置：
```json5
{
@@ -46,8 +46,8 @@ x-i18n:
},
}
```
4. 将 BlueBubbles webhooks 指向你的 Gateway网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
5. 启动 Gateway网关；它将注册 webhook 处理器并开始配对。
4. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
5. 启动 Gateway 网关；它将注册 webhook 处理程序并开始配对。
## 新手引导
@@ -62,8 +62,8 @@ openclaw onboard
- **服务器 URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`）
- **密码**（必填）：来自 BlueBubbles 服务器设置的 API 密码
- **Webhook 路径**（可选）：默认为 `/bluebubbles-webhook`
- **私聊策略**：配对、允许列表、开放或禁用
- **允许列表**：电话号码、邮箱或聊天目标
- **私信策略**：配对、白名单、开放或禁用
- **白名单**：电话号码、电子邮件或聊天目标
你也可以通过 CLI 添加 BlueBubbles：
@@ -71,13 +71,13 @@ openclaw onboard
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
```
## 访问控制（私聊 + 群组）
## 访问控制（私信 + 群组）
私聊：
私信：
- 默认：`channels.bluebubbles.dmPolicy = "pairing"`。
- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
- 批准方式：
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
@@ -92,10 +92,10 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
- 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。
- 当群组启用 `requireMention` 时，智能体仅在被提及时回复。
- 当群组启用 `requireMention` 时，智能体仅在被提及时响应。
- 来自授权发送者的控制命令会绕过提及门控。
按群组配置：
单群组配置：
```json5
{
@@ -104,8 +104,8 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // 所有群组的默认值
"iMessage;-;chat123": { requireMention: false }, // 针对特定群组的覆盖
"*": { requireMention: true }, // 所有群组的默认设置
"iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖设置
},
},
},
@@ -115,12 +115,12 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
### 命令门控
- 控制命令（例如 `/config`、`/model`）需要授权。
- 使用 `allowFrom` 和 `groupAllowFrom` 来确定命令授权。
- 授权发送者即使在群组中未提及也可以运行控制命令。
- 使用 `allowFrom` 和 `groupAllowFrom` 确定命令授权。
- 授权发送者即使在群组中未被提及也可以运行控制命令。
## 输入状态 + 已读回执
- **输入指示器**：在生成回复前和生成过程中自动发送。
- **输入指示器**：在响应生成前和生成期间自动发送。
- **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。
- **输入指示器**：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入状态（通过 DELETE 手动停止不可靠）。
@@ -136,21 +136,21 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
## 高级操作
在配置中启用后，BlueBubbles 支持高级消息操作：
BlueBubbles 在配置中启用时支持高级消息操作：
```json5
{
channels: {
bluebubbles: {
actions: {
reactions: true, // tapback 回应（默认：true）
edit: true, // 编辑已发送消息（macOS 13+，macOS 26 Tahoe 上不可用）
reactions: true, // tapback（默认：true）
edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上不可用）
unsend: true, // 撤回消息（macOS 13+）
reply: true, // 按消息 GUID 回复线程
sendWithEffect: true, // 消息特效（slam、loud 等）
reply: true, // 通过消息 GUID 进行回复线程
sendWithEffect: true, // 消息效果（slam、loud 等）
renameGroup: true, // 重命名群聊
setGroupIcon: true, // 设置群聊图标/头像（macOS 26 Tahoe 上不稳定）
addParticipant: true, // 向群组添加参与者
setGroupIcon: true, // 设置群聊图标/照片（在 macOS 26 Tahoe 上不稳定）
addParticipant: true, // 将参与者添加到群组
removeParticipant: true, // 从群组移除参与者
leaveGroup: true, // 离开群聊
sendAttachment: true, // 发送附件/媒体
@@ -166,40 +166,40 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
- **edit**：编辑已发送的消息（`messageId`、`text`）
- **unsend**：撤回消息（`messageId`）
- **reply**：回复特定消息（`messageId`、`text`、`to`）
- **sendWithEffect**：使用 iMessage 特效发送（`text`、`to`、`effectId`）
- **sendWithEffect**：带 iMessage 效果发送（`text`、`to`、`effectId`）
- **renameGroup**：重命名群聊（`chatGuid`、`displayName`）
- **setGroupIcon**：设置群聊图标/头像（`chatGuid`、`media`）——在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标不会同步）。
- **addParticipant**：向群组添加成员（`chatGuid`、`address`）
- **removeParticipant**：从群组移除成员（`chatGuid`、`address`）
- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）— 在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标未同步）。
- **addParticipant**：将某人添加到群组（`chatGuid`、`address`）
- **removeParticipant**：将某人从群组移除（`chatGuid`、`address`）
- **leaveGroup**：离开群聊（`chatGuid`）
- **sendAttachment**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`）
- 语音备忘录：设置 `asVoice: true` 并使用 **MP3** 或 **CAF** 音频以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
- 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
### 消息 ID（短格式与完整格式）
### 消息 ID（短格式 vs 完整格式）
OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。
OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
- `MessageSid` / `ReplyToId` 可以是短 ID。
- `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。
- 短 ID 存储在内存中；它们可能在重启或缓存清除后过期。
- 操作接受短格式或完整格式的 `messageId`，但如果短 ID 不再可用则会报错。
- 操作接受短或完整的 `messageId`，但如果短 ID 不再可用将会报错。
对于持久化自动化和存储，请使用完整 ID：
- 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}`
- 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull`
模板变量请参阅[配置](/gateway/configuration)。
参见[配置](/gateway/configuration)了解模板变量。
## 分块流式传输
控制回复是作为单条消息发送还是分块流式传输：
控制响应是作为单条消息发送还是分块流式传输：
```json5
{
channels: {
bluebubbles: {
blockStreaming: true, // 启用分块流式传输（默认行为）
blockStreaming: true, // 启用分块流式传输（默认关闭）
},
},
}
@@ -209,7 +209,7 @@ OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。
- 入站附件会被下载并存储在媒体缓存中。
- 媒体上限通过 `channels.bluebubbles.mediaMaxMb` 设置（默认：8 MB）。
- 出站文本按 `channels.bluebubbles.textChunkLimit` 进行分块（默认：4000 字符）。
- 出站文本按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 字符）。
## 配置参考
@@ -222,17 +222,17 @@ OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。
- `channels.bluebubbles.password`：API 密码。
- `channels.bluebubbles.webhookPath`：Webhook 端点路径（默认：`/bluebubbles-webhook`）。
- `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。
- `channels.bluebubbles.allowFrom`：私聊允许列表（句柄、邮箱、E.164 号码、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.allowFrom`：私信白名单（句柄、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。
- `channels.bluebubbles.groupAllowFrom`：群组发送者允许列表。
- `channels.bluebubbles.groups`：按群组配置（`requireMention` 等）。
- `channels.bluebubbles.groupAllowFrom`：群组发送者白名单。
- `channels.bluebubbles.groups`：单群组配置（`requireMention` 等）。
- `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`true`）。
- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符数，默认：4000）。
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在空行（段落边界）处分割，然后再进行长度分块。
- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB，默认：8）。
- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。
- `channels.bluebubbles.dmHistoryLimit`：私聊历史限制。
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复必需）。
- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符）（默认：4000）。
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在长度分块前先按空行（段落边界）分割。
- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB）（默认：8）。
- `channels.bluebubbles.historyLimit`：上下文的最大群组消息数（0 表示禁用）。
- `channels.bluebubbles.dmHistoryLimit`：私信历史限制。
- `channels.bluebubbles.actions`：启用/禁用特定操作。
- `channels.bluebubbles.accounts`：多账户配置。
@@ -241,31 +241,31 @@ OpenClaw 可能会呈现*短*消息 ID（例如 `1`、`2`）以节省 token。
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
- `messages.responsePrefix`。
## 寻址/投递目标
## 地址 / 投递目标
推荐使用 `chat_guid` 以实现稳定路由：
优先使用 `chat_guid` 以获得稳定的路由：
- `chat_guid:iMessage;-;+15555550123`（群组推荐使用）
- `chat_guid:iMessage;-;+15555550123`（群组推荐）
- `chat_id:123`
- `chat_identifier:...`
- 直接句柄：`+15555550123`、`user@example.com`
- 如果直接句柄没有现有的私聊会话，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。
- 如果直接句柄没有现有的私信聊天，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。
## 安全
## 安全性
- Webhook 请求通过将 `guid`/`password` 查询参数或请求头与 `channels.bluebubbles.password` 比较来进行认证。来自 `localhost` 的请求也会被接受。
- 请保密 API 密码和 webhook 端点（将其视为凭证）。
- localhost 信任意味着同主机的反向代理可能会无意间绕过密码。如果你为 Gateway网关设置了代理，请在代理层要求认证并配置 `gateway.trustedProxies`。参见 [Gateway网关安全](/gateway/security#reverse-proxy-configuration)。
- 如果将 BlueBubbles 服务器暴露到局域网外部，请启用 HTTPS + 防火墙规则。
- Webhook 请求通过比较 `guid`/`password` 查询参数或头部与 `channels.bluebubbles.password` 进行身份验证。来自 `localhost` 的请求也会被接受。
- 保持 API 密码和 webhook 端点的机密性（将它们视为凭证）。
- localhost 信任意味着同主机的反向代理可能无意中绕过密码验证。如果你使用代理 Gateway 网关，请在代理处要求身份验证并配置 `gateway.trustedProxies`。参见 [Gateway 网关安全性](/gateway/security#reverse-proxy-configuration)。
- 如果将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。
## 故障排除
- 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。
- 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway 网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。
- 配对码在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
- 回应功能需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确保服务器版本已暴露该接口。
- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；确保服务器版本支持它。
- 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前不可用。
- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功但新图标不会同步。
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果编辑功能在 macOS 26（Tahoe）上仍然显示，请手动通过 `channels.bluebubbles.actions.edit=false` 禁用。
- 在 macOS 26（Tahoe）上群组图标更新可能不稳定：API 可能返回成功但新图标未同步。
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。
- 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。
通用渠道工作流参考请参阅[渠道](/channels)和[插件](/plugins)指南。
有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/plugins)指南。
docs/zh-CN/channels/discord.md
+158 -153
View File
@@ -1,32 +1,32 @@
---
read_when:
- 开发 Discord 渠道功能
- 开发 Discord 渠道功能时
summary: Discord 机器人支持状态、功能和配置
title: Discord
x-i18n:
generated_at: "2026-02-01T19:19:25Z"
generated_at: "2026-02-03T07:45:45Z"
model: claude-opus-4-5
provider: pi
source_hash: 44e44e855481a81557d9c205bacaa82efef528f8dba59a2c39c26aeb4f420c62
source_hash: 2f0083b55648f9158668b80d078353421e7dc310135fdc43f2d280b242bf8459
source_path: channels/discord.md
workflow: 14
workflow: 15
---
# Discord（Bot API）
状态：已可用于通过官方 Discord 机器人网关进行私信和服务器文字频道通信。
状态：已支持通过官方 Discord 机器人网关进行私信和服务器文字频道通信。
## 快速设置（新手）
1. 创建一个 Discord 机器人并复制机器人 token。
2. 在 Discord 应用设置中，启用 **Message Content Intent**（如果你计划使用允许列表或名称查找，还需启用 **Server Members Intent**）。
3. 为 OpenClaw 设置 token：
1. 创建 Discord 机器人并复制机器人令牌。
2. 在 Discord 应用设置中启用 **Message Content Intent**（如果你计划使用允许列表或名称查找，还需启用 **Server Members Intent**）。
3. 为 OpenClaw 设置令牌：
- 环境变量：`DISCORD_BOT_TOKEN=...`
- 或配置：`channels.discord.token: "..."`。
- 如果两者都设置了，配置优先（环境变量回退仅用于默认账户）。
4. 邀请机器人到你的服务器并赋予消息权限（如果只想用私信可以创建一个私人服务器）。
5. 启动 Gateway网关。
6. 私信访问默认需要配对；首次联系时批准配对码即可。
- 如果两者都设置，配置优先（环境变量回退仅适用于默认账户）。
4. 使用消息权限邀请机器人到你的服务器（如果你只想使用私信，可以创建一个私人服务器）。
5. 启动 Gateway 网关。
6. 私信访问默认采用配对模式；首次联系时需批准配对码。
最小配置：
@@ -44,42 +44,42 @@ x-i18n:
## 目标
- 通过 Discord 私信或服务器频道与 OpenClaw 对话。
- 私聊合并到智能体的主会话（默认 `agent:main:main`）；服务器频道作为 `agent:<agentId>:discord:channel:<channelId>` 保持隔离（显示名称使用 `discord:<guildSlug>#<channelSlug>`）。
- 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，可选通过 `channels.discord.dm.groupChannels` 限制。
- 保持路由确定性：回复始终发回消息到达的渠道。
- 直接聊天会合并到智能体的主会话（默认 `agent:main:main`）；服务器频道保持隔离为 `agent:<agentId>:discord:channel:<channelId>`（显示名称使用 `discord:<guildSlug>#<channelSlug>`）。
- 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，并可选择通过 `channels.discord.dm.groupChannels` 进行限制。
- 保持路由确定性：回复始终返回到消息来源的渠道。
## 工作原理
1. 创建 Discord 应用 → Bot，启用所需的 intent（私信 + 服务器消息 + 消息内容），获取机器人 token。
2. 邀请机器人到你的服务器，赋予在你需要使用的地方读取/发送消息所需的权限。
1. 创建 Discord 应用程序 → Bot，启用你需要的意图（私信 + 服务器消息 + 消息内容），并获取机器人令牌。
2. 使用所需权限邀请机器人到你的服务器，以便在你想使用的地方读取/发送消息。
3. 使用 `channels.discord.token` 配置 OpenClaw（或使用 `DISCORD_BOT_TOKEN` 作为回退）。
4. 运行 Gateway网关；当 token 可用（配置优先，环境变量回退）且 `channels.discord.enabled` 不为 `false` 时，它会自动启动 Discord 渠道。
- 如果你偏好使用环境变量，设置 `DISCORD_BOT_TOKEN`（配置块是可选的）。
5. 私聊：投递时使用 `user:<id>`（或 `<@id>` 提及）；所有回合都进入共享的 `main` 会话。裸数字 ID 具有歧义性，会被拒绝。
6. 服务器频道：投递时使用 `channel:<channelId>`。默认需要提及，可按服务器或按频道设置。
7. 私聊：默认通过 `channels.discord.dm.policy`（默认：`"pairing"`）进行安全保护。未知发送者会收到配对码（1 小时后过期）；通过 `openclaw pairing approve discord <code>` 批准。
4. 运行 Gateway 网关；当令牌可用（配置优先，环境变量回退）且 `channels.discord.enabled` 不为 `false` 时，它会自动启动 Discord 渠道。
- 如果你更喜欢使用环境变量，设置 `DISCORD_BOT_TOKEN`（配置块是可选的）。
5. 直接聊天：发送时使用 `user:<id>`（或 `<@id>` 提及）；所有对话都进入共享的 `main` 会话。纯数字 ID 是模糊的，会被拒绝。
6. 服务器频道：发送时使用 `channel:<channelId>`。默认需要提及，可以按服务器或按频道设置。
7. 直接聊天：默认通过 `channels.discord.dm.policy` 进行安全保护（默认：`"pairing"`）。未知发送者会收到配对码（1 小时后过期）；通过 `openclaw pairing approve discord <code>` 批准。
- 要保持旧的"对任何人开放"行为：设置 `channels.discord.dm.policy="open"` 和 `channels.discord.dm.allowFrom=["*"]`。
- 要硬性限制允许列表：设置 `channels.discord.dm.policy="allowlist"` 并在 `channels.discord.dm.allowFrom` 中列出发送者。
- 要使用硬编码允许列表：设置 `channels.discord.dm.policy="allowlist"` 并在 `channels.discord.dm.allowFrom` 中列出发送者。
- 要忽略所有私信：设置 `channels.discord.dm.enabled=false` 或 `channels.discord.dm.policy="disabled"`。
8. 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，可选通过 `channels.discord.dm.groupChannels` 限制。
9. 可选的服务器规则：设置 `channels.discord.guilds`，以服务器 ID（推荐）或 slug 为键，包含按频道的规则。
10. 可选的原生命令：`commands.native` 默认为 `"auto"`（Discord/Telegram 开启，Slack 关闭）。通过 `channels.discord.commands.native: true|false|"auto"` 覆盖；`false` 会清除之前注册的命令。文本命令由 `commands.text` 控制，必须作为独立的 `/...` 消息发送。使用 `commands.useAccessGroups: false` 可绕过命令的访问组检查。
8. 群组私信默认被忽略；通过 `channels.discord.dm.groupEnabled` 启用，并可选择通过 `channels.discord.dm.groupChannels` 进行限制。
9. 可选服务器规则：设置 `channels.discord.guilds`，以服务器 ID（首选）或 slug 为键，并包含每个频道的规则。
10. 可选原生命令：`commands.native` 默认为 `"auto"`（Discord/Telegram 开启，Slack 关闭）。使用 `channels.discord.commands.native: true|false|"auto"` 覆盖；`false` 会清除之前注册的命令。文本命令由 `commands.text` 控制，必须作为独立的 `/...` 消息发送。使用 `commands.useAccessGroups: false` 可跳过命令的访问组检查。
- 完整命令列表 + 配置：[斜杠命令](/tools/slash-commands)
11. 可选的服务器上下文历史：设置 `channels.discord.historyLimit`（默认 20，回退到 `messages.groupChat.historyLimit`）以在回复提及时包含最近 N 条服务器消息作为上下文。设置 `0` 可禁用。
12. 回应：智能体可以通过 `discord` 工具触发回应（由 `channels.discord.actions.*` 控制）。
- 回应移除语义：参见 [/tools/reactions](/tools/reactions)。
- `discord` 工具仅在当前渠道为 Discord 时暴露。
13. 原生命令使用隔离的会话键（`agent:<agentId>:discord:slash:<userId>`）而非共享的 `main` 会话。
11. 可选服务器上下文历史：设置 `channels.discord.historyLimit`（默认 20，回退到 `messages.groupChat.historyLimit`）以在回复提及时包含最近 N 条服务器消息作为上下文。设置 `0` 禁用。
12. 表情反应：智能体可以通过 `discord` 工具触发表情反应（受 `channels.discord.actions.*` 控制）。
- 表情反应移除语义：参见 [/tools/reactions](/tools/reactions)。
- `discord` 工具仅在当前渠道是 Discord 时暴露。
13. 原生命令使用隔离的会话键（`agent:<agentId>:discord:slash:<userId>`）而不是共享的 `main` 会话。
注意：名称 → ID 解析使用服务器成员搜索，需要 Server Members Intent；如果机器人无法搜索成员，请使用 ID 或 `<@id>` 提及。
注意：Slug 为小写且空格替换为 `-`。频道名称的 slug 不包含前导 `#`。
注意：服务器上下文 `[from:]` 行包含 `author.tag` + `id`，方便进行可直接 ping 的回复。
注意：Slug 为小写，空格替换为 `-`。频道名称的 slug 不包含前导 `#`。
注意：服务器上下文 `[from:]` 行包含 `author.tag` + `id`，便于进行可提及的回复。
## 配置写入
默认情况下，Discord 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。
默认情况下，允许 Discord 写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。
通过以下方式禁用：
禁用方式：
```json5
{
@@ -91,32 +91,32 @@ x-i18n:
这是在服务器（guild）频道（如 `#help`）中运行 OpenClaw 的"Discord 开发者门户"设置。
### 1) 创建 Discord 应用 + 机器人用户
### 1）创建 Discord 应用 + 机器人用户
1. Discord 开发者门户 → **Applications** → **New Application**
2. 在你的应用中：
- **Bot** → **Add Bot**
- 复制 **Bot Token**（这就是你放入 `DISCORD_BOT_TOKEN` 的值）
- 复制 **Bot Token**（这是你放入 `DISCORD_BOT_TOKEN` 的内容）
### 2) 启用 OpenClaw 所需的网关 intent
### 2）启用 OpenClaw 需要的网关意图
Discord 会阻止"特权 intent"，除非你明确启用。
Discord 会阻止"特权意图"，除非你明确启用它们。
在 **Bot** → **Privileged Gateway Intents** 中，启用：
在 **Bot** → **Privileged Gateway Intents** 中启用：
- **Message Content Intent**（在大多数服务器中读取消息文本所必需；没有它你会看到"Used disallowed intents"或机器人会连接但不响应消息）
- **Server Members Intent**（推荐；某些成员/用户查找和服务器中的允许列表匹配所必需）
- **Server Members Intent**（推荐；服务器中的某些成员/用户查找和允许列表匹配需要）
通常你**不**需要 **Presence Intent**。
你通常**不需要** **Presence Intent**。
### 3) 生成邀请 URL（OAuth2 URL 生成器）
### 3）生成邀请 URL（OAuth2 URL Generator）
在你的应用中：**OAuth2** → **URL Generator**
**Scopes**
- ✅ `bot`
- ✅ `applications.commands`（原生命令所必需）
- ✅ `applications.commands`（原生命令所需）
**Bot Permissions**（最小基线）
@@ -126,27 +126,27 @@ Discord 会阻止"特权 intent"，除非你明确启用。
- ✅ Embed Links
- ✅ Attach Files
- ✅ Add Reactions（可选但推荐）
- ✅ Use External Emojis / Stickers（可选；仅在你需要时）
- ✅ Use External Emojis / Stickers（可选；仅当你需要时）
除非你在调试且完全信任机器人，否则避免使用 **Administrator**。
除非你在调试并完全信任机器人，否则避免使用 **Administrator**。
复制生成的 URL，打开它，选择你的服务器，安装机器人。
复制生成的 URL，打开它，选择你的服务器，然后安装机器人。
### 4) 获取 ID（服务器/用户/频道）
### 4）获取 ID（服务器/用户/频道）
Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。
Discord 到处使用数字 ID；OpenClaw 配置优先使用 ID。
1. Discord（桌面/网页）→ **用户设置** → **高级** → 启用 **开发者模式**
2. 右键点击：
- 服务器名称 → **复制服务器 ID**（guild id）
- 服务器名称 → **复制服务器 ID**（服务器 ID）
- 频道（例如 `#help`）→ **复制频道 ID**
- 你的用户 → **复制用户 ID**
### 5) 配置 OpenClaw
### 5）配置 OpenClaw
#### Token
#### 令牌
通过环境变量设置机器人 token（推荐用于服务器）：
通过环境变量设置机器人令牌（服务器上推荐）：
- `DISCORD_BOT_TOKEN=...`
@@ -163,7 +163,7 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。
}
```
多账户支持：使用 `channels.discord.accounts`，每个账户配置独立的 token 和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。
多账户支持：使用 `channels.discord.accounts`，每个账户有自己的令牌和可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解通用模式。
#### 允许列表 + 频道路由
@@ -195,52 +195,57 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。
}
```
注意事项：
注意：
- `requireMention: true` 表示机器人仅在被提及时回复（推荐用于共享频道）。
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）对服务器消息也算作提及。
- `requireMention: true` 意味着机器人只在被提及时回复（推荐用于共享频道）。
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）对于服务器消息也算作提及。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
- 如果存在 `channels`，任何未列出的频道默认被拒绝。
- 使用 `"*"` 频道条目来应用所有频道的默认值；明确的频道条目会覆盖通配符。
- 帖子继承父频道配置（允许列表、`requireMention`、Skills、提示等），除非你明确添加帖子频道 ID。
- 机器人发送的消息默认被忽略；设置 `channels.discord.allowBots=true` 可允许它们（自己的消息仍然被过滤）。
- 警告：如果你允许回复其他机器人（`channels.discord.allowBots=true`），请使用 `requireMention`、`channels.discord.guilds.*.channels.<id>.users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。
- 使用 `"*"` 频道条目在所有频道应用默认值；显式频道条目覆盖通配符。
- 话题继承父频道配置（允许列表、`requireMention`、Skills、提示词等），除非你显式添加话题频道 ID。
- 机器人发送的消息默认被忽略；设置 `channels.discord.allowBots=true` 允许它们（自己的消息仍被过滤）。
- 警告：如果你允许回复其他机器人（`channels.discord.allowBots=true`），请使用 `requireMention`、`channels.discord.guilds.*.channels.<id>.users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护措施来防止机器人之间的回复循环。
### 6) 验证是否正常工作
### 6）验证是否工作
1. 启动 Gateway网关。
2. 在你的服务器频道中，发送：`@Krill hello`（或你的机器人名称）。
3. 如果没有响应：查看下方**故障排除**。
1. 启动 Gateway 网关。
2. 在你的服务器频道中发送：`@Krill hello`（或你的机器人名称）。
3. 如果没有反应：查看下面的**故障排除**。
### 故障排除
- 首先：运行 `openclaw doctor` 和 `openclaw channels status --probe`（可操作的警告 + 快速审计）。
- **"Used disallowed intents"**：在开发者门户中启用 **Message Content Intent**（以及可能的 **Server Members Intent**），然后重启 Gateway网关。
- **机器人连接但在服务器频道中从不回复**：
- **"Used disallowed intents"**：在开发者门户中启用 **Message Content Intent**（可能还需要 **Server Members Intent**），然后重启 Gateway 网关。
- **机器人连接但从不在服务器频道回复**：
- 缺少 **Message Content Intent**，或
- 机器人缺少频道权限（View/Send/Read History），或
- 你的配置要求提及但你没有提及它，或
- 你的配置需要提及但你没有提及它，或
- 你的服务器/频道允许列表拒绝了该频道/用户。
- **`requireMention: false` 但仍然没有回复**：
- `channels.discord.groupPolicy` 默认为 **allowlist**；将其设置为 `"open"` 或在 `channels.discord.guilds` 下添加服务器条目（可选在 `channels.discord.guilds.<id>.channels` 下列出频道以进行限制）。
- 如果你只设置了 `DISCORD_BOT_TOKEN` 且从未创建 `channels.discord` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.discord.groupPolicy`、`channels.defaults.groupPolicy` 或服务器/频道允许列表来锁定它。
- `channels.discord.groupPolicy` 默认为 **allowlist**；将其设置为 `"open"` 或在 `channels.discord.guilds` 下添加服务器条目（可选择在 `channels.discord.guilds.<id>.channels` 下列出频道以进行限制）。
- 如果你只设置了 `DISCORD_BOT_TOKEN` 而从未创建 `channels.discord` 部分，运行时会将 `groupPolicy` 默认为 `open`。添加 `channels.discord.groupPolicy`、`channels.defaults.groupPolicy` 或服务器/频道允许列表来锁定它。
- `requireMention` 必须位于 `channels.discord.guilds`（或特定频道）下。顶层的 `channels.discord.requireMention` 会被忽略。
- **权限审计**（`channels status --probe`）仅检查数字频道 ID。如果你使用 slug/名称作为 `channels.discord.guilds.*.channels` 的键，审计无法验证权限。
- **私信不工作**：`channels.discord.dm.enabled=false`、`channels.discord.dm.policy="disabled"`，或你尚未被批准（`channels.discord.dm.policy="pairing"`）。
- **权限审计**（`channels status --probe`）只检查数字频道 ID。如果你使用 slug/名称作为 `channels.discord.guilds.*.channels` 键，审计无法验证权限。
- **私信不工作**：`channels.discord.dm.enabled=false`、`channels.discord.dm.policy="disabled"`，或者你尚未被批准（`channels.discord.dm.policy="pairing"`）。
- **Discord 中的执行审批**：Discord 支持私信中执行审批的**按钮 UI**（允许一次 / 始终允许 / 拒绝）。`/approve <id> ...` 仅用于转发的审批，不会解析 Discord 的按钮提示。如果你看到 `❌ Failed to submit approval: Error: unknown approval id` 或 UI 从未出现，请检查：
- 你的配置中有 `channels.discord.execApprovals.enabled: true`。
- 你的 Discord 用户 ID 在 `channels.discord.execApprovals.approvers` 中列出（UI 仅发送给审批者）。
- 使用私信提示中的按钮（**Allow once**、**Always allow**、**Deny**）。
- 参见[执行审批](/tools/exec-approvals)和[斜杠命令](/tools/slash-commands)了解更广泛的审批和命令流程。
## 功能与限制
## 功能和限制
- 私信和服务器文字频道（帖子被视为独立频道；不支持语音）。
- 输入指示尽力发送；消息分块使用 `channels.discord.textChunkLimit`（默认 2000）并按行数分割较长回复（`channels.discord.maxLinesPerMessage`，默认 17）。
- 可选的换行分块：设置 `channels.discord.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。
- 支持文件上传，上限为配置的 `channels.discord.mediaMaxMb`（默认 8 MB）。
- 服务器回复默认需要提及门控，以避免嘈杂的机器人。
- 支持私信和服务器文字频道（话题被视为独立频道；不支持语音）。
- 打字指示器尽力发送；消息分块使用 `channels.discord.textChunkLimit`（默认 2000），并按行数分割长回复（`channels.discord.maxLinesPerMessage`，默认 17）。
- 可选换行分块：设置 `channels.discord.chunkMode="newline"` 以在空行（段落边界）处分割，然后再进行长度分块。
- 支持文件上传，最大 `channels.discord.mediaMaxMb`（默认 8 MB）。
- 默认服务器回复需要提及，以避免嘈杂的机器人。
- 当消息引用另一条消息时，会注入回复上下文（引用内容 + ID）。
- 原生回复线程**默认关闭**；通过 `channels.discord.replyToMode` 和回复标签启用。
- 原生回复线程**默认关闭**；使用 `channels.discord.replyToMode` 和回复标签启用。
## 重试策略
出站 Discord API 调用在速率限制（429）时使用 Discord 的 `retry_after`（如可用）进行重试，采用指数退避和抖动。通过 `channels.discord.retry` 配置。参见[重试策略](/concepts/retry)。
出站 Discord API 调用在速率限制（429）时使用 Discord `retry_after`（如果可用）进行重试，采用指数退避和抖动。通过 `channels.discord.retry` 配置。参见[重试策略](/concepts/retry)。
## 配置
@@ -311,57 +316,58 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。
}
```
确认回应由 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认回应。
确认表情反应通过 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认表情反应。
- `dm.enabled`：设置 `false` 可忽略所有私信（默认 `true`）。
- `dm.enabled`：设置 `false` 忽略所有私信（默认 `true`）。
- `dm.policy`：私信访问控制（推荐 `pairing`）。`"open"` 需要 `dm.allowFrom=["*"]`。
- `dm.allowFrom`：私信允许列表（用户 ID 或名称）。用于 `dm.policy="allowlist"` 和 `dm.policy="open"` 验证。向导接受用户名并在机器人可以搜索成员时将其解析为 ID。
- `dm.allowFrom`：私信允许列表（用户 ID 或名称）。用于 `dm.policy="allowlist"` 和 `dm.policy="open"` 验证。向导接受用户名，并在机器人可以搜索成员时将其解析为 ID。
- `dm.groupEnabled`：启用群组私信（默认 `false`）。
- `dm.groupChannels`：群组私信频道 ID 或 slug 的可选允许列表。
- `groupPolicy`：控制服务器频道处理方式（`open|disabled|allowlist`）；`allowlist` 需要频道允许列表。
- `guilds`：按服务器 ID（推荐）或 slug 为键的按服务器规则。
- `guilds."*"`：当没有明确条目时应用的默认按服务器设置。
- `groupPolicy`：控制服务器频道处理（`open|disabled|allowlist`）；`allowlist` 需要频道允许列表。
- `guilds`：按服务器规则，以服务器 ID（首选）或 slug 为键。
- `guilds."*"`：当没有显式条目时应用的默认每服务器设置。
- `guilds.<id>.slug`：用于显示名称的可选友好 slug。
- `guilds.<id>.users`：可选的按服务器用户允许列表（ID 或名称）。
- `guilds.<id>.tools`：可选的按服务器工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `guilds.<id>.toolsBySender`：可选的按发送者工具策略覆盖（服务器级别，在频道覆盖缺失时应用；支持 `"*"` 通配符）。
- `guilds.<id>.users`：可选的每服务器用户允许列表（ID 或名称）。
- `guilds.<id>.tools`：可选的每服务器工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `guilds.<id>.toolsBySender`：服务器级别的可选每发送者工具策略覆盖（在频道覆盖缺失时应用；支持 `"*"` 通配符）。
- `guilds.<id>.channels.<channel>.allow`：当 `groupPolicy="allowlist"` 时允许/拒绝频道。
- `guilds.<id>.channels.<channel>.requireMention`：频道的提及门控。
- `guilds.<id>.channels.<channel>.tools`：可选的按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `guilds.<id>.channels.<channel>.toolsBySender`：可选的频道内按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `guilds.<id>.channels.<channel>.users`：可选的按频道用户允许列表。
- `guilds.<id>.channels.<channel>.requireMention`：频道的提及限制。
- `guilds.<id>.channels.<channel>.tools`：可选的每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `guilds.<id>.channels.<channel>.toolsBySender`：频道内的可选每发送者工具策略覆盖（支持 `"*"` 通配符）。
- `guilds.<id>.channels.<channel>.users`：可选的每频道用户允许列表。
- `guilds.<id>.channels.<channel>.skills`：Skills 过滤器（省略 = 所有 Skills，空 = 无）。
- `guilds.<id>.channels.<channel>.systemPrompt`：频道的额外系统提示（与频道主题合并）。
- `guilds.<id>.channels.<channel>.enabled`：设置 `false` 可禁用频道。
- `guilds.<id>.channels.<channel>.systemPrompt`：频道的额外系统提示词（与频道主题组合）。
- `guilds.<id>.channels.<channel>.enabled`：设置 `false` 禁用频道。
- `guilds.<id>.channels`：频道规则（键为频道 slug 或 ID）。
- `guilds.<id>.requireMention`：按服务器的提及要求（可按频道覆盖）。
- `guilds.<id>.reactionNotifications`：回应系统事件模式（`off`、`own`、`all`、`allowlist`）。
- `textChunkLimit`：出站文本分块大小（字符）。默认：2000。
- `chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在按长度分块之前按空行（段落边界）分割。
- `guilds.<id>.requireMention`：每服务器提及要求（可按频道覆盖）。
- `guilds.<id>.reactionNotifications`：表情反应系统事件模式（`off`、`own`、`all`、`allowlist`）。
- `textChunkLimit`：出站文本块大小（字符）。默认：2000。
- `chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在空行（段落边界）处分割，然后再进行长度分块。
- `maxLinesPerMessage`：每条消息的软最大行数。默认：17。
- `mediaMaxMb`：限制保存到磁盘的入站媒体大小。
- `historyLimit`：回复提及时包含的最近服务器消息数作为上下文（默认 20；回退到 `messages.groupChat.historyLimit`；`0` 禁用）。
- `dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`dms["<user_id>"].historyLimit`。
- `historyLimit`：回复提及时作为上下文包含的最近服务器消息数量（默认 20；回退到 `messages.groupChat.historyLimit`；`0` 禁用）。
- `dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`dms["<user_id>"].historyLimit`。
- `retry`：出站 Discord API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。
- `pluralkit`：解析 PluralKit 代理消息，使系统成员显示为不同的发送者。
- `actions`：按操作的工具门控；省略则允许所有（设置 `false` 可禁用）。
- `reactions`（涵盖添加回应 + 读取回应）
- `actions`：每操作工具门控；省略允许所有（设置 `false` 禁用）。
- `reactions`（涵盖表情反应 + 读取表情反应）
- `stickers`、`emojiUploads`、`stickerUploads`、`polls`、`permissions`、`messages`、`threads`、`pins`、`search`
- `memberInfo`、`roleInfo`、`channelInfo`、`voiceStatus`、`events`
- `channels`（创建/编辑/删除频道 + 分类 + 权限）
- `channels`（创建/编辑/删除频道 + 类别 + 权限）
- `roles`（角色添加/移除，默认 `false`）
- `moderation`（超时/踢出/封禁，默认 `false`）
- `execApprovals`：Discord 专用执行审批私信（按钮 UI）。支持 `enabled`、`approvers`、`agentFilter`、`sessionFilter`。
回应通知使用 `guilds.<id>.reactionNotifications`：
表情反应通知使用 `guilds.<id>.reactionNotifications`：
- `off`：无回应事件。
- `own`：机器人自己消息上的回应（默认）。
- `all`：所有消息上的所有回应。
- `allowlist`：来自 `guilds.<id>.users` 的用户在所有消息上的回应（空列表则禁用）。
- `off`：无表情反应事件。
- `own`：机器人自己消息上的表情反应（默认）。
- `all`：所有消息上的所有表情反应。
- `allowlist`：来自 `guilds.<id>.users` 的用户在所有消息上的表情反应（空列表禁用）。
### PluralKit（PK）支持
启用 PK 查找，使代理消息解析为底层的系统 + 成员。启用后，OpenClaw 使用成员身份进行允许列表匹配，并将发送者标记为 `Member (PK:System)` 以避免意外的 Discord ping。
启用 PK 查找，以便代理消息解析到底层系统 + 成员。启用后，OpenClaw 使用成员身份进行允许列表匹配，并将发送者标记为 `Member (PK:System)` 以避免意外的 Discord 提及。
```json5
{
@@ -378,86 +384,85 @@ Discord 到处使用数字 ID；OpenClaw 配置推荐使用 ID。
允许列表注意事项（启用 PK 时）：
- 在 `dm.allowFrom`、`guilds.<id>.users` 或按频道的 `users` 中使用 `pk:<memberId>`。
- 成员显示名称也通过名称/slug 匹配。
- 查找使用**原始** Discord 消息 ID（代理前的消息），因此 PK API 仅在其 30 分钟窗口内解析它。
- 如果 PK 查找失败（例如没有 token 的私有系统），代理消息被视为机器人消息并被丢弃，除非设置 `channels.discord.allowBots=true`。
- 在 `dm.allowFrom`、`guilds.<id>.users` 或每频道 `users` 中使用 `pk:<memberId>`。
- 成员显示名称也按名称/slug 匹配。
- 查找使用**原始** Discord 消息 ID（代理前的消息），因此 PK API 只在其 30 分钟窗口内解析它。
- 如果 PK 查找失败（例如，没有令牌的私有系统），代理消息会被视为机器人消息并被丢弃，除非 `channels.discord.allowBots=true`。
### 工具操作默认值
| 操作组 | 默认值 | 说明 |
| -------------- | ------ | ------------------------------- |
| reactions | 启用 | 添加回应 + 列出回应 + emojiList |
| stickers | 启用 | 发送贴纸 |
| emojiUploads | 启用 | 上传表情 |
| stickerUploads | 启用 | 上传贴纸 |
| polls | 启用 | 创建投票 |
| permissions | 启用 | 频道权限快照 |
| messages | 启用 | 读取/发送/编辑/删除 |
| threads | 启用 | 创建/列出/回复 |
| pins | 启用 | 置顶/取消置顶/列出 |
| search | 启用 | 消息搜索（预览功能） |
| memberInfo | 启用 | 成员信息 |
| roleInfo | 启用 | 角色列表 |
| channelInfo | 启用 | 频道信息 + 列表 |
| channels | 启用 | 频道/分类管理 |
| voiceStatus | 启用 | 语音状态查询 |
| events | 启用 | 列出/创建计划事件 |
| roles | 禁用 | 角色添加/移除 |
| moderation | 禁用 | 超时/踢出/封禁 |
| 操作组 | 默认 | 说明 |
| -------------- | ---- | ----------------------------------- |
| reactions | 启用 | 表情反应 + 列出表情反应 + emojiList |
| stickers | 启用 | 发送贴纸 |
| emojiUploads | 启用 | 上传表情 |
| stickerUploads | 启用 | 上传贴纸 |
| polls | 启用 | 创建投票 |
| permissions | 启用 | 频道权限快照 |
| messages | 启用 | 读取/发送/编辑/删除 |
| threads | 启用 | 创建/列出/回复 |
| pins | 启用 | 置顶/取消置顶/列出 |
| search | 启用 | 消息搜索（预览功能） |
| memberInfo | 启用 | 成员信息 |
| roleInfo | 启用 | 角色列表 |
| channelInfo | 启用 | 频道信息 + 列表 |
| channels | 启用 | 频道/类别管理 |
| voiceStatus | 启用 | 语音状态查询 |
| events | 启用 | 列出/创建预定事件 |
| roles | 禁用 | 角色添加/移除 |
| moderation | 禁用 | 超时/踢出/封禁 |
- `replyToMode`：`off`（默认）、`first` 或 `all`。仅在模型输出包含回复标签时生效。
- `replyToMode`：`off`（默认）、`first` 或 `all`。仅在模型包含回复标签时适用。
## 回复标签
要请求线程回复，模型可以在输出中包含一个标签：
要请求线程回复，模型可以在其输出中包含一个标签：
- `[[reply_to_current]]` — 回复触发的 Discord 消息。
- `[[reply_to:<id>]]` — 回复上下文/历史中的特定消息 ID。
当前消息 ID 以 `[message_id: …]` 附加到提示中；历史条目已包含 ID。
- `[[reply_to:<id>]]` — 回复上下文/历史中的特定消息 ID。当前消息 ID 作为 `[message_id: …]` 附加到提示词；历史条目已包含 ID。
行为由 `channels.discord.replyToMode` 控制：
- `off`：忽略标签。
- `first`：仅第一个出站分块/附件作为回复。
- `all`：每个出站分块/附件都作为回复。
- `first`：只有第一个出站块/附件是回复。
- `all`：每个出站块/附件都是回复。
允许列表匹配注意事项：
- `allowFrom`/`users`/`groupChannels` 接受 ID、名称、标签或 `<@id>` 格式的提及。
- `allowFrom`/`users`/`groupChannels` 接受 ID、名称、标签或像 `<@id>` 这样的提及。
- 支持 `discord:`/`user:`（用户）和 `channel:`（群组私信）等前缀。
- 使用 `*` 允许任何发送者/频道。
- 当存在 `guilds.<id>.channels` 时，未列出的频道默认被拒绝。
- 当省略 `guilds.<id>.channels` 时，允许列表中服务器的所有频道都被允许。
- 要**不允许任何频道**，设置 `channels.discord.groupPolicy: "disabled"`（或保持空的允许列表）。
- 配置向导接受 `Guild/Channel` 名称（公共 + 私有）并在可能时将其解析为 ID。
- 要**不允许任何频道**，设置 `channels.discord.groupPolicy: "disabled"`（或保持空允许列表）。
- 配置向导接受 `Guild/Channel` 名称（公开 + 私有）并在可能时将其解析为 ID。
- 启动时，OpenClaw 将允许列表中的频道/用户名称解析为 ID（当机器人可以搜索成员时）并记录映射；未解析的条目保持原样。
原生命令注意事项：
- 注册的命令与 OpenClaw 的聊天命令一致。
- 原生命令遵循与私信/服务器消息相同的允许列表（`channels.discord.dm.allowFrom`、`channels.discord.guilds`、按频道规则）。
- 斜杠命令在 Discord UI 中可能对不在允许列表中的用户仍然可见；OpenClaw 在执行时强制执行允许列表并回复"未授权"。
- 注册的命令镜像 OpenClaw 的聊天命令。
- 原生命令遵循与私信/服务器消息相同的允许列表（`channels.discord.dm.allowFrom`、`channels.discord.guilds`、每频道规则）。
- 斜杠命令可能在 Discord UI 中对未在允许列表中的用户仍然可见；OpenClaw 在执行时强制执行允许列表并回复"未授权"。
## 工具操作
智能体可以调用 `discord` 执行以下操作：
智能体可以使用以下操作调用 `discord`：
- `react` / `reactions`（添加或列出回应）
- `react` / `reactions`（添加或列出表情反应）
- `sticker`、`poll`、`permissions`
- `readMessages`、`sendMessage`、`editMessage`、`deleteMessage`
- 读取/搜索/置顶工具的负载包含标准化的 `timestampMs`（UTC 纪元毫秒）和 `timestampUtc`，同时保留原始 Discord `timestamp`。
- 读取/搜索/置顶工具负载包含规范化的 `timestampMs`（UTC 纪元毫秒）和 `timestampUtc` 以及原始 Discord `timestamp`。
- `threadCreate`、`threadList`、`threadReply`
- `pinMessage`、`unpinMessage`、`listPins`
- `searchMessages`、`memberInfo`、`roleInfo`、`roleAdd`、`roleRemove`、`emojiList`
- `channelInfo`、`channelList`、`voiceStatus`、`eventList`、`eventCreate`
- `timeout`、`kick`、`ban`
Discord 消息 ID 在注入的上下文中呈现（`[discord message id: …]` 和历史行），方便智能体定位它们。
Discord 消息 ID 在注入的上下文中显示（`[discord message id: …]` 和历史行），以便智能体可以定位它们。
表情可以是 unicode（例如 `✅`）或自定义表情语法如 `<:party_blob:1234567890>`。
## 安全与运维
- 将机器人 token 视为密码；在受管主机上推荐使用 `DISCORD_BOT_TOKEN` 环境变量或锁定配置文件权限。
- 仅授予机器人所需的权限（通常是读取/发送消息）。
- 如果机器人卡住或被速率限制，在确认没有其他进程占用 Discord 会话后重启 Gateway网关（`openclaw gateway --force`）。
- 像对待密码一样对待机器人令牌；在受监督的主机上优先使用 `DISCORD_BOT_TOKEN` 环境变量，或锁定配置文件权限。
- 只授予机器人所需的权限（通常是读取/发送消息）。
- 如果机器人卡住或受到速率限制，在确认没有其他进程拥有 Discord 会话后重启 Gateway 网关（`openclaw gateway --force`）。
docs/zh-CN/channels/googlechat.md
+55 -55
View File
@@ -1,38 +1,38 @@
---
read_when:
- 开发 Google Chat 渠道功能
- 开发 Google Chat 渠道功能时
summary: Google Chat 应用支持状态、功能和配置
title: Google Chat
x-i18n:
generated_at: "2026-02-01T19:20:03Z"
generated_at: "2026-02-03T07:43:39Z"
model: claude-opus-4-5
provider: pi
source_hash: 3b2bb116cdd12614c3d5afddd0879e9deb05c3606e3a2385cbc07f23552b357e
source_path: channels/googlechat.md
workflow: 14
workflow: 15
---
# Google Chat（Chat API）
状态：已可通过 Google Chat API webhook（仅 HTTP）用于私信和空间。
状态：已支持通过 Google Chat API webhooks（仅 HTTP）使用私信和空间。
## 快速设置（新手）
1. 创建一个 Google Cloud 项目并启用 **Google Chat API**。
- 前往：[Google Chat API 凭据](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
- 如果尚未启用，请启用该 API。
2. 创建**服务账户**：
- 前往：[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**）。
- 有访问权限的主账号留空（点击 **Done**）。
3. 创建并下载 **JSON 密钥**：
- 在服务账户列表中，点击你刚创建的那个。
- 进入 **Keys** 标签页。
- 在服务账号列表中，点击刚刚创建的账号。
- 前往 **Keys** 标签页。
- 点击 **Add Key** > **Create new key**。
- 选择 **JSON** 并点击 **Create**。
4. 将下载的 JSON 文件存储在你的 Gateway网关主机上（例如 `~/.openclaw/googlechat-service-account.json`）。
5. 在 [Google Cloud Console Chat 配置](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建 Google Chat 应用：
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`）
@@ -40,49 +40,49 @@ x-i18n:
- 启用 **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。_
- 在 **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 &lt;Your Domain&gt;**。
- 在文本框中输入你的邮箱地址（例如 `user@example.com`）。
- 点击底部的 **Save**。
6. **启用应用状态**：
- 保存后，**刷新页面**。
- 查找 **App status** 部分（通常在保存后位于顶部或底部附近）。
- 找到 **App status** 部分（通常在保存后位于顶部或底部附近）。
- 将状态更改为 **Live - available to users**。
- 再次点击 **Save**。
7. 使用服务账户路径 + webhook audience 配置 OpenClaw：
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 请求。
8. 设置 webhook audience 类型和值（与你的 Chat 应用配置匹配）。
9. 启动 Gateway 网关。Google Chat 将向你的 webhook 路径发送 POST 请求。
## 添加到 Google Chat
Gateway网关运行且你的邮箱已添加到可见性列表后：
Gateway 网关运行后，且你的邮箱已添加到可见性列表中：
1. 前往 [Google Chat](https://chat.google.com/)。
2. 点击 **Direct Messages** 旁边的 **+**（加号）图标。
3. 在搜索栏中（通常用于添加人员的地方），输入你在 Google Cloud Console 中配置的 **App name**。
- **注意**：机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。
3. 在搜索栏（通常用于添加联系人的位置）中，输入你在 Google Cloud Console 中配置的 **App name**。
- **注意**：该机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。
4. 从结果中选择你的机器人。
5. 点击 **Add** 或 **Chat** 开始一对一对话。
6. 发送"Hello"来触发助手！
## 公共 URL（仅 Webhook）
## 公网 URL（仅 Webhook）
Google Chat webhook 需要公共 HTTPS 端点。为安全起见，**仅将 `/googlechat` 路径暴露**到互联网。将 OpenClaw 仪表板和其他敏感端点保持在私有网络上。
Google Chat webhooks 需要一个公网 HTTPS 端点。为了安全起见，**只将 `/googlechat` 路径暴露到互联网**。将 OpenClaw 仪表板和其他敏感端点保留在你的私有网络上。
### 方案 A：Tailscale Funnel（推荐）
使用 Tailscale Serve 用于私有仪表板，Funnel 用于公共 webhook 路径。这样 `/` 保持私有，仅暴露 `/googlechat`。
使用 Tailscale Serve 提供私有仪表板，使用 Funnel 提供公网 webhook 路径。这样可以保持 `/` 私有，同时只暴露 `/googlechat`。
1. **检查你的 Gateway网关绑定在哪个地址上：**
1. **检查你的 Gateway 网关绑定的地址：**
```bash
ss -tlnp | grep 18789
```
注意 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。
记下 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。
2. **仅将仪表板暴露给 tailnet（端口 8443）：**
@@ -104,8 +104,8 @@ Google Chat webhook 需要公共 HTTPS 端点。为安全起见，**仅将 `/goo
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
```
4. **为节点授权 Funnel 访问：**
如果出现提示，请访问输出中显示的授权 URL，在你的 tailnet 策略中为此节点启用 Funnel。
4. **授权节点访问 Funnel：**
如果出现提示，请访问输出中显示的授权 URL，以在你的 tailnet 策略中为此节点启用 Funnel。
5. **验证配置：**
```bash
@@ -113,19 +113,19 @@ Google Chat webhook 需要公共 HTTPS 端点。为安全起见，**仅将 `/goo
tailscale funnel status
```
你的公共 webhook URL 将是：
你的公网 webhook URL 将是：
`https://<node-name>.<tailnet>.ts.net/googlechat`
你的私有仪表板仅限 tailnet 访问：
`https://<node-name>.<tailnet>.ts.net:8443/`
在 Google Chat 应用配置中使用公共 URL（不带 `:8443`）。
在 Google Chat 应用配置中使用公网 URL（不带 `:8443`）。
> 注意：此配置在重启后持续有效。要在之后移除，运行 `tailscale funnel reset` 和 `tailscale serve reset`。
> 注意：此配置在重启后会保留。如需稍后移除，请运行 `tailscale funnel reset` 和 `tailscale serve reset`。
### 方案 B：反向代理（Caddy）
如果你使用像 Caddy 这样的反向代理，仅代理特定路径：
如果你使用像 Caddy 这样的反向代理，只代理特定路径：
```caddy
your-domain.com {
@@ -133,31 +133,31 @@ your-domain.com {
}
```
使用此配置，对 `your-domain.com/` 的任何请求将被忽略或返回 404，而 `your-domain.com/googlechat` 安全地路由到 OpenClaw。
使用此配置，任何发往 `your-domain.com/` 的请求将被忽略或返回 404，而 `your-domain.com/googlechat` 会安全地路由到 OpenClaw。
### 方案 C：Cloudflare Tunnel
配置你的隧道入口规则，仅路由 webhook 路径：
配置你的隧道入口规则，只路由 webhook 路径：
- **路径**：`/googlechat` -> `http://localhost:18789/googlechat`
- **默认规则**：HTTP 404（Not Found）
- **默认规则**：HTTP 404（未找到）
## 工作原理
1. Google Chat 向 Gateway网关发送 webhook POST 请求。每个请求包含一个 `Authorization: Bearer <token>` 头。
2. OpenClaw 根据配置的 `audienceType` + `audience` 验证 token：
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. 私信访问默认需要配对。未知发送者会收到配对码；通过以下方式批准：
4. 私信访问默认为配对模式。未知发送者会收到配对码；使用以下命令批准：
- `openclaw pairing approve googlechat <code>`
5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 `botUser`。
## 目标
## 目标标识符
使用以下标识符进行投递和允许列表：
使用这些标识符进行消息投递和允许列表：
- 私信：`users/<userId>` 或 `users/<email>`（接受邮箱地址）。
- 空间：`spaces/<spaceId>`。
@@ -173,7 +173,7 @@ your-domain.com {
audienceType: "app-url",
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
botUser: "users/1234567890", // 可选；辅助提及检测
botUser: "users/1234567890", // 可选；帮助提及检测
dm: {
policy: "pairing",
allowFrom: ["users/1234567890", "name@example.com"],
@@ -197,11 +197,11 @@ your-domain.com {
注意事项：
- 服务账户凭据也可以通过 `serviceAccount`（JSON 字符串）内联传递。
- 服务账号凭证也可以通过 `serviceAccount`（JSON 字符串）内联传递。
- 如果未设置 `webhookPath`，默认 webhook 路径为 `/googlechat`。
- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用回应功能。
- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用表情回应。
- `typingIndicator` 支持 `none`、`message`（默认）和 `reaction`（reaction 需要用户 OAuth）。
- 附件通过 Chat API 下载并存储在媒体管道中（大小由 `mediaMaxMb` 限制）。
- 附件通过 Chat API 下载并存储在媒体管道中（大小受 `mediaMaxMb` 限制）。
## 故障排除
@@ -213,15 +213,15 @@ your-domain.com {
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
```
这意味着 webhook 处理器未注册。常见原因：
这意味着 webhook 处理程序未注册。常见原因：
1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。通过以下方式验证：
1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。使用以下命令验证：
```bash
openclaw config get channels.googlechat
```
如果返回"Config path not found"，添加配置（参见[配置要点](#配置要点)）。
如果返回"Config path not found"，请添加配置（参见[配置要点](#配置要点)）。
2. **插件未启用**：检查插件状态：
@@ -229,9 +229,9 @@ status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Al
openclaw plugins list | grep googlechat
```
如果显示"disabled"，在配置中添加 `plugins.entries.googlechat.enabled: true`。
如果显示"disabled"，请在配置中添加 `plugins.entries.googlechat.enabled: true`。
3. **Gateway网关未重启**：添加配置后，重启 Gateway网关：
3. **Gateway 网关未重启**：添加配置后，重启 Gateway 网关：
```bash
openclaw gateway restart
```
@@ -245,13 +245,13 @@ openclaw channels status
### 其他问题
- 检查 `openclaw channels status --probe` 查看认证错误或缺失的 audience 配置。
- 如果没有消息到达，确认 Chat 应用的 webhook URL + 事件订阅。
- 如果提及门控阻止了回复，将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。
- 发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway网关。
- 检查 `openclaw channels status --probe` 以查看认证错误或缺少 audience 配置。
- 如果没有收到消息，请确认 Chat 应用的 webhook URL 和事件订阅。
- 如果提及门控阻止了回复，请将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。
- 在发送测试消息时使用 `openclaw logs --follow` 查看请求是否到达 Gateway 网关。
相关文档：
- [Gateway网关配置](/gateway/configuration)
- [Gateway 网关配置](/gateway/configuration)
- [安全](/gateway/security)
- [回应](/tools/reactions)
- [表情回应](/tools/reactions)
docs/zh-CN/channels/grammy.md
+17 -17
View File
@@ -1,38 +1,38 @@
---
read_when:
- 开发 Telegram 或 grammY 相关功能
summary: 通过 grammY 集成 Telegram Bot API 及设置说明
- 开发 Telegram 或 grammY 相关功能时
summary: 通过 grammY 集成 Telegram Bot API，附设置说明
title: grammY
x-i18n:
generated_at: "2026-02-01T19:20:16Z"
generated_at: "2026-02-03T10:03:55Z"
model: claude-opus-4-5
provider: pi
source_hash: ea7ef23e6d77801f4ef5fc56685ef4470f79f5aecab448d644a72cbab53521b7
source_path: channels/grammy.md
workflow: 14
workflow: 15
---
# grammY 集成（Telegram Bot API）
# 为什么选择 grammY
- TypeScript 优先的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理、速率限制器。
- 比手动编写 fetch + FormData 更简洁的媒体辅助工具；支持所有 Bot API 方法。
- 可扩展：通过自定义 fetch 支持代理，会话中间件（可选），类型安全的上下文。
- 以 TS 为核心的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理和速率限制器。
- 媒体处理辅助工具比手动编写 fetch + FormData 更简洁；支持所有 Bot API 方法。
- 可扩展：通过自定义 fetch 支持代理，可选的会话中间件，类型安全的上下文。
# 已交付的功能
# 我们发布的内容
- **单一客户端路径：** 基于 fetch 的实现已移除；grammY 现在是唯一的 Telegram 客户端（发送 + Gateway网关），默认启用 grammY throttler。
- **Gateway网关：** `monitorTelegramProvider` 构建一个 grammY `Bot`，接入提及/允许列表门控、通过 `getFile`/`download` 下载媒体，并通过 `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument` 投递回复。支持通过 `webhookCallback` 进行长轮询或 webhook。
- **单一客户端路径：** 移除了基于 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`（允许列表 + 提及默认值）、`channels.telegram.allowFrom`、`channels.telegram.groupAllowFrom`、`channels.telegram.groupPolicy`、`channels.telegram.mediaMaxMb`、`channels.telegram.linkPreview`、`channels.telegram.proxy`、`channels.telegram.webhookSecret`、`channels.telegram.webhookUrl`。
- **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 覆盖了私信 + 群组提及门控和出站发送；欢迎更多媒体/webhook 测试用例。
- **测试：** grammY mock 覆盖了私信 + 群组 mention 网关控制和出站发送；欢迎添加更多媒体/webhook 测试用例。
待讨论问题
待解决问题
- 如果遇到 Bot API 429 错误，考虑使用可选的 grammY 插件（throttler）。
- 添加更多结构化的媒体测试（贴纸、语音消息）。
- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway网关接入）。
- 添加更多结构化媒体测试（贴纸、语音消息）。
- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway 网关配置）。
docs/zh-CN/channels/imessage.md
+65 -65
View File
@@ -1,29 +1,29 @@
---
read_when:
- 设置 iMessage 支持
- 调试 iMessage 收发
summary: 通过 imsg（基于 stdio 的 JSON-RPC）实现 iMessage 支持、设置和 chat_id 路由
- 调试 iMessage 发送/接收
summary: 通过 imsg（基于 stdio 的 JSON-RPC）实现 iMessage 支持、设置及 chat_id 路由
title: iMessage
x-i18n:
generated_at: "2026-02-01T19:21:07Z"
generated_at: "2026-02-03T07:44:18Z"
model: claude-opus-4-5
provider: pi
source_hash: bc19756a42ead80a0845f18c4830c3f1f40948f69b2b016a4026598cfb8fef0d
source_path: channels/imessage.md
workflow: 14
workflow: 15
---
# iMessage（imsg）
# iMessage (imsg)
状态：外部 CLI 集成。Gateway网关启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。
状态：外部 CLI 集成。Gateway 网关生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。
## 快速设置（新手）
1. 确保此 Mac 上的"信息"已登录。
1. 确保在此 Mac 上已登录"信息"。
2. 安装 `imsg`：
- `brew install steipete/tap/imsg`
3. 配置 OpenClaw 的 `channels.imessage.cliPath` 和 `channels.imessage.dbPath`。
4. 启动 Gateway网关并批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。
4. 启动 Gateway 网关并批准所有 macOS 提示（自动化 + 完全磁盘访问权限）。
最小配置：
@@ -39,18 +39,18 @@ x-i18n:
}
```
## 它是什么
## 简介
- 在 macOS 上由 `imsg` 支持的 iMessage 渠道。
- 确定性路由：回复始终发回 iMessage。
- 基于 macOS 上 `imsg` 的 iMessage 渠道。
- 确定性路由：回复始终返回到 iMessage。
- 私信共享智能体的主会话；群组是隔离的（`agent:<agentId>:imessage:group:<chat_id>`）。
- 如果多参与者线程以 `is_group=false` 到达，你仍然可以通过 `chat_id` 使用 `channels.imessage.groups` 来隔离它（参见下方"类群组线程"）。
- 如果多参与者会话以 `is_group=false` 到达，你仍可使用 `channels.imessage.groups` 按 `chat_id` 隔离（参见下方"类群组会话"）。
## 配置写入
默认情况下，iMessage 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。
默认情况下，iMessage 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。
通过以下方式禁用：
禁用方式：
```json5
{
@@ -60,31 +60,31 @@ x-i18n:
## 要求
- macOS 且"信息"已登录。
- OpenClaw + `imsg` 需要完全磁盘访问权限（访问 Messages 数据库）。
- 已登录"信息"的 macOS。
- OpenClaw + `imsg` 的完全磁盘访问权限（访问"信息"数据库）。
- 发送时需要自动化权限。
- `channels.imessage.cliPath` 可以指向任何代理 stdin/stdout 的命令（例如，通过 SSH 连接到另一台 Mac 并运行 `imsg rpc` 的包装脚本）。
## 设置（快速路径）
1. 确保此 Mac 上的"信息"已登录。
2. 配置 iMessage 并启动 Gateway网关。
1. 确保在此 Mac 上已登录"信息"。
2. 配置 iMessage 并启动 Gateway 网关。
### 专用机器人 macOS 用户（用于隔离身份）
如果你希望机器人从一个**独立的 iMessage 身份**发送消息（并保持你的个人"信息"整洁），请使用专用的 Apple ID + 专用的 macOS 用户。
如果你希望机器人从**独立的 iMessage 身份**发送（并保持你的个人"信息"整洁），请使用专用 Apple ID + 专用 macOS 用户。
1. 创建一个专用的 Apple ID（例如：`my-cool-bot@icloud.com`）。
- Apple 可能需要手机号码进行验证/双重认证。
2. 创建一个 macOS 用户（例如：`openclawhome`）并登录。
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 包装脚本。
7. 将 `channels.imessage.accounts.bot.cliPath` 指向以机器人用户身份运行 `imsg` 的 SSH 包装脚本。
首次运行注意事项：发送/接收可能需要在*机器人 macOS 用户*中进行 GUI 审批（自动化 + 完全磁盘访问权限）。如果 `imsg rpc` 看起来卡住或退出，请登录该用户（屏幕共享很有帮助），运行一次 `imsg chats --limit 1` / `imsg send ...`，批准提示，然后重试。
首次运行注意事项：发送/接收可能需要在*机器人 macOS 用户*中进行 GUI 批准（自动化 + 完全磁盘访问权限）。如果 `imsg rpc` 看起来卡住或退出，请登录该用户（屏幕共享很有帮助），运行一次 `imsg chats --limit 1` / `imsg send ...`，批准提示，然后重试。
示例包装脚本（`chmod +x`）。将 `<bot-macos-user>` 替换为你的实际 macOS 用户名：
@@ -92,7 +92,7 @@ x-i18n:
#!/usr/bin/env bash
set -euo pipefail
# 先运行一次交互式 SSH 以接受主机密钥：
# 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" "$@"
@@ -118,11 +118,11 @@ exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@local
}
```
对于单账户设置，使用扁平选项（`channels.imessage.cliPath`、`channels.imessage.dbPath`）而非 `accounts` 映射。
对于单账户设置，使用扁平选项（`channels.imessage.cliPath`、`channels.imessage.dbPath`）而不是 `accounts` 映射。
### 远程/SSH 变体（可选）
如果你想在另一台 Mac 上使用 iMessage，将 `channels.imessage.cliPath` 设置为通过 SSH 在远程 macOS 主机上运行 `imsg` 的包装脚本。OpenClaw 只需要 stdio。
如果你想在另一台 Mac 上使用 iMessage，请将 `channels.imessage.cliPath` 设置为通过 SSH 在远程 macOS 主机上运行 `imsg` 的包装脚本。OpenClaw 只需要 stdio。
示例包装脚本：
@@ -131,36 +131,36 @@ exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@local
exec ssh -T gateway-host imsg "$@"
```
**远程附件：** 当 `cliPath` 通过 SSH 指向远程主机时，Messages 数据库中的附件路径引用的是远程机器上的文件。OpenClaw 可以通过设置 `channels.imessage.remoteHost` 自动通过 SCP 获取这些文件：
**远程附件：** 当 `cliPath` 通过 SSH 指向远程主机时，"信息"数据库中的附件路径引用的是远程机器上的文件。OpenClaw 可以通过设置 `channels.imessage.remoteHost` 自动通过 SCP 获取这些文件：
```json5
{
channels: {
imessage: {
cliPath: "~/imsg-ssh", // 到远程 Mac 的 SSH 包装脚本
remoteHost: "user@gateway-host", // 用于 SCP 文件传输
cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
remoteHost: "user@gateway-host", // for SCP file transfer
includeAttachments: true,
},
},
}
```
如果未设置 `remoteHost`，OpenClaw 会尝试通过解析你包装脚本中的 SSH 命令来自动检测。建议显式配置以确保可靠性。
如果未设置 `remoteHost`，OpenClaw 会尝试通过解析包装脚本中的 SSH 命令自动检测。建议显式配置以提高可靠性。
#### 通过 Tailscale 连接远程 Mac（示例）
如果 Gateway网关运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上，Tailscale 是最简单的桥接方案：Gateway网关通过 tailnet 与 Mac 通信，通过 SSH 运行 `imsg`，并通过 SCP 传回附件。
如果 Gateway 网关运行在 Linux 主机/虚拟机上但 iMessage 必须运行在 Mac 上，Tailscale 是最简单的桥接方式：Gateway 网关通过 tailnet 与 Mac 通信，通过 SSH 运行 `imsg`，并通过 SCP 获取附件。
架构：
```
┌──────────────────────────────┐ SSH (imsg rpc) ┌──────────────────────────┐
│ Gateway网关主机（Linux/VM） │──────────────────────────────────▶│ 装有 Messages + imsg 的 Mac │
│ - openclaw gateway │ SCP（附件） │ - Messages 已登录 │
│ - channels.imessage.cliPath │◀──────────────────────────────────│ - 远程登录已启用 │
│ Gateway host (Linux/VM) │──────────────────────────────────▶│ Mac with Messages + imsg │
│ - openclaw gateway │ SCP (attachments) │ - Messages signed in │
│ - channels.imessage.cliPath │◀──────────────────────────────────│ - Remote Login enabled │
└──────────────────────────────┘ └──────────────────────────┘
▲
│ Tailscale tailnet（主机名或 100.x.y.z）
│ Tailscale tailnet (hostname or 100.x.y.z)
▼
user@gateway-host
```
@@ -190,19 +190,19 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
注意事项：
- 确保 Mac 已登录"信息"，且远程登录已启用。
- 确保 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`（它通常包含 token）。
多账户支持：使用 `channels.imessage.accounts` 配置每个账户及可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解共享模式。不要提交 `~/.openclaw/openclaw.json`（它通常包含令牌）。
## 访问控制（私信 + 群组）
私信：
- 默认：`channels.imessage.dmPolicy = "pairing"`。
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- 未知发送者会收到配对码；消息在批准前会被忽略（配对码在 1 小时后过期）。
- 批准方式：
- `openclaw pairing list imessage`
- `openclaw pairing approve imessage <CODE>`
- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/start/pairing)
@@ -210,23 +210,23 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
群组：
- `channels.imessage.groupPolicy = open | allowlist | disabled`。
- 当设置为 `allowlist` 时，`channels.imessage.groupAllowFrom` 控制谁可以在群组中触发。
- 提及门控使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`），因为 iMessage 没有原生提及元数据。
- 设置 `allowlist` 时，`channels.imessage.groupAllowFrom` 控制谁可以在群组中触发。
- 提及检测使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`），因为 iMessage 没有原生提及元数据。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
## 工作原理（行为）
- `imsg` 流式传输消息事件；Gateway网关将其标准化为共享的渠道信封。
- 回复始终路由回同一个 chat id 或用户名。
- `imsg` 流式传输消息事件；Gateway 网关将它们规范化为共享渠道信封。
- 回复始终路由回相同的 chat id 或 handle。
## 类群组线程（`is_group=false`）
## 类群组会话（`is_group=false`）
一些 iMessage 线程可能有多个参与者，但由于"信息"存储聊天标识符的方式，仍然以 `is_group=false` 到达。
某些 iMessage 会话可能有多个参与者，但根据"信息"存储聊天标识符的方式，仍以 `is_group=false` 到达。
如果你在 `channels.imessage.groups` 下显式配置了一个 `chat_id`，OpenClaw 会将该线程视为"群组"，用于：
如果你在 `channels.imessage.groups` 下显式配置了 `chat_id`，OpenClaw 会将该会话视为"群组"用于：
- 会话隔离（独立的 `agent:<agentId>:imessage:group:<chat_id>` 会话键）
- 群组允许列表/提及门控行为
- 群组允许列表 / 提及检测行为
示例：
@@ -244,27 +244,27 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
}
```
当你想为特定线程使用隔离的个性/模型时很有用（参见[多智能体路由](/concepts/multi-agent)）。有关文件系统隔离，请参阅[沙箱](/gateway/sandboxing)。
当你想为特定会话使用隔离的个性/模型时这很有用（参见[多智能体路由](/concepts/multi-agent)）。关于文件系统隔离，参见[沙箱隔离](/gateway/sandboxing)。
## 媒体 + 限制
- 通过 `channels.imessage.includeAttachments` 可选接收附件。
- 媒体上限通过 `channels.imessage.mediaMaxMb` 设置。
- 通过 `channels.imessage.includeAttachments` 可选附件摄取。
- 通过 `channels.imessage.mediaMaxMb` 设置媒体上限。
## 限制
- 出站文本按 `channels.imessage.textChunkLimit` 分块（默认 4000）。
- 可选的换行分块：设置 `channels.imessage.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。
- 媒体上传上限由 `channels.imessage.mediaMaxMb` 限制（默认 16）。
- 可选换行分块：设置 `channels.imessage.chunkMode="newline"` 在长度分块前按空行（段落边界）分割。
- 媒体上传受 `channels.imessage.mediaMaxMb` 限制（默认 16）。
## 寻址 / 投递目标
推荐使用 `chat_id` 进行稳定路由：
优先使用 `chat_id` 进行稳定路由：
- `chat_id:123`（推荐）
- `chat_guid:...`
- `chat_identifier:...`
- 直接用户名：`imessage:+1555` / `sms:+1555` / `user@example.com`
- 直接 handle：`imessage:+1555` / `sms:+1555` / `user@example.com`
列出聊天：
@@ -279,22 +279,22 @@ imsg chats --limit 20
提供商选项：
- `channels.imessage.enabled`：启用/禁用渠道启动。
- `channels.imessage.cliPath`：`imsg` 的路径。
- `channels.imessage.dbPath`：Messages 数据库路径。
- `channels.imessage.remoteHost`：当 `cliPath` 指向远程 Mac 时用于 SCP 附件传输的 SSH 主机（例如 `user@gateway-host`）。未设置时从 SSH 包装脚本自动检测。
- `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`：SMS 区域。
- `channels.imessage.region`：短信区域。
- `channels.imessage.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.imessage.allowFrom`：私信允许列表（用户名、邮箱、E.164 号码或 `chat_id:*`）。`open` 需要 `"*"`。iMessage 没有用户名；使用用户名或聊天目标。
- `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.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`，在按长度分块之前按空行（段落边界）分割。
- `channels.imessage.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。
相关全局选项：
docs/zh-CN/channels/index.md
+19 -17
View File
@@ -5,46 +5,48 @@ read_when:
summary: OpenClaw 可连接的消息平台
title: 聊天渠道
x-i18n:
generated_at: "2026-02-01T19:21:22Z"
generated_at: "2026-02-03T07:43:27Z"
model: claude-opus-4-5
provider: pi
source_hash: 2632863def6dee97e0fa8b931762f0969174fd4fb22303a00dcd46527fe4a141
source_path: channels/index.md
workflow: 14
workflow: 15
---
# 聊天渠道
OpenClaw 可以在你已经使用的任何聊天应用上与你对话。每个渠道通过 Gateway网关连接。所有渠道都支持文本；媒体和回应功能因渠道而异。
OpenClaw 可以在你已经使用的任何聊天应用上与你交流。每个渠道通过 Gateway 网关连接。
所有渠道都支持文本；媒体和表情回应的支持因渠道而异。
## 支持的渠道
- [WhatsApp](/channels/whatsapp) — 最受欢迎；使用 Baileys 并需要二维码配对。
- [WhatsApp](/channels/whatsapp) — 最受欢迎；使用 Baileys，需要二维码配对。
- [Telegram](/channels/telegram) — 通过 grammY 使用 Bot API；支持群组。
- [Discord](/channels/discord) — Discord Bot API + Gateway网关；支持服务器、频道和私信。
- [Discord](/channels/discord) — Discord Bot API + Gateway；支持服务器、频道和私信。
- [Slack](/channels/slack) — Bolt SDK；工作区应用。
- [Google Chat](/channels/googlechat) — 通过 HTTP webhook 使用 Google Chat API 应用。
- [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) — 仅限 macOS；通过 imsg 原生集成（旧版，新设置建议使用 BlueBubbles）。
- [BlueBubbles](/channels/bluebubbles) — **iMessage 推荐方案**；使用 BlueBubbles macOS 服务器 REST API，完整功能支持（编辑、撤回、特效、表情回应、群组管理——编辑功能目前在 macOS 26 Tahoe 上存在问题）。
- [iMessage](/channels/imessage) — 仅限 macOS；通过 imsg 原生集成（旧版方案，新部署建议使用 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 的通讯工具（插件，需单独安装）。
- [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 UI。
- [Zalo](/channels/zalo) — Zalo Bot API；越南流行的消息应用（插件，需单独安装）。
- [Zalo Personal](/channels/zalouser) — 通过二维码登录的 Zalo 个人账号（插件，需单独安装）。
- [WebChat](/web/webchat) — 基于 WebSocket 的 Gateway 网关 WebChat 界面。
## 注意事项
- 渠道可以同时运行；配置多个渠道后 OpenClaw 会按聊天路由。
- 最快的设置通常是 **Telegram**（简单的 bot token）。WhatsApp 需要二维码配对并在磁盘上存储更多状态。
- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。
- 最快的设置方式通常是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对，
并在磁盘上存储更多状态。
- 群组行为因渠道而异；参见[群组](/concepts/groups)。
- 私信配对和允许列表出于安全考虑强制执行；参见[安全](/gateway/security)。
- Telegram 内部实现：[grammY 说明](/channels/grammy)。
- 为安全起见，私信配对和允许列表会被强制执行；参见[安全](/gateway/security)。
- Telegram 内部机制：[grammY 说明](/channels/grammy)。
- 故障排除：[渠道故障排除](/channels/troubleshooting)。
- 模型提供商单独文档化；参见[模型提供商](/providers/models)。
- 模型提供商单独记录；参见[模型提供商](/providers/models)。
docs/zh-CN/channels/line.md
+31 -31
View File
@@ -1,26 +1,26 @@
---
read_when:
- 你想将 OpenClaw 连接到 LINE
- 你需要 LINE webhook + 凭据设置
- 你需要 LINE 特定的消息选项
summary: LINE Messaging API 插件设置、配置和使用
- 你需要配置 LINE webhook + 凭证
- 你想了解 LINE 特有的消息选项
summary: LINE Messaging API 插件的配置、设置和使用方法
title: LINE
x-i18n:
generated_at: "2026-02-01T19:21:38Z"
generated_at: "2026-02-03T07:43:38Z"
model: claude-opus-4-5
provider: pi
source_hash: 8fbac126786f95b9454f3cc61906c2798393a8d7914e787d3755c020c7ab2da6
source_path: channels/line.md
workflow: 14
workflow: 15
---
# LINE（插件）
LINE 通过 LINE Messaging API 连接到 OpenClaw。插件作为 Gateway网关上的 webhook 接收器运行，使用你的频道访问 token + 频道密钥进行认证。
LINE 通过 LINE Messaging API 连接到 OpenClaw。该插件作为 webhook 接收器在 Gateway 网关上运行，使用你的 channel access token + channel secret 进行身份验证。
状态：通过插件支持。支持私信、群聊、媒体、位置、Flex 消息、模板消息和快速回复。不支持回应和线程。
状态：通过插件支持。支持私信、群聊、媒体、位置、Flex 消息、模板消息和快捷回复。不支持表情回应和话题回复。
## 需要插件
## 需要安装插件
安装 LINE 插件：
@@ -34,20 +34,20 @@ openclaw plugins install @openclaw/line
openclaw plugins install ./extensions/line
```
## 设置
## 配置步骤
1. 创建 LINE Developers 账户并打开控制台：
https://developers.line.biz/console/
2. 创建（或选择）一个 Provider 并添加一个 **Messaging API** 频道。
3. 从频道设置中复制 **Channel access token** 和 **Channel secret**。
2. 创建（或选择）一个 Provider 并添加 **Messaging API** 渠道。
3. 从渠道设置中复制 **Channel access token** 和 **Channel secret**。
4. 在 Messaging API 设置中启用 **Use webhook**。
5. 将 webhook URL 设置为你的 Gateway网关端点（需要 HTTPS）：
5. 将 webhook URL 设置为你的 Gateway 网关端点（必须使用 HTTPS）：
```
https://gateway-host/line/webhook
```
Gateway网关响应 LINE 的 webhook 验证（GET）和入站事件（POST）。如果你需要自定义路径，请设置 `channels.line.webhookPath` 或 `channels.line.accounts.<id>.webhookPath` 并相应更新 URL。
Gateway 网关会响应 LINE 的 webhook 验证（GET）和入站事件（POST）。如果你需要自定义路径，请设置 `channels.line.webhookPath` 或 `channels.line.accounts.<id>.webhookPath` 并相应更新 URL。
## 配置
@@ -66,12 +66,12 @@ Gateway网关响应 LINE 的 webhook 验证（GET）和入站事件（POST）。
}
```
环境变量（仅默认账户）：
环境变量（仅限默认账户）：
- `LINE_CHANNEL_ACCESS_TOKEN`
- `LINE_CHANNEL_SECRET`
Token/密钥文件：
Token/secret 文件：
```json5
{
@@ -84,7 +84,7 @@ Token/密钥文件：
}
```
多账户：
多账户配置：
```json5
{
@@ -104,7 +104,7 @@ Token/密钥文件：
## 访问控制
私信默认需要配对。未知发送者会收到配对码，在批准之前其消息会被忽略。
私信默认使用配对模式。未知发送者会收到配对码，其消息在获得批准前会被忽略。
```bash
openclaw pairing list line
@@ -114,12 +114,12 @@ openclaw pairing approve line <CODE>
允许列表和策略：
- `channels.line.dmPolicy`：`pairing | allowlist | open | disabled`
- `channels.line.allowFrom`：私信的允许 LINE 用户 ID 列表
- `channels.line.allowFrom`：私信的允许列表 LINE 用户 ID
- `channels.line.groupPolicy`：`allowlist | open | disabled`
- `channels.line.groupAllowFrom`：群组的允许 LINE 用户 ID 列表
- 按群组覆盖：`channels.line.groups.<groupId>.allowFrom`
- `channels.line.groupAllowFrom`：群组的允许列表 LINE 用户 ID
- 单群组覆盖：`channels.line.groups.<groupId>.allowFrom`
LINE ID 区分大小写。有效的 ID 格式如下：
LINE ID 区分大小写。有效 ID 格式如下：
- 用户：`U` + 32 位十六进制字符
- 群组：`C` + 32 位十六进制字符
@@ -127,14 +127,14 @@ LINE ID 区分大小写。有效的 ID 格式如下：
## 消息行为
- 文本在 5000 字符处分块。
- Markdown 格式会被去除；代码块和表格在可能时会转换为 Flex 卡片。
- 流式响应会被缓冲；智能体工作时 LINE 接收完整分块并显示加载动画。
- 媒体下载上限由 `channels.line.mediaMaxMb` 限制（默认 10）。
- 文本按 5000 字符分块。
- Markdown 格式会被移除；代码块和表格会尽可能转换为 Flex 卡片。
- 流式响应会被缓冲；智能体处理时，LINE 会收到完整分块并显示加载动画。
- 媒体下载受 `channels.line.mediaMaxMb` 限制（默认 10）。
## 渠道数据（富消息）
使用 `channelData.line` 发送快速回复、位置、Flex 卡片或模板消息。
使用 `channelData.line` 发送快捷回复、位置、Flex 卡片或模板消息。
```json5
{
@@ -151,7 +151,7 @@ LINE ID 区分大小写。有效的 ID 格式如下：
flexMessage: {
altText: "Status card",
contents: {
/* Flex 负载 */
/* Flex payload */
},
},
templateMessage: {
@@ -167,7 +167,7 @@ LINE ID 区分大小写。有效的 ID 格式如下：
}
```
LINE 插件还附带一个 `/card` 命令用于 Flex 消息预设：
LINE 插件还提供 `/card` 命令用于 Flex 消息预设：
```
/card info "Welcome" "Thanks for joining!"
@@ -175,6 +175,6 @@ LINE 插件还附带一个 `/card` 命令用于 Flex 消息预设：
## 故障排除
- **Webhook 验证失败：** 确保 webhook URL 为 HTTPS 且 `channelSecret` 与 LINE 控制台匹配。
- **没有入站事件：** 确认 webhook 路径与 `channels.line.webhookPath` 匹配且 Gateway网关可从 LINE 访问。
- **媒体下载错误：** 如果媒体超过默认限制，请增大 `channels.line.mediaMaxMb`。
- **Webhook 验证失败：** 确保 webhook URL 使用 HTTPS 且 `channelSecret` 与 LINE 控制台中的一致。
- **没有入站事件：** 确认 webhook 路径与 `channels.line.webhookPath` 匹配，且 Gateway 网关可从 LINE 访问。
- **媒体下载错误：** 如果媒体超过默认限制，请提高 `channels.line.mediaMaxMb`。
docs/zh-CN/channels/matrix.md
+62 -62
View File
@@ -4,25 +4,25 @@ read_when:
summary: Matrix 支持状态、功能和配置
title: Matrix
x-i18n:
generated_at: "2026-02-01T19:22:24Z"
generated_at: "2026-02-03T07:44:02Z"
model: claude-opus-4-5
provider: pi
source_hash: b276b5263593c766e7be6549abbb27927177e7b51cfd297b4825965372513ee4
source_path: channels/matrix.md
workflow: 14
workflow: 15
---
# Matrix（插件）
Matrix 是一个开放、去中心化的消息协议。OpenClaw 作为 Matrix **用户**连接到任何主服务器，因此你需要为机器人创建一个 Matrix 账户。登录后，你可以直接私信机器人或邀请它加入房间（Matrix 的"群组"）。Beeper 也是一个可用的客户端选项，但它需要启用端到端加密。
Matrix 是一个开放的去中心化消息协议。OpenClaw 以 Matrix **用户**身份连接到任意主服务器，因此你需要为机器人创建一个 Matrix 账户。登录后，你可以直接私信机器人或邀请它加入房间（Matrix"群组"）。Beeper 也是一个有效的客户端选项，但它需要启用 E2EE。
状态：通过插件支持（@vector-im/matrix-bot-sdk）。支持私信、房间、线程、媒体、回应、投票（发送 + poll-start 转为文本）、位置和端到端加密（需要加密支持）。
状态：通过插件（@vector-im/matrix-bot-sdk）支持。支持私信、房间、话题、媒体、表情回应、投票（发送 + poll-start 作为文本）、位置和 E2EE（需要加密支持）。
## 需要插件
Matrix 作为插件发布，不包含在核心安装中。
Matrix 作为插件提供，不包含在核心安装中。
通过 CLI 安装（npm 注册表）：
通过 CLI 安装（npm 仓库）：
```bash
openclaw plugins install @openclaw/matrix
@@ -34,7 +34,7 @@ openclaw plugins install @openclaw/matrix
openclaw plugins install ./extensions/matrix
```
如果你在配置/新手引导期间选择了 Matrix 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
如果你在配置/新手引导期间选择 Matrix 并检测到 git 检出，OpenClaw 将自动提供本地安装路径。
详情：[插件](/plugin)
@@ -46,8 +46,8 @@ openclaw plugins install ./extensions/matrix
2. 在主服务器上创建 Matrix 账户：
- 在 [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/) 浏览托管选项
- 或自行托管。
3. 获取机器人账户的访问 token：
- 在你的主服务器上使用 Matrix 登录 API 配合 `curl`：
3. 获取机器人账户的访问令牌：
- 在你的主服务器上使用 `curl` 调用 Matrix 登录 API：
```bash
curl --request POST \
@@ -64,18 +64,18 @@ openclaw plugins install ./extensions/matrix
```
- 将 `matrix.example.org` 替换为你的主服务器 URL。
- 或设置 `channels.matrix.userId` + `channels.matrix.password`：OpenClaw 调用相同的登录端点，将访问 token 存储在 `~/.openclaw/credentials/matrix/credentials.json` 中，并在下次启动时重用。
- 或设置 `channels.matrix.userId` + `channels.matrix.password`：OpenClaw 会调用相同的登录端点，将访问令牌存储在 `~/.openclaw/credentials/matrix/credentials.json`，并在下次启动时重用。
4. 配置凭据：
4. 配置凭证：
- 环境变量：`MATRIX_HOMESERVER`、`MATRIX_ACCESS_TOKEN`（或 `MATRIX_USER_ID` + `MATRIX_PASSWORD`）
- 或配置：`channels.matrix.*`
- 如果两者都设置了，配置优先。
- 使用访问 token 时：用户 ID 通过 `/whoami` 自动获取。
- 设置时，`channels.matrix.userId` 应为完整的 Matrix ID（例如：`@bot:example.org`）。
5. 重启 Gateway网关（或完成新手引导）。
6. 从任何 Matrix 客户端（Element、Beeper 等；参见 https://matrix.org/ecosystem/clients/）与机器人开始私信或邀请它加入房间。Beeper 需要端到端加密，因此请设置 `channels.matrix.encryption: true` 并验证设备。
- 如果两者都设置，配置优先。
- 使用访问令牌时：用户 ID 通过 `/whoami` 自动获取。
- 设置时，`channels.matrix.userId` 应为完整的 Matrix ID（示例：`@bot:example.org`）。
5. 重启 Gateway 网关（或完成新手引导）。
6. 从任何 Matrix 客户端（Element、Beeper 等；参见 https://matrix.org/ecosystem/clients/）与机器人开始私信或邀请它加入房间。Beeper 需要 E2EE，因此请设置 `channels.matrix.encryption: true` 并验证设备。
最小配置（访问 token，用户 ID 自动获取）：
最小配置（访问令牌，用户 ID 自动获取）：
```json5
{
@@ -90,7 +90,7 @@ openclaw plugins install ./extensions/matrix
}
```
端到端加密配置（启用端到端加密）：
E2EE 配置（启用端到端加密）：
```json5
{
@@ -106,27 +106,27 @@ openclaw plugins install ./extensions/matrix
}
```
## 加密（端到端加密）
## 加密（E2EE）
端到端加密通过 Rust 加密 SDK **支持**。
通过 Rust 加密 SDK **支持**端到端加密。
通过 `channels.matrix.encryption: true` 启用：
使用 `channels.matrix.encryption: true` 启用：
- 如果加密模块加载成功，加密房间会自动解密。
- 向加密房间发送时，出站媒体会被加密。
- 首次连接时，OpenClaw 会从你的其他会话请求设备验证。
- 发送到加密房间时，出站媒体会被加密。
- 首次连接时，OpenClaw 会向你的其他会话请求设备验证。
- 在另一个 Matrix 客户端（Element 等）中验证设备以启用密钥共享。
- 如果加密模块无法加载，端到端加密将被禁用且加密房间无法解密；OpenClaw 会记录警告。
- 如果你看到缺少加密模块的错误（例如 `@matrix-org/matrix-sdk-crypto-nodejs-*`），请允许 `@matrix-org/matrix-sdk-crypto-nodejs` 的构建脚本并运行 `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` 或通过 `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js` 获取二进制文件。
- 如果无法加载加密模块，E2EE 将被禁用，加密房间将无法解密；OpenClaw 会记录警告。
- 如果你看到缺少加密模块的错误（例如 `@matrix-org/matrix-sdk-crypto-nodejs-*`），请允许 `@matrix-org/matrix-sdk-crypto-nodejs` 的构建脚本并运行 `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs`，或使用 `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js` 获取二进制文件。
加密状态按账户 + 访问 token 存储在 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/`（SQLite 数据库）。同步状态存储在同一目录下的 `bot-storage.json` 中。如果访问 token（设备）发生变化，会创建新的存储，机器人必须重新验证才能在加密房间中使用。
加密状态按账户 + 访问令牌存储在 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/`（SQLite 数据库）。同步状态存储在同目录的 `bot-storage.json` 中。如果访问令牌（设备）更改，将创建新的存储，机器人必须重新验证才能访问加密房间。
**设备验证：**
启用端到端加密后，机器人会在启动时从你的其他会话请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证完成后，机器人可以解密加密房间中的消息。
启用 E2EE 时，机器人将在启动时向你的其他会话请求验证。打开 Element（或其他客户端）并批准验证请求以建立信任。验证后，机器人可以解密加密房间中的消息。
## 路由模型
- 回复始终发回 Matrix。
- 回复始终返回到 Matrix。
- 私信共享智能体的主会话；房间映射到群组会话。
## 访问控制（私信）
@@ -136,12 +136,12 @@ openclaw plugins install ./extensions/matrix
- `openclaw pairing list matrix`
- `openclaw pairing approve matrix <CODE>`
- 公开私信：`channels.matrix.dm.policy="open"` 加上 `channels.matrix.dm.allowFrom=["*"]`。
- `channels.matrix.dm.allowFrom` 仅接受完整 Matrix 用户 ID（例如 `@user:server`）。向导仅在目录搜索得到唯一精确匹配时解析显示名称为用户 ID。
- `channels.matrix.dm.allowFrom` 仅接受完整 Matrix 用户 ID（例如 `@user:server`）。向导仅在目录搜索得到唯一精确匹配时将显示名称解析为用户 ID。
## 房间（群组）
- 默认：`channels.matrix.groupPolicy = "allowlist"`（提及门控）。使用 `channels.defaults.groupPolicy` 可在未设置时覆盖默认值。
- 使用 `channels.matrix.groups` 允许列表中的房间（房间 ID/别名；名称仅在目录搜索得到唯一精确匹配时解析为 ID）：
- 默认：`channels.matrix.groupPolicy = "allowlist"`（提及门控）。使用 `channels.defaults.groupPolicy` 在未设置时覆盖默认值。
- 使用 `channels.matrix.groups` 配置房间允许列表（房间 ID 或别名；名称仅在目录搜索得到唯一精确匹配时解析为 ID）：
```json5
{
@@ -160,35 +160,35 @@ openclaw plugins install ./extensions/matrix
- `requireMention: false` 启用该房间的自动回复。
- `groups."*"` 可以设置跨房间的提及门控默认值。
- `groupAllowFrom` 限制哪些发送者可以在房间中触发机器人（完整 Matrix 用户 ID）。
- 按房间的 `users` 允许列表可以进一步限制特定房间内的发送者（使用完整 Matrix 用户 ID）。
- `groupAllowFrom` 限制哪些发送者可以在房间中触发机器人（需完整 Matrix 用户 ID）。
- 每个房间的 `users` 允许列表可以进一步限制特定房间内的发送者（需完整 Matrix 用户 ID）。
- 配置向导会提示输入房间允许列表（房间 ID、别名或名称），仅在精确且唯一匹配时解析名称。
- 启动时，OpenClaw 将允许列表中的房间/用户名称解析为 ID 并记录映射；未解析的条目不会参与允许列表匹配。
- 邀请默认自动加入；通过 `channels.matrix.autoJoin` 和 `channels.matrix.autoJoinAllowlist` 控制。
- 要**不允许任何房间**，设置 `channels.matrix.groupPolicy: "disabled"`（或保持空的允许列表）。
- 旧版键：`channels.matrix.rooms`（与 `groups` 结构相同）。
- 默认自动加入邀请；使用 `channels.matrix.autoJoin` 和 `channels.matrix.autoJoinAllowlist` 控制。
- 要**禁止所有房间**，设置 `channels.matrix.groupPolicy: "disabled"`（或保持空的允许列表）。
- 旧版键名：`channels.matrix.rooms`（与 `groups` 相同的结构）。
## 线程
## 话题
- 支持回复线程。
- `channels.matrix.threadReplies` 控制回复是否保持在线程中：
- 支持回复话题。
- `channels.matrix.threadReplies` 控制回复是否保持在话题中：
- `off`、`inbound`（默认）、`always`
- `channels.matrix.replyToMode` 控制不在线程中回复时的 reply-to 元数据：
- `channels.matrix.replyToMode` 控制不在话题中回复时的 reply-to 元数据：
- `off`（默认）、`first`、`all`
## 功能
| 功能 | 状态 |
| ---------- | ---------------------------------------------------------- |
| 私信 | ✅ 支持 |
| 房间 | ✅ 支持 |
| 线程 | ✅ 支持 |
| 媒体 | ✅ 支持 |
| 端到端加密 | ✅ 支持（需要加密模块） |
| 回应 | ✅ 支持（通过工具发送/读取） |
| 投票 | ✅ 支持发送；入站 poll start 转换为文本（响应/结束被忽略） |
| 位置 | ✅ 支持（geo URI；忽略海拔） |
| 原生命令 | ✅ 支持 |
| 功能 | 状态 |
| -------- | ------------------------------------------------------ |
| 私信 | ✅ 支持 |
| 房间 | ✅ 支持 |
| 话题 | ✅ 支持 |
| 媒体 | ✅ 支持 |
| E2EE | ✅ 支持（需要加密模块） |
| 表情回应 | ✅ 支持（通过工具发送/读取） |
| 投票 | ✅ 支持发送；入站投票开始转换为文本（响应/结束被忽略） |
| 位置 | ✅ 支持（geo URI；忽略海拔） |
| 原生命令 | ✅ 支持 |
## 配置参考（Matrix）
@@ -198,24 +198,24 @@ openclaw plugins install ./extensions/matrix
- `channels.matrix.enabled`：启用/禁用渠道启动。
- `channels.matrix.homeserver`：主服务器 URL。
- `channels.matrix.userId`：Matrix 用户 ID（使用访问 token 时可选）。
- `channels.matrix.accessToken`：访问 token。
- `channels.matrix.password`：登录密码（token 会被存储）。
- `channels.matrix.userId`：Matrix 用户 ID（使用访问令牌时可选）。
- `channels.matrix.accessToken`：访问令牌。
- `channels.matrix.password`：登录密码（令牌会被存储）。
- `channels.matrix.deviceName`：设备显示名称。
- `channels.matrix.encryption`：启用端到端加密（默认：false）。
- `channels.matrix.encryption`：启用 E2EE（默认：false）。
- `channels.matrix.initialSyncLimit`：初始同步限制。
- `channels.matrix.threadReplies`：`off | inbound | always`（默认：inbound）。
- `channels.matrix.textChunkLimit`：出站文本分块大小（字符）。
- `channels.matrix.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
- `channels.matrix.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。
- `channels.matrix.dm.policy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.matrix.dm.allowFrom`：私信允许列表（完整 Matrix 用户 ID）。`open` 需要 `"*"`。向导在可能时将名称解析为 ID。
- `channels.matrix.dm.allowFrom`：私信允许列表（需完整 Matrix 用户 ID）。`open` 需要 `"*"`。向导在可能时将名称解析为 ID。
- `channels.matrix.groupPolicy`：`allowlist | open | disabled`（默认：allowlist）。
- `channels.matrix.groupAllowFrom`：群组消息的允许发送者列表（完整 Matrix 用户 ID）。
- `channels.matrix.allowlistOnly`：强制对私信 + 房间执行允许列表规则。
- `channels.matrix.groups`：群组允许列表 + 按房间设置映射。
- `channels.matrix.groupAllowFrom`：群组消息的允许发送者列表（需完整 Matrix 用户 ID）。
- `channels.matrix.allowlistOnly`：强制私信 + 房间使用允许列表规则。
- `channels.matrix.groups`：群组允许列表 + 每个房间的设置映射。
- `channels.matrix.rooms`：旧版群组允许列表/配置。
- `channels.matrix.replyToMode`：线程/标签的 reply-to 模式。
- `channels.matrix.replyToMode`：话题/标签的 reply-to 模式。
- `channels.matrix.mediaMaxMb`：入站/出站媒体上限（MB）。
- `channels.matrix.autoJoin`：邀请处理（`always | allowlist | off`，默认：always）。
- `channels.matrix.autoJoinAllowlist`：自动加入的允许房间 ID/别名。
- `channels.matrix.actions`：按操作的工具门控（reactions/messages/pins/memberInfo/channelInfo）。
- `channels.matrix.actions`：每个操作的工具限制（reactions/messages/pins/memberInfo/channelInfo）。
docs/zh-CN/channels/mattermost.md
+18 -16
View File
@@ -5,21 +5,23 @@ read_when:
summary: Mattermost 机器人设置和 OpenClaw 配置
title: Mattermost
x-i18n:
generated_at: "2026-02-01T19:22:40Z"
generated_at: "2026-02-03T07:43:43Z"
model: claude-opus-4-5
provider: pi
source_hash: 57fabe5eb0efbcb885f4178b317b2fa99a41daf609e3a471de2b44db9def4ad7
source_path: channels/mattermost.md
workflow: 14
workflow: 15
---
# Mattermost（插件）
状态：通过插件支持（bot token + WebSocket 事件）。支持频道、群组和私信。Mattermost 是一个可自托管的团队消息平台；有关产品详情和下载请访问官方网站 [mattermost.com](https://mattermost.com)。
状态：通过插件支持（bot token + WebSocket 事件）。支持频道、群组和私信。
Mattermost 是一个可自托管的团队消息平台；有关产品详情和下载，请访问官方网站
[mattermost.com](https://mattermost.com)。
## 需要插件
Mattermost 作为插件发布，不包含在核心安装中。
Mattermost 以插件形式提供，不包含在核心安装中。
通过 CLI 安装（npm 注册表）：
@@ -33,16 +35,16 @@ openclaw plugins install @openclaw/mattermost
openclaw plugins install ./extensions/mattermost
```
如果你在配置/新手引导期间选择了 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
如果你在配置/新手引导期间选择 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
详情：[插件](/plugin)
## 快速设置
1. 安装 Mattermost 插件。
2. 创建一个 Mattermost 机器人账户并复制 **bot token**。
2. 创建 Mattermost bot 账户并复制 **bot token**。
3. 复制 Mattermost **基础 URL**（例如 `https://chat.example.com`）。
4. 配置 OpenClaw 并启动 Gateway网关。
4. 配置 OpenClaw 并启动 Gateway 网关。
最小配置：
@@ -61,7 +63,7 @@ openclaw plugins install ./extensions/mattermost
## 环境变量（默认账户）
如果你偏好使用环境变量，请在 Gateway网关主机上设置：
如果你偏好使用环境变量，请在 Gateway 网关主机上设置：
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
@@ -73,7 +75,7 @@ openclaw plugins install ./extensions/mattermost
Mattermost 自动响应私信。频道行为由 `chatmode` 控制：
- `oncall`（默认）：仅在频道中被 @提及时响应。
- `onmessage`：响应频道中的每条消息。
- `onmessage`：响应每条频道消息。
- `onchar`：当消息以触发前缀开头时响应。
配置示例：
@@ -91,8 +93,8 @@ Mattermost 自动响应私信。频道行为由 `chatmode` 控制：
注意事项：
- `onchar` 模式仍然响应明确的 @提及。
- `channels.mattermost.requireMention` 对旧版配置仍然有效，但推荐使用 `chatmode`。
- `onchar` 仍会响应显式 @提及。
- `channels.mattermost.requireMention` 对旧配置仍然有效，但推荐使用 `chatmode`。
## 访问控制（私信）
@@ -104,13 +106,13 @@ Mattermost 自动响应私信。频道行为由 `chatmode` 控制：
## 频道（群组）
- 默认：`channels.mattermost.groupPolicy = "allowlist"`（提及门控）。
- 使用 `channels.mattermost.groupAllowFrom` 允许列表发送者（用户 ID 或 `@username`）。
- 开放频道：`channels.mattermost.groupPolicy="open"`（提及门控）。
- 默认：`channels.mattermost.groupPolicy = "allowlist"`（提及限制）。
- 使用 `channels.mattermost.groupAllowFrom` 将发送者加入允许列表（用户 ID 或 `@username`）。
- 开放频道：`channels.mattermost.groupPolicy="open"`（提及限制）。
## 出站投递目标
在 `openclaw message send` 或定时任务/webhook 中使用以下目标格式：
在 `openclaw message send` 或 cron/webhooks 中使用这些目标格式：
- `channel:<id>` 用于频道
- `user:<id>` 用于私信
@@ -137,6 +139,6 @@ Mattermost 支持在 `channels.mattermost.accounts` 下配置多个账户：
## 故障排除
- 频道中没有回复：确保机器人已加入频道并提及它（oncall 模式），使用触发前缀（onchar 模式），或设置 `chatmode: "onmessage"`。
- 频道中无回复：确保 bot 在频道中并提及它（oncall），使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。
- 认证错误：检查 bot token、基础 URL 以及账户是否已启用。
- 多账户问题：环境变量仅适用于 `default` 账户。
docs/zh-CN/channels/msteams.md
+176 -171
View File
@@ -1,32 +1,32 @@
---
read_when:
- 开发 Microsoft Teams 渠道功能
- 开发 MS Teams 渠道功能
summary: Microsoft Teams 机器人支持状态、功能和配置
title: Microsoft Teams
x-i18n:
generated_at: "2026-02-01T19:26:12Z"
generated_at: "2026-02-03T07:46:52Z"
model: claude-opus-4-5
provider: pi
source_hash: 3d5641c578086f7569f42276d4ef2462200b9927ca3f505e6ee26806103eaa60
source_hash: 2046cb8fa3dd349f4b25a40c013a87188af8f75c1886a782698bff2bb9f70971
source_path: channels/msteams.md
workflow: 14
workflow: 15
---
# Microsoft Teams（插件）
> "进入此处者，放弃一切希望。"
> "进入此地者，放弃一切希望。"
更新时间：2026-01-21
状态：支持文本 + 私信附件；频道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见[在群聊中发送文件](#在群聊中发送文件)）。投票通过 Adaptive Cards 发送。
状态：支持文本 + 私信附件；频道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见[在群聊中发送文件](#sending-files-in-group-chats)）。投票通过 Adaptive Cards 发送。
## 需要插件
Microsoft Teams 作为插件发布，不包含在核心安装中。
Microsoft Teams 作为插件提供，不包含在核心安装中。
**破坏性变更（2026.1.15）：** Microsoft Teams 已从核心中移出。如果你使用它，必须安装插件。
**破坏性变更（2026.1.15）：** MS Teams 已从核心移出。如果你使用它，必须安装插件。
原因说明：保持核心安装更轻量，并让 Microsoft Teams 依赖项可以独立更新。
原因说明：保持核心安装更轻量，并让 MS Teams 依赖项可以独立更新。
通过 CLI 安装（npm 注册表）：
@@ -40,17 +40,18 @@ openclaw plugins install @openclaw/msteams
openclaw plugins install ./extensions/msteams
```
如果你在配置/新手引导期间选择了 Teams 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
如果你在配置/新手引导过程中选择 Teams 并检测到 git 检出，
OpenClaw 将自动提供本地安装路径。
详情：[插件](/plugin)
## 快速设置（新手）
## 快速设置（初学者）
1. 安装 Microsoft Teams 插件。
2. 创建一个 **Azure Bot**（App ID + 客户端密钥 + 租户 ID）。
3. 使用这些凭据配置 OpenClaw。
3. 使用这些凭证配置 OpenClaw。
4. 通过公共 URL 或隧道暴露 `/api/messages`（默认端口 3978）。
5. 安装 Teams 应用包并启动 Gateway网关。
5. 安装 Teams 应用包并启动 Gateway 网关。
最小配置：
@@ -68,19 +69,19 @@ openclaw plugins install ./extensions/msteams
}
```
注意：群聊默认被阻止（`channels.msteams.groupPolicy: "allowlist"`）。要允许群组回复，请设置 `channels.msteams.groupAllowFrom`（或使用 `groupPolicy: "open"` 允许任何成员，提及门控）。
注意：群聊默认被阻止（`channels.msteams.groupPolicy: "allowlist"`）。要允许群组回复，请设置 `channels.msteams.groupAllowFrom`（或使用 `groupPolicy: "open"` 允许任何成员，需要提及才能触发）。
## 目标
- 通过 Teams 私信、群聊或频道与 OpenClaw 对话。
- 保持路由确定性：回复始终发回消息到达的渠道。
- 默认使用安全的渠道行为（除非另行配置，否则需要提及）。
- 通过 Teams 私信、群聊或频道与 OpenClaw 交流。
- 保持路由确定性：回复始终返回到消息到达的渠道。
- 默认使用安全的渠道行为（除非另有配置，否则需要提及）。
## 配置写入
默认情况下，Microsoft Teams 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。
通过以下方式禁用：
禁用方式：
```json5
{
@@ -92,14 +93,14 @@ openclaw plugins install ./extensions/msteams
**私信访问**
- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在批准前会被忽略。
- `channels.msteams.allowFrom` 接受 AAD 对象 ID、UPN 或显示名称。当凭据允许时，向导通过 Microsoft Graph 将名称解析为 ID。
- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在获得批准之前将被忽略。
- `channels.msteams.allowFrom` 接受 AAD 对象 ID、UPN 或显示名称。当凭证允许时，向导会通过 Microsoft Graph 将名称解析为 ID。
**群组访问**
- 默认：`channels.msteams.groupPolicy = "allowlist"`（被阻止，除非你添加 `groupAllowFrom`）。使用 `channels.defaults.groupPolicy` 可在未设置时覆盖默认值。
- 默认：`channels.msteams.groupPolicy = "allowlist"`（除非添加 `groupAllowFrom`，否则被阻止）。使用 `channels.defaults.groupPolicy` 在未设置时覆盖默认值。
- `channels.msteams.groupAllowFrom` 控制哪些发送者可以在群聊/频道中触发（回退到 `channels.msteams.allowFrom`）。
- 设置 `groupPolicy: "open"` 可允许任何成员（默认仍需提及门控）。
- 设置 `groupPolicy: "open"` 允许任何成员（默认仍需提及才能触发）。
- 要**不允许任何频道**，设置 `channels.msteams.groupPolicy: "disabled"`。
示例：
@@ -117,11 +118,12 @@ openclaw plugins install ./extensions/msteams
**团队 + 频道允许列表**
- 通过在 `channels.msteams.teams` 下列出团队和频道来限定群组/频道回复范围。
- 通过在 `channels.msteams.teams` 下列出团队和频道来限定群组/频道回复的范围。
- 键可以是团队 ID 或名称；频道键可以是会话 ID 或名称。
- 当 `groupPolicy="allowlist"` 且存在团队允许列表时，仅接受列出的团队/频道（提及门控）。
- 当 `groupPolicy="allowlist"` 且存在团队允许列表时，仅接受列出的团队/频道（需要提及才能触发）。
- 配置向导接受 `Team/Channel` 条目并为你存储。
- 启动时，OpenClaw 将团队/频道和用户允许列表名称解析为 ID（当 Graph 权限允许时）并记录映射；未解析的条目保持原样。
- 启动时，OpenClaw 将团队/频道和用户允许列表名称解析为 ID（当 Graph 权限允许时）
并记录映射；未解析的条目保持原样。
示例：
@@ -146,10 +148,10 @@ openclaw plugins install ./extensions/msteams
1. 安装 Microsoft Teams 插件。
2. 创建一个 **Azure Bot**（App ID + 密钥 + 租户 ID）。
3. 构建一个引用该机器人并包含下方 RSC 权限的 **Teams 应用包**。
4. 将 Teams 应用上传/安装到团队（或私人范围用于私信）。
5. 在 `~/.openclaw/openclaw.json`（或环境变量）中配置 `msteams` 并启动 Gateway网关。
6. Gateway网关默认在 `/api/messages` 上监听 Bot Framework webhook 流量。
3. 构建一个引用机器人并包含以下 RSC 权限的 **Teams 应用包**。
4. 将 Teams 应用上传/安装到团队中（或用于私信的个人范围）。
5. 在 `~/.openclaw/openclaw.json`（或环境变量）中配置 `msteams` 并启动 Gateway 网关。
6. Gateway 网关默认在 `/api/messages` 上监听 Bot Framework webhook 流量。
## Azure Bot 设置（前提条件）
@@ -158,13 +160,13 @@ openclaw plugins install ./extensions/msteams
### 步骤 1：创建 Azure Bot
1. 前往[创建 Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
2. 填写 **Basics** 标签页：
2. 填写**基本信息**选项卡：
| 字段 | 值 |
| ------------------ | --------------------------------------------------- |
| **Bot handle** | 你的机器人名称，例如 `openclaw-msteams`（必须唯一） |
| **Subscription** | 选择你的 Azure 订阅 |
| **Resource group** | 新建或使用现有的 |
| **Resource group** | 新建或使用现有 |
| **Pricing tier** | **Free** 用于开发/测试 |
| **Type of App** | **Single Tenant**（推荐 - 见下方说明） |
| **Creation type** | **Create new Microsoft App ID** |
@@ -173,22 +175,22 @@ openclaw plugins install ./extensions/msteams
3. 点击 **Review + create** → **Create**（等待约 1-2 分钟）
### 步骤 2：获取凭据
### 步骤 2：获取凭证
1. 前往你的 Azure Bot 资源 → **Configuration**
2. 复制 **Microsoft App ID** → 这是你的 `appId`
3. 点击 **Manage Password** → 进入应用注册
3. 点击 **Manage Password** → 前往应用注册
4. 在 **Certificates & secrets** → **New client secret** → 复制 **Value** → 这是你的 `appPassword`
5. 进入 **Overview** → 复制 **Directory (tenant) ID** → 这是你的 `tenantId`
5. 前往 **Overview** → 复制 **Directory (tenant) ID** → 这是你的 `tenantId`
### 步骤 3：配置消息端点
1. 在 Azure Bot → **Configuration**
2. 将 **Messaging endpoint** 设置为你的 webhook URL：
- 生产环境：`https://your-domain.com/api/messages`
- 本地开发：使用隧道（参见下方[本地开发](#本地开发隧道)）
- 本地开发：使用隧道（见下方[本地开发](#local-development-tunneling)）
### 步骤 4：启用 Teams 频道
### 步骤 4：启用 Teams 渠道
1. 在 Azure Bot → **Channels**
2. 点击 **Microsoft Teams** → Configure → Save
@@ -198,7 +200,7 @@ openclaw plugins install ./extensions/msteams
Teams 无法访问 `localhost`。本地开发请使用隧道：
**方案 A：ngrok**
**选项 A：ngrok**
```bash
ngrok http 3978
@@ -206,7 +208,7 @@ ngrok http 3978
# 将消息端点设置为：https://abc123.ngrok.io/api/messages
```
**方案 B：Tailscale Funnel**
**选项 B：Tailscale Funnel**
```bash
tailscale funnel 3978
@@ -215,31 +217,31 @@ tailscale funnel 3978
## Teams 开发者门户（替代方案）
除了手动创建清单 ZIP 外，你可以使用 [Teams 开发者门户](https://dev.teams.microsoft.com/apps)：
除了手动创建清单 ZIP，你可以使用 [Teams 开发者门户](https://dev.teams.microsoft.com/apps)：
1. 点击 **+ New app**
2. 填写基本信息（名称、描述、开发者信息）
3. 进入 **App features** → **Bot**
3. 前往 **App features** → **Bot**
4. 选择 **Enter a bot ID manually** 并粘贴你的 Azure Bot App ID
5. 勾选范围：**Personal**、**Team**、**Group Chat**
6. 点击 **Distribute** → **Download app package**
7. 在 Teams 中：**Apps** → **Manage your apps** → **Upload a custom app** → 选择 ZIP
这通常比手动编辑 JSON 清单更简单。
这通常比手动编辑 JSON 清单更容易。
## 测试机器人
**方案 A：Azure Web Chat（先验证 webhook）**
**选项 A：Azure Web Chat（先验证 webhook）**
1. 在 Azure 门户 → 你的 Azure Bot 资源 → **Test in Web Chat**
2. 发送一条消息 - 你应该看到回复
3. 这确认了你的 webhook 端点在 Teams 设置之前可以正常工作
2. 发送一条消息 - 你应该看到响应
3. 这确认你的 webhook 端点在 Teams 设置之前正常工作
**方案 B：Teams（安装应用后）**
**选项 B：Teams（应用安装后）**
1. 安装 Teams 应用（旁加载或组织目录）
1. 安装 Teams 应用（侧载或组织目录）
2. 在 Teams 中找到机器人并发送私信
3. 检查 Gateway网关日志中的传入活动
3. 检查 Gateway 网关日志中的传入活动
## 设置（最小纯文本）
@@ -248,7 +250,7 @@ tailscale funnel 3978
- 从本地检出：`openclaw plugins install ./extensions/msteams`
2. **机器人注册**
- 创建 Azure Bot（见上方）并记录：
- 创建一个 Azure Bot（见上文）并记录：
- App ID
- 客户端密钥（App password）
- 租户 ID（单租户）
@@ -256,10 +258,10 @@ tailscale funnel 3978
3. **Teams 应用清单**
- 包含一个 `bot` 条目，其中 `botId = <App ID>`。
- 范围：`personal`、`team`、`groupChat`。
- `supportsFiles: true`（个人范围文件处理所必需）。
- 添加 RSC 权限（见下方）。
- `supportsFiles: true`（个人范围文件处理所需）。
- 添加 RSC 权限（见下文）。
- 创建图标：`outline.png`（32x32）和 `color.png`（192x192）。
- 将三个文件打包在一起：`manifest.json`、`outline.png`、`color.png`。
- 将三个文件一起打包：`manifest.json`、`outline.png`、`color.png`。
4. **配置 OpenClaw**
@@ -275,29 +277,29 @@ tailscale funnel 3978
}
```
你也可以使用环境变量替代配置键：
你也可以使用环境变量代替配置键：
- `MSTEAMS_APP_ID`
- `MSTEAMS_APP_PASSWORD`
- `MSTEAMS_TENANT_ID`
5. **机器人端点**
- 将 Azure Bot 消息端点设置为：
- 将 Azure Bot Messaging Endpoint 设置为：
- `https://<host>:3978/api/messages`（或你选择的路径/端口）。
6. **运行 Gateway网关**
- 当插件已安装且 `msteams` 配置存在凭据时，Teams 渠道会自动启动。
6. **运行 Gateway 网关**
- 当插件已安装且 `msteams` 配置存在并有凭证时，Teams 渠道会自动启动。
## 历史上下文
- `channels.msteams.historyLimit` 控制多少条最近的频道/群组消息被包含在提示中。
- 回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。
- 私信历史可通过 `channels.msteams.dmHistoryLimit`（用户回合数）限制。按用户覆盖：`channels.msteams.dms["<user_id>"].historyLimit`。
- `channels.msteams.historyLimit` 控制将多少条最近的频道/群组消息包含到提示中。
- 回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。
- 私信历史可以通过 `channels.msteams.dmHistoryLimit`（用户轮次）限制。每用户覆盖：`channels.msteams.dms["<user_id>"].historyLimit`。
## 当前 Teams RSC 权限（清单）
以下是我们 Teams 应用清单中**现有的 resourceSpecific 权限**。它们仅在安装了应用的团队/聊天中适用。
这些是我们 Teams 应用清单中**现有的 resourceSpecific 权限**。它们仅适用于安装了应用的团队/聊天内部。
**频道（团队范围）：**
**对于频道（团队范围）：**
- `ChannelMessage.Read.Group`（Application）- 无需 @提及即可接收所有频道消息
- `ChannelMessage.Send.Group`（Application）
@@ -307,11 +309,11 @@ tailscale funnel 3978
- `TeamMember.Read.Group`（Application）
- `TeamSettings.Read.Group`（Application）
**群聊：**
**对于群聊：**
- `ChatMessage.Read.Chat`（Application）- 无需 @提及即可接收所有群聊消息
## 示例 Teams 清单（已脱敏）
## Teams 清单示例（已脱敏）
包含必需字段的最小有效示例。请替换 ID 和 URL。
@@ -361,30 +363,30 @@ tailscale funnel 3978
}
```
### 清单注意事项（必需字段）
### 清单注意事项（必填字段）
- `bots[].botId` **必须**与 Azure Bot App ID 匹配。
- `webApplicationInfo.id` **必须**与 Azure Bot App ID 匹配。
- `bots[].scopes` 必须包含你计划使用的范围（`personal`、`team`、`groupChat`）。
- `bots[].supportsFiles: true` 是个人范围文件处理所必需的。
- `authorization.permissions.resourceSpecific` 必须包含频道读取/发送权限（如果你需要频道流量）。
- `bots[].scopes` 必须包含你计划使用的界面（`personal`、`team`、`groupChat`）。
- `bots[].supportsFiles: true` 是个人范围文件处理所需的。
- `authorization.permissions.resourceSpecific` 如果你需要频道流量，必须包含频道读取/发送权限。
### 更新现有应用
要更新已安装的 Teams 应用（例如添加 RSC 权限）：
要更新已安装的 Teams 应用（例如，添加 RSC 权限）：
1. 使用新设置更新 `manifest.json`
2. **递增 `version` 字段**（例如 `1.0.0` → `1.1.0`）
1. 使用新设置更新你的 `manifest.json`
2. **增加 `version` 字段**（例如，`1.0.0` → `1.1.0`）
3. **重新打包**清单和图标（`manifest.json`、`outline.png`、`color.png`）
4. 上传新的 zip：
- **方案 A（Teams 管理中心）：** Teams 管理中心 → Teams apps → Manage apps → 找到你的应用 → Upload new version
- **方案 B（旁加载）：** 在 Teams 中 → Apps → Manage your apps → Upload a custom app
- **选项 A（Teams 管理中心）：** Teams 管理中心 → Teams apps → Manage apps → 找到你的应用 → Upload new version
- **选项 B（侧载）：** 在 Teams 中 → Apps → Manage your apps → Upload a custom app
5. **对于团队频道：** 在每个团队中重新安装应用以使新权限生效
6. **完全退出并重新启动 Teams**（不只是关闭窗口）以清除缓存的应用元数据
6. **完全退出并重新启动 Teams**（不仅仅是关闭窗口）以清除缓存的应用元数据
## 功能：仅 RSC vs Graph
## 功能：仅 RSC 与 Graph
### 仅使用 **Teams RSC**（已安装应用，无 Graph API 权限）
### 仅使用 **Teams RSC**（应用已安装，无 Graph API 权限）
可用：
@@ -394,108 +396,109 @@ tailscale funnel 3978
不可用：
- 频道/群组**图片或文件内容**（负载仅包含 HTML 占位符）。
- 频道/群组**图片或文件内容**（负载仅包含 HTML 存根）。
- 下载存储在 SharePoint/OneDrive 中的附件。
- 读取消息历史（超出实时 webhook 事件范围）。
- 读取消息历史（超出实时 webhook 事件）。
### 使用 **Teams RSC + Microsoft Graph Application 权限**
新增：
增加：
- 下载托管内容（粘贴到消息中的图片）。
- 下载存储在 SharePoint/OneDrive 中的文件附件。
- 通过 Graph 读取频道/聊天消息历史。
### RSC vs Graph API
### RSC 与 Graph API 对比
| 功能 | RSC 权限 | Graph API |
| -------------- | ------------------ | --------------------------- |
| **实时消息** | 是（通过 webhook） | 否（仅轮询） |
| **历史消息** | 否 | 是（可查询历史） |
| **设置复杂度** | 仅需应用清单 | 需要管理员同意 + token 流程 |
| **离线可用** | 否（必须运行中） | 是（可随时查询） |
| 功能 | RSC 权限 | Graph API |
| -------------- | ------------------ | ------------------------- |
| **实时消息** | 是（通过 webhook） | 否（仅轮询） |
| **历史消息** | 否 | 是（可查询历史） |
| **设置复杂度** | 仅应用清单 | 需要管理员同意 + 令牌流程 |
| **离线工作** | 否（必须运行） | 是（随时查询） |
**总结：** RSC 用于实时监听；Graph API 用于历史访问。要补上离线期间错过的消息，你需要具有 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。
**结论：** RSC 用于实时监听；Graph API 用于历史访问。要在离线时补上错过的消息，你需要带有 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。
## 启用 Graph 的媒体 + 历史（频道所必需）
## 启用 Graph 的媒体 + 历史（频道所需）
如果你需要**频道**中的图片/文件或想获取**消息历史**，必须启用 Microsoft Graph 权限并授予管理员同意。
如果你需要**频道**中的图片/文件或想要获取**消息历史**，你必须启用 Microsoft Graph 权限并授予管理员同意。
1. 在 Entra ID（Azure AD）**应用注册**中，添加 Microsoft Graph **Application 权限**：
1. 在 Entra ID（Azure AD）**App Registration** 中，添加 Microsoft Graph **Application 权限**：
- `ChannelMessage.Read.All`（频道附件 + 历史）
- `Chat.Read.All` 或 `ChatMessage.Read.All`（群聊）
2. 为租户**授予管理员同意**。
3. 递增 Teams 应用**清单版本**，重新上传，并在 **Teams 中重新安装应用**。
3. 提升 Teams 应用**清单版本**，重新上传，并**在 Teams 中重新安装应用**。
4. **完全退出并重新启动 Teams** 以清除缓存的应用元数据。
## 已知限制
### Webhook 超时
Teams 通过 HTTP webhook 投递消息。如果处理时间过长（例如 LLM 响应缓慢），你可能会看到：
Teams 通过 HTTP webhook 传递消息。如果处理时间过长（例如，LLM 响应缓慢），你可能会看到：
- Gateway网关超时
- Gateway 网关超时
- Teams 重试消息（导致重复）
- 回复丢失
- 丢失的回复
OpenClaw 通过快速返回并主动发送回复来处理此问题，但非常慢的响应仍可能导致问题。
OpenClaw 通过快速返回并主动发送回复来处理这个问题，但非常慢的响应仍可能导致问题。
### 格式
### 格式化
Teams markdown 比 Slack 或 Discord 更有限：
- 基本格式有效：**粗体**、_斜体_、`代码`、链接
- 复杂 markdown（表格、嵌套列表）可能无法正确渲染
- 支持 Adaptive Cards 用于投票和任意卡片发送（见下方）
- 基本格式化有效：**粗体**、_斜体_、`代码`、链接
- 复杂的 markdown（表格、嵌套列表）可能无法正确渲染
- 支持 Adaptive Cards 用于投票和任意卡片发送（见下文）
## 配置
关键设置（共享渠道模式请参见 `/gateway/configuration`）：
关键设置（共享渠道模式见 `/gateway/configuration`）：
- `channels.msteams.enabled`：启用/禁用渠道。
- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭据。
- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭证。
- `channels.msteams.webhook.port`（默认 `3978`）
- `channels.msteams.webhook.path`（默认 `/api/messages`）
- `channels.msteams.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）
- `channels.msteams.allowFrom`：私信允许列表（AAD 对象 ID、UPN 或显示名称）。当 Graph 访问可用时，向导在设置期间将名称解析为 ID。
- `channels.msteams.textChunkLimit`：出站文本分块大小。
- `channels.msteams.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
- `channels.msteams.chunkMode`：`length`（默认）或 `newline` 在长度分块之前按空行（段落边界）分割。
- `channels.msteams.mediaAllowHosts`：入站附件主机允许列表（默认为 Microsoft/Teams 域名）。
- `channels.msteams.mediaAuthAllowHosts`：在媒体重试时附加 Authorization 头的允许列表（默认为 Graph + Bot Framework 主机）。
- `channels.msteams.requireMention`：在频道/群组中需要 @提及（默认 true）。
- `channels.msteams.replyStyle`：`thread | top-level`（参见[回复样式：线程 vs 帖子](#回复样式线程-vs-帖子)）。
- `channels.msteams.teams.<teamId>.replyStyle`：按团队覆盖。
- `channels.msteams.teams.<teamId>.requireMention`：按团队覆盖。
- `channels.msteams.teams.<teamId>.tools`：按团队默认工具策略覆盖（`allow`/`deny`/`alsoAllow`），在频道覆盖缺失时使用。
- `channels.msteams.teams.<teamId>.toolsBySender`：按团队按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`：按频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`：按频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`：按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`：按频道按发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.sharePointSiteId`：用于群聊/频道文件上传的 SharePoint 站点 ID（参见[在群聊中发送文件](#在群聊中发送文件)）。
- `channels.msteams.replyStyle`：`thread | top-level`（见[回复样式](#reply-style-threads-vs-posts)）。
- `channels.msteams.teams.<teamId>.replyStyle`：每团队覆盖。
- `channels.msteams.teams.<teamId>.requireMention`：每团队覆盖。
- `channels.msteams.teams.<teamId>.tools`：当缺少频道覆盖时使用的默认每团队工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.toolsBySender`：默认每团队每发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`：每频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`：每频道覆盖。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`：每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`：每频道每发送者工具策略覆盖（支持 `"*"` 通配符）。
- `channels.msteams.sharePointSiteId`：用于群聊/频道文件上传的 SharePoint 站点 ID（见[在群聊中发送文件](#sending-files-in-group-chats)）。
## 路由与会话
## 路由和会话
- 会话键遵循标准智能体格式（参见 [/concepts/session](/concepts/session)）：
- 会话键遵循标准智能体格式（见 [/concepts/session](/concepts/session)）：
- 私信共享主会话（`agent:<agentId>:<mainKey>`）。
- 频道/群组消息使用会话 ID：
- `agent:<agentId>:msteams:channel:<conversationId>`
- `agent:<agentId>:msteams:group:<conversationId>`
## 回复样式：线程 vs 帖子
## 回复样式：话题 vs 帖子
Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式：
| 样式 | 描述 | 推荐的 `replyStyle` |
| ----------------------- | ------------------------------ | ------------------- |
| **Posts**（经典） | 消息显示为卡片，下方有线程回复 | `thread`（默认） |
| **Threads**（类 Slack） | 消息线性排列，更像 Slack | `top-level` |
| **Posts**（经典） | 消息显示为卡片，下方有话题回复 | `thread`（默认） |
| **Threads**（类 Slack） | 消息线性流动，更像 Slack | `top-level` |
**问题：** Teams API 不暴露频道使用哪种 UI 样式。如果你使用了错误的 `replyStyle`：
**问题：** Teams API 不暴露频道使用的 UI 样式。如果你使用错误的 `replyStyle`：
- 在 Threads 样式的频道中使用 `thread` → 回复嵌套显示不自然
- 在 Posts 样式的频道中使用 `top-level` → 回复显示为独立的顶级帖子而非在线程中
- 在 Threads 样式频道中使用 `thread` → 回复嵌套显示很别扭
- 在 Posts 样式频道中使用 `top-level` → 回复显示为单独的顶级帖子而不是在话题中
**解决方案：** 根据频道的设置方式按频道配置 `replyStyle`：
**解决方案：** 根据频道的设置方式为每个频道配置 `replyStyle`：
```json
{
@@ -514,41 +517,43 @@ Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式：
}
```
## 附件与图片
## 附件和图片
**当前限制：**
- **私信：** 图片和文件附件通过 Teams bot 文件 API 可用。
- **频道/群组：** 附件存储在 M365 存储（SharePoint/OneDrive）中。Webhook 负载仅包含 HTML 占位符，而非实际文件字节。**需要 Graph API 权限**才能下载频道附件。
- **私信：** 图片和文件附件通过 Teams bot file API 工作。
- **频道/群组：** 附件存储在 M365 存储（SharePoint/OneDrive）中。webhook 负载仅包含 HTML 存根，而非实际文件字节。**需要 Graph API 权限**才能下载频道附件。
没有 Graph 权限时，包含图片的频道消息将仅作为纯文本接收（机器人无法访问图片内容）。默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。通过 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 允许任何主机）。
没有 Graph 权限，带图片的频道消息将作为纯文本接收（机器人无法访问图片内容）。
默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。使用 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 允许任何主机）。
Authorization 头仅附加到 `channels.msteams.mediaAuthAllowHosts` 中的主机（默认为 Graph + Bot Framework 主机）。保持此列表严格（避免多租户后缀）。
## 在群聊中发送文件
机器人可以使用 FileConsentCard 流程在私信中发送文件（内置）。然而，**在群聊/频道中发送文件**需要额外设置：
机器人可以使用 FileConsentCard 流程在私信中发送文件（内置）。但是，**在群聊/频道中发送文件**需要额外设置：
| 场景 | 文件发送方式 | 所需设置 |
| -------------------- | --------------------------------------- | ------------------------------------ |
| **私信** | FileConsentCard → 用户接受 → 机器人上传 | 开箱即用 |
| **群聊/频道** | 上传到 SharePoint → 分享链接 | 需要 `sharePointSiteId` + Graph 权限 |
| **图片（任何场景）** | Base64 编码内联 | 开箱即用 |
| 上下文 | 文件发送方式 | 所需设置 |
| ---------------------- | --------------------------------------- | ------------------------------------ |
| **私信** | FileConsentCard → 用户接受 → 机器人上传 | 开箱即用 |
| **群聊/频道** | 上传到 SharePoint → 共享链接 | 需要 `sharePointSiteId` + Graph 权限 |
| **图片（任何上下文）** | Base64 编码内联 | 开箱即用 |
### 为什么群聊需要 SharePoint
机器人没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点对应用程序标识不可用）。要在群聊/频道中发送文件，机器人上传到 **SharePoint 站点**并创建共享链接。
机器人没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点对应用程序身份不起作用）。要在群聊/频道中发送文件，机器人上传到 **SharePoint 站点**并创建共享链接。
### 设置
1. 在 Entra ID（Azure AD）→ 应用注册中**添加 Graph API 权限**：
1. **在 Entra ID（Azure AD）→ App Registration 中添加 Graph API 权限**：
- `Sites.ReadWrite.All`（Application）- 上传文件到 SharePoint
- `Chat.Read.All`（Application）- 可选，启用按用户共享链接
- `Chat.Read.All`（Application）- 可选，启用每用户共享链接
2. 为租户**授予管理员同意**。
3. **获取你的 SharePoint 站点 ID：**
```bash
# 通过 Graph Explorer 或使用有效 token 的 curl：
# 通过 Graph Explorer 或带有效令牌的 curl：
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
@@ -575,38 +580,38 @@ Teams 最近在相同的底层数据模型上引入了两种频道 UI 样式：
| 权限 | 共享行为 |
| --------------------------------------- | ------------------------------------------ |
| 仅 `Sites.ReadWrite.All` | 组织范围共享链接（组织中的任何人都可访问） |
| `Sites.ReadWrite.All` + `Chat.Read.All` | 按用户共享链接（仅聊天成员可访问） |
| 仅 `Sites.ReadWrite.All` | 组织范围共享链接（组织中任何人都可以访问） |
| `Sites.ReadWrite.All` + `Chat.Read.All` | 每用户共享链接（仅聊天成员可以访问） |
按用户共享更安全，因为只有聊天参与者可以访问文件。如果缺少 `Chat.Read.All` 权限，机器人回退到组织范围共享。
每用户共享更安全，因为只有聊天参与者才能访问文件。如果缺少 `Chat.Read.All` 权限，机器人回退到组织范围共享。
### 回退行为
| 场景 | 结果 |
| --------------------------------------- | ------------------------------------------ |
| 群聊 + 文件 + 已配置 `sharePointSiteId` | 上传到 SharePoint，发送共享链接 |
| 群聊 + 文件 + 未配置 `sharePointSiteId` | 尝试 OneDrive 上传（可能失败），仅发送文本 |
| 个人聊天 + 文件 | FileConsentCard 流程（无需 SharePoint） |
| 任何场景 + 图片 | Base64 编码内联（无需 SharePoint） |
| 场景 | 结果 |
| --------------------------------------- | ------------------------------------------------ |
| 群聊 + 文件 + 已配置 `sharePointSiteId` | 上传到 SharePoint，发送共享链接 |
| 群聊 + 文件 + 无 `sharePointSiteId` | 尝试 OneDrive 上传（可能失败），仅发送文本 |
| 个人聊天 + 文件 | FileConsentCard 流程（无需 SharePoint 即可工作） |
| 任何上下文 + 图片 | Base64 编码内联（无需 SharePoint 即可工作） |
### 文件存储位置
上传的文件存储在已配置 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹。
上传的文件存储在配置的 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹中。
## 投票（Adaptive Cards）
OpenClaw 通过 Adaptive Cards 发送 Teams 投票（没有原生 Teams 投票 API）。
OpenClaw 将 Teams 投票作为 Adaptive Cards 发送（没有原生 Teams 投票 API）。
- CLI：`openclaw message poll --channel msteams --target conversation:<id> ...`
- 投票由 Gateway网关记录在 `~/.openclaw/msteams-polls.json` 中。
- Gateway网关必须保持在线以记录投票。
- 投票尚不会自动发布结果摘要（如需要请查看存储文件）。
- 投票由 Gateway 网关记录在 `~/.openclaw/msteams-polls.json` 中。
- Gateway 网关必须保持在线才能记录投票。
- 投票尚不自动发布结果摘要（如需要请检查存储文件）。
## Adaptive Cards（任意）
使用 `message` 工具或 CLI 向 Teams 用户或会话发送任意 Adaptive Card JSON。
`card` 参数接受 Adaptive Card JSON 对象。提供 `card` 时，消息文本是可选的。
`card` 参数接受 Adaptive Card JSON 对象。当提供 `card` 时，消息文本是可选的。
**智能体工具：**
@@ -631,11 +636,11 @@ openclaw message send --channel msteams \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
```
卡片 schema 和示例请参见 [Adaptive Cards 文档](https://adaptivecards.io/)。目标格式详情请参见下方[目标格式](#目标格式)。
参见 [Adaptive Cards 文档](https://adaptivecards.io/)了解卡片模式和示例。目标格式详情见下方[目标格式](#target-formats)。
## 目标格式
Microsoft Teams 目标使用前缀区分用户和会话：
MSTeams 目标使用前缀来区分用户和会话：
| 目标类型 | 格式 | 示例 |
| ----------------- | -------------------------------- | ------------------------------------------------- |
@@ -685,12 +690,12 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread.
}
```
注意：不带 `user:` 前缀时，名称默认解析为群组/团队。通过显示名称定位人员时请始终使用 `user:`。
注意：没有 `user:` 前缀时，名称默认解析为群组/团队。按显示名称定位人员时始终使用 `user:`。
## 主动消息
- 主动消息仅在用户**已交互后**才可能，因为我们在那个时候存储会话引用。
- `dmPolicy` 和允许列表门控请参见 `/gateway/configuration`。
- 主动消息仅在用户交互**之后**才可能，因为我们在那时存储会话引用。
- 有关 `dmPolicy` 和允许列表控制，请参见 `/gateway/configuration`。
## 团队和频道 ID（常见陷阱）
@@ -714,8 +719,8 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr
**用于配置：**
- 团队 ID = `/team/` 后的路径段（URL 解码后，例如 `19:Bk4j...@thread.tacv2`）
- 频道 ID = `/channel/` 后的路径段（URL 解码后）
- 团队 ID = `/team/` 后的路径段（URL 解码，例如 `19:Bk4j...@thread.tacv2`）
- 频道 ID = `/channel/` 后的路径段（URL 解码）
- **忽略** `groupId` 查询参数
## 私有频道
@@ -725,12 +730,12 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr
| 功能 | 标准频道 | 私有频道 |
| ------------------- | -------- | ---------------- |
| 机器人安装 | 是 | 有限 |
| 实时消息（webhook） | 是 | 可能不可用 |
| 实时消息（webhook） | 是 | 可能不工作 |
| RSC 权限 | 是 | 行为可能不同 |
| @提及 | 是 | 如果机器人可访问 |
| Graph API 历史 | 是 | 是（需要权限） |
| Graph API 历史 | 是 | 是（有权限） |
**私有频道不可用时的变通方案：**
**如果私有频道不工作的变通方法：**
1. 使用标准频道进行机器人交互
2. 使用私信 - 用户始终可以直接给机器人发消息
@@ -740,31 +745,31 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr
### 常见问题
- **频道中图片不显示：** Graph 权限或管理员同意缺失。重新安装 Teams 应用并完全退出/重新打开 Teams。
- **频道中没有响应：** 默认需要提及；设置 `channels.msteams.requireMention=false` 或按团队/频道配置。
- **版本不匹配（Teams 仍显示旧清单）：** 移除并重新添加应用，完全退出 Teams 以刷新。
- **Webhook 返回 401 Unauthorized：** 在没有 Azure JWT 的情况下手动测试时这是预期的 - 表示端点可达但认证失败。使用 Azure Web Chat 进行正确测试。
- **频道中图片不显示：** 缺少 Graph 权限或管理员同意。重新安装 Teams 应用并完全退出/重新打开 Teams。
- **频道中无响应：** 默认需要提及；设置 `channels.msteams.requireMention=false` 或按团队/频道配置。
- **版本不匹配（Teams 仍显示旧清单）：** 移除 + 重新添加应用并完全退出 Teams 以刷新。
- **来自 webhook 的 401 Unauthorized：** 在没有 Azure JWT 的情况下手动测试时属于预期情况 - 意味着端点可达但认证失败。使用 Azure Web Chat 正确测试。
### 清单上传错误
- **"Icon file cannot be empty"：** 清单引用了 0 字节的图标文件。创建有效的 PNG 图标（`outline.png` 32x32，`color.png` 192x192）。
- **"webApplicationInfo.Id already in use"：** 应用仍安装在其他团队/聊天中。先找到并卸载它，或等待 5-10 分钟传播。
- **上传时显示"Something went wrong"：** 改为通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 标签页，检查响应体中的实际错误。
- **旁加载失败：** 尝试"Upload an app to your org's app catalog"而非"Upload a custom app" - 这通常可以绕过旁加载限制。
- **"Icon file cannot be empty"：** 清单引用的图标文件为 0 字节。创建有效的 PNG 图标（`outline.png` 为 32x32，`color.png` 为 192x192）。
- **"webApplicationInfo.Id already in use"：** 应用仍安装在另一个团队/聊天中。先找到并卸载它，或等待 5-10 分钟让其传播。
- **上传时"Something went wrong"：** 改为通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 选项卡，检查响应正文中的实际错误。
- **侧载失败：** 尝试"Upload an app to your org's app catalog"而不是"Upload a custom app" - 这通常可以绕过侧载限制。
### RSC 权限不生效
### RSC 权限不工作
1. 验证 `webApplicationInfo.id` 与你的机器人 App ID 完全匹配
2. 重新上传应用并在团队/聊天中重新安装
3. 检查你的组织管理员是否阻止了 RSC 权限
4. 确认你使用了正确的范围：`ChannelMessage.Read.Group` 用于团队，`ChatMessage.Read.Chat` 用于群聊
4. 确认你使用的是正确的范围：团队使用 `ChannelMessage.Read.Group`，群聊使用 `ChatMessage.Read.Chat`
## 参考
## 参考资料
- [创建 Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - Azure Bot 设置指南
- [Teams 开发者门户](https://dev.teams.microsoft.com/apps) - 创建/管理 Teams 应用
- [Teams 应用清单 schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
- [Teams 应用清单模式](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
- [使用 RSC 接收频道消息](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
- [RSC 权限参考](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
- [Teams bot 文件处理](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（频道/群组需要 Graph）
- [Teams 机器人文件处理](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（频道/群组需要 Graph）
- [主动消息](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
docs/zh-CN/channels/nextcloud-talk.md
+33 -32
View File
@@ -1,53 +1,54 @@
---
read_when:
- 开发 Nextcloud Talk 渠道功能
- 开发 Nextcloud Talk 渠道功能时
summary: Nextcloud Talk 支持状态、功能和配置
title: Nextcloud Talk
x-i18n:
generated_at: "2026-02-01T19:26:32Z"
generated_at: "2026-02-03T10:04:00Z"
model: claude-opus-4-5
provider: pi
source_hash: 21b7b9756c4356a76dc0f14c10e44ed74a284cf3badf87e2df75eb88d8a90c31
source_path: channels/nextcloud-talk.md
workflow: 14
workflow: 15
---
# Nextcloud Talk（插件）
状态：通过插件支持（webhook 机器人）。支持私信、房间、回应和 markdown 消息。
状态：通过插件支持（webhook 机器人）。支持私信、房间、表情回应和 Markdown 消息。
## 需要插件
Nextcloud Talk 作为插件发布，不包含在核心安装中。
Nextcloud Talk 以插件形式提供，不包含在核心安装包中。
通过 CLI 安装（npm 注册表）：
通过 CLI 安装（npm 仓库）：
```bash
openclaw plugins install @openclaw/nextcloud-talk
```
本地检出（从 git 仓库运行时）：
本地检出安装（从 git 仓库运行时）：
```bash
openclaw plugins install ./extensions/nextcloud-talk
```
如果你在配置/新手引导期间选择了 Nextcloud Talk 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
如果你在配置/新手引导过程中选择了 Nextcloud Talk，并且检测到 git 检出，
OpenClaw 将自动提供本地安装路径。
详情：[插件](/plugin)
## 快速设置（新手）
1. 安装 Nextcloud Talk 插件。
2. 在你的 Nextcloud 服务器上创建一个机器人：
2. 在你的 Nextcloud 服务器上创建机器人：
```bash
./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
```
3. 在目标房间设置中启用该机器人。
3. 在目标房间设置中启用机器人。
4. 配置 OpenClaw：
- 配置：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
- 配置项：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
- 或环境变量：`NEXTCLOUD_TALK_BOT_SECRET`（仅默认账户）
5. 重启 Gateway网关（或完成新手引导）。
5. 重启 Gateway 网关（或完成新手引导）。
最小配置：
@@ -66,23 +67,23 @@ openclaw plugins install ./extensions/nextcloud-talk
## 注意事项
- 机器人无法主动发起私信。用户必须先给机器人发消息。
- Webhook URL 必须能被 Gateway网关访问；如果在代理后面，请设置 `webhookPublicUrl`。
- 机器人无法主动发起私信。用户必须先向机器人发送消息。
- Webhook URL 必须可被 Gateway 网关访问；如果在代理后面，请设置 `webhookPublicUrl`。
- 机器人 API 不支持媒体上传；媒体以 URL 形式发送。
- Webhook 负载不区分私信和房间；设置 `apiUser` + `apiPassword` 以启用房间类型查询（否则私信会被视为房间）。
- Webhook 载荷无法区分私信和房间；设置 `apiUser` + `apiPassword` 以启用房间类型查询（否则私信将被视为房间）。
## 访问控制（私信）
- 默认：`channels.nextcloud-talk.dmPolicy = "pairing"`。未知发送者会收到配对码。
- 通过以下方式批准：
- 默认：`channels.nextcloud-talk.dmPolicy = "pairing"`。未知发送者将收到配对码。
- 批准方式：
- `openclaw pairing list nextcloud-talk`
- `openclaw pairing approve nextcloud-talk <CODE>`
- 公开私信：`channels.nextcloud-talk.dmPolicy="open"` 加上 `channels.nextcloud-talk.allowFrom=["*"]`。
## 房间（群组）
- 默认：`channels.nextcloud-talk.groupPolicy = "allowlist"`（提及门控）。
- 使用 `channels.nextcloud-talk.rooms` 允许列表中的房间：
- 默认：`channels.nextcloud-talk.groupPolicy = "allowlist"`（需要提及触发）。
- 使用 `channels.nextcloud-talk.rooms` 设置房间白名单：
```json5
{
@@ -96,17 +97,17 @@ openclaw plugins install ./extensions/nextcloud-talk
}
```
- 要不允许任何房间，保持允许列表为空或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。
- 如需禁止所有房间，保持白名单为空或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。
## 功能
## 功能支持
| 功能 | 状态 |
| -------- | ------ |
| 私信 | 支持 |
| 房间 | 支持 |
| 线程 | 不支持 |
| 话题 | 不支持 |
| 媒体 | 仅 URL |
| 回应 | 支持 |
| 表情回应 | 支持 |
| 原生命令 | 不支持 |
## 配置参考（Nextcloud Talk）
@@ -127,15 +128,15 @@ openclaw plugins install ./extensions/nextcloud-talk
- `channels.nextcloud-talk.webhookPath`：webhook 路径（默认：/nextcloud-talk-webhook）。
- `channels.nextcloud-talk.webhookPublicUrl`：外部可达的 webhook URL。
- `channels.nextcloud-talk.dmPolicy`：`pairing | allowlist | open | disabled`。
- `channels.nextcloud-talk.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。
- `channels.nextcloud-talk.allowFrom`：私信白名单（用户 ID）。`open` 需要 `"*"`。
- `channels.nextcloud-talk.groupPolicy`：`allowlist | open | disabled`。
- `channels.nextcloud-talk.groupAllowFrom`：群组允许列表（用户 ID）。
- `channels.nextcloud-talk.rooms`：按房间设置和允许列表。
- `channels.nextcloud-talk.historyLimit`：群组历史限制（0 禁用）。
- `channels.nextcloud-talk.dmHistoryLimit`：私信历史限制（0 禁用）。
- `channels.nextcloud-talk.dms`：按私信覆盖（historyLimit）。
- `channels.nextcloud-talk.textChunkLimit`：出站文本分块大小（字符）。
- `channels.nextcloud-talk.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
- `channels.nextcloud-talk.groupAllowFrom`：群组白名单（用户 ID）。
- `channels.nextcloud-talk.rooms`：每个房间的设置和白名单。
- `channels.nextcloud-talk.historyLimit`：群组历史记录限制（0 表示禁用）。
- `channels.nextcloud-talk.dmHistoryLimit`：私信历史记录限制（0 表示禁用）。
- `channels.nextcloud-talk.dms`：每个私信的覆盖设置（historyLimit）。
- `channels.nextcloud-talk.textChunkLimit`：出站文本分块大小（字符数）。
- `channels.nextcloud-talk.chunkMode`：`length`（默认）或 `newline`，在长度分块前按空行（段落边界）分割。
- `channels.nextcloud-talk.blockStreaming`：禁用此渠道的分块流式传输。
- `channels.nextcloud-talk.blockStreamingCoalesce`：分块流式传输合并调优。
- `channels.nextcloud-talk.mediaMaxMb`：入站媒体上限（MB）。
- `channels.nextcloud-talk.mediaMaxMb`：入站媒体大小上限（MB）。
docs/zh-CN/channels/nostr.md
+36 -36
View File
@@ -1,37 +1,37 @@
---
read_when:
- 你想让 OpenClaw 通过 Nostr 接收私信
- 你希望 OpenClaw 通过 Nostr 接收私信
- 你正在设置去中心化消息
summary: 通过 NIP-04 加密消息的 Nostr 私信渠道
title: Nostr
x-i18n:
generated_at: "2026-02-01T19:26:55Z"
generated_at: "2026-02-03T07:44:13Z"
model: claude-opus-4-5
provider: pi
source_hash: 6b9fe4c74bf5e7c0f59bbaa129ec5270fd29a248551a8a9a7dde6cff8fb46111
source_path: channels/nostr.md
workflow: 14
workflow: 15
---
# Nostr
**状态：** 可选插件（默认禁用）。
Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（私信）。
Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DMs）。
## 安装（按需）
### 新手引导（推荐）
- 新手引导向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选的渠道插件。
- 选择 Nostr 时会提示你按需安装插件。
- 选择 Nostr 会提示你按需安装插件。
安装默认行为：
安装默认值：
- **开发渠道 + 可用 git 检出：** 使用本地插件路径。
- **稳定版/测试版：** 从 npm 下载。
- **Dev 渠道 + git checkout 可用：** 使用本地插件路径。
- **Stable/Beta：** 从 npm 下载。
你始终可以在提示中覆盖此选择。
你可以随时在提示中覆盖选择。
### 手动安装
@@ -39,13 +39,13 @@ Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够
openclaw plugins install @openclaw/nostr
```
使用本地检出（开发工作流）：
使用本地 checkout（开发工作流）：
```bash
openclaw plugins install --link <path-to-openclaw>/extensions/nostr
```
安装或启用插件后请重启 Gateway网关。
安装或启用插件后重启 Gateway 网关。
## 快速设置
@@ -74,7 +74,7 @@ nak key generate
export NOSTR_PRIVATE_KEY="nsec1..."
```
4. 重启 Gateway网关。
4. 重启 Gateway 网关。
## 配置参考
@@ -90,7 +90,7 @@ export NOSTR_PRIVATE_KEY="nsec1..."
## 个人资料元数据
个人资料数据作为 NIP-01 `kind:0` 事件发布。你可以从控制 UI（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。
个人资料数据作为 NIP-01 `kind:0` 事件发布。你可以从控制界面（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。
示例：
@@ -124,9 +124,9 @@ export NOSTR_PRIVATE_KEY="nsec1..."
### 私信策略
- **pairing**（默认）：未知发送者会收到配对码。
- **allowlist**：只有 `allowFrom` 中的公钥可以发私信。
- **open**：公开入站私信（需要 `allowFrom: ["*"]`）。
- **disabled**：忽略入站私信。
- **allowlist**：只有 `allowFrom` 中的公钥可以发送私信。
- **open**：公开接收私信（需要 `allowFrom: ["*"]`）。
- **disabled**：忽略接收的私信。
### 允许列表示例
@@ -164,20 +164,20 @@ export NOSTR_PRIVATE_KEY="nsec1..."
}
```
建议：
提示：
- 使用 2-3 个中继以实现冗余。
- 避免使用过多中继（延迟、重复）。
- 付费中继可以提高可靠性。
- 本地中继适用于测试（`ws://localhost:7777`）。
- 本地中继适合测试（`ws://localhost:7777`）。
## 协议支持
| NIP | 状态 | 描述 |
| ------ | ------ | ----------------------------- |
| NIP-01 | 支持 | 基本事件格式 + 个人资料元数据 |
| NIP-04 | 支持 | 加密私信（`kind:4`） |
| NIP-17 | 计划中 | Gift-wrapped 私信 |
| NIP-01 | 已支持 | 基本事件格式 + 个人资料元数据 |
| NIP-04 | 已支持 | 加密私信（`kind:4`） |
| NIP-17 | 计划中 | 礼物包装私信 |
| NIP-44 | 计划中 | 版本化加密 |
## 测试
@@ -203,38 +203,38 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry
### 手动测试
1. 从日志中记下机器人公钥（npub）。
2. 打开一个 Nostr 客户端（Damus、Amethyst 等）。
3. 私信机器人公钥。
4. 验证回复。
2. 打开 Nostr 客户端（Damus、Amethyst 等）。
3. 向机器人公钥发送私信。
4. 验证响应。
## 故障排除
### 无法收到消息
### 未收到消息
- 验证私钥是否有效。
- 确保中继 URL 可达并使用 `wss://`（本地使用 `ws://`）。
- 确认 `enabled` 未设为 `false`。
- 检查 Gateway网关日志中的中继连接错误。
- 确保中继 URL 可访问并使用 `wss://`（本地使用 `ws://`）。
- 确认 `enabled` 不是 `false`。
- 检查 Gateway 网关日志中的中继连接错误。
### 无法发送回复
### 未发送响应
- 检查中继是否接受写入。
- 验证出站连接。
- 注意中继速率限制。
### 重复回复
### 重复响应
- 使用多个中继时属于预期行为。
- 消息按事件 ID 去重；只有第一次投递会触发回复。
- 使用多个中继时属于正常现象。
- 消息按事件 ID 去重；只有首次投递会触发响应。
## 安全
- 绝不提交私钥。
- 切勿提交私钥。
- 使用环境变量存储密钥。
- 生产机器人请考虑使用 `allowlist`。
- 生产环境机器人考虑使用 `allowlist`。
## 限制（MVP）
- 仅支持私信（无群聊）。
- 仅支持私信（不支持群聊）。
- 不支持媒体附件。
- 仅支持 NIP-04（计划支持 NIP-17 gift-wrap）。
- 仅支持 NIP-04（计划支持 NIP-17 礼物包装）。
docs/zh-CN/channels/signal.md
+46 -46
View File
@@ -1,29 +1,29 @@
---
read_when:
- 设置 Signal 支持
- 调试 Signal 收发
summary: 通过 signal-cli（JSON-RPC + SSE）实现 Signal 支持、设置和号码模型
- 调试 Signal 发送/接收
summary: 通过 signal-cli（JSON-RPC + SSE）支持 Signal，设置和号码模型
title: Signal
x-i18n:
generated_at: "2026-02-01T19:27:25Z"
generated_at: "2026-02-03T07:44:15Z"
model: claude-opus-4-5
provider: pi
source_hash: ca4de8b3685017f54a959e3e2699357ab40b3e4e68574bd7fb5739e4679e7d8a
source_path: channels/signal.md
workflow: 14
workflow: 15
---
# Signal（signal-cli）
# Signal (signal-cli)
状态：外部 CLI 集成。Gateway网关通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。
状态：外部 CLI 集成。Gateway 网关通过 HTTP JSON-RPC + SSE 与 `signal-cli` 通信。
## 快速设置（新手）
## 快速设置（初学者）
1. 为机器人使用一个**单独的 Signal 号码**（推荐）。
1. 为 bot 使用**单独的 Signal 号码**（推荐）。
2. 安装 `signal-cli`（需要 Java）。
3. 链接机器人设备并启动守护进程：
3. 链接 bot 设备并启动守护进程：
- `signal-cli link -n "OpenClaw"`
4. 配置 OpenClaw 并启动 Gateway网关。
4. 配置 OpenClaw 并启动 Gateway 网关。
最小配置：
@@ -44,14 +44,14 @@ x-i18n:
## 它是什么
- 通过 `signal-cli` 的 Signal 渠道（非嵌入式 libsignal）。
- 确定性路由：回复始终发回 Signal。
- 确定性路由：回复始终返回到 Signal。
- 私信共享智能体的主会话；群组是隔离的（`agent:<agentId>:signal:group:<groupId>`）。
## 配置写入
默认情况下，Signal 允许通过 `/config set|unset` 触发的配置更新写入（需要 `commands.config: true`）。
默认情况下，Signal 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。
通过以下方式禁用：
禁用方式：
```json5
{
@@ -61,16 +61,16 @@ x-i18n:
## 号码模型（重要）
- Gateway网关连接到一个 **Signal 设备**（`signal-cli` 账户）。
- 如果你在**个人 Signal 账户**上运行机器人，它会忽略你自己的消息（循环保护）。
- 要实现"我给机器人发消息它回复我"，请使用一个**单独的机器人号码**。
- Gateway 网关连接到一个 **Signal 设备**（`signal-cli` 账户）。
- 如果你在**个人 Signal 账户**上运行 bot，它会忽略你自己的消息（循环保护）。
- 要实现"我发消息给 bot 然后它回复"，请使用**单独的 bot 号码**。
## 设置（快速路径）
1. 安装 `signal-cli`（需要 Java）。
2. 链接机器人账户：
2. 链接 bot 账户：
- `signal-cli link -n "OpenClaw"` 然后在 Signal 中扫描二维码。
3. 配置 Signal 并启动 Gateway网关。
3. 配置 Signal 并启动 Gateway 网关。
示例：
@@ -88,11 +88,11 @@ x-i18n:
}
```
多账户支持：使用 `channels.signal.accounts`，每个账户配置独立选项和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。
多账户支持：使用 `channels.signal.accounts` 配置每个账户及可选的 `name`。共享模式请参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。
## 外部守护进程模式（httpUrl）
如果你想自行管理 `signal-cli`（JVM 冷启动慢、容器初始化或共享 CPU），可以单独运行守护进程并将 OpenClaw 指向它：
如果你想自己管理 `signal-cli`（JVM 冷启动慢、容器初始化或共享 CPU），请单独运行守护进程并将 OpenClaw 指向它：
```json5
{
@@ -105,19 +105,19 @@ x-i18n:
}
```
这会跳过 OpenClaw 内部的自动启动和启动等待。当自动启动较慢时，请设置 `channels.signal.startupTimeoutMs`。
这会跳过自动启动和 OpenClaw 内部的启动等待。对于自动启动时的慢启动，请设置 `channels.signal.startupTimeoutMs`。
## 访问控制（私信 + 群组）
私信：
- 默认：`channels.signal.dmPolicy = "pairing"`。
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
- 未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- `openclaw pairing list signal`
- `openclaw pairing approve signal <CODE>`
- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/start/pairing)
- 仅 UUID 的发送者（来自 `sourceUuid`）以 `uuid:<id>` 形式存储在 `channels.signal.allowFrom` 中。
- 仅有 UUID 的发送者（来自 `sourceUuid`）在 `channels.signal.allowFrom` 中存储为 `uuid:<id>`。
群组：
@@ -126,31 +126,31 @@ x-i18n:
## 工作原理（行为）
- `signal-cli` 作为守护进程运行；Gateway网关通过 SSE 读取事件。
- 入站消息被标准化为共享的渠道信封。
- 回复始终路由回同一个号码或群组。
- `signal-cli` 作为守护进程运行；Gateway 网关通过 SSE 读取事件。
- 入站消息被规范化为共享渠道信封。
- 回复始终路由回同一号码或群组。
## 媒体 + 限制
- 出站文本按 `channels.signal.textChunkLimit` 分块（默认 4000）。
- 可选的换行分块：设置 `channels.signal.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。
- 可选换行分块：设置 `channels.signal.chunkMode="newline"` 在长度分块前按空行（段落边界）分割。
- 支持附件（从 `signal-cli` 获取 base64）。
- 默认媒体上限：`channels.signal.mediaMaxMb`（默认 8）。
- 使用 `channels.signal.ignoreAttachments` 跳过媒体下载。
- 群组历史上下文使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。
- 使用 `channels.signal.ignoreAttachments` 跳过下载媒体。
- 群组历史上下文使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。
## 输入指示 + 已读回执
## 输入指示器 + 已读回执
- **输入指示**：OpenClaw 通过 `signal-cli sendTyping` 发送输入信号，并在回复运行期间刷新。
- **输入指示器**：OpenClaw 通过 `signal-cli sendTyping` 发送输入信号，并在回复运行时刷新它们。
- **已读回执**：当 `channels.signal.sendReadReceipts` 为 true 时，OpenClaw 为允许的私信转发已读回执。
- signal-cli 不暴露群组的已读回执。
- Signal-cli 不暴露群组的已读回执。
## 回应（message 工具）
## 表情回应（message 工具）
- 使用 `message action=react` 配合 `channel=signal`。
- 目标：发送者 E.164 或 UUID（使用配对输出中的 `uuid:<id>`；裸 UUID 也可以）。
- `messageId` 是你要回应的消息的 Signal 时间戳。
- 群组回应需要 `targetAuthor` 或 `targetAuthorUuid`。
- 群组表情回应需要 `targetAuthor` 或 `targetAuthorUuid`。
示例：
@@ -162,13 +162,13 @@ message action=react channel=signal target=signal:group:<groupId> targetAuthor=u
配置：
- `channels.signal.actions.reactions`：启用/禁用回应操作（默认 true）。
- `channels.signal.actions.reactions`：启用/禁用表情回应操作（默认 true）。
- `channels.signal.reactionLevel`：`off | ack | minimal | extensive`。
- `off`/`ack` 禁用智能体回应（message 工具 `react` 会报错）。
- `minimal`/`extensive` 启用智能体回应并设置引导级别。
- 按账户覆盖：`channels.signal.accounts.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
- `off`/`ack` 禁用智能体表情回应（message 工具 `react` 会报错）。
- `minimal`/`extensive` 启用智能体表情回应并设置指导级别。
- 每账户覆盖：`channels.signal.accounts.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
## 投递目标（CLI/定时任务）
## 投递目标（CLI/cron）
- 私信：`signal:+15551234567`（或纯 E.164）。
- UUID 私信：`uuid:<id>`（或裸 UUID）。
@@ -182,24 +182,24 @@ message action=react channel=signal target=signal:group:<groupId> targetAuthor=u
提供商选项：
- `channels.signal.enabled`：启用/禁用渠道启动。
- `channels.signal.account`：机器人账户的 E.164。
- `channels.signal.account`：bot 账户的 E.164。
- `channels.signal.cliPath`：`signal-cli` 的路径。
- `channels.signal.httpUrl`：完整守护进程 URL（覆盖 host/port）。
- `channels.signal.httpHost`、`channels.signal.httpPort`：守护进程绑定（默认 127.0.0.1:8080）。
- `channels.signal.autoStart`：自动启动守护进程（未设置 `httpUrl` 时默认 true）。
- `channels.signal.startupTimeoutMs`：启动等待超时，单位毫秒（上限 120000）。
- `channels.signal.autoStart`：自动启动守护进程（如果未设置 `httpUrl` 则默认 true）。
- `channels.signal.startupTimeoutMs`：启动等待超时（毫秒）（上限 120000）。
- `channels.signal.receiveMode`：`on-start | manual`。
- `channels.signal.ignoreAttachments`：跳过附件下载。
- `channels.signal.ignoreStories`：忽略来自守护进程的动态。
- `channels.signal.sendReadReceipts`：转发已读回执。
- `channels.signal.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.signal.allowFrom`：私信允许列表（E.164 或 `uuid:<id>`）。`open` 需要 `"*"`。Signal 没有用户名；使用电话/UUID 标识。
- `channels.signal.allowFrom`：私信允许列表（E.164 或 `uuid:<id>`）。`open` 需要 `"*"`。Signal 没有用户名；使用电话/UUID id。
- `channels.signal.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。
- `channels.signal.groupAllowFrom`：群组发送者允许列表。
- `channels.signal.historyLimit`：包含为上下文的最大群组消息数（0 禁用）。
- `channels.signal.dmHistoryLimit`：私信历史限制（用户回合数）。按用户覆盖：`channels.signal.dms["<phone_or_uuid>"].historyLimit`。
- `channels.signal.historyLimit`：作为上下文包含的最大群组消息数（0 禁用）。
- `channels.signal.dmHistoryLimit`：私信历史限制（用户轮次）。每用户覆盖：`channels.signal.dms["<phone_or_uuid>"].historyLimit`。
- `channels.signal.textChunkLimit`：出站分块大小（字符）。
- `channels.signal.chunkMode`：`length`（默认）或 `newline`，在按长度分块之前按空行（段落边界）分割。
- `channels.signal.chunkMode`：`length`（默认）或 `newline` 在长度分块前按空行（段落边界）分割。
- `channels.signal.mediaMaxMb`：入站/出站媒体上限（MB）。
相关全局选项：
docs/zh-CN/channels/slack.md
+104 -103
View File
@@ -1,14 +1,14 @@
---
read_when: 设置 Slack 或调试 Slack Socket/HTTP 模式
summary: Slack 的 Socket 或 HTTP webhook 模式设置
read_when: Setting up Slack or debugging Slack socket/HTTP mode
summary: Slack 的 socket 或 HTTP webhook 模式设置
title: Slack
x-i18n:
generated_at: "2026-02-01T19:29:15Z"
generated_at: "2026-02-03T07:45:49Z"
model: claude-opus-4-5
provider: pi
source_hash: 703b4b4333bebfef26b64710ba452bdfc3e7d2115048d4e552e8659425b3609b
source_path: channels/slack.md
workflow: 14
workflow: 15
---
# Slack
@@ -19,7 +19,7 @@ x-i18n:
1. 创建一个 Slack 应用并启用 **Socket Mode**。
2. 创建一个 **App Token**（`xapp-...`）和 **Bot Token**（`xoxb-...`）。
3. 为 OpenClaw 设置 token 并启动 Gateway网关。
3. 为 OpenClaw 设置令牌并启动 Gateway 网关。
最小配置：
@@ -37,10 +37,10 @@ x-i18n:
### 设置
1. 在 https://api.slack.com/apps 创建 Slack 应用（从头开始）。
2. **Socket Mode** → 开启。然后进入 **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes**，使用范围 `connections:write`。复制 **App Token**（`xapp-...`）。
3. **OAuth & Permissions** → 添加 bot token 范围（使用下方清单）。点击 **Install to Workspace**。复制 **Bot User OAuth Token**（`xoxb-...`）。
4. 可选：**OAuth & Permissions** → 添加 **User Token Scopes**（参见下方只读列表）。重新安装应用并复制 **User OAuth Token**（`xoxp-...`）。
1. 在 https://api.slack.com/apps 创建一个 Slack 应用（从头开始）。
2. **Socket Mode** → 开启。然后前往 **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes**，添加 `connections:write` 权限范围。复制 **App Token**（`xapp-...`）。
3. **OAuth & Permissions** → 添加 bot token 权限范围（使用下面的 manifest）。点击 **Install to Workspace**。复制 **Bot User OAuth Token**（`xoxb-...`）。
4. 可选：**OAuth & Permissions** → 添加 **User Token Scopes**（参见下面的只读列表）。重新安装应用并复制 **User OAuth Token**（`xoxp-...`）。
5. **Event Subscriptions** → 启用事件并订阅：
- `message.*`（包括编辑/删除/线程广播）
- `app_mention`
@@ -49,16 +49,16 @@ x-i18n:
- `channel_rename`
- `pin_added`、`pin_removed`
6. 邀请机器人加入你希望它读取的频道。
7. Slash Commands → 如果你使用 `channels.slack.slashCommand`，创建 `/openclaw`。如果你启用原生命令，为每个内置命令添加一个斜杠命令（名称与 `/help` 列表相同）。Slack 的原生命令默认关闭，除非你设置 `channels.slack.commands.native: true`（全局 `commands.native` 为 `"auto"`，Slack 下默认关闭）。
8. App Home → 启用 **Messages Tab** 以便用户可以给机器人发私信。
7. Slash Commands → 如果你使用 `channels.slack.slashCommand`，创建 `/openclaw`。如果启用原生命令，为每个内置命令添加一个斜杠命令（名称与 `/help` 相同）。除非你设置 `channels.slack.commands.native: true`，否则 Slack 默认关闭原生命令（全局 `commands.native` 是 `"auto"`，对 Slack 保持关闭）。
8. App Home → 启用 **Messages Tab** 以便用户可以私信机器人。
使用下方清单以保持范围和事件同步。
使用下面的 manifest 以保持权限范围和事件同步。
多账户支持：使用 `channels.slack.accounts`，每个账户配置独立 token 和可选的 `name`。共享模式请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)。
多账户支持：使用 `channels.slack.accounts` 配置每个账户的令牌和可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解共享模式。
### OpenClaw 配置（最小）
通过环境变量设置 token（推荐）：
通过环境变量设置令牌（推荐）：
- `SLACK_APP_TOKEN=xapp-...`
- `SLACK_BOT_TOKEN=xoxb-...`
@@ -77,13 +77,13 @@ x-i18n:
}
```
### 用户 token（可选）
### 用户令牌（可选）
OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历史记录、置顶、回应、表情、成员信息）。默认保持只读：有用户 token 时读取操作优先使用它，写入仍使用 bot token，除非你明确选择。即使设置了 `userTokenReadOnly: false`，当 bot token 可用时写入操作仍优先使用它。
OpenClaw 可以使用 Slack 用户令牌（`xoxp-...`）进行读取操作（历史记录、置顶、表情回应、表情符号、成员信息）。默认情况下保持只读：当存在用户令牌时，读取优先使用用户令牌，而写入仍然使用 bot 令牌，除非你明确选择加入。即使设置了 `userTokenReadOnly: false`，当 bot 令牌可用时，写入仍然优先使用 bot 令牌。
用户 token 在配置文件中设置（不支持环境变量）。多账户时设置 `channels.slack.accounts.<id>.userToken`。
用户令牌在配置文件中配置（不支持环境变量）。对于多账户，设置 `channels.slack.accounts.<id>.userToken`。
同时使用 bot + app + user token 的示例：
包含 bot + app + 用户令牌的示例：
```json5
{
@@ -98,7 +98,7 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历
}
```
显式设置 userTokenReadOnly 的示例（允许用户 token 写入）：
明确设置 userTokenReadOnly 的示例（允许用户令牌写入）：
```json5
{
@@ -114,26 +114,27 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历
}
```
#### Token 使用
#### 令牌使用
- 读取操作（历史记录、回应列表、置顶列表、表情列表、成员信息、搜索）在配置了用户 token 时优先使用，否则使用 bot token。
- 写入操作（发送/编辑/删除消息、添加/移除回应、置顶/取消置顶、文件上传）默认使用 bot token。如果 `userTokenReadOnly: false` 且没有 bot token 可用，OpenClaw 回退到用户 token。
- 读取操作（历史记录、表情回应列表、置顶列表、表情符号列表、成员信息、搜索）在配置了用户令牌时优先使用用户令牌，否则使用 bot 令牌。
- 写入操作（发送/编辑/删除消息、添加/移除表情回应、置顶/取消置顶、文件上传）默认使用 bot 令牌。如果 `userTokenReadOnly: false` 且没有可用的 bot 令牌，OpenClaw 会回退到用户令牌。
### 历史上下文
- `channels.slack.historyLimit`（或 `channels.slack.accounts.*.historyLimit`）控制多少条最近的频道/群组消息被包含在提示中。
- 回退到 `messages.groupChat.historyLimit`。设置 `0` 可禁用（默认 50）。
- `channels.slack.historyLimit`（或 `channels.slack.accounts.*.historyLimit`）控制将多少条最近的频道/群组消息包含到提示中。
- 回退到 `messages.groupChat.historyLimit`。设置为 `0` 以禁用（默认 50）。
## HTTP 模式（Events API）
当你的 Gateway网关可通过 HTTPS 被 Slack 访问时使用 HTTP webhook 模式（适用于服务器部署）。HTTP 模式使用 Events API + Interactivity + Slash Commands，共享请求 URL。
当你的 Gateway 网关可以通过 HTTPS 被 Slack 访问时（服务器部署的典型情况），使用 HTTP webhook 模式。
HTTP 模式使用 Events API + Interactivity + Slash Commands，共享一个请求 URL。
### 设置
1. 创建 Slack 应用并**禁用 Socket Mode**（如果你只使用 HTTP 则可选）。
1. 创建一个 Slack 应用并**禁用 Socket Mode**（如果你只使用 HTTP 则可选）。
2. **Basic Information** → 复制 **Signing Secret**。
3. **OAuth & Permissions** → 安装应用并复制 **Bot User OAuth Token**（`xoxb-...`）。
4. **Event Subscriptions** → 启用事件并将 **Request URL** 设置为你的 Gateway网关 webhook 路径（默认 `/slack/events`）。
4. **Event Subscriptions** → 启用事件并将 **Request URL** 设置为你的 Gateway 网关 webhook 路径（默认 `/slack/events`）。
5. **Interactivity & Shortcuts** → 启用并设置相同的 **Request URL**。
6. **Slash Commands** → 为你的命令设置相同的 **Request URL**。
@@ -158,9 +159,9 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历
多账户 HTTP 模式：设置 `channels.slack.accounts.<id>.mode = "http"` 并为每个账户提供唯一的 `webhookPath`，以便每个 Slack 应用可以指向自己的 URL。
### 清单（可选）
### Manifest（可选）
使用此 Slack 应用清单可快速创建应用（根据需要调整名称/命令）。如果你计划配置用户 token，请包含用户范围。
使用此 Slack 应用 manifest 快速创建应用（如果需要可以调整名称/命令）。如果你计划配置用户令牌，请包含用户权限范围。
```json
{
@@ -250,23 +251,23 @@ OpenClaw 可以使用 Slack 用户 token（`xoxp-...`）进行读取操作（历
}
```
如果你启用原生命令，为你想暴露的每个命令添加一个 `slash_commands` 条目（匹配 `/help` 列表）。通过 `channels.slack.commands.native` 覆盖。
如果启用原生命令，为每个要公开的命令添加一个 `slash_commands` 条目（与 `/help` 列表匹配）。使用 `channels.slack.commands.native` 覆盖。
## 范围（当前 vs 可选）
## 权限范围（当前 vs 可选）
Slack 的 Conversations API 按类型设定范围：你只需要你实际使用的会话类型（channels、groups、im、mpim）对应的范围。概览请参见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/。
Slack 的 Conversations API 是按类型区分的：你只需要你实际接触的会话类型（channels、groups、im、mpim）的权限范围。概述参见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/。
### Bot token 范围（必需）
### Bot 令牌权限范围（必需）
- `chat:write`（通过 `chat.postMessage` 发送/更新/删除消息）
https://docs.slack.dev/reference/methods/chat.postMessage
- `im:write`（通过 `conversations.open` 打开用户私信）
- `im:write`（通过 `conversations.open` 打开私信用于用户私信）
https://docs.slack.dev/reference/methods/conversations.open
- `channels:history`、`groups:history`、`im:history`、`mpim:history`
https://docs.slack.dev/reference/methods/conversations.history
- `channels:read`、`groups:read`、`im:read`、`mpim:read`
https://docs.slack.dev/reference/methods/conversations.info
- `users:read`（用户查找）
- `users:read`（用户查询）
https://docs.slack.dev/reference/methods/users.info
- `reactions:read`、`reactions:write`（`reactions.get` / `reactions.add`）
https://docs.slack.dev/reference/methods/reactions.get
@@ -279,9 +280,9 @@ Slack 的 Conversations API 按类型设定范围：你只需要你实际使用
- `files:write`（通过 `files.uploadV2` 上传）
https://docs.slack.dev/messaging/working-with-files/#upload
### 用户 token 范围（可选，默认只读）
### 用户令牌权限范围（可选，默认只读）
如果你配置了 `channels.slack.userToken`，请在 **User Token Scopes** 下添加这些。
如果你配置了 `channels.slack.userToken`，在 **User Token Scopes** 下添加这些。
- `channels:history`、`groups:history`、`im:history`、`mpim:history`
- `channels:read`、`groups:read`、`im:read`、`mpim:read`
@@ -291,19 +292,19 @@ Slack 的 Conversations API 按类型设定范围：你只需要你实际使用
- `emoji:read`
- `search:read`
### 目前不需要（但未来可能）
### 目前不需要（但未来可能需要）
- `mpim:write`（仅在我们添加群组私信打开/私信开始功能时需要，通过 `conversations.open`）
- `groups:write`（仅在我们添加私有频道管理时需要：创建/重命名/邀请/归档）
- `chat:write.public`（仅在我们想向机器人未加入的频道发帖时需要）
- `mpim:write`（仅当我们添加群组私信打开/私信启动时通过 `conversations.open`）
- `groups:write`（仅当我们添加私有频道管理时：创建/重命名/邀请/归档）
- `chat:write.public`（仅当我们想发布到机器人未加入的频道时）
https://docs.slack.dev/reference/scopes/chat.write.public
- `users:read.email`（仅在我们需要从 `users.info` 获取邮箱字段时需要）
- `users:read.email`（仅当我们需要从 `users.info` 获取邮箱字段时）
https://docs.slack.dev/changelog/2017-04-narrowing-email-access
- `files:read`（仅在我们开始列出/读取文件元数据时需要）
- `files:read`（仅当我们开始列出/读取文件元数据时）
## 配置
Slack 仅使用 Socket Mode（无 HTTP webhook 服务器）。提供两个 token：
Slack 仅使用 Socket Mode（无 HTTP webhook 服务器）。提供两个令牌：
```json
{
@@ -352,40 +353,40 @@ Slack 仅使用 Socket Mode（无 HTTP webhook 服务器）。提供两个 token
}
```
Token 也可以通过环境变量提供：
令牌也可以通过环境变量提供：
- `SLACK_BOT_TOKEN`
- `SLACK_APP_TOKEN`
确认回应由 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认回应。
确认表情回应通过 `messages.ackReaction` + `messages.ackReactionScope` 全局控制。使用 `messages.removeAckAfterReply` 在机器人回复后清除确认表情回应。
## 限制
- 出站文本按 `channels.slack.textChunkLimit` 分块（默认 4000）。
- 可选的换行分块：设置 `channels.slack.chunkMode="newline"` 在按长度分块之前按空行（段落边界）分割。
- 媒体上传上限由 `channels.slack.mediaMaxMb` 限制（默认 20）。
- 可选的换行分块：设置 `channels.slack.chunkMode="newline"` 以在长度分块之前按空行（段落边界）分割。
- 媒体上传受 `channels.slack.mediaMaxMb` 限制（默认 20）。
## 回复线程
默认情况下，OpenClaw 在主频道中回复。使用 `channels.slack.replyToMode` 控制自动线程行为：
默认情况下，OpenClaw 在主频道回复。使用 `channels.slack.replyToMode` 控制自动线程：
| 模式 | 行为 |
| ------- | ------------------------------------------------------------------------------------------------ |
| `off` | **默认。** 在主频道回复。仅在触发消息已在线程中时才在线程中回复。 |
| `first` | 第一条回复进入线程（在触发消息下方），后续回复进入主频道。适用于保持上下文可见同时避免线程杂乱。 |
| `all` | 所有回复都进入线程。保持对话集中但可能降低可见性。 |
| 模式 | 行为 |
| ------- | -------------------------------------------------------------------------------------------- |
| `off` | **默认。** 在主频道回复。仅当触发消息已在线程中时才使用线程。 |
| `first` | 第一条回复进入线程（在触发消息下），后续回复进入主频道。适合保持上下文可见同时避免线程混乱。 |
| `all` | 所有回复都进入线程。保持对话集中但可能降低可见性。 |
该模式同时适用于自动回复和智能体工具调用（`slack sendMessage`）。
该模式适用于自动回复和智能体工具调用（`slack sendMessage`）。
### 按聊天类型设置线程
### 按聊天类型的线程
你可以通过设置 `channels.slack.replyToModeByChatType` 为不同聊天类型配置不同的线程行为：
你可以通过设置 `channels.slack.replyToModeByChatType` 为每种聊天类型配置不同的线程行为：
```json5
{
channels: {
slack: {
replyToMode: "off", // 频道默认
replyToMode: "off", // 频道的默认值
replyToModeByChatType: {
direct: "all", // 私信始终使用线程
group: "first", // 群组私信/MPIM 第一条回复使用线程
@@ -399,7 +400,7 @@ Token 也可以通过环境变量提供：
- `direct`：一对一私信（Slack `im`）
- `group`：群组私信 / MPIM（Slack `mpim`）
- `channel`：标准频道（公共/私有）
- `channel`：标准频道（公开/私有）
优先级：
@@ -407,11 +408,11 @@ Token 也可以通过环境变量提供：
2. `replyToMode`
3. 提供商默认值（`off`）
旧版 `channels.slack.dm.replyToMode` 在未设置聊天类型覆盖时仍作为 `direct` 的回退值。
当未设置聊天类型覆盖时，旧版 `channels.slack.dm.replyToMode` 仍可作为 `direct` 的回退。
示例：
仅私信使用线程：
仅对私信使用线程：
```json5
{
@@ -424,7 +425,7 @@ Token 也可以通过环境变量提供：
}
```
群组私信使用线程但频道保持在根级：
对群组私信使用线程但保持频道在根级别：
```json5
{
@@ -437,7 +438,7 @@ Token 也可以通过环境变量提供：
}
```
频道使用线程，私信保持在根级：
让频道使用线程，保持私信在根级别：
```json5
{
@@ -452,79 +453,79 @@ Token 也可以通过环境变量提供：
### 手动线程标签
对于精细控制，在智能体回复中使用以下标签：
对于细粒度控制，在智能体响应中使用这些标签：
- `[[reply_to_current]]` — 回复触发消息（开始/继续线程）。
- `[[reply_to:<id>]]` — 回复特定消息 ID。
- `[[reply_to:<id>]]` — 回复特定的消息 id。
## 会话 + 路由
- 私信共享 `main` 会话（与 WhatsApp/Telegram 类似）。
- 私信共享 `main` 会话（与 WhatsApp/Telegram 相同）。
- 频道映射到 `agent:<agentId>:slack:channel:<channelId>` 会话。
- 斜杠命令使用 `agent:<agentId>:slack:slash:<userId>` 会话（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）。
- 如果 Slack 不提供 `channel_type`，OpenClaw 从频道 ID 前缀（`D`、`C`、`G`）推断并默认为 `channel` 以保持会话键稳定。
- 原生命令注册使用 `commands.native`（全局默认 `"auto"` → Slack 关闭），可通过 `channels.slack.commands.native` 按工作区覆盖。文本命令需要独立的 `/...` 消息，可通过 `commands.text: false` 禁用。Slack 斜杠命令在 Slack 应用中管理，不会自动移除。使用 `commands.useAccessGroups: false` 可绕过命令的访问组检查。
- 如果 Slack 未提供 `channel_type`，OpenClaw 会从频道 ID 前缀（`D`、`C`、`G`）推断并默认为 `channel` 以保持会话键稳定。
- 原生命令注册使用 `commands.native`（全局默认 `"auto"` → Slack 关闭），可以使用 `channels.slack.commands.native` 按工作空间覆盖。文本命令需要独立的 `/...` 消息，可以使用 `commands.text: false` 禁用。Slack 斜杠命令在 Slack 应用中管理，不会自动移除。使用 `commands.useAccessGroups: false` 绕过命令的访问组检查。
- 完整命令列表 + 配置：[斜杠命令](/tools/slash-commands)
## 私信安全（配对）
- 默认：`channels.slack.dm.policy="pairing"` — 未知私信发送者会收到配对码（1 小时后过期）。
- 通过 `openclaw pairing approve slack <code>` 批准。
- 默认：`channels.slack.dm.policy="pairing"` — 未知的私信发送者会收到配对码（1 小时后过期）。
- 通过以下方式批准：`openclaw pairing approve slack <code>`。
- 要允许任何人：设置 `channels.slack.dm.policy="open"` 和 `channels.slack.dm.allowFrom=["*"]`。
- `channels.slack.dm.allowFrom` 接受用户 ID、@用户名或邮箱（启动时当 token 允许时解析）。向导在设置期间当 token 允许时接受用户名并将其解析为 ID。
- `channels.slack.dm.allowFrom` 接受用户 ID、@用户名或邮箱（在令牌允许时启动时解析）。向导在设置期间接受用户名，并在令牌允许时将其解析为 ID。
## 群组策略
- `channels.slack.groupPolicy` 控制频道处理方式（`open|disabled|allowlist`）。
- `allowlist` 需要频道列在 `channels.slack.channels` 中。
- 如果你只设置了 `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` 且从未创建 `channels.slack` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.slack.groupPolicy`、`channels.defaults.groupPolicy` 或频道允许列表来锁定它。
- 配置向导接受 `#channel` 名称并在可能时将其解析为 ID（公共 + 私有）；如果存在多个匹配，优先选择活跃频道。
- 启动时，OpenClaw 将允许列表中的频道/用户名称解析为 ID（当 token 允许时）并记录映射；未解析的条目保持原样。
- 要**不允许任何频道**，设置 `channels.slack.groupPolicy: "disabled"`（或保持空的允许列表）。
- `channels.slack.groupPolicy` 控制频道处理（`open|disabled|allowlist`）。
- `allowlist` 要求频道列在 `channels.slack.channels` 中。
- 如果你只设置了 `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` 而从未创建 `channels.slack` 部分，运行时默认将 `groupPolicy` 设为 `open`。添加 `channels.slack.groupPolicy`、`channels.defaults.groupPolicy` 或频道白名单来锁定它。
- 配置向导接受 `#channel` 名称，并在可能时（公开 + 私有）将其解析为 ID；如果存在多个匹配，它优先选择活跃的频道。
- 启动时，OpenClaw 将白名单中的频道/用户名解析为 ID（在令牌允许时）并记录映射；未解析的条目按原样保留。
- 要**不允许任何频道**，设置 `channels.slack.groupPolicy: "disabled"`（或保留空白名单）。
频道选项（`channels.slack.channels.<id>` 或 `channels.slack.channels.<name>`）：
- `allow`：当 `groupPolicy="allowlist"` 时允许/拒绝频道。
- `requireMention`：频道的提及门控。
- `tools`：可选的按频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `toolsBySender`：可选的频道内按发送者工具策略覆盖（键为发送者 ID/@用户名/邮箱；支持 `"*"` 通配符）。
- `tools`：可选的每频道工具策略覆盖（`allow`/`deny`/`alsoAllow`）。
- `toolsBySender`：频道内可选的每发送者工具策略覆盖（键为发送者 id/@用户名/邮箱；支持 `"*"` 通配符）。
- `allowBots`：允许此频道中机器人发送的消息（默认：false）。
- `users`：可选的按频道用户允许列表。
- `users`：可选的每频道用户白名单。
- `skills`：Skills 过滤器（省略 = 所有 Skills，空 = 无）。
- `systemPrompt`：频道的额外系统提示（与主题/目的合并）。
- `enabled`：设置 `false` 可禁用频道。
- `systemPrompt`：频道的额外系统提示（与主题/目的组合）。
- `enabled`：设置为 `false` 以禁用频道。
## 投递目标
在定时任务/CLI 发送中使用：
与 cron/CLI 发送一起使用：
- `user:<id>` 用于私信
- `channel:<id>` 用于频道
## 工具操作
Slack 工具操作可通过 `channels.slack.actions.*` 控制：
Slack 工具操作可以通过 `channels.slack.actions.*` 进行门控：
| 操作组 | 默认值 | 说明 |
| ---------- | ------ | ------------------- |
| reactions | 启用 | 添加回应 + 列出回应 |
| messages | 启用 | 读取/发送/编辑/删除 |
| pins | 启用 | 置顶/取消置顶/列出 |
| memberInfo | 启用 | 成员信息 |
| emojiList | 启用 | 自定义表情列表 |
| 操作组 | 默认 | 说明 |
| ---------- | ------ | ----------------------- |
| reactions | 已启用 | 表情回应 + 列出表情回应 |
| messages | 已启用 | 读取/发送/编辑/删除 |
| pins | 已启用 | 置顶/取消置顶/列表 |
| memberInfo | 已启用 | 成员信息 |
| emojiList | 已启用 | 自定义表情符号列表 |
## 安全注意事项
## 安全说明
- 写入操作默认使用 bot token，以便状态变更操作保持在应用机器人权限和身份范围内。
- 设置 `userTokenReadOnly: false` 允许在 bot token 不可用时使用用户 token 进行写入操作，这意味着操作以安装用户的访问权限运行。请将用户 token 视为高权限凭据，并严格设置操作门控和允许列表。
- 如果你启用用户 token 写入，请确保用户 token 包含你预期的写入范围（`chat:write`、`reactions:write`、`pins:write`、`files:write`），否则这些操作会失败。
- 写入默认使用 bot 令牌，因此状态更改操作保持在应用的机器人权限和身份范围内。
- 设置 `userTokenReadOnly: false` 允许在 bot 令牌不可用时使用用户令牌进行写入操作，这意味着操作以安装用户的访问权限运行。将用户令牌视为高权限，并保持操作门控和白名单严格。
- 如果你启用用户令牌写入，请确保用户令牌包含你期望的写入权限范围（`chat:write`、`reactions:write`、`pins:write`、`files:write`），否则这些操作将失败。
## 注意事项
## 说明
- 提及门控通过 `channels.slack.channels` 控制（将 `requireMention` 设为 `true`）；`agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）也算作提及。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
- 回应通知遵循 `channels.slack.reactionNotifications`（使用 `reactionAllowlist` 配合 `allowlist` 模式）。
- 机器人发送的消息默认被忽略；通过 `channels.slack.allowBots` 或 `channels.slack.channels.<id>.allowBots` 启用。
- 警告：如果你允许回复其他机器人（`channels.slack.allowBots=true` 或 `channels.slack.channels.<id>.allowBots=true`），请使用 `requireMention`、`channels.slack.channels.<id>.users` 允许列表和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护规则来防止机器人之间的回复循环。
- Slack 工具的回应移除语义请参见 [/tools/reactions](/tools/reactions)。
- 在权限允许且未超过大小限制时，附件会被下载到媒体存储。
- 提及门控通过 `channels.slack.channels` 控制（将 `requireMention` 设置为 `true`）；`agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）也算作提及。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每智能体的模式。
- 表情回应通知遵循 `channels.slack.reactionNotifications`（在 `allowlist` 模式下使用 `reactionAllowlist`）。
- 默认忽略机器人发送的消息；通过 `channels.slack.allowBots` 或 `channels.slack.channels.<id>.allowBots` 启用。
- 警告：如果你允许回复其他机器人（`channels.slack.allowBots=true` 或 `channels.slack.channels.<id>.allowBots=true`），请使用 `requireMention`、`channels.slack.channels.<id>.users` 白名单和/或在 `AGENTS.md` 和 `SOUL.md` 中设置明确的防护措施来防止机器人之间的回复循环。
- 对于 Slack 工具，表情回应移除语义见 [/tools/reactions](/tools/reactions)。
- 附件在允许且在大小限制内时会下载到媒体存储。
docs/zh-CN/channels/telegram.md
+222 -226
View File
@@ -1,30 +1,30 @@
---
read_when:
- 开发 Telegram 功能或 webhook 时
summary: Telegram 机器人支持状态、功能与配置
- 开发 Telegram 功能或 webhook
summary: Telegram 机器人支持状态、功能和配置
title: Telegram
x-i18n:
generated_at: "2026-02-01T19:54:11Z"
generated_at: "2026-02-03T10:07:32Z"
model: claude-opus-4-5
provider: pi
source_hash: 63198fce8c29a1020590d6a3ca142314b30c35d50317b878bf1fb1bfd8d54747
source_hash: 65da427e5f2383edb674054f8133a5777b2aae8a7c4bd78defa065124090a19c
source_path: channels/telegram.md
workflow: 14
workflow: 15
---
# Telegram (Bot API)
# Telegram（Bot API）
状态：通过 grammY 实现的机器人私聊 + 群组功能已可用于生产环境。默认使用长轮询；webhook 可选。
状态：通过 grammY 支持机器人私信和群组，已可用于生产环境。默认使用长轮询；webhook 可选。
## 快速设置（新手）
## 快速设置（入门）
1. 通过 **@BotFather**（[直达链接](https://t.me/BotFather)）创建机器人。确认用户名确实是 `@BotFather`，然后复制令牌。
2. 设置令牌：
1. 通过 **@BotFather**（[直达链接](https://t.me/BotFather)）创建机器人。确认用户名确实是 `@BotFather`，然后复制 token。
2. 设置 token：
- 环境变量：`TELEGRAM_BOT_TOKEN=...`
- 或配置：`channels.telegram.botToken: "..."`。
- 如果两者都设置了，配置优先（环境变量回退仅适用于默认账户）。
3. 启动 Gateway网关。
4. 私聊访问默认为配对模式；首次联系时需批准配对码。
3. 启动 Gateway 网关。
4. 私信访问默认使用配对模式；首次联系时需要批准配对码。
最小配置：
@@ -40,26 +40,26 @@ x-i18n:
}
```
## 简介
## 这是什么
- 由 Gateway网关管理的 Telegram Bot API 渠道。
- 确定性路由：回复始终发回 Telegram；模型不会选择渠道。
- 私聊共享智能体的主会话；群组保持隔离（`agent:<agentId>:telegram:group:<chatId>`）。
- 一个由 Gateway 网关拥有的 Telegram Bot API 渠道。
- 确定性路由：回复返回到 Telegram；模型不会选择渠道。
- 私信共享智能体的主会话；群组保持隔离（`agent:<agentId>:telegram:group:<chatId>`）。
## 设置（快速路径）
### 1）创建机器人令牌（BotFather）
### 1）创建机器人 token（BotFather）
1. 打开 Telegram，与 **@BotFather**（[直达链接](https://t.me/BotFather)）对话。确认用户名确实是 `@BotFather`。
2. 运行 `/newbot`，然后按提示操作（名称 + 以 `bot` 结尾的用户名）。
3. 复制令牌并安全保存。
1. 打开 Telegram 并与 **@BotFather**（[直达链接](https://t.me/BotFather)）对话。确认用户名确实是 `@BotFather`。
2. 运行 `/newbot`，然后按照提示操作（名称 + 以 `bot` 结尾的用户名）。
3. 复制 token 并安全保存。
可选的 BotFather 设置：
- `/setjoingroups` — 允许/禁止将机器人添加到群组。
- `/setprivacy` — 控制机器人是否能看到所有群组消息。
- `/setjoingroups` — 允许/拒绝将机器人添加到群组。
- `/setprivacy` — 控制机器人是否可以看到所有群组消息。
### 2）配置令牌（环境变量或配置）
### 2）配置 token（环境变量或配置文件）
示例：
@@ -79,34 +79,32 @@ x-i18n:
环境变量选项：`TELEGRAM_BOT_TOKEN=...`（适用于默认账户）。
如果环境变量和配置都设置了，配置优先。
多账户支持：使用 `channels.telegram.accounts`，为每个账户设置令牌和可选的 `name`。请参阅 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解通用模式。
多账户支持：使用 `channels.telegram.accounts`，每个账户有独立的 token 和可选的 `name`。参见 [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) 了解共享模式。
3. 启动 Gateway网关。当令牌被解析后（配置优先，环境变量回退），Telegram 即启动。
4. 私聊访问默认为配对模式。机器人首次被联系时需批准配对码。
5. 对于群组：添加机器人，决定隐私/管理员行为（见下文），然后设置 `channels.telegram.groups` 来控制提及门控 + 白名单。
3. 启动 Gateway 网关。当 token 解析成功时 Telegram 启动（配置优先，环境变量回退）。
4. 私信访问默认为配对模式。机器人首次被联系时批准配对码。
5. 对于群组：添加机器人，决定隐私/管理员行为（见下文），然后设置 `channels.telegram.groups` 来控制提及门控和允许列表。
## 令牌 + 隐私 + 权限（Telegram 端）
## Token + 隐私 + 权限（Telegram 端）
### 令牌创建（BotFather）
### Token 创建（BotFather）
- `/newbot` 创建机器人并返回令牌（请保密）。
- 如果令牌泄露，通过 @BotFather 撤销/重新生成令牌并更新配置。
- `/newbot` 创建机器人并返回 token（请保密）。
- 如果 token 泄露，通过 @BotFather 撤销/重新生成，并更新你的配置。
### 群组消息可见性（隐私模式）
Telegram 机器人默认启用**隐私模式**，这会限制它们能接收到的群组消息。
如果你的机器人必须看到*所有*群组消息，有两种选择：
Telegram 机器人默认启用**隐私模式**，这会限制它们接收哪些群组消息。
如果你的机器人必须看到*所有*群组消息，有两个选项：
- 使用 `/setprivacy` 禁用隐私模式，**或者**
- 将机器人设为群组**管理员**（管理员机器人可以接收所有消息）。
- 使用 `/setprivacy` 禁用隐私模式**或**
- 将机器人添加为群组**管理员**（管理员机器人可以接收所有消息）。
**注意：** 切换隐私模式后，Telegram 要求将机器人从每个群组中移除并重新添加，
更改才能生效。
**注意：** 当你切换隐私模式时，Telegram 要求将机器人从每个群组中移除并重新添加，更改才能生效。
### 群组权限（管理员权限）
管理员状态在群组内设置（Telegram 界面）。管理员机器人始终能接收所有
群组消息，因此如果需要完全可见性，请使用管理员身份。
管理员状态在群组内设置（Telegram UI）。管理员机器人始终接收所有群组消息，因此如果需要完全可见性，请使用管理员身份。
## 工作原理（行为）
@@ -114,31 +112,31 @@ Telegram 机器人默认启用**隐私模式**，这会限制它们能接收到
- 群组回复默认需要提及（原生 @提及或 `agents.list[].groupChat.mentionPatterns` / `messages.groupChat.mentionPatterns`）。
- 多智能体覆盖：在 `agents.list[].groupChat.mentionPatterns` 上设置每个智能体的模式。
- 回复始终路由回同一个 Telegram 聊天。
- 长轮询使用 grammY runner，按聊天排序；总体并发受 `agents.defaults.maxConcurrent` 限制。
- 长轮询使用 grammY runner，每个聊天按顺序处理；总体并发受 `agents.defaults.maxConcurrent` 限制。
- Telegram Bot API 不支持已读回执；没有 `sendReadReceipts` 选项。
## 草稿流式传输
OpenClaw 可以使用 `sendMessageDraft` 在 Telegram 私聊中流式传输部分回复。
OpenClaw 可以在 Telegram 私信中使用 `sendMessageDraft` 流式传输部分回复。
要求：
- 在 @BotFather 中为机器人启用话题模式（论坛话题模式）。
- 仅限私聊话题（Telegram 在入站消息中包含 `message_thread_id`）。
- `channels.telegram.streamMode` 未设为 `"off"`（默认：`"partial"`，`"block"` 启用分块草稿更新）。
- 在 @BotFather 中为机器人启用线程模式（论坛话题模式）。
- 仅限私聊线程（Telegram 在入站消息中包含 `message_thread_id`）。
- `channels.telegram.streamMode` 未设置为 `"off"`（默认：`"partial"`，`"block"` 启用分块草稿更新）。
草稿流式传输仅适用于私聊；Telegram 在群组或频道中不支持此功能。
草稿流式传输仅限私信；Telegram 在群组或频道中不支持此功能。
## 格式化（Telegram HTML）
- 出站 Telegram 文本使用 `parse_mode: "HTML"`（Telegram 支持的标签子集）。
- 类 Markdown 输入被渲染为 **Telegram 安全的 HTML**（粗体/斜体/删除线/代码/链接）；块级元素被扁平化为带换行符/项目符号的文本。
- 类 Markdown 输入被渲染为 **Telegram 安全 HTML**（粗体/斜体/删除线/代码/链接）；块级元素被扁平化为带换行/项目符号的文本。
- 来自模型的原始 HTML 会被转义，以避免 Telegram 解析错误。
- 如果 Telegram 拒绝 HTML 负载，OpenClaw 会以纯文本重试同一条消息。
- 如果 Telegram 拒绝 HTML 负载，OpenClaw 会以纯文本重试相同的消息。
## 命令（原生 + 自定义）
OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注册到 Telegram 的机器人菜单。
OpenClaw 在启动时向 Telegram 的机器人菜单注册原生命令（如 `/status`、`/reset`、`/model`）。
你可以通过配置向菜单添加自定义命令：
```json5
@@ -146,8 +144,8 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "Git backup" },
{ command: "generate", description: "Create an image" },
{ command: "backup", description: "Git 备份" },
{ command: "generate", description: "创建图片" },
],
},
},
@@ -157,29 +155,29 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注
## 故障排除
- 日志中出现 `setMyCommands failed` 通常意味着到 `api.telegram.org` 的出站 HTTPS/DNS 被阻止。
- 如果看到 `sendMessage` 或 `sendChatAction` 失败，请检查 IPv6 路由和 DNS。
- 如果你看到 `sendMessage` 或 `sendChatAction` 失败，检查 IPv6 路由和 DNS。
更多帮助：[渠道故障排除](/channels/troubleshooting)。
注意：
- 自定义命令**仅为菜单条目**；除非你在其他地方处理它们，否则 OpenClaw 不会实现它们。
- 命令名称会被规范化（去除前导 `/`，转为小写），且必须匹配 `a-z`、`0-9`、`_`（1–32 个字符）。
- 自定义命令**不能覆盖原生命令**。冲突会被忽略并记录到日志。
- 如果 `commands.native` 被禁用，则只注册自定义命令（如果没有自定义命令则清空）。
- 自定义命令**仅是菜单条目**；除非你在其他地方处理它们，否则 OpenClaw 不会实现它们。
- 命令名称会被规范化（去除前导 `/`，转为小写），必须匹配 `a-z`、`0-9`、`_`（1-32 个字符）。
- 自定义命令**不能覆盖原生命令**。冲突会被忽略并记录日志。
- 如果禁用了 `commands.native`，则只注册自定义命令（如果没有则清空）。
## 限制
- 出站文本按 `channels.telegram.textChunkLimit` 分块（默认 4000）。
- 可选的换行分块：设置 `channels.telegram.chunkMode="newline"` 以在空行（段落边界）处拆分，然后再按长度分块。
- 可选的换行分块：设置 `channels.telegram.chunkMode="newline"` 在长度分块之前按空行（段落边界）分割。
- 媒体下载/上传受 `channels.telegram.mediaMaxMb` 限制（默认 5）。
- Telegram Bot API 请求在 `channels.telegram.timeoutSeconds` 后超时（通过 grammY 默认 500）。设置更低的值以避免长时间挂起。
- 群组历史上下文使用 `channels.telegram.historyLimit`（或 `channels.telegram.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设为 `0` 以禁用（默认 50）。
- 私聊历史可通过 `channels.telegram.dmHistoryLimit`（用户轮次）限制。按用户覆盖：`channels.telegram.dms["<user_id>"].historyLimit`。
- Telegram Bot API 请求在 `channels.telegram.timeoutSeconds` 后超时（通过 grammY 默认 500）。设置较低的值以避免长时间挂起。
- 群组历史上下文使用 `channels.telegram.historyLimit`（或 `channels.telegram.accounts.*.historyLimit`），回退到 `messages.groupChat.historyLimit`。设置 `0` 禁用（默认 50）。
- 私信历史可以用 `channels.telegram.dmHistoryLimit`（用户轮次）限制。每用户覆盖：`channels.telegram.dms["<user_id>"].historyLimit`。
## 群组激活模式
默认情况下，机器人在群组中只响应提及（`@botname` 或 `agents.list[].groupChat.mentionPatterns` 中的模式）。要更改此行为：
默认情况下，机器人只响应群组中的提及（`@botname` 或 `agents.list[].groupChat.mentionPatterns` 中的模式）。要更改此行为：
### 通过配置（推荐）
@@ -188,31 +186,31 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注
channels: {
telegram: {
groups: {
"-1001234567890": { requireMention: false }, // 在此群组中始终回复
"-1001234567890": { requireMention: false }, // 在此群组中始终响应
},
},
},
}
```
**重要：** 设置 `channels.telegram.groups` 会创建一个**白名单** - 只有列出的群组（或 `"*"`）会被接受。
论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非你在 `channels.telegram.groups.<groupId>.topics.<topicId>` 下添加每个话题的覆盖。
**重要：** 设置 `channels.telegram.groups` 会创建一个**允许列表** - 只有列出的群组（或 `"*"`）会被接受。
论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非你在 `channels.telegram.groups.<groupId>.topics.<topicId>` 下添加每话题覆盖。
允许所有群组且始终回复：
要允许所有群组并始终响应：
```json5
{
channels: {
telegram: {
groups: {
"*": { requireMention: false }, // 所有群组，始终回复
"*": { requireMention: false }, // 所有群组，始终响应
},
},
},
}
```
保持所有群组仅提及时回复（默认行为）：
要保持所有群组仅提及响应（默认行为）：
```json5
{
@@ -230,26 +228,26 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注
在群组中发送：
- `/activation always` - 回复所有消息
- `/activation always` - 响应所有消息
- `/activation mention` - 需要提及（默认）
**注意：** 命令仅更新会话状态。要在重启后保持行为，请使用配置。
**注意：** 命令只更新会话状态。要在重启后保持持久行为，请使用配置。
### 获取群组聊天 ID
将群组中的任意消息转发给 Telegram 上的 `@userinfobot` 或 `@getidsbot`，即可看到聊天 ID（负数，如 `-1001234567890`）。
将群组中的任何消息转发给 Telegram 上的 `@userinfobot` 或 `@getidsbot` 以查看聊天 ID（负数，如 `-1001234567890`）。
**提示：** 要获取你自己的用户 ID，私聊机器人，它会回复你的用户 ID（配对消息），或者在命令启用后使用 `/whoami`。
**提示：** 要获取你自己的用户 ID，私信机器人，它会回复你的用户 ID（配对消息），或者在命令启用后使用 `/whoami`。
**隐私提示：** `@userinfobot` 是第三方机器人。如果你更注重隐私，可以将机器人添加到群组，发送一条消息，然后使用 `openclaw logs --follow` 读取 `chat.id`，或使用 Bot API 的 `getUpdates`。
**隐私注意：** `@userinfobot` 是第三方机器人。如果你更倾向于其他方式，将机器人添加到群组，发送一条消息，然后使用 `openclaw logs --follow` 读取 `chat.id`，或使用 Bot API `getUpdates`。
## 配置写入
默认情况下，Telegram 允许写入由渠道事件或 `/config set|unset` 触发的配置更新。
以下情况会发生配置写入：
这发生在以下情况：
- 群组升级为超级群组时，Telegram 发出 `migrate_to_chat_id`（聊天 ID 变更）。OpenClaw 可以自动迁移 `channels.telegram.groups`。
- 群组升级为超级群组，Telegram 发出 `migrate_to_chat_id`（聊天 ID 更改）。OpenClaw 可以自动迁移 `channels.telegram.groups`。
- 你在 Telegram 聊天中运行 `/config set` 或 `/config unset`（需要 `commands.config: true`）。
禁用方式：
@@ -264,14 +262,14 @@ OpenClaw 在启动时将原生命令（如 `/status`、`/reset`、`/model`）注
Telegram 论坛话题在每条消息中包含 `message_thread_id`。OpenClaw：
- 将 `:topic:<threadId>` 追加到 Telegram 群组会话键，使每个话题相互隔离。
- 发送输入指示器和回复时携带 `message_thread_id`，确保回复留在话题内。
- 通用话题（thread id `1`）比较特殊：消息发送时省略 `message_thread_id`（Telegram 会拒绝），但输入指示器仍包含它。
- 在模板上下文中暴露 `MessageThreadId` + `IsForum`，用于路由/模板。
- 话题级配置可在 `channels.telegram.groups.<chatId>.topics.<threadId>` 下设置（skills、白名单、自动回复、系统提示词、禁用）。
- 话题配置继承群组设置（requireMention、白名单、skills、提示词、enabled），除非按话题覆盖。
- 将 `:topic:<threadId>` 附加到 Telegram 群组会话键，使每个话题隔离。
- 发送输入指示器和回复时带上 `message_thread_id`，使响应保持在话题内。
- 通用话题（线程 id `1`）是特殊的：消息发送省略 `message_thread_id`（Telegram 会拒绝），但输入指示器仍然包含它。
- 在模板上下文中暴露 `MessageThreadId` + `IsForum` 用于路由/模板。
- 话题特定配置可在 `channels.telegram.groups.<chatId>.topics.<threadId>` 下设置（skills、允许列表、自动回复、系统提示、禁用）。
- 话题配置继承群组设置（requireMention、允许列表、skills、提示、enabled），除非每话题覆盖。
私聊在某些边缘情况下可能包含 `message_thread_id`。OpenClaw 保持私聊会话键不变，但在存在 thread id 时仍将其用于回复/草稿流式传输。
私聊在某些边缘情况下可能包含 `message_thread_id`。OpenClaw 保持私信会话键不变，但在存在线程 id 时仍将其用于回复/草稿流式传输。
## 内联按钮
@@ -289,7 +287,7 @@ Telegram 支持带回调按钮的内联键盘。
}
```
按账户配置：
对于每账户配置：
```json5
{
@@ -310,30 +308,30 @@ Telegram 支持带回调按钮的内联键盘。
作用域：
- `off` — 禁用内联按钮
- `dm` — 仅私聊（群组目标被阻止）
- `group` — 仅群组（私聊目标被阻止）
- `all` — 私聊 + 群组
- `allowlist` — 私聊 + 群组，但仅限 `allowFrom`/`groupAllowFrom` 允许的发送者（与控制命令规则相同）
- `dm` — 仅私信（群组目标被阻止）
- `group` — 仅群组（私信目标被阻止）
- `all` — 私信 + 群组
- `allowlist` — 私信 + 群组，但仅限 `allowFrom`/`groupAllowFrom` 允许的发送者（与控制命令规则相同）
默认值：`allowlist`。
默认：`allowlist`。
旧版：`capabilities: ["inlineButtons"]` = `inlineButtons: "all"`。
### 发送按钮
使用消息工具的 `buttons` 参数：
使用带 `buttons` 参数的消息工具：
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
message: "Choose an option:",
message: "选择一个选项：",
buttons: [
[
{ text: "Yes", callback_data: "yes" },
{ text: "No", callback_data: "no" },
{ text: "是", callback_data: "yes" },
{ text: "否", callback_data: "no" },
],
[{ text: "Cancel", callback_data: "cancel" }],
[{ text: "取消", callback_data: "cancel" }],
],
}
```
@@ -343,75 +341,75 @@ Telegram 支持带回调按钮的内联键盘。
### 配置选项
Telegram 功能可在两个层级配置（上面展示了对象形式；旧版字符串数组仍受支持）：
Telegram 功能可以在两个级别配置（上面显示的对象形式；旧版字符串数组仍然支持）：
- `channels.telegram.capabilities`：全局默认功能配置，应用于所有 Telegram 账户，除非被覆盖。
- `channels.telegram.accounts.<account>.capabilities`：按账户的功能配置，覆盖该账户的全局默认值。
- `channels.telegram.capabilities`：应用于所有 Telegram 账户的全局默认功能配置，除非被覆盖。
- `channels.telegram.accounts.<account>.capabilities`：每账户功能，覆盖该特定账户的全局默认值。
当所有 Telegram 机器人/账户应具有相同行为时，使用全局设置。当不同机器人需要不同行为时，使用按账户配置（例如，一个账户只处理私聊，另一个允许在群组中使用）。
当所有 Telegram 机器人/账户应具有相同行为时使用全局设置。当不同机器人需要不同行为时使用每账户配置（例如，一个账户只处理私信，而另一个允许在群组中使用）。
## 访问控制（私聊 + 群组）
## 访问控制（私信 + 群组）
### 私聊访问
### 私信访问
- 默认：`channels.telegram.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前被忽略（配对码 1 小时后过期）。
- 默认：`channels.telegram.dmPolicy = "pairing"`。未知发送者收到配对码；在批准之前消息被忽略（配对码 1 小时后过期）。
- 批准方式：
- `openclaw pairing list telegram`
- `openclaw pairing approve telegram <CODE>`
- 配对是 Telegram 私聊使用的默认令牌交换方式。详情：[配对](/start/pairing)
- `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；请使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。
- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/start/pairing)
- `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。
#### 查找你的 Telegram 用户 ID
更安全的方式（无需第三方机器人）：
更安全（无第三方机器人）：
1. 启动 Gateway网关并私聊你的机器人。
1. 启动 Gateway 网关并私信你的机器人。
2. 运行 `openclaw logs --follow` 并查找 `from.id`。
替代方式（官方 Bot API）：
备选（官方 Bot API）：
1. 私聊你的机器人。
2. 使用你的机器人令牌获取更新，并读取 `message.from.id`：
1. 私信你的机器人。
2. 使用你的机器人 token 获取更新并读取 `message.from.id`：
```bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```
第三方方式（隐私性较低）：
第三方（隐私性较低）：
- 私聊 `@userinfobot` 或 `@getidsbot` 并使用返回的用户 ID。
- 私信 `@userinfobot` 或 `@getidsbot` 并使用返回的用户 id。
### 群组访问
两个独立的控制：
**1. 允许哪些群组**（通过 `channels.telegram.groups` 的群组白名单）：
**1. 允许哪些群组**（通过 `channels.telegram.groups` 的群组允许列表）：
- 没有 `groups` 配置 = 允许所有群组
- 无 `groups` 配置 = 允许所有群组
- 有 `groups` 配置 = 只允许列出的群组或 `"*"`
- 示例：`"groups": { "-1001234567890": {}, "*": {} }` 允许所有群组
**2. 允许哪些发送者**（通过 `channels.telegram.groupPolicy` 的发送者过滤）：
- `"open"` = 允许的群组中所有发送者都可以发消息
- `"open"` = 允许群组中的所有发送者发消息
- `"allowlist"` = 只有 `channels.telegram.groupAllowFrom` 中的发送者可以发消息
- `"disabled"` = 完全不接受群组消息
默认为 `groupPolicy: "allowlist"`（除非添加 `groupAllowFrom`，否则被阻止）。
- `"disabled"` = 不接受任何群组消息
默认是 `groupPolicy: "allowlist"`（除非添加 `groupAllowFrom` 否则被阻止）。
大多数用户需要：`groupPolicy: "allowlist"` + `groupAllowFrom` + 在 `channels.telegram.groups` 中列出特定群组
## 长轮询 vs webhook
- 默认：长轮询（不需要公网 URL）。
- 默认：长轮询（不需要公共 URL）。
- Webhook 模式：设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`（可选 `channels.telegram.webhookPath`）。
- 本地监听器绑定到 `0.0.0.0:8787`，默认服务 `POST /telegram-webhook`。
- 如果你的公网 URL 不同，请使用反向代理并将 `channels.telegram.webhookUrl` 指向公网端点。
- 本地监听器绑定到 `0.0.0.0:8787`，默认服务于 `POST /telegram-webhook`。
- 如果你的公共 URL 不同，使用反向代理并将 `channels.telegram.webhookUrl` 指向公共端点。
## 回复线程
Telegram 通过标签支持可选的线程回复：
- `[[reply_to_current]]` -- 回复触发消息。
- `[[reply_to:<id>]]` -- 回复特定消息 ID。
- `[[reply_to:<id>]]` -- 回复特定消息 id。
通过 `channels.telegram.replyToMode` 控制：
@@ -419,17 +417,16 @@ Telegram 通过标签支持可选的线程回复：
## 音频消息（语音 vs 文件）
Telegram 区分**语音消息**（圆形气泡）和**音频文件**（元数据卡片）。
OpenClaw 默认使用音频文件以保持向后兼容。
Telegram 区分**语音备忘录**（圆形气泡）和**音频文件**（元数据卡片）。
OpenClaw 默认使用音频文件以保持向后兼容性。
要在智能体回复中强制使用语音消息气泡，在回复中的任意位置包含此标签：
要在智能体回复中强制使用语音备忘录气泡，在回复中的任何位置包含此标签：
- `[[audio_as_voice]]` — 以语音消息而非文件形式发送音频。
- `[[audio_as_voice]]` — 将音频作为语音备忘录而不是文件发送。
该标签会从发送的文本中移除。其他渠道会忽略此标签。
该标签会从发送的文本中去除。其他渠道会忽略此标签。
对于消息工具发送，设置 `asVoice: true` 并附带兼容语音的音频 `media` URL
（当有 media 时 `message` 为可选）：
对于消息工具发送，设置 `asVoice: true` 并配合兼容语音的音频 `media` URL（当存在 media 时 `message` 是可选的）：
```json5
{
@@ -443,34 +440,34 @@ OpenClaw 默认使用音频文件以保持向后兼容。
## 贴纸
OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。
OpenClaw 支持接收和发送 Telegram 贴纸，并具有智能缓存功能。
### 接收贴纸
当用户发送贴纸时，OpenClaw 根据贴纸类型进行处理：
当用户发送贴纸时，OpenClaw 根据贴纸类型处理：
- **静态贴纸（WEBP）：** 下载并通过视觉能力处理。贴纸在消息内容中显示为 `<media:sticker>` 占位符。
- **动态贴纸（TGS）：** 跳过（不支持 Lottie 格式处理）。
- **视频贴纸（WEBM）：** 跳过（不支持视频格式处理）。
- **静态贴纸（WEBP）：** 下载并通过视觉处理。贴纸在消息内容中显示为 `<media:sticker>` 占位符。
- **动画贴纸（TGS）：** 跳过（Lottie 格式不支持处理）。
- **视频贴纸（WEBM）：** 跳过（视频格式不支持处理）。
接收贴纸时可用的模板上下文字段：
- `Sticker` — 包含以下属性的对象：
- `emoji` — 与贴纸关联的表情
- `emoji` — 与贴纸关联的表情符号
- `setName` — 贴纸集名称
- `fileId` — Telegram 文件 ID（可用于发回同一贴纸）
- `fileId` — Telegram 文件 ID（用于发送相同贴纸）
- `fileUniqueId` — 用于缓存查找的稳定 ID
- `cachedDescription` — 可用时的缓存视觉描述
### 贴纸缓存
贴纸通过 AI 的视觉能力处理以生成描述。由于相同的贴纸经常被重复发送，OpenClaw 会缓存这些描述以避免冗余的 API 调用。
贴纸通过 AI 的视觉功能处理以生成描述。由于相同的贴纸经常重复发送，OpenClaw 缓存这些描述以避免冗余的 API 调用。
**工作原理：**
1. **首次遇到：** 贴纸图像被发送给 AI 进行视觉分析。AI 生成描述（例如"一只卡通猫热情地挥手"）。
2. **缓存存储：** 描述与贴纸的文件 ID、表情和集合名称一起保存。
3. **后续遇到：** 再次看到同一贴纸时，直接使用缓存的描述，不再将图像发送给 AI。
2. **缓存存储：** 描述与贴纸的文件 ID、表情符号和集合名称一起保存。
3. **后续遇到：** 当再次看到相同贴纸时，直接使用缓存的描述。图像不会发送给 AI。
**缓存位置：** `~/.openclaw/telegram/sticker-cache.json`
@@ -482,22 +479,22 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。
"fileUniqueId": "AgADBAADb6cxG2Y",
"emoji": "👋",
"setName": "CoolCats",
"description": "A cartoon cat waving enthusiastically",
"description": "一只卡通猫热情地挥手",
"cachedAt": "2026-01-15T10:30:00.000Z"
}
```
**优势：**
**优点：**
- 通过避免对同一贴纸重复调用视觉能力来降低 API 成本
- 缓存贴纸的响应速度更快（无视觉处理延迟）
- 支持基于缓存描述的贴纸搜索功能
- 通过避免对相同贴纸重复调用视觉 API 来降低 API 成本
- 缓存贴纸响应更快（无视觉处理延迟）
- 基于缓存描述启用贴纸搜索功能
缓存在接收贴纸时自动填充，无需手动管理。
缓存在接收贴纸时自动填充。无需手动缓存管理。
### 发送贴纸
智能体可以使用 `sticker` 和 `sticker-search` 动作发送和搜索贴纸。这些功能默认禁用，必须在配置中启用：
智能体可以使用 `sticker` 和 `sticker-search` 动作发送和搜索贴纸。这些默认禁用，必须在配置中启用：
```json5
{
@@ -524,24 +521,24 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。
参数：
- `fileId`（必填）— 贴纸的 Telegram 文件 ID。可从接收贴纸时的 `Sticker.fileId` 获取，或从 `sticker-search` 结果获取。
- `fileId`（必需）— 贴纸的 Telegram 文件 ID。从接收贴纸时的 `Sticker.fileId` 获取，或从 `sticker-search` 结果获取。
- `replyTo`（可选）— 要回复的消息 ID。
- `threadId`（可选）— 论坛话题的消息线程 ID。
**搜索贴纸：**
智能体可以通过描述、表情或集合名称搜索缓存的贴纸：
智能体可以按描述、表情符号或集合名称搜索缓存的贴纸：
```json5
{
action: "sticker-search",
channel: "telegram",
query: "cat waving",
query: "猫 挥手",
limit: 5,
}
```
从缓存返回匹配的贴纸：
返回缓存中匹配的贴纸：
```json5
{
@@ -551,14 +548,14 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。
{
fileId: "CAACAgIAAxkBAAI...",
emoji: "👋",
description: "A cartoon cat waving enthusiastically",
description: "一只卡通猫热情地挥手",
setName: "CoolCats",
},
],
}
```
搜索使用跨描述文本、表情字符和集合名称的模糊匹配。
搜索在描述文本、表情符号字符和集合名称之间使用模糊匹配。
**带线程的示例：**
@@ -575,73 +572,72 @@ OpenClaw 支持接收和发送 Telegram 贴纸，并带有智能缓存。
## 流式传输（草稿）
Telegram 可以在智能体生成回复时流式传输**草稿气泡**。
OpenClaw 使用 Bot API 的 `sendMessageDraft`（非真实消息），然后将
最终回复作为普通消息发送。
Telegram 可以在智能体生成响应时流式传输**草稿气泡**。
OpenClaw 使用 Bot API `sendMessageDraft`（不是真实消息），然后将最终回复作为普通消息发送。
要求（Telegram Bot API 9.3+）：
- **启用话题的私聊**（机器人的论坛话题模式）。
- 入站消息必须包含 `message_thread_id`（私聊话题线程）。
- 群组/超级群组/频道中的流式传输会被忽略。
- 入站消息必须包含 `message_thread_id`（私有话题线程）。
- 群组/超级群组/频道的流式传输被忽略。
配置：
- `channels.telegram.streamMode: "off" | "partial" | "block"`（默认：`partial`）
- `partial`：用最新的流式文本更新草稿气泡。
- `block`：以更大的块更新草稿气泡（分块）。
- `block`：以较大块（分块）更新草稿气泡。
- `off`：禁用草稿流式传输。
- 可选（仅适用于 `streamMode: "block"`）：
- 可选（仅用于 `streamMode: "block"`）：
- `channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }`
- 默认值：`minChars: 200`、`maxChars: 800`、`breakPreference: "paragraph"`（受 `channels.telegram.textChunkLimit` 限制）。
- 默认值：`minChars: 200`、`maxChars: 800`、`breakPreference: "paragraph"`（限制在 `channels.telegram.textChunkLimit` 内）。
注意：草稿流式传输与**分块流式传输**（渠道消息）不同。
分块流式传输默认关闭，如果你想要提前的 Telegram 消息而非草稿更新，需要设置 `channels.telegram.blockStreaming: true`。
分块流式传输默认关闭，如果你想要早期 Telegram 消息而不是草稿更新，需要 `channels.telegram.blockStreaming: true`。
推理流式传输（仅 Telegram）：
推理流（仅限 Telegram）：
- `/reasoning stream` 在回复生成时将推理过程流式传输到草稿气泡中，然后发送不包含推理过程的最终答案。
- 如果 `channels.telegram.streamMode` 为 `off`，推理流式传输将被禁用。
- `/reasoning stream` 在回复生成时将推理流式传输到草稿气泡中，然后发送不带推理的最终答案。
- 如果 `channels.telegram.streamMode` 为 `off`，推理流被禁用。
更多上下文：[流式传输 + 分块](/concepts/streaming)。
## 重试策略
出站 Telegram API 调用在遇到瞬态网络/429 错误时会以指数退避和抖动进行重试。通过 `channels.telegram.retry` 配置。参见[重试策略](/concepts/retry)。
出站 Telegram API 调用在遇到临时网络/429 错误时会以指数退避和抖动进行重试。通过 `channels.telegram.retry` 配置。参见[重试策略](/concepts/retry)。
## 智能体工具（消息 + 表情回应）
## 智能体工具（消息 + 反应）
- 工具：`telegram`，`sendMessage` 动作（`to`、`content`，可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）。
- 工具：`telegram`，`react` 动作（`chatId`、`messageId`、`emoji`）。
- 工具：`telegram`，`deleteMessage` 动作（`chatId`、`messageId`）。
- 表情回应移除语义：参见 [/tools/reactions](/tools/reactions)。
- 工具：`telegram`，使用 `sendMessage` 动作（`to`、`content`，可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）。
- 工具：`telegram`，使用 `react` 动作（`chatId`、`messageId`、`emoji`）。
- 工具：`telegram`，使用 `deleteMessage` 动作（`chatId`、`messageId`）。
- 反应移除语义：参见 [/tools/reactions](/tools/reactions)。
- 工具门控：`channels.telegram.actions.reactions`、`channels.telegram.actions.sendMessage`、`channels.telegram.actions.deleteMessage`（默认：启用），以及 `channels.telegram.actions.sticker`（默认：禁用）。
## 表情回应通知
## 反应通知
**表情回应的工作原理：**
Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而非消息负载中的属性。当用户添加表情回应时，OpenClaw：
**反应工作原理：**
Telegram 反应作为**单独的 `message_reaction` 事件**到达，而不是消息负载中的属性。当用户添加反应时，OpenClaw：
1. 从 Telegram API 接收 `message_reaction` 更新
2. 将其转换为**系统事件**，格式为：`"Telegram reaction added: {emoji} by {user} on msg {id}"`
3. 使用与常规消息**相同的会话键**将系统事件入队
4. 当该对话中的下一条消息到达时，系统事件被排出并添加到智能体上下文的前面
3. 使用与常规消息**相同的会话键**将系统事件加入队列
4. 当该对话中的下一条消息到达时，系统事件被排出并前置到智能体的上下文中
智能体将表情回应视为对话历史中的**系统通知**，而非消息元数据。
智能体将反应视为对话历史中的**系统通知**，而不是消息元数据。
**配置：**
- `channels.telegram.reactionNotifications`：控制哪些表情回应触发通知
- `"off"` — 忽略所有表情回应
- `"own"` — 当用户对机器人消息做出表情回应时通知（尽力而为；内存中）（默认）
- `"all"` — 对所有表情回应进行通知
- `channels.telegram.reactionNotifications`：控制哪些反应触发通知
- `"off"` — 忽略所有反应
- `"own"` — 当用户对机器人消息做出反应时通知（尽力而为；内存中）（默认）
- `"all"` — 通知所有反应
- `channels.telegram.reactionLevel`：控制智能体的表情回应能力
- `"off"` — 智能体不能对消息做表情回应
- `"ack"` — 机器人发送确认表情回应（处理时显示 👀）（默认）
- `"minimal"` — 智能体可以少量使用表情回应（指导原则：每 5-10 次交流 1 次）
- `"extensive"` — 智能体可以在适当时大量使用表情回应
- `channels.telegram.reactionLevel`：控制智能体的反应能力
- `"off"` — 智能体不能对消息做出反应
- `"ack"` — 机器人发送确认反应（处理时显示 👀）（默认）
- `"minimal"` — 智能体可以少量反应（指导：每 5-10 次交换 1 次）
- `"extensive"` — 智能体可以在适当时自由反应
**论坛群组：** 论坛群组中的表情回应包含 `message_thread_id`，使用如 `agent:main:telegram:group:{chatId}:topic:{threadId}` 的会话键。这确保同一话题中的表情回应和消息保持在一起。
**论坛群组：** 论坛群组中的反应包含 `message_thread_id`，使用类似 `agent:main:telegram:group:{chatId}:topic:{threadId}` 的会话键。这确保同一话题中的反应和消息保持在一起。
**示例配置：**
@@ -649,8 +645,8 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而
{
channels: {
telegram: {
reactionNotifications: "all", // 查看所有表情回应
reactionLevel: "minimal", // 智能体可以少量使用表情回应
reactionNotifications: "all", // 查看所有反应
reactionLevel: "minimal", // 智能体可以少量反应
},
},
}
@@ -658,51 +654,51 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而
**要求：**
- Telegram 机器人必须在 `allowed_updates` 中显式请求 `message_reaction`（由 OpenClaw 自动配置）
- 对于 webhook 模式，表情回应包含在 webhook 的 `allowed_updates` 中
- 对于轮询模式，表情回应包含在 `getUpdates` 的 `allowed_updates` 中
- Telegram 机器人必须在 `allowed_updates` 中明确请求 `message_reaction`（由 OpenClaw 自动配置）
- 对于 webhook 模式，反应包含在 webhook `allowed_updates` 中
- 对于轮询模式，反应包含在 `getUpdates` `allowed_updates` 中
## 投递目标（CLI/定时任务）
## 投递目标（CLI/cron）
- 使用聊天 ID（`123456789`）或用户名（`@name`）作为目标。
- 使用聊天 id（`123456789`）或用户名（`@name`）作为目标。
- 示例：`openclaw message send --channel telegram --target 123456789 --message "hi"`。
## 故障排除
**机器人在群组中不响应非提及消息：**
**机器人不响应群组中的非提及消息：**
- 如果你设置了 `channels.telegram.groups.*.requireMention=false`，Telegram 的 Bot API **隐私模式**必须被禁用。
- 如果你设置了 `channels.telegram.groups.*.requireMention=false`，Telegram 的 Bot API **隐私模式**必须禁用。
- BotFather：`/setprivacy` → **Disable**（然后从群组中移除并重新添加机器人）
- `openclaw channels status` 在配置期望接收非提及群组消息时会显示警告。
- `openclaw channels status --probe` 可以额外检查显式数字群组 ID 的成员资格（无法审计通配符 `"*"` 规则）。
- 快速测试：`/activation always`（仅会话级别；持久化请使用配置）
- `openclaw channels status` 在配置期望未提及群组消息时显示警告。
- `openclaw channels status --probe` 可以额外检查显式数字群组 ID 的成员资格（它无法审计通配符 `"*"` 规则）。
- 快速测试：`/activation always`（仅会话级别；使用配置以持久化）
**机器人完全看不到群组消息：**
- 如果设置了 `channels.telegram.groups`，群组必须被列出或使用 `"*"`
- 在 @BotFather 中检查隐私设置 → "Group Privacy" 应为 **OFF**
- 确认机器人确实是成员（而非只是没有读取权限的管理员）
- 检查 Gateway网关日志：`openclaw logs --follow`（查找 "skipping group message"）
- 在 @BotFather 中检查隐私设置 →"Group Privacy"应为 **OFF**
- 验证机器人确实是成员（不仅仅是没有读取权限的管理员）
- 检查 Gateway 网关日志：`openclaw logs --follow`（查找"skipping group message"）
**机器人响应提及但不响应 `/activation always`：**
- `/activation` 命令更新会话状态但不会持久化到配置
- `/activation` 命令更新会话状态但不持久化到配置
- 要持久化行为，将群组添加到 `channels.telegram.groups` 并设置 `requireMention: false`
**`/status` 等命令不工作：**
**像 `/status` 这样的命令不起作用：**
- 确保你的 Telegram 用户 ID 已授权（通过配对或 `channels.telegram.allowFrom`）
- 即使在 `groupPolicy: "open"` 的群组中，命令也需要授权
**长轮询在 Node 22+ 上立即中止（通常涉及代理/自定义 fetch）：**
**长轮询在 Node 22+ 上立即中止（通常与代理/自定义 fetch 有关）：**
- Node 22+ 对 `AbortSignal` 实例更严格；外部信号可能会立即中止 `fetch` 调用。
- 升级到规范化 abort 信号的 OpenClaw 版本，或在 Node 20 上运行 Gateway网关直到可以升级。
- Node 22+ 对 `AbortSignal` 实例更严格；外部信号可以立即中止 `fetch` 调用。
- 升级到规范化中止信号的 OpenClaw 构建版本，或在可以升级之前在 Node 20 上运行 Gateway 网关。
**机器人启动后静默停止响应（或日志中出现 `HttpError: Network request ... failed`）：**
**机器人启动后静默停止响应（或日志显示 `HttpError: Network request ... failed`）：**
- 某些主机优先将 `api.telegram.org` 解析为 IPv6。如果你的服务器没有可用的 IPv6 出口，grammY 可能会卡在仅 IPv6 的请求上。
- 修复方法：启用 IPv6 出口**或者**强制 `api.telegram.org` 使用 IPv4 解析（例如，使用 IPv4 A 记录添加 `/etc/hosts` 条目，或在操作系统 DNS 栈中优先使用 IPv4），然后重启 Gateway网关。
- 某些主机首先将 `api.telegram.org` 解析为 IPv6。如果你的服务器没有可用的 IPv6 出口，grammY 可能会卡在仅 IPv6 的请求上。
- 通过启用 IPv6 出口**或**强制 `api.telegram.org` 使用 IPv4 解析来修复（例如，使用 IPv4 A 记录添加 `/etc/hosts` 条目，或在你的 OS DNS 堆栈中优先使用 IPv4），然后重启 Gateway 网关。
- 快速检查：`dig +short api.telegram.org A` 和 `dig +short api.telegram.org AAAA` 确认 DNS 返回的内容。
## 配置参考（Telegram）
@@ -712,44 +708,44 @@ Telegram 表情回应作为**独立的 `message_reaction` 事件**到达，而
提供商选项：
- `channels.telegram.enabled`：启用/禁用渠道启动。
- `channels.telegram.botToken`：机器人令牌（BotFather）。
- `channels.telegram.tokenFile`：从文件路径读取令牌。
- `channels.telegram.botToken`：机器人 token（BotFather）。
- `channels.telegram.tokenFile`：从文件路径读取 token。
- `channels.telegram.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.telegram.allowFrom`：私聊白名单（ID/用户名）。`open` 需要 `"*"`。
- `channels.telegram.allowFrom`：私信允许列表（id/用户名）。`open` 需要 `"*"`。
- `channels.telegram.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。
- `channels.telegram.groupAllowFrom`：群组发送者白名单（ID/用户名）。
- `channels.telegram.groups`：按群组的默认设置 + 白名单（使用 `"*"` 作为全局默认）。
- `channels.telegram.groupAllowFrom`：群组发送者允许列表（id/用户名）。
- `channels.telegram.groups`：每群组默认值 + 允许列表（使用 `"*"` 作为全局默认值）。
- `channels.telegram.groups.<id>.requireMention`：提及门控默认值。
- `channels.telegram.groups.<id>.skills`：Skills 过滤（省略 = 所有 Skills，空 = 无 Skills）。
- `channels.telegram.groups.<id>.allowFrom`：按群组的发送者白名单覆盖。
- `channels.telegram.groups.<id>.systemPrompt`：群组的额外系统提示词。
- `channels.telegram.groups.<id>.enabled`：设为 `false` 时禁用该群组。
- `channels.telegram.groups.<id>.topics.<threadId>.*`：按话题覆盖（与群组字段相同）。
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`：按话题的提及门控覆盖。
- `channels.telegram.groups.<id>.skills`：skill 过滤器（省略 = 所有 skills，空 = 无）。
- `channels.telegram.groups.<id>.allowFrom`：每群组发送者允许列表覆盖。
- `channels.telegram.groups.<id>.systemPrompt`：群组的额外系统提示。
- `channels.telegram.groups.<id>.enabled`：为 `false` 时禁用群组。
- `channels.telegram.groups.<id>.topics.<threadId>.*`：每话题覆盖（与群组相同的字段）。
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`：每话题提及门控覆盖。
- `channels.telegram.capabilities.inlineButtons`：`off | dm | group | all | allowlist`（默认：allowlist）。
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`：按账户覆盖。
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`：每账户覆盖。
- `channels.telegram.replyToMode`：`off | first | all`（默认：`first`）。
- `channels.telegram.textChunkLimit`：出站分块大小（字符数）。
- `channels.telegram.chunkMode`：`length`（默认）或 `newline`，在空行（段落边界）处拆分后再按长度分块。
- `channels.telegram.textChunkLimit`：出站分块大小（字符）。
- `channels.telegram.chunkMode`：`length`（默认）或 `newline` 在长度分块之前按空行（段落边界）分割。
- `channels.telegram.linkPreview`：切换出站消息的链接预览（默认：true）。
- `channels.telegram.streamMode`：`off | partial | block`（草稿流式传输）。
- `channels.telegram.mediaMaxMb`：入站/出站媒体上限（MB）。
- `channels.telegram.retry`：出站 Telegram API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。
- `channels.telegram.network.autoSelectFamily`：覆盖 Node 的 autoSelectFamily（true=启用，false=禁用）。在 Node 22 上默认禁用以避免 Happy Eyeballs 超时。
- `channels.telegram.network.autoSelectFamily`：覆盖 Node autoSelectFamily（true=启用，false=禁用）。在 Node 22 上默认禁用以避免 Happy Eyeballs 超时。
- `channels.telegram.proxy`：Bot API 调用的代理 URL（SOCKS/HTTP）。
- `channels.telegram.webhookUrl`：启用 webhook 模式（需要 `channels.telegram.webhookSecret`）。
- `channels.telegram.webhookSecret`：webhook 密钥（设置 webhookUrl 时必填）。
- `channels.telegram.webhookSecret`：webhook 密钥（设置 webhookUrl 时必需）。
- `channels.telegram.webhookPath`：本地 webhook 路径（默认 `/telegram-webhook`）。
- `channels.telegram.actions.reactions`：Telegram 工具表情回应门控。
- `channels.telegram.actions.sendMessage`：Telegram 工具消息发送门控。
- `channels.telegram.actions.deleteMessage`：Telegram 工具消息删除门控。
- `channels.telegram.actions.sticker`：Telegram 贴纸动作门控 — 发送和搜索（默认：false）。
- `channels.telegram.reactionNotifications`：`off | own | all` — 控制哪些表情回应触发系统事件（未设置时默认：`own`）。
- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive` — 控制智能体的表情回应能力（未设置时默认：`minimal`）。
- `channels.telegram.actions.reactions`：门控 Telegram 工具反应。
- `channels.telegram.actions.sendMessage`：门控 Telegram 工具消息发送。
- `channels.telegram.actions.deleteMessage`：门控 Telegram 工具消息删除。
- `channels.telegram.actions.sticker`：门控 Telegram 贴纸动作 — 发送和搜索（默认：false）。
- `channels.telegram.reactionNotifications`：`off | own | all` — 控制哪些反应触发系统事件（未设置时默认：`own`）。
- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive` — 控制智能体的反应能力（未设置时默认：`minimal`）。
相关全局选项：
- `agents.list[].groupChat.mentionPatterns`（提及门控模式）。
- `messages.groupChat.mentionPatterns`（全局回退）。
- `commands.native`（默认为 `"auto"` → Telegram/Discord 启用，Slack 禁用）、`commands.text`、`commands.useAccessGroups`（命令行为）。通过 `channels.telegram.commands.native` 覆盖。
- `commands.native`（默认为 `"auto"` → Telegram/Discord 开启，Slack 关闭）、`commands.text`、`commands.useAccessGroups`（命令行为）。使用 `channels.telegram.commands.native` 覆盖。
- `messages.responsePrefix`、`messages.ackReaction`、`messages.ackReactionScope`、`messages.removeAckAfterReply`。
docs/zh-CN/channels/tlon.md
+20 -22
View File
@@ -1,36 +1,34 @@
---
read_when:
- 开发 Tlon/Urbit 渠道功能时
- 开发 Tlon/Urbit 渠道功能
summary: Tlon/Urbit 支持状态、功能和配置
title: Tlon
x-i18n:
generated_at: "2026-02-01T19:58:15Z"
generated_at: "2026-02-03T07:44:17Z"
model: claude-opus-4-5
provider: pi
source_hash: 19d7ffe23e82239fd2a2e35913e0d52c809b2c2b939dd39184e6c27a539ed97d
source_path: channels/tlon.md
workflow: 14
workflow: 15
---
# Tlon（插件）
Tlon 是一个基于 Urbit 构建的去中心化通讯工具。OpenClaw 连接到你的 Urbit ship，可以
回复私信和群聊消息。群聊回复默认需要 @ 提及，并可通过白名单进一步限制。
Tlon 是一个基于 Urbit 构建的去中心化即时通讯工具。OpenClaw 连接到你的 Urbit ship，可以响应私信和群聊消息。群组回复默认需要 @ 提及，并可通过允许列表进一步限制。
状态：通过插件支持。支持私信、群组提及、线程回复和纯文本媒体回退
（URL 附加到标题）。不支持反应、投票和原生媒体上传。
状态：通过插件支持。支持私信、群组提及、话题回复和纯文本媒体回退（URL 附加到说明文字）。不支持表情回应、投票和原生媒体上传。
## 需要插件
Tlon 以插件形式提供，不包含在核心安装包中。
Tlon 作为插件提供，不包含在核心安装中。
通过 CLI 安装（npm 注册表）：
通过 CLI 安装（npm 仓库）：
```bash
openclaw plugins install @openclaw/tlon
```
本地签出（从 git 仓库运行时）：
本地检出（从 git 仓库运行时）：
```bash
openclaw plugins install ./extensions/tlon
@@ -43,8 +41,8 @@ openclaw plugins install ./extensions/tlon
1. 安装 Tlon 插件。
2. 获取你的 ship URL 和登录代码。
3. 配置 `channels.tlon`。
4. 重启 Gateway网关。
5. 向机器人发送私信或在群组渠道中提及它。
4. 重启 Gateway 网关。
5. 私信机器人或在群组频道中提及它。
最小配置（单账户）：
@@ -61,9 +59,9 @@ openclaw plugins install ./extensions/tlon
}
```
## 群组渠道
## 群组频道
默认启用自动发现。你也可以手动固定渠道：
默认启用自动发现。你也可以手动固定频道：
```json5
{
@@ -89,7 +87,7 @@ openclaw plugins install ./extensions/tlon
## 访问控制
私信白名单（为空 = 允许所有）：
私信允许列表（空 = 允许全部）：
```json5
{
@@ -101,7 +99,7 @@ openclaw plugins install ./extensions/tlon
}
```
群组授权（默认为受限模式）：
群组授权（默认受限）：
```json5
{
@@ -124,15 +122,15 @@ openclaw plugins install ./extensions/tlon
}
```
## 投递目标（CLI/定时任务）
## 投递目标（CLI/cron）
与 `openclaw message send` 或定时投递配合使用：
与 `openclaw message send` 或 cron 投递一起使用：
- 私信：`~sampel-palnet` 或 `dm/~sampel-palnet`
- 群组：`chat/~host-ship/channel` 或 `group:~host-ship/channel`
## 备注
## 注意事项
- 群聊回复需要提及（例如 `~your-bot-ship`）才会响应。
- 线程回复：如果收到的消息在线程中，OpenClaw 会在线程内回复。
- 媒体：`sendMedia` 回退为文本 + URL（不支持原生上传）。
- 群组回复需要提及（例如 `~your-bot-ship`）才能响应。
- 话题回复：如果入站消息在话题中，OpenClaw 会在话题内回复。
- 媒体：`sendMedia` 回退为文本 + URL（无原生上传）。
docs/zh-CN/channels/twitch.md
+67 -66
View File
@@ -1,32 +1,32 @@
---
read_when:
- 为 OpenClaw 设置 Twitch 聊天集成
summary: Twitch 聊天机器人配置与设置
summary: Twitch 聊天机器人配置和设置
title: Twitch
x-i18n:
generated_at: "2026-02-01T19:58:38Z"
generated_at: "2026-02-03T07:44:41Z"
model: claude-opus-4-5
provider: pi
source_hash: aa7d60444e7f7e5dd7d02ce21527089058e024b8f427aeedf9e200a2818eb007
source_hash: 0dd1c05bef570470d8b82c1f6dee5337e8b76b57269c5cad6aee2e711483f8ba
source_path: channels/twitch.md
workflow: 14
workflow: 15
---
# Twitch（插件）
通过 IRC 连接支持 Twitch 聊天。OpenClaw 以 Twitch 用户（机器人账号）身份连接，在频道中接收和发送消息。
通过 IRC 连接支持 Twitch 聊天。OpenClaw 以 Twitch 用户（机器人账户）身份连接，在频道中接收和发送消息。
## 需要插件
Twitch 以插件形式提供，未包含在核心安装中。
Twitch 作为插件发布，未与核心安装捆绑。
通过 CLI（npm 注册表）安装：
通过 CLI 安装（npm 注册表）：
```bash
openclaw plugins install @openclaw/twitch
```
本地签出（从 git 仓库运行时）：
本地检出（从 git 仓库运行时）：
```bash
openclaw plugins install ./extensions/twitch
@@ -34,19 +34,19 @@ openclaw plugins install ./extensions/twitch
详情：[插件](/plugin)
## 快速设置（入门）
## 快速设置（新手）
1. 为机器人创建一个专用 Twitch 账号（或使用现有账号）。
1. 为机器人创建一个专用的 Twitch 账户（或使用现有账户）。
2. 生成凭证：[Twitch Token Generator](https://twitchtokengenerator.com/)
- 选择 **Bot Token**
- 确认已勾选 `chat:read` 和 `chat:write` 权限范围
- 确认已选择 `chat:read` 和 `chat:write` 权限范围
- 复制 **Client ID** 和 **Access Token**
3. 查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. 配置令牌：
- 环境变量：`OPENCLAW_TWITCH_ACCESS_TOKEN=...`（仅限默认账号）
- 或配置文件：`channels.twitch.accessToken`
- 如果两者都设置了，配置文件优先（环境变量回退仅适用于默认账号）。
5. 启动 Gateway网关。
- 环境变量：`OPENCLAW_TWITCH_ACCESS_TOKEN=...`（仅限默认账户）
- 或配置：`channels.twitch.accessToken`
- 如果两者都设置，配置优先（环境变量回退仅适用于默认账户）。
5. 启动 Gateway 网关。
**⚠️ 重要：** 添加访问控制（`allowFrom` 或 `allowedRoles`）以防止未授权用户触发机器人。`requireMention` 默认为 `true`。
@@ -57,22 +57,22 @@ openclaw plugins install ./extensions/twitch
channels: {
twitch: {
enabled: true,
username: "openclaw", // 机器人的 Twitch 账号
username: "openclaw", // 机器人的 Twitch 账户
accessToken: "oauth:abc123...", // OAuth Access Token（或使用 OPENCLAW_TWITCH_ACCESS_TOKEN 环境变量）
clientId: "xyz789...", // 从 Token Generator 获取的 Client ID
channel: "vevisk", // 要加入的 Twitch 频道聊天室（必填）
clientId: "xyz789...", // Token Generator 中的 Client ID
channel: "vevisk", // 要加入的 Twitch 频道聊天（必填）
allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID - 从 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 获取
},
},
}
```
## 工作原理
## 它是什么
- 由 Gateway网关拥有的 Twitch 渠道。
- 确定性路由：回复始终返回到 Twitch。
- 每个账号映射到一个隔离的会话键 `agent:<agentId>:twitch:<accountName>`。
- `username` 是机器人的账号（用于认证），`channel` 是要加入的聊天室。
- 由 Gateway 网关拥有的 Twitch 渠道。
- 确定性路由：回复总是返回到 Twitch。
- 每个账户映射到一个隔离的会话键 `agent:<agentId>:twitch:<accountName>`。
- `username` 是机器人账户（进行身份验证的账户），`channel` 是要加入的聊天室。
## 设置（详细）
@@ -81,20 +81,20 @@ openclaw plugins install ./extensions/twitch
使用 [Twitch Token Generator](https://twitchtokengenerator.com/)：
- 选择 **Bot Token**
- 确认已勾选 `chat:read` 和 `chat:write` 权限范围
- 确认已选择 `chat:read` 和 `chat:write` 权限范围
- 复制 **Client ID** 和 **Access Token**
无需手动注册应用。令牌在数小时后过期。
无需手动注册应用。令牌在几小时后过期。
### 配置机器人
**环境变量（仅限默认账号）：**
**环境变量（仅限默认账户）：**
```bash
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
```
**或配置文件：**
**或配置：**
```json5
{
@@ -110,7 +110,7 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
}
```
如果环境变量和配置文件都设置了，配置文件优先。
如果环境变量和配置都设置了，配置优先。
### 访问控制（推荐）
@@ -119,23 +119,24 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
channels: {
twitch: {
allowFrom: ["123456789"], // （推荐）仅限你的 Twitch 用户 ID
allowedRoles: ["moderator"], // 或按角色限制
},
},
}
```
优先使用 `allowFrom` 作为硬性允许列表。如果你想要基于角色的访问控制，请改用 `allowedRoles`。
**可用角色：** `"moderator"`、`"owner"`、`"vip"`、`"subscriber"`、`"all"`。
**为什么使用用户 ID？** 用户名可以更改，存在冒充风险。用户 ID 是永久的。
**为什么用用户 ID？** 用户名可以更改，允许冒充。用户 ID 是永久的。
查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/（将 Twitch 用户名转换为 ID）
查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/（将你的 Twitch 用户名转换为 ID）
## 令牌刷新（可选）
从 [Twitch Token Generator](https://twitchtokengenerator.com/) 获取的令牌无法自动刷新——过期后需重新生成。
来自 [Twitch Token Generator](https://twitchtokengenerator.com/) 的令牌无法自动刷新 - 过期时需要重新生成。
如需自动刷新令牌，请在 [Twitch Developer Console](https://dev.twitch.tv/console) 创建你自己的 Twitch 应用，并添加到配置中：
要实现自动令牌刷新，请在 [Twitch Developer Console](https://dev.twitch.tv/console) 创建你自己的 Twitch 应用并添加到配置中：
```json5
{
@@ -150,11 +151,11 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
机器人会在令牌过期前自动刷新，并记录刷新事件。
## 多账号支持
## 多账户支持
使用 `channels.twitch.accounts` 配置每个账号的令牌。参见 [`gateway/configuration`](/gateway/configuration) 了解通用模式。
使用 `channels.twitch.accounts` 配置每个账户的令牌。参阅 [`gateway/configuration`](/gateway/configuration) 了解共享模式。
示例（一个机器人账号加入两个频道）：
示例（一个机器人账户在两个频道中）：
```json5
{
@@ -179,7 +180,7 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
}
```
**注意：** 每个账号需要自己的令牌（每个频道一个令牌）。
**注意：** 每个账户需要自己的令牌（每个频道一个令牌）。
## 访问控制
@@ -199,7 +200,7 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
}
```
### 按用户 ID 设置允许列表（最安全）
### 按用户 ID 允许列表（最安全）
```json5
{
@@ -215,9 +216,10 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
}
```
### 组合允许列表 + 角色
### 基于角色的访问（替代方案）
`allowFrom` 中的用户可绕过角色检查：
`allowFrom` 是硬性允许列表。设置后，只允许这些用户 ID。
如果你想要基于角色的访问，请不设置 `allowFrom`，改为配置 `allowedRoles`：
```json5
{
@@ -225,7 +227,6 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
twitch: {
accounts: {
default: {
allowFrom: ["123456789"],
allowedRoles: ["moderator"],
},
},
@@ -263,17 +264,17 @@ openclaw channels status --probe
### 机器人不响应消息
**检查访问控制：** 临时设置 `allowedRoles: ["all"]` 进行测试。
**检查访问控制：** 确保你的用户 ID 在 `allowFrom` 中，或临时移除 `allowFrom` 并设置 `allowedRoles: ["all"]` 来测试。
**检查机器人是否在频道中：** 机器人必须加入 `channel` 中指定的频道。
### 令牌问题
**"Failed to connect" 或认证错误：**
**"Failed to connect"或身份验证错误：**
- 确认 `accessToken` 是 OAuth 访问令牌值（通常以 `oauth:` 前缀开头）
- 检查令牌是否具有 `chat:read` 和 `chat:write` 权限范围
- 如果使用令牌刷新，确认已设置 `clientSecret` 和 `refreshToken`
- 验证 `accessToken` 是 OAuth 访问令牌值（通常以 `oauth:` 前缀开头）
- 检查令牌具有 `chat:read` 和 `chat:write` 权限范围
- 如果使用令牌刷新，验证 `clientSecret` 和 `refreshToken` 已设置
### 令牌刷新不工作
@@ -284,36 +285,36 @@ Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)
```
如果看到 "token refresh disabled (no refresh token)"：
如果你看到"token refresh disabled (no refresh token)"：
- 确保已提供 `clientSecret`
- 确保已提供 `refreshToken`
- 确保提供了 `clientSecret`
- 确保提供了 `refreshToken`
## 配置
**账号配置：**
**账户配置：**
- `username` - 机器人用户名
- `accessToken` - 具有 `chat:read` 和 `chat:write` 权限的 OAuth 访问令牌
- `clientId` - Twitch Client ID（来自 Token Generator 或你的应用）
- `channel` - 要加入的频道（必填）
- `enabled` - 启用此账号（默认：`true`）
- `clientSecret` - 可选：用于自动刷新令牌
- `refreshToken` - 可选：用于自动刷新令牌
- `enabled` - 启用此账户（默认：`true`）
- `clientSecret` - 可选：用于自动令牌刷新
- `refreshToken` - 可选：用于自动令牌刷新
- `expiresIn` - 令牌过期时间（秒）
- `obtainmentTimestamp` - 令牌获取时间戳
- `allowFrom` - 用户 ID 允许列表
- `allowedRoles` - 基于角色的访问控制（`"moderator" | "owner" | "vip" | "subscriber" | "all"`）
- `requireMention` - 要求 @提及（默认：`true`）
- `requireMention` - 需要 @提及（默认：`true`）
**提供商选项：**
- `channels.twitch.enabled` - 启用/禁用渠道启动
- `channels.twitch.username` - 机器人用户名（简化单账号配置）
- `channels.twitch.accessToken` - OAuth 访问令牌（简化单账号配置）
- `channels.twitch.clientId` - Twitch Client ID（简化单账号配置）
- `channels.twitch.channel` - 要加入的频道（简化单账号配置）
- `channels.twitch.accounts.<accountName>` - 多账号配置（上述所有账号字段）
- `channels.twitch.username` - 机器人用户名（简化的单账户配置）
- `channels.twitch.accessToken` - OAuth 访问令牌（简化的单账户配置）
- `channels.twitch.clientId` - Twitch Client ID（简化的单账户配置）
- `channels.twitch.channel` - 要加入的频道（简化的单账户配置）
- `channels.twitch.accounts.<accountName>` - 多账户配置（以上所有账户字段）
完整示例：
@@ -370,15 +371,15 @@ Access token refreshed for user 123456 (expires in 14400s)
## 安全与运维
- **将令牌视为密码** - 切勿将令牌提交到 git
- **将令牌视为密码** - 永远不要将令牌提交到 git
- **使用自动令牌刷新** 用于长时间运行的机器人
- **使用用户 ID 允许列表** 而非用户名进行访问控制
- **监控日志** 关注令牌刷新事件和连接状态
- **最小化令牌权限范围** - 仅请求 `chat:read` 和 `chat:write`
- **如遇问题**：确认没有其他进程占用会话后，重启 Gateway网关
- **使用用户 ID 允许列表** 而不是用户名进行访问控制
- **监控日志** 查看令牌刷新事件和连接状态
- **最小化令牌权限范围** - 只请求 `chat:read` 和 `chat:write`
- **如果卡住**：在确认没有其他进程拥有会话后重启 Gateway 网关
## 限制
- 每条消息最多 **500 个字符**（按词边界自动分块）
- 分块前会移除 Markdown 格式
- 每条消息 **500 个字符**（在单词边界自动分块）
- 分块前会去除 Markdown
- 无速率限制（使用 Twitch 内置的速率限制）
docs/zh-CN/channels/whatsapp.md
+121 -120
View File
@@ -4,24 +4,24 @@ read_when:
summary: WhatsApp（网页渠道）集成：登录、收件箱、回复、媒体和运维
title: WhatsApp
x-i18n:
generated_at: "2026-02-01T20:00:02Z"
generated_at: "2026-02-03T07:46:24Z"
model: claude-opus-4-5
provider: pi
source_hash: 44fd88f8e269284999e5a5a52b230edae6e6f978528dd298d6a5603d03c0c38d
source_path: channels/whatsapp.md
workflow: 14
workflow: 15
---
# WhatsApp（网页渠道）
状态：仅支持通过 Baileys 的 WhatsApp Web。Gateway网关拥有会话。
状态：仅支持通过 Baileys 的 WhatsApp Web。Gateway 网关拥有会话。
## 快速设置（入门）
## 快速设置（新手）
1. 如果可能，使用**单独的手机号码**（推荐）。
2. 在 `~/.openclaw/openclaw.json` 中配置 WhatsApp。
3. 运行 `openclaw channels login` 扫描二维码（已关联设备）。
4. 启动 Gateway网关。
3. 运行 `openclaw channels login` 扫描二维码（关联设备）。
4. 启动 Gateway 网关。
最小配置：
@@ -38,13 +38,13 @@ x-i18n:
## 目标
- 单个 Gateway网关进程中支持多个 WhatsApp 账号（多账号）。
- 在一个 Gateway 网关进程中支持多个 WhatsApp 账户（多账户）。
- 确定性路由：回复返回到 WhatsApp，无模型路由。
- 模型获得足够的上下文以理解引用回复。
- 模型能看到足够的上下文来理解引用回复。
## 配置写入
默认情况下，WhatsApp 允许通过 `/config set|unset` 触发配置更新写入（需要 `commands.config: true`）。
默认情况下，WhatsApp 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。
禁用方式：
@@ -54,21 +54,21 @@ x-i18n:
}
```
## 架构（职责划分）
## 架构（谁拥有什么）
- **Gateway网关** 拥有 Baileys socket 和收件箱循环。
- **CLI / macOS 应用** 与 Gateway网关通信；不直接使用 Baileys。
- **活跃监听器** 是出站发送的必要条件；否则发送会快速失败。
- **Gateway 网关**拥有 Baileys socket 和收件箱循环。
- **CLI / macOS 应用**与 Gateway 网关通信；不直接使用 Baileys。
- 发送出站消息需要**活跃的监听器**；否则发送会快速失败。
## 获取手机号码（两种模式）
WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会被屏蔽。在 WhatsApp 上运行 OpenClaw 有两种支持的方式：
WhatsApp 需要真实手机号码进行验证。VoIP 和虚拟号码通常会被封锁。在 WhatsApp 上运行 OpenClaw 有两种支持的方式：
### 专用号码（推荐）
为 OpenClaw 使用**单独的手机号码**。最佳用户体验，干净的路由，无自聊天问题。理想设置：**备用/旧 Android 手机 + eSIM**。保持 Wi-Fi 和充电连接，通过二维码关联。
为 OpenClaw 使用**单独的手机号码**。最佳用户体验，清晰的路由，无自聊天怪异问题。理想设置：**备用/旧 Android 手机 + eSIM**。保持 Wi-Fi 和电源连接，通过二维码关联。
**WhatsApp Business：** 你可以在同一设备上使用不同号码的 WhatsApp Business。非常适合将个人 WhatsApp 分开 — 安装 WhatsApp Business 并在其中注册 OpenClaw 号码。
**WhatsApp Business：** 你可以在同一设备上使用不同号码的 WhatsApp Business。非常适合将个人 WhatsApp 分开——安装 WhatsApp Business 并在那里注册 OpenClaw 号码。
**示例配置（专用号码，单用户允许列表）：**
@@ -84,13 +84,13 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会
```
**配对模式（可选）：**
如果你想使用配对而非允许列表，将 `channels.whatsapp.dmPolicy` 设置为 `pairing`。未知发送者会收到配对码；通过以下命令批准：
如果你想使用配对而不是允许列表，请将 `channels.whatsapp.dmPolicy` 设置为 `pairing`。未知发送者会收到配对码；使用以下命令批准：
`openclaw pairing approve whatsapp <code>`
### 个人号码（备选方案）
快速备选方案：在**你自己的号码**上运行 OpenClaw。给自己发消息（WhatsApp "给自己发消息"）进行测试，避免打扰联系人。在设置和实验期间，需要在主手机上读取验证码。**必须启用自聊天模式。**
当向导询问你的个人 WhatsApp 号码时，输入你将用来发消息的手机号（所有者/发送者），而不是助手号码。
快速备选方案：在**你自己的号码**上运行 OpenClaw。给自己发消息（WhatsApp"给自己发消息"）进行测试，这样就不会打扰联系人。在设置和实验期间需要在主手机上阅读验证码。**必须启用自聊天模式。**
当向导询问你的个人 WhatsApp 号码时，输入你将用于发送消息的手机（所有者/发送者），而不是助手号码。
**示例配置（个人号码，自聊天）：**
@@ -104,64 +104,65 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会
}
```
当设置了 `messages.responsePrefix` 时，自聊天回复默认使用 `[{identity.name}]`（否则为 `[openclaw]`）。
如果 `messages.responsePrefix` 未设置，则使用默认值。显式设置可自定义或禁用前缀（使用 `""` 来移除）。
当设置了 `identity.name` 时，自聊天回复默认为 `[{identity.name}]`（否则为 `[openclaw]`），
前提是 `messages.responsePrefix` 未设置。明确设置它可以自定义或禁用
前缀（使用 `""` 来移除）。
### 号码获取技巧
### 号码获取提示
- **本国 eSIM**，来自你所在国家的移动运营商（最可靠）
- **本地 eSIM** 来自你所在国家的移动运营商（最可靠）
- 奥地利：[hot.at](https://www.hot.at)
- 英国：[giffgaff](https://www.giffgaff.com) — 免费 SIM 卡，无合约
- **预付费 SIM 卡** — 便宜，只需接收一条验证短信
**避免使用：** TextNow、Google Voice、大多数"免费短信"服务 — WhatsApp 会积极屏蔽这些号码。
**避免：** TextNow、Google Voice、大多数"免费短信"服务——WhatsApp 会积极封锁这些。
**提示：** 该号码只需接收一条验证短信。之后，WhatsApp Web 会话通过 `creds.json` 持久保存。
**提示：** 该号码只需要接收一条验证短信。之后，WhatsApp Web 会话通过 `creds.json` 持久化。
## 为什么不用 Twilio？
- 早期 OpenClaw 版本支持 Twilio 的 WhatsApp Business 集成。
- WhatsApp Business 号码不适合个人助手。
- Meta 强制执行 24 小时回复窗口；如果你在过去 24 小时内没有回复，商业号码无法发起新消息。
- 高频或"频繁"使用会触发激进的封禁，因为商业账号不适合发送大量个人助手消息。
- 结果：投递不可靠且频繁被封禁，因此已移除支持。
- 高频或"频繁"使用会触发激进的封锁，因为商业账户不适合发送大量个人助手消息。
- 结果：投递不可靠且频繁被封锁，因此该支持已被移除。
## 登录 + 凭证
- 登录命令：`openclaw channels login`（通过已关联设备扫描二维码）。
- 多账号登录：`openclaw channels login --account <id>`（`<id>` = `accountId`）。
- 默认账号（省略 `--account` 时）：如果存在则为 `default`，否则为第一个已配置的账号 ID（排序后）。
- 登录命令：`openclaw channels login`（通过关联设备扫描二维码）。
- 多账户登录：`openclaw channels login --account <id>`（`<id>` = `accountId`）。
- 默认账户（省略 `--account` 时）：如果存在则为 `default`，否则为第一个配置的账户 id（排序后）。
- 凭证存储在 `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`。
- 备份副本位于 `creds.json.bak`（损坏时恢复）。
- 旧版兼容：早期安装将 Baileys 文件直接存储在 `~/.openclaw/credentials/`。
- 注销：`openclaw channels logout`（或 `--account <id>`）删除 WhatsApp 认证状态（但保留共享的 `oauth.json`）。
- 已注销的 socket => 错误提示重新关联。
- 备份副本在 `creds.json.bak`（损坏时恢复）。
- 旧版兼容性：较旧的安装将 Baileys 文件直接存储在 `~/.openclaw/credentials/` 中。
- 登出：`openclaw channels logout`（或 `--account <id>`）删除 WhatsApp 认证状态（但保留共享的 `oauth.json`）。
- 已登出的 socket => 错误提示重新关联。
## 入站流程（私聊 + 群聊）
## 入站流程（私信 + 群组）
- WhatsApp 事件来自 `messages.upsert`（Baileys）。
- 收件箱监听器在关闭时解除绑定，以避免在测试/重启中累积事件处理器。
- 收件箱监听器在关闭时分离，以避免在测试/重启时累积事件处理器。
- 状态/广播聊天被忽略。
- 私聊使用 E.164 格式；群聊使用群组 JID。
- **私聊策略**：`channels.whatsapp.dmPolicy` 控制私聊访问（默认：`pairing`）。
- 直接聊天使用 E.164；群组使用群组 JID。
- **私信策略**：`channels.whatsapp.dmPolicy` 控制直接聊天访问（默认：`pairing`）。
- 配对：未知发送者会收到配对码（通过 `openclaw pairing approve whatsapp <code>` 批准；码在 1 小时后过期）。
- 开放：需要 `channels.whatsapp.allowFrom` 包含 `"*"`。
- 你关联的 WhatsApp 号码被隐式信任，因此自消息跳过 `channels.whatsapp.dmPolicy` 和 `channels.whatsapp.allowFrom` 检查。
- 你关联的 WhatsApp 号码是隐式信任的，因此自身消息会跳过 `channels.whatsapp.dmPolicy` 和 `channels.whatsapp.allowFrom` 检查。
### 个人号码模式（备选方案）
如果你在**个人 WhatsApp 号码**上运行 OpenClaw，启用 `channels.whatsapp.selfChatMode`（参见上方示例配置）。
如果你在**个人 WhatsApp 号码**上运行 OpenClaw，请启用 `channels.whatsapp.selfChatMode`（见上面的示例）。
行为：
- 出站私聊消息不会触发配对回复（防止骚扰联系人）。
- 出站私信永远不会触发配对回复（防止打扰联系人）。
- 入站未知发送者仍遵循 `channels.whatsapp.dmPolicy`。
- 自聊天模式（allowFrom 包含你的号码）避免自动已读回执并忽略提及 JID。
- 非自聊天私聊会发送已读回执。
- 非自聊天私信会发送已读回执。
## 已读回执
默认情况下，Gateway网关会在接受入站 WhatsApp 消息后将其标记为已读（蓝色对勾）。
默认情况下，Gateway 网关在接受入站 WhatsApp 消息后将其标记为已读（蓝色勾号）。
全局禁用：
@@ -171,7 +172,7 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会
}
```
按账号禁用：
按账户禁用：
```json5
{
@@ -185,31 +186,31 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会
}
```
备注：
注意事项：
- 自聊天模式始终跳过已读回执。
## WhatsApp 常见问题：发送消息 + 配对
**关联 WhatsApp 后，OpenClaw 会给随机联系人发消息吗？**
不会。默认私聊策略是**配对**，因此未知发送者只会收到配对码，其消息**不会被处理**。OpenClaw 只回复收到的聊天，或你显式触发的发送（智能体/CLI）。
**当我关联 WhatsApp 时，OpenClaw 会给随机联系人发消息吗？**
不会。默认私信策略是**配对**，因此未知发送者只会收到配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你明确触发的发送（智能体/CLI）。
**WhatsApp 上的配对是如何工作的？**
配对是针对未知发送者的私聊门控：
配对是未知发送者的私信门控：
- 新发送者的首条私聊消息会返回一个短码（消息不会被处理）。
- 通过以下命令批准：`openclaw pairing approve whatsapp <code>`（用 `openclaw pairing list whatsapp` 列出）。
- 来自新发送者的第一条私信返回一个短码（消息不会被处理）。
- 使用以下命令批准：`openclaw pairing approve whatsapp <code>`（使用 `openclaw pairing list whatsapp` 列出）。
- 码在 1 小时后过期；每个渠道的待处理请求上限为 3 个。
**多人可以在同一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗？**
可以，通过 `bindings` 将每个发送者路由到不同的智能体（peer `kind: "dm"`，发送者 E.164 如 `+15551234567`）。回复仍然来自**同一个 WhatsApp 账号**，且私聊会折叠到每个智能体的主会话，因此请使用**每人一个智能体**。私聊访问控制（`dmPolicy`/`allowFrom`）在每个 WhatsApp 账号级别是全局的。参见[多智能体路由](/concepts/multi-agent)。
**多个人可以在一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗？**
可以，通过 `bindings` 将每个发送者路由到不同的智能体（peer `kind: "dm"`，发送者 E.164 如 `+15551234567`）。回复仍然来自**同一个 WhatsApp 账户**，直接聊天会折叠到每个智能体的主会话，因此**每人使用一个智能体**。私信访问控制（`dmPolicy`/`allowFrom`）是每个 WhatsApp 账户全局的。参见[多智能体路由](/concepts/multi-agent)。
**为什么向导要询问我的手机号码？**
向导使用它来设置你的**允许列表/所有者**，以便允许你自己的私聊消息。它不用于自动发送。如果你在个人 WhatsApp 号码上运行，使用相同的号码并启用 `channels.whatsapp.selfChatMode`。
**为什么向导会询问我的手机号码？**
向导使用它来设置你的**允许列表/所有者**，以便允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用相同的号码并启用 `channels.whatsapp.selfChatMode`。
## 消息标准化（模型看到的内容）
## 消息规范化（模型看到的内容）
- `Body` 是当前消息正文及其信封。
- `Body` 是带有信封的当前消息正文。
- 引用回复上下文**始终附加**：
```
[Replying to +1555 id:ABC123]
@@ -219,35 +220,35 @@ WhatsApp 需要真实的手机号码进行验证。VoIP 和虚拟号码通常会
- 回复元数据也会设置：
- `ReplyToId` = stanzaId
- `ReplyToBody` = 引用正文或媒体占位符
- `ReplyToSender` = E.164（已知时）
- `ReplyToSender` = 已知时为 E.164
- 纯媒体入站消息使用占位符：
- `<media:image|video|audio|document|sticker>`
## 群聊
## 群组
- 群聊映射到 `agent:<agentId>:whatsapp:group:<jid>` 会话。
- 群聊策略：`channels.whatsapp.groupPolicy = open|disabled|allowlist`（默认 `allowlist`）。
- 群组映射到 `agent:<agentId>:whatsapp:group:<jid>` 会话。
- 群组策略：`channels.whatsapp.groupPolicy = open|disabled|allowlist`（默认 `allowlist`）。
- 激活模式：
- `mention`（默认）：需要 @提及或正则匹配。
- `always`：始终触发。
- `/activation mention|always` 仅限所有者且必须作为独立消息发送。
- 所有者 = `channels.whatsapp.allowFrom`（未设置时为自身 E.164）。
- `/activation mention|always` 仅限所有者，必须作为独立消息发送。
- 所有者 = `channels.whatsapp.allowFrom`（如果未设置则为自身 E.164）。
- **历史注入**（仅待处理）：
- 最近*未处理*的消息（默认 50 条）插入在：
`[Chat messages since your last reply - for context]`（已在会话中的消息不会被重复注入）
- 当前消息位于：
`[Chat messages since your last reply - for context]`（已在会话中的消息不会重新注入）
- 当前消息在：
`[Current message - respond to this]`
- 发送者后缀附加：`[from: Name (+E164)]`
- 群聊元数据缓存 5 分钟（主题 + 参与者）。
- 附加发送者后缀：`[from: Name (+E164)]`
- 群组元数据缓存 5 分钟（主题 + 参与者）。
## 回复投递（线程）
- WhatsApp Web 发送标准消息（当前 Gateway网关中无引用回复线程）。
- WhatsApp Web 发送标准消息（当前 Gateway 网关无引用回复线程）。
- 此渠道忽略回复标签。
## 确认反应（收到消息时自动反应）
## 确认表情（收到时自动回应）
WhatsApp 可以在收到消息时立即自动发送表情反应，在机器人生成回复之前。这为用户提供即时反馈，表明其消息已收到。
WhatsApp 可以在收到传入消息时立即自动发送表情回应，在机器人生成回复之前。这为用户提供即时反馈，表明他们的消息已收到。
**配置：**
@@ -265,14 +266,14 @@ WhatsApp 可以在收到消息时立即自动发送表情反应，在机器人
**选项：**
- `emoji`（字符串）：用于确认的表情（例如 "👀"、"✅"、"📨"）。为空或省略 = 功能禁用。
- `direct`（布尔值，默认：`true`）：在私聊/私信 中发送反应。
- `emoji`（字符串）：用于确认的表情（例如"👀"、"✅"、"📨"）。为空或省略 = 功能禁用。
- `direct`（布尔值，默认：`true`）：在直接/私信聊天中发送表情回应。
- `group`（字符串，默认：`"mentions"`）：群聊行为：
- `"always"`：对所有群聊消息做出反应（即使没有 @提及）
- `"mentions"`：仅在机器人被 @提及时做出反应
- `"never"`：从不在群聊中做出反应
- `"always"`：对所有群消息做出回应（即使没有 @提及）
- `"mentions"`：仅在机器人被 @提及时做出回应
- `"never"`：从不在群组中做出回应
**按账号覆盖：**
**按账户覆盖：**
```json
{
@@ -292,42 +293,42 @@ WhatsApp 可以在收到消息时立即自动发送表情反应，在机器人
**行为说明：**
- 反应在收到消息时**立即**发送，在输入指示器或机器人回复之前。
- 在 `requireMention: false`（激活模式：always）的群组中，`group: "mentions"` 会对所有消息做出反应（不仅仅是 @提及）。
- 即发即忘：反应失败会被记录但不会阻止机器人回复。
- 群聊反应会自动包含参与者 JID。
- 表情回应在消息收到时**立即**发送，在输入指示器或机器人回复之前。
- 在 `requireMention: false`（激活：always）的群组中，`group: "mentions"` 会对所有消息做出回应（不仅仅是 @提及）。
- 即发即忘：表情回应失败会被记录但不会阻止机器人回复。
- 群组表情回应会自动包含参与者 JID。
- WhatsApp 忽略 `messages.ackReaction`；请改用 `channels.whatsapp.ackReaction`。
## 智能体工具（反应）
## 智能体工具（表情回应）
- 工具：`whatsapp`，使用 `react` 动作（`chatJid`、`messageId`、`emoji`，可选 `remove`）。
- 可选：`participant`（群聊发送者）、`fromMe`（对自己的消息做出反应）、`accountId`（多账号）。
- 反应移除语义：参见 [/tools/reactions](/tools/reactions)。
- 工具：`whatsapp`，带有 `react` 动作（`chatJid`、`messageId`、`emoji`，可选 `remove`）。
- 可选：`participant`（群组发送者）、`fromMe`（对自己的消息做出回应）、`accountId`（多账户）。
- 表情移除语义：参见 [/tools/reactions](/tools/reactions)。
- 工具门控：`channels.whatsapp.actions.reactions`（默认：启用）。
## 限制
- 出站文本按 `channels.whatsapp.textChunkLimit` 分块（默认 4000）。
- 可选换行分块：设置 `channels.whatsapp.chunkMode="newline"` 在空行（段落边界）处分割，再进行长度分块。
- 可选换行分块：设置 `channels.whatsapp.chunkMode="newline"` 在长度分块之前按空行（段落边界）分割。
- 入站媒体保存受 `channels.whatsapp.mediaMaxMb` 限制（默认 50 MB）。
- 出站媒体项受 `agents.defaults.mediaMaxMb` 限制（默认 5 MB）。
## 出站发送（文本 + 媒体）
- 使用活跃的网页监听器；如果 Gateway网关未运行则报错。
- 使用活跃的网页监听器；如果 Gateway 网关未运行则报错。
- 文本分块：每条消息最大 4k（可通过 `channels.whatsapp.textChunkLimit` 配置，可选 `channels.whatsapp.chunkMode`）。
- 媒体：
- 支持图片/视频/音频/文档。
- 音频以 PTT 发送；`audio/ogg` => `audio/ogg; codecs=opus`。
- 仅第一个媒体项带字幕。
- 音频作为 PTT 发送；`audio/ogg` => `audio/ogg; codecs=opus`。
- 仅在第一个媒体项上添加标题。
- 媒体获取支持 HTTP(S) 和本地路径。
- 动态 GIF：WhatsApp 期望带 `gifPlayback: true` 的 MP4 以实现内联循环播放。
- 动画 GIF：WhatsApp 期望带有 `gifPlayback: true` 的 MP4 以实现内联循环。
- CLI：`openclaw message send --media <mp4> --gif-playback`
- Gateway网关：`send` 参数包含 `gifPlayback: true`
- Gateway 网关：`send` 参数包含 `gifPlayback: true`
## 语音消息（PTT 音频）
WhatsApp 以**语音消息**（PTT 气泡）发送音频。
WhatsApp 将音频作为**语音消息**（PTT 气泡）发送。
- 最佳效果：OGG/Opus。OpenClaw 将 `audio/ogg` 重写为 `audio/ogg; codecs=opus`。
- WhatsApp 忽略 `[[audio_as_voice]]`（音频已作为语音消息发送）。
@@ -336,43 +337,43 @@ WhatsApp 以**语音消息**（PTT 气泡）发送音频。
- 默认出站上限：5 MB（每个媒体项）。
- 覆盖：`agents.defaults.mediaMaxMb`。
- 图片会自动优化为 JPEG 以控制在上限内（缩放 + 质量扫描）。
- 超大媒体 => 错误；媒体回复回退为文本警告。
- 图片自动优化为上限以下的 JPEG（调整大小 + 质量扫描）。
- 超大媒体 => 错误；媒体回复降级为文本警告。
## 心跳
- **Gateway网关心跳** 记录连接健康状态（`web.heartbeatSeconds`，默认 60 秒）。
- **智能体心跳** 可按智能体配置（`agents.list[].heartbeat`）或通过
`agents.defaults.heartbeat` 全局配置（未设置每智能体条目时的回退）。
- 使用配置的心跳提示（默认：`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_OK` 跳过行为。
- 投递默认到最后使用的渠道（或已配置的目标）。
- **Gateway 网关心跳**记录连接健康状态（`web.heartbeatSeconds`，默认 60 秒）。
- **智能体心跳**可以按智能体配置（`agents.list[].heartbeat`）或通过
`agents.defaults.heartbeat` 全局配置（当没有设置按智能体条目时的降级）。
- 使用配置的心跳提示词（默认：`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_OK` 跳过行为。
- 投递默认为最后使用的渠道（或配置的目标）。
## 重连行为
- 退避策略：`web.reconnect`：
- `initialMs`、`maxMs`、`factor`、`jitter`、`maxAttempts`。
- 如果达到 maxAttempts，网页监控停止（降级）。
- 已注销 => 停止并要求重新关联。
- 已登出 => 停止并要求重新关联。
## 配置速查表
## 配置快速映射
- `channels.whatsapp.dmPolicy`（私聊策略：pairing/allowlist/open/disabled）。
- `channels.whatsapp.selfChatMode`（同号设置；机器人使用你的个人 WhatsApp 号码）。
- `channels.whatsapp.allowFrom`（私聊允许列表）。WhatsApp 使用 E.164 手机号码（无用户名）。
- `channels.whatsapp.dmPolicy`（私信策略：pairing/allowlist/open/disabled）。
- `channels.whatsapp.selfChatMode`（同手机设置；机器人使用你的个人 WhatsApp 号码）。
- `channels.whatsapp.allowFrom`（私信允许列表）。WhatsApp 使用 E.164 手机号码（无用户名）。
- `channels.whatsapp.mediaMaxMb`（入站媒体保存上限）。
- `channels.whatsapp.ackReaction`（消息收到时的自动反应：`{emoji, direct, group}`）。
- `channels.whatsapp.accounts.<accountId>.*`（按账号设置 + 可选 `authDir`）。
- `channels.whatsapp.accounts.<accountId>.mediaMaxMb`（按账号入站媒体上限）。
- `channels.whatsapp.accounts.<accountId>.ackReaction`（按账号确认反应覆盖）。
- `channels.whatsapp.groupAllowFrom`（群聊发送者允许列表）。
- `channels.whatsapp.groupPolicy`（群聊策略）。
- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts.<accountId>.historyLimit`（群聊历史上下文；`0` 禁用）。
- `channels.whatsapp.dmHistoryLimit`（私聊历史限制，按用户轮数）。按用户覆盖：`channels.whatsapp.dms["<phone>"].historyLimit`。
- `channels.whatsapp.groups`（群聊允许列表 + 提及门控默认值；使用 `"*"` 允许全部）
- `channels.whatsapp.actions.reactions`（WhatsApp 工具反应门控）。
- `channels.whatsapp.ackReaction`（消息收到时的自动回应：`{emoji, direct, group}`）。
- `channels.whatsapp.accounts.<accountId>.*`（按账户设置 + 可选 `authDir`）。
- `channels.whatsapp.accounts.<accountId>.mediaMaxMb`（按账户入站媒体上限）。
- `channels.whatsapp.accounts.<accountId>.ackReaction`（按账户确认回应覆盖）。
- `channels.whatsapp.groupAllowFrom`（群组发送者允许列表）。
- `channels.whatsapp.groupPolicy`（群组策略）。
- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts.<accountId>.historyLimit`（群组历史上下文；`0` 禁用）。
- `channels.whatsapp.dmHistoryLimit`（私信历史限制，按用户轮次）。按用户覆盖：`channels.whatsapp.dms["<phone>"].historyLimit`。
- `channels.whatsapp.groups`（群组允许列表 + 提及门控默认值；使用 `"*"` 允许全部）
- `channels.whatsapp.actions.reactions`（门控 WhatsApp 工具表情回应）。
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）
- `messages.groupChat.historyLimit`
- `channels.whatsapp.messagePrefix`（入站前缀；按账号：`channels.whatsapp.accounts.<accountId>.messagePrefix`；已弃用：`messages.messagePrefix`）
- `channels.whatsapp.messagePrefix`（入站前缀；按账户：`channels.whatsapp.accounts.<accountId>.messagePrefix`；已弃用：`messages.messagePrefix`）
- `messages.responsePrefix`（出站前缀）
- `agents.defaults.mediaMaxMb`
- `agents.defaults.heartbeat.every`
@@ -390,21 +391,21 @@ WhatsApp 以**语音消息**（PTT 气泡）发送音频。
- 子系统：`whatsapp/inbound`、`whatsapp/outbound`、`web-heartbeat`、`web-reconnect`。
- 日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`（可配置）。
- 故障排除指南：[Gateway网关故障排除](/gateway/troubleshooting)。
- 故障排除指南：[Gateway 网关故障排除](/gateway/troubleshooting)。
## 故障排除（快速）
**未关联 / 需要二维码登录**
- 症状：`channels status` 显示 `linked: false` 或警告"未关联"。
- 修复：在 Gateway网关主机上运行 `openclaw channels login` 并扫描二维码（WhatsApp → 设置 → 已关联设备）。
- 症状：`channels status` 显示 `linked: false` 或警告"Not linked"。
- 修复：在 Gateway 网关主机上运行 `openclaw channels login` 并扫描二维码（WhatsApp → 设置 → 关联设备）。
**已关联但断开连接 / 重连循环**
- 症状：`channels status` 显示 `running, disconnected` 或警告"已关联但断开连接"。
- 修复：`openclaw doctor`（或重启 Gateway网关）。如果问题持续，通过 `channels login` 重新关联并检查 `openclaw logs --follow`。
- 症状：`channels status` 显示 `running, disconnected` 或警告"Linked but disconnected"。
- 修复：`openclaw doctor`（或重启 Gateway 网关）。如果问题持续，通过 `channels login` 重新关联并检查 `openclaw logs --follow`。
**Bun 运行时**
- **不推荐**使用 Bun。WhatsApp（Baileys）和 Telegram 在 Bun 上不稳定。
请使用 **Node** 运行 Gateway网关。（参见入门指南运行时说明。）
- **不推荐** Bun。WhatsApp（Baileys）和 Telegram 在 Bun 上不可靠。
请使用 **Node** 运行 Gateway 网关。（参见入门指南运行时说明。）
docs/zh-CN/channels/zalo.md
+62 -62
View File
@@ -1,40 +1,40 @@
---
read_when:
- 处理 Zalo 功能或 webhook 时
summary: Zalo 机器人支持状态、功能和配置
- 开发 Zalo 功能或 webhooks
summary: Zalo bot 支持状态、功能和配置
title: Zalo
x-i18n:
generated_at: "2026-02-01T19:58:32Z"
generated_at: "2026-02-03T07:44:44Z"
model: claude-opus-4-5
provider: pi
source_hash: 0311d932349f96412b712970b5d37329b91929bf3020536edf3ca0ff464373c0
source_path: channels/zalo.md
workflow: 14
workflow: 15
---
# Zalo (Bot API)
状态：实验性。仅支持私信；根据 Zalo 文档，群组功能即将推出。
状态：实验性。仅支持私信；根据 Zalo 文档，群组即将推出。
## 需要插件
Zalo 以插件形式提供，不包含在核心安装中。
- 通过 CLI 安装：`openclaw plugins install @openclaw/zalo`
- 或在新手引导中选择 **Zalo** 并确认安装提示
- 或在新手引导期间选择 **Zalo** 并确认安装提示
- 详情：[插件](/plugin)
## 快速设置（新手）
## 快速设置（初学者）
1. 安装 Zalo 插件：
- 从源码检出安装：`openclaw plugins install ./extensions/zalo`
- 从 npm 安装（如已发布）：`openclaw plugins install @openclaw/zalo`
- 从源代码检出：`openclaw plugins install ./extensions/zalo`
- 从 npm（如果已发布）：`openclaw plugins install @openclaw/zalo`
- 或在新手引导中选择 **Zalo** 并确认安装提示
2. 设置令牌：
2. 设置 token：
- 环境变量：`ZALO_BOT_TOKEN=...`
- 或配置：`channels.zalo.botToken: "..."`。
3. 重启 Gateway网关（或完成新手引导）。
4. 私信访问默认使用配对模式；首次联系时需批准配对码。
3. 重启 Gateway 网关（或完成新手引导）。
4. 私信访问默认为配对模式；首次联系时批准配对码。
最小配置：
@@ -50,25 +50,25 @@ Zalo 以插件形式提供，不包含在核心安装中。
}
```
## 简介
## 它是什么
Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gateway网关运行一个用于一对一对话的机器人。
它非常适合需要将消息确定性路由回 Zalo 的客服或通知场景。
Zalo 是一款专注于越南市场的即时通讯应用；其 Bot API 让 Gateway 网关可以运行一个用于一对一对话的 bot。
它非常适合需要确定性路由回 Zalo 的支持或通知场景。
- 由 Gateway网关管理的 Zalo Bot API 渠道。
- 确定性路由：回复始终返回 Zalo；模型不会选择渠道。
- 由 Gateway 网关拥有的 Zalo Bot API 渠道。
- 确定性路由：回复返回到 Zalo；模型不会选择渠道。
- 私信共享智能体的主会话。
- 群组尚不支持（Zalo 文档标注"即将推出"）。
## 设置（快速路径）
### 1) 创建机器人令牌（Zalo Bot Platform）
### 1）创建 bot token（Zalo Bot 平台）
1. 前往 **https://bot.zaloplatforms.com** 并登录。
2. 创建新机器人并配置其设置。
3. 复制机器人令牌（格式：`12345689:abc-xyz`）。
2. 创建新 bot 并配置其设置。
3. 复制 bot token（格式：`12345689:abc-xyz`）。
### 2) 配置令牌（环境变量或配置文件）
### 2）配置 token（环境变量或配置）
示例：
@@ -86,49 +86,49 @@ Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gatew
环境变量选项：`ZALO_BOT_TOKEN=...`（仅适用于默认账户）。
多账户支持：使用 `channels.zalo.accounts`，为每个账户配置令牌和可选的 `name`。
多账户支持：使用 `channels.zalo.accounts` 配置每账户 token 和可选的 `name`。
3. 重启 Gateway网关。当令牌被解析（通过环境变量或配置）时，Zalo 将启动。
4. 私信访问默认使用配对模式。机器人首次被联系时，请批准配对码。
3. 重启 Gateway 网关。当 token 被解析（环境变量或配置）时，Zalo 启动。
4. 私信访问默认为配对模式。当 bot 首次被联系时批准配对码。
## 工作原理（行为）
- 入站消息被标准化为共享渠道信封，并包含媒体占位符。
- 回复始终路由回同一个 Zalo 聊天。
- 入站消息被规范化为带有媒体占位符的共享渠道信封。
- 回复始终路由回同一 Zalo 聊天。
- 默认使用长轮询；可通过 `channels.zalo.webhookUrl` 启用 webhook 模式。
## 限制
- 出站文本按 2000 字符分块（Zalo API 限制）。
- 媒体下载/上传受 `channels.zalo.mediaMaxMb` 限制（默认 5）。
- 由于 2000 字符限制导致流式传输意义不大，默认禁用流式传输。
- 由于 2000 字符限制使流式传输效果不佳，默认阻止流式传输。
## 访问控制（私信）
### 私信访问
- 默认：`channels.zalo.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前将被忽略（配对码 1 小时后过期）。
- 批准方式：
- 默认：`channels.zalo.dmPolicy = "pairing"`。未知发送者会收到配对码；消息在批准前会被忽略（配对码 1 小时后过期）。
- 通过以下方式批准：
- `openclaw pairing list zalo`
- `openclaw pairing approve zalo <CODE>`
- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
- `channels.zalo.allowFrom` 接受数字用户 ID（不支持用户名查找）。
- `channels.zalo.allowFrom` 接受数字用户 ID（无用户名查找功能）。
## 长轮询与 webhook
- 默认：长轮询（无需公网 URL）。
- 默认：长轮询（不需要公共 URL）。
- Webhook 模式：设置 `channels.zalo.webhookUrl` 和 `channels.zalo.webhookSecret`。
- Webhook 密钥必须为 8-256 个字符。
- Webhook secret 必须为 8-256 个字符。
- Webhook URL 必须使用 HTTPS。
- Zalo 通过 `X-Bot-Api-Secret-Token` 请求头发送事件以进行验证。
- Gateway网关 HTTP 在 `channels.zalo.webhookPath` 处理 webhook 请求（默认为 webhook URL 路径）。
- Zalo 发送事件时带有 `X-Bot-Api-Secret-Token` 头用于验证。
- Gateway 网关 HTTP 在 `channels.zalo.webhookPath` 处理 webhook 请求（默认为 webhook URL 路径）。
**注意：** 根据 Zalo API 文档，getUpdates（轮询）和 webhook 互斥。
**注意：** 根据 Zalo API 文档，getUpdates（轮询）和 webhook 是互斥的。
## 支持的消息类型
- **文本消息**：完全支持，按 2000 字符分块。
- **图片消息**：下载并处理入站图片；通过 `sendPhoto` 发送图片。
- **文本消息**：完全支持，2000 字符分块。
- **图片消息**：下载和处理入站图片；通过 `sendPhoto` 发送图片。
- **贴纸**：已记录但未完全处理（无智能体响应）。
- **不支持的类型**：已记录（例如来自受保护用户的消息）。
@@ -140,30 +140,30 @@ Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gatew
| 群组 | ❌ 即将推出（根据 Zalo 文档） |
| 媒体（图片） | ✅ 支持 |
| 表情回应 | ❌ 不支持 |
| 话题 | ❌ 不支持 |
| 主题 | ❌ 不支持 |
| 投票 | ❌ 不支持 |
| 原生命令 | ❌ 不支持 |
| 流式传输 | ⚠️ 已禁用（2000 字符限制） |
| 流式传输 | ⚠️ 已阻止（2000 字符限制） |
## 投递目标（CLI/定时任务）
## 投递目标（CLI/cron）
- 使用聊天 ID 作为目标。
- 使用聊天 id 作为目标。
- 示例：`openclaw message send --channel zalo --target 123456789 --message "hi"`。
## 故障排除
**机器人无响应：**
**Bot 不响应：**
- 检查令牌是否有效：`openclaw channels status --probe`
- 验证发送者是否已批准（配对或 allowFrom）
- 检查 Gateway网关日志：`openclaw logs --follow`
- 检查 token 是否有效：`openclaw channels status --probe`
- 验证发送者已被批准（配对或 allowFrom）
- 检查 Gateway 网关日志：`openclaw logs --follow`
**Webhook 未收到事件：**
- 确保 webhook URL 使用 HTTPS
- 验证密钥令牌为 8-256 个字符
- 确认 Gateway网关 HTTP 端点在配置的路径上可达
- 检查 getUpdates 轮询是否未在运行（两者互斥）
- 验证 secret token 为 8-256 个字符
- 确认 Gateway 网关 HTTP 端点在配置的路径上可访问
- 检查 getUpdates 轮询未在运行（它们是互斥的）
## 配置参考（Zalo）
@@ -172,25 +172,25 @@ Zalo 是一款面向越南市场的即时通讯应用；其 Bot API 允许 Gatew
提供商选项：
- `channels.zalo.enabled`：启用/禁用渠道启动。
- `channels.zalo.botToken`：来自 Zalo Bot Platform 的机器人令牌。
- `channels.zalo.tokenFile`：从文件路径读取令牌。
- `channels.zalo.botToken`：来自 Zalo Bot 平台的 bot token。
- `channels.zalo.tokenFile`：从文件路径读取 token。
- `channels.zalo.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。
- `channels.zalo.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。向导会要求输入数字 ID。
- `channels.zalo.mediaMaxMb`：入站/出站媒体大小上限（MB，默认 5）。
- `channels.zalo.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。向导会询问数字 ID。
- `channels.zalo.mediaMaxMb`：入站/出站媒体上限（MB，默认 5）。
- `channels.zalo.webhookUrl`：启用 webhook 模式（需要 HTTPS）。
- `channels.zalo.webhookSecret`：webhook 密钥（8-256 个字符）。
- `channels.zalo.webhookPath`：Gateway网关 HTTP 服务器上的 webhook 路径。
- `channels.zalo.webhookSecret`：webhook secret（8-256 字符）。
- `channels.zalo.webhookPath`：Gateway 网关 HTTP 服务器上的 webhook 路径。
- `channels.zalo.proxy`：API 请求的代理 URL。
多账户选项：
- `channels.zalo.accounts.<id>.botToken`：每个账户的令牌。
- `channels.zalo.accounts.<id>.tokenFile`：每个账户的令牌文件。
- `channels.zalo.accounts.<id>.botToken`：每账户 token。
- `channels.zalo.accounts.<id>.tokenFile`：每账户 token 文件。
- `channels.zalo.accounts.<id>.name`：显示名称。
- `channels.zalo.accounts.<id>.enabled`：启用/禁用账户。
- `channels.zalo.accounts.<id>.dmPolicy`：每个账户的私信策略。
- `channels.zalo.accounts.<id>.allowFrom`：每个账户的允许列表。
- `channels.zalo.accounts.<id>.webhookUrl`：每个账户的 webhook URL。
- `channels.zalo.accounts.<id>.webhookSecret`：每个账户的 webhook 密钥。
- `channels.zalo.accounts.<id>.webhookPath`：每个账户的 webhook 路径。
- `channels.zalo.accounts.<id>.proxy`：每个账户的代理 URL。
- `channels.zalo.accounts.<id>.dmPolicy`：每账户私信策略。
- `channels.zalo.accounts.<id>.allowFrom`：每账户允许列表。
- `channels.zalo.accounts.<id>.webhookUrl`：每账户 webhook URL。
- `channels.zalo.accounts.<id>.webhookSecret`：每账户 webhook secret。
- `channels.zalo.accounts.<id>.webhookPath`：每账户 webhook 路径。
- `channels.zalo.accounts.<id>.proxy`：每账户代理 URL。
docs/zh-CN/channels/zalouser.md
+32 -32
View File
@@ -1,27 +1,27 @@
---
read_when:
- 为 OpenClaw 设置 Zalo Personal
- 调试 Zalo Personal 登录或消息流
summary: 通过 zca-cli（二维码登录）支持 Zalo 个人账号，功能与配置说明
- 调试 Zalo Personal 登录或消息流程
summary: 通过 zca-cli（QR 登录）支持 Zalo 个人账户、功能和配置
title: Zalo Personal
x-i18n:
generated_at: "2026-02-01T19:58:27Z"
generated_at: "2026-02-03T07:44:34Z"
model: claude-opus-4-5
provider: pi
source_hash: 2a249728d556e5cc52274627bdaf390fa10e815afa04f4497feb57a2a0cb9261
source_path: channels/zalouser.md
workflow: 14
workflow: 15
---
# Zalo Personal（非官方）
状态：实验性。此集成通过 `zca-cli` 自动化操作一个**个人 Zalo 账号**。
状态：实验性。此集成通过 `zca-cli` 自动化**个人 Zalo 账户**。
> **警告：** 这是一个非官方集成，可能导致账号被暂停或封禁。使用风险自负。
> **警告：**这是一个非官方集成，可能导致账户被暂停/封禁。使用风险自负。
## 需要安装插件
## 需要插件
Zalo Personal 以插件形式提供，不包含在核心安装包中。
Zalo Personal 作为插件提供，不包含在核心安装中。
- 通过 CLI 安装：`openclaw plugins install @openclaw/zalouser`
- 或从源码检出安装：`openclaw plugins install ./extensions/zalouser`
@@ -29,17 +29,17 @@ Zalo Personal 以插件形式提供，不包含在核心安装包中。
## 前置条件：zca-cli
Gateway网关所在机器必须在 `PATH` 中包含 `zca` 可执行文件。
Gateway 网关机器必须在 `PATH` 中有可用的 `zca` 二进制文件。
- 验证：`zca --version`
- 如果缺失，请安装 zca-cli（参见 `extensions/zalouser/README.md` 或上游 zca-cli 文档）。
## 快速设置（入门）
## 快速设置（新手）
1. 安装插件（见上文）。
2. 登录（二维码方式，在 Gateway网关机器上操作）：
2. 登录（QR，在 Gateway 网关机器上）：
- `openclaw channels login --channel zalouser`
- 使用 Zalo 手机应用扫描终端中的二维码。
- 用 Zalo 手机应用扫描终端中的二维码。
3. 启用渠道：
```json5
@@ -53,22 +53,22 @@ Gateway网关所在机器必须在 `PATH` 中包含 `zca` 可执行文件。
}
```
4. 重启 Gateway网关（或完成新手引导）。
5. 私信访问默认为配对模式；首次联系时需批准配对码。
4. 重启 Gateway 网关（或完成新手引导）。
5. 私信访问默认为配对模式；首次联系时批准配对码。
## 功能说明
## 这是什么
- 使用 `zca listen` 接收入站消息。
- 使用 `zca msg ...` 发送回复（文本/媒体/链接）。
- 专为 Zalo Bot API 不可用时的"个人账号"使用场景设计。
- 专为"个人账户"使用场景设计，适用于 Zalo Bot API 不可用的情况。
## 命名说明
## 命名
渠道 ID 为 `zalouser`，以明确表示这是对**个人 Zalo 用户账号**的自动化操作（非官方）。我们将 `zalo` 保留给未来可能的官方 Zalo API 集成。
渠道 ID 为 `zalouser`，以明确表示这是自动化**个人 Zalo 用户账户**（非官方）。我们保留 `zalo` 用于未来可能的官方 Zalo API 集成。
## 查找 ID（通讯录）
## 查找 ID（目录）
使用通讯录 CLI 发现联系人/群组及其 ID：
使用目录 CLI 发现联系人/群组及其 ID：
```bash
openclaw directory self --channel zalouser
@@ -78,13 +78,13 @@ openclaw directory groups list --channel zalouser --query "work"
## 限制
- 出站文本按约 2000 字符分块（Zalo 客户端限制）。
- 流式传输默认被禁用。
- 出站文本分块为约 2000 字符（Zalo 客户端限制）。
- 默认阻止流式传输。
## 访问控制（私信）
`channels.zalouser.dmPolicy` 支持：`pairing | allowlist | open | disabled`（默认：`pairing`）。
`channels.zalouser.allowFrom` 接受用户 ID 或名称。向导在可用时通过 `zca friend find` 将名称解析为 ID。
`channels.zalouser.allowFrom` 接受用户 ID 或名称。向导会在可用时通过 `zca friend find` 将名称解析为 ID。
通过以下方式批准：
@@ -93,13 +93,13 @@ openclaw directory groups list --channel zalouser --query "work"
## 群组访问（可选）
- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。未设置时使用 `channels.defaults.groupPolicy` 覆盖默认值。
- 通过允许列表进行限制：
- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。使用 `channels.defaults.groupPolicy` 在未设置时覆盖默认值。
- 通过以下方式限制为允许列表：
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups`（键为群组 ID 或名称）
- 禁止所有群组：`channels.zalouser.groupPolicy = "disabled"`。
- 配置向导可以提示设置群组允许列表。
- 启动时，OpenClaw 会将允许列表中的群组/用户名称解析为 ID 并记录映射关系；未解析的条目保持原样。
- 阻止所有群组：`channels.zalouser.groupPolicy = "disabled"`。
- 配置向导可以提示输入群组允许列表。
- 启动时，OpenClaw 将允许列表中的群组/用户名称解析为 ID 并记录映射；未解析的条目保持原样。
示例：
@@ -117,9 +117,9 @@ openclaw directory groups list --channel zalouser --query "work"
}
```
## 多账号
## 多账户
账号映射到 zca 配置文件。示例：
账户映射到 zca 配置文件。示例：
```json5
{
@@ -139,9 +139,9 @@ openclaw directory groups list --channel zalouser --query "work"
**找不到 `zca`：**
- 安装 zca-cli 并确保 Gateway网关进程的 `PATH` 中包含该命令。
- 安装 zca-cli 并确保它在 Gateway 网关进程的 `PATH` 中。
**登录状态无法保持：**
**登录不保持：**
- `openclaw channels status --probe`
- 重新登录：`openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`