II. 频道系统 - 2. Telegram

📍 课程位置

阶段：II. 频道系统
课序：第 2 课
前置知识：I. 核心架构（Gateway/Session/Tools）
后续课程：II-3. Discord

---

🎯 本课核心问题（你不懂我就这样教你）

你接 Telegram 的时候，最常见的问题是：

1. 我怎么让 OpenClaw 用 Telegram Bot 收消息/回消息？
2. 为什么有人能乱发消息给我？怎么限制谁能聊？
3. Webhook/长轮询到底是什么？我该选哪个？
4. 群聊里怎么避免机器人乱插话？

这一篇我们把 Telegram 接入的关键步骤、配置、常见坑一次讲透。

---

🧠 心智模型：Telegram = Bot API 的“标准化渠道”

一句话：

Telegram 接入通常是 Bot API（你创建一个 bot，拿到 token），OpenClaw 用这个 token 跟 Telegram 通信。

类比：

• Telegram 像“一个开放平台”
• Bot Token 像“平台给你发的钥匙”
• OpenClaw Gateway 拿钥匙去收/发消息

---

✅ 你要达到的结果（验收标准）

• 创建 Telegram Bot 并拿到 Bot Token
• 配置 OpenClaw，让它能收到 Telegram 消息
• 能回复 Telegram 私聊
• 能限制允许聊天的用户（安全）
• 群聊默认只在 @ 时响应

---

🔧 第一步：创建 Telegram Bot 并拿 token

1. 在 Telegram 里找到 @BotFather
2. 输入 /newbot
3. 按提示设置 bot 名称和用户名
4. 拿到一串 token（形如 123456:ABC-DEF...）

这串 token 就是你后续配置 OpenClaw 的核心凭证。

---

🔧 第二步：在 OpenClaw 配置中启用 Telegram

在 ~/.openclaw/openclaw.json：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABCDEF...",

      // 安全策略（非常重要）
      dmPolicy: "pairing",         // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"], // allowlist/open 时用；pairing 时可不配

      // 群聊策略（建议默认 require mention）
      groupPolicy: "open",
    },
  },
}

dmPolicy 怎么选？

• pairing（推荐）：陌生人先配对再聊天
• allowlist：只有 allowFrom 里的 tg 用户能聊
• open：任何人都能 DM（风险大）
• disabled：禁用私聊

如果你担心风险：直接用 allowlist。

---

🔧 第三步：拿到 Telegram 用户 ID（tg:xxx）

allowFrom 里需要写 tg:<user_id>。

拿 user_id 的最简单方式：

• 先把 bot 拉进对话
• 给它发一条消息
• 在 OpenClaw 日志/控制台里看事件 payload（通常会显示 sender id）

你看到的格式一般类似：

• tg:123456789

---

🧩 群聊不乱回：只在 @ 时响应

建议在 agent/groupChat + channel groups 设置里统一开启。

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
}

Telegram 群里也支持 @bot（原生 mention），配合 mentionPatterns 更稳。

---

🌐 Webhook vs Long Polling（你该选哪个？）

这块很多人会纠结，我直接给结论：

Long Polling（常用，省事）

• 机器人主动去 Telegram 拉消息
• 你不需要公网地址
• 本地开发非常友好

Webhook（更“正规”的生产模式）

• Telegram 主动把消息推送到你的服务器
• 你需要一个公网 https 地址
• 需要处理证书/可达性

建议：

• 你如果是本地跑或没稳定公网：优先 Long Polling
• 你如果是云服务器+域名+https：用 Webhook

（具体取决于 OpenClaw 的 Telegram channel 实现方式，你可以理解为：能跑通优先，别被架构洁癖卡住。）

---

⚠️ Telegram 最常见的坑（以及怎么排）

现象	常见原因	排查/解决
bot 没反应	token 错/未启用 channel	检查 channels.telegram.enabled/botToken
陌生人能聊	dmPolicy=open	改 pairing/allowlist
白名单不生效	allowFrom 格式错	必须是 tg:<id>
群聊乱回	没启用 mention gating	配置 requireMention / mentionPatterns
收到但回不去	发送权限/网络问题	看 gateway 日志中的错误

---

📝 学习心得

Telegram 这章的核心其实就两件事：

1. token：BotFather 发给你的钥匙
2. 访问控制：dmPolicy/allowFrom + 群聊 mention gating

只要你把“安全策略”当作第一优先级，你就不会走偏。

---

✅ 本课总结（记住 5 句话）

1. Telegram 接入的核心凭证是 Bot Token。
2. dmPolicy 决定谁能私聊你，推荐 pairing/allowlist。
3. allowFrom 需要 tg:<user_id> 格式。
4. 群聊建议默认 @ 才响应，避免乱回与注入风险。
5. 选 Webhook 还是 Long Polling：先跑通再优化，别被架构洁癖卡住。

---

🔗 相关资源

• 官方文档：https://docs.openclaw.ai/channels/telegram
• 配置参考：https://docs.openclaw.ai/gateway/configuration-reference
• 下一课：II-3. Discord