chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
0d1a59a93d
commit
ff7a031afa
@ -4,15 +4,15 @@ read_when:
|
||||
summary: Telegram 机器人支持状态、能力和配置
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T12:15:24Z"
|
||||
generated_at: "2026-04-29T14:46:33Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 500f1282c7d6f7350b781a2413737b0e34b00ea8b042703341fd9ddb700ecfb4
|
||||
source_hash: 1ffc0c1a6bb94fbab81ede0f08b0e3a165f06c599d4d06d4b9e70c8ba41121f7
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
生产级支持通过 grammY 实现 bot 私信和群组。默认模式是长轮询；webhook 模式是可选的。
|
||||
可通过 grammY 用于生产环境中的 bot 私信和群组。默认模式是长轮询；webhook 模式为可选。
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
|
||||
@ -30,9 +30,9 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="在 BotFather 中创建 bot token">
|
||||
打开 Telegram，并与 **@BotFather** 聊天（确认账号名正好是 `@BotFather`）。
|
||||
打开 Telegram 并与 **@BotFather** 对话（确认账号名完全是 `@BotFather`）。
|
||||
|
||||
运行 `/newbot`，按照提示操作，并保存 token。
|
||||
运行 `/newbot`，按提示操作，并保存 token。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -52,7 +52,7 @@ x-i18n:
|
||||
```
|
||||
|
||||
环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。
|
||||
Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置 token，然后启动 Gateway 网关。
|
||||
Telegram **不**使用 `openclaw channels login telegram`；请在配置或环境变量中配置 token，然后启动 Gateway 网关。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -74,34 +74,34 @@ openclaw pairing approve telegram <CODE>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
token 解析顺序支持账户感知。实际使用中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。
|
||||
token 解析顺序是账户感知的。实际上，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。
|
||||
</Note>
|
||||
|
||||
## Telegram 端设置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="隐私模式和群组可见性">
|
||||
Telegram bot 默认启用**隐私模式**，这会限制它们能收到的群组消息。
|
||||
Telegram bot 默认启用**隐私模式**，这会限制它们能接收的群组消息。
|
||||
|
||||
如果 bot 必须看到所有群组消息，可以：
|
||||
|
||||
- 通过 `/setprivacy` 禁用隐私模式，或
|
||||
- 将 bot 设为群组管理员。
|
||||
|
||||
切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用该变更。
|
||||
切换隐私模式时，请在每个群组中移除并重新添加 bot，以便 Telegram 应用更改。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="群组权限">
|
||||
管理员状态在 Telegram 群组设置中控制。
|
||||
|
||||
管理员 bot 会收到所有群组消息，这对常驻群组行为很有用。
|
||||
管理员 bot 会接收所有群组消息，这对始终开启的群组行为很有用。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="有用的 BotFather 开关">
|
||||
|
||||
- `/setjoingroups` 用于允许/拒绝添加到群组
|
||||
- `/setjoingroups` 用于允许或拒绝添加到群组
|
||||
- `/setprivacy` 用于群组可见性行为
|
||||
|
||||
</Accordion>
|
||||
@ -118,21 +118,21 @@ token 解析顺序支持账户感知。实际使用中，配置值优先于环
|
||||
- `open`（要求 `allowFrom` 包含 `"*"`）
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到 bot 用户名的 Telegram 账户都能向 bot 发送命令。仅在有意公开且工具受到严格限制的 bot 上使用它；单所有者 bot 应使用 `allowlist` 并搭配数字用户 ID。
|
||||
`dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到 bot 用户名的 Telegram 账户都能向 bot 发送命令。仅应将它用于有意公开且工具严格受限的 bot；单所有者 bot 应使用带有数字用户 ID 的 `allowlist`。
|
||||
|
||||
`channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并标准化。
|
||||
在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账户级 `allowFrom: ["*"]` 条目不会让该账户公开，除非合并后的有效账户 allowlist 仍包含显式通配符。
|
||||
`dmPolicy: "allowlist"` 搭配空 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。
|
||||
设置只会要求输入数字用户 ID。
|
||||
如果你已升级且配置包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 解析它们（尽力而为；需要 Telegram bot token）。
|
||||
如果你之前依赖配对存储 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 还没有显式 ID 时）。
|
||||
`channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。
|
||||
在多账户配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：除非合并后的有效账户 allowlist 仍包含显式通配符，否则账户级 `allowFrom: ["*"]` 条目不会让该账户公开。
|
||||
`dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。
|
||||
设置只会询问数字用户 ID。
|
||||
如果你已升级且配置中包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram bot token）。
|
||||
如果你之前依赖配对存储的 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。
|
||||
|
||||
对于单所有者 bot，优先使用 `dmPolicy: "allowlist"` 并搭配显式数字 `allowFrom` ID，以便将访问策略持久保存在配置中（而不是依赖之前的配对批准）。
|
||||
对于单所有者 bot，优先使用带有显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便在配置中保持访问策略持久（而不是依赖之前的配对批准）。
|
||||
|
||||
常见困惑：私信配对批准并不表示“这个发送者在所有地方都已授权”。
|
||||
配对授予私信访问权限。如果还没有命令所有者，第一次获批的配对还会设置 `commands.ownerAllowFrom`，让仅所有者命令和执行批准拥有显式操作员账户。
|
||||
常见混淆：私信配对批准并不表示“此发送者在所有地方都已授权”。
|
||||
配对授予私信访问权限。如果还没有命令所有者，第一次批准的配对也会设置 `commands.ownerAllowFrom`，以便仅所有者命令和 exec 批准拥有显式操作员账户。
|
||||
群组发送者授权仍来自显式配置 allowlist。
|
||||
如果你想要“我授权一次后，私信和群组命令都能工作”，请把你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
|
||||
如果你希望“我授权一次后，私信和群组命令都能工作”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
|
||||
|
||||
### 查找你的 Telegram 用户 ID
|
||||
|
||||
@ -148,18 +148,18 @@ token 解析顺序支持账户感知。实际使用中，配置值优先于环
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
第三方方法（隐私性较低）：`@userinfobot` 或 `@getidsbot`。
|
||||
第三方方法（隐私较低）：`@userinfobot` 或 `@getidsbot`。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="群组策略和 allowlist">
|
||||
两个控制项会共同生效：
|
||||
两个控制项会一起生效：
|
||||
|
||||
1. **允许哪些群组**（`channels.telegram.groups`）
|
||||
- 没有 `groups` 配置：
|
||||
- 搭配 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
|
||||
- 搭配 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
|
||||
- 已配置 `groups`：作为 allowlist 生效（显式 ID 或 `"*"`）
|
||||
- 使用 `groupPolicy: "open"`：任何群组都能通过群组 ID 检查
|
||||
- 使用 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
|
||||
- 已配置 `groups`：作为 allowlist（显式 ID 或 `"*"`）
|
||||
|
||||
2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
|
||||
- `open`
|
||||
@ -167,16 +167,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
|
||||
`groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被标准化）。
|
||||
不要把 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
|
||||
非数字条目会在发送者授权中被忽略。
|
||||
安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。
|
||||
配对保持仅限私信。对于群组，请设置 `groupAllowFrom` 或按群组/主题设置 `allowFrom`。
|
||||
如果 `groupAllowFrom` 未设置，Telegram 会回退到配置 `allowFrom`，而不是配对存储。
|
||||
单所有者 bot 的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，不设置 `groupAllowFrom`，并在 `channels.telegram.groups` 下允许目标群组。
|
||||
运行时说明：如果完全缺少 `channels.telegram`，运行时默认采用故障关闭的 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
|
||||
`groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
|
||||
不要将 Telegram 群组或超级群组 chat ID 放入 `groupAllowFrom`。负数 chat ID 属于 `channels.telegram.groups`。
|
||||
非数字条目会被发送者授权忽略。
|
||||
安全边界（`2026.2.25+`）：群组发送者鉴权**不会**继承私信配对存储批准。
|
||||
配对仅适用于私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。
|
||||
如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
|
||||
单所有者 bot 的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
|
||||
运行时说明：如果完全缺少 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，否则运行时默认采用故障关闭的 `groupPolicy="allowlist"`。
|
||||
|
||||
示例：允许一个特定群组中的任何成员：
|
||||
示例：允许一个特定群组中的任意成员：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
示例：只允许一个特定群组中的特定用户：
|
||||
示例：只允许一个特定群组内的特定用户：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -213,21 +213,21 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。
|
||||
|
||||
- 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
|
||||
- 当你想限制允许群组中哪些人可以触发 bot 时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
|
||||
- 仅当你希望允许群组中的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。
|
||||
- 将像 `-1001234567890` 这样的负数 Telegram 群组或超级群组 chat ID 放在 `channels.telegram.groups` 下。
|
||||
- 当你想限制已允许群组内哪些人可以触发 bot 时，将像 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
|
||||
- 仅当你希望已允许群组中的任何成员都能与 bot 对话时，才使用 `groupAllowFrom: ["*"]`。
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="提及行为">
|
||||
群组回复默认要求提及。
|
||||
群组回复默认需要提及。
|
||||
|
||||
提及可以来自：
|
||||
|
||||
- 原生 `@botusername` 提及，或
|
||||
- 以下位置中的提及模式：
|
||||
- 以下位置的提及模式：
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
@ -236,9 +236,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
这些只会更新会话状态。使用配置实现持久化。
|
||||
这些只更新会话状态。使用配置实现持久化。
|
||||
|
||||
持久化配置示例：
|
||||
持久配置示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -252,10 +252,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
获取群组聊天 ID：
|
||||
获取群组 chat ID：
|
||||
|
||||
- 将群组消息转发给 `@userinfobot` / `@getidsbot`
|
||||
- 或从 `openclaw logs --follow` 读取 `chat.id`
|
||||
- 或从 `openclaw logs --follow` 中读取 `chat.id`
|
||||
- 或检查 Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
@ -265,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 网关进程内部都会保护长轮询，因此同一时间只有一个活跃轮询器可以使用一个 bot token。如果你仍然看到 `getUpdates` 409 冲突，可能有另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个 token。
|
||||
- 默认情况下，长轮询 watchdog 会在 120 秒内没有完成 `getUpdates` 活性检测后触发重启。仅当你的部署在长时间运行任务期间仍看到误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围是 `30000` 到 `600000`；支持按账户覆盖。
|
||||
- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。
|
||||
- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:<threadId>` 以保持话题隔离。
|
||||
- 私信消息可以携带 `message_thread_id`；OpenClaw 使用线程感知的会话键进行路由，并保留线程 ID 用于回复。
|
||||
- 长轮询使用 grammY runner，并按 chat/线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
|
||||
- 长轮询在每个 Gateway 网关进程内受到保护，因此同一时间只有一个活动 poller 可以使用一个 bot token。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一个 token。
|
||||
- 默认情况下，长轮询 watchdog 会在 120 秒内没有完成 `getUpdates` 活性检查后触发重启。仅当你的部署在长时间运行工作期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持每账户覆盖。
|
||||
- Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。
|
||||
|
||||
## 功能参考
|
||||
@ -280,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`）
|
||||
- 在 Telegram 上，`progress` 映射为 `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
|
||||
{
|
||||
@ -306,22 +306,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
仅当你希望只交付最终结果时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的“Working...”消息发送。批准提示、媒体载荷和错误仍会通过正常最终交付路由。仅当你只想保留回答预览编辑，同时隐藏工具进度 Status 行时，才使用 `streaming.preview.toolProgress: false`。
|
||||
仅当你需要只交付最终内容时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，并且通用工具/进度杂音会被抑制，而不是作为独立的“Working...”消息发送。批准提示、媒体载荷和错误仍通过正常最终交付路由。仅当你想保留答案预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。
|
||||
|
||||
对于纯文本回复：
|
||||
|
||||
- 短私信/群组/话题预览：OpenClaw 保持同一条预览消息，并在原处执行最终编辑
|
||||
- 超过约一分钟的预览：OpenClaw 将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳反映的是完成时间，而不是预览创建时间
|
||||
- 简短的私信/群组/主题预览：OpenClaw 保留同一条预览消息，并在原位执行最终编辑
|
||||
- 早于约一分钟的预览：OpenClaw 会将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间
|
||||
|
||||
对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终投递，然后清理预览消息。
|
||||
|
||||
预览流式传输独立于分块流式传输。当 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
|
||||
预览流式传输独立于分块流式传输。当为 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
|
||||
|
||||
如果原生草稿传输不可用/被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。
|
||||
如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。
|
||||
|
||||
仅 Telegram 的推理流：
|
||||
仅限 Telegram 的推理流：
|
||||
|
||||
- `/reasoning stream` 在生成时将推理发送到实时预览
|
||||
- `/reasoning stream` 会在生成期间将推理发送到实时预览
|
||||
- 最终答案发送时不包含推理文本
|
||||
|
||||
</Accordion>
|
||||
@ -342,9 +342,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
原生命令默认值：
|
||||
|
||||
- `commands.native: "auto"` 为 Telegram 启用原生命令
|
||||
- `commands.native: "auto"` 会为 Telegram 启用原生命令
|
||||
|
||||
添加自定义命令菜单条目：
|
||||
添加自定义命令菜单项：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -361,47 +361,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
规则：
|
||||
|
||||
- 名称会规范化（去掉前导 `/`，转为小写）
|
||||
- 名称会被规范化（去掉开头的 `/`，转换为小写）
|
||||
- 有效模式：`a-z`、`0-9`、`_`，长度 `1..32`
|
||||
- 自定义命令不能覆盖原生命令
|
||||
- 冲突/重复项会被跳过并记录日志
|
||||
|
||||
注意事项：
|
||||
注意：
|
||||
|
||||
- 自定义命令只是菜单条目；它们不会自动实现行为
|
||||
- 即使插件/skill 命令未显示在 Telegram 菜单中，输入时仍可工作
|
||||
- 自定义命令只是菜单项；它们不会自动实现行为
|
||||
- 插件/Skills 命令即使未显示在 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 拒绝了配置的机器人令牌。请用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
|
||||
- `setMyCommands failed` 携带网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
|
||||
- `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少插件/Skills/自定义命令，或禁用 `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 拒绝了已配置的机器人令牌。用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
|
||||
- `setMyCommands failed` 并带有网络/fetch 错误，通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
|
||||
|
||||
### 设备配对命令（`device-pair` 插件）
|
||||
|
||||
安装 `device-pair` 插件后：
|
||||
|
||||
1. `/pair` 生成设置代码
|
||||
2. 在 iOS 应用中粘贴代码
|
||||
3. `/pair pending` 列出待处理请求（包括角色/作用域）
|
||||
2. 在 iOS app 中粘贴代码
|
||||
3. `/pair pending` 列出待处理请求（包括角色/范围）
|
||||
4. 批准请求：
|
||||
- `/pair approve <requestId>` 用于显式批准
|
||||
- `/pair approve` 用于只有一个待处理请求的情况
|
||||
- 只有一个待处理请求时使用 `/pair approve`
|
||||
- `/pair approve latest` 用于最近的请求
|
||||
|
||||
设置代码携带一个短期有效的引导令牌。内置引导交接会将主节点令牌保持在 `scopes: []`；任何交接出去的操作员令牌都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。引导作用域检查带有角色前缀，因此该操作员允许列表只满足操作员请求；非操作员角色仍需要其自身角色前缀下的作用域。
|
||||
设置代码携带一个短期有效的 bootstrap 令牌。内置 bootstrap 交接会将主节点令牌保持在 `scopes: []`；任何被交接的操作员令牌仍限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 内。Bootstrap 范围检查带有角色前缀，因此该操作员 allowlist 只满足操作员请求；非操作员角色仍需要其自身角色前缀下的范围。
|
||||
|
||||
如果设备使用已变更的认证详情重试（例如角色/作用域/公钥），之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
|
||||
如果设备用已更改的认证详细信息重试（例如角色/范围/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
|
||||
|
||||
更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="内联按钮">
|
||||
配置内联键盘作用域：
|
||||
配置内联键盘范围：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -433,7 +433,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
作用域：
|
||||
范围：
|
||||
|
||||
- `off`
|
||||
- `dm`
|
||||
@ -441,9 +441,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist`（默认）
|
||||
|
||||
旧版 `capabilities: ["inlineButtons"]` 映射到 `inlineButtons: "all"`。
|
||||
旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。
|
||||
|
||||
消息操作示例：
|
||||
消息动作示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -461,33 +461,33 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
回调点击会作为文本传递给智能体：
|
||||
回调点击会作为文本传给智能体：
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="面向智能体和自动化的 Telegram 消息操作">
|
||||
Telegram 工具操作包括：
|
||||
<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`）。
|
||||
渠道消息动作公开符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
|
||||
|
||||
门控控制项：
|
||||
门控控制：
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker`（默认：禁用）
|
||||
- `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>
|
||||
|
||||
@ -503,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_*]]` 标签仍会被遵循。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="论坛话题和线程行为">
|
||||
<Accordion title="论坛主题和线程行为">
|
||||
论坛超级群组：
|
||||
|
||||
- 话题会话键追加 `:topic:<threadId>`
|
||||
- 回复和正在输入目标为话题线程
|
||||
- 话题配置路径：
|
||||
- 主题会话键追加 `:topic:<threadId>`
|
||||
- 回复和输入状态会定向到主题线程
|
||||
- 主题配置路径：
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
常规话题（`threadId=1`）特殊情况：
|
||||
General 主题（`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` 仅限话题，不会从群组默认值继承。
|
||||
主题继承：主题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
|
||||
`agentId` 仅限主题使用，不会从群组默认值继承。
|
||||
|
||||
**按话题的智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同智能体。这让每个话题拥有自己隔离的工作区、记忆和会话。示例：
|
||||
**按主题进行智能体路由**：每个主题都可以通过在主题配置中设置 `agentId` 路由到不同智能体。这会让每个主题拥有自己的隔离工作区、记忆和会话。示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -545,13 +545,13 @@ 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"`，以及类似 `-1001234567890:topic:42` 的主题限定 ID）固定 ACP harness 会话。目前范围限定为群组/超级群组中的论坛主题。参见 [ACP 智能体](/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>
|
||||
|
||||
@ -561,10 +561,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Telegram 区分语音便笺和音频文件。
|
||||
|
||||
- 默认：音频文件行为
|
||||
- 在智能体回复中使用标签 `[[audio_as_voice]]` 强制发送语音便笺
|
||||
- 入站语音便笺转录会在智能体上下文中被框定为机器生成的、不受信任的文本；提及检测仍使用原始转录，因此受提及门控的语音消息继续可用。
|
||||
- 在智能体回复中使用标签 `[[audio_as_voice]]` 可强制按语音便笺发送
|
||||
- 入站语音便笺转录会在智能体上下文中被框定为机器生成的、不受信任的文本；提及检测仍使用原始转录，因此由提及门控的语音消息会继续工作。
|
||||
|
||||
消息操作示例：
|
||||
消息动作示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -580,7 +580,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Telegram 区分视频文件和视频便笺。
|
||||
|
||||
消息操作示例：
|
||||
消息动作示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -592,7 +592,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
视频便笺不支持标题；提供的消息文本会单独发送。
|
||||
视频便笺不支持说明；提供的消息文本会单独发送。
|
||||
|
||||
### 贴纸
|
||||
|
||||
@ -614,9 +614,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
贴纸会被描述一次（如果可能）并缓存，以减少重复的视觉调用。
|
||||
贴纸会被描述一次（在可行时），并被缓存以减少重复视觉调用。
|
||||
|
||||
启用贴纸操作：
|
||||
启用贴纸动作：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -630,7 +630,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
发送贴纸操作：
|
||||
发送贴纸动作：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -654,31 +654,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="反应通知">
|
||||
Telegram 反应会作为 `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 处理入站消息时发送一个确认表情符号。
|
||||
|
||||
解析顺序：
|
||||
@ -686,17 +686,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"）
|
||||
- 智能体身份表情符号兜底（`agents.list[].identity.emoji`，否则为 "👀"）
|
||||
|
||||
注意事项：
|
||||
|
||||
- Telegram 需要 unicode 表情符号（例如 "👀"）。
|
||||
- 使用 `""` 可为某个渠道或账号禁用该反应。
|
||||
- Telegram 期望 unicode 表情符号（例如 "👀"）。
|
||||
- 使用 `""` 可为某个渠道或账号禁用回应。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="来自 Telegram 事件和命令的配置写入">
|
||||
渠道配置写入默认启用（`configWrites !== false`）。
|
||||
默认启用渠道配置写入（`configWrites !== false`）。
|
||||
|
||||
Telegram 触发的写入包括：
|
||||
|
||||
@ -718,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 密钥令牌和 JSON 正文，然后再向 Telegram 返回 `200`。
|
||||
随后 OpenClaw 会通过长轮询所用的同一套按聊天/按话题机器人通道异步处理该更新，因此缓慢的智能体轮次不会占用 Telegram 的投递 ACK。
|
||||
Webhook 模式会先验证请求保护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。
|
||||
OpenClaw 随后会通过长轮询使用的同一套按聊天/按话题机器人通道异步处理更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="限制、重试和 CLI 目标">
|
||||
- `channels.telegram.textChunkLimit` 默认值为 4000。
|
||||
- `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。
|
||||
- `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 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界安全发送重试，但不会重试可能导致可见消息重复的模糊发送后网络信封。
|
||||
- `channels.telegram.retry` 配置应用于 Telegram 发送辅助工具（CLI/工具/操作），用于可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界的安全发送重试，但不会重试可能重复可见消息的、语义不明确的发送后网络信封。
|
||||
|
||||
CLI 发送目标可以是数字聊天 ID 或用户名：
|
||||
|
||||
@ -758,55 +758,55 @@ 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 发送还支持：
|
||||
|
||||
- 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带 `buttons` 块的 `--presentation` 创建内联键盘
|
||||
- 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带 `buttons` 块的 `--presentation` 来创建内联键盘
|
||||
- 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递
|
||||
- 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传
|
||||
|
||||
操作门控：
|
||||
|
||||
- `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` 中的数字所有者 ID）
|
||||
- `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both`
|
||||
- `channels.telegram.execApprovals.enabled`（至少解析到一个审批人时自动启用）
|
||||
- `channels.telegram.execApprovals.approvers`（回退到来自 `commands.ownerAllowFrom` 的数字所有者 ID）
|
||||
- `channels.telegram.execApprovals.target`: `dm`（默认）| `channel` | `both`
|
||||
- `agentFilter`、`sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及机器人向哪里发送普通回复。它们不会让某人成为执行审批者。当还没有命令所有者时，第一个已批准的私信配对会引导创建 `commands.ownerAllowFrom`，因此单所有者设置仍可工作，无需在 `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.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 |
|
||||
| `channels.telegram.errorCooldownMs` | 数字（ms） | `60000` | 向同一聊天发送错误回复之间的最短时间。在故障期间防止错误刷屏。 |
|
||||
|
||||
支持按账号、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。
|
||||
|
||||
@ -829,13 +829,13 @@ 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 --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法探测成员身份。
|
||||
- 快速会话测试：`/activation always`。
|
||||
|
||||
</Accordion>
|
||||
@ -843,40 +843,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
<Accordion title="机器人完全看不到群组消息">
|
||||
|
||||
- 当 `channels.telegram.groups` 存在时，群组必须列出（或包含 `"*"`）
|
||||
- 验证机器人是否为群组成员
|
||||
- 查看日志：`openclaw logs --follow` 查看跳过原因
|
||||
- 验证机器人在群组中的成员身份
|
||||
- 查看日志：`openclaw logs --follow`，了解跳过原因
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="命令部分可用或完全不可用">
|
||||
|
||||
- 授权你的发送者身份（配对和/或数字 `allowFrom`）
|
||||
- 即使群组策略为 `open`，命令授权仍然适用
|
||||
- `setMyCommands failed` 加上 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生菜单
|
||||
- 启动时的 `deleteMyCommands` / `setMyCommands` 调用是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题
|
||||
- 即使群组策略是 `open`，命令授权仍然适用
|
||||
- `setMyCommands failed` 并带有 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目太多；减少插件/skill/自定义命令，或禁用原生菜单
|
||||
- 启动时的 `deleteMyCommands` / `setMyCommands` 调用是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/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 调用。
|
||||
- 如果 `deleteWebhook` 在轮询启动期间因瞬时网络错误失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告空 webhook URL 时，轮询会继续，因为清理已经满足。
|
||||
|
||||
</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`，OpenClaw 默认会在 120 秒内没有完成的长轮询活性后重启轮询并重建 Telegram 传输。
|
||||
- 当正在运行的轮询账号在启动宽限期后尚未完成 `getUpdates`，或其最后一次成功的轮询传输活动已过期时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。
|
||||
- 只有当长时间运行的 `getUpdates` 调用健康，但你的主机仍报告误报的轮询停滞重启时，才增大 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
|
||||
- Telegram 还会遵循进程代理环境变量用于 Bot API 传输，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍然可以绕过 `api.telegram.org`。
|
||||
- 如果在服务环境中通过 `OPENCLAW_PROXY_URL` 配置了 OpenClaw 托管代理，且不存在标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。
|
||||
- 在直连出站/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`、正在运行的 webhook 账号在启动宽限期后没有完成 `setWebhook`，或上一次成功的轮询传输活动已过期时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。
|
||||
- 只有在长时间运行的 `getUpdates` 调用健康，但你的主机仍报告误报的轮询停滞重启时，才增大 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
|
||||
- Telegram 的 Bot API 传输也遵循进程代理环境变量，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍可绕过 `api.telegram.org`。
|
||||
- 如果服务环境通过 `OPENCLAW_PROXY_URL` 配置了 OpenClaw 托管代理，且不存在标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。
|
||||
- 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -894,7 +894,7 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- 默认已允许 Telegram 媒体下载使用 RFC 2544 基准范围响应（`198.18.0.0/15`）。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
|
||||
- RFC 2544 基准范围答案（`198.18.0.0/15`）默认已经允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -903,20 +903,18 @@ 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 访问应保持关闭。
|
||||
`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
|
||||
@ -932,27 +930,27 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。
|
||||
|
||||
<Accordion title="高价值 Telegram 字段">
|
||||
<Accordion title="高信号 Telegram 字段">
|
||||
|
||||
- 启动/认证：`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`
|
||||
- 流式传输：`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>`）
|
||||
- 自定义 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>
|
||||
|
||||
## 相关内容
|
||||
@ -962,7 +960,7 @@ dig +short api.telegram.org AAAA
|
||||
将 Telegram 用户配对到 Gateway 网关。
|
||||
</Card>
|
||||
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
|
||||
群组和主题允许列表行为。
|
||||
群组和 topic 允许列表行为。
|
||||
</Card>
|
||||
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
|
||||
将入站消息路由到智能体。
|
||||
@ -971,7 +969,7 @@ dig +short api.telegram.org AAAA
|
||||
威胁模型与加固。
|
||||
</Card>
|
||||
<Card title="多智能体路由" icon="sitemap" href="/zh-CN/concepts/multi-agent">
|
||||
将群组和主题映射到智能体。
|
||||
将群组和 topic 映射到智能体。
|
||||
</Card>
|
||||
<Card title="故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
|
||||
跨渠道诊断。
|
||||
|
||||
297
docs/zh-CN/ci.md
297
docs/zh-CN/ci.md
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue
Block a user