$cd ../tutorials/
popularchannels20 min read• March 2026
$ cat whatsapp-integration.md
export WhatsAppIntegration
/** 让您的 OpenClaw AI 通过 WhatsApp 随时随地可达 */
table-of-contents.ts
const sections = [
]
section_01_architecture.md
🏗️## 工作原理：Gateway 架构
WhatsApp 不为个人提供免费官方 API，因此 OpenClaw 采用 Gateway（网关）架构。openclaw-messenger-gateway 创建一个虚拟浏览器（Chromium），代替您登录 WhatsApp Web，并将消息桥接到您的 OpenClaw 实例。
▸
您 → 向自己号码（或专用号）发送 WhatsApp 消息
▸
Gateway → 通过 WhatsApp Web 拦截消息
▸
OpenClaw → 使用选定的 AI 模型处理请求
▸
回复 → 返回您的 WhatsApp 聊天
// 💡 建议：使用副号（如 Google Voice 或廉价 SIM 卡）作为专用 AI WhatsApp 号，而不是您的个人号码。
section_02_prerequisites.md
## ✅ 前置条件
☐OpenClaw 已运行并可访问（参见入门指南）
☐一个 WhatsApp 账号（建议使用专用副号）
☐主机已安装 Docker
☐Node.js 18+（不使用 Docker 运行 Gateway 时需要）
☐服务器需 24/7 运行（VPS 或长开机器）
section_03_install.sh
## 📦 安装 WhatsApp Gateway
OpenClaw 消息网关是一个独立服务，与您的主 OpenClaw 实例并排运行。
Option A: Docker (Recommended)
# Pull and start the gateway
$ docker pull ghcr.io/clawdbot/openclaw-messenger-gateway:latest
$ docker run -d \
--name openclaw-gateway \
-p 3001:3001 \
-e OPENCLAW_URL=http://YOUR_OPENCLAW_IP:18789 \
-v gateway-sessions:/app/sessions \
ghcr.io/clawdbot/openclaw-messenger-gateway:latest
Option B: Node.js
$ git clone https://github.com/clawdbot/openclaw-messenger-gateway
$ cd openclaw-messenger-gateway && npm install
$ cp .env.example .env
# Edit .env with your OpenClaw URL, then:
$ npm start
section_04_pair.md
## 📱 绑定您的 WhatsApp 账号
Gateway 运行后，您需要通过扫描二维码将其与 WhatsApp 账号关联。
步骤 1：打开配对界面
在浏览器中访问 http://YOUR_SERVER_IP:3001。
步骤 2：扫描二维码
打开手机 WhatsApp → 设置 → 已链接的设备 → 关联设备，扫描 Gateway 界面中显示的二维码。
步骤 3：等待确认
10 秒内界面应显示 Connected ✓。会话已保存到磁盘，重启后依然有效。
// ⚠️ 二维码 60 秒后过期，过期请刷新页面获取新码。
section_05_config.yaml
## ⚙️ 连接到 OpenClaw
在 OpenClaw 配置文件中，添加 WhatsApp 频道：
# openclaw/config.yaml
channels:
whatsapp:
enabled: true
gateway_url: "http://localhost:3001"
allowed_numbers:
- "+1234567890" # YOUR number
section_06_security.md
🔐## 安全加固（关键！）
这是最重要的部分。给 AI 访问您的 WhatsApp 意味着任何给您发消息的人都能与 AI 交互。OpenClaw 使用访问控制列表（ACL）——忽略白名单外所有号码的消息。
// Finding unauthorized attempt logs:
$ docker logs openclaw 2>&1 | grep "SECURITY"
[SECURITY] Unauthorized message from: +9876543210. Ignoring.
⚠️ 切勿将 allowed_numbers 留空或设为 * 在生产服务器上。否则任何人都能无限制使用您的 AI（费用由您承担）。
section_07_test.md
## 🧪 测试并上线
从已授权的 WhatsApp 号发送消息，检查是否收到回复：
// Your WhatsApp message:
You: "Hello! What's the weather like in Tokyo right now?"
// OpenClaw response (~10 seconds):
OpenClaw: "Currently in Tokyo: 12°C, partly cloudy..."
section_08_troubleshoot.md
## 🔧 故障排除
重启后会话丢失
-v gateway-sessions:/app/sessions Docker 卷保存您的 WhatsApp 会话。如果会话仍然断开，请重新扫描二维码，并考虑在 Docker 容器上使用 --restart always。
二维码未显示
检查 3001 端口是否可访问。防火墙后可临时运行：sudo ufw allow 3001，配置完成后记得限制访问。
消息未到达 OpenClaw
确认 OPENCLAW_URL 环境变量正确。检查：curl http://YOUR_OPENCLAW_IP:18789/health 应返回 OK。
WhatsApp 账号被封
WhatsApp 偶尔会封禁使用非官方网关的账号。低量个人使用时此情况罕见，但使用专用副号可大幅降低风险。
next_steps.md
## 🚀 下一步
您的 OpenClaw 现已连接 WhatsApp！探索更多频道并加固安全：