跳转至

Telegram

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

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

配对

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

频道故障排查

跨频道诊断和修复手册。

网关配置

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

各页面涵盖内容

各章节迁移位置

先前单页版本中的每个章节标题都会在此保留其锚点,因此诸如 /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.*。显式账户策略优先;如果两个作用域都未设置,则私聊使用 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 工具的表情回应语义。

群组

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

频道路由

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

安全

威胁模型和加固。

多智能体路由

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

故障排查

跨频道诊断。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw