基于 AlphaAvatar 打造 WhatsApp AI 助手:Baileys 渠道架构与白名单安全实战

原创2026-10-27 19:00:061,986 阅读

基于 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 助手实时多模态运行架构图

为什么选择 AlphaAvatar 做 WhatsApp AI 助手?

大多数聊天机器人框架把「渠道逻辑」和「AI 逻辑」搅在一起,换一家消息平台就要改核心代码。AlphaAvatar 走的是渠道解耦路线:

  • 🎙️ 渠道只是入口:WhatsApp、Web、语音、摄像头都只是输入通道,AI 核心完全独立;
  • 🧠 插件生态加持:Memory(长期记忆)、Persona(用户画像)、RAG、MCP 工具调用等插件开箱即用,你的 WhatsApp 助手可以"记住"和"行动";
  • 🔌 可插拔驱动:当前默认驱动是 Baileys(基于 WhatsApp Web 协议,适合开发和个人使用),未来可平滑切换 Meta Cloud API / Twilio 官方接口,Agent 侧代码一行不用改。

下面这张截图展示了 AlphaAvatar 助手与用户实时交互的完整界面(语音、文字、工具调用、状态反馈一应俱全):

AlphaAvatar 实时 AI 助手界面:语音、对话与工具调用演示

渠道架构: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

一条消息的完整旅程

  1. 📥 接收:Baileys 驱动监听 messages.upsert 事件,忽略自己发的消息和 @broadcast 广播,提取纯文本;
  2. 🔐 过滤:驱动与 Core 两层分别执行白名单校验(详见下文);
  3. 🚀 桥接:Core 在 core.py 中对 message_id 去重后,交给 room_manager.py 按 chat_id 映射到专属 LiveKit 房间(wa_<chat_id>);
  4. 🤖 推理:livekit_bridge.py 把事件发布到 whatsapp.in 话题,Agent 订阅后处理;
  5. 📤 回复: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 个关键机制

  1. ✅ 号码归一化:自动剥离 @s.whatsapp.net 后缀和所有非数字字符,+971 50-1234567 与 971501234567@s.whatsapp.net 等价匹配,配置文件写起来零门槛;
  2. 🚫 群聊默认拒绝:以 @g.us 结尾的群聊 ID 无论是否在名单中一律拒绝,规避群聊广播放大攻击;
  3. ⚙️ 环境开关控制:默认关闭(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 插件,让它成为真正"记得住、干得了事"的私人助手。 🚀

登录后查看全文
AlphaAvatar