---
title: How to Set Up Qwen Audio Agent With Claude Code for Voice
url: "https://goremy.ai/blog/articles/qwen-audio-agent-claude-code-voice-setup"
author: Luis Chavez-Mattos
editor: Luis Chavez-Mattos
editor_title: Director, Product
published: "2026-10-30T07:00:09.239Z"
updated: "2026-10-30T07:00:09.239Z"
topic: AI Coding Tools
description: "Set up the open-source Qwen Audio Agent with Claude Code over ACP: install, config, voice-built app tests, interruptions, task cancellation and cost notes."
---

# How to Set Up Qwen Audio Agent With Claude Code for Voice

> Set up the open-source Qwen Audio Agent with Claude Code over ACP: install, config, voice-built app tests, interruptions, task cancellation and cost notes.

Edited by Luis Chavez-Mattos, Director, Product · Published 2026-10-30

## What is Qwen Audio Agent and how does it work with Claude Code?

Qwen Audio Agent is an open-source app that connects a voice conversation to agents that do work on your computer. A realtime voice model handles the talking. Claude Code handles the coding. A local gateway sits between them and returns task results to the conversation, so you can ask questions or change requirements by voice while Claude builds in the background. Claude connects through an Agent Client Protocol (ACP) adapter that the project installs for you.

## TL;DR

- The setup has **two separate model connections**: a cloud realtime voice model (via DashScope) and Claude Code as the coding back end.
- Install version 2.0.1 with npm on a supported Node 24 release (the walkthrough uses 24.15 or later, with npm 10+), then run the config, install and setup commands in order.
- Confirm Claude Code works on its own first, because the setup command **checks components but does not prove you have quota**.
- Set the workspace path explicitly. **Opening a terminal in a folder does not make it the agent's workspace.**
- Interrupting a spoken reply does not cancel a back-end task. **Stopping the voice and stopping the coding agent are different actions.**
- Both sides bill you: the voice provider and your Claude account. Open source does not make hosted model calls free.

## What do you need before installing?

You need four things:

1. Node 24 series, starting at 24.15, with npm 10 or newer. Check with `node --version` and `npm --version`.
2. A DashScope API key from the provider's console. Keep it out of screen recordings and repos.
3. A working Claude Code install, signed in or configured with the API access you normally use.
4. A browser with microphone access. Headphones help, because the mic otherwise picks up the assistant's own voice.

A desktop installer also exists. It bundles its own runtime and adds a floating voice orb. There is a terminal interface too. This guide sticks to the command line and browser client, since the browser shows the transcript and background tasks side by side.

## How do you install and configure Qwen Audio Agent?

Install the pinned version globally:

```
npm install -g qwen-audio-agent@2.0.1
```

Then ask the tool where its config lives:

```
qwen-audio config
```

One caveat: the exact binary name comes from a spoken walkthrough, so confirm it against the package README after installing. The default config file sits in your home directory under `.config`, in a folder named for the tool, as `config.env`.

In that file, set:

- **DashScope API key**: the key you created in the provider's console.
- **Realtime provider**: DashScope, using the Qwen audio 3.0 realtime plus model listed in the project's configuration. This is the voice model only.

The voice model is separate from the coding model. You choose Claude as the back end in the next step.

## How do you connect Claude Code through ACP?

Run the install step, which checks for Claude components and installs whatever is missing, including the ACP adapter. If Claude Code is already on your machine, it reuses that installation.

```
qwen-audio install claude
```

Before going further, open Claude on its own:

```
claude
```

Finish sign-in and send one small request. Debugging a quota or auth problem through a voice interface is miserable, so prove Claude works first. Then exit and run the integration check:

```
qwen-audio setup --backend claude
```

This verifies the integration pieces. It says nothing about whether your account can actually run tasks.

Back in `config.env`, set:

| Setting | Value |
|---|---|
| Agent protocol | `claude` |
| Backend model | Empty, to use Claude's existing model configuration |
| Backend permission mode | `native`, so Claude's normal permission behavior applies |
| Workspace | Absolute path to a dedicated project folder |

Create that folder first. The demo uses one called `voice-code-demo`. Check the path carefully. The app has its own default workspace, and a Claude-specific workspace setting can override the general one. A mismatch means Claude edits the wrong directory.

One more expectation to set: this opens a new agent workflow. It will not take over a Claude terminal session you already have running.

## How do you start the gateway and web UI?

Start the gateway in one terminal and leave it running:

```
qwen-audio
```

In a second terminal, launch the browser client:

```
qwen-audio web
```

The default local address ends in port 3101. Allow microphone access, enable the mic input, and confirm that both the gateway and the voice connection show as connected.

## How do you test that the voice link and the back end both work?

Test in layers, cheapest first.

**Voice check.** Say something like "Please speak English. Keep your answer short and tell me that you can hear me." Read the transcript as well as the reply. If the transcript is wrong, Claude will later receive the wrong request. If you see text but hear nothing, look at your output device and browser audio before touching the back end.

**Back-end check.** Ask it to inspect the configured project folder, report its absolute path, and list files without changing anything. That should create a real back-end task. Open the task details and compare the reported path with the folder you chose.

## What happens when you build an app by voice?

The demonstrated project is a small issue tracker called Voice Desk. The spec: plain HTML, CSS and JavaScript, a dark theme, an issue list, a new issue button, add and complete actions, a completed filter, local storage persistence, basic validation, and instructions for running it locally. Keeping it small matters. In a giant app you could not tell whether a spoken correction landed in the right place.

If Claude raises a permission request, read the operation before approving. In this app, allowing a task can also allow later operations within that task. A disposable project keeps that scope easy to reason about.

Once the build is running, ask a side question, such as what local storage does here and whether a refresh should delete issues. The assistant should answer while the task card shows the build still active. This does not make Claude code faster. It gives you useful time while it works.

## Can you interrupt, change requirements and cancel tasks?

Yes, but each action does something different.

- **Interrupting speech.** Saying "Make that shorter, please" should stop the old audio and produce a shorter answer. It does not cancel a task the back end already accepted. That is useful when you want the explanation to stop but the work to continue.
- **Changing a requirement mid-build.** The demo asks for a light theme and a button renamed to "create issue." The front end can accept this while the task runs, but it may become follow-up work instead of changing the current turn. Watch the task state and the final files. A spoken "got it" is not proof the file changed.
- **Cancelling.** The demo uses a read-only accessibility review for this test. Ask to cancel it, naming the task by its card if several are active. A cancel request and a completed cancellation are separate events. If the task finishes first, you have not tested cancellation. Cancelling also does not undo edits already made, so check the diff after stopping any editing task.
- **Muting or closing.** Muting the mic or ending the conversation is a different action again. Background work can keep going. Use the task cancellation control when you mean stop the work.

## How should you verify the result and report bugs?

Do not trust the completion message. Open the app and test it: add "fix the mobile menu" and "update the help page," mark one complete, toggle the filter, then refresh and confirm storage persisted. Check the light theme and the renamed button.

For a bug report, give Claude an observable condition. The demo checks whether a title containing only spaces gets rejected, and asks Claude to explain how the current code handles it, add a regression check, and fix it only if it fails, while preserving normal titles and saved issues. That beats asking it to rewrite the form because something looks off.

While it works, you can ask the voice front end a general question, such as why checking raw text length can let a spaces-only title through. Treat that as a general explanation. Only the code and the test output tell you what this app does.

Voice suits describing a problem you are looking at. Use text for exact error messages, file paths and code, and ask for launch commands as copyable text instead of listening to them read aloud.

## How much does it cost?

The source gives no prices, so check current ones yourself. What it does say is structural:

- The DashScope voice front end bills for the conversation, with pricing depending on model and region.
- Claude Code bills through its configured account or API for the coding work.
- Extra follow-up tasks add more back-end usage.

To compare costs fairly, record both sides of the same session. Asking the assistant to put detailed results in text and speak only a short summary cuts voice usage. Local voice front ends exist, but they need their own model and hardware, and a local voice layer does not make a cloud Claude back end local.

## Frequently Asked Questions

### Does Qwen Audio Agent take over my existing Claude Code session?

No. It starts a new agent workflow through the ACP adapter. Your separate Claude terminal conversation stays its own thing.

### Why did Claude edit the wrong folder?

The workspace setting probably points somewhere else. Your terminal's current directory does not set it, and a Claude-specific workspace value can override the general one. Check the configured absolute path and verify it with the list-files test.

### Does interrupting the assistant stop the coding task?

No. Interrupting only cuts off the spoken reply. To stop accepted back-end work, use the task cancellation control and confirm the state changed to cancelled.

### Is it free because it is open source?

The software is open source, but the voice connection uses a DashScope API account and Claude Code uses your own Claude access. Both can incur charges.

### What should I check if the transcript looks wrong?

Fix that before anything else. A bad transcript means Claude receives a bad instruction. Try headphones to stop echo, and check your mic input. If you hear nothing despite seeing text, look at the output device and browser audio.