Sprachanruf-Plugin

​

Schnellstart

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 smoke
openclaw voicecall smoke --to "+15555550123"

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

​

Konfiguration

{
  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: "...",
          },
          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 */ },
        },
      },
    },
  },
}

​

Sitzungsbereich

​

Echtzeit-Sprachkonversationen

• realtime.enabled wird für Twilio Media Streams unterstützt.
• realtime.provider ist optional. Wenn es nicht gesetzt ist, verwendet Voice Call den ersten registrierten Echtzeit-Sprach-Provider.
• Gebündelte Echtzeit-Sprach-Provider: Google Gemini Live (google) und OpenAI (openai), registriert durch ihre Provider-Plugins.
• Provider-eigene Rohkonfiguration liegt unter realtime.providers.<providerId>.
• Voice Call stellt standardmäßig das gemeinsame Echtzeit-Tool openclaw_agent_consult bereit. Das Echtzeitmodell kann es aufrufen, wenn der Anrufer nach tieferer Analyse, aktuellen Informationen oder normalen OpenClaw-Tools fragt.
• realtime.consultPolicy fügt optional Hinweise hinzu, wann das Echtzeitmodell openclaw_agent_consult aufrufen sollte.
• realtime.agentContext.enabled ist standardmäßig deaktiviert. Wenn aktiviert, injiziert Voice Call beim Sitzungsaufbau eine begrenzte Agent-Identität und eine ausgewählte Workspace-Dateikapsel in die Anweisungen des Echtzeit-Providers.
• realtime.fastContext.enabled ist standardmäßig deaktiviert. Wenn aktiviert, durchsucht Voice Call zuerst indexierten Speicher/Sitzungskontext nach der Consult-Frage und gibt diese Ausschnitte innerhalb von realtime.fastContext.timeoutMs an das Echtzeitmodell zurück, bevor nur dann auf den vollständigen Consult-Agent zurückgefallen wird, wenn realtime.fastContext.fallbackToConsult true ist.
• Wenn realtime.provider auf einen nicht registrierten Provider verweist oder überhaupt kein Echtzeit-Sprach-Provider registriert ist, protokolliert Voice Call eine Warnung und überspringt Echtzeitmedien, statt das gesamte Plugin fehlschlagen zu lassen.
• Consult-Sitzungsschlüssel verwenden die gespeicherte Anrufsitzung erneut, wenn verfügbar, und fallen anschließend auf den konfigurierten sessionScope zurück (per-phone standardmäßig oder per-call für isolierte Anrufe).

​

Tool-Richtlinie

​

Agent-Sprachkontext

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

​

Beispiele für Realtime-Provider

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

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

​

Streaming-Transkription

• streaming.provider ist optional. Wenn nicht gesetzt, verwendet Voice Call den ersten registrierten Realtime-Transkriptions-Provider.
• Gebündelte Realtime-Transkriptions-Provider: Deepgram (deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai) und xAI (xai), registriert durch ihre Provider-Plugins.
• Provider-eigene Rohkonfiguration liegt unter streaming.providers.<providerId>.
• Nachdem Twilio eine akzeptierte Stream-start-Nachricht sendet, registriert Voice Call den Stream sofort, stellt eingehende Medien über den Transkriptions-Provider in die Warteschlange, während der Provider verbindet, und startet die anfängliche Begrüßung erst, wenn die Realtime-Transkription bereit ist.
• Wenn streaming.provider auf einen nicht registrierten Provider verweist oder keiner registriert ist, protokolliert Voice Call eine Warnung und überspringt Media-Streaming, statt das gesamte Plugin fehlschlagen zu lassen.

​

Beispiele für Streaming-Provider

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

{
  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 für Anrufe

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

• Legacy-tts.<provider>-Schlüssel innerhalb der Plugin-Konfiguration (openai, elevenlabs, microsoft, edge) werden durch openclaw doctor --fix repariert; eingecheckte Konfiguration sollte tts.providers.<provider> verwenden.
• Core-TTS wird verwendet, wenn Twilio-Media-Streaming aktiviert ist; andernfalls fallen Anrufe auf Provider-native Stimmen zurück.
• Wenn ein Twilio-Media-Stream bereits aktiv ist, fällt Voice Call nicht auf TwiML <Say> zurück. Wenn Telefonie-TTS in diesem Zustand nicht verfügbar ist, schlägt die Wiedergabeanforderung fehl, statt zwei Wiedergabepfade zu mischen.
• Wenn Telefonie-TTS auf einen sekundären Provider zurückfällt, protokolliert Voice Call zur Fehlersuche eine Warnung mit der Provider-Kette (from, to, attempts).
• Wenn Twilio-Barge-In oder Stream-Abbau die ausstehende TTS-Warteschlange leert, werden eingereihte Wiedergabeanforderungen abgeschlossen, statt Anrufer beim Warten auf den Abschluss der Wiedergabe hängen zu lassen.

​

TTS-Beispiele

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

​

Eingehende Anrufe

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

​

Routing pro Nummer

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

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

​

Vertrag für gesprochene Ausgabe

{"spoken":"..."}

• Ignoriert Payloads, die als Reasoning-/Fehlerinhalte markiert sind.
• Parst direktes JSON, eingezäuntes JSON oder Inline-"spoken"-Schlüssel.
• Fällt auf Klartext zurück und entfernt wahrscheinliche Planungs-/Meta-Einleitungsabsätze.

​

Startverhalten von Konversationen

• Leeren der Barge-In-Warteschlange und Auto-Response werden nur unterdrückt, während die anfängliche Begrüßung aktiv gesprochen wird.
• Wenn die anfängliche Wiedergabe fehlschlägt, kehrt der Anruf zu listening zurück, und die anfängliche Nachricht bleibt für einen erneuten Versuch in der Warteschlange.
• Die anfängliche Wiedergabe für Twilio-Streaming startet beim Verbinden des Streams ohne zusätzliche Verzögerung.
• Barge-In bricht aktive Wiedergabe ab und leert eingereihte, aber noch nicht wiedergegebene Twilio-TTS-Einträge. Geleerte Einträge werden als übersprungen aufgelöst, sodass nachfolgende Antwortlogik fortfahren kann, ohne auf Audio zu warten, das nie abgespielt wird.
• Realtime-Sprachkonversationen verwenden den eigenen Eröffnungs-Turn des Realtime-Streams. Voice Call sendet für diese anfängliche Nachricht kein Legacy-<Say>-TwiML-Update, sodass ausgehende <Connect><Stream>-Sitzungen verbunden bleiben.

​

Schonfrist bei Trennung des Twilio-Streams

• Wenn sich der Stream innerhalb dieses Zeitfensters erneut verbindet, wird das automatische Beenden abgebrochen.
• Wenn nach der Kulanzzeit kein Stream erneut registriert wird, wird der Anruf beendet, um hängende aktive Anrufe zu verhindern.

​

Bereinigung veralteter Anrufe

• Produktion: 120–300 Sekunden für Benachrichtigungs-Flows.
• Halten Sie diesen Wert höher als maxDurationSeconds, damit normale Anrufe abgeschlossen werden können. Ein guter Ausgangspunkt ist maxDurationSeconds + 30–60 Sekunden.

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

​

Webhook-Sicherheit

• Webhook-Replay-Schutz ist für Twilio und Plivo aktiviert. Wiederholte gültige Webhook-Anfragen werden bestätigt, aber für Seiteneffekte übersprungen.
• Twilio-Konversationsdurchläufe enthalten ein Token pro Durchlauf in <Gather>-Callbacks, sodass veraltete oder wiederholte Sprach-Callbacks keinen neueren ausstehenden Transkript-Durchlauf erfüllen können.
• Nicht authentifizierte Webhook-Anfragen werden vor dem Lesen des Bodys abgewiesen, wenn die erforderlichen Signatur-Header des Providers fehlen.
• Der Voice-Call-Webhook verwendet das gemeinsame Pre-Auth-Body-Profil (64 KB / 5 Sekunden) plus eine In-Flight-Obergrenze pro IP vor der Signaturprüfung.

{
  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

​

Agent-Tool

​

Gateway-RPC

​

Fehlerbehebung

​

Einrichtung schlägt bei Webhook-Exposition fehl

openclaw voicecall setup
openclaw voicecall setup --json

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

openclaw voicecall setup
openclaw voicecall smoke

​

Provider-Anmeldedaten schlagen fehl

• Twilio: twilio.accountSid, twilio.authToken und fromNumber oder TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN und TWILIO_FROM_NUMBER.
• Telnyx: telnyx.apiKey, telnyx.connectionId, telnyx.publicKey und fromNumber.
• Plivo: plivo.authId, plivo.authToken und fromNumber.

​

Anrufe starten, aber Provider-Webhooks kommen nicht an

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

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

• publicUrl zeigt auf einen anderen Pfad als serve.path.
• Die Tunnel-URL hat sich geändert, nachdem das Gateway gestartet wurde.
• Ein Proxy leitet die Anfrage weiter, entfernt oder überschreibt aber Host-/Proto-Header.
• Firewall oder DNS leiten den öffentlichen Hostnamen an einen anderen Ort als das Gateway.
• Das Gateway wurde ohne aktiviertes Voice-Call-Plugin neu gestartet.

​

Signaturprüfung schlägt fehl

• Bestätigen Sie, dass die Provider-Webhook-URL exakt mit publicUrl übereinstimmt, einschließlich Schema, Host und Pfad.
• Aktualisieren Sie bei ngrok-Free-Tier-URLs publicUrl, wenn sich der Tunnel-Hostname ändert.
• Stellen Sie sicher, dass der Proxy die ursprünglichen Host- und Proto-Header beibehält, oder konfigurieren Sie webhookSecurity.allowedHosts.
• Aktivieren Sie skipSignatureVerification nicht außerhalb lokaler Tests.

​

Google Meet Twilio-Beitritte schlagen fehl

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

openclaw googlemeet setup --transport twilio

• Google Meet delegiert den Twilio-Beitritt an Voice Call.
• Voice Call speichert Pre-Connect-DTMF-TwiML.
• Initiales Twilio-TwiML wird verbraucht und vor der Echtzeit-Verarbeitung bereitgestellt.
• Voice Call stellt Echtzeit-TwiML für den Twilio-Anruf bereit.
• Google Meet fordert nach der Post-DTMF-Verzögerung Begrüßungssprache mit voicecall.speak an.

​

Echtzeitanruf hat keine Sprache

• Ein Echtzeit-Provider-Plugin ist geladen und registriert.
• realtime.provider ist nicht gesetzt oder benennt einen registrierten Provider.
• Der API-Schlüssel des Providers ist für den Gateway-Prozess verfügbar.
• openclaw logs --follow zeigt, dass Echtzeit-TwiML bereitgestellt, die Echtzeit-Bridge gestartet und die initiale Begrüßung eingereiht wurde.

​

Verwandt

• Sprechmodus
• Text-to-speech
• Sprachaktivierung