Telegram

此页面将 Telegram 机器人连接到 OpenClaw，并设置谁可以给它发送消息。

Telegram 已通过 grammY 为机器人私聊和群组提供生产就绪支持。长轮询是默认传输方式。Webhook 模式为可选。

配对

Telegram 的默认私聊策略为配对。

通道故障排查

跨通道诊断和修复手册。

网关配置

完整的通道配置模式和示例。

各页面涵盖内容¶

Telegram 设置 — 安装机器人、设置 Token、批准第一条私聊，并将机器人添加到群组。
Telegram 访问控制 — 私聊策略、群组允许列表、提及门控以及按聊天的工具策略。
Telegram 消息行为 — 运行时模型、流式预览、原生命令、回复标签和发送限制。
Telegram 线程与会话 — 论坛主题会话键、按主题的代理以及 ACP 绑定。
Telegram 富消息与审批 — Bot API 10.3 富消息、内联按钮、消息操作和执行审批。
Telegram 媒体与附件 — 照片相册、语音和视频笔记、位置、场所和贴纸。
Telegram 事件与操作 — 反应通知、配置写入和错误回复策略。
Telegram 传输方式 — 长轮询与 Webhook 模式对比。
Telegram Dashboard Mini App — 使用 /dashboard 在 Telegram 内打开 Control UI。
Telegram 故障排查 — 静默群组、缺失命令、被拒绝的 Token 和不稳定的轮询。

各章节迁移位置¶

来自先前单页版本的每个章节标题都在此保留其锚点，因此诸如 /channels/telegram#troubleshooting 之类的现有链接仍然可以解析。每个条目都指向当前承载该内容的页面。

配置参考¶

主要参考：配置参考 - Telegram.

openclaw doctor --fix 会从其原有配置作用域中移除已弃用的调优设置（timeoutSeconds、mediaGroupFlushMs、pollingStallThresholdMs、retry 和 errorCooldownMs）。账户名称和发送者特定的工具策略键会被保留，即使它们与已弃用设置名称匹配。

高信号 Telegram 字段

启动/认证：enabled、botToken、tokenFile（必须是常规文件；拒绝符号链接）、accounts.*
访问控制：dmPolicy、allowFrom、direct.*.tools、direct.*.toolsBySender、groupPolicy、groupAllowFrom、groups、groups.*.topics.*、顶层 bindings[]（type: "acp"）
群组介绍：joinIntro、accounts.*.joinIntro（默认：true）
主题默认值：groups.<chatId>.topics."*" 适用于未匹配的论坛主题；精确主题 ID 会覆盖它
执行审批：execApprovals、accounts.*.execApprovals
命令/菜单：commands.native、commands.nativeSkills、customCommands
线程/回复：replyToMode、threadBindings
流式传输：streaming（模式 off | partial | block | progress）、streaming.preview.toolProgress
格式/投递：textChunkLimit、streaming.chunkMode、richMessages、markdown.tables（off | bullets | code | block）、linkPreview、responsePrefix
媒体/网络：mediaMaxMb、network.autoSelectFamily、network.dangerouslyAllowPrivateNetwork、proxy
自定义 API 根：apiRoot（仅 Bot API 根；不要包含 /bot<TOKEN>）、trustedLocalFileRoots（自托管 Bot API 的绝对 file_path 根）
webhook：webhookUrl、webhookSecret、webhookPath、webhookCertPath、legacyWebhook（默认为现有监听器；false 仅使用 Gateway 端口）
操作/能力：capabilities.inlineButtons、actions.sendMessage|editMessage|deleteMessage|reactions|sticker|createForumTopic|editForumTopic
反应：reactionNotifications、reactionLevel
错误：errorPolicy、silentErrorReplies
写入/历史：configWrites、historyLimit、dmHistoryLimit、dms.*.historyLimit

Note

多账户优先级：配置了两个或更多账户 ID 时，请设置 channels.telegram.defaultAccount（或包含 channels.telegram.accounts.default），以明确默认路由。否则 OpenClaw 会回退到第一个规范化账户 ID，并且 openclaw doctor 会发出警告。省略的账户 dmPolicy、groupPolicy、allowFrom 和 groupAllowFrom 继承渠道根配置，而不是 accounts.default.*。显式账户策略优先；如果两个作用域都未设置，DM 使用 pairing，群组使用 allowlist。

多智能体账户所有权¶

每个 Telegram 账户都需要一个可解析的智能体所有者。要将默认账户绑定到 main，请在顶层 bindings 数组中添加此条目：

json5 validate=false { agentId: "main", match: { channel: "telegram", accountId: "default" } }

请使用为 Gateway 配置的智能体和账户 ID。缺失的所有者会使该账户保持阻塞状态，并在渠道状态中显示确切的绑定修复措施；其他账户继续运行。添加绑定并重启 Gateway。

当升级旧版 agents.list 配置时，Doctor 会在保存显式所有权之前，在绑定中保留之前的隐式账户所有者。Doctor 要求原始名册，并且永远不会将更窄的会话路由提升为账户范围的所有权。缺失的历史所有权需要操作员选择；Doctor 会报告需要添加的确切绑定，而不会更改现有路由。参见迁移修复.

配对

将 Telegram 用户配对到 Gateway。

反应

message 工具的 emoji 反应语义。

群组

群组和主题允许列表行为。

渠道路由

将入站消息路由到智能体。

安全

威胁模型和加固。

多智能体路由

将群组和主题映射到智能体。