Qwen-Audio-Agent：阿里通义千问开源的实时语音智能体框架

一、Qwen-Audio-Agent 是什么

Qwen-Audio-Agent 是阿里通义千问音频团队开源、基于通义千问实时语音大模型 Qwen Audio 3.0 Realtime 打造的本地全双工实时语音智能体运行框架，开源协议为 Apache 2.0。

该项目核心解决传统语音对话工具两大痛点：一是语音交互单向传输、无法随时打断对话；二是AI执行代码、文件操作、复杂工具任务时对话阻塞，用户只能等待任务完成才能继续沟通。

它将实时语音流式交互与可异步并行执行任务的AI智能体（Agent） 深度融合，提供终端控制台、网页界面、macOS桌面客户端三套交互载体，兼容遵循 ACP 协议的各类代码智能体，所有用户对话记忆、任务记录本地存储，仅音频对话数据上传阿里云百炼实时语音服务，兼顾本地数据安全与云端语音识别合成能力。

二、功能特色

1. 全双工流式实时语音交互
   原生支持人声打断、边说边识别、实时流式语音合成；macOS内置回声消除，可外放扬声器对话；Windows、Linux环境需搭配耳机实现无回声全双工，半双工模式适配普通外放设备。

2. 对话与后台任务异步并行
   AI执行代码运行、文件编辑、批量处理等耗时任务时不会锁定对话通道。用户可随时提问任务进度、中途取消任务、追加修改指令，任务完成后结果自动汇入对话上下文，支持多轮二次调整。

3. 多端可视化交互客户端
   内置三种交互入口：TUI 终端文本界面、WebUI 浏览器网页面板、macOS 悬浮球桌面客户端；桌面端提供动态声波UI，支持后台常驻系统托盘，一键唤醒语音对话。

4. 多智能体后端兼容，一键切换
   原生适配 OpenCode、OpenClaw、Qoder、Hermes、CodeBuddy、Codex 六大代码智能体，同时兼容所有符合 ACP 标准的自定义Agent，通过环境变量、配置文件快速切换后端执行引擎。

5. 本地离线记忆存储
   用户对话记录、任务历史、个性化偏好全部保存在本地目录 ~/.config/qwaudio/，无自动云端上传逻辑，保护本地文件与对话隐私。

6. 系统后台托管服务
   支持将语音网关注册为系统后台服务，开机自启、长期后台在线，无需重复启动命令，适配长期挂机语音助手场景。

7. 分级安全权限管控
   分为 native 弹窗询问权限、full 全自动执行权限两种模式；文件修改、系统命令运行前可弹窗确认，避免AI误操作本地文件。

三、技术细节

1. 整体技术栈

• 网关主程序：Node.js 22.22.2+/24.15.0 + TypeScript，负责音频流转发、对话上下文管理、Agent任务调度

• 前端交互：原生HTML/CSS/JS WebUI；Swift 开发 macOS 桌面悬浮客户端

• 脚本工具：Shell 实现系统服务安装、环境初始化、一键部署脚本

• 语音底层：对接阿里云 DashScope Qwen Audio 3.0 Realtime 流式语音API，完成实时ASR语音识别、TTS语音合成、人声端点检测

• Agent通信：自研 ACP（Agent Communication Protocol）通信协议，网关与代码智能体进程间标准数据交互规范

2. 核心运行架构

三层分层架构：

1. 音频采集交互层：麦克风音频采集、回声消除、人声端点检测，分发音频流至云端语音模型；接收云端语音流输出扬声器。

2. 网关调度核心层：上下文缓存、任务队列异步管理、多端客户端连接管理、权限校验、本地记忆读写、ACP协议中转。

3. Agent执行层：独立子进程运行代码智能体，耗时任务放入异步队列，执行状态实时回传给网关，不阻塞语音对话链路。

3. 关键技术机制

• 全双工流式链路：音频分片毫秒级传输，识别文本逐字实时推送，支持用户中途打断AI语音输出。

• 任务并行调度：采用多队列隔离机制，对话问答队列与工具执行队列完全分离，两条链路独立运行互不阻塞。

• 本地持久化：采用JSON文件轻量化存储会话记忆，无数据库依赖，开箱即用。

• 进程隔离：每个Agent后端独立子进程运行，任务崩溃不会导致整个语音网关服务中断。

4. 部署运行依赖

运行环境最低要求：Node.js 22+、npm 10+；调用语音能力需阿里云百炼 DASHSCOPE_API_KEY；macOS客户端编译依赖Xcode，Windows/Linux音频依赖系统自带音频驱动。

四、应用场景

1. 本地语音编程助手
   对着麦克风口述代码需求，AI后台异步编写、运行、调试代码，说话过程中可随时打断、修改需求，无需等待代码执行完毕。

2. 桌面常驻语音自动化工具
   后台长期挂机，语音下达批量文件整理、文档处理、脚本运行指令，同步询问任务进度，适合办公自动化。

3. 开发者本地多模态调试工具
   网页端/终端实时语音对话，结合代码智能体调试项目，语音快速查询接口、修复报错、生成测试用例。

4. 轻量化离线语音私人助理
   本地留存所有对话记录，隐私敏感场景使用，语音查询本地文件、执行系统命令，数据不上传第三方平台。

5. 自定义语音智能体二次开发基座
   基于ACP协议接入自研工具Agent，快速搭建专属实时语音交互机器人，适配小型工作室、个人开发者定制需求。

五、使用方法

方式1：NPM全局一键安装（推荐）

1. 环境准备：安装 Node.js 22 及以上版本，打开终端。

2. 全局安装命令：

npm install -g qwen-audio-agent

3. 初始化配置，填入阿里云百炼API Key：

qwenaudio config

4. 启动语音网关核心服务：

qwenaudio

5. 选择交互客户端（新开终端执行其一）

• 终端文本界面：qwenaudio tui

• 浏览器网页界面：qwenaudio webui

• macOS桌面悬浮球：直接启动桌面客户端程序

方式2：GitHub源码本地部署

1. 克隆源码仓库

git clone https://github.com/QwenAudio/qwen-audio-agent.git
cd qwen-audio-agent

2. 安装项目依赖

npm install

3. 本地构建打包

npm run build

4. 本地启动网关与交互端，命令同上述全局安装流程。

方式3：系统后台托管（长期挂机）

执行系统服务安装命令，实现开机自启后台运行，配套启停、状态查看、卸载运维指令。

使用注意事项

1. Windows/Linux外放扬声器使用会产生回声，必须佩戴耳机才能正常全双工交互；macOS自带回声消除，可直接外放。

2. 安全权限默认 native 弹窗确认模式，频繁执行本地脚本可手动修改配置切换为 full 全自动权限。

3. 所有对话历史自动保存至 ~/.config/qwaudio/，手动删除文件夹即可清空全部本地记忆。

六、竞品对比

选取2款同类型实时语音智能体框架进行横向对比：OpenAI Realtime Agent、VoiceCode Agent

七、常见问题解答

Q：运行程序提示缺少 DASHSCOPE_API_KEY，如何解决？

A：登录阿里云百炼控制台，创建DashScope应用获取API密钥，执行qwenaudio config命令，按提示粘贴密钥保存配置文件后重启网关服务即可。

Q：Windows使用时AI无法识别人声，持续出现回声杂音怎么办？

A：Windows系统无内置回声消除能力，必须佩戴有线/无线耳机隔绝扬声器回声；同时在电脑音频设置中将麦克风增益调低，避免噪音干扰语音识别。

Q：启动qwenaudio webui后浏览器无法打开网页界面？

A：网关服务未正常启动，先执行qwenaudio开启核心网关；同时检查本机127.0.01端口未被其他程序占用，关闭端口占用软件后重新启动。

Q：执行代码任务时程序弹窗询问权限，如何关闭弹窗自动执行？

A：修改本地配置文件，将权限字段从native修改为full，保存配置后重启网关；仅可信本地开发环境推荐开启全自动权限。

Q：macOS桌面悬浮球启动后无麦克风权限，收不到人声？

A：前往系统设置-隐私与安全性，授予桌面客户端麦克风权限，重启悬浮球程序后即可正常采集音频。

Q：如何清空所有本地对话记忆与任务历史？

A：关闭所有qwen-audio-agent进程，删除本地目录~/.config/qwaudio/全部文件夹，重新启动程序会自动生成全新空白记忆配置。

Q：是否支持接入自研自定义代码智能体？

A：支持，只要智能体程序遵循项目ACP通信协议规范，在配置文件中填写自定义Agent启动命令与工作目录，即可一键切换后端。

八、相关链接

• GitHub仓库地址：https://github.com/QwenAudio/qwen-audio-agent

九、总结

Qwen-Audio-Agent是适配国内网络环境、完全开源的全双工实时语音智能体运行框架，依托通义千问流式语音大模型实现低延迟人声交互，创新的任务异步并行机制解决了传统语音工具任务阻塞对话的核心痛点，同时提供多端可视化交互载体、本地隐私存储、多代码智能体兼容能力，部署门槛低、二次开发拓展性强，面向个人开发者、编程爱好者、办公自动化需求人群提供一套完整可本地部署的语音AI工具链，无复杂环境依赖，国内云节点保障稳定语音识别与合成体验。