Telegram（机器人 API）

状态：通过 grammY 为机器人私聊 + 群组做好生产准备。长轮询是默认模式；webhook 模式是可选的。

快速设置

在 BotFather 中创建机器人令牌

打开 Telegram 并与 @BotFather 聊天（确认句柄正好是 @BotFather）。

运行 /newbot，按照提示操作，并保存令牌。

配置令牌和私聊策略

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

环境变量回退：TELEGRAM_BOT_TOKEN=...（仅默认账户）。 Telegram 不使用 openclaw channels login telegram；在配置/环境变量中配置令牌，然后启动网关。

启动网关并批准首次私聊

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

配对码在 1 小时后过期。

将机器人添加到群组

将机器人添加到你的群组，然后设置 channels.telegram.groups 和 groupPolicy 以匹配你的访问模型。

令牌解析顺序是账户感知的。实际上，配置值优先于环境变量回退，TELEGRAM_BOT_TOKEN 仅适用于默认账户。

Telegram 端设置

访问控制和激活

channels.telegram.dmPolicy 控制直接消息访问：

pairing（默认）
allowlist（需要 allowFrom 中至少有一个发送者 ID）
open（需要 allowFrom 包含 "*"）
disabled

channels.telegram.allowFrom 接受数字 Telegram 用户 ID。telegram: / tg: 前缀被接受并标准化。 dmPolicy: "allowlist" 且 allowFrom 为空会阻止所有私聊并被配置验证拒绝。入门向导接受 @username 输入并将其解析为数字 ID。如果你升级且配置包含 @username 白名单条目，运行 openclaw doctor --fix 来解析它们（尽力而为；需要 Telegram 机器人令牌）。如果你之前依赖配对存储白名单文件，openclaw doctor --fix 可以在白名单迁移流程中将条目恢复到 channels.telegram.allowFrom（例如当 dmPolicy: "allowlist" 还没有显式 ID 时）。

查找你的 Telegram 用户 ID

更安全（无需第三方机器人）：

向机器人发送私聊。
运行 openclaw logs --follow。
读取 from.id。

官方 Bot API 方法：

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

第三方方法（隐私性较低）：@userinfobot 或 @getidsbot。

运行时行为

Telegram 由网关进程拥有。
路由是确定性的：Telegram 入站回复回 Telegram（模型不选择频道）。
入站消息标准化为带有回复元数据和媒体占位符的共享频道信封。
群组会话按群组 ID 隔离。论坛主题附加 :topic:<threadId> 以保持主题隔离。
私聊消息可以携带 message_thread_id；OpenClaw 使用线程感知会话键路由它们并为回复保留线程 ID。
长轮询使用 grammY 运行器进行每聊天/每线程排序。整体运行器 sink 并发使用 agents.defaults.maxConcurrent。
Telegram Bot API 没有已读回执支持（sendReadReceipts 不适用）。

功能参考

故障排除

更多帮助：频道故障排除。

Telegram 配置参考指针

主要参考：

channels.telegram.enabled：启用/禁用频道启动。
channels.telegram.botToken：机器人令牌（BotFather）。
channels.telegram.tokenFile：从文件路径读取令牌。
channels.telegram.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）。
channels.telegram.allowFrom：私聊白名单（数字 Telegram 用户 ID）。allowlist 需要至少一个发送者 ID。open 需要 "*"。openclaw doctor --fix 可以解析旧版 @username 条目为 ID 并可以在白名单迁移流程中从配对存储文件恢复白名单条目。
channels.telegram.defaultTo：当没有显式 --reply-to 时 CLI --deliver 使用的默认 Telegram 目标。
channels.telegram.groupPolicy：open | allowlist | disabled（默认：allowlist）。
channels.telegram.groupAllowFrom：群组发送者白名单（数字 Telegram 用户 ID）。openclaw doctor --fix 可以解析旧版 @username 条目为 ID。非数字条目在认证时被忽略。群组认证不使用私聊配对存储回退（2026.2.25+）。
多账户优先级：
- channels.telegram.accounts.default.allowFrom 和 channels.telegram.accounts.default.groupAllowFrom 仅适用于 default 账户。
- 命名账户在账户级值未设置时继承 channels.telegram.allowFrom 和 channels.telegram.groupAllowFrom。
- 命名账户不继承 channels.telegram.accounts.default.allowFrom / groupAllowFrom。
channels.telegram.groups：每群组默认 + 白名单（使用 "*" 表示全局默认）。
- channels.telegram.groups.<id>.groupPolicy：群组策略的每群组覆盖（open | allowlist | disabled）。
- channels.telegram.groups.<id>.requireMention：提及限制默认。
- channels.telegram.groups.<id>.skills：技能过滤器（省略 = 所有技能，空 = 无）。
- channels.telegram.groups.<id>.allowFrom：每群组发送者白名单覆盖。
- channels.telegram.groups.<id>.systemPrompt：群组的额外系统提示。
- channels.telegram.groups.<id>.enabled：当 false 时禁用群组。
- channels.telegram.groups.<id>.topics.<threadId>.*：每主题覆盖（与群组相同的字段）。
- channels.telegram.groups.<id>.topics.<threadId>.groupPolicy：群组策略的每主题覆盖（open | allowlist | disabled）。
- channels.telegram.groups.<id>.topics.<threadId>.requireMention：每主题提及限制覆盖。
channels.telegram.capabilities.inlineButtons：off | dm | group | all | allowlist（默认：allowlist）。
channels.telegram.accounts.<account>.capabilities.inlineButtons：每账户覆盖。
channels.telegram.commands.nativeSkills：启用/禁用 Telegram 原生技能命令。
channels.telegram.replyToMode：off | first | all（默认：off）。
channels.telegram.textChunkLimit：出站分块大小（字符）。
channels.telegram.chunkMode：length（默认）或 newline 在长度分块之前按空行（段落边界）分割。
channels.telegram.linkPreview：切换出站消息的链接预览（默认：true）。
channels.telegram.streaming：off | partial | block | progress（实时流预览；默认：partial；progress 映射到 partial；block 是旧版预览模式兼容性）。在私聊中，partial 在可用时使用原生 sendMessageDraft。
channels.telegram.mediaMaxMb：入站 Telegram 媒体下载/处理上限（MB）。
channels.telegram.retry：Telegram 发送助手（CLI/工具/动作）在可恢复出站 API 错误时的重试策略（attempts, minDelayMs, maxDelayMs, jitter）。
channels.telegram.network.autoSelectFamily：覆盖 Node autoSelectFamily（true=启用，false=禁用）。Node 22+ 上默认启用，WSL2 默认禁用。
channels.telegram.network.dnsResultOrder：覆盖 DNS 结果顺序（ipv4first 或 verbatim）。Node 22+ 上默认 ipv4first。
channels.telegram.proxy：Bot API 调用的代理 URL（SOCKS/HTTP）。
channels.telegram.webhookUrl：启用 webhook 模式（需要 channels.telegram.webhookSecret）。
channels.telegram.webhookSecret：webhook 密钥（设置 webhookUrl 时需要）。
channels.telegram.webhookPath：本地 webhook 路径（默认 /telegram-webhook）。
channels.telegram.webhookHost：本地 webhook 绑定主机（默认 127.0.0.1）。
channels.telegram.webhookPort：本地 webhook 绑定端口（默认 8787）。
channels.telegram.actions.reactions：门控 Telegram 工具反应。
channels.telegram.actions.sendMessage：门控 Telegram 工具消息发送。
channels.telegram.actions.deleteMessage：门控 Telegram 工具消息删除。
channels.telegram.actions.sticker：门控 Telegram 贴纸动作——发送和搜索（默认：false）。
channels.telegram.reactionNotifications：off | own | all — 控制哪些反应触发系统事件（默认：未设置时为 own）。
channels.telegram.reactionLevel：off | ack | minimal | extensive — 控制代理的反应能力（默认：未设置时为 minimal）。
配置参考 - Telegram

Telegram 专用高信号字段：

启动/认证：enabled、botToken、tokenFile、accounts.*
访问控制：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、groups.*.topics.*
命令/菜单：commands.native、commands.nativeSkills、customCommands
主题/回复：replyToMode
流式传输：streaming（预览）、blockStreaming
格式化/传递：textChunkLimit、chunkMode、linkPreview、responsePrefix
媒体/网络：mediaMaxMb、timeoutSeconds、retry、network.autoSelectFamily、proxy
webhook：webhookUrl、webhookSecret、webhookPath、webhookHost
动作/功能：capabilities.inlineButtons、actions.sendMessage|editMessage|deleteMessage|reactions|sticker
反应：reactionNotifications、reactionLevel
写入/历史：configWrites、historyLimit、dmHistoryLimit、dms.*.historyLimit

Telegram