Installation

Requires Node.js ^22.22.2, ^24.15.0, or >=26.0.0, and npm 10+. When using the default DashScope real-time voice frontend, a DashScope API Key is also required. The repository provides .nvmrc and .node-version; when using nvm, you can simply run nvm use.

One-line Install

Install from npm (recommended):

npm install -g qwen-audio-agent

You can also install the latest code directly from GitHub:

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

Install from Source

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

Upgrade

Upgrade to the latest npm version:

npm install -g qwen-audio-agent@latest

Upgrade to the latest GitHub code:

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

After upgrading, if the Gateway is running as a background service, run qwenaudio gateway restart for the new version to take effect.

Verify Installation

View the exact location of the configuration file and confirm the installation is ready:

qwenaudio config

After configuring the backend agent, you can run a read-only check to confirm whether the backend executable, ACP integration, and adapter are ready:

qwenaudio setup

Configuration File Location

The CLI and the desktop version share ~/.config/qwaudio/config.env (settings, identity, memory, and the shared workspace live in the same user directory). Only runtime state — Gateway process, locks, logs, and skins — is kept in the desktop app's own application data directory (~/Library/Application Support/Qwen Audio Agent on macOS), so the two can run simultaneously. Set QWAUDIO_CONFIG_DIR or XDG_CONFIG_HOME to change the configuration directory. See Configuration for details.

Obtain a DashScope API Key

Alibaba Cloud Model Studio (Bailian) provides a free trial quota for Qwen Audio 3.0 Realtime. After creating an API Key, you can start using qwen-audio-agent for free.

1. Open the API Key page in the Bailian console, log in to your account, and click Create API Key.
2. Copy the generated Key and fill it into config.env later. Do not publicly share or commit your API Key.

For detailed instructions, see the official Bailian documentation.