如何将 AlphaAvatar 链接到 WhatsApp（Channel 架构实践）

🔗 项目地址
👉 https://github.com/AlphaAvatar/AlphaAvatar
欢迎 Star ⭐ / PR 🚀

在 AlphaAvatar 的最新版本中，我们开始让 Agent 不再局限于 Playground，而是可以真正接入外部通信平台。

其中第一个落地的 Channel，就是：

✅ WhatsApp（基于 Baileys Driver）

这篇文章将带你一步步完成：

• AlphaAvatar Channel 架构快速理解
• WhatsApp 是如何接入的
• 如何本地跑通完整链路
• 当前限制与后续规划

---

🧠 一、整体思路：Agent 不直接接平台

在 AlphaAvatar 中，我们没有把 WhatsApp 逻辑直接写进 Agent。

而是采用了一种更可扩展的设计：

可以简单理解为：

• Driver：负责接入 WhatsApp
• Bridge：负责转发与路由
• Runtime：负责 AI 推理（LLM / Memory / RAG / MCP）

👉 这意味着：

Agent 不需要知道消息来自 WhatsApp

---

🏗 二、WhatsApp Channel 结构

当前 WhatsApp Channel 分为两层：

---

1️⃣ Driver Layer（Node.js）

使用：

Baileys（WhatsApp Web 协议）

负责：

• 登录 WhatsApp
• 接收消息
• 发送消息

---

2️⃣ Bridge Core（Python）

负责：

• WebSocket 通信
• 消息路由（whatsapp.in / whatsapp.out）
• Session 管理
• 与 AlphaAvatar Agent 对接

---

🔁 三、一条消息是如何流动的？

---

🚀 四、如何接入 WhatsApp（实操步骤）

下面是最关键的部分：如何把 WhatsApp 跑起来

---

1️⃣ 启动 AlphaAvatar Agent

ENV_FILE=.env.dev alphaavatar dev examples/agent_configs/pipline_openai_tools.yaml

👉 这一步会启动：

• AgentSession
• AvatarEngine
• Memory / RAG / MCP 等能力

---

2️⃣ 启动 WhatsApp Channel

ENV_FILE=.env.dev sh examples/channels/start_whatsapp.sh

这个脚本会自动完成：

• 启动 WhatsApp Bridge Core（Python）
• 启动 Baileys Driver（Node.js）
• 建立 WebSocket 连接

⚠️ 注意：

必须先启动 Agent，再启动 Channel

---

3️⃣ 扫码登录 WhatsApp

启动后，终端会打印二维码：

• 打开 WhatsApp
• 进入 Linked Devices
• 扫描二维码

---

4️⃣ 发送消息测试

当你发送一条 WhatsApp 消息时：

• Driver 会收到消息
• Bridge 转发到 Agent
• Agent 自动回复
• 回复通过 WhatsApp 发回

👉 至此链路打通

---

⚠️ 五、常见问题（开发阶段）

在当前版本中，WhatsApp Channel 仍然处于开发阶段，可能遇到以下问题：

---

1. 收不到消息 / 无法回复

常见日志：

• identity changed
• No session found to decrypt message

原因通常是：

Baileys 本地 session 与 WhatsApp 当前状态不一致

解决方法：

rm -rf auth

然后重新扫码登录。

---

2. Driver 已连接但链路不通

可能原因：

• Agent 未启动
• 启动顺序错误
• WebSocket 未连接成功

建议：

👉 先确认 Agent 正常运行，再启动 Channel

---

3. 二维码未显示

可能原因：

• 日志被重定向到文件
• 未正确 tail 输出

---

🔌 六、为什么这样设计？

这套结构最大的优势是：

---

1️⃣ Driver 可替换

当前：

• Baileys（开发用）

未来：

• Meta Cloud API
• Twilio WhatsApp API

👉 不需要改 Agent

---

2️⃣ 支持多 Channel

未来可以同时支持：

• WhatsApp
• WeChat
• Slack
• Web App

---

3️⃣ Runtime 完全解耦

Agent 只处理：

whatsapp.in → thinking → whatsapp.out

不关心底层平台。

---

🗺 七、后续规划（TODO）

---

Channel 层

• Meta Cloud API Driver（生产级）
• Twilio Driver
• WeChat Channel
• Slack Channel

---

能力扩展

• 语音消息（ASR）
• 图片 / 文件支持
• 多模态输入
• Streaming 回复

---

架构增强

• Channel SDK（自定义接入）
• 多 Channel 并行
• 更完善的 Session 管理
• 监控与稳定性优化

---

🏁 总结

通过 Channel 架构，AlphaAvatar 正在实现一个关键能力：

让 Agent 从“开发工具”变成“可接入真实世界的 Avatar”

而 WhatsApp，只是第一步。