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 setup --json

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

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

​

Konfiguration

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // oder "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // oder TWILIO_FROM_NUMBER für Twilio
          toNumber: "+15550005678",
          sessionScope: "per-phone", // per-phone | per-call
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, wie kann ich Ihnen helfen?",
              responseSystemPrompt: "Sie sind ein prägnant formulierender Spezialist für Baseballkarten.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // optional: us1 | ie1 | au1; Standardwert ist us1
          },
          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Öffentlicher Telnyx-Webhook-Schlüssel aus dem Mission Control Portal
            // (Base64; kann auch über TELNYX_PUBLIC_KEY festgelegt werden).
            publicKey: "...",
          },
          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

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

          // Webhook-Sicherheit (für Tunnel/Proxys empfohlen)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Öffentliche Bereitstellung (eine Option auswählen)
          // publicUrl: "https://example.ngrok.app/voice/webhook",
          // tunnel: { provider: "ngrok" },
          // tailscale: { mode: "funnel", path: "/voice/webhook" },

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

          streaming: { enabled: true /* nur Twilio; siehe Streaming-Transkription */ },
          realtime: { enabled: false /* siehe Echtzeit-Sprachkonversationen */ },
        },
      },
    },
  },
}

​

Konfigurationsreferenz

​

Sitzungsbereich

​

Echtzeit-Sprachkonversationen

• realtime.enabled wird für Twilio und Telnyx unterstützt.
• realtime.provider ist optional. Wenn nicht festgelegt, verwendet Voice Call den ersten registrierten Realtime-Sprach-Provider.
• Gebündelte Realtime-Sprach-Provider: Google Gemini Live (google) und OpenAI (openai), die von ihren Provider-Plugins registriert werden.
• Die Provider-eigene Rohkonfiguration befindet sich unter realtime.providers.<providerId>.
• Voice Call stellt standardmäßig das gemeinsame Realtime-Tool openclaw_agent_consult bereit. Das Realtime-Modell kann es aufrufen, wenn der Anrufer nach tiefergehender Schlussfolgerung, aktuellen Informationen oder regulären OpenClaw-Tools fragt.
• realtime.consultPolicy fügt optional Anweisungen dazu hinzu, wann das Realtime-Modell openclaw_agent_consult aufrufen soll.
• realtime.agentContext.enabled ist standardmäßig deaktiviert. Wenn diese Option aktiviert ist, fügt Voice Call beim Einrichten der Sitzung eine begrenzte Agentenidentität und eine Kapsel ausgewählter Workspace-Dateien in die Anweisungen für den Realtime-Provider ein.
• realtime.fastContext.enabled ist standardmäßig deaktiviert. Wenn diese Option aktiviert ist, durchsucht Voice Call zunächst den indizierten Speicher-/Sitzungskontext nach der Konsultationsfrage und gibt diese Ausschnitte innerhalb von realtime.fastContext.timeoutMs an das Realtime-Modell zurück, bevor nur dann auf den vollständigen Konsultationsagenten zurückgegriffen wird, wenn realtime.fastContext.fallbackToConsult wahr ist.
• Wenn realtime.provider auf einen nicht registrierten Provider verweist oder überhaupt kein Realtime-Sprach-Provider registriert ist, protokolliert Voice Call eine Warnung und überspringt Realtime-Medien, statt das gesamte Plugin fehlschlagen zu lassen.
• inboundPolicy darf nicht "disabled" sein, wenn realtime.enabled wahr ist; validateProviderConfig lehnt diese Kombination ab.
• Konsultations-Sitzungsschlüssel verwenden, sofern verfügbar, die gespeicherte Anrufsitzung erneut und greifen andernfalls auf den konfigurierten Wert sessionScope zurück (standardmäßig per-phone oder per-call für isolierte Anrufe).

​

Tool-Richtlinie

​

Sprachkontext des Agenten

{
  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: "Sprechen Sie kurz. Rufen Sie openclaw_agent_consult auf, bevor Sie tiefergehende Tools verwenden.",
            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}" },
            },
          },
        },
      },
    },
  },
}

​

Streaming-Transkription

• streaming.provider ist optional. Wenn nicht festgelegt, 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), die von ihren Provider-Plugins registriert werden.
• Die Provider-eigene Rohkonfiguration befindet sich unter streaming.providers.<providerId>.
• Nachdem Twilio eine akzeptierte Stream-Nachricht start gesendet hat, registriert Voice Call den Stream sofort, stellt eingehende Medien während des Verbindungsaufbaus durch den Transkriptions-Provider in eine Warteschlange und beginnt mit der ersten 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 das Medienstreaming, 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, wenn OPENAI_API_KEY festgelegt ist
                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, wenn XAI_API_KEY festgelegt ist
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

​

TTS für Anrufe

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

• Veraltete tts.<provider>-Schlüssel innerhalb der Plugin-Konfiguration (openai, elevenlabs, microsoft, edge) werden durch openclaw doctor --fix repariert; die gespeicherte Konfiguration sollte tts.providers.<provider> verwenden.
• Kern-TTS wird verwendet, wenn Twilio-Medienstreaming aktiviert ist; andernfalls greifen Anrufe auf Provider-native Stimmen zurück.
• Wenn bereits ein Twilio-Medienstream aktiv ist, greift 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 vermischen.
• Wenn Telefonie-TTS auf einen sekundären Provider zurückgreift, protokolliert Voice Call zu Debuggingzwecken eine Warnung mit der Provider-Kette (from, to, attempts).
• Wenn Twilio-Barge-in oder der Stream-Abbau die ausstehende TTS-Warteschlange leert, werden Wiedergabeanforderungen in der Warteschlange abgeschlossen, statt Anrufer, die auf den Abschluss der Wiedergabe warten, unbegrenzt warten zu lassen.

​

TTS-Beispiele

{
  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: "Hallo! Wie kann ich helfen?",
}

​

Routing pro Nummer

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

{
  inboundGreeting: "Hallo von der Hauptleitung.",
  responseSystemPrompt: "Sie sind der standardmäßige Sprachassistent.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, wie kann ich helfen?",
      responseSystemPrompt: "Sie sind ein prägnanter Spezialist für Baseball-Sammelkarten.",
      tts: {
        providers: {
          openai: { speakerVoice: "alloy" },
        },
      },
    },
  },
}

​

Vertrag für gesprochene Ausgaben

• Ignoriert Nutzdaten, die als Reasoning-/Fehlerinhalt gekennzeichnet sind.
• Parst direktes JSON, JSON in Codeblöcken oder eingebettete Schlüssel vom Typ "spoken".
• Greift auf Klartext zurück und entfernt wahrscheinliche einleitende Planungs-/Metaabsätze.

​

Verhalten beim Gesprächsbeginn

• Das Leeren der Barge-in-Warteschlange und automatische Antworten werden nur unterdrückt, solange 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 beginnt beim Verbindungsaufbau des Streams ohne zusätzliche Verzögerung.
• Barge-in bricht die aktive Wiedergabe ab und entfernt Twilio-TTS-Einträge aus der Warteschlange, deren Wiedergabe noch nicht begonnen hat. Entfernte Einträge werden als übersprungen aufgelöst, sodass die Logik für Folgeantworten fortfahren kann, ohne auf Audio zu warten, das niemals abgespielt wird.
• Echtzeit-Sprachunterhaltungen verwenden den eigenen Eröffnungsbeitrag des Echtzeit-Streams. Voice Call sendet für diese anfängliche Nachricht kein veraltetes TwiML-Update vom Typ <Say>, sodass ausgehende Sitzungen vom Typ <Connect><Stream> verbunden bleiben.

​

Kulanzfrist bei Trennung eines Twilio-Streams

• Wenn der Stream innerhalb dieses Zeitfensters erneut verbunden wird, wird das automatische Beenden abgebrochen.
• Wenn nach Ablauf der Kulanzfrist kein Stream erneut registriert wird, wird der Anruf beendet, um dauerhaft aktive Anrufe zu verhindern.

​

Bereinigung veralteter Anrufe

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

​

Webhook-Sicherheit

• Der Wiederholungsschutz für Webhooks ist für Twilio, Telnyx und Plivo aktiviert. Wiederholt gesendete gültige Webhook-Anfragen werden bestätigt, ihre Nebenwirkungen jedoch übersprungen.
• Twilio-Gesprächsbeiträge enthalten in Rückrufen vom Typ <Gather> ein Token pro Beitrag, sodass veraltete/wiederholte Sprachrückrufe keinen neueren ausstehenden Transkriptbeitrag erfüllen können.
• Nicht authentifizierte Webhook-Anfragen werden vor dem Lesen des Bodys abgelehnt, wenn die erforderlichen Signatur-Header des Providers fehlen.
• Der Voice-Call-Webhook verwendet vor der Signaturprüfung das gemeinsame Profil zum Lesen des Bodys vor der Authentifizierung (maximal 64 KB Body-Größe, 5 Sekunden Lesezeitüberschreitung) sowie eine Obergrenze für gleichzeitig laufende Anfragen pro Schlüssel (standardmäßig 8 gleichzeitige Anfragen pro Schlüssel).

{
  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 von OpenClaw"
openclaw voicecall start --to "+15555550123"   # Alias für call
openclaw voicecall continue --call-id <id> --message "Noch Fragen?"
openclaw voicecall speak --call-id <id> --message "Einen 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                      # Beitragslatenz aus Protokollen zusammenfassen
openclaw voicecall expose --mode funnel

​

Agentenwerkzeug

​

Gateway-RPC

​

Fehlerbehebung

​

Einrichtung der Webhook-Bereitstellung schlägt fehl

openclaw voicecall setup
openclaw voicecall setup --json

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          publicUrl: "https://voice.example.com/voice/webhook",
          // oder
          tunnel: { provider: "ngrok" },
          // oder
          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 oder TELNYX_API_KEY, TELNYX_CONNECTION_ID und TELNYX_PUBLIC_KEY.
• Plivo: plivo.authId, plivo.authToken und fromNumber oder PLIVO_AUTH_ID und PLIVO_AUTH_TOKEN.

​

Anrufe starten, aber Provider-Webhooks treffen nicht ein

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

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

• publicUrl verweist auf einen anderen Pfad als serve.path.
• Die Tunnel-URL wurde nach dem Start des Gateways geändert.
• Ein Proxy leitet die Anfrage weiter, entfernt oder schreibt jedoch die Host-/Protokoll-Header um.
• Firewall oder DNS leitet den öffentlichen Hostnamen an ein anderes Ziel als das Gateway weiter.
• Das Gateway wurde neu gestartet, ohne dass das Voice-Call-Plugin aktiviert war.

​

Signaturüberprüfung schlägt fehl

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

​

Twilio-Beitritte zu Google Meet 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 das DTMF-TwiML vor dem Verbindungsaufbau.
• Das anfängliche Twilio-TwiML wird verarbeitet und vor der Echtzeitverarbeitung bereitgestellt.
• Voice Call stellt Echtzeit-TwiML für den Twilio-Anruf bereit.
• Google Meet fordert nach der Verzögerung nach DTMF die Begrüßungssprache mit voicecall.speak an.

​

Echtzeitanruf hat keine Sprachausgabe

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

​

Verwandte Themen

• Sprechmodus
• Text-zu-Sprache
• Sprachaktivierung