← 返回目录

Telegram（Bot API）

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

快速设置（入门）

  1. 通过 @BotFather（直达链接）创建机器人。确认用户名确实是 @BotFather，然后复制 token。
  2. 设置 token：
  3. 启动 Gateway 网关。
  4. 私信访问默认使用配对模式；首次联系时需要批准配对码。

最小配置：

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

这是什么

设置（快速路径）

1）创建机器人 token（BotFather）

  1. 打开 Telegram 并与 @BotFather（直达链接）对话。确认用户名确实是 @BotFather。
  2. 运行 /newbot，然后按照提示操作（名称 + 以 bot 结尾的用户名）。
  3. 复制 token 并安全保存。

可选的 BotFather 设置：

2）配置 token（环境变量或配置文件）

示例：

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

环境变量选项：TELEGRAM_BOT_TOKEN=...（适用于默认账户）。 如果环境变量和配置都设置了，配置优先。

多账户支持：使用 channels.telegram.accounts，每个账户有独立的 token 和可选的 name。参见 gateway/configuration 了解共享模式。

  1. 启动 Gateway 网关。当 token 解析成功时 Telegram 启动（配置优先，环境变量回退）。
  2. 私信访问默认为配对模式。机器人首次被联系时批准配对码。
  3. 对于群组：添加机器人，决定隐私/管理员行为（见下文），然后设置 channels.telegram.groups 来控制提及门控和允许列表。

Token + 隐私 + 权限（Telegram 端）

Token 创建（BotFather）

群组消息可见性（隐私模式）

Telegram 机器人默认启用隐私模式，这会限制它们接收哪些群组消息。 如果你的机器人必须看到所有群组消息，有两个选项：

注意： 当你切换隐私模式时，Telegram 要求将机器人从每个群组中移除并重新添加，更改才能生效。

群组权限（管理员权限）

管理员状态在群组内设置（Telegram UI）。管理员机器人始终接收所有群组消息，因此如果需要完全可见性，请使用管理员身份。

工作原理（行为）

草稿流式传输

OpenClaw 可以在 Telegram 私信中使用 sendMessageDraft 流式传输部分回复。

要求：

草稿流式传输仅限私信；Telegram 在群组或频道中不支持此功能。

格式化（Telegram HTML）

命令（原生 + 自定义）

OpenClaw 在启动时向 Telegram 的机器人菜单注册原生命令（如 /status、/reset、/model）。 你可以通过配置向菜单添加自定义命令：

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

故障排除

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

注意：

限制

群组激活模式

默认情况下，机器人只响应群组中的提及（@botname 或 agents.list[].groupChat.mentionPatterns 中的模式）。要更改此行为：

通过配置（推荐）

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }, // 在此群组中始终响应
      },
    },
  },
}

重要： 设置 channels.telegram.groups 会创建一个允许列表 - 只有列出的群组（或 "*"）会被接受。 论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非你在 channels.telegram.groups.<groupId>.topics.<topicId> 下添加每话题覆盖。

要允许所有群组并始终响应：

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }, // 所有群组，始终响应
      },
    },
  },
}

要保持所有群组仅提及响应（默认行为）：

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // 或完全省略 groups
      },
    },
  },
}

通过命令（会话级别）

在群组中发送：

注意： 命令只更新会话状态。要在重启后保持持久行为，请使用配置。

获取群组聊天 ID

将群组中的任何消息转发给 Telegram 上的 @userinfobot 或 @getidsbot 以查看聊天 ID（负数，如 -1001234567890）。

提示： 要获取你自己的用户 ID，私信机器人，它会回复你的用户 ID（配对消息），或者在命令启用后使用 /whoami。

隐私注意： @userinfobot 是第三方机器人。如果你更倾向于其他方式，将机器人添加到群组，发送一条消息，然后使用 openclaw logs --follow 读取 chat.id，或使用 Bot API getUpdates。

配置写入

默认情况下，Telegram 允许写入由渠道事件或 /config set|unset 触发的配置更新。

这发生在以下情况：

禁用方式：

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

话题（论坛超级群组）

Telegram 论坛话题在每条消息中包含 message_thread_id。OpenClaw：

私聊在某些边缘情况下可能包含 message_thread_id。OpenClaw 保持私信会话键不变，但在存在线程 id 时仍将其用于回复/草稿流式传输。

内联按钮

Telegram 支持带回调按钮的内联键盘。

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

对于每账户配置：

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

作用域：

默认：allowlist。 旧版：capabilities: ["inlineButtons"] = inlineButtons: "all"。

发送按钮

使用带 buttons 参数的消息工具：

{
  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 机器人/账户应具有相同行为时使用全局设置。当不同机器人需要不同行为时使用每账户配置（例如，一个账户只处理私信，而另一个允许在群组中使用）。

访问控制（私信 + 群组）

私信访问

查找你的 Telegram 用户 ID

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

  1. 启动 Gateway 网关并私信你的机器人。
  2. 运行 openclaw logs --follow 并查找 from.id。

备选（官方 Bot API）：

  1. 私信你的机器人。
  2. 使用你的机器人 token 获取更新并读取 message.from.id：
    curl "https://api.telegram.org/bot<bot_token>/getUpdates"

第三方（隐私性较低）：

群组访问

两个独立的控制：

1. 允许哪些群组（通过 channels.telegram.groups 的群组允许列表）：

2. 允许哪些发送者（通过 channels.telegram.groupPolicy 的发送者过滤）：

大多数用户需要：groupPolicy: "allowlist" + groupAllowFrom + 在 channels.telegram.groups 中列出特定群组

长轮询 vs webhook

回复线程

Telegram 通过标签支持可选的线程回复：

通过 channels.telegram.replyToMode 控制：

音频消息（语音 vs 文件）

Telegram 区分语音备忘录（圆形气泡）和音频文件（元数据卡片）。 OpenClaw 默认使用音频文件以保持向后兼容性。

要在智能体回复中强制使用语音备忘录气泡，在回复中的任何位置包含此标签：

该标签会从发送的文本中去除。其他渠道会忽略此标签。

对于消息工具发送，设置 asVoice: true 并配合兼容语音的音频 media URL（当存在 media 时 message 是可选的）：

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

贴纸

OpenClaw 支持接收和发送 Telegram 贴纸，并具有智能缓存功能。

接收贴纸

当用户发送贴纸时，OpenClaw 根据贴纸类型处理：

接收贴纸时可用的模板上下文字段：

贴纸缓存

贴纸通过 AI 的视觉功能处理以生成描述。由于相同的贴纸经常重复发送，OpenClaw 缓存这些描述以避免冗余的 API 调用。

工作原理：

  1. 首次遇到： 贴纸图像被发送给 AI 进行视觉分析。AI 生成描述（例如"一只卡通猫热情地挥手"）。
  2. 缓存存储： 描述与贴纸的文件 ID、表情符号和集合名称一起保存。
  3. 后续遇到： 当再次看到相同贴纸时，直接使用缓存的描述。图像不会发送给 AI。

缓存位置： ~/.openclaw/telegram/sticker-cache.json

缓存条目格式：

{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "一只卡通猫热情地挥手",
  "cachedAt": "2026-01-15T10:30:00.000Z"
}

优点：

缓存在接收贴纸时自动填充。无需手动缓存管理。

发送贴纸

智能体可以使用 sticker 和 sticker-search 动作发送和搜索贴纸。这些默认禁用，必须在配置中启用：

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

发送贴纸：

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

参数：

搜索贴纸：

智能体可以按描述、表情符号或集合名称搜索缓存的贴纸：

{
  action: "sticker-search",
  channel: "telegram",
  query: "猫 挥手",
  limit: 5,
}

返回缓存中匹配的贴纸：

{
  ok: true,
  count: 2,
  stickers: [
    {
      fileId: "CAACAgIAAxkBAAI...",
      emoji: "👋",
      description: "一只卡通猫热情地挥手",
      setName: "CoolCats",
    },
  ],
}

搜索在描述文本、表情符号字符和集合名称之间使用模糊匹配。

带线程的示例：

{
  action: "sticker",
  channel: "telegram",
  to: "-1001234567890",
  fileId: "CAACAgIAAxkBAAI...",
  replyTo: 42,
  threadId: 123,
}

流式传输（草稿）

Telegram 可以在智能体生成响应时流式传输草稿气泡。 OpenClaw 使用 Bot API sendMessageDraft（不是真实消息），然后将最终回复作为普通消息发送。

要求（Telegram Bot API 9.3+）：

配置：

注意：草稿流式传输与分块流式传输（渠道消息）不同。 分块流式传输默认关闭，如果你想要早期 Telegram 消息而不是草稿更新，需要 channels.telegram.blockStreaming: true。

推理流（仅限 Telegram）：

重试策略

出站 Telegram API 调用在遇到临时网络/429 错误时会以指数退避和抖动进行重试。通过 channels.telegram.retry 配置。参见重试策略。

智能体工具（消息 + 反应）

反应通知

反应工作原理： Telegram 反应作为单独的 message_reaction 事件到达，而不是消息负载中的属性。当用户添加反应时，OpenClaw：

  1. 从 Telegram API 接收 message_reaction 更新
  2. 将其转换为系统事件，格式为："Telegram reaction added: {emoji} by {user} on msg {id}"
  3. 使用与常规消息相同的会话键将系统事件加入队列
  4. 当该对话中的下一条消息到达时，系统事件被排出并前置到智能体的上下文中

智能体将反应视为对话历史中的系统通知，而不是消息元数据。

配置：

论坛群组： 论坛群组中的反应包含 message_thread_id，使用类似 agent:main:telegram:group:{chatId}:topic:{threadId} 的会话键。这确保同一话题中的反应和消息保持在一起。

示例配置：

{
  channels: {
    telegram: {
      reactionNotifications: "all", // 查看所有反应
      reactionLevel: "minimal", // 智能体可以少量反应
    },
  },
}

要求：

投递目标（CLI/cron）

故障排除

机器人不响应群组中的非提及消息：

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

机器人响应提及但不响应 /activation always：

像 /status 这样的命令不起作用：

长轮询在 Node 22+ 上立即中止（通常与代理/自定义 fetch 有关）：

机器人启动后静默停止响应（或日志显示 HttpError: Network request ... failed）：

配置参考（Telegram）

完整配置：配置

提供商选项：

相关全局选项：