为什么这篇值得先看
OpenClaw 配置难点不在 JSON5 语法，而在你到底想让谁进来、什么时候进来、进来后是否必须被点名。很多“配置写错”的真实原因，其实是策略没有先想清楚：私聊想走 pairing，群聊却希望必须 @；团队想允许测试账号，生产账号却不能开放给所有人。
这篇只解决一个核心问题：把配置拆成可审计的几层。你不需要一口气理解所有字段，但至少要知道 dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、requireMention、messages.visibleReplies 分别控制什么。
先抓住这 3 个关键点
- dmPolicy 解决私聊准入，groups / groupPolicy / groupAllowFrom 解决群聊准入，requireMention 解决群里触发阈值。
- allowlist 不是可有可无的补充，而是把 OpenClaw 用稳的关键工具。
- 配置写得清楚，后面排错和团队协作才不靠猜。
先把配置分成 4 层
| 层级 | 典型字段 | 它回答的问题 | 常见错误 |
|---|---|---|---|
| Gateway 运行层 | gateway.mode、health check、restart、auth | Gateway 能否启动、如何被访问、如何保持稳定 | 把 Gateway 启动失败误判成 channel 配置错 |
| 私聊准入层 | dmPolicy、allowFrom | 谁能私信机器人 | open 没有边界，或 allowlist 没列人 |
| 群聊准入层 | groupPolicy、groupAllowFrom、groups | 哪些群可以触发机器人 | 批准了 DM 后误以为群权限也开了 |
| 群聊触发层 | requireMention、mentionPatterns、messages.visibleReplies | 群里什么时候应该真正回复 | 群里每条消息都触发，或者回复路径不符合预期 |
排查时也按这 4 层走。不要看到 Telegram 不回复就直接重写 bot token，也不要看到 Control UI 有状态就认为配置一定生效。
实操步骤
- 先把“私聊规则”和“群聊规则”分开思考，不要混成一个大块配置。
- 决定 dmPolicy 是 pairing、allowlist、open 还是 disabled，再写 allowFrom。
- 决定群聊是否允许、允许哪些群、是否必须 @mention。
- 对 groups 单独处理 requireMention，别默认群里所有消息都应该触发助手。
- 每改一次策略，都回到实际聊天场景里做一次验证，不要只看文件本身。
配置或命令示例
{
channels: {
telegram: {
dmPolicy: "allowlist",
allowFrom: ["tg:123456789"],
groups: { "*": { requireMention: true } }
}
}
}再看一个更接近团队使用的骨架。它不追求覆盖所有字段，而是把策略分层写清楚。
{
gateway: {
mode: "local",
channelHealthCheckMinutes: 5,
channelStaleEventThresholdMinutes: 30
},
messages: {
visibleReplies: "automatic",
groupChat: {
visibleReplies: "message_tool"
}
},
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
allowFrom: ["tg:123456789"],
groupPolicy: "allowlist",
groupAllowFrom: ["tg-group:-1001234567890"],
groups: {
"tg-group:-1001234567890": {
requireMention: true
}
}
}
}
}这段配置表达的是：
- Gateway 本地运行，并启用基础 channel health 监控。
- 私聊默认走 pairing，但保留一个已知允许来源。
- 群聊必须在 allowlist 内，而且指定群必须 @ 才触发。
- 群组可见回复走 message tool 路径，避免旧式自动回复在团队群里造成误解。
dmPolicy 怎么选
| 值 | 适合场景 | 风险 |
|---|---|---|
pairing | 新 channel 上线、希望陌生发送者先走审批 | 管理员要及时处理 code，过期后需要重来 |
allowlist | 稳定生产环境、成员名单明确 | 忘记更新 allowFrom 会挡住合法用户 |
open | 临时公开测试、演示 bot、隔离环境 | 容易被未知私信触发，生产环境慎用 |
disabled | 暂停私聊入口、只保留群或其他入口 | 用户会以为 bot 故障，需要公告清楚 |
如果你不确定，优先从 pairing 开始，再把稳定成员沉淀到 allowlist。不要因为调试方便就长期保留 open。
群聊配置怎么选
群聊比私聊更容易误触发，因为同一条消息可能被很多人看到。建议默认遵守三条规则：
- 群是否允许，先由
groupPolicy/groupAllowFrom/groups决定。 - 允许进入的群，也默认
requireMention: true。 - 群里回复路径尽量可控，必要时检查
messages.groupChat.visibleReplies。
团队群、客户群、告警群不要共用一套策略。客户群应该更保守，告警群应该更明确触发词，团队内部测试群才适合短期放宽。
配置变更检查清单
- 这次改的是 Gateway 运行层、私聊准入层、群聊准入层，还是群聊触发层。
- 是否有至少一个真实账号或群 ID 用来验证。
allowFrom/groupAllowFrom的 ID 格式是否来自实际渠道，而不是手写猜测。- 是否知道回滚方式，例如恢复上一个配置片段或切回
disabled。 - 改完是否做了“私聊一次、群聊一次、非授权账号一次”的验证。
- 如果是团队环境，是否记录了修改人、修改原因和验证结果。
生产环境推荐基线
这个基线不是唯一答案，但适合大多数刚开始上线的团队：
- 私聊：
dmPolicy: "pairing"或allowlist。 - 群聊：只允许明确群 ID，不使用全局开放。
- 群触发：默认
requireMention: true。 - Gateway：不要绕过启动防护；配置缺失时先修复配置。
- 密钥：bot token、Gateway token、paired state、allowlist 存储都按敏感数据处理。
- 审计：每次新增成员、新增群、新增设备，都留下最小记录。
常见坑
- 把 dmPolicy 和 groupPolicy 混着想，导致私聊、群聊都表现异常。
- allowlist 写对了值，但没核对账号格式，最后还是进不来。
- 想让群里更安静，却忘记 requireMention 这种最直接的降噪开关。
- 在测试环境用
open很顺手，迁到生产时忘记收紧。 - 批准了某个人的 pairing，却忘记群组授权是另一套规则。
- 改了配置但只看文件，没有回到真实聊天入口验证。
完成检查
- 你能解释每个策略字段控制的是哪一层行为。
- 你的私聊和群聊至少已经不是“一把梭”的默认开放状态。
- 别人接手你的配置时，也能较快看懂它在做什么。
- 你能用一条真实私聊和一条真实群聊证明配置生效。
为什么建议把这篇收藏起来
- 这类配置解释文是最容易被收藏的常青内容之一。
- 每次扩渠道、加群或加人，都会回到这篇。
- 它也是后续看安全加固、channel routing 和团队 playbook 的前置页。