配置前先回答三个问题：谁能私信、哪个群能进入、群里的谁需要怎样触发。把这三件事分开后，字段才不会互相混用。
本篇用 Telegram 做具体练习。不同渠道的身份格式、默认值与策略可能不同，不要把 Telegram ID 原样放进 WhatsApp 配置。旧“配置模板库”已合并到本页，模板按场景分别下载。
先分清三个 ID
| 身份 | 本文演示值 | 用在哪里 |
|---|---|---|
| 允许使用的 Telegram 用户 | 123456789 | allowFrom、groupAllowFrom |
| 允许接入的 Telegram 群 | -1001234567890 | groups 对象的键 |
| Bot 身份与凭据 | 使用实际 Bot 的 token 文件 | tokenFile；不充当允许用户 ID |
这些数字只是占位值。用你已核实的实际身份替换，获取方式见 Telegram 接入教程。不要用手机号、用户名或机器人自己的 ID 猜测个人用户 ID。
**更正说明：**本站旧示例曾把群 ID 放进 groupAllowFrom。当前 Telegram 官方文档明确它筛选的是群内发送者；群 ID 应作为 groups 的键。只修正 JSON 语法无法解决这种身份错误。
字段各自控制什么
| 字段 | 本篇 Telegram 场景中的作用 | 常见误解 |
|---|---|---|
dmPolicy | 私聊准入模式 | 私聊放行后群里也自动放行 |
allowFrom | 明确允许的私聊发送者 | 填入 Bot ID 或群 ID |
groupPolicy | 群内发送者准入策略 | 以为它列出了哪些群 |
groupAllowFrom | 群内允许触发的用户名单 | 填入负数群 ID |
groups | 允许进入的群及各群设置 | 用 "*" 却以为只允许一个群 |
requireMention | 该群的提及触发要求 | 把 @ 提及当成身份授权 |
明确配置 groupAllowFrom，比依赖回退行为更容易审阅。本篇不把消息可见回复策略或 Gateway 运行参数混入渠道准入配置；它们是其他层面的设置。
先用配对审批跑通私聊
下载私聊模板。模板中的 token 文件路径必须替换，文件本身不包含真实凭据。它采用 pairing：先批准你自己的测试身份，再验证私聊。
{
"channels": {
"telegram": {
"enabled": true,
"tokenFile": "/REPLACE/telegram-token.txt",
"dmPolicy": "pairing",
"groupPolicy": "disabled"
}
}
}这一步关闭群入口。首次私聊收到配对信息后，按 Telegram 接入教程核对并批准你自己的配对请求，再验证回复。它是渠道配置片段，不是包含模型、Gateway 和所有既有渠道的完整运行配置。不要用它覆盖整个 openclaw.json。
下一步群聊模板把私聊切换为固定 allowlist，因此需要填写已核实的用户 ID；已批准配对不代表固定名单可以留空。open 是不同的准入选择，不是排错按钮；本练习不需要开放给所有用户。
再开放一个测试群
下载群聊模板。在前一步基础上，群 ID 和群内发送者分别填写：
{
"channels": {
"telegram": {
"enabled": true,
"tokenFile": "/REPLACE/telegram-token.txt",
"dmPolicy": "allowlist",
"allowFrom": ["123456789"],
"groupPolicy": "allowlist",
"groupAllowFrom": ["123456789"],
"groups": {
"-1001234567890": { "requireMention": true }
}
}
}
}读这段配置时，可以说成：“用户 123456789 可以私聊；在群 -1001234567890 中，也只允许名单里的用户按提及规则触发。”不要把“配置里有群”理解成“群里的所有人都获得权限”。
Telegram 的 Privacy Mode、Bot 是否在群中以及实际消息类型，还会影响 Bot 收到哪些消息。真实接入步骤和七项消息验收见 指定群接入。
改配置按三个层次验收
1. 语法与 schema
先保存当前有效配置，确认正在修改的实例和配置文件。把需要的字段合入测试配置，再执行当前版本支持的校验命令：
openclaw config validate --json检查 valid、warnings 与实际校验路径；多实例或自定义 home 时，不要误验另一个文件。具体隔离配置和 patch 流程见 Telegram 一站式接入。
本站已用 2026.9.2 校验两份下载模板，均返回 valid:true；但这只证明字段符合该次 CLI 的 schema。完整记录见 配置校验证据。
2. 身份与规则
对照表逐项确认用户 ID、群 ID、token 文件路径，以及是否存在更具体的账户配置。检查最终生效配置，不能只看刚编辑的片段。
本站还做过一个负例：把私聊 allowFrom 设为空。CLI 仍返回 valid:true，但同时警告所有 DM 都会被丢弃。因此退出码为 0 不能代替阅读警告，更不能证明用户可以访问。
3. 真实消息行为
按 下载验收表 记录实际结果。尚未执行的项目写“未验证”。
| 场景 | 预期检查 |
|---|---|
| 授权用户私聊 | 可以按任务正常处理 |
| 非授权用户私聊 | 不执行其任务 |
| 指定群内授权用户提及 Bot | 进入预期处理流程 |
| 同群非授权用户提及 Bot | 不执行其任务 |
| 不在允许范围内的群 | 不因出现提及就放行 |
| 更改后恢复原测试配置 | 原有预期行为可恢复 |
单纯“不回复”不一定证明正确拒绝，也可能是 Bot 离线。先做授权成功的正例，再做拒绝负例，并核对日志；不要公开无关聊天内容。
为什么配置能校验，却仍然不工作
- **所有私聊无响应：**先看空名单警告、身份、Bot 连接和实际生效实例。
- **私聊正常，群无响应：**依次核对群键、发送者名单、提及、Privacy Mode 与群权限。
- **改了文件但行为没变：**核对配置路径、账户覆盖和该版本的重新加载方式。
- **非授权用户仍能执行：**停止扩大测试，检查其他账户、通配项和实际执行身份，恢复原测试配置后定位。
不要通过同时开放 open、加入 "*"、关闭提及来掩盖问题。一次只改一个条件，才能知道是哪层起作用。
模板怎样复用
把模板保留为不含凭据的场景文件；把具体身份、版本、修改原因和验收日期记录在你自己的维护表中。增加第二个用户或群时，重复正例与负例，不要只验证新增成员能用。
WhatsApp 使用其专属身份与接入方式，继续看 WhatsApp 接入教程。本页不提供一份混合所有渠道的“万能模板”，避免复制时把不同渠道的字段规则混在一起。