🔊 Voice & Talk Mode

🎚️ Three levels of voice

🎤 Level 1: Voice notes (easiest)

Send a voice note on Telegram or WhatsApp. OpenClaw automatically transcribes it using Whisper and processes the transcript like a normal text message. No extra config needed if you have an OpenAI API key.

This works because:

• Telegram/WhatsApp voice notes arrive as audio files
• OpenClaw runs them through Whisper (OpenAI API or local)
• The transcript is treated as the message body
• Slash commands in speech work too ("slash reset" → /reset)

# STT config (usually auto-detected from your OpenAI key)
{
  "messages": {
    "stt": {
      "provider": "openai",
      "model": "whisper-1",
      "language": "en"
    }
  }
}

🗣️ Level 2: TTS responses

Make your agent talk back with ElevenLabs:

1. Sign up at elevenlabs.io (free tier available for testing)
2. Copy your API key from Profile → API Keys
3. Browse the voice library and pick a voice ID

# Set the env var
export ELEVENLABS_API_KEY="your_key_here"

# Or configure in openclaw.json
{
  "messages": {
    "tts": {
      "auto": "inbound",
      "provider": "elevenlabs",
      "voiceId": "EXAVITQu4vr4xnSDxMaL",
      "maxTextLength": 4000,
      "timeoutMs": 30000
    }
  }
}

TTS auto modes

🎧 Level 3: Talk Mode

Full hands-free: you speak, the agent listens, processes, and speaks back. Requires a paired node device with microphone and speaker.

Architecture

┌─────────────┐  WebSocket  ┌──────────────────────┐
│ Node device  │◄──────────►│    Gateway            │
│ (mic + spkr) │            │ (model + tools)       │
│ macOS/iOS/   │            │ ws://127.0.0.1:18789  │
│ Android      │            └──────────────────────┘
└─────────────┘
  ↕ Whisper STT    ↕ ElevenLabs TTS

The Gateway handles AI processing; the node handles audio I/O. This keeps gateway headless and stable.

Activate Talk Mode

• Web client: Click the microphone icon at localhost:18789
• macOS app: Push-to-talk overlay in the menu bar
• iOS/Android: Via the companion node app
• Wake word: Say "hey claw" (see below)
• Chat command: Send "Start talk mode" or "Let's talk"

Talk Mode config

{
  "talk": {
    "voiceId": "EXAVITQu4vr4xnSDxMaL",
    "modelId": "eleven_v3",
    "outputFormat": "mp3_44100_128",
    "interruptOnSpeech": true,
    "stability": 0.5,
    "similarityBoost": 0.75
  }
}

Interrupt on speech: If you start talking while the agent is speaking, it stops and listens. Feels natural.

👂 Wake word detection

Always-on listening that activates on a keyword (like "Hey Siri" or "OK Google"):

{
  "voice": {
    "wake_word": {
      "enabled": true,
      "engine": "porcupine",
      "keyword": "hey claw",
      "sensitivity": 0.5
    }
  }
}

🔄 Provider comparison

⚙️ Full config reference

{
  "messages": {
    "stt": {
      "provider": "openai",
      "model": "whisper-1",
      "language": "en"
    },
    "tts": {
      "auto": "inbound",
      "provider": "elevenlabs",
      "voiceId": "EXAVITQu4vr4xnSDxMaL",
      "maxTextLength": 4000,
      "timeoutMs": 30000
    }
  },
  "talk": {
    "voiceId": "EXAVITQu4vr4xnSDxMaL",
    "modelId": "eleven_v3",
    "interruptOnSpeech": true,
    "stability": 0.5,
    "similarityBoost": 0.75
  }
}

💡 Tips & best practices

• Start with voice notes — Level 1 costs almost nothing and works today
• Use "inbound" TTS mode — agent only speaks when you spoke first
• Set maxTextLength — prevents TTS from reading 300-line stack traces
• Use headphones for Talk Mode — prevents echo and improves wake word detection
• Choose voice wisely — ElevenLabs has dozens of pre-made voices. Browse the library to match your agent's personality.
• Monitor ElevenLabs credits — chatty setups can hit $50+/mo. The free tier is fine for testing.
• Local Whisper as fallback — if cloud STT is down, local model keeps working

🔧 Troubleshooting