为什么这篇值得先看
Telegram 是 OpenClaw 用户最常用的技术入口之一。它的接入看起来比 WhatsApp 简单，因为不需要扫码登录，但真正容易出错的地方更多：BotFather token 放在哪里、TELEGRAM_BOT_TOKEN 何时生效、pairing code 谁来批、群组 ID 和用户 ID 该放在哪个字段、Privacy Mode 会不会挡住消息。
官方 Telegram 文档把它描述为可用于生产的 bot 私信和群组支持，默认模式是长轮询，也可以配置 webhook。换句话说，你不是只在“装一个 bot”，而是在为 OpenClaw 设置一个受访问控制约束的消息入口。
先抓住这 3 个关键点
- Telegram 依赖
botToken或 token file，不走openclaw channels login telegram。 - 私信 pairing 只授权私信访问；群组授权仍然要看
groups、groupPolicy和groupAllowFrom。 - 群聊排错先看 Privacy Mode、管理员权限、群组 ID、
requireMention，再怀疑模型或 prompt。
官方资料依据
本页核验于 2026-06-16，主要依据官方 Telegram channel、channels pairing、channel config reference 和 channel routing 页面。
| 官方信息 | 对你的影响 |
|---|---|
| 默认模式是长轮询，webhook 可选 | 大多数个人部署先用长轮询；只有你明确有公网入口和反向代理时再上 webhook |
botToken 配置值优先，TELEGRAM_BOT_TOKEN 只应用于默认账户 | 多账号或团队环境不要只依赖环境变量，最好显式配置 account |
dmPolicy: "allowlist" 搭配空 allowFrom 会阻止所有私信 | 安全起步可以严格，但要把自己的数字 Telegram user ID 写进去 |
群组聊天 ID 通常是 -100... 负数，应放在 channels.telegram.groups 下 | 不要把群组 ID 放进 groupAllowFrom；那里应该是用户 ID |
| 配对仅适用于私信，群组发送者授权不继承 pairing 存储 | “我私聊能用”不能证明“我在群里也被授权” |
实操步骤：从私聊到群聊
- 在 Telegram 里确认你正在和真正的
@BotFather对话，运行/newbot创建 bot，并保存 token。 - 把 token 写入
channels.telegram.botToken，或在默认账户场景下使用TELEGRAM_BOT_TOKEN。不要执行不存在的 Telegram login 命令。 - 先设置
dmPolicy: "pairing"，启动openclaw gateway，用私信触发第一条 pairing。 - 运行
openclaw pairing list telegram，确认 code 和发送者，再运行openclaw pairing approve telegram <CODE>。 - 私聊成功后，再把 bot 加进一个测试群。获取两个 ID：你的 Telegram user ID 和群组 chat ID。
- 把用户 ID 放入
allowFrom或groupAllowFrom，把群组 chat ID 放入channels.telegram.groups。 - 群里先用
@<bot_username> ping测试requireMention: true的路径，再决定是否需要更宽松的/activation always或持久化配置。
配置或命令示例
私聊起步配置
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
allowFrom: ["tg:123456789"],
groups: {
"*": { requireMention: true }
}
}
}
}openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>单 owner 群组配置
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "allowlist",
allowFrom: ["123456789"],
groupPolicy: "allowlist",
groups: {
"-1001234567890": {
requireMention: true
}
}
}
}
}这里 123456789 是你的 Telegram user ID，-1001234567890 是超级群组 chat ID。两个 ID 的位置不能互换。
特定群里允许多人触发
{
channels: {
telegram: {
groups: {
"-1001234567890": {
requireMention: true,
allowFrom: ["8734062810", "745123456"]
}
}
}
}
}如果你的目标是“这个群里任何成员都能和机器人对话”，才考虑 groupPolicy: "open" 或 groupAllowFrom: ["*"]。公开群、客户群和跨团队群不建议这样起步。
Privacy Mode 和群聊可见性
Telegram bot 默认启用 Privacy Mode，它会限制 bot 能看到的群组消息。你通常有三种选择：
| 目标 | Telegram 端设置 | OpenClaw 端设置 |
|---|---|---|
| 只在被 @ 时回复 | 保持 Privacy Mode 默认即可 | groups.<id>.requireMention: true |
| 群里常驻监听 | 通过 BotFather /setprivacy 禁用，或把 bot 设为管理员 | 明确允许群组和发送者，谨慎设置 requireMention: false |
| 论坛话题或多人协作 | 获取 chat id 和 topic/thread 信息 | 用 groups / topics 或 bindings 做持久路由 |
切换 Privacy Mode 后，常见做法是把 bot 从群里移除再重新添加，让 Telegram 应用新设置。群聊完全看不到时，先不要改模型，先确认 bot 是否真的能收到平台更新。
长轮询还是 webhook
默认长轮询适合个人 VPS、本地开发和大多数自托管场景。Webhook 适合已经有公网域名、TLS、反向代理和明确运维边界的部署。官方配置里 webhook 需要 webhookUrl、webhookSecret、webhookPath、webhookHost 等字段，默认本地监听可绑定在 127.0.0.1:8787。
如果你刚开始接 Telegram，不要为了“看起来更生产”直接上 webhook。先用长轮询跑通访问控制、群聊 ID、mention 和错误回复，再把入口切到 webhook。
常见排错路径
- bot 完全不响应私信：检查 token 是否来自当前 BotFather、
getMe是否 401、dmPolicy是否 allowlist 但allowFrom为空。 - 找不到 Telegram login 命令：这是正常的。Telegram 通过 token 配置接入。
- 群里不响应非提及消息：如果
requireMention=false，还要确认 Privacy Mode 是否禁用或 bot 是否管理员。 - 群里完全看不到消息：确认
channels.telegram.groups是否包含群组 ID，bot 是否仍在群里，日志是否显示被策略跳过。 - 把群组 ID 放错位置：
-100...群组 ID 放groups，用户 ID 放allowFrom或groupAllowFrom。 - 长轮询 409 冲突：通常表示另一个 OpenClaw Gateway、脚本或外部轮询器正在使用同一个 token。
风险边界
dmPolicy: "open"加allowFrom: ["*"]会让任何找到 bot 用户名的人都能命令它。除非你有严格工具限制和公开机器人需求，否则不要这样起步。- 私信 pairing 批准不等于群组授权。团队环境里要把群组 sender allowlist 写进配置。
TELEGRAM_BOT_TOKEN只适合作为默认账户 fallback。多账号或多 bot 部署应显式声明 account。- webhook 入口不要裸暴露。官方 webhook 路径会校验 secret 和 JSON 正文，反向代理也应限制来源和日志泄漏。
- Telegram 允许列表限制的是谁可以触发智能体，不等于完整的数据脱敏边界。群组上下文、回复引用和媒体仍要按团队隐私标准处理。
常见坑
- 还在找
openclaw channels login telegram，结果白白浪费时间。 - dmPolicy 设成 allowlist，但 allowFrom 为空，直接把所有私聊都挡住。
- 群里想让 bot 看所有消息，却没处理好 Privacy Mode 或管理员权限。
- 用
@username当 allowlist 长期配置，却没有通过 doctor 或日志确认它解析成数字 ID。 - 批准了私信 pairing 后，误以为同一个人已经获得群组命令权限。
完成检查
channels.telegram.botToken或默认账户TELEGRAM_BOT_TOKEN已配置，Gateway 启动无 token 认证错误。- 私信 pairing 已审批，或者
allowFrom中有明确数字用户 ID。 - 当前
dmPolicy是pairing、allowlist、open还是disabled，你能解释原因。 - 群聊中，群组 chat ID 位于
groups，触发者 user ID 位于allowFrom/groupAllowFrom。 - Privacy Mode、管理员权限和
requireMention的组合与你预期一致。 - 至少测试过私信、群聊 @、普通群聊消息三种路径。
下一步内链
- 如果卡在 code 或 approve 顺序，继续看 OpenClaw pairing 教程。
- 如果要同时接 Telegram 和 WhatsApp，继续看 OpenClaw channel routing 实战。
- 如果重点是群管理，继续看 OpenClaw Telegram 群聊设置。
为什么建议把这篇收藏起来
- Telegram 是很多技术用户的主工作台，值得有一篇更“配置导向”的教程。
- 这篇能帮你把 token、pairing、群聊三套逻辑一次理顺。