Voice Agent — Real-Time Phone Calls

openclaw plugins install @openclaw/voice-call

You are helping me set up the @openclaw/voice-call plugin for real-time voice
conversations. Please follow these steps carefully and do not skip any.

OBJECTIVE
Configure OpenClaw to make and receive phone calls via Twilio with Google
Gemini Live realtime audio (full-duplex conversation).

PREREQUISITES I HAVE
- OpenClaw is running and you can edit ~/.openclaw/openclaw.json
- @openclaw/voice-call plugin is installed (if not, run: openclaw plugins install @openclaw/voice-call)

WHAT I NEED FROM YOU
Ask me for these credentials one at a time (do not ask for all at once):
1. My Twilio Account SID
2. My Twilio Auth Token
3. My Twilio phone number (E.164 format, e.g. +1855XXXXXXX)
4. My cell phone number (to whitelist for inbound calls)
5. My Gemini API key (from https://aistudio.google.com/apikey — should start with AIza or AQ.)
6. My public hostname where OpenClaw is reachable (for Twilio webhook, e.g. myhost.example.com)

STEPS TO EXECUTE

Step A — Verify the Gemini key works for realtime
Run: curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-2.5-flash-native-audio-preview-12-2025?key=MY_KEY"
Expected response should include "bidiGenerateContent" in supportedGenerationMethods.
If it fails, tell me to generate a new key.

Step B — Add GEMINI_API_KEY to env in openclaw.json
Add the key under the "env" block.

Step C — Add voice-call plugin config to plugins.entries
Use this template, filling in credentials:
{
  "voice-call": {
    "enabled": true,
    "config": {
      "provider": "twilio",
      "fromNumber": "MY_TWILIO_PHONE",
      "publicUrl": "https://MY_HOST/voice/webhook",
      "twilio": {
        "accountSid": "MY_TWILIO_SID",
        "authToken": "MY_AUTH_TOKEN"
      },
      "outbound": { "defaultMode": "conversation" },
      "skipSignatureVerification": true,
      "serve": { "bind": "0.0.0.0", "port": 3334 },
      "inboundPolicy": "allowlist",
      "allowFrom": ["MY_CELL_NUMBER"],
      "inboundGreeting": "Hello, this is [NAME]. How can I help you?",
      "realtime": {
        "enabled": true,
        "provider": "google",
        "providers": {
          "google": {
            "model": "gemini-2.5-flash-native-audio-preview-12-2025",
            "apiKey": "MY_GEMINI_KEY"
          }
        }
      }
    }
  }
}

CRITICAL RULES:
- Paste the actual Gemini key directly in apiKey — do NOT use __ENV_GEMINI_API_KEY__
  reference (env vars can be stale in containers)
- Do NOT include tts or streaming blocks — they conflict with realtime
- The model MUST be "gemini-2.5-flash-native-audio-preview-12-2025" — NOT
  "gemini-2.5-flash" (doesn't support bidi)

Step D — Expose the port (HyperClaw only)
Go to Settings → Public Services and enable port 3334. Without this, Twilio
cannot reach the voice endpoint.

Step E — Configure Twilio webhook
In Twilio Console, go to your phone number settings and set the Voice webhook
URL to https://MY_HOST/voice/webhook (HTTP POST).

Step F — Create a restore script
Write a script at ~/.openclaw/workspace/voice-call-config-restore.sh that
reapplies this config on pod restart. Add a note to HEARTBEAT.md to check the
plugin on startup.

Step G — Restart the gateway
Run: openclaw gateway restart

Step H — Test
Make a test call to my cell with:
voice_call({ action: "initiate_call", to: "MY_CELL", mode: "conversation",
message: "Hey, testing the voice setup. Can you hear me?" })

TROUBLESHOOTING REFERENCE
- Silent call: API key format is wrong — paste it inline, not as an env var reference
- session.error → closed on inbound: key may be expired (AQ. tokens are short-lived)
  or model name is wrong
- Gateway restart doesn't pick up changes: zombie child processes — SIGUSR1 can fail
  in containers, try a full restart