Telegram（Bot API）

状态：生产就绪，通过 grammY 支持 Bot 私信和群组。默认使用长轮询（long polling）；也支持 Webhook 模式。

最快上手：Telegram 是 OpenClaw 所有渠道中接入最简单的——只需一个 Bot Token。

快速配置

步骤 1：在 BotFather 创建 Bot Token

打开 Telegram，与 @BotFather 对话（确认 handle 正好是 @BotFather）。

发送 /newbot，按提示操作，保存生成的 Token。

步骤 2：配置 Token 和访问策略

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

环境变量备选（仅限默认账户）：TELEGRAM_BOT_TOKEN=...

注意：Telegram 不需要 openclaw channels login telegram。在配置中或环境变量里设置 Token 后直接启动 Gateway 即可。

步骤 3：启动 Gateway 并审批第一条私信

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

配对码有效期 1 小时。

步骤 4：将 Bot 加入群组

将 Bot 加入群组后，设置 channels.telegram.groups 和 groupPolicy 以匹配你的访问模型。

Telegram 侧设置

隐私模式和群组可见性

Telegram Bot 默认开启隐私模式，只能收到 @mention 自己的群消息。

如果 Bot 需要接收所有群消息，任选其一：

• 通过 /setprivacy 关闭隐私模式
• 将 Bot 设为群管理员

切换隐私模式后，需要将 Bot 从群中移除再重新添加才能生效。

常用 BotFather 设置

• /setjoingroups：允许/禁止被拉入群组
• /setprivacy：群可见性行为

访问控制

私信策略（dmPolicy）

channels.telegram.dmPolicy 控制私信访问：

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

channels.telegram.allowFrom 接受数字格式的 Telegram 用户 ID，telegram: / tg: 前缀会自动规范化。

如何获取你的 Telegram 用户 ID（推荐方式）：

1. 给你的 Bot 发一条私信
2. 运行 openclaw logs --follow
3. 查看日志中的 from.id

群组策略

两个控制层叠使用：

1. 哪些群组可以访问（channels.telegram.groups）

   • 未配置 groups 且 groupPolicy: "allowlist"（默认）：所有群组被拦截
   • 未配置 groups 且 groupPolicy: "open"：任何群组都可以通过
   • 配置了 groups：充当白名单

2. 群组内哪些发送者可以访问（channels.telegram.groupPolicy）

   • open
   • allowlist（默认）
   • disabled

示例：允许某个群中的所有成员：

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

Mention 行为

群组回复默认需要 @mention。Mention 可以来自：

• 原生 @botusername mention
• agents.list[].groupChat.mentionPatterns 中的文本匹配模式

临时切换（仅本次会话）：

• /activation always：无需 mention 即响应
• /activation mention：恢复需要 mention

持久配置（关闭所有群的 mention 要求）：

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

获取群 ID：

• 转发一条群消息给 @userinfobot / @getidsbot
• 或在 openclaw logs --follow 中查看 chat.id

流式回复

⚠️ 文档与实际代码存在差异

• 📄 文档旧写法：channels.telegram.streamMode（布尔值）
• 💻 源码行为：字段名为 channels.telegram.streaming，取值为 off | partial | block | progress（默认 partial）
• ✅ 建议：使用 streaming: "partial" 开启流式预览

OpenClaw 可以在生成回复时实时流式推送：

• 私信：通过 sendMessageDraft 原生草稿流式更新（Bot API 9.5 于 2026-03-01 向所有 Bot 开放）
• 群组/话题：预览消息 + editMessageText 编辑更新

若原生草稿传输不可用，自动回退到 sendMessage + editMessageText。

功能配置

自定义命令菜单

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

命令菜单在 Gateway 启动时通过 setMyCommands 自动注册。

链接预览

默认启用，可关闭：

{
  channels: {
    telegram: {
      linkPreview: false,
    },
  },
}

多账户

{
  channels: {
    telegram: {
      accounts: {
        personal: { botToken: "TOKEN_1", dmPolicy: "pairing" },
        work: { botToken: "TOKEN_2", dmPolicy: "allowlist", allowFrom: ["123"] },
      },
    },
  },
}

运行时说明

• Telegram 由 Gateway 进程管理
• 路由是确定性的：Telegram 来的消息回复到 Telegram
• 群组会话按群 ID 隔离；论坛话题（Forum Topics）额外用 :topic:<threadId> 区分
• Telegram Bot API 不支持已读回执（sendReadReceipts 对 Telegram 无效）