OpenClaw AI Voice Interaction Configuration

1. Course Overview

This course will introduce how to configure OpenClaw's AI voice interaction pipeline, including voice configuration file location, key parameter descriptions, startup methods, and common troubleshooting.

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

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 results are published to OpenClaw

5. OpenClaw returns results

6. [Optional] TTS broadcasts the returned results (reply content may be long, you can choose whether to broadcast)

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 from the template:

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

3.2 Minimum Configuration to Check Before Startup

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 Description

4.1 Voice Recognition Engine

xxxxxxxxxx
ASR_ENGINE=dashscope

Currently supports two modes:

• dashscope: Tongyi Bailian native voice recognition interface, suitable for direct online use

For most beginners, it is recommended to keep:

xxxxxxxxxx
ASR_ENGINE=dashscope

4.2 Microphone and Speaker Devices

xxxxxxxxxx
DEVICE=0
SPEAKER_DEVICE=0

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

Scenarios suitable for modification:

• Multiple microphone devices

• USB microphone is not the system default device

• Speaker output is on the wrong device

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

4.3 DashScope Authentication and ASR Model

Please log in to Alibaba Cloud Bailian to apply for an API key yourself

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: Must be filled with a valid API-KEY

• DASHSCOPE_API_URL: Default is already provided

• DASHSCOPE_ASR_MODEL: Default voice recognition model

If this is not configured correctly, common symptoms are:

• Recognition failure after program startup

• Authentication error return

• Voice recognition request timeout or model error

4.4 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

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, this time should be increased
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 local gateway port

• Automatically read gateway authentication token

Therefore, if voice recognition is successful but OpenClaw does not execute 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 use the matching voice module, it usually adopts serial wake mode.

Main functions are:

• Normally wait for wake signal

• Start collecting next voice segment after receiving wake signal

• Return to waiting state after processing is complete

If there is no matching 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 parameters in .env, then restart the program.

Currently voice_to_openclaw/.env enables the domestic version (Bailian) by default.

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 recognition language is changed to English, XUNFEI_ASR_ACCENT is no longer needed; it can be commented out or kept with original value without being used

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 only want to verify English recognition first, just 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 enables TTS, it is recommended to switch to the corresponding English voice tone simultaneously, otherwise it may happen that English recognition is normal but the broadcast still sounds like Chinese voice.

After modification is complete, re-execute the following startup command to take effect.

5. Start Voice Interaction

5.1 Prepare Virtual Environment

This step is not needed for factory images. If dependencies have not been 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 enter waiting for wake or waiting for voice input state.

If you start English log, it will look like this,

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

5.3 If Other Interaction Methods Need Broadcast

• Change broadcast parameter configuration to True

xxxxxxxxxx
ENABLE_TTS=true 

• Additionally start an independent listener, terminal input

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 report errors immediately, it indicates that the basic environment is probably normal.

6.2 Verify Recognition and Publishing Process

Say "Hello, yahboom" to wake up, then you can try saying:

• Tell me a joke

• Display hello on OLED

If you can see OpenClaw returning text, it indicates:

• Microphone collection is normal

• ASR is normal

• OpenClaw gateway publishing is normal

It has a cropping function; if it's too short, you can tell it a joke via voice.

6.4 Verify TTS [Optional]

If enabled:

xxxxxxxxxx
ENABLE_TTS=true

Then 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 have been 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 microphone device number DEVICE is correct

7.3 Recognition Successful But OpenClaw Not Responding

Check first:

• Whether OPENCLAW_CONFIG_PATH is correct

• Whether the gateway port in openclaw.json is normal

• Whether OpenClaw gateway has been started

7.4 Can Recognize But No Voice Broadcast

Check first:

• Whether ENABLE_TTS is true

• Whether SPEAKER_DEVICE is correct

• Whether 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 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 effective

5. Check if recognition is effective

6. Check if OpenClaw receives text

7. Finally check TTS broadcast