这篇的终点很具体：你给自己的 Bot 发私信能收到回复；在一个指定测试群中，只有允许的人按规则触发它。先只做文字消息，跑通后再接文件、自动化或多个 Bot。
本站验证范围： 已在 macOS、Node 24.15.0、OpenClaw 2026.9.2 中校验本文两个配置片段。下面的消息结果是接入后你需要逐项检查的预期。
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，验证配置并重启，再检查群里不再触发任务。若需要回退整次修改，恢复事先保存的配置，并注意之后新增的其他设置不能被旧备份覆盖。
OpenClaw WhatsApp 一站式接入
本篇从“选哪个号码”开始，直到手机端收到第一条实际回复。首次练习关闭群入口，只验证一个明确身份。旧号码选择页已合并到本页。
**资料来源：**下文依据当前官方文档编写，两份下载配置是按文档整理的示例；实际安装版本、插件 schema 和消息行为请按步骤验收。
第一步：选择号码模式
| 模式 | 你需要准备 | 本文采用的规则 |
|---|---|---|
| 专用号码 | 给 OpenClaw 关联的独立 WhatsApp 账号，以及向它发任务的操作员账号 | 操作员号码放入 allowFrom，关闭同号自聊，群入口关闭 |
| 个人号码自聊 | 你日常使用且准备关联的 WhatsApp 账号 | 明确开启 selfChatMode，将自己的号码写入名单，群入口关闭 |
官网建议条件允许时使用专用号码，也支持个人号码自聊。这里的选择取决于你是否希望把个人聊天与助手身份分开。群聊是后续的接入范围，不是第三种号码模式。
先在自己的记录中填清：哪个号码被扫码关联、哪个号码发送任务、谁负责维护关联设备。专用号路线尤其不要把机器人账号本身的号码误填成唯一操作员。
第二步：准备环境和最小配置
确认 OpenClaw 已安装、模型能完成基本回复，并有一个可持续运行 Gateway 的环境。新建测试实例时按其安装文档选择配置路径，不要覆盖正在使用的完整配置。
WhatsApp 运行组件是独立插件。当前官方文档说明，首次选择该渠道时引导可提示安装；手工安装入口为：
openclaw plugins install @openclaw/whatsapp安装完成后记录 OpenClaw 和插件版本。此命令会安装插件，本文没有代你执行它。不要把缺插件、模型未配置与消息权限问题混为同一类失败。
以下内容只包含 channels.whatsapp，应合入对应实例的配置；保留现有模型、Gateway 和其他渠道设置。
专用号码配置
下载专用号码模板。把示例号码换成发送任务的操作员号码，使用带国家代码的 E.164 格式。
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": [
"+15551234567"
],
"selfChatMode": false,
"groupPolicy": "disabled"
}
}
}本模板明确关闭同号自聊。它只限制入站任务范围，不代表 Agent 获得的其他工具不能向外发送消息；工具权限仍需要单独设计。
个人号码自聊配置
下载个人自聊模板。把示例号码换成你将关联的个人账号号码。
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": [
"+15551234567"
],
"selfChatMode": true,
"groupPolicy": "disabled"
}
}
}selfChatMode 并非普通 allowlist 的别名。当前文档说明，同号自聊有特殊准入：为 true 或未设置时可以进入，dmPolicy: "disabled" 仍会阻止；显式 false 则忽略同号 DM。这里主动写出设置，避免依赖隐式行为。
在扫码之前检查
openclaw config validate --json核对实际校验路径、valid 和警告。此时如果报告渠道或插件无法识别，先检查插件安装与版本，不要删除配置字段来掩盖问题。JSON 能解析并不证明插件接受配置，也不证明 WhatsApp 连接可用。
第三步：关联 WhatsApp 账号
在正确的实例中运行：
openclaw channels login --channel whatsapp用准备关联的 WhatsApp 账号在手机的关联设备入口扫描本次实时二维码。二维码会失效，远程主机上要先准备能及时查看终端的方式，不反复使用旧截图。
扫码关联建立的是账号会话。它不会自动批准所有发送者，也不代表模型已经能回复。
若采用多账号，登录时需明确 --account，并核对认证目录。首次练习建议只完成一个账号；不要将已有私人认证目录复制到公开项目或下载模板里。
第四步：启动 Gateway 并发送最小任务
若该实例已有 Gateway 服务，先查看状态；不要再启动第二个进程。仅在需要前台运行的测试实例中使用：
openclaw gateway另一个终端检查：
openclaw channels status专用号路线：从名单中的操作员账号私信关联号码。个人号路线：在自己的自聊对话发送。使用一个不涉及文件操作的任务：
这是 AC-WA-017 接入测试。请只回复：AC-WA-017 已收到。
不要调用其他工具，不要给其他联系人发送消息。这是演练提示，不替代实际工具权限。检查三层结果：渠道收到输入、模型完成处理、手机端收到回复。只看到“输入中”或 Gateway 日志里的模型文本，都不足以证明送达。
什么时候才使用 pairing approve
本文两份模板都采用 allowlist，不要求名单用户再走配对审批。旧教程把 allowlist 配置与无条件 pairing approve 连在一起，现已更正。
如果你有意将私聊策略改成 pairing，才处理未知发送者的待批准请求：
openclaw pairing list whatsapp
openclaw pairing approve whatsapp "实际配对码"先确认请求属于你正在测试的人和账号，再批准。配对码与登录二维码不是同一件事；没有待处理请求时，不要编造配对码或通过开放所有人来绕过。
第五步：验证拒绝、重启和实际送达
下载 WhatsApp 接入验收表。表中是预期结果，请逐项填写你的实际观察。
| 场景 | 要验证的结果 |
|---|---|
| 已授权身份发送测试消息 | 手机端实际收到对应标记回复 |
| 经同意使用的非授权测试账号发消息 | 不执行其任务；日志能区分准入拒绝与离线 |
| 专用号对自己发 DM | 本模板 selfChatMode false，应被忽略 |
| 个人号自聊 | 本模板 selfChatMode true，按测试请求处理 |
| 测试群内发送消息 | groupPolicy disabled，不执行群任务 |
| 正常重启同一 Gateway 实例 | 检查会话是否恢复，并重新完成一次私聊 |
先完成授权正例，才有条件判断负例是否因准入规则被拒绝。机器人全部无响应时，不能把负例记为成功。
会话是否持久化取决于实际认证目录和运行环境。重启后需要扫码时，先核对账号、目录持久化和日志，不直接删除所有凭据重来。
群聊放到私聊之后
群入口开放前分别记录群 JID、允许的发送者、提及方式。WhatsApp 的群标识与 Telegram 负数群 ID 不同，不要互相复制。
当前官方文档区分群范围与群内发送者策略，提及还要单独判断。首次指定群时使用真实核实的群 JID，并保留发送者限制；不要把 groups: { "*": ... } 当成“只开放测试群”。
这一步需要新的正例和负例验收。私聊 pairing 已批准或某个人能使用私聊，都不能直接证明群权限正确。多账号时还要确认最终生效的是哪份群配置。
按现象排错
| 现象 | 先检查 | 暂时不要做 |
|---|---|---|
| 登录命令没有正常进入 QR 流程 | 插件安装、版本、渠道识别及终端错误 | 重写全部渠道配置 |
| 扫码后仍未关联 | QR 是否有效、手机账号、实例与账户选择 | 重用旧二维码 |
| 已关联但断开 | Gateway 进程、网络、代理和认证目录 | 一次性修改所有超时参数 |
| 私聊输入被忽略 | 实际发送者、dmPolicy、allowFrom、自聊模式 | 改成 open 放行所有人 |
| 模型有输出但手机没有 | 渠道投递错误与目标账号 | 把模型成功当成送达成功 |
| 重启后丢失会话 | 持久卷、认证目录和运行身份 | 清空其他账号凭据 |
停用与保留记录
结束临时测试时，记录结果并清理测试消息中的无关信息。如果决定不再使用该关联，按当前 CLI 帮助确认账号后注销：
openclaw channels logout --channel whatsapp多账号必须指定正确账号；注销会清除对应认证状态，不能当作普通排错的第一步。停用后核对手机关联设备与渠道状态。保留不含凭据的配置、版本和验收记录，后续增加群聊或自动化时才有可比较的基线。
OpenClaw pairing 教程
先分清两类 pairing
| 类型 | 解决的问题 | 常见入口 | 你要检查什么 |
|---|---|---|---|
| 私信发送者 pairing | 某个人能不能通过 Telegram / WhatsApp 等渠道私信助手 | /start、首次私聊、机器人返回 code | openclaw pairing list <channel>、code 是否过期、approve 后是否进入 allowlist |
| 设备 / 节点 pairing | 某个移动端、浏览器、Control UI、无头节点能不能加入 Gateway | QR、setup code、device request | openclaw devices list、requestId、角色、作用域、是否请求更高权限 |
一个非常实用的判断标准：如果问题发生在“某个人发消息给 bot”，优先看 channels pairing；如果问题发生在“某个设备连接 Gateway”，优先看 Gateway / devices pairing。
实操步骤
- 先在 channel 侧触发 pairing，再用终端或 Control UI 查看是否出现待审批项目。
- 运行
openclaw pairing list <channel>，确认 code 是否已经生成、channel 是否正确、状态是否仍有效。 - 用
openclaw pairing approve <channel> <CODE>完成审批，不要让 code 超过有效期。 - 审批完成后，立刻回到 channel 测一次消息路径，确认不是“批了但没真正通”。
- 如果是设备或节点接入，不要套用 channel 命令，改用
openclaw devices list和openclaw devices approve <requestId>。
配置或命令示例
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>如果你不希望陌生私信默认触发 pairing，可以把策略改得更严格。下面只是结构示例，真实 ID 要以官方渠道文档和你的账号格式为准。
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "allowlist",
allowFrom: ["tg:123456789"],
groups: { "*": { requireMention: true } }
}
}
}一条标准私信审批链
- 用户在 Telegram 或 WhatsApp 私信机器人。
- 机器人根据
dmPolicy决定是否返回 pairing code。 - 管理员运行
openclaw pairing list telegram，确认 code、发送者和状态。 - 管理员运行 approve 命令。
- OpenClaw 把允许信息写入对应 channel 的 allowlist 存储。
- 用户再次发消息，管理员确认消息真正进入对话路径。
官方 channels pairing 页面特别强调：DM 配对允许列表用于私信访问，群组授权是独立的。也就是说，批准了某个人的 DM pairing，不代表他可以在群里控制机器人。群组仍然要看 groupAllowFrom、groups 或渠道自己的群组规则。
一条标准设备审批链
- 移动端、浏览器、Control UI 或无头节点尝试连接 Gateway。
- Gateway 创建设备 pairing request，通常带有 requestId、role、scope 等信息。
- 管理员运行
openclaw devices list查看请求。 - 管理员比较“当前已批准访问权限”和“新请求的访问权限”。
- 权限合理时 approve；不认识的设备、异常 scope、异常公钥变更一律 reject 或暂停调查。
设备 pairing 的风险比普通私信 pairing 更接近运行边界。尤其是 role、scope、公钥、token 轮换这类变化，不应该为了省事静默批准。
过期和重试怎么处理
- 不要复用旧 code：过期就是过期，重新触发比排查旧状态更快。
- 不要同时开多个入口乱试：Telegram、WhatsApp、Control UI、mobile app 同时试，会让你分不清哪条 pending request 对应哪个动作。
- 先 reject 再重来：无法确认来源的 pending request，不要因为“可能是我刚才点的”而批准。
- 记录谁批准了什么：团队环境里至少把 channel、code/requestId、批准人、时间和验证结果记下来。
风险边界
- pairing code、setup code 和 bootstrap token 都应当临时当作密码处理。
allowFrom、paired devices、pending requests 都控制访问权，不要把这些文件当普通缓存随意删改。dmPolicy: "open"只适合非常明确的临时测试或公开机器人场景，生产环境应有额外隔离。- 已配对设备如果请求更多 scope 或角色变化，需要重新审批，不能简单当成“同一台设备所以没问题”。
常见坑
- 看到配对码生成就以为完成了，忘记审批这一步。
- 配对码过期后继续反复点旧链接，浪费时间在无效状态上。
- pairing 批了，但后续 dmPolicy / allowlist 仍然挡住消息。
- 批准了 DM pairing，却以为群组权限也同步放开。
- 把设备 pairing request 当成普通聊天 pairing code 处理，导致审批命令和排错方向都错了。