Voice Setup
SimpleClaw supports voice interaction through Talk Mode (voice output) and Voice Wake (voice input) on macOS, iOS, and Android.
Prerequisites
Platform
macOS, iOS, or Android device
Voice Provider
ElevenLabs, OpenAI, or compatible TTS service
Quick Setup
Configure Voice Provider
Set up ElevenLabs (recommended):simpleclaw config set talk.provider '"elevenlabs"' --json
simpleclaw config set talk.providers.elevenlabs.apiKey '"YOUR_API_KEY"' --json
Choose a Voice
List available voices:Set your preferred voice:simpleclaw config set talk.voiceId '"21m00Tcm4TlvDq8ikWAM"' --json
Test Talk Mode
simpleclaw agent --message "Hello!" --talk
Talk Mode Configuration
Talk Mode provides voice output for agent responses.
Basic Configuration
{
"talk": {
"provider": "elevenlabs",
"voiceId": "21m00Tcm4TlvDq8ikWAM",
"modelId": "eleven_turbo_v2",
"interruptOnSpeech": true
}
}
Provider Options
{
"talk": {
"provider": "elevenlabs",
"providers": {
"elevenlabs": {
"apiKey": "YOUR_API_KEY",
"voiceId": "21m00Tcm4TlvDq8ikWAM",
"modelId": "eleven_turbo_v2",
"outputFormat": "mp3_44100_128"
}
}
}
}
{
"talk": {
"provider": "openai",
"providers": {
"openai": {
"apiKey": "YOUR_API_KEY",
"voiceId": "alloy",
"modelId": "tts-1-hd"
}
}
}
}
alloy, echo, fable, onyx, nova, shimmerVoice Aliases
Create named aliases for different voices:
{
"talk": {
"voiceAliases": {
"assistant": "21m00Tcm4TlvDq8ikWAM",
"narrator": "pNInz6obpgDQGcFmaJgB",
"friendly": "EXAVITQu4vr4xnSDxMaL"
}
}
}
simpleclaw agent --message "Tell me a story" --talk --voice narrator
Voice Wake Setup
Voice Wake enables hands-free voice input using a wake word.
macOS Setup
Enable Voice Wake in macOS App
- Open OpenClaw menu bar app
- Go to Preferences → Voice Wake
- Enable Voice Wake
- Choose wake word (default: “Hey Claw”)
Grant Microphone Permission
macOS will prompt for microphone access. Click Allow.
Test Voice Wake
Say your wake word:"Hey Claw, what's the weather today?"
Configure Voice Wake Behavior
{
"voiceWake": {
"enabled": true,
"wakeWord": "Hey Claw",
"autoTalk": true,
"thinkingLevel": "low",
"deliverToChannel": false
}
}
iOS Setup
Install iOS App
Build and install the iOS app (see platform docs).
Pair as Node
- Open the iOS app
- Tap Pair Device
- Scan the QR code from:
simpleclaw nodes pair --platform ios
Enable Voice Wake
In the iOS app:
- Go to Settings
- Enable Voice Wake
- Grant microphone permission
Test
Say: “Hey Claw, what can you do?”
Android Setup
Same process as iOS - build app, pair as node, enable Voice Wake.
Push-to-Talk Mode
Alternative to voice activation - hold a key to speak:
macOS PTT
- Open OpenClaw menu bar app
- Go to Preferences → Voice Wake
- Enable Push to Talk
- Set hotkey (default:
Option+Space)
- Hold hotkey and speak
Voice Wake Configuration Reference
{
"voiceWake": {
"enabled": true,
"wakeWord": "Hey Claw",
"autoTalk": true,
"thinkingLevel": "low",
"deliverToChannel": false,
"sessionKey": "voice",
"agentId": "main",
"timeout": 30000
}
}
Automatically speak responses
Thinking level for voice requests
Also deliver response to last used channel
Talk Mode API
Enable Talk Mode
Via WebSocket:
{
"type": "req",
"id": "req-1",
"method": "talk.mode",
"params": {
"enabled": true,
"phase": "full"
}
}
full - Speak full responsessummary - Speak summaries onlyoff - Disable voice output
Get Talk Configuration
{
"type": "req",
"id": "req-2",
"method": "talk.config",
"params": {}
}
Advanced Features
Interrupt on Speech
Stop agent speech when you start talking:
{
"talk": {
"interruptOnSpeech": true
}
}
Per-Session Voice Settings
Different voices for different agents:
{
"agents": {
"main": {
"talk": {
"voiceId": "assistant"
}
},
"storyteller": {
"talk": {
"voiceId": "narrator"
}
}
}
}
Voice in Channels
Enable voice responses in messaging channels:
{
"channels": {
"telegram": {
"talk": {
"enabled": true,
"voiceId": "assistant"
}
}
}
}
Troubleshooting
- Check system volume
- Verify TTS provider is configured:
simpleclaw config get talk
- Test provider API key:
Voice Wake not triggering
- Check microphone permission in System Settings
- Verify Voice Wake is enabled:
simpleclaw config get voiceWake.enabled
- Check Gateway logs:
simpleclaw gateway logs --tail 50
Poor transcription quality
- Reduce background noise
- Speak closer to microphone
- Adjust voice timeout:
simpleclaw config set voiceWake.timeout 45000 --json
- Switch to a cheaper provider (OpenAI vs ElevenLabs)
- Use shorter responses:
simpleclaw config set talk.maxLength 500 --json
- Disable auto-talk for non-essential sessions
Next Steps
Remote Gateway
Run Gateway on remote server with local voice nodes
Custom Skills
Create voice-activated custom tools
Multi-Agent Setup
Different voices for different agents
Troubleshooting
Common voice issues and solutions