OpenClaw（龙虾） AI 的 Telegram 机器人设置与配置

消息平台

状态：通过 grammY 实现机器人私聊 + 群组功能，已可用于生产环境。长轮询是默认模式；Webhook 模式为可选。

配对

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

频道故障排除

跨频道诊断和修复手册。

网关配置

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

快速设置

步骤 1：在 BotFather 中创建机器人令牌

打开 Telegram 并与 @BotFather 聊天（确认其用户名确为 @BotFather）。运行 /newbot，按照提示操作，并保存令牌。

步骤 2：配置令牌和私聊策略

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

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

步骤 3：启动网关并批准首次私聊

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

配对码在 1 小时后过期。

步骤 4：将机器人添加到群组

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

ℹ️ 令牌解析顺序是账户感知的。实际上，配置值优先于环境变量后备方案，且 TELEGRAM_BOT_TOKEN 仅适用于默认账户。

Telegram 端设置

隐私模式和群组可见性

群组权限

有用的 BotFather 开关

访问控制和激活

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

运行时行为

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

功能参考

实时流预览（原生草稿 + 消息编辑）

格式化和 HTML 后备方案

原生命令和自定义命令

内联按钮

用于代理和自动化的 Telegram 消息操作

回复线程标签

论坛话题和线程行为

音频、视频和贴纸

反应通知

确认反应

来自 Telegram 事件和命令的配置写入

长轮询与 Webhook

限制、重试和 CLI 目标

故障排除

机器人不响应未提及的群组消息

机器人完全看不到群组消息

命令部分工作或完全不工作

轮询或网络不稳定

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

Telegram 配置参考要点

主要参考：

channels.telegram.enabled：启用/禁用频道启动。
channels.telegram.botToken：机器人令牌（BotFather）。
channels.telegram.tokenFile：从文件路径读取令牌。
channels.telegram.dmPolicy：pairing | allowlist | open | disabled（默认：配对）。
channels.telegram.allowFrom：私聊允许列表（数字 Telegram 用户 ID）。allowlist 需要至少一个发送者 ID。open 需要 "*"。openclaw doctor --fix 可以将旧版 @username 条目解析为 ID，并可以在允许列表迁移流程中从配对存储文件中恢复允许列表条目。
channels.telegram.actions.poll：启用或禁用 Telegram 投票创建（默认：启用；仍需要 sendMessage）。
channels.telegram.defaultTo：当没有显式提供 --reply-to 时，CLI --deliver 使用的默认 Telegram 目标。
channels.telegram.groupPolicy：open | allowlist | disabled（默认：允许列表）。
channels.telegram.groupAllowFrom：群组发送者允许列表（数字 Telegram 用户 ID）。openclaw doctor --fix 可以将旧版 @username 条目解析为 ID。非数字条目在授权时被忽略。群组授权不使用私聊配对存储后备方案（2026.2.25+）。
多账户优先级：
- 当配置两个或更多账户 ID 时，设置 channels.telegram.defaultAccount（或包含 channels.telegram.accounts.default）以使默认路由明确。
- 如果两者都未设置，OpenClaw 回退到第一个规范化的账户 ID，并且 openclaw doctor 会发出警告。
- 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>.*：每话题覆盖（群组字段 + 话题特有的 agentId）。
- channels.telegram.groups.<id>.topics.<threadId>.agentId：将此话题路由到特定代理（覆盖群组级和绑定路由）。
- channels.telegram.groups.<id>.topics.<threadId>.groupPolicy：群组策略的每话题覆盖（open | allowlist | disabled）。
- channels.telegram.groups.<id>.topics.<threadId>.requireMention：提及门控的每话题覆盖。
- 顶层 bindings[] 包含 type: "acp" 和规范话题 id chatId:topic:topicId 在 match.peer.id 中：持久化 ACP 话题绑定字段（参见 ACP 代理）。
- channels.telegram.direct.<id>.topics.<threadId>.agentId：将私聊话题路由到特定代理（与论坛话题行为相同）。
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，默认：100）。
channels.telegram.retry：针对可恢复的出站 API 错误，Telegram 发送助手（CLI/工具/操作）的重试策略（尝试次数、minDelayMs、maxDelayMs、抖动）。
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.*、顶层 bindings[]（type: "acp"）
命令/菜单：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

配对