chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
377b4b522b
commit
dfbb0529cc
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要连接一个 Feishu/Lark 机器人
|
||||
- 你想连接一个 Feishu/Lark 机器人
|
||||
- 你正在配置 Feishu 渠道
|
||||
summary: Feishu 机器人概览、功能和配置
|
||||
title: Feishu
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T22:37:15Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-29T05:57:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 54db77a6bb05d862fe8eb5dfc97d04e4252b20e2b0ccbf204eb49d9d7256b026
|
||||
source_hash: 37de7cbb12821f119ca1a06fcdb8e80a07752e1cbfc462344d24750fbf13147a
|
||||
source_path: channels/feishu.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Feishu / Lark
|
||||
|
||||
Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共享文档、管理日历并协同完成工作。
|
||||
Feishu/Lark 是一体化协作平台，团队可在其中聊天、共享文档、管理日历并协同完成工作。
|
||||
|
||||
**Status：** 适用于机器人私信和群聊的生产就绪状态。WebSocket 是默认模式；webhook 模式为可选。
|
||||
**Status：** 已可用于生产环境中的机器人私信 + 群聊。WebSocket 是默认模式；webhook 模式是可选项。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
<Note>
|
||||
需要 OpenClaw 2026.4.25 或更高版本。运行 `openclaw --version` 进行检查。使用 `openclaw update` 升级。
|
||||
需要 OpenClaw 2026.4.25 或更高版本。运行 `openclaw --version` 检查。使用 `openclaw update` 升级。
|
||||
</Note>
|
||||
|
||||
<Steps>
|
||||
@ -32,7 +32,7 @@ Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共
|
||||
```bash
|
||||
openclaw channels login --channel feishu
|
||||
```
|
||||
使用你的 Feishu/Lark 移动应用扫描二维码，以自动创建一个 Feishu/Lark 机器人。
|
||||
使用你的 Feishu/Lark 移动应用扫描二维码，即可自动创建 Feishu/Lark 机器人。
|
||||
</Step>
|
||||
|
||||
<Step title="设置完成后，重启 Gateway 网关以应用更改">
|
||||
@ -48,11 +48,11 @@ Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共
|
||||
|
||||
### 私信
|
||||
|
||||
配置 `dmPolicy` 以控制谁可以向机器人发送私信：
|
||||
配置 `dmPolicy` 来控制谁可以向机器人发送私信：
|
||||
|
||||
- `"pairing"` — 未知用户会收到配对码；通过 CLI 批准
|
||||
- `"allowlist"` — 只有 `allowFrom` 中列出的用户可以聊天（默认：仅机器人所有者）
|
||||
- `"open"` — 允许所有用户
|
||||
- `"allowlist"` — 只有列在 `allowFrom` 中的用户可以聊天（默认：仅机器人所有者）
|
||||
- `"open"` — 仅当 `allowFrom` 包含 `"*"` 时允许公开私信；如果使用限制性条目，只有匹配的用户可以聊天
|
||||
- `"disabled"` — 禁用所有私信
|
||||
|
||||
**批准配对请求：**
|
||||
@ -68,24 +68,24 @@ openclaw pairing approve feishu <CODE>
|
||||
|
||||
| 值 | 行为 |
|
||||
| ------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `"open"` | 响应群组中的所有消息 |
|
||||
| `"allowlist"` | 仅响应 `groupAllowFrom` 中的群组，或在 `groups.<chat_id>` 下显式配置的群组 |
|
||||
| `"disabled"` | 禁用所有群组消息；显式的 `groups.<chat_id>` 条目不会覆盖此设置 |
|
||||
| `"open"` | 回复群组中的所有消息 |
|
||||
| `"allowlist"` | 只回复 `groupAllowFrom` 中的群组，或在 `groups.<chat_id>` 下显式配置的群组 |
|
||||
| `"disabled"` | 禁用所有群组消息；显式的 `groups.<chat_id>` 条目不会覆盖此设置 |
|
||||
|
||||
默认值：`allowlist`
|
||||
|
||||
**提及要求**（`channels.feishu.requireMention`）：
|
||||
|
||||
- `true` — 需要 @提及（默认）
|
||||
- `false` — 无需 @提及也会响应
|
||||
- `true` — 要求 @提及（默认）
|
||||
- `false` — 无需 @提及也会回复
|
||||
- 按群组覆盖：`channels.feishu.groups.<chat_id>.requireMention`
|
||||
- 仅广播用的 `@all` 和 `@_all` 不会被视为对机器人的提及。如果一条消息同时提及 `@all` 和机器人本身，仍然算作提及了机器人。
|
||||
- 仅用于广播的 `@all` 和 `@_all` 不会被视为机器人提及。同时提及 `@all` 和机器人本身的消息仍会算作机器人提及。
|
||||
|
||||
---
|
||||
|
||||
## 群组配置示例
|
||||
|
||||
### 允许所有群组，不需要 @提及
|
||||
### 允许所有群组，无需 @提及
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -97,7 +97,7 @@ openclaw pairing approve feishu <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
### 允许所有群组，但仍需要 @提及
|
||||
### 允许所有群组，仍然要求 @提及
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -110,21 +110,21 @@ openclaw pairing approve feishu <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
### 仅允许特定群组
|
||||
### 仅允许指定群组
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
groupPolicy: "allowlist",
|
||||
// 群组 ID 类似于：oc_xxx
|
||||
// Group IDs look like: oc_xxx
|
||||
groupAllowFrom: ["oc_xxx", "oc_yyy"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
在 `allowlist` 模式下，你也可以通过添加显式的 `groups.<chat_id>` 条目来准入某个群组。显式条目不会覆盖 `groupPolicy: "disabled"`。`groups.*` 下的通配符默认项会配置匹配的群组，但它们本身不会让群组获得准入。
|
||||
在 `allowlist` 模式下，你也可以通过添加显式的 `groups.<chat_id>` 条目来接纳某个群组。显式条目不会覆盖 `groupPolicy: "disabled"`。`groups.*` 下的通配符默认值会配置匹配的群组，但它们本身不会接纳群组。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -151,7 +151,7 @@ openclaw pairing approve feishu <CODE>
|
||||
groupAllowFrom: ["oc_xxx"],
|
||||
groups: {
|
||||
oc_xxx: {
|
||||
// 用户 open_id 类似于：ou_xxx
|
||||
// User open_ids look like: ou_xxx
|
||||
allowFrom: ["ou_user1", "ou_user2"],
|
||||
},
|
||||
},
|
||||
@ -168,19 +168,19 @@ openclaw pairing approve feishu <CODE>
|
||||
|
||||
### 群组 ID（`chat_id`，格式：`oc_xxx`）
|
||||
|
||||
在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入**设置**。群组 ID（`chat_id`）会显示在设置页面中。
|
||||
在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入**设置**。群组 ID（`chat_id`）会列在设置页面上。
|
||||
|
||||
|
||||
|
||||
|
||||
### 用户 ID（`open_id`，格式：`ou_xxx`）
|
||||
|
||||
启动 Gateway 网关，向机器人发送一条私信，然后查看日志：
|
||||
启动 Gateway 网关，向机器人发送私信，然后检查日志：
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
在日志输出中查找 `open_id`。你也可以查看待处理的配对请求：
|
||||
在日志输出中查找 `open_id`。你也可以检查待处理的配对请求：
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
@ -190,14 +190,14 @@ openclaw pairing list feishu
|
||||
|
||||
## 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
| --------- | ------------------------ |
|
||||
| `/status` | 显示机器人状态 |
|
||||
| `/reset` | 重置当前会话 |
|
||||
| `/model` | 显示或切换 AI 模型 |
|
||||
| 命令 | 描述 |
|
||||
| --------- | -------------------- |
|
||||
| `/status` | 显示机器人状态 |
|
||||
| `/reset` | 重置当前会话 |
|
||||
| `/model` | 显示或切换 AI 模型 |
|
||||
|
||||
<Note>
|
||||
Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为纯文本消息发送。
|
||||
Feishu/Lark 不支持原生斜杠菜单，因此请将这些命令作为纯文本消息发送。
|
||||
</Note>
|
||||
|
||||
---
|
||||
@ -206,12 +206,12 @@ Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为
|
||||
|
||||
### 机器人在群聊中没有响应
|
||||
|
||||
1. 确保机器人已加入群组
|
||||
2. 确保你 @提及了机器人（默认必需）
|
||||
3. 确认 `groupPolicy` 不是 `"disabled"`
|
||||
1. 确保机器人已添加到群组
|
||||
2. 确保你 @提及了机器人（默认要求）
|
||||
3. 验证 `groupPolicy` 不是 `"disabled"`
|
||||
4. 检查日志：`openclaw logs --follow`
|
||||
|
||||
### 机器人未收到消息
|
||||
### 机器人没有收到消息
|
||||
|
||||
1. 确保机器人已在 Feishu Open Platform / Lark Developer 中发布并获批
|
||||
2. 确保事件订阅包含 `im.message.receive_v1`
|
||||
@ -223,7 +223,7 @@ Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为
|
||||
### App Secret 泄露
|
||||
|
||||
1. 在 Feishu Open Platform / Lark Developer 中重置 App Secret
|
||||
2. 更新你配置中的值
|
||||
2. 在你的配置中更新该值
|
||||
3. 重启 Gateway 网关：`openclaw gateway restart`
|
||||
|
||||
---
|
||||
@ -261,7 +261,7 @@ Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为
|
||||
```
|
||||
|
||||
`defaultAccount` 控制在出站 API 未指定 `accountId` 时使用哪个账户。
|
||||
`accounts.<id>.tts` 使用与 `messages.tts` 相同的结构，并会在全局 TTS 配置之上进行深度合并，因此多机器人 Feishu 部署可以在全局保留共享的提供商凭证，同时仅按账户覆盖语音、模型、角色设定或自动模式。
|
||||
`accounts.<id>.tts` 使用与 `messages.tts` 相同的形状，并会深度合并到全局 TTS 配置之上，因此多机器人 Feishu 设置可以在全局保留共享的提供商凭证，同时仅按账户覆盖语音、模型、角色或自动模式。
|
||||
|
||||
### 消息限制
|
||||
|
||||
@ -270,14 +270,14 @@ Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为
|
||||
|
||||
### 流式传输
|
||||
|
||||
Feishu/Lark 通过交互式卡片支持流式回复。启用后，机器人会在生成文本时实时更新卡片。
|
||||
Feishu/Lark 支持通过交互式卡片进行流式回复。启用后，机器人会在生成文本时实时更新卡片。
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
streaming: true, // 启用流式卡片输出（默认：true）
|
||||
blockStreaming: true, // 启用分块流式传输（默认：true）
|
||||
streaming: true, // enable streaming card output (default: true)
|
||||
blockStreaming: true, // enable block-level streaming (default: true)
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -287,10 +287,10 @@ Feishu/Lark 通过交互式卡片支持流式回复。启用后，机器人会
|
||||
|
||||
### 配额优化
|
||||
|
||||
使用两个可选标志来减少 Feishu/Lark API 调用次数：
|
||||
使用两个可选标志减少 Feishu/Lark API 调用次数：
|
||||
|
||||
- `typingIndicator`（默认 `true`）：设为 `false` 以跳过“正在输入”反应调用
|
||||
- `resolveSenderNames`（默认 `true`）：设为 `false` 以跳过发送者资料查询
|
||||
- `typingIndicator`（默认 `true`）：设置为 `false` 可跳过输入中反应调用
|
||||
- `resolveSenderNames`（默认 `true`）：设置为 `false` 可跳过发送者资料查询
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -305,7 +305,7 @@ Feishu/Lark 通过交互式卡片支持流式回复。启用后，机器人会
|
||||
|
||||
### ACP 会话
|
||||
|
||||
Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由文本命令驱动——没有原生斜杠命令菜单，因此请直接在对话中使用 `/acp ...` 消息。
|
||||
Feishu/Lark 支持用于私信和群组线程消息的 ACP。Feishu/Lark ACP 由文本命令驱动，没有原生斜杠菜单，因此请直接在对话中使用 `/acp ...` 消息。
|
||||
|
||||
#### 持久 ACP 绑定
|
||||
|
||||
@ -351,19 +351,19 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由
|
||||
}
|
||||
```
|
||||
|
||||
#### 从聊天中启动 ACP
|
||||
#### 从聊天中生成 ACP
|
||||
|
||||
在 Feishu/Lark 私信或话题中：
|
||||
在 Feishu/Lark 私信或线程中：
|
||||
|
||||
```text
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
`--thread here` 适用于私信和 Feishu/Lark 话题消息。后续在已绑定对话中的消息会直接路由到该 ACP 会话。
|
||||
`--thread here` 适用于私信和 Feishu/Lark 线程消息。绑定对话中的后续消息会直接路由到该 ACP 会话。
|
||||
|
||||
### 多智能体路由
|
||||
|
||||
使用 `bindings` 将 Feishu/Lark 私信或群组路由到不同的智能体。
|
||||
使用 `bindings` 将 Feishu/Lark 私信或群组路由到不同智能体。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -399,41 +399,41 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由
|
||||
- `match.peer.kind`：`"direct"`（私信）或 `"group"`（群聊）
|
||||
- `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`）
|
||||
|
||||
查找提示请参见[获取群组/用户 ID](#get-groupuser-ids)。
|
||||
请参阅[获取群组/用户 ID](#get-groupuser-ids)了解查找提示。
|
||||
|
||||
---
|
||||
|
||||
## 配置参考
|
||||
|
||||
完整配置： [Gateway 网关配置](/zh-CN/gateway/configuration)
|
||||
完整配置：[Gateway 网关配置](/zh-CN/gateway/configuration)
|
||||
|
||||
| 设置 | 说明 | 默认值 |
|
||||
| 设置 | 描述 | 默认值 |
|
||||
| ------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------- |
|
||||
| `channels.feishu.enabled` | 启用/禁用该渠道 | `true` |
|
||||
| `channels.feishu.enabled` | 启用/停用该渠道 | `true` |
|
||||
| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` |
|
||||
| `channels.feishu.connectionMode` | 事件传输方式（`websocket` 或 `webhook`） | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | 用于出站路由的默认账户 | `default` |
|
||||
| `channels.feishu.verificationToken` | webhook 模式必需 | — |
|
||||
| `channels.feishu.encryptKey` | webhook 模式必需 | — |
|
||||
| `channels.feishu.webhookPath` | webhook 路由路径 | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | webhook 绑定主机 | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | webhook 绑定端口 | `3000` |
|
||||
| `channels.feishu.webhookPath` | Webhook 路由路径 | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | Webhook 绑定主机 | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | Webhook 绑定端口 | `3000` |
|
||||
| `channels.feishu.accounts.<id>.appId` | App ID | — |
|
||||
| `channels.feishu.accounts.<id>.appSecret` | App Secret | — |
|
||||
| `channels.feishu.accounts.<id>.domain` | 按账户覆盖域名 | `feishu` |
|
||||
| `channels.feishu.accounts.<id>.tts` | 按账户覆盖 TTS | `messages.tts` |
|
||||
| `channels.feishu.accounts.<id>.domain` | 每个账户的域名覆盖设置 | `feishu` |
|
||||
| `channels.feishu.accounts.<id>.tts` | 每个账户的 TTS 覆盖设置 | `messages.tts` |
|
||||
| `channels.feishu.dmPolicy` | 私信策略 | `allowlist` |
|
||||
| `channels.feishu.allowFrom` | 私信白名单（`open_id` 列表） | [BotOwnerId] |
|
||||
| `channels.feishu.allowFrom` | 私信允许列表（open_id 列表） | [BotOwnerId] |
|
||||
| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | 群组白名单 | — |
|
||||
| `channels.feishu.requireMention` | 在群组中要求 @提及 | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | 按群组覆盖 @提及要求；显式 ID 在 allowlist 模式下也会让该群组获得准入 | inherited |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | 启用/禁用特定群组 | `true` |
|
||||
| `channels.feishu.groupAllowFrom` | 群组允许列表 | — |
|
||||
| `channels.feishu.requireMention` | 群组中要求 @mention | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | 每个群组的 @mention 覆盖设置；显式 ID 在允许列表模式下也会准入该群组 | inherited |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | 启用/停用特定群组 | `true` |
|
||||
| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` |
|
||||
| `channels.feishu.streaming` | 流式卡片输出 | `true` |
|
||||
| `channels.feishu.blockStreaming` | 分块流式传输 | `true` |
|
||||
| `channels.feishu.typingIndicator` | 发送“正在输入”反应 | `true` |
|
||||
| `channels.feishu.blockStreaming` | 块级流式传输 | `true` |
|
||||
| `channels.feishu.typingIndicator` | 发送正在输入反应 | `true` |
|
||||
| `channels.feishu.resolveSenderNames` | 解析发送者显示名称 | `true` |
|
||||
|
||||
---
|
||||
@ -450,7 +450,7 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由
|
||||
- ✅ 视频/媒体
|
||||
- ✅ 表情贴纸
|
||||
|
||||
Feishu/Lark 的入站音频消息会被标准化为媒体占位符，而不是原始 `file_key` JSON。当配置了 `tools.media.audio` 时，OpenClaw 会下载语音消息资源，并在智能体轮次开始前运行共享音频转写，因此智能体接收到的是语音转写文本。如果 Feishu 在音频负载中直接包含转写文本，则会直接使用该文本，而不会再发起一次 ASR 调用。如果没有音频转写提供商，智能体仍会接收到一个 `<media:audio>` 占位符以及已保存的附件，而不是原始的 Feishu 资源负载。
|
||||
入站 Feishu/Lark 音频消息会被规范化为媒体占位符，而不是原始 `file_key` JSON。当配置了 `tools.media.audio` 时，OpenClaw 会下载语音留言资源，并在智能体轮次开始前运行共享音频转写，因此智能体会收到语音转写文本。如果 Feishu 在音频载荷中直接包含转写文本，则会直接使用该文本，不再进行另一次 ASR 调用。如果没有音频转写提供商，智能体仍会收到一个 `<media:audio>` 占位符和已保存的附件，而不是原始 Feishu 资源载荷。
|
||||
|
||||
### 发送
|
||||
|
||||
@ -460,24 +460,24 @@ Feishu/Lark 的入站音频消息会被标准化为媒体占位符，而不是
|
||||
- ✅ 音频
|
||||
- ✅ 视频/媒体
|
||||
- ✅ 交互式卡片（包括流式更新）
|
||||
- ⚠️ 富文本（post 风格格式；不支持完整的 Feishu/Lark 原生编辑能力）
|
||||
- ⚠️ 富文本（post 风格格式；不支持完整 Feishu/Lark 创作能力）
|
||||
|
||||
原生 Feishu/Lark 音频气泡使用 Feishu `audio` 消息类型，并要求上传 Ogg/Opus 媒体（`file_type: "opus"`）。现有的 `.opus` 和 `.ogg` 媒体会直接作为原生音频发送。MP3/WAV/M4A 和其他常见音频格式，仅会在回复请求语音投递时转码为 48 kHz Ogg/Opus（使用 `ffmpeg`），例如 `audioAsVoice` / 消息工具 `asVoice`，包括 TTS 语音便笺回复。普通 MP3 附件会保持为常规文件。如果缺少 `ffmpeg` 或转换失败，OpenClaw 会回退为文件附件并记录原因。
|
||||
原生 Feishu/Lark 音频气泡使用 Feishu `audio` 消息类型，并要求上传 Ogg/Opus 媒体（`file_type: "opus"`）。已有的 `.opus` 和 `.ogg` 媒体会直接作为原生音频发送。只有当回复请求语音递送（`audioAsVoice` / 消息工具 `asVoice`，包括 TTS 语音留言回复）时，MP3/WAV/M4A 和其他可能的音频格式才会通过 `ffmpeg` 转码为 48kHz Ogg/Opus。普通 MP3 附件仍作为常规文件发送。如果缺少 `ffmpeg` 或转换失败，OpenClaw 会回退为文件附件并记录原因。
|
||||
|
||||
### 话题和回复
|
||||
### 线程和回复
|
||||
|
||||
- ✅ 内联回复
|
||||
- ✅ 话题回复
|
||||
- ✅ 回复话题消息时，媒体回复会保持话题感知
|
||||
- ✅ 行内回复
|
||||
- ✅ 线程回复
|
||||
- ✅ 回复线程消息时，媒体回复会保持线程感知
|
||||
|
||||
对于 `groupSessionScope: "group_topic"` 和 `"group_topic_sender"`，原生 Feishu/Lark 话题群组使用事件中的 `thread_id`（`omt_*`）作为规范的话题会话键。对于 OpenClaw 转换为话题的普通群组回复，仍继续使用回复根消息 ID（`om_*`），这样首轮消息和后续消息会保持在同一个会话中。
|
||||
对于 `groupSessionScope: "group_topic"` 和 `"group_topic_sender"`，原生 Feishu/Lark 话题群使用事件 `thread_id`（`omt_*`）作为规范的话题会话键。OpenClaw 转换成线程的普通群组回复会继续使用回复根消息 ID（`om_*`），因此第一轮和后续轮次会保持在同一会话中。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [渠道概览](/zh-CN/channels) — 所有支持的渠道
|
||||
- [配对](/zh-CN/channels/pairing) — 私信身份验证与配对流程
|
||||
- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程
|
||||
- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
|
||||
- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
|
||||
- [安全](/zh-CN/gateway/security) — 访问模型与加固措施
|
||||
- [安全](/zh-CN/gateway/security) — 访问模型和加固
|
||||
|
||||
@ -2,20 +2,20 @@
|
||||
read_when:
|
||||
- 设置私信访问控制
|
||||
- 配对新的 iOS/Android 节点
|
||||
- 审查 OpenClaw 的安全态势
|
||||
summary: 配对概览：批准谁可以私信你 + 哪些节点可以加入
|
||||
- 审查 OpenClaw 安全态势
|
||||
summary: 配对概览：批准谁可以给你发私信 + 哪些节点可以加入
|
||||
title: 配对
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T22:44:28Z"
|
||||
generated_at: "2026-04-29T05:57:51Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 123d1dccfab0a2ed8a415934eb508e373c4fe85e3d07adb5eb8aa9f3cf8a3fc9
|
||||
source_hash: cfdcaf831aedb122ea85200518b8dc1c6f42eff365444dee6c4b740050b1ce26
|
||||
source_path: channels/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
“配对”是 OpenClaw 的显式访问批准步骤。
|
||||
它用于两个位置：
|
||||
它用于两个地方：
|
||||
|
||||
1. **私信配对**（谁可以与机器人对话）
|
||||
2. **节点配对**（哪些设备/节点可以加入 Gateway 网关网络）
|
||||
@ -24,15 +24,20 @@ x-i18n:
|
||||
|
||||
## 1) 私信配对（入站聊天访问）
|
||||
|
||||
当某个渠道配置了私信策略 `pairing` 时，未知发送者会收到一个短代码，并且他们的消息在你批准前**不会被处理**。
|
||||
当某个渠道配置了私信策略 `pairing` 时，未知发送者会收到一个短代码，并且在你批准之前，他们的消息**不会被处理**。
|
||||
|
||||
默认私信策略记录在：[安全](/zh-CN/gateway/security)
|
||||
|
||||
只有当生效的私信允许列表包含 `"*"` 时，`dmPolicy: "open"` 才是公开的。
|
||||
设置和验证要求公开开放配置必须包含该通配符。如果现有
|
||||
状态包含带有具体 `allowFrom` 条目的 `open`，运行时仍然只允许
|
||||
这些发送者，并且配对存储的批准不会扩大 `open` 访问范围。
|
||||
|
||||
配对代码：
|
||||
|
||||
- 8 个字符，大写，不包含易混淆字符（`0O1I`）。
|
||||
- 8 个字符，大写，不含易混淆字符（`0O1I`）。
|
||||
- **1 小时后过期**。机器人只会在创建新请求时发送配对消息（大约每个发送者每小时一次）。
|
||||
- 待处理的私信配对请求默认每个渠道最多 **3 个**；额外请求会被忽略，直到其中一个过期或获批。
|
||||
- 待处理的私信配对请求默认限制为**每个渠道 3 个**；额外请求会被忽略，直到其中一个过期或被批准。
|
||||
|
||||
### 批准发送者
|
||||
|
||||
@ -41,47 +46,47 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
如果尚未配置命令所有者，批准私信配对代码也会将
|
||||
`commands.ownerAllowFrom` 引导设置为获批发送者，例如 `telegram:123456789`。
|
||||
这会为首次设置提供一个显式所有者，用于特权命令和 exec
|
||||
如果尚未配置命令所有者，批准私信配对代码还会将
|
||||
`commands.ownerAllowFrom` 引导设置为已批准的发送者，例如 `telegram:123456789`。
|
||||
这会为首次设置提供一个明确的所有者，用于特权命令和 exec
|
||||
批准提示。所有者存在后，后续配对批准只会授予私信
|
||||
访问权限；它们不会添加更多所有者。
|
||||
访问权限；不会添加更多所有者。
|
||||
|
||||
支持的渠道：`bluebubbles`、`discord`、`feishu`、`googlechat`、`imessage`、`irc`、`line`、`matrix`、`mattermost`、`msteams`、`nextcloud-talk`、`nostr`、`openclaw-weixin`、`signal`、`slack`、`synology-chat`、`telegram`、`twitch`、`whatsapp`、`zalo`、`zalouser`。
|
||||
|
||||
### 状态存放位置
|
||||
### 状态存储位置
|
||||
|
||||
存储在 `~/.openclaw/credentials/` 下：
|
||||
|
||||
- 待处理请求：`<channel>-pairing.json`
|
||||
- 已批准允许列表存储：
|
||||
- 默认账号：`<channel>-allowFrom.json`
|
||||
- 非默认账号：`<channel>-<accountId>-allowFrom.json`
|
||||
- 默认账户：`<channel>-allowFrom.json`
|
||||
- 非默认账户：`<channel>-<accountId>-allowFrom.json`
|
||||
|
||||
账号作用域行为：
|
||||
账户作用域行为：
|
||||
|
||||
- 非默认账号只读写其作用域化的允许列表文件。
|
||||
- 默认账号使用渠道作用域的非作用域化允许列表文件。
|
||||
- 非默认账户只读写其作用域内的允许列表文件。
|
||||
- 默认账户使用渠道作用域的非作用域允许列表文件。
|
||||
|
||||
请将这些文件视为敏感信息（它们控制对你的助手的访问）。
|
||||
请将这些内容视为敏感信息（它们控制对你的助手的访问）。
|
||||
|
||||
<Note>
|
||||
配对允许列表存储用于私信访问。群组授权是单独的。
|
||||
配对允许列表存储用于私信访问。群组授权是独立的。
|
||||
批准私信配对代码不会自动允许该发送者运行群组
|
||||
命令或在群组中控制机器人。首个所有者引导是 `commands.ownerAllowFrom`
|
||||
中的单独配置状态，而群聊投递仍遵循该
|
||||
渠道的群组允许列表（例如 `groupAllowFrom`、`groups`，或根据渠道而定的按群组
|
||||
或按话题覆盖项）。
|
||||
命令或在群组中控制机器人。首次所有者引导是 `commands.ownerAllowFrom`
|
||||
中的独立配置状态，群聊投递仍遵循该
|
||||
渠道的群组允许列表（例如 `groupAllowFrom`、`groups`，或取决于渠道的按群组
|
||||
或按主题覆盖）。
|
||||
</Note>
|
||||
|
||||
## 2) 节点设备配对（iOS/Android/macOS/无头节点）
|
||||
|
||||
节点以 `role: node` 的**设备**身份连接到 Gateway 网关。Gateway 网关
|
||||
会创建设备配对请求，且该请求必须获批。
|
||||
会创建设备配对请求，必须批准该请求。
|
||||
|
||||
### 通过 Telegram 配对（推荐用于 iOS）
|
||||
|
||||
如果使用 `device-pair` 插件，你可以完全通过 Telegram 完成首次设备配对：
|
||||
如果你使用 `device-pair` 插件，可以完全通过 Telegram 完成首次设备配对：
|
||||
|
||||
1. 在 Telegram 中，向你的机器人发送消息：`/pair`
|
||||
2. 机器人会回复两条消息：一条说明消息，以及一条单独的**设置代码**消息（便于在 Telegram 中复制/粘贴）。
|
||||
@ -89,23 +94,23 @@ openclaw pairing approve telegram <CODE>
|
||||
4. 粘贴设置代码并连接。
|
||||
5. 回到 Telegram：`/pair pending`（查看请求 ID、角色和作用域），然后批准。
|
||||
|
||||
设置代码是一个 base64 编码的 JSON 载荷，包含：
|
||||
设置代码是一个 base64 编码的 JSON 载荷，其中包含：
|
||||
|
||||
- `url`：Gateway 网关 WebSocket URL（`ws://...` 或 `wss://...`）
|
||||
- `bootstrapToken`：用于初始配对握手的短期单设备引导令牌
|
||||
|
||||
该引导令牌携带内置配对引导配置文件：
|
||||
该引导令牌携带内置的配对引导配置文件：
|
||||
|
||||
- 主要移交的 `node` 令牌保持 `scopes: []`
|
||||
- 任何移交的 `operator` 令牌都保持受限于引导允许列表：
|
||||
- 任何移交的 `operator` 令牌都受引导允许列表限制：
|
||||
`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`
|
||||
- 引导作用域检查按角色前缀划分，而不是一个扁平作用域池：
|
||||
- 引导作用域检查按角色前缀区分，而不是一个扁平的作用域池：
|
||||
operator 作用域条目只满足 operator 请求，非 operator 角色
|
||||
仍必须在它们自己的角色前缀下请求作用域
|
||||
仍必须在其自身角色前缀下请求作用域
|
||||
- 后续令牌轮换/撤销仍同时受设备已批准的
|
||||
角色合约和调用方会话的 operator 作用域限制
|
||||
角色契约和调用方会话的 operator 作用域限制
|
||||
|
||||
在设置代码有效期间，请像对待密码一样对待它。
|
||||
设置代码在有效期内应像密码一样对待。
|
||||
|
||||
### 批准节点设备
|
||||
|
||||
@ -115,17 +120,17 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
如果同一设备使用不同认证详情重试（例如不同
|
||||
角色/作用域/公钥），之前待处理的请求会被取代，并创建新的
|
||||
如果同一设备使用不同的认证详情重试（例如不同的
|
||||
角色/作用域/公钥），之前的待处理请求会被取代，并创建新的
|
||||
`requestId`。
|
||||
|
||||
<Note>
|
||||
已配对的设备不会静默获得更宽泛的访问权限。如果它重新连接并请求更多作用域或更宽泛角色，OpenClaw 会保持现有批准不变，并创建一个新的待处理升级请求。在批准前，使用 `openclaw devices list` 比较当前已批准访问权限与新请求的访问权限。
|
||||
已配对设备不会静默获得更广泛的访问权限。如果它重新连接并请求更多作用域或更广泛的角色，OpenClaw 会保持现有批准不变，并创建一个新的待处理升级请求。在批准前，使用 `openclaw devices list` 比较当前已批准的访问权限与新请求的访问权限。
|
||||
</Note>
|
||||
|
||||
### 可选的受信任 CIDR 节点自动批准
|
||||
### 可选的可信 CIDR 节点自动批准
|
||||
|
||||
默认情况下，设备配对仍为手动。对于严格受控的节点网络，
|
||||
设备配对默认仍为手动。对于严格受控的节点网络，
|
||||
你可以通过显式 CIDR 或精确 IP 选择启用首次节点自动批准：
|
||||
|
||||
```json5
|
||||
@ -141,7 +146,7 @@ openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
这只适用于没有请求
|
||||
作用域的新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍需要手动
|
||||
作用域的全新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍需要手动
|
||||
批准。角色、作用域、元数据和公钥变更仍需要手动
|
||||
批准。
|
||||
|
||||
@ -152,12 +157,12 @@ openclaw devices reject <requestId>
|
||||
- `pending.json`（短期；待处理请求会过期）
|
||||
- `paired.json`（已配对设备 + 令牌）
|
||||
|
||||
### 注意事项
|
||||
### 备注
|
||||
|
||||
- 旧版 `node.pair.*` API（CLI：`openclaw nodes pending|approve|reject|remove|rename`）是一个
|
||||
单独的 Gateway 网关自有配对存储。WS 节点仍需要设备配对。
|
||||
- 配对记录是已批准角色的持久事实来源。活动
|
||||
设备令牌仍受限于该已批准角色集；已批准角色之外的零散令牌条目
|
||||
独立的 Gateway 网关拥有的配对存储。WS 节点仍需要设备配对。
|
||||
- 配对记录是已批准角色的持久事实来源。活跃的
|
||||
设备令牌仍受该已批准角色集限制；已批准角色之外的意外令牌条目
|
||||
不会创建新的访问权限。
|
||||
|
||||
## 相关文档
|
||||
|
||||
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置 Synology Chat 与 OpenClaw 的集成
|
||||
- 调试 Synology Chat webhook 路由
|
||||
summary: Synology Chat webhook 设置和 OpenClaw 配置
|
||||
- 设置 Synology Chat 与 OpenClaw 配合使用
|
||||
- 调试 Synology Chat 网络钩子路由
|
||||
summary: Synology Chat 网络钩子设置和 OpenClaw 配置
|
||||
title: Synology Chat
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:42:03Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-29T05:57:46Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5135e9aa1fd86437a635378dfbbde321bbd2e5f6fef7a3cc740ea54ebf4b76d5
|
||||
source_hash: c3d6d7a56bd15d29de38c6ae29ae496b491c2e75df5e0a0a15410b0fbdc55a00
|
||||
source_path: channels/synology-chat.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
状态：内置插件的私信渠道，使用 Synology Chat webhooks。
|
||||
该插件接收来自 Synology Chat 出站 webhook 的入站消息，并通过 Synology Chat 入站 webhook 发送回复。
|
||||
Status：使用 Synology Chat webhook 的内置插件私信渠道。
|
||||
该插件接受来自 Synology Chat outgoing webhook 的入站消息，并通过 Synology Chat incoming webhook 发送回复。
|
||||
|
||||
## 内置插件
|
||||
|
||||
在当前 OpenClaw 版本中，Synology Chat 作为内置插件提供，因此常规打包构建不需要单独安装。
|
||||
Synology Chat 在当前 OpenClaw 版本中作为内置插件随附，因此正常的打包构建不需要单独安装。
|
||||
|
||||
如果你使用的是较旧的构建版本，或是不包含 Synology Chat 的自定义安装，请手动安装：
|
||||
如果你使用的是较旧构建，或排除了 Synology Chat 的自定义安装，请手动安装：
|
||||
|
||||
从本地检出安装：
|
||||
|
||||
@ -28,35 +28,35 @@ x-i18n:
|
||||
openclaw plugins install ./path/to/local/synology-chat-plugin
|
||||
```
|
||||
|
||||
详情参见：[Plugins](/zh-CN/tools/plugin)
|
||||
详情：[插件](/zh-CN/tools/plugin)
|
||||
|
||||
## 快速设置
|
||||
|
||||
1. 确保 Synology Chat 插件可用。
|
||||
- 当前打包的 OpenClaw 版本已内置该插件。
|
||||
- 较旧/自定义安装可通过上面的命令，从源码检出中手动添加。
|
||||
- 较旧/自定义安装可以使用上面的命令从源码检出手动添加。
|
||||
- `openclaw onboard` 现在会在与 `openclaw channels add` 相同的渠道设置列表中显示 Synology Chat。
|
||||
- 非交互式设置：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
|
||||
2. 在 Synology Chat 集成中：
|
||||
- 创建一个入站 webhook 并复制其 URL。
|
||||
- 创建一个带有你的 secret token 的出站 webhook。
|
||||
3. 将出站 webhook URL 指向你的 OpenClaw Gateway 网关：
|
||||
- 创建一个 incoming webhook 并复制其 URL。
|
||||
- 使用你的 secret token 创建一个 outgoing webhook。
|
||||
3. 将 outgoing webhook URL 指向你的 OpenClaw Gateway 网关：
|
||||
- 默认是 `https://gateway-host/webhook/synology`。
|
||||
- 或者使用你自定义的 `channels.synology-chat.webhookPath`。
|
||||
- 或使用你的自定义 `channels.synology-chat.webhookPath`。
|
||||
4. 在 OpenClaw 中完成设置。
|
||||
- 引导式：`openclaw onboard`
|
||||
- 直接设置：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
|
||||
5. 重启 Gateway 网关，并向 Synology Chat bot 发送一条私信。
|
||||
- 直接：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
|
||||
5. 重启 Gateway 网关，并向 Synology Chat 机器人发送私信。
|
||||
|
||||
Webhook 身份验证详情：
|
||||
Webhook 认证详情：
|
||||
|
||||
- OpenClaw 按顺序从 `body.token`、然后 `?token=...`、再然后 headers 中接受出站 webhook token。
|
||||
- OpenClaw 会先从 `body.token` 接受 outgoing webhook token，然后是 `?token=...`，最后是 headers。
|
||||
- 接受的 header 形式：
|
||||
- `x-synology-token`
|
||||
- `x-webhook-token`
|
||||
- `x-openclaw-token`
|
||||
- `Authorization: Bearer <token>`
|
||||
- 空 token 或缺失 token 会以失败关闭方式处理。
|
||||
- 空 token 或缺失 token 会失败关闭。
|
||||
|
||||
最小配置：
|
||||
|
||||
@ -90,23 +90,23 @@ Webhook 身份验证详情：
|
||||
|
||||
配置值会覆盖环境变量。
|
||||
|
||||
`SYNOLOGY_CHAT_INCOMING_URL` 不能通过工作区 `.env` 设置；参见 [工作区 `.env` 文件](/zh-CN/gateway/security)。
|
||||
`SYNOLOGY_CHAT_INCOMING_URL` 不能从工作区 `.env` 设置；请参阅[工作区 `.env` 文件](/zh-CN/gateway/security)。
|
||||
|
||||
## 私信策略与访问控制
|
||||
## 私信策略和访问控制
|
||||
|
||||
- 推荐默认使用 `dmPolicy: "allowlist"`。
|
||||
- `dmPolicy: "allowlist"` 是推荐的默认值。
|
||||
- `allowedUserIds` 接受 Synology 用户 ID 列表（或逗号分隔字符串）。
|
||||
- 在 `allowlist` 模式下，空的 `allowedUserIds` 列表会被视为配置错误，webhook 路由不会启动（如需允许所有人，请使用 `dmPolicy: "open"`）。
|
||||
- `dmPolicy: "open"` 允许任意发送者。
|
||||
- `dmPolicy: "disabled"` 阻止私信。
|
||||
- 回复接收方绑定默认保持基于稳定的数字 `user_id`。`channels.synology-chat.dangerouslyAllowNameMatching: true` 是紧急兼容模式，会重新启用基于可变用户名/昵称查找的回复投递。
|
||||
- 配对批准可配合以下命令使用：
|
||||
- 在 `allowlist` 模式下，空的 `allowedUserIds` 列表会被视为配置错误，webhook 路由不会启动（如需允许所有用户，请使用 `dmPolicy: "open"` 与 `allowedUserIds: ["*"]`）。
|
||||
- 只有当 `allowedUserIds` 包含 `"*"` 时，`dmPolicy: "open"` 才允许公开私信；如果是限制性条目，则只有匹配的用户可以聊天。
|
||||
- `dmPolicy: "disabled"` 会阻止私信。
|
||||
- 默认情况下，回复收件人绑定保持在稳定的数字 `user_id` 上。`channels.synology-chat.dangerouslyAllowNameMatching: true` 是应急兼容模式，会重新启用可变用户名/昵称查找来投递回复。
|
||||
- 配对批准可使用：
|
||||
- `openclaw pairing list synology-chat`
|
||||
- `openclaw pairing approve synology-chat <CODE>`
|
||||
|
||||
## 出站投递
|
||||
|
||||
请使用数字 Synology Chat 用户 ID 作为目标。
|
||||
使用数字 Synology Chat 用户 ID 作为目标。
|
||||
|
||||
示例：
|
||||
|
||||
@ -115,16 +115,16 @@ openclaw message send --channel synology-chat --target 123456 --text "Hello from
|
||||
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
|
||||
```
|
||||
|
||||
支持通过基于 URL 的文件投递发送媒体。
|
||||
出站文件 URL 必须使用 `http` 或 `https`，私有网络或其他被阻止的网络目标会在 OpenClaw 将 URL 转发给 NAS webhook 之前被拒绝。
|
||||
支持通过基于 URL 的文件投递发送媒体。
|
||||
出站文件 URL 必须使用 `http` 或 `https`，并且在 OpenClaw 将该 URL 转发到 NAS webhook 之前，会拒绝私有或其他被阻止的网络目标。
|
||||
|
||||
## 多账户
|
||||
|
||||
支持在 `channels.synology-chat.accounts` 下配置多个 Synology Chat 账户。
|
||||
每个账户都可以覆盖 token、入站 URL、webhook 路径、私信策略和限制。
|
||||
私信会话会按账户和用户隔离，因此两个不同 Synology 账户上的同一个数字 `user_id` 不会共享转录状态。
|
||||
请为每个已启用账户提供不同的 `webhookPath`。OpenClaw 现在会拒绝重复的精确路径，并在多账户设置中拒绝启动那些仅继承共享 webhook 路径的具名账户。
|
||||
如果你确实需要为具名账户保留旧版继承行为，请在该账户或 `channels.synology-chat` 上设置 `dangerouslyAllowInheritedWebhookPath: true`，但重复的精确路径仍会以失败关闭方式被拒绝。推荐为每个账户显式配置路径。
|
||||
`channels.synology-chat.accounts` 下支持多个 Synology Chat 账户。
|
||||
每个账户都可以覆盖 token、incoming URL、webhook path、私信策略和限制。
|
||||
私信会话按账户和用户隔离，因此两个不同 Synology 账户上的相同数字 `user_id` 不会共享对话状态。
|
||||
为每个已启用账户指定不同的 `webhookPath`。OpenClaw 现在会拒绝重复的精确路径，并且在多账户设置中会拒绝启动仅继承共享 webhook path 的命名账户。
|
||||
如果你有意需要为某个命名账户使用旧版继承，请在该账户上或在 `channels.synology-chat` 设置 `dangerouslyAllowInheritedWebhookPath: true`，但重复的精确路径仍会失败关闭。优先使用显式的按账户路径。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -151,35 +151,35 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te
|
||||
|
||||
## 安全说明
|
||||
|
||||
- 请妥善保管 `token`，如有泄露请轮换。
|
||||
- 除非你明确信任使用自签名本地 NAS 证书，否则请保持 `allowInsecureSsl: false`。
|
||||
- 入站 webhook 请求会进行 token 验证，并按发送者进行速率限制。
|
||||
- 无效 token 检查使用常量时间 secret 比较，并以失败关闭方式处理。
|
||||
- 在生产环境中，优先使用 `dmPolicy: "allowlist"`。
|
||||
- 除非你明确需要旧版基于用户名的回复投递，否则请保持 `dangerouslyAllowNameMatching` 关闭。
|
||||
- 除非你明确接受多账户设置中共享路径路由的风险，否则请保持 `dangerouslyAllowInheritedWebhookPath` 关闭。
|
||||
- 保持 `token` 机密，如果泄露请轮换。
|
||||
- 除非你明确信任自签名的本地 NAS 证书，否则保持 `allowInsecureSsl: false`。
|
||||
- 入站 webhook 请求会按发送者进行 token 验证和限速。
|
||||
- 无效 token 检查使用常量时间 secret 比较，并失败关闭。
|
||||
- 生产环境优先使用 `dmPolicy: "allowlist"`。
|
||||
- 除非你明确需要基于旧版用户名的回复投递，否则保持 `dangerouslyAllowNameMatching` 关闭。
|
||||
- 除非你明确接受多账户设置中的共享路径路由风险，否则保持 `dangerouslyAllowInheritedWebhookPath` 关闭。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- `Missing required fields (token, user_id, text)`：
|
||||
- 出站 webhook 负载缺少所需字段之一
|
||||
- outgoing webhook payload 缺少某个必填字段
|
||||
- 如果 Synology 通过 headers 发送 token，请确保 Gateway 网关/代理保留这些 headers
|
||||
- `Invalid token`：
|
||||
- 出站 webhook secret 与 `channels.synology-chat.token` 不匹配
|
||||
- 请求命中了错误的账户/webhook 路径
|
||||
- 反向代理在请求到达 OpenClaw 前剥离了 token header
|
||||
- outgoing webhook secret 与 `channels.synology-chat.token` 不匹配
|
||||
- 请求命中了错误的账户/webhook path
|
||||
- 反向代理在请求到达 OpenClaw 之前剥离了 token header
|
||||
- `Rate limit exceeded`：
|
||||
- 来自同一来源的过多无效 token 尝试，可能会暂时将该来源锁定
|
||||
- 已认证发送者也会受到单独的按用户消息速率限制
|
||||
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`：
|
||||
- 已启用 `dmPolicy="allowlist"`，但未配置任何用户
|
||||
- 来自同一来源的无效 token 尝试过多，可能会暂时锁定该来源
|
||||
- 已认证发送者也有单独的按用户消息速率限制
|
||||
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].`：
|
||||
- `dmPolicy="allowlist"` 已启用，但未配置用户
|
||||
- `User not authorized`：
|
||||
- 发送者的数字 `user_id` 不在 `allowedUserIds` 中
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [渠道概览](/zh-CN/channels) — 所有受支持的渠道
|
||||
- [配对](/zh-CN/channels/pairing) — 私信身份验证与配对流程
|
||||
- [群组](/zh-CN/channels/groups) — 群聊行为与提及门控
|
||||
- [渠道概览](/zh-CN/channels) — 所有支持的渠道
|
||||
- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程
|
||||
- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
|
||||
- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
|
||||
- [安全](/zh-CN/gateway/security) — 访问模型与安全加固
|
||||
- [安全](/zh-CN/gateway/security) — 访问模型和加固
|
||||
|
||||
@ -4,15 +4,15 @@ read_when:
|
||||
summary: Telegram 机器人支持状态、能力和配置
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T23:40:09Z"
|
||||
generated_at: "2026-04-29T05:57:36Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: aecd9edba56d0689a5823536a92171fa6e0c3ef56656f4699bb1e5793e248751
|
||||
source_hash: 0bf75d82f21658a1ca547b2e4ab229f7b6e47537a2379bf52bd7a18f0677664b
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
通过 grammY 可用于生产环境中的机器人私信和群组。长轮询是默认模式；webhook 模式是可选的。
|
||||
可用于生产环境的机器人私信和群组，基于 grammY。长轮询是默认模式；webhook 模式可选。
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
|
||||
@ -30,9 +30,9 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="在 BotFather 中创建机器人令牌">
|
||||
打开 Telegram 并与 **@BotFather** 聊天（确认用户名正好是 `@BotFather`）。
|
||||
打开 Telegram 并与 **@BotFather** 聊天（确认用户名正是 `@BotFather`）。
|
||||
|
||||
运行 `/newbot`，按照提示操作，并保存令牌。
|
||||
运行 `/newbot`，按提示操作，并保存令牌。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -52,7 +52,7 @@ x-i18n:
|
||||
```
|
||||
|
||||
环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。
|
||||
Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。
|
||||
Telegram **不**使用 `openclaw channels login telegram`；在配置/环境变量中配置令牌，然后启动 Gateway 网关。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -64,38 +64,38 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
配对码会在 1 小时后过期。
|
||||
配对代码会在 1 小时后过期。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="将机器人添加到群组">
|
||||
将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，以匹配你的访问模型。
|
||||
将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy` 以匹配你的访问模型。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
令牌解析顺序支持账号感知。实际使用中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账号。
|
||||
令牌解析顺序支持账号感知。实际使用中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账号。
|
||||
</Note>
|
||||
|
||||
## Telegram 端设置
|
||||
## Telegram 侧设置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="隐私模式和群组可见性">
|
||||
Telegram 机器人默认启用**隐私模式**，这会限制它们能接收哪些群组消息。
|
||||
Telegram 机器人默认使用**隐私模式**，这会限制它们能接收的群组消息。
|
||||
|
||||
如果机器人必须看到所有群组消息，可以：
|
||||
|
||||
- 通过 `/setprivacy` 禁用隐私模式，或
|
||||
- 将机器人设为群组管理员。
|
||||
|
||||
切换隐私模式后，请在每个群组中移除并重新添加机器人，以便 Telegram 应用该更改。
|
||||
切换隐私模式时，请在每个群组中移除并重新添加机器人，以便 Telegram 应用该变更。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="群组权限">
|
||||
管理员状态在 Telegram 群组设置中控制。
|
||||
|
||||
管理员机器人会接收所有群组消息，这对常驻群组行为很有用。
|
||||
管理员机器人会接收所有群组消息，这对始终在线的群组行为很有用。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -111,27 +111,28 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
<Tabs>
|
||||
<Tab title="私信策略">
|
||||
`channels.telegram.dmPolicy` 控制直接消息访问：
|
||||
`channels.telegram.dmPolicy` 控制私信访问：
|
||||
|
||||
- `pairing`（默认）
|
||||
- `allowlist`（要求 `allowFrom` 中至少有一个发送者 ID）
|
||||
- `open`（要求 `allowFrom` 包含 `"*"`）
|
||||
- `disabled`
|
||||
|
||||
使用 `dmPolicy: "open"` 且 `allowFrom: ["*"]` 时，任何找到或猜到机器人用户名的 Telegram 账号都可以向机器人发出命令。只应将它用于有意公开、且工具受到严格限制的机器人；单所有者机器人应使用带数字用户 ID 的 `allowlist`。
|
||||
`dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能命令机器人。仅在有意公开且工具权限严格受限的机器人上使用；单所有者机器人应使用带数字用户 ID 的 `allowlist`。
|
||||
|
||||
`channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。
|
||||
`dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。
|
||||
设置过程只会要求输入数字用户 ID。
|
||||
如果你已升级且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 解析它们（尽力而为；需要 Telegram 机器人令牌）。
|
||||
如果你之前依赖配对存储中的允许列表文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 还没有显式 ID 时）。
|
||||
`channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。接受并规范化 `telegram:` / `tg:` 前缀。
|
||||
在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会让该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。
|
||||
`dmPolicy: "allowlist"` 搭配空 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。
|
||||
设置只会询问数字用户 ID。
|
||||
如果你升级后配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力处理；需要 Telegram 机器人令牌）。
|
||||
如果你以前依赖配对存储允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如 `dmPolicy: "allowlist"` 还没有显式 ID 时）。
|
||||
|
||||
对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并配置显式的数字 `allowFrom` ID，以便让访问策略在配置中保持持久（而不是依赖之前的配对批准）。
|
||||
对于单所有者机器人，优先使用带显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便在配置中保持访问策略持久化（而不是依赖之前的配对批准）。
|
||||
|
||||
常见混淆：批准私信配对并不意味着“这个发送者在所有地方都已授权”。
|
||||
配对授予私信访问权限。如果还没有命令所有者，第一次获批的配对也会设置 `commands.ownerAllowFrom`，让仅所有者命令和执行批准拥有显式操作员账号。
|
||||
群组发送者授权仍然来自显式配置允许列表。
|
||||
如果你希望“我授权一次后，私信和群组命令都能使用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
|
||||
常见误解：私信配对批准并不意味着“此发送者在所有地方都已授权”。
|
||||
配对授予私信访问权限。如果还没有命令所有者，首次获批的配对也会设置 `commands.ownerAllowFrom`，让仅所有者命令和 exec 批准拥有显式操作员账号。
|
||||
群组发送者授权仍来自显式配置允许列表。
|
||||
如果你想要“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
|
||||
|
||||
### 查找你的 Telegram 用户 ID
|
||||
|
||||
@ -147,7 +148,7 @@ openclaw pairing approve telegram <CODE>
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
第三方方法（隐私性较低）：`@userinfobot` 或 `@getidsbot`。
|
||||
第三方方法（隐私性较弱）：`@userinfobot` 或 `@getidsbot`。
|
||||
|
||||
</Tab>
|
||||
|
||||
@ -155,9 +156,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
两个控制项会共同生效：
|
||||
|
||||
1. **允许哪些群组**（`channels.telegram.groups`）
|
||||
- 没有 `groups` 配置：
|
||||
- 使用 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
|
||||
- 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
|
||||
- 无 `groups` 配置：
|
||||
- 搭配 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
|
||||
- 搭配 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
|
||||
- 已配置 `groups`：作为允许列表（显式 ID 或 `"*"`）
|
||||
|
||||
2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
|
||||
@ -167,13 +168,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
`groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
|
||||
`groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
|
||||
不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 属于 `channels.telegram.groups`。
|
||||
非数字条目会被发送者授权忽略。
|
||||
安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。
|
||||
配对只适用于私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
|
||||
不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
|
||||
非数字条目会在发送者授权中被忽略。
|
||||
安全边界（`2026.2.25+`）：群组发送者身份验证**不会**继承私信配对存储批准。
|
||||
配对仅用于私信。对于群组，请设置 `groupAllowFrom` 或按群组/主题设置 `allowFrom`。
|
||||
如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
|
||||
单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
|
||||
运行时说明：如果完全缺少 `channels.telegram`，运行时默认会以失败关闭方式使用 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
|
||||
运行时注意事项：如果完全缺少 `channels.telegram`，运行时会默认以失败关闭方式使用 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
|
||||
|
||||
示例：允许一个特定群组中的任何成员：
|
||||
|
||||
@ -192,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
示例：只允许一个特定群组内的特定用户：
|
||||
示例：仅允许一个特定群组中的特定用户：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -212,9 +213,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。
|
||||
|
||||
- 将像 `-1001234567890` 这样的负数 Telegram 群组或超级群组聊天 ID 放到 `channels.telegram.groups` 下。
|
||||
- 当你想限制允许群组内哪些人可以触发机器人时，将像 `8734062810` 这样的 Telegram 用户 ID 放到 `groupAllowFrom` 下。
|
||||
- 仅当你希望允许群组中的任何成员都能与机器人交谈时，才使用 `groupAllowFrom: ["*"]`。
|
||||
- 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
|
||||
- 当你想限制允许群组中哪些人可以触发机器人时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
|
||||
- 仅当你希望允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
|
||||
|
||||
</Warning>
|
||||
|
||||
@ -235,9 +236,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
这些只会更新会话状态。使用配置实现持久化。
|
||||
这些只会更新会话状态。使用配置来持久化。
|
||||
|
||||
持久配置示例：
|
||||
持久化配置示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -254,7 +255,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
获取群组聊天 ID：
|
||||
|
||||
- 将群组消息转发给 `@userinfobot` / `@getidsbot`
|
||||
- 或从 `openclaw logs --follow` 中读取 `chat.id`
|
||||
- 或从 `openclaw logs --follow` 读取 `chat.id`
|
||||
- 或检查 Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
@ -264,12 +265,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- Telegram 由 Gateway 网关进程拥有。
|
||||
- 路由是确定性的：Telegram 入站消息会回复到 Telegram（模型不会选择渠道）。
|
||||
- 入站消息会规范化为共享渠道信封，并包含回复元数据和媒体占位符。
|
||||
- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:<threadId>`，以保持话题隔离。
|
||||
- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用支持线程感知的会话键路由，并在回复中保留线程 ID。
|
||||
- 长轮询使用 grammY runner，并按聊天/按线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
|
||||
- 长轮询在每个 Gateway 网关进程内受到保护，因此一次只能有一个活跃 poller 使用某个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个令牌。
|
||||
- 默认情况下，长轮询看门狗会在 120 秒内没有完成的 `getUpdates` 活性信号后触发重启。只有当你的部署在长时间运行工作期间仍然看到误报的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
|
||||
- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。
|
||||
- 群组会话按群组 ID 隔离。论坛主题会追加 `:topic:<threadId>` 以保持主题隔离。
|
||||
- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知的会话键路由它们，并为回复保留线程 ID。
|
||||
- 长轮询使用 grammY runner，并按聊天/线程排序。总体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
|
||||
- 每个 Gateway 网关进程内部都会保护长轮询，因此同一时间只有一个活跃轮询器可以使用一个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个令牌。
|
||||
- 长轮询看门狗默认会在 120 秒内没有完成的 `getUpdates` 活跃性后触发重启。仅当你的部署在长时间运行工作期间仍看到误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
|
||||
- Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。
|
||||
|
||||
## 功能参考
|
||||
@ -279,16 +280,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
OpenClaw 可以实时流式传输部分回复：
|
||||
|
||||
- 直接聊天：预览消息 + `editMessageText`
|
||||
- 群组/话题：预览消息 + `editMessageText`
|
||||
- 群组/主题：预览消息 + `editMessageText`
|
||||
|
||||
要求：
|
||||
|
||||
- `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
|
||||
- `progress` 在 Telegram 上映射为 `partial`（与跨渠道命名兼容）
|
||||
- `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输处于活动状态时为 `true`）
|
||||
- 会检测旧版 `channels.telegram.streamMode` 和布尔 `streaming` 值；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode`
|
||||
- `progress` 在 Telegram 上映射为 `partial`（兼容跨渠道命名）
|
||||
- `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（预览流式传输处于活跃状态时默认为 `true`）
|
||||
- 会检测旧版 `channels.telegram.streamMode` 和布尔值 `streaming`；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode`
|
||||
|
||||
工具进度预览更新是在工具运行时显示的简短“Working...”行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持启用这些内容，以匹配 `v2026.4.22` 及更高版本发布的 OpenClaw 行为。若要保留答案文本的编辑预览但隐藏工具进度行，请设置：
|
||||
工具进度预览更新是在工具运行时显示的短“Working...”行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持启用这些更新，以匹配 `v2026.4.22` 及更高版本中已发布的 OpenClaw 行为。若要为回答文本保留已编辑预览，但隐藏工具进度行，请设置：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -305,39 +306,39 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
仅当你想要只投递最终结果时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的“Working...”消息发送。批准提示、媒体载荷和错误仍然会通过正常的最终投递路由。仅当你只想保留答案预览编辑、同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。
|
||||
仅当你希望只交付最终结果时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度杂讯会被抑制，而不是作为独立“Working...”消息发送。批准提示、媒体载荷和错误仍会通过正常的最终交付路由。仅当你只想保留回答预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。
|
||||
|
||||
对于纯文本回复：
|
||||
|
||||
- 简短的私信/群组/话题预览：OpenClaw 会保留同一条预览消息，并在原处执行最终编辑
|
||||
- 早于约一分钟的预览：OpenClaw 会将完整回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间
|
||||
- 短私信/群组/topic 预览：OpenClaw 保留同一条预览消息，并在原处执行最终编辑
|
||||
- 超过约一分钟的预览：OpenClaw 会将完成的回复作为一条新的最终消息发送，然后清理预览，因此 Telegram 可见时间戳会反映完成时间，而不是预览创建时间
|
||||
|
||||
对于复杂回复（例如媒体负载），OpenClaw 会回退到正常的最终交付，然后清理预览消息。
|
||||
对于复杂回复（例如媒体载荷），OpenClaw 会回退到普通的最终投递，然后清理预览消息。
|
||||
|
||||
预览流式传输与分块流式传输是分开的。当 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，避免重复流式传输。
|
||||
预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，避免双重流式传输。
|
||||
|
||||
如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。
|
||||
如果原生草稿传输不可用/被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。
|
||||
|
||||
仅限 Telegram 的推理流：
|
||||
仅 Telegram 的推理流：
|
||||
|
||||
- `/reasoning stream` 在生成时将推理发送到实时预览
|
||||
- `/reasoning stream` 会在生成时将推理发送到实时预览
|
||||
- 最终答案发送时不包含推理文本
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="格式化和 HTML 回退">
|
||||
<Accordion title="格式与 HTML 回退">
|
||||
出站文本使用 Telegram `parse_mode: "HTML"`。
|
||||
|
||||
- 类 Markdown 文本会渲染为 Telegram 安全的 HTML。
|
||||
- 原始模型 HTML 会被转义，以减少 Telegram 解析失败。
|
||||
- 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。
|
||||
|
||||
链接预览默认启用，可以通过 `channels.telegram.linkPreview: false` 禁用。
|
||||
链接预览默认启用，可通过 `channels.telegram.linkPreview: false` 禁用。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生命令和自定义命令">
|
||||
Telegram 命令菜单注册在启动时通过 `setMyCommands` 处理。
|
||||
Telegram 命令菜单注册会在启动时通过 `setMyCommands` 处理。
|
||||
|
||||
原生命令默认值：
|
||||
|
||||
@ -368,39 +369,39 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
注意：
|
||||
|
||||
- 自定义命令只是菜单项；它们不会自动实现行为
|
||||
- 即使未显示在 Telegram 菜单中，插件/skill 命令在输入时仍然可以工作
|
||||
- 插件/skill 命令即使未显示在 Telegram 菜单中，输入时仍可工作
|
||||
|
||||
如果禁用原生命令，内置命令会被移除。自定义/插件命令在已配置时仍可注册。
|
||||
如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可能注册。
|
||||
|
||||
常见设置失败：
|
||||
|
||||
- `setMyCommands failed` 带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然超出限制；减少插件/skill/自定义命令，或禁用 `channels.telegram.commands.native`。
|
||||
- 当直接的 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并出现 `404: Not Found`，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须只是 Bot API 根地址，并且 `openclaw doctor --fix` 会移除意外尾随的 `/bot<TOKEN>`。
|
||||
- `getMe returned 401` 表示 Telegram 拒绝了已配置的 bot token。使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
|
||||
- `setMyCommands failed` 带有 network/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻断。
|
||||
- `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少插件/skill/自定义命令，或禁用 `channels.telegram.commands.native`。
|
||||
- 当直接 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置为了完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须只是 Bot API 根地址，并且 `openclaw doctor --fix` 会移除意外尾随的 `/bot<TOKEN>`。
|
||||
- `getMe returned 401` 表示 Telegram 拒绝了配置的 bot token。使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会报告为 webhook 清理失败。
|
||||
- `setMyCommands failed` 搭配网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
|
||||
|
||||
### 设备配对命令（`device-pair` 插件）
|
||||
|
||||
安装 `device-pair` 插件后：
|
||||
当安装了 `device-pair` 插件时：
|
||||
|
||||
1. `/pair` 生成设置代码
|
||||
2. 在 iOS 应用中粘贴代码
|
||||
3. `/pair pending` 列出待处理请求（包括角色/作用域）
|
||||
3. `/pair pending` 列出待处理请求（包括角色/范围）
|
||||
4. 批准请求：
|
||||
- `/pair approve <requestId>` 用于显式批准
|
||||
- 只有一个待处理请求时使用 `/pair approve`
|
||||
- 当只有一个待处理请求时使用 `/pair approve`
|
||||
- `/pair approve latest` 用于最近的请求
|
||||
|
||||
设置代码携带一个短期 bootstrap token。内置 bootstrap handoff 会将主节点 token 保持在 `scopes: []`；任何交接的 operator token 都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该 operator allowlist 只满足 operator 请求；非 operator 角色仍然需要其自身角色前缀下的作用域。
|
||||
设置代码携带一个短期 bootstrap token。内置 bootstrap 交接会将主节点 token 保持在 `scopes: []`；任何被交接的操作员 token 都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 范围检查带有角色前缀，因此该操作员允许列表只满足操作员请求；非操作员角色仍需要其自身角色前缀下的范围。
|
||||
|
||||
如果设备使用已更改的认证详情重试（例如角色/作用域/公钥），之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
|
||||
如果设备使用更改后的认证详情重试（例如角色/范围/公钥），之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
|
||||
|
||||
更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="内联按钮">
|
||||
配置内联键盘作用域：
|
||||
配置内联键盘范围：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -414,7 +415,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
按账号覆盖：
|
||||
按账户覆盖：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -432,7 +433,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
作用域：
|
||||
范围：
|
||||
|
||||
- `off`
|
||||
- `dm`
|
||||
@ -442,7 +443,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
旧版 `capabilities: ["inlineButtons"]` 映射到 `inlineButtons: "all"`。
|
||||
|
||||
消息动作示例：
|
||||
消息操作示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -465,8 +466,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="供智能体和自动化使用的 Telegram 消息动作">
|
||||
Telegram 工具动作包括：
|
||||
<Accordion title="供智能体和自动化使用的 Telegram 消息操作">
|
||||
Telegram 工具操作包括：
|
||||
|
||||
- `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
|
||||
- `react`（`chatId`、`messageId`、`emoji`）
|
||||
@ -474,7 +475,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `editMessage`（`chatId`、`messageId`、`content`）
|
||||
- `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`）
|
||||
|
||||
渠道消息动作提供符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
|
||||
渠道消息操作公开了符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
|
||||
|
||||
门控控制：
|
||||
|
||||
@ -484,9 +485,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker`（默认：禁用）
|
||||
|
||||
注意：`edit` 和 `topic-create` 目前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。
|
||||
运行时发送使用活动的配置/secret 快照（启动/重载），因此动作路径不会在每次发送时执行临时 SecretRef 重新解析。
|
||||
运行时发送使用活动的配置/密钥快照（启动/重载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。
|
||||
|
||||
Reaction 移除语义：[/tools/reactions](/zh-CN/tools/reactions)
|
||||
反应移除语义：[/tools/reactions](/zh-CN/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -494,7 +495,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Telegram 支持在生成输出中使用显式回复线程标签：
|
||||
|
||||
- `[[reply_to_current]]` 回复触发消息
|
||||
- `[[reply_to:<id>]]` 回复指定的 Telegram 消息 ID
|
||||
- `[[reply_to:<id>]]` 回复特定 Telegram 消息 ID
|
||||
|
||||
`channels.telegram.replyToMode` 控制处理方式：
|
||||
|
||||
@ -502,29 +503,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
启用回复线程且原始 Telegram 文本或说明可用时，OpenClaw 会自动包含一段原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此较长消息会从开头引用；如果 Telegram 拒绝该引用，则回退为普通回复。
|
||||
当启用回复线程，并且原始 Telegram 文本或标题可用时，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此较长消息会从开头引用，并在 Telegram 拒绝引用时回退到普通回复。
|
||||
|
||||
注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。
|
||||
注意：`off` 禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="论坛话题和线程行为">
|
||||
<Accordion title="论坛 topic 和线程行为">
|
||||
论坛超级群组：
|
||||
|
||||
- 话题会话键追加 `:topic:<threadId>`
|
||||
- 回复和正在输入状态会指向话题线程
|
||||
- 话题配置路径：
|
||||
- topic 会话键追加 `:topic:<threadId>`
|
||||
- 回复和正在输入目标为 topic 线程
|
||||
- topic 配置路径：
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
常规话题（`threadId=1`）特殊情况：
|
||||
通用 topic（`threadId=1`）特殊情况：
|
||||
|
||||
- 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
|
||||
- 正在输入动作仍会包含 `message_thread_id`
|
||||
- 消息发送会省略 `message_thread_id`（Telegram 拒绝 `sendMessage(...thread_id=1)`）
|
||||
- 正在输入操作仍包含 `message_thread_id`
|
||||
|
||||
话题继承：除非被覆盖，话题条目会继承群组设置（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
|
||||
`agentId` 仅属于话题，不会从群组默认值继承。
|
||||
Topic 继承：topic 条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
|
||||
`agentId` 仅属于 topic，不会从群组默认值继承。
|
||||
|
||||
**按话题的智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这让每个话题都拥有自己隔离的工作区、记忆和会话。示例：
|
||||
**按 topic 的智能体路由**：每个 topic 都可以通过在 topic 配置中设置 `agentId` 路由到不同智能体。这会让每个 topic 拥有自己隔离的工作区、记忆和会话。示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -544,26 +545,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
然后每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
然后每个 topic 都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定固定 ACP harness 会话（`bindings[]`，带有 `type: "acp"` 和 `match.channel: "telegram"`、`peer.kind: "group"`，以及像 `-1001234567890:topic:42` 这样的带话题限定的 id）。目前限定于群组/超级群组中的论坛话题。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
|
||||
**持久 ACP topic 绑定**：论坛 topic 可以通过顶层类型化 ACP 绑定固定 ACP harness 会话（`bindings[]` 搭配 `type: "acp"` 和 `match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的 topic 限定 ID）。目前范围限定为群组/超级群组中的论坛 topic。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
|
||||
|
||||
**从聊天启动线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 将当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内固定启动确认。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
|
||||
**从聊天发起线程绑定的 ACP spawn**：`/acp spawn <agent> --thread here|auto` 会将当前 topic 绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在 topic 内固定 spawn 确认。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
|
||||
|
||||
模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的 DM 聊天会保留 DM 路由，但使用线程感知的会话键。
|
||||
模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保持私信路由，但使用线程感知的会话键。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="音频、视频和贴纸">
|
||||
### 音频消息
|
||||
|
||||
Telegram 区分语音留言和音频文件。
|
||||
Telegram 区分语音消息和音频文件。
|
||||
|
||||
- 默认：音频文件行为
|
||||
- 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音留言发送
|
||||
- 入站语音留言转录会在智能体上下文中被框定为机器生成的非可信文本；提及检测仍使用原始转录，因此受提及门控的语音消息会继续工作。
|
||||
- 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音消息发送
|
||||
- 入站语音消息转写会在智能体上下文中被框定为机器生成的、不受信任文本；提及检测仍使用原始转写，因此提及门控的语音消息会继续工作。
|
||||
|
||||
消息动作示例：
|
||||
消息操作示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -577,9 +578,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### 视频消息
|
||||
|
||||
Telegram 区分视频文件和视频留言。
|
||||
Telegram 区分视频文件和视频消息。
|
||||
|
||||
消息动作示例：
|
||||
消息操作示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -591,7 +592,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
视频留言不支持说明；提供的消息文本会单独发送。
|
||||
视频消息不支持标题；提供的消息文本会单独发送。
|
||||
|
||||
### 贴纸
|
||||
|
||||
@ -613,9 +614,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
贴纸会被描述一次（如果可能）并缓存，以减少重复视觉调用。
|
||||
贴纸会被描述一次（尽可能），并缓存以减少重复视觉调用。
|
||||
|
||||
启用贴纸动作：
|
||||
启用贴纸操作：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -629,7 +630,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
发送贴纸动作：
|
||||
发送贴纸操作：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -653,31 +654,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reaction 通知">
|
||||
Telegram reaction 会作为 `message_reaction` 更新到达（独立于消息负载）。
|
||||
<Accordion title="反应通知">
|
||||
Telegram 反应以 `message_reaction` 更新到达（独立于消息载荷）。
|
||||
|
||||
启用后，OpenClaw 会将如下系统事件加入队列：
|
||||
启用后，OpenClaw 会将如下系统事件入队：
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
配置：
|
||||
|
||||
- `channels.telegram.reactionNotifications`：`off | own | all`（默认：`own`）
|
||||
- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认：`minimal`）
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all`（默认：`own`）
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（默认：`minimal`）
|
||||
|
||||
注意：
|
||||
|
||||
- `own` 表示仅用户对机器人发送消息的反应（通过已发送消息缓存尽力处理）。
|
||||
- 反应事件仍遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
|
||||
- Telegram 不会在反应更新中提供话题 ID。
|
||||
- 非论坛群组路由到群聊会话
|
||||
- 论坛群组路由到群组通用话题会话（`:topic:1`），而不是精确的原始话题
|
||||
- `own` 表示仅对机器人发送消息的用户回应生效（通过已发送消息缓存尽力而为）。
|
||||
- 回应事件仍会遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
|
||||
- Telegram 不会在回应更新中提供话题 ID。
|
||||
- 非论坛群组会路由到群聊会话
|
||||
- 论坛群组会路由到群组常规话题会话（`:topic:1`），而不是确切的原始话题
|
||||
|
||||
轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="确认反应">
|
||||
<Accordion title="确认回应">
|
||||
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。
|
||||
|
||||
解析顺序：
|
||||
@ -689,8 +690,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
注意：
|
||||
|
||||
- Telegram 需要 unicode 表情符号（例如 "👀"）。
|
||||
- 使用 `""` 可为某个渠道或账号禁用反应。
|
||||
- Telegram 需要 Unicode 表情符号（例如 "👀"）。
|
||||
- 使用 `""` 可禁用某个渠道或账号的回应。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -717,28 +718,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="长轮询与 webhook">
|
||||
默认使用长轮询。对于 webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。
|
||||
默认使用长轮询。若使用 webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选设置 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。
|
||||
|
||||
本地监听器绑定到 `127.0.0.1:8787`。对于公共入口，可以在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。
|
||||
本地监听器绑定到 `127.0.0.1:8787`。对于公网入口，请在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。
|
||||
|
||||
Webhook 模式会在向 Telegram 返回 `200` 前验证请求防护、Telegram 密钥令牌和 JSON 正文。
|
||||
随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理该更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
|
||||
webhook 模式会先验证请求保护、Telegram secret token 和 JSON 正文，然后才向 Telegram 返回 `200`。
|
||||
随后 OpenClaw 会通过长轮询使用的同一组按聊天/按话题划分的机器人通道异步处理更新，因此较慢的智能体回合不会阻塞 Telegram 的投递确认。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="限制、重试和 CLI 目标">
|
||||
- `channels.telegram.textChunkLimit` 默认值为 4000。
|
||||
- `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。
|
||||
- `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。
|
||||
- `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时时间（未设置时，使用 grammY 默认值）。
|
||||
- `channels.telegram.pollingStallThresholdMs` 默认为 `120000`；仅在误报轮询停滞重启时，才在 `30000` 到 `600000` 之间调整。
|
||||
- `channels.telegram.chunkMode="newline"` 会优先按段落边界（空行）分割，再按长度分割。
|
||||
- `channels.telegram.mediaMaxMb`（默认 100）会限制入站和出站 Telegram 媒体大小。
|
||||
- `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（若未设置，则使用 grammY 默认值）。
|
||||
- `channels.telegram.pollingStallThresholdMs` 默认为 `120000`；仅在轮询停滞重启误报时，调整到 `30000` 到 `600000` 之间。
|
||||
- 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
|
||||
- 回复/引用/转发的补充上下文目前会按接收内容传递。
|
||||
- Telegram 允许列表主要限制谁可以触发智能体，而不是完整的补充上下文删改边界。
|
||||
- 私信历史控制项：
|
||||
- Telegram 允许列表主要用于控制谁可以触发智能体，并不是完整的补充上下文脱敏边界。
|
||||
- 私信历史控制：
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/动作）中的可恢复出站 API 错误。
|
||||
- `channels.telegram.retry` 配置适用于 Telegram 发送辅助逻辑（CLI/工具/actions），用于可恢复的出站 API 错误。
|
||||
|
||||
CLI 发送目标可以是数字聊天 ID 或用户名：
|
||||
|
||||
@ -757,12 +758,12 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
仅限 Telegram 的投票标志：
|
||||
仅 Telegram 可用的投票标志：
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` 用于论坛话题（或使用 `:topic:` 目标）
|
||||
- 用于论坛话题的 `--thread-id`（也可以使用 `:topic:` 目标）
|
||||
|
||||
Telegram 发送还支持：
|
||||
|
||||
@ -770,42 +771,42 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递
|
||||
- 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传
|
||||
|
||||
动作门控：
|
||||
Action gating：
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票
|
||||
- `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送启用状态
|
||||
- `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送功能
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Telegram 中的执行审批">
|
||||
Telegram 支持在审批者私信中进行执行审批，并可选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。
|
||||
<Accordion title="Telegram 中的 exec 审批">
|
||||
Telegram 支持在审批者私信中进行 exec 审批，也可以选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。
|
||||
|
||||
配置路径：
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`（当至少一个审批者可解析时自动启用）
|
||||
- `channels.telegram.execApprovals.approvers`（回退到来自 `commands.ownerAllowFrom` 的数字 owner ID）
|
||||
- `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字所有者 ID）
|
||||
- `channels.telegram.execApprovals.target`: `dm`（默认）| `channel` | `both`
|
||||
- `agentFilter`、`sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及机器人在哪里发送正常回复。它们不会让某人成为执行审批者。当尚不存在命令 owner 时，首次批准的私信配对会引导创建 `commands.ownerAllowFrom`，因此单 owner 设置仍可工作，而无需在 `execApprovals.approvers` 下重复 ID。
|
||||
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及机器人将普通回复发送到哪里。它们不会让某人成为 exec 审批者。当还没有命令所有者时，第一次获批的私信配对会引导生成 `commands.ownerAllowFrom`，因此单所有者设置仍可工作，而无需在 `execApprovals.approvers` 下重复 ID。
|
||||
|
||||
渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。执行审批默认在 30 分钟后过期。
|
||||
渠道投递会在聊天中显示命令文本；只应在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。exec 审批默认在 30 分钟后过期。
|
||||
|
||||
内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。带有 `plugin:` 前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过执行审批解析。
|
||||
内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。
|
||||
|
||||
参见 [执行审批](/zh-CN/tools/exec-approvals)。
|
||||
参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 错误回复控制
|
||||
|
||||
当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制该错误。两个配置键控制此行为：
|
||||
当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制它。两个配置键控制此行为：
|
||||
|
||||
| 键 | 值 | 默认值 | 描述 |
|
||||
| ----------------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 向同一聊天发送错误回复的最小间隔时间。防止故障期间出现错误刷屏。 |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 向同一聊天发送错误回复的最小间隔。可防止中断期间产生错误消息轰炸。 |
|
||||
|
||||
支持按账号、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。
|
||||
|
||||
@ -828,50 +829,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## 故障排除
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="机器人不响应非提及群组消息">
|
||||
<Accordion title="机器人不响应非提及的群组消息">
|
||||
|
||||
- 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。
|
||||
- BotFather：`/setprivacy` -> Disable
|
||||
- 然后将机器人从群组中移除并重新添加
|
||||
- 当配置预期处理未提及的群组消息时，`openclaw channels status` 会发出警告。
|
||||
- `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员探测。
|
||||
- 然后将机器人从群组移除并重新添加
|
||||
- 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。
|
||||
- `openclaw channels status --probe` 可以检查明确的数字群组 ID；通配符 `"*"` 无法探测成员关系。
|
||||
- 快速会话测试：`/activation always`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="机器人完全看不到群组消息">
|
||||
|
||||
- 当存在 `channels.telegram.groups` 时，群组必须被列出（或包含 `"*"`）
|
||||
- 当存在 `channels.telegram.groups` 时，群组必须列在其中（或包含 `"*"`）
|
||||
- 验证机器人是否为群组成员
|
||||
- 查看日志：`openclaw logs --follow` 以了解跳过原因
|
||||
- 查看日志：`openclaw logs --follow`，了解跳过原因
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="命令部分可用或完全不可用">
|
||||
|
||||
- 授权你的发送者身份（配对和/或数字 `allowFrom`）
|
||||
- 即使群组策略为 `open`，命令授权仍然适用
|
||||
- `setMyCommands failed` 伴随 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生菜单
|
||||
- `setMyCommands failed` 伴随网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
|
||||
- 即使群组策略为 `open`，仍会应用命令授权
|
||||
- `setMyCommands failed` 且包含 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单
|
||||
- `setMyCommands failed` 且包含网络/fetch 错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="启动报告未授权令牌">
|
||||
<Accordion title="启动报告未授权 token">
|
||||
|
||||
- `getMe returned 401` 是为已配置机器人令牌返回的 Telegram 身份验证失败。
|
||||
- 在 BotFather 中重新复制或重新生成机器人令牌，然后更新默认账号的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
|
||||
- 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“没有 webhook 存在”只会把同一个错误令牌失败推迟到后续 API 调用。
|
||||
- `getMe returned 401` 是所配置机器人 token 的 Telegram 身份验证失败。
|
||||
- 在 BotFather 中重新复制或重新生成机器人 token，然后为默认账号更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
|
||||
- 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“没有 webhook 存在”只会把同一个错误 token 失败推迟到后续 API 调用。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="轮询或网络不稳定">
|
||||
|
||||
- Node 22+ 加自定义 fetch/proxy 在 AbortSignal 类型不匹配时可能触发立即中止行为。
|
||||
- 某些主机会优先将 `api.telegram.org` 解析到 IPv6；损坏的 IPv6 出站可能导致间歇性 Telegram API 失败。
|
||||
- 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误进行重试。
|
||||
- 如果日志包含 `Polling stall detected`，OpenClaw 默认会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输。
|
||||
- 仅当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍报告误报轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的 proxy、DNS、IPv6 或 TLS 出站问题。
|
||||
- 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：
|
||||
- Node 22+ 加自定义 fetch/proxy 时，如果 AbortSignal 类型不匹配，可能触发立即中止行为。
|
||||
- 某些主机会优先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致间歇性 Telegram API 失败。
|
||||
- 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些错误作为可恢复网络错误重试。
|
||||
- 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成的长轮询存活信号后重启轮询并重建 Telegram 传输。
|
||||
- 只有当长时间运行的 `getUpdates` 调用健康，但你的主机仍报告轮询停滞重启误报时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
|
||||
- 在直连出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -880,7 +881,7 @@ channels:
|
||||
```
|
||||
|
||||
- Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
|
||||
- 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作得更好，请强制选择地址族：
|
||||
- 如果你的主机是 WSL2，或明确在仅 IPv4 行为下效果更好，请强制选择地址族：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -889,7 +890,7 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- RFC 2544 基准范围应答（`198.18.0.0/15`）默认已允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他 private/internal/special-use 地址，你可以选择启用仅限 Telegram 的绕过：
|
||||
- RFC 2544 基准范围响应（`198.18.0.0/15`）默认已允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -898,15 +899,19 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- 同样的选择启用也可按账号在 `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` 中使用。
|
||||
- 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准范围。
|
||||
- 同一个选择加入项也可按账号配置在
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`。
|
||||
- 如果你的代理将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体已默认允许 RFC 2544 基准范围。
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram
|
||||
媒体 SSRF 防护。仅在可信、由操作员控制的代理环境中使用它，例如 Clash、Mihomo 或 Surge fake-IP 路由，并且这些环境会在 RFC 2544 基准测试范围之外合成私有或特殊用途应答。正常的公共互联网 Telegram 访问应保持关闭。
|
||||
媒体 SSRF 防护。仅在受信任、由运维控制的代理环境中使用它，
|
||||
例如 Clash、Mihomo 或 Surge fake-IP 路由，且这些环境会在
|
||||
RFC 2544 基准范围之外合成私有或特殊用途应答。普通公网
|
||||
Telegram 访问请保持关闭。
|
||||
</Warning>
|
||||
|
||||
- 环境覆盖（临时）：
|
||||
- 环境变量覆盖（临时）：
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
@ -926,48 +931,48 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。
|
||||
|
||||
<Accordion title="High-signal Telegram fields">
|
||||
<Accordion title="高价值 Telegram 字段">
|
||||
|
||||
- 启动/凭证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝）
|
||||
- 启动/鉴权：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向普通文件；符号链接会被拒绝）
|
||||
- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`）
|
||||
- 执行批准：`execApprovals`、`accounts.*.execApprovals`
|
||||
- exec 审批：`execApprovals`、`accounts.*.execApprovals`
|
||||
- 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands`
|
||||
- 话题/回复：`replyToMode`
|
||||
- 线程/回复：`replyToMode`
|
||||
- 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming`
|
||||
- 格式/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
|
||||
- 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
|
||||
- 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
|
||||
- 自定义 API 根路径：`apiRoot`（仅限 Bot API 根路径；不要包含 `/bot<TOKEN>`）
|
||||
- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
|
||||
- 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- 表情回应：`reactionNotifications`、`reactionLevel`
|
||||
- reactions：`reactionNotifications`、`reactionLevel`
|
||||
- 错误：`errorPolicy`、`errorCooldownMs`
|
||||
- 写入/历史记录：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
多账号优先级：配置两个或更多账号 ID 时，设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以显式指定默认路由。否则 OpenClaw 会回退到第一个规范化账号 ID，且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。
|
||||
多账号优先级：配置两个或更多账号 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`），以明确默认路由。否则 OpenClaw 会回退到第一个规范化后的账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。
|
||||
</Note>
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
|
||||
将 Telegram 用户配对到 Gateway 网关。
|
||||
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
|
||||
将 Telegram 用户与 Gateway 网关配对。
|
||||
</Card>
|
||||
<Card title="Groups" icon="users" href="/zh-CN/channels/groups">
|
||||
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
|
||||
群组和话题允许列表行为。
|
||||
</Card>
|
||||
<Card title="Channel routing" icon="route" href="/zh-CN/channels/channel-routing">
|
||||
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
|
||||
将入站消息路由到智能体。
|
||||
</Card>
|
||||
<Card title="Security" icon="shield" href="/zh-CN/gateway/security">
|
||||
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
|
||||
威胁模型和加固。
|
||||
</Card>
|
||||
<Card title="Multi-agent routing" icon="sitemap" href="/zh-CN/concepts/multi-agent">
|
||||
<Card title="多智能体路由" icon="sitemap" href="/zh-CN/concepts/multi-agent">
|
||||
将群组和话题映射到智能体。
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
|
||||
<Card title="故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
|
||||
跨渠道诊断。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
191
docs/zh-CN/ci.md
191
docs/zh-CN/ci.md
File diff suppressed because one or more lines are too long
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user