Telegram (Bot API)

状态：通过 grammY 实现，已可用于生产环境，支持机器人私信和群组。默认使用长轮询模式，Webhook 模式可选。

快速配置

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

打开 Telegram 并与 @BotFather 聊天（确认用户名完全是 @BotFather）。

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

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

json5

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

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

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

bash

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

配对码 1 小时后过期。

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

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

注意：令牌解析顺序支持多帐户。实际上，配置值优先于环境变量回退，TELEGRAM_BOT_TOKEN 仅适用于默认帐户。

Telegram 端设置

隐私模式和群组可见性

Telegram 机器人默认处于隐私模式，这限制了它们接收的群组消息。

如果机器人需要查看所有群组消息，可以：

通过 /setprivacy 禁用隐私模式，或
让机器人成为群组管理员。

切换隐私模式时，在每个群组中移除并重新添加机器人，以便 Telegram 应用更改。

群组权限

管理员状态在 Telegram 群组设置中控制。

管理员机器人接收所有群组消息，这对于持续的群组行为很有用。

有用的 BotFather 开关

/setjoingroups 允许/拒绝群组添加
/setprivacy 设置群组可见性行为

访问控制和激活

私信策略

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 时）。

对于单所有者机器人，优先使用 dmPolicy: "allowlist" 并使用显式数字 allowFrom ID，以保持访问策略在配置中持久（而不是依赖之前的配对批准）。

查找你的 Telegram 用户 ID

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

给你的机器人发私信
运行 openclaw logs --follow
读取 from.id

官方 Bot API 方法：

bash

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

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

群组策略和允许列表

两个控制一起应用：

哪些群组被允许 (channels.telegram.groups)
- 没有 groups 配置：
  - groupPolicy: "open"：任何群组都可以通过群组 ID 检查
  - groupPolicy: "allowlist"（默认）：群组被阻止，直到你添加 groups 条目（或 "*"）
- 配置了 groups：作为允许列表（显式 ID 或 "*"）
群组中哪些发送者被允许 (channels.telegram.groupPolicy)
- open
- allowlist（默认）
- disabled

groupAllowFrom 用于群组发送者过滤。如果未设置，Telegram 回退到 allowFrom。 groupAllowFrom 条目应为数字 Telegram 用户 ID（telegram: / tg: 前缀会被标准化）。不要将 Telegram 群组或超级群组聊天 ID 放在 groupAllowFrom 中。负聊天 ID 属于 channels.telegram.groups。非数字条目在发送者授权时被忽略。 安全边界（2026.2.25+）：群组发送者认证不继承私信配对存储批准。配对仅保持私信级别。对于群组，设置 groupAllowFrom 或每个群组/每个主题 allowFrom。运行时说明：如果 channels.telegram 完全缺失，运行时默认使用故障关闭 groupPolicy="allowlist"，除非显式设置 channels.defaults.groupPolicy。

示例：允许特定群组中的任何成员：

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

示例：仅允许特定群组内的特定用户：

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810", "745123456"],
        },
      },
    },
  },
}

警告：常见错误 groupAllowFrom 不是 Telegram 群组允许列表。
将负 Telegram 群组或超级群组聊天 ID（如 -1001234567890）放在 channels.telegram.groups 下。
当你想限制允许群组中哪些人可以触发机器人时，将 Telegram 用户 ID（如 8734062810）放在 groupAllowFrom 下。
只有当你希望允许群组中的任何成员都能与机器人交谈时，才使用 groupAllowFrom: ["*"]。

提及行为

默认情况下群组回复需要提及。

提及可以来自：

原生 @botusername 提及，或
提及模式：
- agents.list[].groupChat.mentionPatterns
- messages.groupChat.mentionPatterns

会话级别命令切换：

/activation always
/activation mention

这些仅更新会话状态。使用配置进行持久化。

持久配置示例：

json5

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

获取群组聊天 ID：

转发群组消息给 @userinfobot / @getidsbot
或者从 openclaw logs --follow 读取 chat.id
或者检查 Bot API getUpdates

运行时行为

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

功能参考

直播预览（消息编辑）

OpenClaw 可以实时流式传输部分回复：

直接聊天：预览消息 + editMessageText
群组/主题：预览消息 + editMessageText

要求：

channels.telegram.streaming 可以是 off | partial | block | progress（默认：partial）
progress 在 Telegram 上映射为 partial（与跨通道命名兼容）
旧版 channels.telegram.streamMode 和布尔 streaming 值会自动映射

对于纯文本回复：

私信：OpenClaw 保持相同的预览消息并就地执行最终编辑（无第二条消息）
群组/主题：OpenClaw 保持相同的预览消息并就地执行最终编辑（无第二条消息）

对于复杂回复（例如媒体负载），OpenClaw 回退到正常最终传递，然后清理预览消息。

预览流式传输与块流式传输分开。当为 Telegram 显式启用块流式传输时，OpenClaw 跳过预览流以避免双重流式传输。

如果原生草稿传输不可用/被拒绝，OpenClaw 自动回退到 sendMessage + editMessageText。

Telegram 专用推理流：

/reasoning stream 在生成时将推理发送到实时预览
最终答案发送时不包含推理文本

格式化和 HTML 回退

出站文本使用 Telegram parse_mode: "HTML"。

类似 Markdown 的文本被渲染为 Telegram 安全的 HTML
原始模型 HTML 被转义以减少 Telegram 解析失败
如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试

链接预览默认启用，可以通过 channels.telegram.linkPreview: false 禁用。

原生命令和自定义命令

Telegram 命令菜单注册在启动时通过 setMyCommands 处理。

原生命令默认：

commands.native: "auto" 为 Telegram 启用原生命令

添加自定义命令菜单项：

json5

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git 备份" },
        { command: "generate", description: "创建图片" },
      ],
    },
  },
}

规则：

名称被标准化（去除前导 /，转为小写）
有效模式：a-z、0-9、_，长度 1..32
自定义命令不能覆盖原生命令
冲突/重复被跳过并记录

说明：

自定义命令只是菜单项；它们不会自动实现行为
插件/技能命令即使不在 Telegram 菜单中显示，键入后仍然可以工作

如果禁用原生命令，内置命令会被移除。自定义/插件命令如果配置了仍然可以注册。

常见设置失败：

setMyCommands failed 且 BOT_COMMANDS_TOO_MUCH 表示修剪后 Telegram 菜单仍然溢出；减少插件/技能/自定义命令或禁用 channels.telegram.commands.native。
setMyCommands failed 且网络/获取错误通常表示到 api.telegram.org 的出站 DNS/HTTPS 被阻止。

设备配对命令（device-pair 插件）

当安装了 device-pair 插件时：

/pair 生成设置代码
在 iOS 应用粘贴代码
/pair approve 批准最近的待处理请求

更多详情：配对。

内联按钮

配置内联键盘范围：

json5

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

按帐户覆盖：

json5

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}

范围：

off
dm
group
all
allowlist（默认）

旧版 capabilities: ["inlineButtons"] 映射到 inlineButtons: "all"。

消息动作示例：

json5

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "选择一个选项：",
  buttons: [
    [
      { text: "是", callback_data: "yes" },
      { text: "否", callback_data: "no" },
    ],
    [{ text: "取消", callback_data: "cancel" }],
  ],
}

回调点击作为文本传递给代理：callback_data: <value>

给代理和自动化的 Telegram 消息动作

Telegram 工具动作包括：

sendMessage (to, content, 可选 mediaUrl, replyToMessageId, messageThreadId)
react (chatId, messageId, emoji)
deleteMessage (chatId, messageId)
editMessage (chatId, messageId, content)
createForumTopic (chatId, name, 可选 iconColor, iconCustomEmojiId)

通道消息动作提供了人性化别名（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（默认：禁用）

说明：edit 和 topic-create 当前默认启用，没有单独的 channels.telegram.actions.* 开关。运行时发送使用活动配置/密钥快照（启动/重新加载），因此动作路径不会在每次发送时执行特别的密钥重新解析。

反应移除语义：工具/反应

回复线程标签

Telegram 支持生成输出中的显式回复线程标签：

[[reply_to_current]] 回复触发消息
[[reply_to:<id>]] 回复特定 Telegram 消息 ID

channels.telegram.replyToMode 控制处理：

off（默认）
first
all

说明：off 禁用隐式回复线程。仍然支持显式 [[reply_to_*]] 标签。

论坛主题和线程行为

论坛超级群组：

主题会话密钥附加 :topic:<threadId>
回复和输入定位主题线程
主题配置路径：channels.telegram.groups.<chatId>.topics.<threadId>

通用主题（threadId=1）特殊情况：

消息发送省略 message_thread_id（Telegram 拒绝 sendMessage(...thread_id=1)）
输入动作仍然包含 message_thread_id

主题继承：主题条目继承群组设置，除非被覆盖（requireMention、allowFrom、skills、systemPrompt、enabled、groupPolicy）。 agentId 是主题专用，不从群组默认继承。

每个主题代理路由：每个主题可以通过在主题配置中设置 agentId 路由到不同代理。这给每个主题自己独立的工作区、内存和会话。示例：

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // 通用主题 → main 代理
            "3": { agentId: "zu" },        // 开发主题 → zu 代理
            "5": { agentId: "coder" }      // 代码审查 → coder 代理
          }
        }
      }
    }
  }
}

每个主题然后有自己的会话密钥：agent:zu:telegram:group:-1001234567890:topic:3

持久 ACP 主题绑定：论坛主题可以通过顶层类型化 ACP 绑定将 ACP 工具链会话固定：

bindings[] 带有 type: "acp" 和 match.channel: "telegram"

示例：

json5

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

这目前作用于群组和超级群组中的论坛主题。

从聊天生成线程绑定的 ACP：

/acp spawn <agent> --thread here|auto 可以将当前 Telegram 主题绑定到新的 ACP 会话。
后续主题消息直接路由到绑定的 ACP 会话（不需要 /acp steer）。
OpenClaw 在成功绑定后会在主题中固定生成确认消息。
需要 channels.telegram.threadBindings.spawnAcpSessions=true。

模板上下文包含：

MessageThreadId
IsForum

私信线程行为：

带有 message_thread_id 的私聊保持私信路由，但使用线程感知会话密钥/回复目标。

音频、视频和贴纸

音频消息

Telegram 区分语音笔记和音频文件。

默认：音频文件行为
在代理回复中添加标签 [[audio_as_voice]] 强制以语音笔记发送

消息动作示例：

json5

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

视频消息

Telegram 区分视频文件和视频笔记。

消息动作示例：

json5

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

视频笔记不支持标题；提供的消息文本单独发送。

贴纸

入站贴纸处理：

静态 WEBP：下载并处理（占位符 <media:sticker>）
动图 TGS：跳过
视频 WEBM：跳过

贴纸上下文字段：

Sticker.emoji
Sticker.setName
Sticker.fileId
Sticker.fileUniqueId
Sticker.cachedDescription

贴纸缓存文件：

~/.openclaw/telegram/sticker-cache.json

贴纸（在可能的情况下）只描述一次并缓存，以减少重复的视觉调用。

启用贴纸动作：

json5

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

发送贴纸动作：

json5

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

搜索缓存贴纸：

json5

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

反应通知

Telegram 反应作为 message_reaction 更新到达（与消息负载分离）。

启用后，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）

说明：

own 表示仅用户对机器人发送消息的反应（通过发送消息缓存尽力而为）。
反应事件仍然尊重 Telegram 访问控制（dmPolicy、allowFrom、groupPolicy、groupAllowFrom）；未授权发送者被丢弃。
Telegram 在反应更新中不提供线程 ID。
- 非论坛群组路由到群组聊天会话
- 论坛群组路由到群组通用主题会话（:topic:1），不是确切的来源主题

轮询/Webhook 的 allowed_updates 自动包含 message_reaction。

Ack 反应

ackReaction 在 OpenClaw 处理入站消息时发送确认 emoji。

解析顺序：

channels.telegram.accounts.<accountId>.ackReaction
channels.telegram.ackReaction
messages.ackReaction
代理身份 emoji 回退（agents.list[].identity.emoji，否则 "👀"）

说明：

Telegram 需要 unicode emoji（例如 "👀"）。
使用 "" 为通道或帐户禁用反应。

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

通道配置写入默认启用（configWrites !== false）。

Telegram 触发的写入包括：

群组迁移事件（migrate_to_chat_id）更新 channels.telegram.groups
/config set 和 /config unset（需要命令启用）

禁用：

json5

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

长轮询 vs Webhook

默认：长轮询。

Webhook 模式：

设置 channels.telegram.webhookUrl
设置 channels.telegram.webhookSecret（设置 webhook URL 时必需）
可选 channels.telegram.webhookPath（默认 /telegram-webhook）
可选 channels.telegram.webhookHost（默认 127.0.0.1）
可选 channels.telegram.webhookPort（默认 8787）

Webhook 模式的默认本地监听器绑定到 127.0.0.1:8787。

如果你的公开端点不同，在前面放置反向代理并将 webhookUrl 指向公开 URL。当你明确需要外部接入时，设置 webhookHost（例如 0.0.0.0）。

限制、重试和 CLI 目标

channels.telegram.textChunkLimit 默认是 4000。
channels.telegram.chunkMode="newline" 在长度分割前优先考虑段落边界（空行）。
channels.telegram.mediaMaxMb（默认 100）限制入站和出站 Telegram 媒体大小。
channels.telegram.timeoutSeconds 覆盖 Telegram API 客户端超时（未设置时，使用 grammY 默认）。
群组上下文历史使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（默认 50）；0 禁用。
私信历史控制：
- channels.telegram.dmHistoryLimit
- channels.telegram.dms["<user_id>"].historyLimit
channels.telegram.retry 配置应用于 Telegram 发送助手（CLI/工具/动作）可恢复的出站 API 错误。

CLI 发送目标可以是数字聊天 ID 或用户名：

bash

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

Telegram 投票使用 openclaw message poll 并支持论坛主题：

bash

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "发布它？" --poll-option "是" --poll-option "否"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "选择时间" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

Telegram 专属投票标志：

--poll-duration-seconds (5-600)
--poll-anonymous
--poll-public
--thread-id 用于论坛主题（或使用 :topic: 目标）

Telegram 发送还支持：

--buttons 用于内联键盘，当 channels.telegram.capabilities.inlineButtons 允许时
--force-document 将出站图片和 GIF 作为文档发送，而不是压缩的照片或动画媒体上传

动作门控：

channels.telegram.actions.sendMessage=false 禁用出站 Telegram 消息，包括投票
channels.telegram.actions.poll=false 禁用 Telegram 投票创建，同时保持常规发送启用

Telegram 中的执行批准

Telegram 支持在批准者私信中进行执行批准，还可以选择性地在原始聊天或主题中发布批准提示。

配置路径：

channels.telegram.execApprovals.enabled
channels.telegram.execApprovals.approvers
channels.telegram.execApprovals.target (dm | channel | both，默认：dm)
agentFilter，sessionFilter

批准者必须是数字 Telegram 用户 ID。当 enabled 为 false 或 approvers 为空时，Telegram 不作为执行批准客户端。批准请求回退到其他配置的批准路由或执行批准回退策略。

传递规则：

target: "dm" 仅将批准提示发送到配置的批准者私信
target: "channel" 将提示发送回原始 Telegram 聊天/主题
target: "both" 发送到批准者私信和原始聊天/主题

只有配置的批准者可以批准或拒绝。非批准者不能使用 /approve 也不能使用 Telegram 批准按钮。通道传递在聊天中显示命令文本，因此仅在可信群组/主题中启用 channel 或 both。当提示落在论坛主题中时，OpenClaw 为批准提示和批准后的后续跟进保留主题。

内联批准按钮还取决于 channels.telegram.capabilities.inlineButtons 允许目标表面（dm、group 或 all）。

故障排除

机器人不回复无需提及的群组消息

如果 requireMention=false，Telegram 隐私模式必须允许完全可见性。
- BotFather：/setprivacy → Disable
- 然后在群组中移除并重新添加机器人
openclaw channels status 在配置期望无需提及的群组消息时发出警告。
openclaw channels status --probe 可以检查显式数字群组 ID；通配符 "*" 无法检查成员资格。
快速会话测试：/activation always。

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

当 channels.telegram.groups 存在时，群组必须被列出（或包含 "*"）
验证机器人在群组中的成员资格
查看日志：openclaw logs --follow 查看跳过原因

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

授权你的发送者身份（配对和/或数字 allowFrom）
即使群组策略是 open，命令授权仍然适用
setMyCommands failed 且 BOT_COMMANDS_TOO_MUCH 表示原生菜单条目太多；减少插件/技能/自定义命令或禁用原生菜单
setMyCommands failed 且网络/获取错误通常表示到 api.telegram.org 的 DNS/HTTPS 可达性问题。

轮询或网络不稳定

Node 22+ + 自定义获取/代理如果 AbortSignal 类型不匹配会触发立即中止行为。
某些主机将 api.telegram.org 优先解析为 IPv6；损坏的 IPv6 出口会导致间歇性 Telegram API 故障。
如果日志包含 TypeError: fetch failed 或 Network request for 'getUpdates' failed!，OpenClaw 现在会将这些作为可恢复网络错误重试。
在出口直接/TLS 不稳定的 VPS 主机上，通过 channels.telegram.proxy 路由 Telegram API 调用：

yaml

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

Node 22+ 默认 autoSelectFamily=true（WSL2 除外）和 dnsResultOrder=ipv4first。
如果你的主机是 WSL2 或者使用 IPv4 行为更稳定，可以强制选择系列：

yaml

channels:
  telegram:
    network:
      autoSelectFamily: false

环境覆盖（临时）：
- OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
- OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
- OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
验证 DNS 答案：

bash

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

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

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.actions.poll：启用或禁用 Telegram 投票创建（默认：enabled；仍然需要 sendMessage）。
channels.telegram.defaultTo：CLI --deliver 在没有显式 --reply-to 时使用的默认 Telegram 目标。
channels.telegram.groupPolicy：open | allowlist | disabled（默认：allowlist）。
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：每个群组覆盖 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：每个主题覆盖 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.execApprovals.enabled：启用 Telegram 作为此帐户的基于聊天的执行批准客户端。
channels.telegram.execApprovals.approvers：允许批准或拒绝执行请求的 Telegram 用户 ID。当 enabled 为 true 时必需。

另请参阅

通道配置 - 通道总览
网关配置参考 - 完整网关配置

Telegram ​

Telegram (Bot API) ​

快速配置 ​

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

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

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

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

Telegram 端设置 ​

隐私模式和群组可见性 ​

群组权限 ​

有用的 BotFather 开关 ​

访问控制和激活 ​

私信策略 ​

查找你的 Telegram 用户 ID ​

群组策略和允许列表 ​

提及行为 ​

运行时行为 ​

功能参考 ​

直播预览（消息编辑） ​

格式化和 HTML 回退 ​

原生命令和自定义命令 ​

设备配对命令（device-pair 插件） ​

内联按钮 ​

给代理和自动化的 Telegram 消息动作 ​

回复线程标签 ​

论坛主题和线程行为 ​

音频、视频和贴纸 ​

音频消息 ​

视频消息 ​

贴纸 ​

反应通知 ​

Ack 反应 ​

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

长轮询 vs Webhook ​

限制、重试和 CLI 目标 ​

Telegram 中的执行批准 ​

故障排除 ​

机器人不回复无需提及的群组消息 ​

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

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

轮询或网络不稳定 ​

Telegram 配置参考指针 ​

另请参阅 ​

Telegram

Telegram (Bot API)

快速配置

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

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

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

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

Telegram 端设置

隐私模式和群组可见性

群组权限

有用的 BotFather 开关

访问控制和激活

私信策略

查找你的 Telegram 用户 ID

群组策略和允许列表

提及行为

运行时行为

功能参考

直播预览（消息编辑）

格式化和 HTML 回退

原生命令和自定义命令

设备配对命令（device-pair 插件）

内联按钮

给代理和自动化的 Telegram 消息动作

回复线程标签

论坛主题和线程行为

音频、视频和贴纸

音频消息

视频消息

贴纸

反应通知

Ack 反应

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

长轮询 vs Webhook

限制、重试和 CLI 目标

Telegram 中的执行批准

故障排除

机器人不回复无需提及的群组消息

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

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

轮询或网络不稳定

Telegram 配置参考指针

另请参阅