xiaozhi-android-client: a Flutter client for xiaozhi-server voice agents

What xiaozhi-android-client actually solves

The project is a client, not a server. Its job is to hold the microphone, stream audio to a xiaozhi-server instance, play back the reply, and let the user interrupt mid-sentence. The README describes real-time voice interaction with interruption, text chat, multiple xiaozhi services in one chat list, and optional Dify agents that accept images. Around that core it adds the things a phone app needs: device management, role management, voiceprint recording, conversation history, and memory views.

The intended audience is narrow. You need a xiaozhi-server deployment, or the author's commercial server, before any of this is useful. The repository description points at xiaozhi-server by name, and the feature list leans on server-side capabilities such as voiceprint recognition, MQTT push, and MCP tool endpoints. A reader looking for a self-contained assistant that works against a public API will not find one here.

It is also, in practice, two products. The README splits the codebase into a V1 native line for pure Android and HarmonyOS NEXT, and a V3 Flutter line covering Android, iOS, HarmonyOS, Web, Windows, macOS and Linux. The native line is described as included with the commercial edition. The Flutter line is what the repository's Dart sources and platform folders correspond to.

Architecture: Flutter shell, server-side intelligence

The top-level layout is a standard Flutter multi-platform project: lib/ for Dart code, android/, ios/, web/, windows/, linux/, macos/ for platform runners, plus test/ and analysis_options.yaml. There is no ohos/ directory in the listing, even though the README claims HarmonyOS support and HAP compilation; the HarmonyOS artifacts shown are labelled ohos-v1, which matches the native V1 line rather than the Flutter tree. That is worth verifying before you promise a HarmonyOS build to anyone.

Transport is where the design becomes concrete. The README lists WS for WebSocket services and MQTT-UDP for MQTT long connections with server-initiated wake-up. Those are two different operating models: WebSocket assumes a live connection while the app is open, while MQTT with server push is what you need for a device that should react to a wake word without the app polling. The server feature table also mentions OTA firmware upgrade and ESP32 theme configuration, which tells you the backend is designed to serve hardware devices as well as phones. The client's claim that it can interoperate with hardware endpoints without mixing memory suggests the server keeps per-device state and the client identifies itself as a distinct endpoint.

Everything intelligent happens remotely. Speech recognition, the model call, voice cloning, long-term memory extraction and MCP tool invocation are all listed as server features. The client renders results and manages account-level objects. That split keeps the Flutter code thin, and it also means the app's behaviour changes whenever the backend changes.

Getting the Flutter client running

The README has no build section, no install commands and no configuration keys. It documents features, platform targets and contact channels, and links a Wiki at jtai.lhht.cc/wiki.html plus a demo video. What the repository does give you is the standard Flutter project skeleton: pubspec.yaml and pubspec.lock at the root, lib/ for the Dart sources, and platform folders for android, ios, web, windows, linux and macos. The README states that you can package APK, iOS, WEB, PC and HarmonyOS HAP builds yourself, without giving flags or signing steps.

Because no commands appear in the README, the honest position is that the project tells you where to get it (the releases page and the Wiki) rather than how to build it. The only build-adjacent facts available are the files present in the tree, so the first real step is reading pubspec.yaml for the SDK constraint and dependency set, then reading documents/ and lib/ for the server endpoint format, which the README never states. If you want a runnable artifact without building, the releases page is the route the README itself points to.

What you should expect after a successful launch, based on the README, is a chat list you can add multiple xiaozhi services to. Registering a server endpoint is the first real task, and the README does not document that screen, the endpoint format, or whether a server URL is entered by hand or discovered.

Where the documentation stops and the guesswork starts

The most serious limitation is that the README is a sales page. It has no installation steps, no environment variables, no configuration keys, no server URL format, and no rollback guidance. It does not say which xiaozhi-server version the client is compatible with, and it does not describe the wire protocol beyond naming WS and MQTT-UDP. If you are evaluating this for a team, budget time to read the Dart sources instead of the documentation.

The licence position is also more complicated than the badge suggests. The repository carries Apache-2.0, and the LICENSE file is at the root. But the README describes a commercial edition, a V1 native client given to buyers, custom development services, and a server product with membership billing and payment integrations. Apache-2.0 covers what is in this repository; it does not grant you the native V1 clients, the commercial server, or the hosted Wiki content. Anyone planning to ship a product on top of this should read the LICENSE file and the README together rather than assuming the badge settles the question. That is a factual observation about scope, not legal advice.

Maintenance is a mixed signal. The last push to main was on 2026-09-14, which is current. The most recent tagged release, v2.1, dates from 2025-03-31, and the two before it, v1.9.5 and v1.9, are from March 2025 as well. So the branch moves while the release tags do not. If you depend on tagged artifacts, you are depending on something roughly a year and a half older than the code you are reading.

How it compares to building on the xiaozhi protocol directly

The obvious alternative is to write your own client against xiaozhi-server. The difference is where the work sits. This project gives you a Flutter application layer: chat list, device list, role editor, voiceprint recorder, memory viewer, theme switching, Live2D model import, HTML preview and video playback. Building that yourself against the same server means reimplementing the account and device screens, which is most of the UI and almost none of the intelligence.

The second alternative is the project's own V1 native line. The README positions it for AI terminal and AI hardware products, with foldable and secondary-display adaptations, and describes it as native rather than a wrapper, with faster startup and lower power draw. The Flutter V3 line is positioned for full-platform coverage and full commercial features. If your target is a single Android device with a battery budget, the native line is the better fit on paper, and it is also the one you cannot get from this repository.

A third option is to skip the client entirely and talk to the server from a thin script. That works for testing a backend, and it is a reasonable way to verify that your xiaozhi-server is reachable before blaming the app. It gives you nothing for voice interruption, audio capture, or the account features, which is exactly the gap this project fills.

Licence, upgrade cost and what a fork inherits

Apache-2.0 is permissive: you can modify, redistribute and use the code commercially, provided you keep the licence and notices. For a Flutter client that is a comfortable position, and it means a fork is legally straightforward. The constraint is not the licence text but the dependency surface. pubspec.lock is committed, so you can see the exact dependency set, and any Flutter app of this scope carries platform plugin risk: audio capture, echo cancellation, MQTT, WebSocket and Live2D rendering all touch native code on at least some targets. The README states that echo cancellation has been implemented for Flutter iOS and Android, which is the hardest part of the audio path and also the part most likely to break on OS upgrades.

Upgrade cost is driven by the release gap. With the newest tag at v2.1 from 2025-03-31 and main pushed on 2026-09-14, tracking main means tracking unreleased changes. If you vendor this code, pin a commit rather than a tag, and expect to re-read the diff when you move forward.

There is also a support boundary to accept. The README routes questions to email, WeChat and a Wiki, and offers paid custom development. There is no issue-triage process described, no compatibility matrix, and no changelog beyond the release titles.

Who should pick this up, and what to check first

This fits a developer who already operates a xiaozhi-server, wants a cross-platform client without writing the voice loop, and is comfortable reading Dart to fill in what the README omits. It fits less well if you need a documented build pipeline, if you are targeting HarmonyOS from the Flutter tree and cannot confirm the HAP path from the repository layout, or if the native Android and HarmonyOS clients are the actual requirement, since those are tied to the commercial edition.

Before you invest, verify three things in order. First, open pubspec.yaml and documents/ and confirm which backend endpoints and protocol the client expects, because the README never states the server URL format. Second, check whether the feature you need exists on main or only in a release, given the March 2025 tags against a September 2026 branch. Third, read LICENSE alongside the README's commercial sections so you know which parts of the product you are actually allowed to redistribute.

Editorial conclusion

Adopt it if you already run a xiaozhi-server or a compatible backend and want a Flutter shell you can compile for Android, iOS, Web or desktop without writing the voice loop yourself. Do not adopt it if you need a documented, reproducible build from the README alone, or if the native Android and HarmonyOS clients are what you actually want, since those are described as a gift with the commercial edition. Before committing, read documents/ and pubspec.yaml to confirm which backend endpoints the client expects, and check whether the release you plan to ship predates the current main branch.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. TOM88812/xiaozhi-android-client on GitHub