基于 AlphaAvatar 打造 WhatsApp AI 助手:Baileys 渠道架构与白名单安全实战
基于 AlphaAvatar 打造 WhatsApp AI 助手:Baileys 渠道架构与白名单安全实战
AlphaAvatar 是一个可自托管的实时多模态 AI 助手框架,内置 WhatsApp 渠道:通过 Baileys 驱动连接 WhatsApp Web 协议,再经 Bridge Core 桥接到 Agent 运行时,并配合白名单机制只放行可信号码。本文将带你快速搭建这个 WhatsApp AI 助手,看懂 Baileys 渠道的三层架构,并掌握白名单安全配置。
💡 AlphaAvatar 的完整运行架构如下图所示,WhatsApp 属于最上层「USER & CHANNELS(输入源)」之一,消息最终汇入 Agent & Runtime 层参与实时多模态交互:
为什么选择 AlphaAvatar 做 WhatsApp AI 助手?
大多数聊天机器人框架把「渠道逻辑」和「AI 逻辑」搅在一起,换一家消息平台就要改核心代码。AlphaAvatar 走的是渠道解耦路线:
- 🎙️ 渠道只是入口:WhatsApp、Web、语音、摄像头都只是输入通道,AI 核心完全独立;
- 🧠 插件生态加持:Memory(长期记忆)、Persona(用户画像)、RAG、MCP 工具调用等插件开箱即用,你的 WhatsApp 助手可以"记住"和"行动";
- 🔌 可插拔驱动:当前默认驱动是 Baileys(基于 WhatsApp Web 协议,适合开发和个人使用),未来可平滑切换 Meta Cloud API / Twilio 官方接口,Agent 侧代码一行不用改。
下面这张截图展示了 AlphaAvatar 助手与用户实时交互的完整界面(语音、文字、工具调用、状态反馈一应俱全):
渠道架构:Driver + Bridge Core + Agent 三层设计
WhatsApp 渠道位于 avatar-channels/avatar-channels-whatsapp/,官方说明见 README。整体分为两层可替换/稳定的结构:
WhatsApp 后端 API
│
▼
Driver 层(可替换,当前为 Baileys)
│ WebSocket(ws://127.0.0.1:18789)
▼
Bridge Core(Python 稳定层)
│ LiveKit DataChannel(whatsapp.in / whatsapp.out)
▼
AlphaAvatar Agent
| 层级 | 职责 | 代码位置 |
|---|---|---|
| 🔌 Driver 层 | 连接 WhatsApp、收发原始消息、归一化事件格式、通过 WebSocket 与 Core 通信 | drivers/baileys/src/baileys.ts |
| 🧠 Bridge Core | WebSocket 枢纽、消息去重、会话映射、LiveKit 发布/订阅、路由 whatsapp.in / whatsapp.out |
core.py |
一条消息的完整旅程
- 📥 接收:Baileys 驱动监听
messages.upsert事件,忽略自己发的消息和@broadcast广播,提取纯文本; - 🔐 过滤:驱动与 Core 两层分别执行白名单校验(详见下文);
- 🚀 桥接:Core 在 core.py 中对
message_id去重后,交给 room_manager.py 按chat_id映射到专属 LiveKit 房间(wa_<chat_id>); - 🤖 推理:livekit_bridge.py 把事件发布到
whatsapp.in话题,Agent 订阅后处理; - 📤 回复:Agent 输出经
whatsapp.out回到 Core,Core 再通过 WebSocket 推给 Driver 发送。
几个值得学习的设计细节:
- ⏳ 消息缓冲:房间创建后 Agent 需要预热,期间到达的消息先进入
pending_messages缓冲,收到whatsapp.ready信号后统一冲刷,避免首条消息丢失; - ♻️ 自动重连:Baileys 驱动采用指数退避(1s → 2s → 4s → … 上限 15s)重启 WebSocket 与 WhatsApp 连接;被登出(
loggedOut)时会提示清空 auth 重新扫码配对; - 🧹 空闲回收:房间空闲超过
WHATSAPP_IDLE_TIMEOUT_SEC(默认 900 秒)自动关闭,防止长期占用 LiveKit 资源。
快速上手:4 步跑通 WhatsApp AI 助手
第一步:启动 Agent 与 Bridge Core
先按主 README 的 Quick Start 启动 AlphaAvatar Agent(需要 LiveKit 与模型 API 的环境变量,模板见 .env.template)。然后在仓库根目录启动 WhatsApp 核心:
uv run alphaavatar-whatsapp-core
看到 WhatsApp Core WS listening on ws://127.0.0.1:18789 即成功。
第二步:启动 Baileys 驱动
cd drivers/baileys
pnpm install
pnpm dev
看到 Connected to Core WS 后,终端会打印一个二维码。
第三步:手机扫码绑定
打开 WhatsApp → 设置 → 已关联设备 → 关联设备,扫描终端二维码,日志出现 WhatsApp connection opened 即绑定成功。
第四步:发送消息测试
给你的 WhatsApp 账号发一条消息,应收到 [echo] your message 回复(未接入 Agent 前的链路自检);Agent 正常运行后会得到真正的 AI 回复。
💡 也可以一条命令搞定全部(先确保 Agent 已启动):
ENV_FILE=.env.dev sh examples/channels/start_whatsapp.sh
该脚本会依次拉起 Core 与驱动并等待就绪,见 start_whatsapp.sh。
白名单安全实战:只让可信号码说话
对外暴露一个 AI 助手,第一件事是访问控制。AlphaAvatar 的 WhatsApp 白名单是一个"双保险"设计,逻辑分别实现在驱动侧 baileys.ts 和核心侧 whitelist.py,任一层拦截都会直接丢弃消息并记录 Blocked by whitelist 告警。
白名单的 3 个关键机制
- ✅ 号码归一化:自动剥离
@s.whatsapp.net后缀和所有非数字字符,+971 50-1234567与971501234567@s.whatsapp.net等价匹配,配置文件写起来零门槛; - 🚫 群聊默认拒绝:以
@g.us结尾的群聊 ID 无论是否在名单中一律拒绝,规避群聊广播放大攻击; - ⚙️ 环境开关控制:默认关闭(
WHATSAPP_WHITELIST_ENABLED=false),启用后白名单文件缺失或为空时也会告警提示。
配置步骤
在 .env.dev 中开启并指定名单文件(模板参考 .env.template):
WHATSAPP_WHITELIST_ENABLED=true
WHATSAPP_WHITELIST_FILE='avatar-channels/avatar-channels-whatsapp/whitelist.txt'
然后创建白名单文件(每行一个号码,格式随意,归一化后匹配):
+8613800138000
9715012345678
⚠️ 仓库内自带的 white_list.txt 是占位示例,请替换为你自己的号码。未通过校验的消息会被静默丢弃,仅在日志中留下
Blocked inbound by whitelist记录——这既是安全,也是一种轻量的行为审计。
统一事件 Schema:驱动与核心的契约
所有 Driver 无论底层是 Baileys、Meta 还是 Twilio,都必须输出统一格式的 JSON 事件(定义见 schema/events.py):
| 方向 | 关键字段 |
|---|---|
| 入站(in) | channel=whatsapp、from、chat_id、message_id、text、meta.driver |
| 出站(out) | to、chat_id、text |
这意味着换驱动 = 只换 drivers/ 目录下的实现:Bridge Core、LiveKit 话题、Agent 路由逻辑、Memory/RAG/MCP 插件全部保持不变——这正是架构文档中强调的"驱动可替换、核心稳定"原则。
面向生产:Baileys 升级路线图
Baileys 基于 WhatsApp Web 协议,官方建议仅用于开发、内部测试和个人 Bot。迁移到生产环境时,官方 README 给出了一份加固清单:
- 持久化去重(Redis / 数据库)替代内存 Set;
- 每用户消息队列 + 限流;
- 白名单 / 配对机制(已内置);
- 监控健康检查、容器化部署;
- 🔄 用 Meta Cloud API 或 Twilio WhatsApp API 替换 Baileys 驱动。
小结
通过 Baileys 驱动 + Python Bridge Core + LiveKit 数据通道的三层架构,AlphaAvatar 把 WhatsApp 变成你的实时 AI 助手的一个"入口",而白名单机制以双层拦截、号码归一化和群聊拒绝三道防线守住安全底线。从 uv run alphaavatar-whatsapp-core 开始,四步即可在手机上和它对话——接下来,不妨给它配上 Memory 与 MCP 插件,让它成为真正"记得住、干得了事"的私人助手。 🚀