XiaoZhi AI Chatbot Documentation Center | XiaoZhi.Dev
Usage Guide
XiaoZhi AI Frequently Asked Questions

XiaoZhi AI Frequently Asked Questions

For simplicity, “XiaoZhi AI terminal” below means the XiaoZhi AI chatbot. Apart from questions about ESP32-S3-WROOM-1 series boards, most answers refer to the breadboard build; other vendors’ kits and custom builds are not covered here. Firmware answers are checked against upstream 78/xiaozhi-esp32 v2.5.2. For anything about the management console, follow what the official console actually shows.

Getting Started

Q0: What are the steps to build a XiaoZhi AI robot?

A: Using a breadboard, Dupont wires, or wires you solder yourself, there are 5 steps:

  1. Buy the parts and modules: follow the list. See Hardware Build Guide (Parts List and Wiring).
  2. Wire the hardware: pick the wiring diagram or connection table that matches your board (44-pin or 42-pin), and connect the wires by the printed letters and numbers.
  3. Download and flash the firmware:
    • Firmware files are named like v2.5.2_<variant>.zip; GitHub Releases is the reference. Find the variant name in Supported Boards.
    • Breadboard Wi-Fi build: bread-compact-wifi (0.91-inch 128×32 OLED). For a 128×64 screen choose bread-compact-wifi-128x64.
    • Breadboard ML307 4G build (optional): bread-compact-ml307 (bread-compact-ml307-128x64 for a 128×64 screen).
    • Flashing tools and firmware download: Firmware Download
  4. Get the device online:
    • ESP32-S3 boards support Wi-Fi by default. Configure the Wi-Fi where you use it, or a phone hotspot (2.4 GHz only; networks that need a second login step are not supported). See the Network Configuration Guide.
    • The ML307R-4G build only needs a SIM card / data card (IoT card).
  5. Register the device: once online, the device shows and reads out an activation code; enter it in the console to bind the device. See First Boot. Then say “你好小智” to start using it.

Notes:

  • The Wi-Fi setup in steps 3 and 4 can be done before wiring the modules.
  • If you buy a third-party board or an assembled product, follow its own instructions. Usually no wiring is needed; just flash the matching firmware.

Q1: I can’t solder. Can I still build a XiaoZhi AI chatbot?

A: Yes. Follow the project tutorial and use the breadboard Wi-Fi build. Buy modules with pins already soldered, wire them and flash the firmware to the board as documented, then set up Wi-Fi and register the device. No soldering iron is needed at any point.

Q2: Where can I see the parts list, and where do I buy it?

A:

  1. For the hardware materials and modules, see the parts list and wiring section of the Hardware Build Guide.
  2. For purchasing:
    • Separate parts: search by module name, for example “ESP32 S3 development board”, “INMP441” for the microphone, “MAX98357” for the audio amplifier.
    • Kits: search for “XiaoZhi AI ESP32” or “XiaoZhi AI ESP32S3”.
    • Buying tips: see the Hardware Build Guide.

Note: products differ between sellers, so choose a shop with a good reputation, high sales and good reviews. Questions before purchase and after-sales issues are between you and the seller.

Q3: Do I need to buy the ML307R-4G module?

A: The ML307R-4G module is optional. It is mainly for these cases:

  • There is no Wi-Fi where you use the device, or Wi-Fi is restricted (for example campus or commercial networks that require a second login).
  • You have no Wi-Fi and connecting to a phone hotspot is inconvenient, or you have no smartphone.

Conclusion: if you have normal Wi-Fi or a phone hotspot, you don’t need the ML307R-4G module (unless you don’t want to deal with Wi-Fi and don’t mind paying for mobile data).

Also: the Cat.1 4G builds listed in the upstream README use three kinds of modules: ML307, EC801E and NT26. See Supported Boards for which boards can use them.

Firmware and Flashing

Q4: How do I flash the XiaoZhi AI firmware, and what if it fails?

A: See Firmware Download and Flashing. Key points:

  1. Select ESP32-S3 as the chip.
  2. The load mode is UART by default; plug into the USB port on the right side of the board (the silkscreen on the back says COM).
  3. Tick the BIN file to flash, and enter 0 or 0x0 as the address.
  4. Select the COM port your computer recognizes.

Notes:

  • Use a phone or board-supplied USB-C data cable, not a thin USB charging cable.
  • The path of the BIN file must not contain Chinese characters, or loading and flashing will fail.

Q5: What is IDF? Do I need to set up an IDF environment?

A:

  1. Ordinary users don’t need to install or configure an IDF environment; only developers or people learning to program do.
  2. IDF means ESP-IDF, the official development framework from Espressif, the maker of ESP32 chips. It supports developing ESP32 applications in C/C++. v2.5.2 requires ESP-IDF 6.0.1 or later, and the release/v6.1 branch is recommended.
  3. If you need to set it up:

Hardware

Q6: Why is there no sound from my XiaoZhi AI terminal’s speaker?

A:

  1. Check that the speaker is connected correctly. The red wire is usually positive and the black wire negative.
  2. Check that the digital amplifier is wired correctly and makes good contact. Refer to the wiring table.
  3. If you power the board from a computer USB port and the speaker is rated around 3 W, the supply may be too weak. Use a 5V 2A (or higher) USB charger, or the USB port of a 5V 2.1A power bank.

If the wiring is correct and it still doesn’t work, test with a spare speaker and digital amplifier module.

Q7: Why does the speaker sound hoarse or abnormal?

A:

  1. A hoarse sound usually means the amplifier’s GAIN pin is not connected to ground (GND), or the GND wiring is unstable.
  2. A crackling electrical noise may be electromagnetic interference. Keep the terminal away from strong magnetic devices and modules, and separate it from charge/discharge power supplies.

Q8: How do I adjust the volume?

A:

  1. By voice: the LLM sets the volume through the device-side MCP tool self.audio_speaker.set_volume. Just say “set the volume to …” or “turn the volume down / up a little”. See the MCP Usage Guide.
  2. With buttons: the bread-compact-wifi breadboard build defines volume buttons in config.h: IO40 is volume up and IO39 is volume down. For other boards, follow the notes in each board’s directory.

Q9: Why doesn’t “你好小智” wake the terminal, or why is there no reaction?

A:

  1. Make sure the wake word is correct (“你好小智”, not “小智你好” or anything else).
  2. Check that the microphone’s 6 pins are wired correctly and make good contact.
  3. For the INMP441 microphone, the side with the microphone icon, silkscreen letters and the sound hole normally faces up.
  4. If the wiring is correct and it still doesn’t work, test with a spare microphone.
  5. Reading the board’s output with a serial tool can help locate the problem.

Q10: The terminal asks me to set up the network, but I can’t find the Xiaozhi-XXXX hotspot.

A: This means the ESP32-S3 board’s Wi-Fi signal has a problem. You can:

  1. Temporarily press a finger on the board’s antenna area, or wind a wire around it, to strengthen the signal.
  2. Read the board’s output with a serial tool to locate the problem.

Q11: How do I set up or switch Wi-Fi again?

A:

  1. Power the board on again or restart it, and press the board’s provisioning button during startup: on bread-compact-wifi, click the BOOT button once; for other boards see the notes in each board’s directory. The device enters network configuration mode.
  2. If a saved Wi-Fi network cannot be reached within 60 seconds, the device also enters configuration mode on its own.
  3. Some boards provide an MCP tool named self.disp.network (reconfigure the network).

Note: the device keeps up to 10 Wi-Fi networks. If it has saved networks it will not enter configuration mode by itself, so to change networks you have to enter configuration mode as described above. See the Network Configuration Guide.

Q12: Why is my screen not lit?

A:

  1. Check that the screen is wired correctly and makes good contact.
  2. Breadboard quality varies; if something is wrong, test continuity with a multimeter.
  3. If the wiring is correct and it still doesn’t work, test with a spare screen.

Features and Usage

Q13: Can the terminal play music?

A: The v2.5.2 firmware source has no music playback feature. Whether you can ask for songs depends on the server you connect to, so follow the official console or your own server’s documentation. To play local music, you can extend the hardware interface and code yourself, or connect a third-party music platform on the server side.

Q14: Can I switch between large models such as DeepSeek?

A: Yes, but the server decides. With the official server, the available models and where to switch them are shown on the official console (it connects to the official server by default, and individual users can use the Qwen realtime model for free after registering). With a self-hosted server, choose the model in that server’s configuration; see Self-Hosted Server. The device firmware itself is not tied to any specific model.

Q15: Does the terminal support Bluetooth?

A: Not for now.

  • The ESP32-S3 chip/module supports Bluetooth BLE in peripheral mode only (it can be connected to). The XiaoZhi firmware does not use this by default; BLE is only used to send Wi-Fi credentials when BluFi provisioning is enabled, see the BluFi Setup Guide.
  • Because only peripheral mode is supported, the terminal cannot connect to Bluetooth headphones or speakers.

Q16: Can I use a bigger speaker?

A: Yes. The terminal’s default digital amplifier, the MAX98357, supports speakers of around 3 W. For more power, use another I2S amplifier module, but note that USB power on an ESP32 board generally doesn’t exceed 5 W, so higher power needs a separate supply.

Q17: Does the terminal support headphones or a 3.5 mm audio output?

A: Not by default; you need to replace the audio module, for example:

  • PCM5102 audio module (stereo DAC, about 10 CNY)
  • UDA1334A I2S stereo decoder (about 13–15 CNY)

Both support 3.5 mm audio output and need no code changes.

Q18: Can I use a bigger screen?

A: These screen types are supported:

  1. SSD1306 OLED screens:
    • Default: 0.91-inch 4-pin monochrome OLED (128×32).
    • You can switch to 4-pin SSD1306 screens such as 0.96-inch, 1.3-inch and 1.5-inch (128×64).
    • In menuconfig, choose SSD1306 12832, SSD1306 12864 or SH1106 128*64 under OLED Type, then rebuild.
  2. SPI-LCD screens:
    • LCD breadboard builds such as bread-compact-wifi-lcd support drivers including ST7789, ST7735, ST7796, ILI9341, GC9A01 and NV3030B, with variants by resolution and IPS or not.
    • In menuconfig, choose the matching driver and resolution under LCD Type, then build and flash.

Q19: Can I change the wake word?

A: Yes. v2.5.2 offers two ways:

  1. Custom wake word: in menuconfig, choose Multinet model (Custom Wake Word) under Wake Word Implementation Type. Enter the wake word in pinyin (separated by spaces), then the display text sent to the server after wake-up, and adjust the threshold if needed (1–99, smaller is more sensitive, default 20). This needs an ESP32-S3 / P4 / S31 with PSRAM. For the build environment see Set Up the ESP-IDF Environment and Build XiaoZhi.
  2. Assets generator: upstream provides a web custom Assets generator to change the wake word, fonts, emoji and chat background online. See the Custom Assets Guide.

The default “你好小智” is a built-in ESP-SR wake word model. For the wake word types available on chips other than ESP32-S3, see Chip Support and Storage Specs.

Q20: Can I rename the XiaoZhi AI role?

A: Yes. In the XiaoZhi AI management console, edit the AI role name under role configuration and save; it takes effect afterwards.

Note: the role name is the agent name configured for the large model. It has nothing to do with the offline wake word “你好小智”; the two are not related.

Q21: Can I change the voice?

A: Yes. In the XiaoZhi AI console, switch the role’s voice under role configuration. You can preview it first, then submit and save. The next conversation uses the new voice.

Q22: Can XiaoZhi AI recognize my voice and remember who I am?

A: Yes. Steps:

  1. In the XiaoZhi AI console, go to Agents and find Voiceprint Recognition.
  2. In the drop-down menu, choose a voice recording (a longer, clear one is recommended).
  3. Enter a name and a description (the relationship between the speaker and the role).
  4. Click OK to add the speaker.
  5. Wake XiaoZhi AI again and ask in the next conversation; it will know who you are.

Note: because of technical limits, recognition accuracy is not 100%, and it drops as more speakers are added.

Q23: Can I use my own custom voice?

A: It is in internal testing. The feature needs server support and uploading a custom voice is not open yet. Please watch for later announcements.

Q24: Does the terminal support battery power? How do I connect it?

A: You need a 5V boost module:

  1. The ESP32-S3 board needs 5V. A lithium battery is usually 3.8V, which is not enough, so adding a 5V charge/discharge board is recommended.
  2. To power the board externally: connect VOUT/5V+ of the 5V charge/discharge board to the board’s 5Vin pin and GND to the board’s GND pin.
  3. You can also power it directly from a power bank over USB-C; a 5V 2.1A output is recommended.

Q25: Can it control motors or servos by voice?

A: Not by default; you need to add a servo or motor driver module. The ESP32-S3 can be extended through device-side MCP tools (see Q26): the large model calls a tool to send signals to the driver board.

XiaoZhi AI has been ported to the ESP-SparkBot board (directory espressif/esp-sparkbot, tracked chassis), where the self.chassis.* MCP tools provide forward, backward, turning and dancing. Board source: espressif/esp-sparkbot

Q26: Can it control other devices by voice?

A: Yes, through MCP. Device-side MCP can control volume, lights, motors, GPIO and more; cloud MCP can add smart-home control, PC desktop operation, knowledge search, email and more. See the MCP documentation for the protocol and usage; adding new device-side tools needs your own development.

Q27: Which development boards on the market are supported?

A: The v2.5.2 release matrix has 154 board directories and 188 firmware variants, covering ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3, ESP32-S31 and ESP32-P4. See Supported Boards for the full list.

When flashing, choose the firmware of the matching variant. When building, choose the board under Target Board in menuconfig. Other boards need to be adapted and rebuilt; see the Custom Board Guide.

Q28: Which large model does XiaoZhi AI use? Is the server open source?

A: The device firmware is open source (78/xiaozhi-esp32). It connects to the official server by default, and individual users can use the Qwen realtime model for free after registering. On the server side the community has several open-source implementations, for example xinnan-tech/xiaozhi-esp32-server (Python), joey-zhou/xiaozhi-esp32-server-java (Java), AnimeAIChat/xiaozhi-server-go (Golang) and hackers365/xiaozhi-esp32-server-golang (Golang). For the connection steps and security warnings see Self-Hosted Server; for the full list see Ecosystem Projects.

Q29: Can XiaoZhi AI connect to large models such as GPT?

A: Large models are connected on the server side; the device firmware does not connect to them directly. With the official server, the available models are whatever the official console offers. To use other large models, use a self-hosted server. For example, the community project xiaozhi-esp32-server can connect to Alibaba Bailian, Volcano Engine, DeepSeek, Zhipu, Gemini and others through OpenAI-compatible interfaces; see Self-Hosted Server.

For more information, see the README and docs directory of the upstream project 78/xiaozhi-esp32, or report problems on GitHub Issues.

XiaoZhi AI Budget Version - ESP32 Development Board Implementation