qwen-audio-agent review: voice for Claude Code, hands-free (2026)

What you get in one minute#

Verdict: Niche. qwen-audio-agent works, but most Claude Code users should use the built-in /voice dictation; install this only for a two-way spoken conversation while Claude works.

Logo: the official QwenAudio GitHub organisation (github.com/QwenAudio)

It is a separate voice runtime, not a Claude Code plugin: you speak, hear short replies, and hand longer tasks to Claude Code. Version 2.0.1 shipped on 26 September 2026; the project is Apache-2.0 and had 3,078 stars on 30 October 2026.

What it does#

You talk to a realtime voice model. When a request needs work, the model hands the task to Claude Code, which reads and edits files in your workspace. The result comes back as speech.

The default voice frontend is qwen-audio-3.1-realtime-plus on Alibaba Cloud DashScope. Local frontends exist as an alternative, and AGENT_PROTOCOL=none runs voice only, which is how you test the voice path before adding a coding agent.

How it works in the background#

Audio to Alibaba Cloud, work to Claude Code, result back to the talk.

Three parts do the work. The frontend agent is the voice model. The orchestration runtime owns tasks, permissions, sessions, and result delivery. The backend agent is Claude Code, reached through the Agent Client Protocol (ACP). The Gateway hosts the runtime and listens on 127.0.0.1:3101 by default.

The voice model calls spawn_thinking when work is needed. The runtime acknowledges and runs the task in the background, so the conversation does not block. The ACP adapter starts Claude Code as a subprocess. Your microphone audio and voice context go to Alibaba Cloud by default; Claude Code keeps its own login and tools.

Under the hood: the dissection#

qwen-audio-agent/
├── cli/bin/qwenaudio.mjs          # the qwenaudio command
├── cli/src/
│   ├── config-command.mjs         # prints and writes config.env
│   ├── launcher.mjs               # starts the Gateway and clients
│   └── gateway-service.mjs        # background service
├── server/src/
│   ├── index.mjs                  # Gateway entry
│   ├── voice/                     # realtime provider and sessions
│   ├── orchestration/             # tasks, permissions, results
│   ├── backend/                   # ACP/A2A adapters
│   └── transport/                 # client WebSocket
├── tui/  web/  desktop/  mobile/  # clients
└── config/                        # templates

What users say#

Complaints dominate the 16 reports; issue trackers attract complaints, not a satisfaction rate.

We read 16 reports: 14 GitHub issues and two guides. Twelve lean negative, two are mixed, one is positive, one is neutral. That is not a satisfaction rate; issue trackers collect complaints.

The positive one is a blog review from August 2026. It gives 4/5 and praises the install and background tasks. It calls the Gateway local-only with no authentication, which the privacy document contradicts: pairing, device tokens, Tailscale, and HTTPS are documented.

In the mixed #563, a production user on a phone line ran the 3.1 voice model with a local patch for a week and asked for support; the issue was closed. The Better Stack guide likes the architecture but warns about paid DashScope and documentation gaps. It repeats claims the docs do not support, so we used only its general caveats.

Complaints cluster around frontends and plumbing. #560: Google Live never connects. #557: StepFun cannot reconnect with history. #549 matters most: a task result was announced in another session; it was closed after a fix. Others cover missing voice cloning, discarded usage accounting, and a desktop setting that overwrote AGENT_PROTOCOL.

The gap for this review: none of the 16 reports is about the Claude Code adapter. A GitHub search found two issues mentioning "claude", both opened by the maintainer. The project rates Claude Code 4/5. The exact setup this page reviews has no independent user evidence yet.

Pros: what is genuinely good#

• Two-way voice, not just dictation. You hear the answer, and on macOS you can interrupt it.
• Background work with a spoken result. The conversation continues while Claude Code runs.
• It reuses your Claude Code setup. Login, tools, MCP servers, and skills stay in Claude Code.
• Open source and active. Apache-2.0, created in July 2026, with fixes shipping.

Cons: what to weigh first#

• The Claude Code path is unverified in public. The 4/5 rating is the project's own; no user report was found.
• Audio is paid and metered. Billed per token, Claude usage separate, and no per-session estimate. Audio is $6.40 in and $24 out per 1M tokens (Singapore).
• Audio leaves your machine by default. It goes to Alibaba Cloud DashScope. The privacy document is in Chinese.
• It overlaps with a free built-in. /voice dictation uses no Claude tokens with a claude.ai account.
• Full-duplex is macOS-only. Linux and Windows TUI are half-duplex; the echo-cancelling helper is a macOS build.

Should you consider it? When it is useful#

Dictation first; install only for spoken replies and paid cloud audio.

Use it only for two-way voice with Claude Code, ideally on macOS (full-duplex), with paid cloud audio.

If you only need to speak prompts, use /voice. If audio must stay local, test the unverified local frontends on a spare machine. On Linux or Windows, expect half-duplex.

Install and check it#

Desktop installers include the Gateway; Linux builds from source. The CLI needs Node ^22.22.2, ^24.15.0, or >=26.0.0, and npm 10+.

Linux#

1. Check node --version and npm --version; install a supported Node release if needed.
2. npm install -g qwen-audio-agent
3. qwenaudio config prints the path, normally ~/.config/qwaudio/config.env.
4. Add these lines, starting with AGENT_PROTOCOL=none to test voice first:

QWEN_AUDIO_REALTIME_PROVIDER=dashscope
QWEN_AUDIO_REALTIME_API_KEY=<YOUR_DASHSCOPE_KEY>
QWEN_AUDIO_REALTIME_MODEL=qwen-audio-3.1-realtime-plus
AGENT_PROTOCOL=none

5. Run qwenaudio, then qwenaudio webui in a second terminal; allow the microphone and say hello. For the TUI: python -m pip install sounddevice, then qwenaudio tui.
6. Install and sign in to Claude Code separately; add the adapter from the desktop Backend Agent screen, or let the CLI fetch it through npx when missing. Set AGENT_PROTOCOL=claude and restart.

Tip: Run qwenaudio --version and qwenaudio doctor before blaming the voice model. They separate a broken install from a provider problem.

Windows (PowerShell)#

1. Check node --version and npm --version; the same minimums apply.
2. npm install -g qwen-audio-agent, then qwenaudio --version.
3. qwenaudio config, edit config.env with the four lines above, and start with AGENT_PROTOCOL=none.
4. Run qwenaudio, then qwenaudio webui in a second window. The TUI needs Python and sounddevice; it is half-duplex. The .exe includes the Gateway.
5. Install and sign in to Claude Code, add the adapter, set AGENT_PROTOCOL=claude, restart.

Tip: If you only want the desktop app, skip npm. The .exe already contains the Gateway.

Mac (Terminal)#

1. For full-duplex TUI voice: xcode-select --install. The helper is built into ~/Library/Caches/qwaudio/tui/macos-voice-io.
2. Check Node and npm, then npm install -g qwen-audio-agent, then qwenaudio config and edit config.env.
3. Run qwenaudio, then qwenaudio webui or qwenaudio tui; allow the microphone and say hello.
4. Install and sign in to Claude Code, add the adapter, set AGENT_PROTOCOL=claude, restart. The .dmg includes the Gateway and supports full-duplex.

Tip: Leave QWEN_AUDIO_AGENT_BACKEND_MODEL empty unless you need a specific model; Claude Code then uses its own.

Check it worked#

Run qwenaudio --version, qwenaudio doctor, and qwenaudio setup. Start the Gateway and one client; both should show connected. Say hello, then ask for a small task in a test folder. The transcript should appear and the result should be spoken.

doctor and setup check components, not credentials.

Things to keep in mind#

• Permissions. native asks for approval; full auto-approves and belongs only in trusted projects.
• Privacy. Audio and voice context go to Alibaba Cloud by default; work context goes to Claude. Logs stay under ~/.config/qwaudio.
• Remote access. Keep the Gateway on localhost. --lan is unencrypted; use Tailscale or an HTTPS reverse proxy, and revoke leaked pairing links.
• Updates. npm install -g qwen-audio-agent@latest updates the CLI. The adapter defaults to 0.93.0; newer Claude Code versions may need an update.

Common mistakes#

Tip: If voice works but Claude does not, set AGENT_PROTOCOL=none to confirm the voice path, then switch to claude and restart.

Troubleshooting#

FAQ#

Is this a Claude Code plugin? No. It is a separate Node runtime that reaches Claude Code through an ACP adapter.

Does Claude Code already have voice? Yes, for dictation. /voice turns speech into prompt text and costs no Claude tokens, but it does not read replies aloud.

Does my audio go to the cloud? By default, yes: audio goes to Alibaba Cloud DashScope. Local frontends are unverified here.

How much does a session cost? No estimate is published. Audio is billed per token ($6.40 in, $24 out per 1M), and Claude usage follows your plan or API billing.

Sources#

• npm package: https://registry.npmjs.org/qwen-audio-agent/latest
• Repository: https://github.com/QwenAudio/qwen-audio-agent
• Releases: https://github.com/QwenAudio/qwen-audio-agent/releases/tag/v2.0.1 and https://github.com/QwenAudio/qwen-audio-agent/releases/tag/v2.0.0
• Quickstart: https://qwenaudio.github.io/qwen-audio-agent/getting-started/quickstart
• Install: https://qwenaudio.github.io/qwen-audio-agent/getting-started/install
• Backends: https://qwenaudio.github.io/qwen-audio-agent/backends/overview
• Claude Code backend: https://qwenaudio.github.io/qwen-audio-agent/backends/configuration#claude-code
• Architecture: https://qwenaudio.github.io/qwen-audio-agent/architecture/overview
• Gateway: https://qwenaudio.github.io/qwen-audio-agent/operations/gateway
• Troubleshooting: https://qwenaudio.github.io/qwen-audio-agent/operations/troubleshooting
• TUI: https://qwenaudio.github.io/qwen-audio-agent/getting-started/tui
• CLI: https://qwenaudio.github.io/qwen-audio-agent/reference/cli
• Privacy: https://github.com/QwenAudio/qwen-audio-agent/blob/main/PRIVACY.md
• Pricing: https://www.alibabacloud.com/help/en/model-studio/qwen-audio-3-1-realtime-plus
• Claude Code /voice: https://code.claude.com/docs/en/voice-dictation
• ACP: https://agentclientprotocol.com/protocol/overview
• Adapter: https://github.com/agentclientprotocol/claude-agent-acp
• Blog review: https://aiblog.jasonead.com/blog/2026/08/08/qwen-audio-agent-runtime-voice-ai-agents/
• Better Stack: https://betterstack.com/community/guides/ai/qwen-audio-agent/
• Issues: #580, #563, #560, #557, #550, #549, #532, #530, #475, #474, #436, #431, #334, #333

Checked against the official docs on 2026-10-30. The tool was not installed by DIY Lab Hub; commands come from the official docs, and no output was invented.