chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
6a665edba5
commit
645011769d
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- 处理 Telegram 功能或 webhook 相关工作
|
||||
- 处理 Telegram 功能或 Webhooks
|
||||
summary: Telegram 机器人支持状态、功能和配置
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T12:04:19Z"
|
||||
generated_at: "2026-04-25T16:48:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 24c32a83e86358afb662c9c354a1b538c90693d07dcc048eaf047dabd6822f7e
|
||||
source_hash: 9509ae437c6017c966d944b6d09af65b106f78ea023174127ac900b8cdc45ede
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
通过 grammY 为机器人私信和群组提供可用于生产环境的支持。默认模式为长轮询；webhook 模式为可选。
|
||||
通过 grammY 为机器人私信和群组提供可用于生产环境的支持。长轮询是默认模式；Webhook 模式为可选。
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
|
||||
Telegram 的默认私信策略是配对。
|
||||
</Card>
|
||||
<Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
|
||||
跨渠道诊断与修复操作手册。
|
||||
跨渠道诊断和修复操作手册。
|
||||
</Card>
|
||||
<Card title="Gateway 网关配置" icon="settings" href="/zh-CN/gateway/configuration">
|
||||
完整的渠道配置模式和示例。
|
||||
@ -30,7 +30,7 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="在 BotFather 中创建机器人令牌">
|
||||
打开 Telegram，并与 **@BotFather** 对话（确认用户名严格为 `@BotFather`）。
|
||||
打开 Telegram，并与 **@BotFather** 聊天（确认账号名完全是 `@BotFather`）。
|
||||
|
||||
运行 `/newbot`，按照提示操作，并保存令牌。
|
||||
|
||||
@ -52,11 +52,11 @@ x-i18n:
|
||||
```
|
||||
|
||||
环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。
|
||||
Telegram **不**使用 `openclaw channels login telegram`；请在配置或环境变量中设置令牌，然后启动 Gateway 网关。
|
||||
Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动网关。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="启动 Gateway 网关并批准第一条私信">
|
||||
<Step title="启动网关并批准第一条私信">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -64,7 +64,7 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
配对码会在 1 小时后过期。
|
||||
配对代码会在 1 小时后过期。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -74,7 +74,7 @@ openclaw pairing approve telegram <CODE>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
令牌解析顺序会识别账户。在实际行为中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。
|
||||
令牌解析顺序是账户感知的。实际行为中，配置值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。
|
||||
</Note>
|
||||
|
||||
## Telegram 端设置
|
||||
@ -85,29 +85,29 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
如果机器人必须看到所有群组消息，可以选择以下任一方式：
|
||||
|
||||
- 通过 `/setprivacy` 禁用隐私模式，或
|
||||
- 通过 `/setprivacy` 关闭隐私模式，或
|
||||
- 将机器人设为群组管理员。
|
||||
|
||||
切换隐私模式时，请在每个群组中移除机器人再重新添加，这样 Telegram 才会应用更改。
|
||||
切换隐私模式后，请在每个群组中移除并重新添加机器人，以便 Telegram 应用该更改。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="群组权限">
|
||||
管理员状态由 Telegram 群组设置控制。
|
||||
管理员状态在 Telegram 群组设置中控制。
|
||||
|
||||
具有管理员权限的机器人会接收所有群组消息，这对始终在线的群组行为很有用。
|
||||
管理员机器人会收到所有群组消息，这对始终在线的群组行为很有帮助。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="有用的 BotFather 开关">
|
||||
<Accordion title="BotFather 的有用开关">
|
||||
|
||||
- `/setjoingroups`：允许或禁止加入群组
|
||||
- `/setprivacy`：控制群组可见性行为
|
||||
- `/setjoingroups` 允许/禁止加入群组
|
||||
- `/setprivacy` 控制群组可见性行为
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 访问控制与激活
|
||||
## 访问控制和激活
|
||||
|
||||
<Tabs>
|
||||
<Tab title="私信策略">
|
||||
@ -118,21 +118,21 @@ openclaw pairing approve telegram <CODE>
|
||||
- `open`（要求 `allowFrom` 包含 `"*"`）
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` 接受 Telegram 数字用户 ID。支持并会规范化 `telegram:` / `tg:` 前缀。
|
||||
`channels.telegram.allowFrom` 接受数字型 Telegram 用户 ID。支持并会规范化 `telegram:` / `tg:` 前缀。
|
||||
当 `dmPolicy: "allowlist"` 且 `allowFrom` 为空时，会阻止所有私信，并被配置校验拒绝。
|
||||
设置时只会询问数字用户 ID。
|
||||
如果你升级后配置中仍包含 `@username` 形式的允许列表条目，请运行 `openclaw doctor --fix` 进行解析（尽力而为；需要 Telegram 机器人令牌）。
|
||||
如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚未设置显式 ID 时）。
|
||||
设置过程只要求填写数字用户 ID。
|
||||
如果你已升级，而配置中包含 `@username` 形式的 allowlist 条目，请运行 `openclaw doctor --fix` 进行解析（尽力而为；需要 Telegram 机器人令牌）。
|
||||
如果你之前依赖配对存储中的 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 还没有显式 ID 时）。
|
||||
|
||||
对于单一拥有者的机器人，建议优先使用 `dmPolicy: "allowlist"` 并显式设置数字 `allowFrom` ID，以便将访问策略稳定保存在配置中（而不是依赖之前的配对批准）。
|
||||
对于单一所有者的机器人，建议优先使用带显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便将访问策略稳定保存在配置中（而不是依赖先前的配对批准）。
|
||||
|
||||
常见困惑：私信配对获批并不意味着“这个发送者在任何地方都已获授权”。
|
||||
配对只授予私信访问权限。群组中的发送者授权仍然来自显式配置的允许列表。
|
||||
如果你希望“我只需授权一次，私信和群组命令都能使用”，请把你的 Telegram 数字用户 ID 放到 `channels.telegram.allowFrom` 中。
|
||||
常见困惑：私信配对批准并不意味着“这个发送者在任何地方都已获授权”。
|
||||
配对只授予私信访问权限。群组发送者授权仍然来自显式配置 allowlist。
|
||||
如果你希望实现“我授权一次，私信和群组命令都能用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`。
|
||||
|
||||
### 查找你的 Telegram 用户 ID
|
||||
|
||||
更安全的方法（无需第三方机器人）：
|
||||
更安全的方法（不使用第三方机器人）：
|
||||
|
||||
1. 给你的机器人发送私信。
|
||||
2. 运行 `openclaw logs --follow`。
|
||||
@ -148,14 +148,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="群组策略和允许列表">
|
||||
有两项控制会同时生效：
|
||||
<Tab title="群组策略和 allowlist">
|
||||
两项控制会共同生效：
|
||||
|
||||
1. **允许哪些群组**（`channels.telegram.groups`）
|
||||
- 没有 `groups` 配置：
|
||||
- 当 `groupPolicy: "open"` 时：任何群组都可以通过群组 ID 检查
|
||||
- 当 `groupPolicy: "allowlist"`（默认）时：在你添加 `groups` 条目（或 `"*"`）之前，群组会被阻止
|
||||
- 已配置 `groups`：其行为是允许列表（显式 ID 或 `"*"`）
|
||||
- 配合 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
|
||||
- 配合 `groupPolicy: "allowlist"`（默认）：在你添加 `groups` 条目（或 `"*"`）之前，群组会被阻止
|
||||
- 已配置 `groups`：其作用是 allowlist（显式 ID 或 `"*"`）
|
||||
|
||||
2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
|
||||
- `open`
|
||||
@ -163,14 +163,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
|
||||
`groupAllowFrom` 条目应为 Telegram 数字用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
|
||||
不要把 Telegram 群组或超级群组 chat ID 放进 `groupAllowFrom`。负数 chat ID 应放在 `channels.telegram.groups` 下。
|
||||
`groupAllowFrom` 条目应为数字型 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
|
||||
不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
|
||||
非数字条目会在发送者授权时被忽略。
|
||||
安全边界（`2026.2.25+`）：群组发送者授权**不会**继承私信配对存储中的批准记录。
|
||||
配对仍然仅用于私信。对于群组，请设置 `groupAllowFrom` 或每个群组 / 每个话题的 `allowFrom`。
|
||||
安全边界（`2026.2.25+`）：群组发送者授权 **不会** 继承私信配对存储的批准。
|
||||
配对仍然仅限私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
|
||||
如果 `groupAllowFrom` 未设置，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
|
||||
单一拥有者机器人的实用模式：将你的用户 ID 设置在 `channels.telegram.allowFrom` 中，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
|
||||
运行时说明：如果 `channels.telegram` 完全缺失，运行时默认会采用失败即关闭的 `groupPolicy="allowlist"`，除非已显式设置 `channels.defaults.groupPolicy`。
|
||||
对于单一所有者机器人的实用模式：将你的用户 ID 设在 `channels.telegram.allowFrom` 中，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
|
||||
运行时说明：如果 `channels.telegram` 完全缺失，运行时默认采用失败即关闭的 `groupPolicy="allowlist"`，除非明确设置了 `channels.defaults.groupPolicy`。
|
||||
|
||||
示例：允许某个特定群组中的任意成员：
|
||||
|
||||
@ -207,17 +207,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。
|
||||
常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。
|
||||
|
||||
- 像 `-1001234567890` 这样的 Telegram 群组或超级群组负数 chat ID，应放在 `channels.telegram.groups` 下。
|
||||
- 像 `8734062810` 这样的 Telegram 用户 ID，应放在 `groupAllowFrom` 下，用于限制已允许群组中哪些人可以触发机器人。
|
||||
- 仅当你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
|
||||
- 将 `-1001234567890` 这类负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
|
||||
- 当你想限制在已允许群组内哪些人可以触发机器人时，将 `8734062810` 这类 Telegram 用户 ID 放在 `groupAllowFrom` 下。
|
||||
- 仅当你希望已允许群组中的任意成员都可以与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="提及行为">
|
||||
默认情况下，群组回复需要提及机器人。
|
||||
默认情况下，群组回复需要提及。
|
||||
|
||||
提及可以来自：
|
||||
|
||||
@ -226,12 +226,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
会话级命令开关：
|
||||
会话级命令切换：
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
这些只会更新会话状态。若要持久生效，请使用配置。
|
||||
这些只会更新会话状态。要持久保存，请使用配置。
|
||||
|
||||
持久配置示例：
|
||||
|
||||
@ -247,10 +247,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
获取群组 chat ID 的方法：
|
||||
获取群组聊天 ID：
|
||||
|
||||
- 将群组消息转发给 `@userinfobot` / `@getidsbot`
|
||||
- 或从 `openclaw logs --follow` 中读取 `chat.id`
|
||||
- 或从 `openclaw logs --follow` 读取 `chat.id`
|
||||
- 或检查 Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
@ -258,14 +258,14 @@ 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 网关进程内部，长轮询都有防护，因此同一时间只有一个活动轮询器能使用某个机器人令牌。如果你仍看到 `getUpdates` 的 409 冲突，很可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个令牌。
|
||||
- 默认情况下，如果 120 秒内没有完成的 `getUpdates` 存活信号，就会触发长轮询看门狗重启。只有在你的部署在长时间运行任务期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值单位为毫秒，允许范围是 `30000` 到 `600000`；支持按账户覆盖。
|
||||
- Telegram 由 Gateway 网关进程拥有。
|
||||
- 路由是确定性的：Telegram 入站回复会返回到 Telegram（模型不会选择渠道）。
|
||||
- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。
|
||||
- 群组会话按群组 ID 隔离。论坛话题会附加 `:topic:<threadId>` 以保持话题隔离。
|
||||
- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知的会话键进行路由，并为回复保留线程 ID。
|
||||
- 长轮询使用 grammY runner，并按每个聊天/每个线程顺序处理。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
|
||||
- 长轮询在每个网关进程内部受保护，因此同一时间只有一个活动轮询器可使用某个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw 网关、脚本或外部轮询器正在使用同一个令牌。
|
||||
- 默认情况下，如果 120 秒内没有完成的 `getUpdates` 存活信号，长轮询看门狗会触发重启。只有在你的部署仍然出现误判的轮询卡住重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值的单位为毫秒，允许范围是 `30000` 到 `600000`；支持按账户覆盖。
|
||||
- Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。
|
||||
|
||||
## 功能参考
|
||||
@ -275,16 +275,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
OpenClaw 可以实时流式传输部分回复：
|
||||
|
||||
- 私聊：预览消息 + `editMessageText`
|
||||
- 群组 / 话题：预览消息 + `editMessageText`
|
||||
- 群组/话题：预览消息 + `editMessageText`
|
||||
|
||||
要求：
|
||||
|
||||
- `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
|
||||
- 在 Telegram 上，`progress` 会映射为 `partial`（与跨渠道命名兼容）
|
||||
- `streaming.preview.toolProgress` 控制工具 / 进度更新是否复用同一条已编辑的预览消息（默认：当预览流式传输处于激活状态时为 `true`）
|
||||
- 会检测旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值；运行 `openclaw doctor --fix` 可将其迁移到 `channels.telegram.streaming.mode`
|
||||
- `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一个被编辑的预览消息（默认：当预览流式传输启用时为 `true`）
|
||||
- 会检测旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode`
|
||||
|
||||
工具进度预览更新是指工具运行期间显示的简短“处理中...”提示行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认启用这些内容，以匹配 `v2026.4.22` 及之后发布版本中的 OpenClaw 行为。若你想保留针对回答文本的已编辑预览，但隐藏工具进度提示行，请设置：
|
||||
工具进度预览更新是指工具运行时显示的简短“处理中...”行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持其启用，以匹配 `v2026.4.22` 及之后已发布的 OpenClaw 行为。如果你想保留用于答案文本的编辑预览，但隐藏工具进度行，请设置：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -301,22 +301,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
仅当你想完全禁用 Telegram 预览编辑时，才使用 `streaming.mode: "off"`。如果你只是想禁用工具进度状态行，请使用 `streaming.preview.toolProgress: false`。
|
||||
仅当你希望完全禁用 Telegram 预览编辑时，才使用 `streaming.mode: "off"`。如果你只是想禁用工具进度状态行，请使用 `streaming.preview.toolProgress: false`。
|
||||
|
||||
对于纯文本回复：
|
||||
|
||||
- 私信：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑（不会发送第二条消息）
|
||||
- 群组 / 话题：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑（不会发送第二条消息）
|
||||
- 私信：OpenClaw 会保留同一个预览消息，并在原地执行最终编辑（不会发送第二条消息）
|
||||
- 群组/话题：OpenClaw 会保留同一个预览消息，并在原地执行最终编辑（不会发送第二条消息）
|
||||
|
||||
对于复杂回复（例如媒体负载），OpenClaw 会回退到正常的最终发送，然后清理预览消息。
|
||||
|
||||
预览流式传输与分块流式传输彼此独立。当 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
|
||||
预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。
|
||||
|
||||
如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。
|
||||
|
||||
仅适用于 Telegram 的推理流：
|
||||
仅限 Telegram 的推理流：
|
||||
|
||||
- `/reasoning stream` 会在生成过程中将推理发送到实时预览中
|
||||
- `/reasoning stream` 会在生成期间将推理发送到实时预览
|
||||
- 最终答案发送时不包含推理文本
|
||||
|
||||
</Accordion>
|
||||
@ -326,14 +326,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- 类 Markdown 文本会被渲染为 Telegram 安全的 HTML。
|
||||
- 原始模型 HTML 会被转义，以减少 Telegram 解析失败。
|
||||
- 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。
|
||||
- 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会重试为纯文本。
|
||||
|
||||
默认启用链接预览，可通过 `channels.telegram.linkPreview: false` 禁用。
|
||||
链接预览默认启用，可通过 `channels.telegram.linkPreview: false` 禁用。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生命令和自定义命令">
|
||||
Telegram 命令菜单注册会在启动时通过 `setMyCommands` 处理。
|
||||
Telegram 命令菜单会在启动时通过 `setMyCommands` 完成注册。
|
||||
|
||||
原生命令默认值：
|
||||
|
||||
@ -356,45 +356,45 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
规则：
|
||||
|
||||
- 名称会被规范化（去掉前导 `/`，转为小写）
|
||||
- 名称会被规范化（移除前导 `/`，转为小写）
|
||||
- 有效模式：`a-z`、`0-9`、`_`，长度 `1..32`
|
||||
- 自定义命令不能覆盖原生命令
|
||||
- 冲突或重复项会被跳过并记录日志
|
||||
- 冲突/重复项会被跳过并记录日志
|
||||
|
||||
说明：
|
||||
|
||||
- 自定义命令只是菜单项；它们不会自动实现行为
|
||||
- 即使未显示在 Telegram 菜单中，插件 / Skills 命令在手动输入时仍然可以工作
|
||||
- 即使未显示在 Telegram 菜单中，plugin/skill 命令在手动输入时仍然可以工作
|
||||
|
||||
如果禁用原生命令，内置命令会被移除。如果已配置，自定义 / 插件命令仍然可以注册。
|
||||
如果原生命令被禁用，内置命令会被移除。自定义/plugin 命令如果已配置，仍然可能被注册。
|
||||
|
||||
常见设置失败：
|
||||
|
||||
- `setMyCommands failed` 且出现 `BOT_COMMANDS_TOO_MUCH`，表示 Telegram 菜单在裁剪后仍然溢出；请减少插件 / Skills / 自定义命令，或禁用 `channels.telegram.commands.native`。
|
||||
- `setMyCommands failed` 且出现 network/fetch 错误，通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
|
||||
- 带有 `BOT_COMMANDS_TOO_MUCH` 的 `setMyCommands failed` 表示 Telegram 菜单在裁剪后仍然溢出；请减少 plugin/skill/自定义命令，或禁用 `channels.telegram.commands.native`。
|
||||
- 带有网络/fetch 错误的 `setMyCommands failed` 通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
|
||||
|
||||
### 设备配对命令（`device-pair` 插件）
|
||||
### 设备配对命令（`device-pair` plugin）
|
||||
|
||||
安装 `device-pair` 插件后：
|
||||
当安装了 `device-pair` plugin 时：
|
||||
|
||||
1. `/pair` 生成设置代码
|
||||
2. 在 iOS 应用中粘贴该代码
|
||||
3. `/pair pending` 列出待处理请求（包括角色 / scopes）
|
||||
2. 在 iOS 应用中粘贴代码
|
||||
3. `/pair pending` 列出待处理请求（包括角色/作用域）
|
||||
4. 批准请求：
|
||||
- `/pair approve <requestId>` 用于显式批准
|
||||
- 当只有一个待处理请求时，可使用 `/pair approve`
|
||||
- `/pair approve latest` 用于批准最近的请求
|
||||
- 当只有一个待处理请求时，使用 `/pair approve`
|
||||
- `/pair approve latest` 用于最近的请求
|
||||
|
||||
设置代码携带一个短期有效的 bootstrap 令牌。内置 bootstrap 交接会将主节点令牌保持为 `scopes: []`；任何交接出的 operator 令牌都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap scope 检查带有角色前缀，因此该 operator 允许列表只能满足 operator 请求；非 operator 角色仍然需要其自身角色前缀下的 scopes。
|
||||
设置代码携带短期有效的引导令牌。内置的引导移交通道会将主节点令牌保持为 `scopes: []`；任何被移交的操作员令牌都仍然受限于 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。引导作用域检查带有角色前缀，因此该操作员 allowlist 仅满足操作员请求；非操作员角色仍然需要其各自角色前缀下的作用域。
|
||||
|
||||
如果设备以更改后的认证详情重试（例如角色 / scopes / 公钥），之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
|
||||
如果设备以变更后的认证详情重试（例如角色/作用域/公钥），之前的待处理请求会被新请求取代，而新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
|
||||
|
||||
更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="内联按钮">
|
||||
配置内联键盘范围：
|
||||
配置内联键盘作用域：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -426,7 +426,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
范围：
|
||||
作用域：
|
||||
|
||||
- `off`
|
||||
- `dm`
|
||||
@ -462,11 +462,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="用于智能体和自动化的 Telegram 消息动作">
|
||||
Telegram 工具动作包括：
|
||||
|
||||
- `sendMessage`（`to`、`content`、可选的 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
|
||||
- `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
|
||||
- `react`（`chatId`、`messageId`、`emoji`）
|
||||
- `deleteMessage`（`chatId`、`messageId`）
|
||||
- `editMessage`（`chatId`、`messageId`、`content`）
|
||||
- `createForumTopic`（`chatId`、`name`、可选的 `iconColor`、`iconCustomEmojiId`）
|
||||
- `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`）
|
||||
|
||||
渠道消息动作提供更易用的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
|
||||
|
||||
@ -477,10 +477,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker`（默认：禁用）
|
||||
|
||||
注意：`edit` 和 `topic-create` 当前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。
|
||||
运行时发送会使用当前激活的配置 / 密钥快照（启动 / 重载时获取），因此动作路径不会在每次发送时临时重新解析 SecretRef。
|
||||
说明：`edit` 和 `topic-create` 当前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。
|
||||
运行时发送使用活动的配置/密钥快照（启动/重载），因此动作路径不会在每次发送时临时执行 `SecretRef` 重新解析。
|
||||
|
||||
移除表情回应的语义：[/tools/reactions](/zh-CN/tools/reactions)
|
||||
移除反应的语义：[/tools/reactions](/zh-CN/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -496,27 +496,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍然会被遵循。
|
||||
说明：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍然会被遵循。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="论坛话题和线程行为">
|
||||
论坛超级群组：
|
||||
|
||||
- 话题会话键会追加 `:topic:<threadId>`
|
||||
- 回复和正在输入状态会定向到该话题线程
|
||||
- 话题会话键会附加 `:topic:<threadId>`
|
||||
- 回复和输入状态会定向到话题线程
|
||||
- 话题配置路径：
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
常规话题（`threadId=1`）特殊情况：
|
||||
|
||||
- 发送消息时省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
|
||||
- 正在输入动作仍包含 `message_thread_id`
|
||||
- 输入状态动作仍然包含 `message_thread_id`
|
||||
|
||||
话题继承：话题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
|
||||
`agentId` 仅适用于话题，不会从群组默认值继承。
|
||||
话题继承：除非被覆盖，话题条目会继承群组设置（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
|
||||
`agentId` 为话题专属，不会从群组默认值继承。
|
||||
|
||||
**按话题进行智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这会为每个话题提供各自隔离的工作区、内存和会话。示例：
|
||||
**按话题的智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这样每个话题都有自己隔离的工作区、记忆和会话。示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -536,23 +536,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
此后，每个话题都有各自的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
随后，每个话题都会有自己的会话键：`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 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]` 中设置 `type: "acp"`，并指定 `match.channel: "telegram"`、`peer.kind: "group"`，以及带话题限定的 ID，如 `-1001234567890:topic:42`）固定到 ACP harness 会话。当前仅适用于群组/超级群组中的论坛话题。参见 [ACP Agents](/zh-CN/tools/acp-agents)。
|
||||
|
||||
**从聊天中生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前话题绑定到一个新的 ACP 会话；后续消息会直接路由到该会话。OpenClaw 会在该话题中固定生成确认消息。要求 `channels.telegram.threadBindings.spawnAcpSessions=true`。
|
||||
**来自聊天的线程绑定 ACP 生成**：`/acp spawn <agent> --thread here|auto` 会将当前话题绑定到一个新的 ACP 会话；后续消息会直接路由到该会话。OpenClaw 会将生成确认消息固定在该话题中。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
|
||||
|
||||
模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但使用支持线程的会话键。
|
||||
模板上下文会公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但会使用线程感知的会话键。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="音频、视频和贴纸">
|
||||
### 音频消息
|
||||
|
||||
Telegram 会区分语音消息和音频文件。
|
||||
Telegram 区分语音便笺和音频文件。
|
||||
|
||||
- 默认：按音频文件处理
|
||||
- 在智能体回复中添加标签 `[[audio_as_voice]]` 可强制按语音消息发送
|
||||
- 默认：音频文件行为
|
||||
- 在智能体回复中添加标签 `[[audio_as_voice]]` 可强制按语音便笺发送
|
||||
- 入站语音便笺转录在智能体上下文中会被标记为机器生成、不可完全信任的文本；提及检测仍使用原始转录，因此基于提及门控的语音消息仍然可用。
|
||||
|
||||
消息动作示例：
|
||||
|
||||
@ -568,7 +569,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### 视频消息
|
||||
|
||||
Telegram 会区分视频文件和视频便笺。
|
||||
Telegram 区分视频文件和视频便笺。
|
||||
|
||||
消息动作示例：
|
||||
|
||||
@ -582,14 +583,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
视频便笺不支持说明文字；提供的消息文本会单独发送。
|
||||
视频便笺不支持标题；提供的消息文本会单独发送。
|
||||
|
||||
### 贴纸
|
||||
|
||||
入站贴纸处理：
|
||||
|
||||
- 静态 WEBP：会下载并处理（占位符 `<media:sticker>`）
|
||||
- 动态 TGS：跳过
|
||||
- 静态 WEBP：下载并处理（占位符 `<media:sticker>`）
|
||||
- 动画 TGS：跳过
|
||||
- 视频 WEBM：跳过
|
||||
|
||||
贴纸上下文字段：
|
||||
@ -604,7 +605,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
贴纸会在可能时描述一次并缓存，以减少重复的视觉调用。
|
||||
贴纸会在可能时仅描述一次并缓存，以减少重复的视觉调用。
|
||||
|
||||
启用贴纸动作：
|
||||
|
||||
@ -631,7 +632,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
搜索缓存贴纸：
|
||||
搜索已缓存贴纸：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -644,8 +645,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="表情回应通知">
|
||||
Telegram 表情回应会以 `message_reaction` 更新到达（独立于消息负载）。
|
||||
<Accordion title="反应通知">
|
||||
Telegram 反应会以 `message_reaction` 更新的形式到达（独立于消息负载）。
|
||||
|
||||
启用后，OpenClaw 会将如下系统事件加入队列：
|
||||
|
||||
@ -653,35 +654,35 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
配置：
|
||||
|
||||
- `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。
|
||||
- `own` 表示仅用户对机器人发送消息的反应（尽力通过已发送消息缓存实现）。
|
||||
- 反应事件仍然遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
|
||||
- Telegram 不会在反应更新中提供线程 ID。
|
||||
- 非论坛群组会路由到群聊会话
|
||||
- 论坛群组会路由到该群组的常规话题会话（`:topic:1`），而不是精确的原始话题
|
||||
- 论坛群组会路由到群组常规话题会话（`:topic:1`），而不是确切的原始话题
|
||||
|
||||
轮询 / webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
|
||||
用于轮询/Webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="确认表情回应">
|
||||
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。
|
||||
<Accordion title="确认反应">
|
||||
`ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认表情符号。
|
||||
|
||||
解析顺序：
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"）
|
||||
- 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"）
|
||||
|
||||
说明：
|
||||
|
||||
- Telegram 期望使用 Unicode emoji（例如 "👀"）。
|
||||
- 使用 `""` 可为某个渠道或账户禁用该表情回应。
|
||||
- Telegram 需要 unicode 表情符号（例如 "👀"）。
|
||||
- 使用 `""` 可为某个渠道或账户禁用该反应。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -707,31 +708,31 @@ 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`）。
|
||||
<Accordion title="长轮询与 Webhook">
|
||||
默认为长轮询。若要使用 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 的投递确认。
|
||||
Webhook 模式会在向 Telegram 返回 `200` 之前校验请求保护、Telegram 密钥令牌以及 JSON 请求体。
|
||||
然后，OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理该更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="限制、重试和 CLI 目标">
|
||||
- `channels.telegram.textChunkLimit` 默认值为 4000。
|
||||
- `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先选择段落边界（空行）。
|
||||
- `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.timeoutSeconds` 会覆盖 Telegram API 客户端超时时间（如果未设置，则应用 grammY 默认值）。
|
||||
- `channels.telegram.pollingStallThresholdMs` 默认为 `120000`；仅在出现误报的轮询卡住重启时，才在 `30000` 到 `600000` 之间调整。
|
||||
- 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
|
||||
- 回复 / 引用 / 转发的补充上下文当前会按接收到的内容传递。
|
||||
- Telegram 允许列表主要用于控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
|
||||
- 回复/引用/转发的补充上下文当前会按接收时原样传递。
|
||||
- Telegram allowlist 主要用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
|
||||
- 私信历史控制：
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI / 工具 / 动作），用于处理可恢复的出站 API 错误。
|
||||
- `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/动作），用于可恢复的出站 API 错误。
|
||||
|
||||
CLI 发送目标可以是数字 chat ID 或用户名：
|
||||
CLI 发送目标可以是数字聊天 ID 或用户名：
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -748,7 +749,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
仅适用于 Telegram 的投票参数：
|
||||
仅限 Telegram 的投票标志：
|
||||
|
||||
- `--poll-duration-seconds`（5-600）
|
||||
- `--poll-anonymous`
|
||||
@ -757,9 +758,9 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
Telegram 发送还支持：
|
||||
|
||||
- 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来实现内联键盘
|
||||
- 使用 `--pin` 或 `--delivery '{"pin":true}'` 请求固定发送，前提是机器人在该聊天中有固定权限
|
||||
- 使用 `--force-document` 以文档形式发送出站图片和 GIF，而不是压缩照片或动画媒体上传
|
||||
- `--presentation` 配合 `buttons` 块，用于在 `channels.telegram.capabilities.inlineButtons` 允许时使用内联键盘
|
||||
- `--pin` 或 `--delivery '{"pin":true}'`，用于在机器人可在该聊天中置顶时请求置顶投递
|
||||
- `--force-document`，用于将出站图像和 GIF 作为文档发送，而不是作为压缩照片或动画媒体上传
|
||||
|
||||
动作门控：
|
||||
|
||||
@ -768,35 +769,35 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Telegram 中的执行审批">
|
||||
Telegram 支持在审批人私信中进行执行审批，并可选择性地在原始聊天或话题中发布提示。审批人必须是 Telegram 数字用户 ID。
|
||||
<Accordion title="Telegram 中的 Exec 审批">
|
||||
Telegram 支持在审批人私信中进行 exec 审批，并可选择在源聊天或话题中发布提示。审批人必须是数字型 Telegram 用户 ID。
|
||||
|
||||
配置路径：
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`（当至少有一个审批人可解析时自动启用）
|
||||
- `channels.telegram.execApprovals.approvers`（回退为来自 `allowFrom` / `defaultTo` 的数字所有者 ID）
|
||||
- `channels.telegram.execApprovals.target`：`dm`（默认） | `channel` | `both`
|
||||
- `channels.telegram.execApprovals.approvers`（回退到来自 `allowFrom` / `defaultTo` 的数字所有者 ID）
|
||||
- `channels.telegram.execApprovals.target`: `dm`（默认）| `channel` | `both`
|
||||
- `agentFilter`、`sessionFilter`
|
||||
|
||||
渠道投递会在聊天中显示命令文本；仅在可信群组 / 话题中启用 `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 会通过 plugin 审批解析；其他 ID 会优先通过 exec 审批解析。
|
||||
|
||||
参见 [执行审批](/zh-CN/tools/exec-approvals)。
|
||||
参见 [Exec approvals](/zh-CN/tools/exec-approvals)。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 错误回复控制
|
||||
|
||||
当智能体遇到投递或提供商错误时，Telegram 可以选择回复错误文本或抑制该错误。两个配置键控制此行为：
|
||||
当智能体遇到投递或提供商错误时，Telegram 可以选择回复错误文本或抑制该回复。两个配置键控制此行为：
|
||||
|
||||
| 键 | 值 | 默认值 | 描述 |
|
||||
| ----------------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 |
|
||||
| `channels.telegram.errorCooldownMs` | 数字（毫秒） | `60000` | 向同一聊天发送错误回复之间的最小间隔时间。可防止故障期间错误刷屏。 |
|
||||
| 键 | 值 | 默认值 | 描述 |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`、`silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 |
|
||||
| `channels.telegram.errorCooldownMs` | 数字（毫秒） | `60000` | 同一聊天两次错误回复之间的最短时间。可防止服务中断期间的错误刷屏。 |
|
||||
|
||||
支持按账户、按群组和按话题覆盖（继承规则与其他 Telegram 配置键相同）。
|
||||
支持按账户、按群组和按话题覆盖（与其他 Telegram 配置键具有相同的继承方式）。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -817,42 +818,42 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## 故障排除
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="机器人不响应未提及它的群组消息">
|
||||
<Accordion title="机器人不响应未提及的群组消息">
|
||||
|
||||
- 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。
|
||||
- BotFather：`/setprivacy` -> Disable
|
||||
- 然后移除机器人并重新添加到群组
|
||||
- 如果 `requireMention=false`，Telegram 隐私模式必须允许完全可见性。
|
||||
- BotFather：`/setprivacy` -> 禁用
|
||||
- 然后移除并重新将机器人添加到群组
|
||||
- 当配置预期接收未提及的群组消息时，`openclaw channels status` 会发出警告。
|
||||
- `openclaw channels status --probe` 可以检查显式的数字群组 ID；无法对通配符 `"*"` 进行成员关系探测。
|
||||
- `openclaw channels status --probe` 可以检查显式数字群组 ID；无法对通配符 `"*"` 进行成员关系探测。
|
||||
- 快速会话测试：`/activation always`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="机器人完全看不到群组消息">
|
||||
<Accordion title="机器人根本看不到群组消息">
|
||||
|
||||
- 当存在 `channels.telegram.groups` 时，必须列出该群组（或包含 `"*"`）
|
||||
- 验证机器人是否已加入该群组
|
||||
- 查看日志：使用 `openclaw logs --follow` 检查跳过原因
|
||||
- 验证机器人是否已加入群组
|
||||
- 查看日志：使用 `openclaw logs --follow` 查找跳过原因
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="命令部分生效或完全不起作用">
|
||||
<Accordion title="命令部分有效或完全无效">
|
||||
|
||||
- 授权你的发送者身份（配对和 / 或数字 `allowFrom`）
|
||||
- 即使群组策略为 `open`，命令授权仍然适用
|
||||
- `setMyCommands failed` 且出现 `BOT_COMMANDS_TOO_MUCH`，表示原生命令菜单条目过多；请减少插件 / Skills / 自定义命令，或禁用原生菜单
|
||||
- `setMyCommands failed` 且出现 network/fetch 错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
|
||||
- 授权你的发送者身份（配对和/或数字 `allowFrom`）
|
||||
- 即使群组策略是 `open`，命令授权仍然适用
|
||||
- 带有 `BOT_COMMANDS_TOO_MUCH` 的 `setMyCommands failed` 表示原生命令菜单条目过多；请减少 plugin/skill/自定义命令，或禁用原生菜单
|
||||
- 带有网络/fetch 错误的 `setMyCommands failed` 通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="轮询或网络不稳定">
|
||||
|
||||
- Node 22+ + 自定义 fetch / 代理 可能会在 AbortSignal 类型不匹配时触发立即中止行为。
|
||||
- 某些主机会优先将 `api.telegram.org` 解析到 IPv6；损坏的 IPv6 出站连接可能导致间歇性的 Telegram API 故障。
|
||||
- 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误重试。
|
||||
- 如果日志包含 `Polling stall detected`，默认情况下，在 120 秒内没有完成的长轮询存活信号时，OpenClaw 会重启轮询并重建 Telegram 传输。
|
||||
- 仅当长时间运行的 `getUpdates` 调用本身健康，但你的主机仍报告误报轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常表明主机与 `api.telegram.org` 之间存在代理、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:
|
||||
@ -860,8 +861,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
|
||||
- 如果你的主机是 WSL2，或明确使用仅 IPv4 行为效果更好，请强制指定地址族选择：
|
||||
- Node 22+ 默认为 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
|
||||
- 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作更好，可强制选择地址族：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -870,7 +871,7 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- RFC 2544 基准范围地址（`198.18.0.0/15`）默认已经被允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有 / 内部 / 特殊用途地址，你可以选择启用仅适用于 Telegram 的绕过：
|
||||
- RFC 2544 基准测试地址范围响应（`198.18.0.0/15`）默认已允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -879,21 +880,19 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- 同样的选择启用也可按账户设置在
|
||||
- 同样的可选启用也支持按账户设置，路径为
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`。
|
||||
- 如果你的代理会将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 基准范围。
|
||||
- 如果你的代理将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 基准测试范围。
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram
|
||||
媒体 SSRF 防护。仅应在受信任、由操作员控制的代理环境中使用它，
|
||||
例如 Clash、Mihomo 或 Surge 的 fake-IP 路由，因为它们可能会生成超出 RFC 2544 基准范围的私有或特殊用途地址。对于正常的公网 Telegram 访问，请保持关闭。
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 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`
|
||||
- 验证 DNS 解析结果：
|
||||
- 校验 DNS 响应：
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -907,44 +906,44 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
## 配置参考
|
||||
|
||||
主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。
|
||||
主参考文档：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。
|
||||
|
||||
<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`
|
||||
- 命令 / 菜单：`commands.native`、`commands.nativeSkills`、`customCommands`
|
||||
- 线程 / 回复：`replyToMode`
|
||||
- exec 审批：`execApprovals`、`accounts.*.execApprovals`
|
||||
- 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands`
|
||||
- 线程/回复：`replyToMode`
|
||||
- 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming`
|
||||
- 格式化 / 投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
|
||||
- 媒体 / 网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
|
||||
- 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
|
||||
- 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
|
||||
- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
|
||||
- 动作 / 能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- 表情回应：`reactionNotifications`、`reactionLevel`
|
||||
- 动作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- 反应：`reactionNotifications`、`reactionLevel`
|
||||
- 错误：`errorPolicy`、`errorCooldownMs`
|
||||
- 写入 / 历史：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
|
||||
- 写入/历史：`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="配对" icon="link" href="/zh-CN/channels/pairing">
|
||||
将 Telegram 用户与 Gateway 网关配对。
|
||||
将 Telegram 用户与网关配对。
|
||||
</Card>
|
||||
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
|
||||
群组和话题允许列表行为。
|
||||
群组和话题 allowlist 行为。
|
||||
</Card>
|
||||
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
|
||||
将入站消息路由到智能体。
|
||||
</Card>
|
||||
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
|
||||
威胁模型与加固。
|
||||
威胁模型和加固。
|
||||
</Card>
|
||||
<Card title="多智能体路由" icon="sitemap" href="/zh-CN/concepts/multi-agent">
|
||||
将群组和话题映射到智能体。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user