# Desktop

The desktop app provides a persistent on-screen voice orb and includes a built-in Gateway, eliminating the need to start a service beforehand. If a local Gateway already exists in the same user configuration directory, it will connect directly and use the Gateway's current runtime configuration; otherwise, the desktop app will start and manage it automatically. On first run, the app creates a configuration file and guides you to fill in the DashScope API Key on the settings page and select a backend agent (frontend-only mode is also available).

## Backend Agent Connection

The app manages the selected backend Agent by default. For Agents that expose
an external-service capability, the Backend Agent settings also allow connecting
to an existing service by address and optional access token. OpenClaw currently
supports this mode; Agents without that capability continue to use their managed
ACP process and do not show irrelevant connection fields.

## Orb and Auto Sleep

When idle, the orb automatically hides and disconnects real-time voice; you can also say "可以退下了" (you may step down) to hide it. The app remains in the menu bar and can be re-summoned from the menu bar or via a show shortcut. The default shortcut is `⇧⌘ Space` and can be changed in app settings.

The sleep timeout and auto-hide are unified into a single "Auto Sleep" setting: during sleep, the microphone continues local listening, and saying the wake word "你好千问" (hello Qianwen) will resume the conversation. Backend agents and submitted tasks are not stopped by sleep; task results will be announced after wake-up. When the wake word is enabled for the first time, it automatically downloads and validates approximately 33 MB of the [`sherpa-onnx`](https://github.com/k2-fsa/sherpa-onnx) Chinese-English KWS model, and uses the local cache thereafter.

## Appearance

The desktop app supports two appearance styles: the Aurora Soundwave Orb and the Liquid Gradient Orb. The following shows their raw animations in the thinking / breathing state:

| Aurora Soundwave Orb | Liquid Gradient Orb |
| --- | --- |
| ![Aurora Soundwave Orb thinking animation](../desktop-fluid-orb-thinking.gif) | ![Liquid Gradient Orb thinking animation](../desktop-goo-orb-thinking.gif) |

## Skins

Beyond the built-in appearances, the orb supports sprite skins in the
[Codex pet](https://github.com/legeling/awesome-codex-pet) package format:
a directory containing `pet.json` and `spritesheet.webp` (8-column grid,
v1 is 1536x1872 with 9 rows, v2 is 1536x2288 with 11 rows). Assets from the
Codex pet ecosystem work without any conversion, and no Codex installation
is required.

Generated skins may use the optional `animations.frames/fps` extension to
describe each standard action's effective frames and speed. See the
[desktop pet skin protocol](./pet-skin-spec.md).

To import a skin you already downloaded, open "Settings → Application →
Appearance", click "Import Skin…", and select the skin folder, its
`pet.json`, or a zip archive. Imported skins are stored under `skins/` in
the desktop data directory and appear in the appearance dropdown alongside
the built-in styles. Selecting an imported skin enables the "Delete"
button next to it; built-in appearances cannot be deleted.

The desktop does not flatten every business signal into one "Agent state".
Lifecycle, runtime readiness, voice interaction, and background work remain
separate; skins consume only stable presentation states and one-shot events.

| System semantics | Skin action | Playback |
| --- | --- | --- |
| Idle | `idle` | Loop continuously |
| Confirmed user speech | `waiting` | Play once, then restore the base action |
| Input committed, awaiting the first response | `review` | Play once; this does not claim access to model-internal "thinking" |
| Playback starts | `waving` | Play once, with subtle playback motion retained |
| Background work active | `running` | Loop as the base action |
| Application starting | `waiting` | Loop continuously |
| First readiness or wake | `waving` | Play once |
| Runtime or task failure | `failed` | Play once |
| Pointer hover | `jumping` | Play once |
| Left/right drag | `running-left` / `running-right` | Loop while dragging |

Permission waits, ownership by another frontend, and detailed connection
phases remain useful business states, but do not select separate sprite
tracks. A transient action restores idle, or running when background work is
still active. Front-end-only mode skips backend readiness.
Skin packages are static assets only (JSON + WebP) and are validated on
import; if a selected skin package is removed, the orb falls back to the
built-in appearance.

## Installation

Download the installer for your platform from the releases page:

- **macOS**: Download the `.dmg`, open it, and drag **Qwen Audio Agent** into "Applications".
- **Windows**: Download the `.exe` installer, double-click to run, and follow the wizard to complete installation.

To build a local test version from source:

```bash
npm run desktop:build:local      # macOS
npm run desktop:build:win        # Windows
npm run desktop:build:linux      # Linux (AppImage + deb, no signing required)
```

The output is located in `dist/desktop/`.

## Data Directory and Isolation

The desktop app uses the standard system application data directory (`~/Library/Application Support/Qwen Audio Agent` on macOS, `%APPDATA%/Qwen Audio Agent` on Windows, and `~/.config/Qwen Audio Agent` on Linux), which is completely isolated from the CLI's `~/.config/qwaudio`. The Gateway, locks, logs, and settings of the two do not interfere with each other and can run simultaneously. On first launch, the desktop app copies `config.env` and other user configurations from the CLI directory (the CLI retains the originals).

## Auto Update and Logs

The settings page displays the current version and allows manual update checks. When a new version is found, the background downloads a delta update, and once complete, a one-click restart installs it.

The desktop app can open the log directory from "Settings → Application → Logs". Along with the Gateway, it records structured JSONL logs with automatic credential redaction and log rotation. For log configuration details, see
[Configuration Guide](../configuration.md#本地日志).