OpenClaw学习总结_II_频道系统_1：WhatsApp集成详解
II. 频道系统 - 1. WhatsApp
📍 课程位置
阶段：II. 频道系统
课序：第 1 课
前置知识：I. 核心架构（Gateway/Session/Tools）
后续课程：II-2. Telegram
🎯 本课核心问题（你不懂我就这样教你）
你会遇到的最现实问题是：
- 我怎么把 OpenClaw 接到 WhatsApp 上，让它能收消息、能回消息？
- 怎么控制谁能跟机器人私聊（安全）？
- 为什么会有扫码、掉线、收不到消息、群聊提及等问题？
这一课我会按“老师教小白”的方式，带你把 WhatsApp 频道接起来，并把常见坑点讲清楚。
🧠 先建立心智模型：WhatsApp 渠道在 OpenClaw 里是什么
一句话：
WhatsApp 渠道 = OpenClaw Gateway 里的一段“适配器”，把 WhatsApp 的消息转换成 OpenClaw 统一的消息事件，再把回复发回 WhatsApp。
类比：
- WhatsApp 像“外部手机通讯软件”
- OpenClaw Gateway 像“总机”
- WhatsApp 插件像“WhatsApp 专线接线员”
✅ 你要达到的结果（验收标准）
完成后你应该能做到：
- 能让 OpenClaw在 WhatsApp 上收到你的消息
- 能让 OpenClaw在 WhatsApp 上回复你
- 能限制只有你（或白名单）能私聊
- 能设置群聊是否需要 @ 才响应
- 出问题时知道从哪里排查
🔧 第一步：在配置里开启 WhatsApp
在~/.openclaw/openclaw.json里增加/修改：
{ channels: { whatsapp: { enabled: true, // 访问策略（重要！） dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["+86xxxxxxxxxxx"], groupPolicy: "open", // open | allowlist | disabled（不同版本可能略有差异） groupAllowFrom: ["*"] } } }dmPolicy 怎么选？（安全最关键）
pairing：默认推荐。陌生人需要配对码才可聊天。allowlist：只有 allowFrom 里的号码能聊天。open：所有人都能 DM 你（风险大，不建议）。disabled：完全禁用 DM。
建议：除非你非常确定，否则用pairing或allowlist。
🔧 第二步：登录 WhatsApp（扫码）
WhatsApp 通道通常需要通过 Web 方式登录（会出现二维码）。
你要做的事：
- 启动 OpenClaw Gateway（确保 WhatsApp channel enabled）
- 观察日志/控制台提示二维码
- 用手机 WhatsApp 扫码登录
类比：
- 就像你在电脑登录微信，需要手机扫码确认
🔧 第三步：验证消息链路
你发一条 WhatsApp 消息给机器人，链路应该是：
WhatsApp 你的消息 ↓ WhatsApp channel adapter（接线员） ↓ Gateway（统一路由） ↓ Session（找到对话上下文） ↓ Agent Loop（理解/工具/生成） ↓ Gateway ↓ WhatsApp channel adapter ↓ WhatsApp 回复如果任意环节断了，就会表现为“没反应”。
🧩 群聊里怎么让它不乱插话？（@ 才回）
建议：群聊默认 require mention。
{ agents: { list: [ { id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, }, ], }, channels: { whatsapp: { groups: { "*": { requireMention: true } } } } }这样做的目的：
- 防止机器人在群里“误触发”
- 降低 prompt injection 风险
- 控制成本
⚠️ WhatsApp 最常见的坑（以及怎么排）
| 现象 | 常见原因 | 排查/解决 |
|---|---|---|
| 扫码后又掉线 | 会话过期/设备登录冲突 | 重新扫码；检查是否在其他设备踢下线 |
| 收不到消息 | channel 未启用/网关没跑 | 检查channels.whatsapp.enabled；看 gateway.log |
| 能收不能回 | 发送权限/会话异常 | 看错误日志；检查 dmPolicy/allowFrom |
| 群聊乱回 | 没开 requireMention | 配置 group mention gating |
| 一直提示配对 | dmPolicy=pairing 且未完成配对 | 完成配对或用 allowlist |
🧪 最小可用配置（MVP）
如果你只想最快跑通：
{ channels: { whatsapp: { enabled: true, dmPolicy: "allowlist", allowFrom: ["+86xxxxxxxxxxx"], } } }📝 学习心得
WhatsApp 这章的“难点”不在配置字段多，而在“登录态”：
- 扫码登录不是一次性的
- 掉线、过期、设备冲突都会导致消息中断
所以我的经验是：
- 先用最小配置跑通
- 再逐步加安全策略（pairing/群聊@）
- 任何问题先看日志，再看配置
✅ 本课总结（记住 5 句话）
- WhatsApp 通道就是 Gateway 的适配器，负责收发 WhatsApp。
- 最重要的安全开关是 dmPolicy（推荐 pairing/allowlist）。
- 扫码登录是最大不稳定因素，掉线先重登。
- 群聊要开 requireMention，避免乱回和注入风险。
- 排障先看 gateway 日志，再回头对照配置。
🔗 相关资源
- 官方文档：https://docs.openclaw.ai/channels/whatsapp
- 配置参考：https://docs.openclaw.ai/gateway/configuration-reference
- 下一课：II-2. Telegram