OpenClaw AI Voice Interaction Configuration

1. Course Overview

This course walks you through configuring the AI voice interaction pipeline in OpenClaw, including voice configuration file locations, key parameter descriptions, startup methods, and common troubleshooting steps.

After completing this course, you will be able to:

• Know which configuration file is used for AI voice interaction
• Understand the meaning of key parameters in .env
• Correctly start the voice program

2. Voice Interaction Overall Pipeline

The current voice interaction process in OpenClaw can be simply understood as:

1. Microphone captures voice
2. Program performs silence detection and segmentation
3. ASR engine converts speech to text
4. Recognition results are published to OpenClaw
5. OpenClaw returns results
6. [Optional] TTS reads out the returned results (the reply content may be long, you can choose whether to read it out)

The core configuration file for this pipeline is:

/home/jetson/voice_to_openclaw/.env

3. Voice Configuration File Description

3.1 Configuration File Location

xxxxxxxxxx
/home/jetson/voice_to_openclaw/.env

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

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

3.2 Minimum Configuration to Check Before Starting

It is recommended to at least confirm the following items:

• ASR_ENGINE
• DASHSCOPE_API_KEY
• DEVICE
• SPEAKER_DEVICE
• OPENCLAW_CONFIG_PATH
• ENABLE_SERIAL_WAKE

4. Key Parameter Descriptions

4.1 Speech Recognition Engine

xxxxxxxxxx
ASR_ENGINE=dashscope

Two modes are currently supported:

• dashscope: Tongyi Bailian native speech recognition API, suitable for direct online use
• faster_whisper: Local Whisper recognition, suitable for local operation (not supported on Raspberry Pi)

For most beginners, we recommend keeping the default:

xxxxxxxxxx
ASR_ENGINE=dashscope

4.2 Microphone and Speaker Devices

xxxxxxxxxx
DEVICE=pulse
SPEAKER_DEVICE=pulse

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
• The speaker output goes to the wrong device

If the voice program starts but you cannot hear or record audio, check these settings first.

4.3 DashScope Authentication and ASR Model

To obtain an API key, log in to Alibaba Cloud Bailian:

Link: Large Model Service Platform Bailian Console

xxxxxxxxxx
DASHSCOPE_API_KEY=
DASHSCOPE_API_URL=https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
DASHSCOPE_ASR_MODEL=qwen3-asr-flash

Where:

• DASHSCOPE_API_KEY: A valid API-KEY must be filled in
• DASHSCOPE_API_URL: A default value is already provided
• DASHSCOPE_ASR_MODEL: Default speech recognition model

If this is not configured correctly, common symptoms are:

• Recognition fails after the program starts
• An authentication error is returned
• Speech recognition request timeout or model error

4.4 TTS Voice Broadcast Configuration

xxxxxxxxxx
ENABLE_TTS=false
WAKE_ACK_TEXT=I'm here.

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

xxxxxxxxxx
ENABLE_TTS=true

Current common TTS parameters include:

• DASHSCOPE_TTS_MODEL
• DASHSCOPE_TTS_VOICE
• DASHSCOPE_TTS_VOLUME
• DASHSCOPE_TTS_SPEECH_RATE

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

4.5 OpenClaw Gateway Configuration Reference

xxxxxxxxxx
OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
OPENCLAW_TIMEOUT=70  # Maximum retry time, waiting for OpenClaw reply. For long tasks, consider increasing this value
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 determine the local gateway port
• Automatically read the gateway authentication token

Therefore, if speech recognition has already succeeded but OpenClaw is not executing commands, check here first.

4.6 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 bundled voice module, serial wake mode is usually used.

The main functions are:

• Wait for the wake signal by default
• Start capturing the next voice segment after receiving the wake signal
• Return to waiting state after processing is complete

If you do not have the bundled serial wake module, you can adjust as needed:

xxxxxxxxxx
ENABLE_SERIAL_WAKE=false

4.7 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.

The current voice_to_openclaw/.env defaults to the Domestic Version (Bailian).

Method 1: Overseas Version (iFlytek International)

Main configuration items:

xxxxxxxxxx
XUNFEI_ASR_LANGUAGE=en_cn
XUNFEI_ASR_ACCENT=mandarin
# Terminal log language: zh / en
UI_LANGUAGE=en

• Chinese recognition: XUNFEI_ASR_LANGUAGE=zh_cn
• English recognition: XUNFEI_ASR_LANGUAGE=en_us
• When the recognition language is changed to English, XUNFEI_ASR_ACCENT is no longer needed and can be commented out or left as-is

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 also enabled and you want English broadcast, you also need to change TTS_VOICE to an English voice tone you have activated; if you are just verifying English recognition first, only change the ASR language.

Method 2: Domestic Version (Bailian)

Main configuration items:

xxxxxxxxxx
DASHSCOPE_LANGUAGE=zh

• Chinese recognition: DASHSCOPE_LANGUAGE=zh
• English recognition: DASHSCOPE_LANGUAGE=en

Example:

xxxxxxxxxx
# Chinese recognition
DASHSCOPE_LANGUAGE=zh
# Terminal log language: zh / en
UI_LANGUAGE=zh

If the Bailian solution also has TTS enabled, it is recommended to simultaneously switch to the corresponding English voice tone, otherwise English recognition may work normally but the broadcast may still use a Chinese voice.

After making the changes, re-run the startup command below for the changes to take effect.

5. Starting Voice Interaction

5.1 Prepare Virtual Environment

This step is not needed for the factory image. If dependencies are not yet installed, first execute:

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

5.2 Startup Method

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

If startup is successful, the program will wait for wake or voice input.

If English log is enabled, it will look like this:

xxxxxxxxxx
# Terminal log language: zh / en
UI_LANGUAGE=en

5.3 If Other Interaction Methods Need Broadcast

• Change the broadcast parameter to True

xxxxxxxxxx
ENABLE_TTS=true 

• Additionally, start a separate listener by entering the following in the terminal:

xxxxxxxxxx
cd ~/voice_to_openclaw
source .venv/bin/activate
python -m src.openclaw_session_tts

6. Configuration Verification Methods

6.1 Verify Voice Program Can Start

Execute:

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

If the program starts successfully and does not immediately report errors, the environment is most likely set up correctly.

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 the OLED

If you can see OpenClaw returning text, it means:

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

6.3 Verify TTS [Optional]

If enabled:

xxxxxxxxxx
ENABLE_TTS=true

After OpenClaw returns results, you should be able to hear voice broadcast.

7. Common Issues

7.1 Program Startup Failure

Check first:

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

7.2 No Recognition Result After Wake

Check first:

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

7.3 Recognition Succeeds but OpenClaw Does Not Respond

Check first:

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

7.4 Can Recognize but No Voice Broadcast

Check first:

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

7.5 Serial Wake Failure

Check first:

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

8. Recommended Debugging Order

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

1. First confirm the .env file exists
2. Then confirm DASHSCOPE_API_KEY has been filled in
3. Start the program and confirm no immediate errors
4. Check if wake is working
5. Check if recognition is working
6. Check if OpenClaw has received the text
7. Finally check TTS broadcast