Quickstart

Complete one conversation first, then add a backend, tools, or remote access. Desktop does not require a CLI installation.

How you want to use it	Next step
Desktop app	Download and open Desktop, then configure it in Settings.
Terminal or browser	Start a Gateway below, then connect TUI or WebUI.
Phone or another computer	Start a Gateway on a computer or server, then generate a connection code.
Custom client or adapter	Read the extension overview.

Command-line quickstart

If not yet installed, see Install & Update.

1. Create configuration

qwenaudio config

Open the reported config.env file. Its default location is ~/.config/qwaudio/config.env.

2. Add credentials

Start in frontend-only mode to verify voice conversation:

QWEN_AUDIO_REALTIME_PROVIDER=dashscope
DASHSCOPE_API_KEY=your-key
QWEN_AUDIO_REALTIME_MODEL=qwen-audio-3.0-realtime-plus
AGENT_PROTOCOL=none

Get a DashScope API Key. For another cloud or local service, replace these settings using the voice frontend guide.

3. Start the Gateway

qwenaudio

Keep this terminal running. In another terminal, open the browser client:

qwenaudio webui

Or use the terminal client:

qwenaudio tui

See the TUI guide for audio dependencies and platform differences.

Verify the first conversation

1. Confirm that the client shows the Gateway and voice frontend as connected.
2. Allow microphone access, enable input, and say “Hello.”
3. Check that you see a transcript and hear a reply.

For missing audio or connection failures, see Troubleshooting. Each user has one active client per Gateway; taking over from a new client disconnects the previous one.

Add a Backend Agent

A backend operates the computer, writes code, and performs other work. Install and configure a supported backend, such as Qwen Code, then change:

AGENT_PROTOCOL=qwen
QWEN_AUDIO_AGENT_BACKEND_MODEL=

Leave the backend model empty to use the Agent's configuration. Stop and restart the Gateway, then ask “Check this computer's memory capacity” and inspect the work card and result.

Without an existing backend, you can use managed OpenCode / OpenClaw initialization. An unset AGENT_PROTOCOL or AGENT_PROTOCOL=none does not start a backend; chat and enabled frontend tools still work. Use qwenaudio --backend none for a temporary override.

Next steps

• How It Fits Together: clients, Gateway, frontend, and backend.
• Conversation & Attachments: text, speech, images, and files.
• Work & Permissions: status, follow-ups, cancellation, and approval.
• Run the Gateway: exit, restart, and background services.