QwenAudio/qwen-audio-agent

# Qwen Audio Agent [中文](README.md) | [English](README_EN.md) [](https://github.com/QwenAudio/qwen-audio-agent/actions/workflows/ci.yml) [](https://www.npmjs.com/package/qwen-audio-agent) [](https://nodejs.org/) [](LICENSE) ## Agent，始终在场 真正的交流，不该在说完一句话后，就陷入漫长的等待。也不该因为 Agent 正在查资料、调用工具或处理任务，整场对话就此暂停。 交流应该是连续的，Agent 也应该始终在场。 所以，我们做了 **qwen-audio-agent**——让 Agent 持续交流、持续工作、持续在场的实时语音运行时。无论是聊天、思考，还是处理任务，Agent 都始终在这场对话里。它会倾听，会回应，也会在任务完成时自然地告诉你： “已经好了。” ## News - **2026-07-30 · [v1.0.0](https://github.com/QwenAudio/qwen-audio-agent/releases/tag/v1.0.0)** 🚀 正式版发布，推出内置 Gateway 的 macOS 桌面版。 - **2026-07-28 · [v0.9.0](https://github.com/QwenAudio/qwen-audio-agent/releases/tag/v0.9.0)** 🌍 项目正式开源，后台 Agent 统一接入 ACP 架构。 ## 对话继续，任务也在继续 对话不会因为后台任务而停下；任务完成后，结果会自然回到当前对话： https://github.com/user-attachments/assets/42022655-36d1-46b2-9c26-ff0765284000 ### 核心特色 - 全双工实时语音交互、自然打断和持续多轮对话 - 一键选择你喜欢的办事 Agent，复用已有的工具、MCP、Skill - 前台对话与后台任务并驾齐驱，可随时追问任务进度或取消任务 - 支持创建多个独立任务，由后台 Agent 异步执行，并持续追踪任务状态 - 任务结果自动回到当前对话，支持继续追问和修改 - 支持 WebUI、终端 TUI 和 macOS 桌面悬浮球 - 支持本地用户档案与跨会话个人记忆 ## 参考架构  能直接回答的问题会立即回答；需要工具或持续处理时，任务会交给后台 Agent。 整个过程中，用户面对的始终是同一个助理。

查看详细架构

 更完整的设计与模块说明见[架构文档](docs/architecture.md)。

## Agent 支持 | 后台 Agent | 接入方式 | 接入准备 | 推荐指数 | | --- | --- | --- | --- | | 无 | N/A | 仅前台模式，无需配置 | ★★★★★ | | OpenCode | 原生 ACP | 支持自动安装和百炼配置 | ★★★★★ | | OpenClaw | 内置 ACP 桥接 | 支持自动安装和百炼配置 | ★★★★★ | | Qoder | 原生 ACP | 用户自行安装和配置 | ★★★★★ | | Kimi Code | 原生 ACP | 用户自行安装和配置 | ★★★★★ | | Hermes | 原生 ACP | 用户自行安装和配置 | ★★★★☆ | | CodeBuddy | 原生 ACP | 用户自行安装和配置 | ★★★★☆ | | Codex | 外部 ACP 适配 | 用户自行安装和配置 | ★★★★☆ | | Claude Code | 外部 ACP 适配 | 用户自行安装和配置 | ★★★★☆ | 推荐指数综合反映当前集成完整度、兼容性和实际验证程度：五星表示已经过充分测试的 推荐集成，四星表示正在开发或尚未完成同等范围验证。 详细配置和能力边界见[配置说明](docs/configuration.md)。 ## 安装 需要 Node.js 22.22.2+ 或 24.15.0+、npm 10+ 和 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 提供 [新人免费额度](https://help.aliyun.com/zh/model-studio/new-free-quota)，创建 API Key 后 即可免费开始使用 qwen-audio-agent。 1. 打开百炼控制台的 [API Key 页面](https://bailian.console.aliyun.com/?tab=model#/api-key)， 登录账号，单击**创建 API Key**。 2. 复制生成的 Key，稍后填入 `config.env`。请勿公开或提交 API Key。 详细说明见[百炼官方文档](https://help.aliyun.com/zh/model-studio/get-api-key)。 ## 快速开始 1. 创建配置： qwenaudio config 2. 打开命令显示的 `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 3. 在一个终端中启动 Gateway： qwenaudio 4. 另开一个终端，启动 TUI： qwenaudio tui 也可以使用浏览器界面： qwenaudio webui ### TUI 使用注意 | 平台 | 默认模式 | 打断方式 | | --- | --- | --- | | macOS | 带回声消除的全双工 | 直接说话 | | Linux / Windows | 半双工 | 播报时按 `x` | Linux 和 Windows 首次使用前需安装 `sounddevice` 和系统 PortAudio。也可以开启 无回声消除的全双工模式；此时请佩戴耳机，避免扬声器声音造成误识别： qwenaudio tui --audio-mode full ## macOS 桌面版 桌面版提供常驻桌面的语音悬浮球，并内置和自动管理 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 详细选项见 [配置说明](docs/configuration.md)。 ## 用户档案与记忆 用户数据保存在 `~/.config/qwaudio/`： - `USER.md`：称呼、所在地、偏好和常用项目 - `frontend-memory.json`：用户明确要求长期记住的信息 - `tasks.json`：任务结果和待通知状态 这些文件只保存在本机，不会写入源码仓库。可以直接编辑 `USER.md`，也可以在对话中 要求助理记住或忘记信息。 ## 使用注意事项 - 不要在用户档案或对话中保存密码、API Key、验证码和访问令牌。 - 麦克风音频与实时对话会发送到配置的 Qwen Audio Realtime 服务。 - 后台任务可能调用所选 Agent 的模型、工具、MCP 和外部服务。 - `full` 权限允许后台执行命令和修改文件，只应在可信项目中使用。 - Gateway 默认仅供本机访问；不要直接暴露到局域网或公网。 - Linux / Windows 使用无回声消除全双工时，请佩戴耳机。 详细数据边界见[隐私说明](PRIVACY.md)，网络与权限配置见 [配置说明](docs/configuration.md)。 ## 源码开发 npm install npm run build npm test npm run dev # Gateway 与 WebUI 热更新 npm run desktop # macOS 桌面悬浮球 更多构建、测试和发布说明见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 交流与分享 你可以直接在 [GitHub Issues](https://github.com/QwenAudio/qwen-audio-agent/issues) 发起讨论。 对中国用户，也可以扫描左侧二维码加入微信交流群；如果群二维码已满或过期， 扫描右侧任一维护者的个人二维码，维护者会邀请你进群。 | 微信交流群 | 个人微信 | 个人微信 | | :---: | :---: | :---: | | | | | ## 参与贡献与安全 - 开发与提交说明：[CONTRIBUTING.md](CONTRIBUTING.md) - 安全问题报告：[SECURITY.md](SECURITY.md) - 数据流向说明：[PRIVACY.md](PRIVACY.md) - 第三方组件声明：[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) ## 许可证 [Apache License 2.0](LICENSE)

标签：GNU通用公共许可证, MITM代理, Node.js, Qwen, 全双工语音, 实时语音交互, 异步任务处理, 暗色界面, 自定义脚本