OpenClaw AI Voice Interaction Configuration

1. Course Overview

This course will introduce how to configure the AI voice interaction chain of OpenClaw, including the voice configuration file location, key parameter descriptions, startup methods, and common problem troubleshooting.

After completing this course, you will be able to:

• Know which configuration file the AI voice interaction uses
• Understand the meaning of key parameters in .env
• Master how to switch between Chinese and English voice recognition
• Correctly start the voice program

2. Overall Voice Interaction Chain

OpenClaw's current voice interaction process can be simply understood as:

1. Microphone collects voice
2. Program performs silence detection and segmentation
3. ASR engine recognizes voice into text
4. Recognition result is published to OpenClaw
5. OpenClaw returns result
6. [Optional] TTS broadcasts the returned result (the reply content will be very long, you can choose whether to broadcast yourself)

The core configuration file for this chain is:

/home/pi/voice_to_openclaw/.env

3. Voice Configuration File Description

3.1 Configuration File Location

Default use factory image

xxxxxxxxxx
/home/pi/voice_to_openclaw/.env

If this file does not exist, you can copy from the template first:

xxxxxxxxxx
cd /home/pi/voice_to_openclaw
cp .env.example .env

3.2 Minimum Configuration Checks Before Startup

It is recommended to confirm at least the following items:

• ASR_ENGINE
• DASHSCOPE_API_KEY
• DASHSCOPE_LANGUAGE or XUNFEI_ASR_LANGUAGE
• DEVICE
• SPEAKER_DEVICE
• OPENCLAW_CONFIG_PATH
• ENABLE_SERIAL_WAKE

4. Key Parameter Description

4.1 Voice Recognition Engine

xxxxxxxxxx
ASR_ENGINE=dashscope

Currently supports three modes:

• dashscope: Tongyi Bailian native voice recognition interface, suitable for direct network use
• xunfei_ws: iFlytek WebSocket voice recognition, suitable for overseas version configuration
• faster_whisper: Local Whisper recognition, suitable for local running (not supported on Raspberry Pi)

4.2 Microphone and Speaker Devices

xxxxxxxxxx
DEVICE=0
SPEAKER_DEVICE=0

These two parameters determine which audio input and output devices the program uses.

Scenarios suitable for modification:

• Multiple microphone devices
• USB microphone is not the system default device
• Speaker output to the wrong device

If the voice program can start but you cannot hear sound or record sound, check here first.

4.3 TTS Voice Broadcast Configuration

xxxxxxxxxx
ENABLE_TTS=false
WAKE_ACK_TEXT=I am here

If you want voice broadcast after voice recognition, you can enable:

xxxxxxxxxx
ENABLE_TTS=true

Currently common TTS parameters include:

• DASHSCOPE_TTS_MODEL
• DASHSCOPE_TTS_VOICE
• DASHSCOPE_TTS_VOLUME
• DASHSCOPE_TTS_SPEECH_RATE

It is recommended to first get the ASR working, then consider enabling TTS.

4.4 OpenClaw Gateway Configuration Reference

xxxxxxxxxx
OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
OPENCLAW_TIMEOUT=70  #Maximum retry time, waiting for OpenClaw reply. If it's a very long task, it is recommended to increase this time
OPENCLAW_RETRY=1

This part of the configuration determines how the voice program sends recognition results to OpenClaw.

By default:

• The program will read openclaw.json
• Automatically derive the local gateway port
• Automatically read the gateway authentication token

Therefore, if voice recognition has succeeded but OpenClaw has not executed instructions, check here first.

4.5 Serial Wake Configuration

xxxxxxxxxx
ENABLE_SERIAL_WAKE=true
MIC_SERIAL_PORT=/dev/ttyUSB0
MIC_SERIAL_BAUDRATE=115200
SERIAL_WAKE_REQUIRED=true

If you are using the factory voice module, serial wake mode is usually used.

Main functions:

• Normally wait for wake signal
• After receiving wake, start collecting the next voice segment
• After processing is complete, return to waiting state again

If you do not have a factory serial wake module, you can adjust according to needs:

xxxxxxxxxx
ENABLE_SERIAL_WAKE=false

4.6 Chinese-English Switching Steps

If you need to switch voice interaction from Chinese to English, it is recommended to directly modify the language parameter in .env, then restart the program.

Currently, voice_to_openclaw/.env defaults to the domestic version (Bailian).

Overseas Version (iFlytek International)

Main configuration items:

xxxxxxxxxx
XUNFEI_ASR_LANGUAGE=en_cn
XUNFEI_ASR_ACCENT=mandarin

• Chinese recognition: XUNFEI_ASR_LANGUAGE=zh_cn
• English recognition: XUNFEI_ASR_LANGUAGE=en_us
• When recognition language is changed to English, XUNFEI_ASR_ACCENT is no longer needed; you can comment it out or keep the original value unused

Example:

​x
# Chinese recognition
XUNFEI_ASR_LANGUAGE=zh_cn
XUNFEI_ASR_ACCENT=mandarin
​
# English recognition
XUNFEI_ASR_LANGUAGE=en_us
# XUNFEI_ASR_ACCENT=mandarin

If TTS is enabled at the same time and you want English broadcast, you also need to change TTS_VOICE to the English voice you have enabled; if you just want to verify English recognition first, only change ASR language.

After modification, just re-execute the startup command below to take effect.

5. Start Voice Interaction

5.1 Prepare Virtual Environment

Factory image does not need this step. If dependencies are not installed yet, execute first:

xxxxxxxxxx
cd /home/pi/voice_to_openclaw
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

5.2 Startup Method

xxxxxxxxxx
cd /home/pi/voice_to_openclaw
source .venv/bin/activate
python -m src.main

If startup is successful, the program will enter the state of waiting for wake or waiting for voice input.

6. Configuration Verification Methods

6.1 Verify Voice Program Can Start

Execute:

xxxxxxxxxx
cd /home/pi/voice_to_openclaw
source .venv/bin/activate
python -m src.main

If the program starts successfully and does not immediately report an error, the basic environment is probably normal.

6.2 Verify Recognition and Publishing Process

After saying "Hi,yahboom" to wake up, you can try saying:

• Tell me a joke
• Display "Hello" on OLED

If you can see OpenClaw return text, it means:

• Microphone collection is normal
• ASR is normal
• OpenClaw gateway publishing is normal

6.3 Verify TTS [Optional]

If already enabled:

xxxxxxxxxx
ENABLE_TTS=true

Then after OpenClaw returns results, you should hear voice broadcast.

7. Common Problems

7.1 Program Fails to Start

Check in order:

• Whether .venv exists
• Whether dependencies are installed
• Whether .env exists

7.2 No Recognition Result After Wake

Check in order:

• Whether ASR_ENGINE is configured correctly
• Whether DASHSCOPE_API_KEY is valid
• Whether microphone device number DEVICE is correct

7.3 Recognition Succeeds But OpenClaw Has No Response

Check in order:

• Whether OPENCLAW_CONFIG_PATH is correct
• Whether the gateway port in openclaw.json is normal
• Whether OpenClaw gateway is started

7.4 Can Recognize But No Sound Broadcast

Check in order:

• Whether ENABLE_TTS is true
• Whether SPEAKER_DEVICE is correct
• Whether the speaker is connected properly

7.5 Serial Wake Fails

Check in order:

• Whether ENABLE_SERIAL_WAKE is true
• Whether MIC_SERIAL_PORT is correct
• Whether MIC_SERIAL_BAUDRATE is correct
• Whether the voice module serial device is recognized by the system

8. Recommended Debugging Order

It is recommended to troubleshoot the voice chain in the following order:

1. First confirm the .env file exists
2. Then confirm DASHSCOPE_API_KEY is filled in
3. Start the program and confirm no immediate error
4. Check if wake takes effect
5. Check if recognition takes effect
6. Check if OpenClaw receives text
7. Finally check TTS broadcast