Voice Setup

Enable voice interaction with SimpleClaw using Talk Mode and Voice Wake

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

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

   Get your API key from ElevenLabs.

2. Choose a Voice

   List available voices:

   simpleclaw talk voices
   

   Set your preferred voice:

   simpleclaw config set talk.voiceId '"21m00Tcm4TlvDq8ikWAM"' --json
   
3. Test Talk Mode

   simpleclaw agent --message "Hello!" --talk
   

   The response will be spoken aloud.

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

ElevenLabs

{
  "talk": {
    "provider": "elevenlabs",
    "providers": {
      "elevenlabs": {
        "apiKey": "YOUR_API_KEY",
        "voiceId": "21m00Tcm4TlvDq8ikWAM",
        "modelId": "eleven_turbo_v2",
        "outputFormat": "mp3_44100_128"
      }
    }
  }
}

OpenAI

{
  "talk": {
    "provider": "openai",
    "providers": {
      "openai": {
        "apiKey": "YOUR_API_KEY",
        "voiceId": "alloy",
        "modelId": "tts-1-hd"
      }
    }
  }
}

OpenAI voices: alloy, echo, fable, onyx, nova, shimmer

Voice Aliases

Create named aliases for different voices:

{
  "talk": {
    "voiceAliases": {
      "assistant": "21m00Tcm4TlvDq8ikWAM",
      "narrator": "pNInz6obpgDQGcFmaJgB",
      "friendly": "EXAVITQu4vr4xnSDxMaL"
    }
  }
}

Use aliases in commands:

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

1. Enable Voice Wake in macOS App

   1. Open OpenClaw menu bar app
   2. Go to Preferences → Voice Wake
   3. Enable Voice Wake
   4. Choose wake word (default: “Hey Claw”)
2. Grant Microphone Permission

   macOS will prompt for microphone access. Click Allow.

3. Test Voice Wake

   Say your wake word:

   "Hey Claw, what's the weather today?"
   
4. Configure Voice Wake Behavior

   {
     "voiceWake": {
       "enabled": true,
       "wakeWord": "Hey Claw",
       "autoTalk": true,
       "thinkingLevel": "low",
       "deliverToChannel": false
     }
   }
   

iOS Setup

1. Install iOS App

   Build and install the iOS app (see platform docs).

2. Pair as Node

   1. Open the iOS app
   2. Tap Pair Device
   3. Scan the QR code from:
      simpleclaw nodes pair --platform ios
      
3. Enable Voice Wake

   In the iOS app:

   1. Go to Settings
   2. Enable Voice Wake
   3. Grant microphone permission
4. 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

1. Open OpenClaw menu bar app
2. Go to Preferences → Voice Wake
3. Enable Push to Talk
4. Set hotkey (default: Option+Space)
5. 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
  }
}

enabled · boolean · default: "false"

Enable Voice Wake

wakeWord · string · default: "Hey Claw"

Wake word phrase

autoTalk · boolean · default: "true"

Automatically speak responses

thinkingLevel · string · default: "low"

Thinking level for voice requests

deliverToChannel · boolean · default: "false"

Also deliver response to last used channel

timeout · number · default: "30000"

Voice input timeout (ms)

Talk Mode API

Enable Talk Mode

Via WebSocket:

{
  "type": "req",
  "id": "req-1",
  "method": "talk.mode",
  "params": {
    "enabled": true,
    "phase": "full"
  }
}

Phases:

• full - Speak full responses
• summary - Speak summaries only
• off - Disable voice output

Get Talk Configuration

{
  "type": "req",
  "id": "req-2",
  "method": "talk.config",
  "params": {}
}

Response includes current provider, voices, and settings.

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"
      }
    }
  }
}

Responses will include voice message attachments.

Troubleshooting

No audio output

1. Check system volume
2. Verify TTS provider is configured:
   simpleclaw config get talk
   
3. Test provider API key:
   simpleclaw talk test
   

Voice Wake not triggering

1. Check microphone permission in System Settings
2. Verify Voice Wake is enabled:
   simpleclaw config get voiceWake.enabled
   
3. Check Gateway logs:
   simpleclaw gateway logs --tail 50
   

Poor transcription quality

1. Reduce background noise
2. Speak closer to microphone
3. Adjust voice timeout:
   simpleclaw config set voiceWake.timeout 45000 --json
   

High TTS costs

1. Switch to a cheaper provider (OpenAI vs ElevenLabs)
2. Use shorter responses:
   simpleclaw config set talk.maxLength 500 --json
   
3. 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