​

Voice Call (Plugin)

• twilio (Programmable Voice + Media Streams)
• telnyx (Call Control v2)
• plivo (Voice API + XML-Transfer + GetInput speech)
• mock (Entwicklung/kein Netzwerk)

• Plugin installieren
• Gateway neu starten
• Unter plugins.entries.voice-call.config konfigurieren
• openclaw voicecall ... oder das Tool voice_call verwenden

​

Wo es läuft (local vs remote)

​

Installation

​

Option A: aus npm installieren (empfohlen)

openclaw plugins install @openclaw/voice-call

​

Option B: aus einem lokalen Ordner installieren (Entwicklung, ohne Kopieren)

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

​

Konfiguration

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // oder "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234",
          toNumber: "+15550005678",

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
          },

          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Öffentlicher Webhook-Schlüssel von Telnyx aus dem Telnyx Mission Control Portal
            // (Base64-String; kann auch über TELNYX_PUBLIC_KEY gesetzt werden).
            publicKey: "...",
          },

          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

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

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

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

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

          streaming: {
            enabled: true,
            provider: "openai", // optional; erster registrierter Echtzeit-Transkriptions-Provider, wenn nicht gesetzt
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // optional, wenn OPENAI_API_KEY gesetzt ist
                model: "gpt-4o-transcribe",
                silenceDurationMs: 800,
                vadThreshold: 0.5,
              },
            },
            preStartTimeoutMs: 5000,
            maxPendingConnections: 32,
            maxPendingConnectionsPerIp: 4,
            maxConnections: 128,
          },
        },
      },
    },
  },
}

• Twilio/Telnyx erfordern eine öffentlich erreichbare Webhook-URL.
• Plivo erfordert eine öffentlich erreichbare Webhook-URL.
• mock ist ein lokaler Entwicklungs-Provider (ohne Netzwerkaufrufe).
• Wenn ältere Konfigurationen noch provider: "log", twilio.from oder alte OpenAI-Schlüssel unter streaming.* verwenden, führen Sie openclaw doctor --fix aus, um sie umzuschreiben.
• Telnyx erfordert telnyx.publicKey (oder TELNYX_PUBLIC_KEY), sofern skipSignatureVerification nicht auf true gesetzt ist.
• skipSignatureVerification ist nur für lokale Tests gedacht.
• Wenn Sie die kostenlose Stufe von ngrok verwenden, setzen Sie publicUrl auf die exakte ngrok-URL; die Signaturprüfung wird immer erzwungen.
• tunnel.allowNgrokFreeTierLoopbackBypass: true erlaubt Twilio-Webhooks mit ungültigen Signaturen nur, wenn tunnel.provider="ngrok" und serve.bind loopback ist (lokaler ngrok-Agent). Nur für lokale Entwicklung verwenden.
• URLs der kostenlosen ngrok-Stufe können sich ändern oder Interstitial-Verhalten hinzufügen; wenn publicUrl abweicht, schlagen Twilio-Signaturen fehl. Für die Produktion sollten Sie eine stabile Domain oder Tailscale funnel bevorzugen.
• Standardwerte für Streaming-Sicherheit:
  • streaming.preStartTimeoutMs schließt Sockets, die niemals einen gültigen start-Frame senden.
• streaming.maxPendingConnections begrenzt die Gesamtzahl nicht authentifizierter Sockets vor dem Start.
• streaming.maxPendingConnectionsPerIp begrenzt nicht authentifizierte Sockets vor dem Start pro Quell-IP.
• streaming.maxConnections begrenzt die Gesamtzahl offener Media-Stream-Sockets (ausstehend + aktiv).
• Das Runtime-Fallback akzeptiert diese alten voice-call-Schlüssel vorerst weiterhin, aber der Umschreibpfad ist openclaw doctor --fix, und der Kompatibilitäts-Shim ist nur vorübergehend.

​

Streaming-Transkription

• streaming.provider ist optional. Wenn es nicht gesetzt ist, verwendet Voice Call den ersten registrierten Echtzeit-Transkriptions-Provider.
• Derzeit ist der gebündelte Provider OpenAI, registriert durch das gebündelte openai- Plugin.
• Rohkonfiguration im Besitz des Providers liegt unter streaming.providers.<providerId>.
• Wenn streaming.provider auf einen nicht registrierten Provider zeigt oder überhaupt kein Echtzeit- Transkriptions-Provider registriert ist, protokolliert Voice Call eine Warnung und überspringt Media-Streaming, statt das gesamte Plugin fehlschlagen zu lassen.

• API-Schlüssel: streaming.providers.openai.apiKey oder OPENAI_API_KEY
• Modell: gpt-4o-transcribe
• silenceDurationMs: 800
• vadThreshold: 0.5

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

• 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

​

Bereinigung veralteter Anrufe

• Produktion: 120–300 Sekunden für Benachrichtigungsabläufe.
• Halten Sie diesen Wert höher als maxDurationSeconds, damit normale Anrufe beendet werden können. Ein guter Ausgangswert ist maxDurationSeconds + 30–60 Sekunden.

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

​

Webhook-Sicherheit

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

​

TTS für Anrufe

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

• Alte tts.<provider>-Schlüssel innerhalb der Plugin-Konfiguration (openai, elevenlabs, microsoft, edge) werden beim Laden automatisch nach tts.providers.<provider> migriert. Bevorzugen Sie die Struktur providers in eingecheckter Konfiguration.
• Microsoft speech wird für Sprachanrufe ignoriert (Telefonie-Audio benötigt PCM; der aktuelle Microsoft-Transport stellt keine PCM-Ausgabe für Telefonie bereit).
• Kern-TTS wird verwendet, wenn Twilio-Media-Streaming aktiviert ist; andernfalls fallen Anrufe auf providernative Stimmen zurück.
• Wenn bereits ein Twilio-Media-Stream 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 Wiedergabeanfrage fehl, statt zwei Wiedergabepfade zu mischen.
• Wenn Telefonie-TTS auf einen sekundären Provider zurückfällt, protokolliert Voice Call zur Fehlerdiagnose eine Warnung mit der Provider-Kette (from, to, attempts).

​

Weitere Beispiele

{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { voice: "alloy" },
      },
    },
  },
}

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

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

​

Eingehende Anrufe

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

• responseModel
• responseSystemPrompt
• responseTimeoutMs

​

Vertrag für gesprochene Ausgabe

• {"spoken":"..."}

• Ignoriert Nutzlasten, die als Reasoning-/Fehlerinhalte markiert sind.
• Parst direktes JSON, JSON in Fences oder Inline-Schlüssel "spoken".
• Fällt auf Klartext zurück und entfernt wahrscheinliche einleitende Absätze für Planung/Meta.

​

Verhalten beim Start von Gesprächen

• Leeren der Barge-in-Warteschlange und automatische Antwort 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 erste Nachricht bleibt zur erneuten Ausführung in der Warteschlange.
• Die anfängliche Wiedergabe für Twilio-Streaming startet bei Stream-Verbindung ohne zusätzliche Verzögerung.

​

Kulanzzeit bei Twilio-Stream-Trennung

• Wenn der Stream innerhalb dieses Zeitfensters erneut verbunden wird, wird die automatische Beendigung abgebrochen.
• Wenn nach der Kulanzzeit kein Stream erneut registriert wird, wird der Anruf beendet, um hängende aktive Anrufe zu verhindern.

​

CLI

openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
openclaw voicecall start --to "+15555550123"   # Alias für call
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall speak --call-id <id> --message "One moment"
openclaw voicecall end --call-id <id>
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw voicecall latency                     # Zuglatenz aus Logs zusammenfassen
openclaw voicecall expose --mode funnel

​

Agent-Tool

• initiate_call (message, to?, mode?)
• continue_call (callId, message)
• speak_to_user (callId, message)
• end_call (callId)
• get_status (callId)

​

Gateway-RPC

• voicecall.initiate (to?, message, mode?)
• voicecall.continue (callId, message)
• voicecall.speak (callId, message)
• voicecall.end (callId)
• voicecall.status (callId)