Spraakoproepplugin

​

Snel aan de slag

openclaw plugins install @openclaw/voice-call

PLUGIN_SRC=./path/to/local/voice-call-plugin
openclaw plugins install "$PLUGIN_SRC"
cd "$PLUGIN_SRC" && pnpm install

openclaw voicecall setup
openclaw voicecall setup --json

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

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

​

Configuratie

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // of "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // of TWILIO_FROM_NUMBER voor Twilio
          toNumber: "+15550005678",
          sessionScope: "per-phone", // per-phone | per-call
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, hoe kan ik helpen?",
              responseSystemPrompt: "Je bent een beknopte specialist in honkbalkaarten.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // optioneel: us1 | ie1 | au1; standaard us1
          },
          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Openbare sleutel voor Telnyx-webhooks uit het Mission Control Portal
            // (Base64; kan ook via TELNYX_PUBLIC_KEY worden ingesteld).
            publicKey: "...",
          },
          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

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

          // Webhookbeveiliging (aanbevolen voor tunnels/proxy's)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Openbare beschikbaarstelling (kies er één)
          // publicUrl: "https://example.ngrok.app/voice/webhook",
          // tunnel: { provider: "ngrok" },
          // tailscale: { mode: "funnel", path: "/voice/webhook" },

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

          streaming: { enabled: true /* alleen Twilio; zie Streaming transcriptie */ },
          realtime: { enabled: false /* zie Realtime spraakgesprekken */ },
        },
      },
    },
  },
}

​

Configuratiereferentie

​

Sessiebereik

​

Realtime spraakgesprekken

• realtime.enabled wordt ondersteund voor Twilio en Telnyx.
• realtime.provider is optioneel. Als dit niet is ingesteld, gebruikt Voice Call de eerste geregistreerde realtime-spraakprovider.
• Gebundelde realtime-spraakproviders: Google Gemini Live (google) en OpenAI (openai), geregistreerd door hun providerplugins.
• Door de provider beheerde onbewerkte configuratie staat onder realtime.providers.<providerId>.
• Voice Call stelt standaard de gedeelde realtime-tool openclaw_agent_consult beschikbaar. Het realtime-model kan deze aanroepen wanneer de beller om diepgaandere redenering, actuele informatie of normale OpenClaw-tools vraagt.
• realtime.consultPolicy voegt optioneel richtlijnen toe voor wanneer het realtime-model openclaw_agent_consult moet aanroepen.
• realtime.agentContext.enabled is standaard uitgeschakeld. Wanneer dit is ingeschakeld, voegt Voice Call tijdens het instellen van de sessie een begrensde agentidentiteit en een geselecteerde capsule met werkruimtebestanden toe aan de instructies voor de realtime-provider.
• realtime.fastContext.enabled is standaard uitgeschakeld. Wanneer dit is ingeschakeld, doorzoekt Voice Call eerst de geïndexeerde geheugen-/sessiecontext voor de consultatievraag en retourneert die fragmenten binnen realtime.fastContext.timeoutMs aan het realtime-model, voordat alleen op de volledige consultatieagent wordt teruggevallen als realtime.fastContext.fallbackToConsult waar is.
• Als realtime.provider naar een niet-geregistreerde provider verwijst, of er helemaal geen realtime-spraakprovider is geregistreerd, registreert Voice Call een waarschuwing en slaat het realtime-media over in plaats van de hele plugin te laten mislukken.
• inboundPolicy mag niet "disabled" zijn wanneer realtime.enabled waar is; validateProviderConfig wijst die combinatie af.
• Consultatiesessiesleutels gebruiken waar mogelijk de opgeslagen oproepsessie opnieuw en vallen daarna terug op de geconfigureerde sessionScope (standaard per-phone, of per-call voor geïsoleerde oproepen).

​

Toolbeleid

​

Spraakcontext van de agent

{
  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"],
            },
          },
        },
      },
    },
  },
}

​

Voorbeelden van realtime-providers

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          provider: "twilio",
          inboundPolicy: "allowlist",
          allowFrom: ["+15550005678"],
          realtime: {
            enabled: true,
            provider: "google",
            instructions: "Spreek kort. Roep openclaw_agent_consult aan voordat je diepgaandere tools gebruikt.",
            toolPolicy: "safe-read-only",
            consultPolicy: "substantive",
            consultThinkingLevel: "low",
            consultFastMode: true,
            agentContext: { enabled: true },
            providers: {
              google: {
                apiKey: "${GEMINI_API_KEY}",
                model: "gemini-3.1-flash-live-preview",
                speakerVoice: "Kore",
                silenceDurationMs: 500,
                startSensitivity: "high",
              },
            },
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          realtime: {
            enabled: true,
            provider: "openai",
            providers: {
              openai: { apiKey: "${OPENAI_API_KEY}" },
            },
          },
        },
      },
    },
  },
}

​

Streamingtranscriptie

• streaming.provider is optioneel. Als dit niet is ingesteld, gebruikt Voice Call de eerste geregistreerde realtime-transcriptieprovider.
• Gebundelde realtime-transcriptieproviders: Deepgram (deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai) en xAI (xai), geregistreerd door hun providerplugins.
• Door de provider beheerde onbewerkte configuratie staat onder streaming.providers.<providerId>.
• Nadat Twilio een geaccepteerd streambericht start verzendt, registreert Voice Call de stream onmiddellijk, plaatst het binnenkomende media via de transcriptieprovider in de wachtrij terwijl de provider verbinding maakt en start het de eerste begroeting pas wanneer realtime-transcriptie gereed is.
• Als streaming.provider naar een niet-geregistreerde provider verwijst, of er geen is geregistreerd, registreert Voice Call een waarschuwing en slaat het mediastreaming over in plaats van de hele plugin te laten mislukken.

​

Voorbeelden van streamingproviders

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

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            streamPath: "/voice/stream",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}", // optioneel als XAI_API_KEY is ingesteld
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

​

TTS voor oproepen

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

• Verouderde tts.<provider>-sleutels binnen de pluginconfiguratie (openai, elevenlabs, microsoft, edge) worden hersteld door openclaw doctor --fix; vastgelegde configuratie moet tts.providers.<provider> gebruiken.
• Kern-TTS wordt gebruikt wanneer Twilio-mediastreaming is ingeschakeld; anders vallen oproepen terug op providerspecifieke stemmen.
• Als er al een Twilio-mediastream actief is, valt Voice Call niet terug op TwiML <Say>. Als telefonie-TTS in die toestand niet beschikbaar is, mislukt het afspeelverzoek in plaats van twee afspeelpaden te combineren.
• Wanneer telefonie-TTS terugvalt op een secundaire provider, registreert Voice Call voor foutopsporing een waarschuwing met de providerketen (from, to, attempts).
• Wanneer Twilio-barge-in of het afbreken van de stream de wachtende TTS-wachtrij wist, worden in de wachtrij geplaatste afspeelverzoeken afgehandeld in plaats van bellers die op voltooiing van het afspelen wachten te laten hangen.

​

TTS-voorbeelden

{
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "alloy" },
    },
  },
}

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          tts: {
            provider: "elevenlabs",
            providers: {
              elevenlabs: {
                apiKey: "elevenlabs_key",
                speakerVoiceId: "pMsXgVXv3BLzUgSXRplE",
                modelId: "eleven_multilingual_v2",
              },
            },
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          tts: {
            providers: {
              openai: {
                model: "gpt-4o-mini-tts",
                speakerVoice: "marin",
              },
            },
          },
        },
      },
    },
  },
}

​

Inkomende oproepen

{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Hallo! Hoe kan ik helpen?",
}

​

Routering per nummer

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

{
  inboundGreeting: "Hallo vanaf de hoofdlijn.",
  responseSystemPrompt: "Je bent de standaard spraakassistent.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, hoe kan ik helpen?",
      responseSystemPrompt: "Je bent een beknopte specialist in honkbalkaarten.",
      tts: {
        providers: {
          openai: { speakerVoice: "alloy" },
        },
      },
    },
  },
}

​

Contract voor gesproken uitvoer

• Negeert payloads die als redeneer-/foutinhoud zijn gemarkeerd.
• Parseert rechtstreekse JSON, JSON in een codeblok of inline sleutels van het type "spoken".
• Valt terug op platte tekst en verwijdert waarschijnlijke inleidende alinea’s met planning/metatekst.

​

Gedrag bij het starten van een gesprek

• Het wissen van de wachtrij bij onderbreken en automatisch antwoorden worden alleen onderdrukt zolang de eerste begroeting actief wordt uitgesproken.
• Als de eerste weergave mislukt, keert de oproep terug naar listening en blijft het eerste bericht in de wachtrij staan om opnieuw te proberen.
• De eerste weergave voor Twilio-streaming begint zonder extra vertraging zodra de stream verbinding maakt.
• Onderbreken breekt actieve weergave af en wist Twilio TTS-items die in de wachtrij staan maar nog niet worden afgespeeld. Gewiste items worden als overgeslagen afgehandeld, zodat de vervolglogica voor antwoorden kan doorgaan zonder te wachten op audio die nooit zal worden afgespeeld.
• Realtime spraakgesprekken gebruiken de eigen openingsbeurt van de realtime stream. Voice Call plaatst geen verouderde TwiML-update van het type <Say> voor dat eerste bericht, zodat uitgaande sessies van het type <Connect><Stream> verbonden blijven.

​

Respijtperiode bij verbreken van Twilio-stream

• Als de stream binnen die periode opnieuw verbinding maakt, wordt het automatisch beëindigen geannuleerd.
• Als na de respijtperiode geen stream opnieuw wordt geregistreerd, wordt de oproep beëindigd om vastgelopen actieve oproepen te voorkomen.

​

Opruimer voor verouderde oproepen

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

​

Webhook-beveiliging

• Webhook-beveiliging tegen herhaling is ingeschakeld voor Twilio, Telnyx en Plivo. Herhaalde geldige Webhook-verzoeken worden bevestigd, maar bijwerkingen worden overgeslagen.
• Twilio-gespreksbeurten bevatten een token per beurt in callbacks van het type <Gather>, zodat verouderde/herhaalde spraakcallbacks niet kunnen voldoen aan een nieuwere wachtende transcriptiebeurt.
• Niet-geverifieerde Webhook-verzoeken worden vóór het lezen van de body geweigerd wanneer de vereiste handtekeningheaders van de provider ontbreken.
• De voice-call-Webhook gebruikt vóór handtekeningverificatie het gedeelde profiel voor het lezen van de body vóór authenticatie (maximale body van 64 KB, leestime-out van 5 seconden), plus een limiet per sleutel voor gelijktijdig verwerkte verzoeken (standaard 8 gelijktijdige verzoeken per sleutel).

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

​

CLI

openclaw voicecall call --to "+15555550123" --message "Hallo van OpenClaw"
openclaw voicecall start --to "+15555550123"   # alias voor call
openclaw voicecall continue --call-id <id> --message "Nog vragen?"
openclaw voicecall speak --call-id <id> --message "Een ogenblik"
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                      # vat de latentie per beurt samen op basis van logboeken
openclaw voicecall expose --mode funnel

​

Agenttool

​

Gateway-RPC

​

Probleemoplossing

​

Instellen van webhooktoegang mislukt

openclaw voicecall setup
openclaw voicecall setup --json

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

openclaw voicecall setup
openclaw voicecall smoke

​

Providerreferenties mislukken

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

​

Gesprekken starten, maar providerwebhooks komen niet aan

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

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

• publicUrl verwijst naar een ander pad dan serve.path.
• De tunnel-URL is gewijzigd nadat de Gateway is gestart.
• Een proxy stuurt het verzoek door, maar verwijdert of herschrijft host-/protoheaders.
• De firewall of DNS routeert de openbare hostnaam naar een andere locatie dan de Gateway.
• De Gateway is opnieuw gestart zonder dat de Voice Call-plugin was ingeschakeld.

​

Handtekeningverificatie mislukt

• Controleer of de webhook-URL van de provider exact overeenkomt met publicUrl, inclusief schema, host en pad.
• Werk bij gratis ngrok-URL’s publicUrl bij wanneer de tunnelhostnaam verandert.
• Zorg dat de proxy de oorspronkelijke host- en protoheaders behoudt of configureer webhookSecurity.allowedHosts.
• Schakel skipSignatureVerification niet in buiten lokale tests.

​

Deelname aan Google Meet via Twilio mislukt

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

openclaw googlemeet setup --transport twilio

• Google Meet delegeert de Twilio-deelname aan Voice Call.
• Voice Call slaat DTMF-TwiML voor het verbinden op.
• De initiële TwiML van Twilio wordt verwerkt en aangeboden vóór de realtime-afhandeling.
• Voice Call biedt realtime-TwiML aan voor het Twilio-gesprek.
• Google Meet vraagt na de vertraging na DTMF om introductiespraak met voicecall.speak.

​

Realtime-gesprek heeft geen spraak

• Er is een realtime-providerplugin geladen en geregistreerd.
• realtime.provider is niet ingesteld of noemt een geregistreerde provider.
• De API-sleutel van de provider is beschikbaar voor het Gateway-proces.
• openclaw logs --follow toont dat realtime-TwiML is aangeboden, de realtime-bridge is gestart en de initiële begroeting in de wachtrij is geplaatst.

​

Gerelateerd

• Gespreksmodus
• Tekst-naar-spraak
• Spraakactivering