这篇的终点很具体：你给自己的 Bot 发私信能收到回复；在一个指定测试群中，只有允许的人按规则触发它。先只做文字消息，跑通后再接文件、自动化或多个 Bot。
**本站验证范围：**已在 macOS、Node 24.15.0、OpenClaw 2026.9.2 中校验本文两个配置片段。没有真实 Telegram Bot 收发实测，下面的消息结果是读者需要检查的预期，不是本站已经收到的回复。
1. 准备材料，先证明模型可用
先在 Dashboard 发一条普通消息，确认模型可以回复。如果这里就报认证或余额错误，先解决模型接入；换成 Telegram 入口不会修好模型。
下载三个文件，保存到自己的练习目录：
这两个 JSON 是合并片段，不能覆盖整份 OpenClaw 配置。本教程从一个尚未配置 Telegram 的默认账户开始；已有具名 accounts 或多个 Bot 的环境，应先按官方多账户说明逐项合并，不能直接套用。
在 Gateway 主机终端运行：
openclaw --version
openclaw config file
openclaw gateway status根据 config file 打印的路径，在本机复制一份配置备份，记住恢复位置。备份可能包含其他服务凭据，不要上传到公开仓库。本文命令以 2026.9.2 为基线；旧版本不认识 config patch 时先查该版本帮助。
2. 创建 Bot，把 token 留在 Gateway 主机
- 在 Telegram 打开官方
@BotFather，确认用户名拼写。 - 发送
/newbot，按提示设置名称和 Bot 用户名。 - 保存返回的 token；它控制的是 Bot，不是你的 Telegram 用户 ID。
- 在 Gateway 主机创建一个私人文本文件，例如用户目录中的
telegram-token.txt，文件正文只放 token。通过本机编辑器粘贴，不要把 token 放进终端命令或截图。 - 确保运行 Gateway 的账号能读取该文件，其他非必要账号不能读取。
打开下载的 telegram-dm-example.json，将 /REPLACE/telegram-token.txt 改为该文件的实际绝对路径。JSON 中 Windows 路径的反斜杠需要转义，使用正斜杠形式通常更容易阅读；路径仍必须位于运行 Gateway 的机器，而不是仅位于浏览器所在电脑。
本文只用 tokenFile。不要再同时填另一份旧 botToken 或依赖不同的环境变量；该版本优先读取 tokenFile，其次 botToken，默认账户最后才使用 TELEGRAM_BOT_TOKEN。
3. 只启用私聊，暂时禁用群聊
私聊片段的核心是：
{
"channels": {
"telegram": {
"enabled": true,
"tokenFile": "/REPLACE/telegram-token.txt",
"dmPolicy": "pairing",
"groupPolicy": "disabled"
}
}
}确认已替换路径。在下载文件所在目录先预览修改：
openclaw config patch --file ./telegram-dm-example.json --dry-run确认预览只涉及预期的 Telegram 字段，再应用：
openclaw config patch --file ./telegram-dm-example.json
openclaw config validate --jsonconfig patch 会递归合并对象，但数组会整体替换。它不是“检查一下”，第二条不带 dry-run 的命令会写配置。
**既要看 valid，也要看 warnings。**配置结构正确不能证明 token 可读、Telegram 可达或模型能回答。
如果 Gateway 作为后台服务运行，执行 openclaw gateway restart。若之前是在终端前台运行，先停止那个进程，再用 openclaw gateway 启动；不要再开第二个进程抢同一个 Bot 的更新。
4. 完成私聊配对，再取得自己的数字 ID
打开自己的 Bot，点击 Start，发送 你好。在 pairing 策略下，首次应收到配对信息；尚未得到授权时，不应直接让陌生人执行任务。
在 Gateway 主机运行：
openclaw pairing list telegram核对发送者是自己，再用实际配对码替换下例：
openclaw pairing approve telegram "实际配对码"配对码有时效，过期后应重新触发并核对新码，不要批准不认识的人。批准后再发一条普通文字请求，确认得到模型回复。
记录配对回复中的 Your Telegram user id。也可在 openclaw logs --follow 中查看对应配对请求的 senderUserId，取得后停止跟踪，避免收集无关聊天日志。这个数字既不是手机号、Bot ID，也不是 @username。
5. 只允许一个群里的指定发送者
创建一个你有权管理的测试群，将 Bot 加入。先不授予不需要的管理员能力。
在 Gateway 主机跟踪日志，向测试群发送一条提及 Bot 的消息，从对应事件读取群 chat ID。只看这次测试的上下文，不把整份日志公开。超级群 ID 通常是 -100... 形式，但不能凭格式编造；要使用实际观察到的值。
打开 telegram-group-example.json，替换三类信息：
| 文件中的示例 | 替换为 | 控制什么 |
|---|---|---|
/REPLACE/telegram-token.txt | Gateway 的实际 token 文件路径 | 连接哪个 Bot |
123456789，有两处 | 你自己的数字用户 ID | 私聊与群聊的发送者 |
-1001234567890 | 测试群的实际 chat ID | 允许哪个群 |
片段使用 dmPolicy: allowlist、明确的 allowFrom 和 groupAllowFrom，并在 groups 中只列一个群。**群 ID 是地图的键，用户 ID 是允许列表成员，不能互换。**私聊配对记录不会自动变成群聊允许列表。
替换完成后：
openclaw config patch --file ./telegram-group-example.json --dry-run
openclaw config patch --file ./telegram-group-example.json
openclaw config validate --json按第 3 步的运行方式重启，再在测试群发送 @你的Bot用户名 只回复测试成功。若实际环境有其他群配置，递归合并不会替你删除旧群；应先核对完整 groups，不能只看新加的一项。
6. 分清 Privacy Mode 和 requireMention
Telegram 的 Privacy Mode 决定 Bot 能收到哪些群消息；OpenClaw 的 requireMention 决定收到后何时触发。后者不能让 Telegram 发送原本不可见的消息。
本练习保持 Privacy Mode，使用 requireMention: true。先验证明确提及。普通非提及测试要发一条新消息，不要回复 Bot，因为回复关系也可能影响触发判断。
只有确实需要持续接收群消息时，才考虑通过 BotFather /setprivacy 调整，或按任务需要授予管理员能力；更改隐私模式后，按 Telegram 说明重新将 Bot 加入群，让设置生效。不要为了修一个提及失败就直接开放所有群和所有发送者。
7. 按七条路径验收，不能只测“能回复”
在下载的验收表中记录本人私聊、非授权私聊、群内授权提及、普通新消息、未授权提及及未配置群等路径。没有第二个合适的测试账号或测试群，就写“未验证”，不要打勾。
本站配置校验发现的一个陷阱
我们把私聊策略设为 allowlist，再把 allowFrom 清空。2026.9.2 的实际 CLI 返回仍是 valid: true，但附带警告：所有私聊会被丢弃。也就是说，只判断退出码或 valid 字段，会漏掉不可用配置。
查看配置验证记录。这份记录没有包含真实 Bot 凭据，也没有声称已经通过七项消息验收。
8. 失败时从对应一层开始
| 症状 | 优先检查 |
|---|---|
getMe 401 | 当前 token 是否正确、tokenFile 是否仍指向旧文件 |
| token 文件读取失败 | 路径在不在 Gateway 主机、服务账号是否可读 |
| 私聊没有模型回复 | 配对状态、allowFrom、Dashboard 的模型是否正常 |
| 私聊可用但群聊不回应 | groupPolicy、群 ID、groupAllowFrom、提及与平台可见性 |
| 长轮询 409 | 是否有另一台 Gateway、脚本或旧进程使用同一个 Bot token |
| 改配置后行为没变 | 修改的是不是实际配置文件、进程是否完成重载 |
不要让自己的诊断脚本同时运行 getUpdates 抢 Bot 消息。初次接入使用默认长轮询，无需为此搭建公网 webhook；确有 webhook 需求再读官方参数和认证说明。
需要停止群聊时，将 groupPolicy 改回 disabled，验证配置并重启，再检查群里不再触发任务。若需要回退整次修改，恢复事先保存的配置，并注意之后新增的其他设置不能被旧备份覆盖。
下一步
配对失败继续看 pairing 教程；多个渠道或多个 Agent 的消息分配看 channel routing；需要让任务执行主机命令时，再单独完成 执行审批练习。