配置前先回答三个问题：谁能私信、哪个群能进入、群里的谁需要怎样触发。把这三件事分开后，字段才不会互相混用。
本篇用 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 接入教程。本页不提供一份混合所有渠道的“万能模板”，避免复制时把不同渠道的字段规则混在一起。
OpenClaw 多渠道路由实战
多渠道最容易出错的地方不是“少接了一个平台”，而是四个结果无法解释：谁被允许、哪个 Agent 接手、上下文存在哪里、回复最终送到哪里。本篇把旧的“WhatsApp + Telegram + Dashboard 案例”合并为一套可检查的路由练习。
**本站验证范围：**配置文件已通过 OpenClaw 2026.9.2 的隔离 schema 校验，但没有连接真实渠道或模型。下载的验收表是空白记录，不是成功截图。
先画路由意图表
本练习假设有两个 Agent：
main：通过明确的 WhatsApp channel binding 处理已授权操作员私聊。support：只处理一个指定 Telegram 工作群。
先用自己的真实 ID 替换示例值，再执行验证。Telegram 用户 ID 与群 ID 的区别见配置入门；WhatsApp 号码和扫码流程见一站式接入。
| 输入 | 准入条件 | 目标 Agent | 会话预期 | 回复位置 |
|---|---|---|---|---|
| WhatsApp 操作员私聊 | 号码在 allowFrom | main | 按渠道与用户隔离 | 原 WhatsApp 私聊 |
| 指定 Telegram 工作群 | 群 ID、发送者均允许且提及 Bot | support | 该 Telegram 群独立会话 | 原 Telegram 群 |
| 其他已允许但没有 matching binding 的消息 | 渠道自身准入通过 | 不选择 Agent | 不应启动任务 | 不应生成普通回复 |
| 未授权用户或群 | 准入失败 | 不应进入 Agent | 不应创建可用任务上下文 | 不应执行任务 |
不要把 Dashboard / Control UI 写成所有审批的强制归宿。它可以用于查看和管理会话；某些审批也能按产品配置转发到渠道。审批规则要单独设计，不能由路由表替代。
配置两个 Agent 和一条精确 binding
下载路由练习配置。它只是一段需要合入现有配置的示例，其中 token 文件、号码、群 ID 和工作区路径都要替换。
{
"session": {
"dmScope": "per-channel-peer",
"groupScope": "per-group"
},
"agents": {
"ownership": "explicit",
"entries": {
"main": {
"name": "Main",
"workspace": "/REPLACE/workspace-main"
},
"support": {
"name": "Support",
"workspace": "/REPLACE/workspace-support"
}
}
},
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567"],
"selfChatMode": false,
"groupPolicy": "disabled"
},
"telegram": {
"enabled": true,
"tokenFile": "/REPLACE/telegram-token.txt",
"dmPolicy": "disabled",
"groupPolicy": "allowlist",
"groupAllowFrom": ["123456789"],
"groups": {
"-1001234567890": {
"requireMention": true
}
}
}
},
"bindings": [
{
"agentId": "support",
"match": {
"channel": "telegram",
"peer": {
"kind": "group",
"id": "-1001234567890"
}
}
},
{
"agentId": "main",
"match": {
"channel": "whatsapp"
}
}
]
}这段配置有三个刻意的选择：多 Agent roster 使用 ownership: "explicit"；Telegram 群与 WhatsApp 默认账号分别有 binding；私聊使用 per-channel-peer，避免不同渠道和发送者挤进同一会话。
下载文件没有 WhatsApp 登录凭据，也不包含模型配置。WhatsApp 渠道是否能加载还取决于插件是否安装；Telegram token 文件也必须真实存在。不要用下载文件覆盖完整生产配置。
配置校验只解决第一层
合入测试实例后运行：
openclaw config validate --json检查输出中的配置路径、valid 和所有 warnings。本站的隔离校验只能证明示例字段满足 2026.9.2 schema；它没有证明示例路径存在、渠道在线或消息会命中预期 Agent。
查看本站的脱敏校验记录。最终结果为 valid:true，并保留一条警告：显式多 Agent 配置没有为 ambient heartbeat 指定 owner，因此 heartbeat 保持关闭。本练习不使用 heartbeat，所以没有为了消除警告而额外授予 owner；如果你的任务需要 heartbeat，应单独选择 owner、权限和投递目标并重新验证。
若你有两个以上同渠道账号，显式设置 channels.<channel>.defaultAccount 或提供名为 default 的账号，并把 accountId 写入相应 binding。当前文档说明，缺少明确默认值时，出站 fallback 可能选择规范化排序后的第一个账号。
bindings 是怎样命中的
当前固定版本的 Agent 配置文档说明：显式多 Agent fleet 没有默认 Agent；没有 matching binding 时关闭处理。精确 peer 比 channel-wide binding 更具体，同一层级则由第一条匹配规则胜出。一个 binding 同时包含多个条件时，所有条件都必须匹配。
这意味着：
- 上例的指定 Telegram 群进入
support。 - 同渠道的另一个准入群不会因为“也是 Telegram”而命中这条精确 binding。
- WhatsApp 默认账号消息命中 channel binding 后进入
main。 - 其他没有 matching binding 的消息不会回落到
main。 - matched Agent 决定 workspace 和 session store；提示词不能把已经选定的 workspace 换掉。
如果多个业务群都交给 support，可以逐个写精确 peer；先不要用 peer.id: "*" 扩大范围。新增一条 binding 后重新跑原有样本，避免更具体的规则改变旧消息的去向。
会话隔离需要单独验收
路由到同一个 Agent，不代表必须共享一段对话。默认情况下，同一 Agent 的直接消息会合入 main 会话；这适合一个完全可信的单人助手，但多人入口可能让不同发送者共享私聊上下文。
session.dmScope | 会话分隔方式 | 适用考虑 |
|---|---|---|
main | 同一 Agent 的 DM 共用主会话 | 单一可信用户需要跨渠道连续上下文 |
per-peer | 按发送者隔离，可跨渠道合并同一身份 | 需要正确维护身份关联 |
per-channel-peer | 按渠道与发送者隔离 | 多渠道、多用户的保守起点 |
per-account-channel-peer | 再加入账号维度 | 同渠道多个账号需要进一步隔离 |
群默认按 channel 与群 ID 隔离。本练习保留 per-group。修改 groupScope 只会改变上下文存储，不能改变 mention、发送者授权或回复目的地。
用四条消息完成验收
下载路由与会话验收表，每条消息使用唯一标记，避免只凭内容相似判断会话。
- WhatsApp 授权操作员发送
AC-ROUTE-WA-01：请只回复当前 Agent 名称和这个标记。 - Telegram 指定群里的授权用户提及 Bot，发送
AC-ROUTE-TG-02：请只回复当前 Agent 名称和这个标记。 - 经同意，用非授权 Telegram 测试身份在同群提及 Bot，确认任务没有执行。
- 在一个已允许但没有 matching binding 的隔离测试入口发送
AC-ROUTE-NOMATCH-03，确认它关闭处理。没有安全的额外入口时，该项写“待验证”，不要临时开放公开访问。
检查日志和会话列表时，记录每条消息对应的 channel、account、peer、agentId 和 session key。只看模型自报“我是 support”不可靠；模型可以说错，路由元数据才是依据。
普通回复应回到来源渠道。若任务需要跨渠道通知，应使用已授权的显式发送工具、channel、account 和目标，并把它作为另一项高权限功能测试，不要修改 prompt 试图让普通回复改道。
检查是否发生上下文串线
先在 WhatsApp 私聊提供一个仅用于测试的临时标记，例如 WA-CONTEXT-71；随后在 Telegram 群中询问该标记，但不要把答案写进问题。
在本练习的两个 Agent 配置下，Telegram 群不应从 WhatsApp 私聊的会话上下文得到该值。如果它正确回答，检查共享 workspace memory、检索功能、系统提示和其他数据源，不能直接断言 session 串线。测试后删除临时信息。
对于同一 Agent 的两个 DM，per-channel-peer 也应产生不同会话。使用 openclaw sessions --json 检查实际条目；不要公开完整 transcript。
按结果定位故障层
| 现象 | 优先检查 |
|---|---|
| 消息完全没有进入 | 渠道在线状态、群/用户准入、mention 和身份格式 |
| 消息进入但 Agent 错误 | binding 的 channel、account、peer 条件及匹配优先级 |
| Agent 正确但上下文串线 | dmScope、groupScope、身份关联和共享 memory |
| 生成了回答但发错账号 | 同渠道 defaultAccount 和显式出站 account |
| 回答出现在另一渠道 | 是否调用了显式发送工具；普通回复不会由模型自由改道 |
| 已准入但报告没有路由所有者 | 是否缺少 matching binding，或其 account / peer 条件不一致 |
| 重启后路由变化 | 实际加载配置、账号覆盖、配置警告和持久化状态 |
一次只修改一层。把 allowlist、binding、session scope 和 prompt 同时重写，会让成功也无法归因。
扩展到更多渠道前
保留已经通过的消息矩阵，将新入口作为一行加入。先定义准入、Agent、会话和回复位置，再写配置。高风险 Agent 应使用独立 workspace、凭据和工具策略；不同 Agent 的 session store 分开并不自动保证外部资源权限也隔离。
完成本篇后，你应该能够从一条消息追踪到准入结果、命中的 binding、Agent、session key 和回复渠道，并能用正例与负例证明这条路径，而不是只说“两个渠道都能聊天”。