Qwen Audio Agent

中文 | English

Agent，始终在场

真正的交流，不该在说完一句话后，就陷入漫长的等待。也不该因为 Agent 正在查资料、调用工具或处理任务，整场对话就此暂停。

交流应该是连续的，Agent 也应该始终在场。

所以，我们做了 qwen-audio-agent——让 Agent 持续交流、持续工作、持续在场的实时语音运行时。无论是聊天、思考，还是处理任务，Agent 都始终在这场对话里。它会倾听，会回应，也会在任务完成时自然地告诉你：

“已经好了。”

News

• 2026-08-03 · v1.3.0 🎙️ 新增 🤗 speech-to-speech 前台接入，支持本地部署 VAD、STT、LLM 与 TTS 全链路。
• 2026-08-01 · v1.2.0 ⚡ 桌面版新增自动更新，优化启动速度与后台 Agent 检测。
• 2026-07-31 · v1.1.0 🤝 新增 Kimi Code CLI 后台，原生 ACP 接入。
• 2026-07-30 · v1.0.0 🚀 正式版发布，推出内置 Gateway 的 macOS 桌面版。
• 2026-07-28 · v0.9.0 🌍 项目正式开源，后台 Agent 统一接入 ACP 架构。

对话继续，任务也在继续

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

https://github.com/user-attachments/assets/42022655-36d1-46b2-9c26-ff0765284000

核心特色

• 全双工实时语音交互、自然打断和持续多轮对话
• 一键选择你喜欢的办事 Agent，复用已有的工具、MCP、Skill
• 前台对话与后台任务并驾齐驱，可随时追问任务进度或取消任务
• 支持创建多个独立任务，由后台 Agent 异步执行，并持续追踪任务状态
• 任务结果自动回到当前对话，支持继续追问和修改
• 支持 WebUI、终端 TUI 和 macOS 桌面悬浮球
• 支持本地用户档案与跨会话个人记忆

参考架构

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

更完整的设计与模块说明见架构文档。

Agent 支持

推荐指数综合反映当前集成完整度、兼容性和实际验证程度：五星表示已经过充分测试的 推荐集成，四星表示正在开发或尚未完成同等范围验证。 详细配置和能力边界见配置说明。

安装

需要 Node.js 22.22.2+ 或 24.15.0+、npm 10+。使用默认的 DashScope 实时语音前台时，还需要 DashScope API Key。 仓库提供 .nvmrc 和 .node-version；使用 nvm 时可直接运行 nvm use。

一键安装（推荐，从 npm 安装）：

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

获取 DashScope API Key

阿里云百炼为 Qwen Audio 3.0 Realtime 提供 新人免费额度，创建 API Key 后 即可免费开始使用 qwen-audio-agent。

1. 打开百炼控制台的 API Key 页面， 登录账号，单击创建 API Key。
2. 复制生成的 Key，稍后填入 config.env。请勿公开或提交 API Key。

详细说明见百炼官方文档。

快速开始

1. 创建配置：

qwenaudio config

1. 打开命令显示的 config.env，填写 DashScope API Key。需要执行后台任务时， 再选择 OpenClaw 或其他后台 Agent：

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

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

qwenaudio

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

qwenaudio tui

也可以使用浏览器界面：

qwenaudio webui

使用 Hugging Face speech-to-speech 前台

qwen-audio-agent 也可以连接用户自行运行的 Hugging Face speech-to-speech。 它将 VAD、STT、LLM 和 TTS 组合成 OpenAI Realtime 兼容服务，整条语音链路既可以 完全运行在本地，也可以按需替换其中的模型或服务。

1. 安装 speech-to-speech：

pip install "speech-to-speech[paraformer]"

1. 启动全本地服务：

Linux / Windows（NVIDIA GPU）：

speech-to-speech \
  --stt paraformer \
  --llm_backend transformers \
  --device cuda

Apple Silicon：

speech-to-speech \
  --stt paraformer \
  --llm_backend mlx-lm \
  --device mps

没有 NVIDIA GPU 时，也可以选择适合 CPU 的更小本地模型；还可以 将 LLM 指向本机运行的 vLLM / llama.cpp。服务默认运行在 ws://127.0.0.1:8765/v1/realtime。

1. 在 qwen-audio-agent 的 config.env 中设置：

QWEN_AUDIO_REALTIME_PROVIDER=speech-to-speech
SPEECH_TO_SPEECH_REALTIME_URL=ws://127.0.0.1:8765/v1/realtime

然后正常启动 qwenaudio。在全本地模式下无需云端 API Key。Gateway 只连接 Realtime 接口，不会修改 speech-to-speech 的 STT、LLM、TTS 或音色配置。 如果 Realtime 接口位于需要 Bearer 认证的代理后方，可设置 SPEECH_TO_SPEECH_AUTH_TOKEN。

TUI 使用注意

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

qwenaudio tui --audio-mode full

macOS 桌面版

桌面版提供常驻桌面的语音悬浮球，并内置 Gateway，无需事先启动服务。同一用户配置 目录已有兼容的本地 Gateway 时会直接复用，否则由桌面版自动启动和管理。首次运行时， 应用会创建配置文件，并引导你在设置页填写 DashScope API Key、选择后台 Agent （也可以使用仅前台模式）。

桌面版支持流光声波球和液态渐变球两种外观。下面分别展示它们在思考 / 呼吸状态 下的原始动态效果：

从发布页下载 .dmg，打开后将 Qwen Audio Agent 拖入“应用程序”即可。

从源码生成本机测试版：

npm run desktop:build:local

后台常驻

希望个人助理长期在线时，可以安装为用户后台服务：

qwenaudio gateway install

常用管理命令：

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

选择后台 Agent

AGENT_PROTOCOL 是可选配置。留空时，Gateway 以仅前台模式运行，实时语音聊天 保持可用；如果请求需要后台执行，前台会明确说明当前没有可用的后台 Agent。 也可以在命令行中使用 qwenaudio --backend none，明确要求仅启动前台模式。

通过 AGENT_PROTOCOL 环境变量或 --backend 参数选择后台 Agent。选择后， OpenCode 和 OpenClaw 支持自动下载安装；配置 DASHSCOPE_API_KEY 和 QWEN_AUDIO_AGENT_BACKEND_MODEL 后即可自动接入百炼 模型。未指定后台模型且用户已经安装并配置对应 Agent 时，则完整复用用户环境。

查看当前可用的后台 Agent：

qwenaudio setup

使用 OpenClaw：

AGENT_PROTOCOL=openclaw

使用 OpenCode：

AGENT_PROTOCOL=opencode

使用 Qoder：

AGENT_PROTOCOL=qoder

后台 Agent 需要用户自行安装并完成原生配置；qwen-audio-agent 会复用其 用户级模型、工具、MCP、Skill 和认证。

其中部分 Agent 通过外部 ACP 适配器接入，除本体外，还需要全局安装对应的适配器。 以 Codex 为例：

npm install -g @agentclientprotocol/codex-acp

CLI 模式缺少适配器时会尝试通过 npx 按需启动；桌面版为保证启动可靠，仅使用已安装的 组件，请提前安装。

使用其他支持 ACP stdio 的 Agent：

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

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

后台权限默认使用 native，由后台 Agent 在需要时询问。只有在可信项目中，并且 明确接受自动执行命令和修改文件时，才应启用：

QWEN_AUDIO_AGENT_BACKEND_PERMISSION_MODE=full

详细选项见 配置说明。

用户档案与记忆

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

• USER.md：称呼、所在地、偏好和常用项目
• frontend-memory.json：用户明确要求长期记住的信息
• tasks.json：任务结果和待通知状态
• logs/：经过凭据脱敏并自动轮转的本地运行日志

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

使用注意事项

• 不要在用户档案或对话中保存密码、API Key、验证码和访问令牌。
• 麦克风音频与实时对话会发送到配置的 Realtime 前台服务（DashScope 或 speech-to-speech）。
• 后台任务可能调用所选 Agent 的模型、工具、MCP 和外部服务。
• full 权限允许后台执行命令和修改文件，只应在可信项目中使用。
• Gateway 默认仅供本机访问；不要直接暴露到局域网或公网。
• Linux / Windows 使用无回声消除全双工时，请佩戴耳机。

详细数据边界见隐私说明，网络与权限配置见 配置说明。

源码开发

npm install
npm run build
npm test

npm run dev       # Gateway 与 WebUI 热更新
npm run desktop   # macOS 桌面悬浮球

更多构建、测试和发布说明见 CONTRIBUTING.md。

交流与分享

你可以直接在 GitHub Issues 发起讨论。

对中国用户，也可以扫描左侧二维码加入微信交流群；如果群二维码已满或过期， 扫描右侧任一维护者的个人二维码，维护者会邀请你进群。

参与贡献与安全

• 开发与提交说明：CONTRIBUTING.md
• 安全问题报告：SECURITY.md
• 数据流向说明：PRIVACY.md
• 第三方组件声明：THIRD_PARTY_NOTICES.md

许可证

Apache License 2.0