Voice call plugin

Voice calls for OpenClaw via a plugin: outbound notifications, multi-turn conversations, full-duplex realtime voice, streaming transcription, and inbound calls with allowlist policies.

Providers: mock (dev, no network), plivo (Voice API + XML transfer + GetInput speech), telnyx (Call Control v2), twilio (Programmable Voice + Media Streams).

Quick start

Use the bare package to follow the current release tag. Pin an exact
version only when you need a reproducible install. Restart the Gateway
afterwards so the plugin loads.

Checks plugin enablement, provider credentials, webhook exposure, and
that only one audio mode (`streaming` or `realtime`) is active.

Both are dry runs by default. Add `--yes` to place a short outbound
notify call:

```bash
openclaw voicecall smoke --to "+15555550123" --yes
```

Configuration

If enabled: true but the selected provider is missing credentials, Gateway startup logs a setup-incomplete warning with the missing keys and skips starting the runtime. Commands, RPC calls, and agent tools still return the exact missing configuration when used.

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // or "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio
          toNumber: "+15550005678",
          sessionScope: "per-phone", // per-phone | per-call
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, how can I help?",
              responseSystemPrompt: "You are a concise baseball card specialist.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // optional: us1 | ie1 | au1; defaults to us1
          },
          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Telnyx webhook public key from the Mission Control Portal
            // (Base64; can also be set via TELNYX_PUBLIC_KEY).
            publicKey: "...",
          },
          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

          // Webhook server
          serve: {
            port: 3334,
            path: "/voice/webhook",
          },

          // Webhook security (recommended for tunnels/proxies)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Public exposure (pick one)
          // publicUrl: "https://example.ngrok.app/voice/webhook",
          // tunnel: { provider: "ngrok" },
          // tailscale: { mode: "funnel", path: "/voice/webhook" },

          outbound: {
            defaultMode: "notify", // notify | conversation
          },

          streaming: { enabled: true /* see Streaming transcription */ },
          realtime: { enabled: false /* see Realtime voice conversations */ },
        },
      },
    },
  },
}

Config reference

Top-level keys under plugins.entries.voice-call.config not shown above:

Twilio defaults to its US1 REST endpoint. To process calls in a supported non-US Region, set twilio.region to ie1 or au1 and use credentials from that Region. See Twilio's non-US REST API guide.

- `provider: "log"` → `provider: "mock"`
- `twilio.from` → `fromNumber`
- `streaming.sttProvider` → `streaming.provider`
- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
- `streaming.sttModel` → `streaming.providers.openai.model`
- `streaming.silenceDurationMs` → `streaming.providers.openai.silenceDurationMs`
- `streaming.vadThreshold` → `streaming.providers.openai.vadThreshold`
- `realtime.agentContext.includeSystemPrompt` is removed (realtime context now uses the generated agent prompt)

Session scope

By default, Voice Call uses sessionScope: "per-phone" so repeat calls from the same caller keep conversation memory. Set sessionScope: "per-call" when each carrier call should start with fresh context, for example reception, booking, IVR, or Google Meet bridge flows where the same phone number may represent different meetings.

Voice Call stores generated session keys under the configured agent namespace (agent:<agentId>:voice:*). Raw explicit integration keys resolve into the same namespace: a canonical agent:<configuredAgentId>:* key keeps that owner and honors core session.mainKey/global-scope aliasing; foreign or malformed agent:* input is scoped as an opaque key under the configured agent; global and unknown remain global sentinels.

Realtime voice conversations

realtime selects a full-duplex realtime voice provider for live call audio. It is separate from streaming, which only forwards audio to realtime transcription providers.

Current runtime behavior:

• realtime.enabled is supported for Twilio and Telnyx.
• realtime.provider is optional. If unset, Voice Call uses the first registered realtime voice provider.
• Bundled realtime voice providers: Google Gemini Live (google) and OpenAI (openai), registered by their provider plugins.
• Provider-owned raw config lives under realtime.providers.<providerId>.
• Voice Call exposes the shared openclaw_agent_consult realtime tool by default. The realtime model can call it when the caller asks for deeper reasoning, current information, or normal OpenClaw tools.
• realtime.consultPolicy optionally adds guidance for when the realtime model should call openclaw_agent_consult.
• realtime.agentContext.enabled is default-off. When enabled, Voice Call injects a bounded agent identity and selected workspace-file capsule into the realtime provider instructions at session setup.
• realtime.fastContext.enabled is default-off. When enabled, Voice Call first searches indexed memory/session context for the consult question and returns those snippets to the realtime model within realtime.fastContext.timeoutMs before falling back to the full consult agent only if realtime.fastContext.fallbackToConsult is true.
• If realtime.provider points at an unregistered provider, or no realtime voice provider is registered at all, Voice Call logs a warning and skips realtime media instead of failing the whole plugin.
• inboundPolicy must not be "disabled" when realtime.enabled is true; validateProviderConfig rejects that combination.
• Consult session keys reuse the stored call session when available, then fall back to the configured sessionScope (per-phone by default, or per-call for isolated calls).

Tool policy

realtime.toolPolicy controls the consult run:

realtime.consultPolicy controls only the realtime model instructions:

Agent voice context

Enable realtime.agentContext when the voice bridge should sound like the configured OpenClaw agent without paying a full agent-consult round trip on ordinary turns. The context capsule is added once when the realtime session is created, so it does not add per-turn latency. Calls to openclaw_agent_consult still run the full OpenClaw agent and should be used for tool work, current information, memory lookups, or workspace state.

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          agentId: "main",
          realtime: {
            enabled: true,
            provider: "google",
            toolPolicy: "safe-read-only",
            consultPolicy: "substantive",
            agentContext: {
              enabled: true,
              maxChars: 6000,
              includeIdentity: true,
              includeWorkspaceFiles: true,
              files: ["SOUL.md", "IDENTITY.md", "USER.md"],
            },
          },
        },
      },
    },
  },
}

Realtime provider examples

```json5
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          provider: "twilio",
          inboundPolicy: "allowlist",
          allowFrom: ["+15550005678"],
          realtime: {
            enabled: true,
            provider: "google",
            instructions: "Speak briefly. Call openclaw_agent_consult before using deeper tools.",
            toolPolicy: "safe-read-only",
            consultPolicy: "substantive",
            consultThinkingLevel: "low",
            consultFastMode: true,
            agentContext: { enabled: true },
            providers: {
              google: {
                apiKey: "${GEMINI_API_KEY}",
                model: "gemini-2.5-flash-native-audio-preview-12-2025",
                speakerVoice: "Kore",
                silenceDurationMs: 500,
                startSensitivity: "high",
              },
            },
          },
        },
      },
    },
  },
}
```

See Google provider and OpenAI provider for provider-specific realtime voice options.

Streaming transcription

streaming selects a realtime transcription provider for live call audio.

Current runtime behavior:

• streaming.provider is optional. If unset, Voice Call uses the first registered realtime transcription provider.
• Bundled realtime transcription providers: Deepgram (deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai), and xAI (xai), registered by their provider plugins.
• Provider-owned raw config lives under streaming.providers.<providerId>.
• After Twilio sends an accepted stream start message, Voice Call registers the stream immediately, queues inbound media through the transcription provider while the provider connects, and starts the initial greeting only after realtime transcription is ready.
• If streaming.provider points at an unregistered provider, or none is registered, Voice Call logs a warning and skips media streaming instead of failing the whole plugin.

Streaming provider examples

```json5
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "openai",
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // optional if OPENAI_API_KEY is set
                model: "gpt-4o-transcribe",
                silenceDurationMs: 800,
                vadThreshold: 0.5,
              },
            },
          },
        },
      },
    },
  },
}
```

```json5
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            streamPath: "/voice/stream",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}", // optional if XAI_API_KEY is set
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}
```

TTS for calls

Voice Call uses the core messages.tts configuration for streaming speech on calls. You can override it under the plugin config with the same shape — it deep-merges with messages.tts.

{
  tts: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "pMsXgVXv3BLzUgSXRplE",
        modelId: "eleven_multilingual_v2",
      },
    },
  },
}

Behavior notes:

• Legacy tts.<provider> keys inside plugin config (openai, elevenlabs, microsoft, edge) are repaired by openclaw doctor --fix; committed config should use tts.providers.<provider>.
• Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider-native voices.
• If a Twilio media stream is already active, Voice Call does not fall back to TwiML <Say>. If telephony TTS is unavailable in that state, the playback request fails instead of mixing two playback paths.
• When telephony TTS falls back to a secondary provider, Voice Call logs a warning with the provider chain (from, to, attempts) for debugging.
• When Twilio barge-in or stream teardown clears the pending TTS queue, queued playback requests settle instead of hanging callers awaiting playback completion.

TTS examples

Inbound calls

Inbound policy defaults to disabled. To enable inbound calls, set:

{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Hello! How can I help?",
}

Auto-responses use the agent system. Tune with responseModel, responseSystemPrompt, and responseTimeoutMs.

Per-number routing

Use numbers when one Voice Call plugin receives calls for multiple phone numbers and each number should behave like a different line. For example, one number can use a casual personal assistant while another uses a business persona, a different response agent, and a different TTS voice.

Routes are selected from the provider-supplied dialed To number. Keys must be E.164 numbers. When a call arrives, Voice Call resolves the matching route once, stores the matched route on the call record, and reuses that effective config for the greeting, classic auto-response path, realtime consult path, and TTS playback. If no route matches, the global Voice Call config is used. Outbound calls do not use numbers; pass the outbound target, message, and session explicitly when initiating the call.

Route overrides currently support:

• inboundGreeting
• tts
• agentId
• responseModel
• responseSystemPrompt
• responseTimeoutMs

The tts route value deep-merges over the global Voice Call tts config, so you can usually override only the provider voice:

{
  inboundGreeting: "Hello from the main line.",
  responseSystemPrompt: "You are the default voice assistant.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, how can I help?",
      responseSystemPrompt: "You are a concise baseball card specialist.",
      tts: {
        providers: {
          openai: { speakerVoice: "alloy" },
        },
      },
    },
  },
}

Spoken output contract

For auto-responses, Voice Call appends a strict spoken-output contract to the system prompt requiring a {"spoken":"..."} JSON reply. Voice Call extracts speech text defensively:

• Ignores payloads marked as reasoning/error content.
• Parses direct JSON, fenced JSON, or inline "spoken" keys.
• Falls back to plain text and removes likely planning/meta lead-in paragraphs.

This keeps spoken playback focused on caller-facing text and avoids leaking planning text into audio.

Conversation startup behavior

For outbound conversation calls, first-message handling is tied to live playback state:

• Barge-in queue clear and auto-response are suppressed only while the initial greeting is actively speaking.
• If initial playback fails, the call returns to listening and the initial message remains queued for retry.
• Initial playback for Twilio streaming starts on stream connect without extra delay.
• Barge-in aborts active playback and clears queued-but-not-yet-playing Twilio TTS entries. Cleared entries resolve as skipped, so follow-up response logic can continue without waiting on audio that will never play.
• Realtime voice conversations use the realtime stream's own opening turn. Voice Call does not post a legacy <Say> TwiML update for that initial message, so outbound <Connect><Stream> sessions stay attached.

Twilio stream disconnect grace

When a Twilio media stream disconnects, Voice Call waits 2000 ms before auto-ending the call:

• If the stream reconnects during that window, auto-end is canceled.
• If no stream re-registers after the grace period, the call is ended to prevent stuck active calls.

Stale call reaper

Use staleCallReaperSeconds (default 120) to end calls that are never answered and never reach a live conversation state, for example notify-mode calls where the provider never delivers a terminal webhook. Set it to 0 to disable.

The reaper runs every 30 seconds and only ends calls that have no answeredAt timestamp and are not already in a terminal or live (speaking/listening) state, so answered conversations are never reaped by this timer; maxDurationSeconds (default 300) is the separate cap that ends answered calls that run too long.

For notify-style flows where carriers can be slow to deliver ring/answer webhooks, raise staleCallReaperSeconds past the default so slow-but-normal calls are not reaped early; 120-300 seconds is a reasonable production range.

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          maxDurationSeconds: 300,
          staleCallReaperSeconds: 120,
        },
      },
    },
  },
}

Webhook security

When a proxy or tunnel sits in front of the Gateway, the plugin reconstructs the public URL for signature verification. These options control which forwarded headers are trusted:

Additional protections:

• Webhook replay protection is enabled for Twilio, Telnyx, and Plivo. Replayed valid webhook requests are acknowledged but skipped for side effects.
• Twilio conversation turns include a per-turn token in <Gather> callbacks, so stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.
• Unauthenticated webhook requests are rejected before body reads when the provider's required signature headers are missing.
• The voice-call webhook uses the shared pre-auth body-read profile (64 KB max body, 5-second read timeout) plus a per-key in-flight cap (8 concurrent requests per key by default) before signature verification.

Example with a stable public host:

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          publicUrl: "https://voice.example.com/voice/webhook",
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
          },
        },
      },
    },
  },
}

CLI

openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
openclaw voicecall start --to "+15555550123"   # alias for call
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall speak --call-id <id> --message "One moment"
openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
openclaw voicecall end --call-id <id>
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw voicecall latency                      # summarize turn latency from logs
openclaw voicecall expose --mode funnel

When the Gateway is already running, operational voicecall commands delegate to the Gateway-owned voice-call runtime so the CLI does not bind a second webhook server. If no Gateway is reachable, the commands fall back to a standalone CLI runtime.

latency reads calls.jsonl from the default voice-call storage path. Use --file <path> to point at a different log and --last <n> to limit analysis to the last N records (default 200). Output includes min/max/avg, p50, and p95 for turn latency and listen-wait times.

Agent tool

Tool name: voice_call.

The voice-call plugin ships a matching agent skill.

Gateway RPC

dtmfSequence is only valid with mode: "conversation"; notify-mode calls should use voicecall.dtmf after the call exists if they need post-connect digits.

Troubleshooting

Setup fails webhook exposure

Run setup from the same environment that runs the Gateway:

openclaw voicecall setup
openclaw voicecall setup --json

For twilio, telnyx, and plivo, webhook-exposure must be green. A configured publicUrl still fails when it points at local or private network space, because the carrier cannot call back into those addresses. Do not use localhost, 127.0.0.1, 0.0.0.0, 10.x, 172.16.x-172.31.x, 192.168.x, 169.254.x, fc00::/7, fd00::/8, or other carrier-grade-NAT ranges as publicUrl.

Twilio notify-mode outbound calls send their initial <Say> TwiML directly in the create-call request, so the first spoken message does not depend on Twilio fetching webhook TwiML. A public webhook is still required for status callbacks, conversation calls, pre-connect DTMF, realtime streams, and post-connect call control.

Use one public exposure path:

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          publicUrl: "https://voice.example.com/voice/webhook",
          // or
          tunnel: { provider: "ngrok" },
          // or
          tailscale: { mode: "funnel", path: "/voice/webhook" },
        },
      },
    },
  },
}

After changing config, restart or reload the Gateway, then run:

openclaw voicecall setup
openclaw voicecall smoke

voicecall smoke is a dry run unless you pass --yes.

Provider credentials fail

Check the selected provider and the required credential fields:

• Twilio: twilio.accountSid, twilio.authToken, and fromNumber, or TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_FROM_NUMBER.
• Telnyx: telnyx.apiKey, telnyx.connectionId, telnyx.publicKey, and fromNumber, or TELNYX_API_KEY, TELNYX_CONNECTION_ID, and TELNYX_PUBLIC_KEY.
• Plivo: plivo.authId, plivo.authToken, and fromNumber, or PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN.

Credentials must exist on the Gateway host. Editing a local shell profile does not affect an already running Gateway until it restarts or reloads its environment.

Calls start but provider webhooks do not arrive

Confirm the provider console points at the exact public webhook URL:

https://voice.example.com/voice/webhook

Then inspect runtime state:

openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw logs --follow

Common causes:

• publicUrl points at a different path than serve.path.
• The tunnel URL changed after the Gateway started.
• A proxy forwards the request but strips or rewrites host/proto headers.
• Firewall or DNS routes the public hostname somewhere other than the Gateway.
• The Gateway was restarted without the Voice Call plugin enabled.

When a reverse proxy or tunnel is in front of the Gateway, set webhookSecurity.allowedHosts to the public hostname, or use webhookSecurity.trustedProxyIPs for a known proxy address. Use webhookSecurity.trustForwardingHeaders only when the proxy boundary is under your control.

Signature verification fails

Provider signatures are checked against the public URL OpenClaw reconstructs from the incoming request. If signatures fail:

• Confirm the provider webhook URL exactly matches publicUrl, including scheme, host, and path.
• For ngrok free-tier URLs, update publicUrl when the tunnel hostname changes.
• Ensure the proxy preserves the original host and proto headers, or configure webhookSecurity.allowedHosts.
• Do not enable skipSignatureVerification outside local testing.

Google Meet Twilio joins fail

Google Meet uses this plugin for Twilio dial-in joins. First verify Voice Call:

openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"

Then verify the Google Meet transport explicitly:

openclaw googlemeet setup --transport twilio

If Voice Call is green but the Meet participant never joins, check the Meet dial-in number, PIN, and --dtmf-sequence. The phone call can be healthy while the meeting rejects or ignores an incorrect DTMF sequence.

Google Meet starts the Twilio phone leg through voicecall.start with a pre-connect DTMF sequence. PIN-derived sequences include the Google Meet plugin's voiceCall.dtmfDelayMs (default 12000 ms) as leading Twilio wait digits, because Meet dial-in prompts can arrive late. Voice Call then redirects back to realtime handling before the intro greeting is requested.

Use openclaw logs --follow for the live phase trace. A healthy Twilio Meet join logs this order:

• Google Meet delegates the Twilio join to Voice Call.
• Voice Call stores pre-connect DTMF TwiML.
• Twilio initial TwiML is consumed and served before realtime handling.
• Voice Call serves realtime TwiML for the Twilio call.
• Google Meet requests intro speech with voicecall.speak after the post-DTMF delay.

openclaw voicecall tail still shows persisted call records; useful for call state and transcripts, but not every webhook/realtime transition appears there.

Realtime call has no speech

Confirm only one audio mode is enabled: realtime.enabled and streaming.enabled cannot both be true.

For realtime Twilio/Telnyx calls, also verify:

• A realtime provider plugin is loaded and registered.
• realtime.provider is unset or names a registered provider.
• The provider API key is available to the Gateway process.
• openclaw logs --follow shows realtime TwiML served, the realtime bridge started, and the initial greeting queued.

Related

• Talk mode
• Text-to-speech
• Voice wake