1. 项目概述
如果你家里有一台小爱音箱，除了让它播报天气、定闹钟，有没有想过让它接入更强大的AI大脑，比如直接和豆包、通义千问甚至你自己部署的LLM对话？或者，让它能识别你自定义的唤醒词，比如“你好龙虾”，然后启动一个专属的AI助手？这正是 open-xiaoai-bridge 这个项目要解决的问题。它是一个运行在你本地服务器（比如树莓派、NAS或者一台常开机的电脑）上的桥接服务，核心任务就是打破小爱音箱的封闭生态，让它变成一个开放的、可编程的AI语音交互终端。
简单来说，它在你和小爱音箱之间架起了一座桥。桥的一头连着音箱的音频输入输出，另一头则通向各种你指定的AI服务。通过它，你可以用自定义的唤醒词（比如“龙虾”、“小智”）来触发不同的AI对话，实现连续多轮交流，甚至还能通过HTTP API远程控制音箱播放任意内容。这相当于给你的小爱音箱“刷”上了一个全新的、更智能的“灵魂”，而这一切都基于开源技术，完全在你的掌控之中。
2. 核心思路与架构解析
2.1 为什么需要桥接器？
小爱音箱的原生系统是一个“黑盒”。它的语音识别（ASR）、自然语言理解（NLU）和语音合成（TTS）都依赖于小米的云端服务。这带来了几个限制：一是功能固定，无法深度定制；二是隐私问题，所有对话数据都要上传；三是生态封闭，无法接入第三方AI能力。
open-xiaoai-bridge 的思路非常巧妙：它不尝试去破解或替换小爱音箱的整个系统，而是“劫持”了它的音频流。具体来说，它需要先在小爱音箱上安装一个轻量级的客户端（Client）。这个客户端会截获麦克风的原始音频数据，通过WebSocket发送给桥接服务端（Server），同时也接收来自服务端的音频数据并播放出来。这样，服务端就获得了对音箱音频输入输出的完全控制权，可以自由地插入自己的语音识别、唤醒词检测和AI对话逻辑。
2.2 系统工作流全景图
整个系统的数据流可以概括为以下几个核心路径：
- 路由到小智AI ：启动与小智服务端的WebSocket连接，将用户的语音流实时转发过去，并接收其返回的TTS音频流进行播放。
- 路由到OpenClaw ：根据配置，有两种模式。 local_asr 模式下，使用本地的SherpaASR模型进行语音识别，将文本发送给OpenClaw Gateway，再转发给指定的AI Agent，最后将Agent的文本回复通过TTS合成并播放。 xiaoai_asr 模式则更巧妙，它“欺骗”小爱音箱进行语音识别，然后截获识别到的文本，再发送给OpenClaw处理。
2.3 核心组件角色
- Client (Rust) : 运行在音箱上的轻量级程序，负责音频抓取、播放和与小爱原生系统的基础交互。它是整个系统的“触手”。
- Server (Python + Rust) : 运行在本地服务器上的主桥接服务。它包含了音频处理流水线（VAD, KWS, ASR）、对话状态机、与各个AI服务（小智、OpenClaw）的连接器，以及HTTP API服务。它是系统的“大脑”。
- OpenClaw : 一个开源的AI Agent框架和网关。在本项目中，它充当了“AI能力调度中心”的角色。Bridge将用户请求发送给OpenClaw Gateway，Gateway再将其路由给配置好的AI Agent（如豆包、DeepSeek等）进行处理。
- 小智AI服务端 : 另一个提供对话能力的服务。Bridge可以作为其客户端，实现完整的语音对话闭环。
实操心得：架构选择的意义 这种“客户端劫持音频 + 服务端集中处理”的架构，平衡了功能与复杂度。客户端足够轻量，稳定性和资源占用低；所有复杂的AI逻辑、模型推理都在服务端完成，方便升级和维护。更重要的是，它保持了小爱音箱原有功能的完整性，你依然可以随时用“小爱同学”唤醒它使用原生功能，两者互不干扰。
3. 环境准备与部署详解
3.1 前期准备：给小爱音箱“动手术”
要让桥接器工作，第一步是获得小爱音箱的“底层访问权限”。这需要通过刷机来实现。 请注意，此操作有风险，可能导致设备失去保修或变砖，请务必仔细阅读教程并确认设备型号支持。
重要提示 ：刷机有风险，请确保你已备份重要数据，并完全理解每一步操作的含义。如果对硬件操作不熟悉，建议先在有相同型号的“练手”设备上尝试，或者寻求社区帮助。
3.2 服务端部署：三种方式对比
服务端可以部署在任何能运行Docker或Python的Linux设备上，比如家庭服务器、NAS、甚至一台旧电脑。
方式一：Docker Compose（推荐） 这是最简单、最干净的方式，能避免复杂的Python环境依赖问题。
# 1. 创建项目目录并进入
mkdir open-xiaoai-bridge && cd open-xiaoai-bridge
# 2. 下载模型文件（这是语音识别和唤醒词检测的基础）
# 从项目的GitHub Releases页面下载最新的模型压缩包，例如：
wget https://github.com/coderzc/open-xiaoai-bridge/releases/download/vad-kws-asr-models/models.tar.gz
tar -zxvf models.tar.gz
# 解压后会得到一个 `models` 文件夹
# 3. 下载核心配置文件
curl -O https://raw.githubusercontent.com/coderzc/ope
