​

Voice Call (plugin)

• twilio (Programmable Voice + Media Streams)
• telnyx (Call Control v2)
• plivo (Voice API + trasferimento XML + GetInput speech)
• mock (sviluppo/senza rete)

• Installa il plugin
• Riavvia il Gateway
• Configura sotto plugins.entries.voice-call.config
• Usa openclaw voicecall ... o lo strumento voice_call

​

Dove viene eseguito (locale vs remoto)

​

Installazione

​

Opzione A: installazione da npm (consigliata)

openclaw plugins install @openclaw/voice-call

​

Opzione B: installazione da una cartella locale (sviluppo, senza copia)

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

​

Configurazione

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

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

          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Chiave pubblica del webhook Telnyx dal Telnyx Mission Control Portal
            // (stringa Base64; può anche essere impostata tramite TELNYX_PUBLIC_KEY).
            publicKey: "...",
          },

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

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

          // Sicurezza webhook (consigliata per tunnel/proxy)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Esposizione pubblica (scegline una)
          // 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", // facoltativo; primo provider di trascrizione realtime registrato se non impostato
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // facoltativo se OPENAI_API_KEY è impostato
                model: "gpt-4o-transcribe",
                silenceDurationMs: 800,
                vadThreshold: 0.5,
              },
            },
            preStartTimeoutMs: 5000,
            maxPendingConnections: 32,
            maxPendingConnectionsPerIp: 4,
            maxConnections: 128,
          },
        },
      },
    },
  },
}

• Twilio/Telnyx richiedono un URL webhook raggiungibile pubblicamente.
• Plivo richiede un URL webhook raggiungibile pubblicamente.
• mock è un provider di sviluppo locale (nessuna chiamata di rete).
• Se configurazioni meno recenti usano ancora provider: "log", twilio.from o chiavi OpenAI legacy streaming.*, esegui openclaw doctor --fix per riscriverle.
• Telnyx richiede telnyx.publicKey (o TELNYX_PUBLIC_KEY) a meno che skipSignatureVerification non sia true.
• skipSignatureVerification è solo per test locali.
• Se usi il livello gratuito di ngrok, imposta publicUrl sull’URL ngrok esatto; la verifica della firma viene sempre applicata.
• tunnel.allowNgrokFreeTierLoopbackBypass: true consente i webhook Twilio con firme non valide solo quando tunnel.provider="ngrok" e serve.bind è loopback (agente locale ngrok). Usalo solo per sviluppo locale.
• Gli URL del livello gratuito di ngrok possono cambiare o aggiungere comportamenti interstiziali; se publicUrl deriva, le firme Twilio falliranno. Per la produzione, preferisci un dominio stabile o Tailscale funnel.
• Valori predefiniti di sicurezza dello streaming:
  • streaming.preStartTimeoutMs chiude i socket che non inviano mai un frame start valido.
• streaming.maxPendingConnections limita il totale dei socket pre-start non autenticati.
• streaming.maxPendingConnectionsPerIp limita i socket pre-start non autenticati per IP sorgente.
• streaming.maxConnections limita il totale dei socket media stream aperti (in attesa + attivi).
• Il fallback runtime accetta ancora temporaneamente quelle vecchie chiavi voice-call, ma il percorso di riscrittura è openclaw doctor --fix e lo shim di compatibilità è temporaneo.

​

Trascrizione in streaming

• streaming.provider è facoltativo. Se non impostato, Voice Call usa il primo provider di trascrizione realtime registrato.
• Oggi il provider incluso è OpenAI, registrato dal plugin incluso openai.
• La configurazione grezza di proprietà del provider si trova in streaming.providers.<providerId>.
• Se streaming.provider punta a un provider non registrato, o non è registrato alcun provider di trascrizione realtime, Voice Call registra un avviso e salta lo streaming media invece di far fallire l’intero plugin.

• API key: streaming.providers.openai.apiKey o OPENAI_API_KEY
• model: 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-...", // facoltativo se OPENAI_API_KEY è impostato
                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

​

Reaper delle chiamate stale

• Produzione: 120–300 secondi per i flussi in stile notify.
• Mantieni questo valore più alto di maxDurationSeconds così le chiamate normali possono terminare. Un buon punto di partenza è maxDurationSeconds + 30–60 secondi.

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

​

Sicurezza dei webhook

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

​

TTS per le chiamate

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

• Le chiavi legacy tts.<provider> nella configurazione del plugin (openai, elevenlabs, microsoft, edge) vengono migrate automaticamente a tts.providers.<provider> al caricamento. Preferisci la struttura providers nella configurazione salvata.
• Microsoft speech viene ignorato per le chiamate vocali (l’audio di telefonia richiede PCM; il trasporto Microsoft attuale non espone output PCM per telefonia).
• Il TTS core viene usato quando è abilitato lo streaming media Twilio; altrimenti le chiamate ricorrono alle voci native del provider.
• Se è già attivo uno stream media Twilio, Voice Call non usa come fallback TwiML <Say>. Se in quello stato il TTS di telefonia non è disponibile, la richiesta di riproduzione fallisce invece di mescolare due percorsi di riproduzione.
• Quando il TTS di telefonia ricorre a un provider secondario, Voice Call registra un avviso con la catena dei provider (from, to, attempts) per il debug.

​

Altri esempi

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

​

Chiamate in ingresso

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

• responseModel
• responseSystemPrompt
• responseTimeoutMs

​

Contratto dell’output parlato

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

• Ignora i payload contrassegnati come contenuto di reasoning/errore.
• Analizza JSON diretto, JSON delimitato o chiavi "spoken" inline.
• Ripiega sul testo semplice e rimuove i paragrafi iniziali probabilmente di pianificazione/meta.

​

Comportamento di avvio della conversazione

• La cancellazione della coda per il barge-in e la risposta automatica vengono soppresse solo mentre il saluto iniziale viene pronunciato attivamente.
• Se la riproduzione iniziale fallisce, la chiamata torna a listening e il messaggio iniziale rimane in coda per un nuovo tentativo.
• La riproduzione iniziale per lo streaming Twilio inizia alla connessione dello stream senza ritardi aggiuntivi.

​

Grace di disconnessione dello stream Twilio

• Se lo stream si riconnette durante quella finestra, la terminazione automatica viene annullata.
• Se dopo il periodo di grace non viene nuovamente registrato alcuno stream, la chiamata viene terminata per evitare chiamate attive bloccate.

​

CLI

openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
openclaw voicecall start --to "+15555550123"   # alias di 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                     # riepiloga la latenza dei turni dai log
openclaw voicecall expose --mode funnel

​

Strumento dell’agente

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

​

RPC Gateway

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