Voice Setup Tutorial

This tutorial will guide you through setting up OpenClaw's voice features, including Voice Wake (always-on speech recognition) and Talk Mode (two-way voice conversation). By the end, you'll have a fully functional hands-free voice assistant. Estimated time: 20-30 minutes.

By the end of this tutorial, you'll have:

• Voice Wake - Always-on speech recognition that activates OpenClaw with a wake word
• Talk Mode - Two-way voice conversation with natural speech responses
• ElevenLabs Integration - High-quality text-to-speech for voice responses
• Hands-Free Operation - Complete voice control without typing

Before starting:

• OpenClaw installed and running - Complete Getting Started Tutorial
• macOS, iOS, or Android - Voice features are platform-specific
• Microphone permissions - Grant microphone access to OpenClaw
• ElevenLabs account (optional, for Talk Mode) - Sign up at elevenlabs.io

Voice Wake enables always-on speech recognition. Let's configure it:

macOS Setup

On macOS, Voice Wake integrates with the system speech recognition:

1. Open the macOS menu bar app (if installed)
2. Go to Settings → Voice Wake
3. Enable Voice Wake
4. Grant microphone permissions when prompted
5. Set your preferred wake word (default: "hey openclaw")

Configuration File Method

Alternatively, configure Voice Wake in your OpenClaw configuration file:

{
  "voice": {
    "wake": {
      "enabled": true,
      "wakeWord": "hey openclaw"
    }
  }
}

Save the configuration and restart the Gateway:

openclaw gateway restart

iOS/Android Setup

On iOS and Android, Voice Wake is available through the companion apps:

1. Install the iOS or Android companion app
2. Pair the device as a node via the Bridge
3. Enable Voice Wake in the app settings
4. Grant microphone permissions

For detailed platform setup, see macOS, iOS, or Android guides.

Talk Mode enables two-way voice conversation with text-to-speech responses. We'll use ElevenLabs for high-quality voice synthesis.

Get ElevenLabs API Key

1. Sign up for an account at elevenlabs.io
2. Navigate to your profile settings
3. Copy your API key
4. Keep it secure - you'll need it for configuration

Configure Talk Mode

Add Talk Mode configuration to your OpenClaw config:

{
  "voice": {
    "talk": {
      "enabled": true,
      "provider": "elevenlabs",
      "apiKey": "your-elevenlabs-api-key",
      "voice": "default"
    }
  }
}

Security Note: Store your API key securely. Consider using environment variables or a secrets manager instead of hardcoding it.

Select a Voice

ElevenLabs offers multiple voice options. You can:

• Use the default voice
• Browse available voices in the ElevenLabs dashboard
• Create a custom voice clone
• Ask OpenClaw to help you choose: "Help me select an ElevenLabs voice for Talk Mode"

Update the "voice" field in your configuration with your chosen voice ID.

Now let's test both Voice Wake and Talk Mode:

Test Voice Wake

1. Ensure Voice Wake is enabled and microphone permissions are granted
2. Say your wake word: "Hey OpenClaw" (or your custom wake word)
3. OpenClaw should activate and be ready to listen
4. Speak your request naturally

Test Talk Mode

1. Send a message to OpenClaw via your connected channel (Telegram, WhatsApp, etc.)
2. Send an audio message or use Voice Wake
3. OpenClaw should respond with an audio message (if Talk Mode is configured)
4. Or ask: "Enable Talk Mode and respond with voice"

You can also test via the CLI:

openclaw agent --message "Say hello in a voice message"

Custom Wake Word

Customize your wake word to something personal:

{
  "voice": {
    "wake": {
      "enabled": true,
      "wakeWord": "hey assistant"
    }
  }
}

Push-to-Talk Mode

On mobile devices, you can use push-to-talk instead of always-on listening:

• iOS/Android apps support push-to-talk buttons
• Hold the button while speaking
• Release to send the audio
• More battery-efficient than always-on listening

Audio Quality Settings

Configure audio quality for Talk Mode responses:

{
  "voice": {
    "talk": {
      "enabled": true,
      "provider": "elevenlabs",
      "voice": "default",
      "stability": 0.5,
      "similarity_boost": 0.75
    }
  }
}

Now that everything is set up, here's how to use your voice assistant:

Voice Wake Workflow

1. Say your wake word: "Hey OpenClaw"
2. Wait for activation confirmation (visual or audio)
3. Speak your request naturally
4. OpenClaw processes and responds

Talk Mode Workflow

1. Send an audio message via your channel
2. OpenClaw transcribes and processes your request
3. OpenClaw responds with an audio message (if Talk Mode enabled)
4. Have a natural voice conversation

Example Use Cases

• Hands-Free Control: "Hey OpenClaw, what's the weather today?"
• Quick Questions: "Hey OpenClaw, remind me to call John at 3pm"
• Voice Notes: Send audio messages while driving or multitasking
• Accessibility: Voice interaction for users who prefer speech

Voice Wake Not Working

• Check microphone permissions in system settings
• Verify Voice Wake is enabled in configuration
• Ensure you're on a supported platform (macOS/iOS/Android)
• Try restarting the Gateway: openclaw gateway restart
• Check Gateway logs: openclaw gateway logs

Talk Mode Not Responding

• Verify ElevenLabs API key is correct
• Check API key has sufficient credits
• Ensure Talk Mode is enabled in configuration
• Test API key directly with ElevenLabs dashboard
• Check voice ID is valid

Audio Quality Issues

• Adjust stability and similarity_boost settings
• Try different ElevenLabs voices
• Check network connection for API calls
• Verify audio format compatibility

Now that you have voice features set up, explore these related topics: