Qwen Audio Agent：让 Agent 始终在场的实时语音运行时

Fen9Pi2026/7/31大约 16 分钟

前言：当 Agent 始终在场

想象这样一个场景：

你正在和 AI 助理对话，让它帮你查资料、写代码、处理任务。但每次你提出一个需要时间的请求后，对话就会陷入漫长的等待。

传统方案的痛点：

对话在说完一句话后就陷入漫长的等待
Agent 正在查资料、调用工具或处理任务时，整场对话就此暂停
无法知道任务进度，无法中途取消
任务完成后，需要重新开始对话，无法继续追问

如果有一个实时语音运行时，让 Agent 始终在场呢？

Qwen Audio Agent 正是这样的解决方案：让 Agent 持续交流、持续工作、持续在场的实时语音运行时。无论是聊天、思考，还是处理任务，Agent 都始终在这场对话里。

今天，我们就来深入分析这个革命性的开源项目。

一、项目概览

1.1 是什么？

Qwen Audio Agent 是 Qwen 团队推出的实时语音运行时。

核心特点：

✅ 全双工实时语音交互：支持自然打断和持续多轮对话
✅ 对话与任务并行：对话不会因为后台任务而停下
✅ 任务自动回到上下文：任务完成后，结果会自然回到当前对话
✅ 多 Agent 支持：一键连接 OpenCode、OpenClaw、Qoder、Hermes、CodeBuddy、Codex、Claude Code
✅ 多种交互方式：WebUI、终端 TUI、macOS 桌面悬浮球
✅ 用户档案与记忆：支持本地用户档案与跨会话个人记忆
✅ 开源免费：Apache-2.0 协议，完全开源

项目地址：https://github.com/QwenAudio/qwen-audio-agent NPM：https://www.npmjs.com/package/qwen-audio-agent 开源协议：Apache License 2.0

1.2 核心价值

传统语音助手的痛点：

对话在说完一句话后就陷入漫长的等待
Agent 正在查资料、调用工具或处理任务时，整场对话就此暂停
无法知道任务进度，无法中途取消
任务完成后，需要重新开始对话，无法继续追问

Qwen Audio Agent 的解决方案：

对话不会因为后台任务而停下
任务完成后，结果会自然回到当前对话
可随时查询进度或取消任务
支持继续追问和修改

二、核心特色

2.1 全双工实时语音交互

核心思想：真正的交流，不该在说完一句话后，就陷入漫长的等待。

能力：

全双工：可以同时说话和听，不需要轮流
自然打断：可以在 Agent 说话时打断，像真人对话一样
持续多轮对话：可以持续对话，不需要每次重新开始
低延迟：实时响应，延迟极低

优势：

交流应该是连续的
Agent 应该始终在场
对话体验更自然

2.2 对话与任务并行

核心思想：对话不会因为后台任务而停下；任务完成后，结果会自然回到当前对话。

能力：

并行处理：对话和后台任务同时进行
进度查询：可随时查询任务进度
任务取消：可随时取消任务
结果回到上下文：任务完成后，结果会自然回到当前对话
继续追问：可以继续追问和修改

示例：

你：帮我查一下 Python 的最新版本

Agent：好的，我来帮你查一下 Python 的最新版本。
      （后台开始查询）

你：顺便查一下 Node.js 的最新版本

Agent：没问题，我也帮你查一下 Node.js 的最新版本。
      （后台继续查询）

你：查得怎么样了？

Agent：Python 的最新版本是 3.13.0，Node.js 的最新版本是 22.22.2。
      （任务结果自动回到当前对话）

你：Python 3.13 有什么新特性？

Agent：Python 3.13 有很多新特性，包括...
      （继续追问，上下文保持）

优势：

对话不会暂停
任务进度透明
可以继续追问

2.3 多 Agent 支持

核心思想：一键连接你喜欢的各种 Agent，使用已有的模型、工具、MCP、Skill。

支持的 Agent：

后台 Agent	接入方式	接入准备	推荐指数
无	N/A	仅前台模式，无需配置	★★★★★
OpenCode	原生 ACP	支持自动安装和百炼配置	★★★★★
OpenClaw	内置 ACP 桥接	支持自动安装和百炼配置	★★★★★
Qoder	原生 ACP	用户自行安装和配置	★★★★★
Hermes	原生 ACP	用户自行安装和配置	★★★★☆
CodeBuddy	原生 ACP	用户自行安装和配置	★★★★☆
Codex	外部 ACP 适配	用户自行安装和配置	★★★★☆
Claude Code	外部 ACP 适配	用户自行安装和配置	★★★★☆

推荐指数说明：

五星：已经过充分测试的推荐集成
四星：正在开发或尚未完成同等范围验证

配置方式：

AGENT_PROTOCOL=openclaw

优势：

一键连接
使用已有的模型、工具、MCP、Skill
灵活选择

2.4 多种交互方式

核心思想：支持 WebUI、终端 TUI 和 macOS 桌面悬浮球。

1. WebUI

浏览器界面
跨平台支持
易于使用

2. 终端 TUI

终端界面
跨平台支持
高度可定制

3. macOS 桌面悬浮球

常驻桌面
流光声波球和液态渐变球两种外观
内置和自动管理 Gateway
无需事先启动服务

优势：

灵活选择
跨平台支持
易于使用

2.5 用户档案与记忆

核心思想：支持本地用户档案与跨会话个人记忆。

用户数据保存在 ~/.config/qwaudio/：

USER.md：称呼、所在地、偏好和常用项目
frontend-memory.json：用户明确要求长期记住的信息
tasks.json：任务结果和待通知状态

特点：

只保存在本机
不会写入源码仓库
可以直接编辑 USER.md
可以在对话中要求助理记住或忘记信息

优势：

跨会话记忆
完全本地
隐私保护

三、架构设计

3.1 参考架构

核心思想：能直接回答的问题会立即回答；需要工具或持续处理时，任务会交给后台 Agent。整个过程中，用户面对的始终是同一个助理。

流程图1

三层架构：

1. 前台层（Frontend）

Qwen Audio 3.0 Realtime：实时语音交互
全双工、自然打断、持续多轮对话
低延迟、高响应

2. 后台层（Backend）

各种 Agent：OpenCode、OpenClaw、Qoder、Hermes、CodeBuddy、Codex、Claude Code
执行任务：查资料、写代码、调用工具
任务结果自动回到当前上下文

3. 用户层（User）

用户档案与记忆：USER.md、frontend-memory.json、tasks.json
跨会话记忆
完全本地

3.2 详细架构

核心组件：

1. Gateway

核心服务
管理前台和后台
处理语音交互

2. Frontend

WebUI：浏览器界面
TUI：终端界面
Desktop：macOS 桌面悬浮球

3. Backend Agent

OpenCode：原生 ACP
OpenClaw：内置 ACP 桥接
Qoder：原生 ACP
Hermes：原生 ACP
CodeBuddy：原生 ACP
Codex：外部 ACP 适配
Claude Code：外部 ACP 适配

4. User Data

USER.md：用户档案
frontend-memory.json：长期记忆
tasks.json：任务状态

优势：

模块化设计
灵活扩展
易于维护

四、安装与使用

4.1 安装

前提条件：

Node.js 22.22.2+ 或 24.15.0+
npm 10+
DashScope API Key

一键安装（推荐）：

npm install -g qwen-audio-agent

从 GitHub 安装：

npm install -g git+https://github.com/QwenAudio/qwen-audio-agent.git

从源码安装：

git clone https://github.com/QwenAudio/qwen-audio-agent.git
cd qwen-audio-agent
npm install
npm run install:global

升级到最新 npm 版本：

npm install -g qwen-audio-agent@latest

升级到 GitHub 最新代码：

npm install -g git+https://github.com/QwenAudio/qwen-audio-agent.git

4.2 获取 DashScope API Key

阿里云百炼为 Qwen Audio 3.0 Realtime 提供新人免费额度。

步骤：

打开百炼控制台的 API Key 页面
登录账号，单击创建 API Key
复制生成的 Key，稍后填入 config.env

注意：

请勿公开或提交 API Key
详细说明见百炼官方文档

4.3 快速开始

1. 创建配置：

qwenaudio config

2. 打开命令显示的 config.env，填写 DashScope API Key：

DASHSCOPE_API_KEY=your-key
# 语音前台模型：qwen-audio-3.0-realtime-flash 或 qwen-audio-3.0-realtime-plus（默认）
QWEN_AUDIO_REALTIME_MODEL=qwen-audio-3.0-realtime-plus
# 后台Agent：可选，不设置或设置为 none 时，启动仅前台模式
AGENT_PROTOCOL=openclaw
# 后台模型：可为空，留空则沿用 Agent 自身的用户配置
QWEN_AUDIO_AGENT_BACKEND_MODEL=qwen3.7-max

3. 在一个终端中启动 Gateway：

qwenaudio

4. 另开一个终端，启动 TUI：

qwenaudio tui

5. 也可以使用浏览器界面：

qwenaudio webui

4.4 TUI 使用注意

平台差异：

平台	默认模式	打断方式
macOS	带回声消除的全双工	直接说话
Linux / Windows	半双工	播报时按 x

Linux / Windows 首次使用：

需安装 sounddevice 和系统 PortAudio
也可以开启无回声消除的全双工模式
此时请佩戴耳机，避免扬声器声音造成误识别：

qwenaudio tui --audio-mode full

4.5 macOS 桌面版

特点：

常驻桌面的语音悬浮球
内置和自动管理 Gateway
无需事先启动服务

首次运行：

应用会创建配置文件
引导你在设置页填写 DashScope API Key
选择后台 Agent（也可以使用仅前台模式）

外观：

流光声波球：流光声波球
液态渐变球：液态渐变球

安装：

从发布页下载 .dmg"
打开后将 Qwen Audio Agent 拖入"应用程序"

从源码生成本机测试版：

npm run desktop:build:local

4.6 后台常驻

安装为用户后台服务：

qwenaudio gateway install

常用管理命令：

qwenaudio gateway status
qwenaudio gateway restart
qwenaudio gateway stop
qwenaudio gateway start
qwenaudio gateway uninstall

五、选择后台 Agent

5.1 AGENT_PROTOCOL 配置

AGENT_PROTOCOL 是可选配置：

留空时：Gateway 以仅前台模式运行
实时语音聊天保持可用
如果请求需要后台执行，前台会明确说明当前没有可用的后台 Agent

也可以在命令行中使用：

qwenaudio --backend none

5.2 选择后台 Agent

通过 AGENT_PROTOCOL 环境变量或 --backend 参数选择后台 Agent。

OpenCode：

AGENT_PROTOCOL=opencode

OpenClaw：

AGENT_PROTOCOL=openclaw

Qoder：

AGENT_PROTOCOL=qoder

Hermes、CodeBuddy、Codex 和 Claude Code：

AGENT_PROTOCOL=hermes
# 或 codebuddy、codex、claude

使用其他支持 ACP stdio 的 Agent：

AGENT_PROTOCOL=acp
ACP_COMMAND=your-agent
ACP_ARGS=["--acp"]

通用 ACP 入口：

不需要修改 Gateway 代码
命令、参数、显示名称和工作目录可分别通过 ACP_COMMAND、ACP_ARGS、ACP_LABEL 和 ACP_WORKSPACE 配置

5.3 后台权限

后台权限默认使用 native：

由后台 Agent 在需要时询问

只有在可信项目中，并且明确接受自动执行命令和修改文件时，才应启用：

QWEN_AUDIO_AGENT_BACKEND_PERMISSION_MODE=full

详细选项见配置说明。

六、实际应用场景

6.1 编程助手

场景：

代码解释
代码生成
代码调试
代码重构

使用 Qwen Audio Agent：

qwenaudio tui

对话示例：

你：帮我解释一下这段代码

Agent：好的，我来解释一下这段代码...
      （立即回答）

你：帮我重构一下

Agent：好的，我来帮你重构这段代码。
      （后台开始重构）

你：重构得怎么样了？

Agent：已经重构好了。主要改进了...
      （任务结果自动回到当前对话）

你：为什么这样重构？

Agent：这样重构是因为...
      （继续追问）

优势：

对话不会暂停
可以随时查询进度
可以继续追问

6.2 知识问答

场景：

技术问题
百科知识
时事新闻
历史文化

使用 Qwen Audio Agent：

qwenaudio tui

对话示例：

你：Python 3.13 有什么新特性？

Agent：Python 3.13 有很多新特性，包括...
      （立即回答）

你：Node.js 22 有什么新特性？

Agent：Node.js 22 也有很多新特性，包括...
      （立即回答）

你：帮我查一下最新的 JavaScript 特性

Agent：好的，我来帮你查一下最新的 JavaScript 特性。
      （后台开始查询）

你：查得怎么样了？

Agent：已经查到了。最新的 JavaScript 特性包括...
      （任务结果自动回到当前对话）

优势：

对话不会暂停
可以随时查询进度
可以继续追问

6.3 任务管理

场景：

任务提醒
任务列表
任务进度
任务完成

使用 Qwen Audio Agent：

qwenaudio tui

对话示例：

你：提醒我下午 3 点开会

Agent：好的，我已经设置了提醒，下午 3 点开会。
      （立即设置）

你：还有什么任务？

Agent：你还有以下任务...
      （立即回答）

你：帮我整理一下本周的任务

Agent：好的，我来帮你整理一下本周的任务。
      （后台开始整理）

你：整理得怎么样了？

Agent：已经整理好了。本周的任务包括...
      （任务结果自动回到当前对话）

优势：

对话不会暂停
可以随时查询进度
可以继续追问

6.4 学习辅导

场景：

知识讲解
概念解释
答疑解惑
学习建议

使用 Qwen Audio Agent：

qwenaudio tui

对话示例：

你：什么是 React？

Agent：React 是一个用于构建用户界面的 JavaScript 库...
      （立即回答）

你：什么是 Vue？

Agent：Vue 是一个渐进式 JavaScript 框架...
      （立即回答）

你：帮我查一下 React 和 Vue 的区别

Agent：好的，我来帮你查一下 React 和 Vue 的区别。
      （后台开始查询）

你：查得怎么样了？

Agent：已经查到了。React 和 Vue 的主要区别包括...
      （任务结果自动回到当前对话）

你：我应该学哪个？

Agent：我建议你学 Vue，因为...
      （继续追问）