Saltar para o conteúdo principal

​
Chamada de Voz (plugin)

Chamadas de voz para o OpenClaw por meio de um plugin. Suporta notificações de saída e conversas de múltiplos turnos com políticas de entrada. Provedores atuais:
  • twilio (Programmable Voice + Media Streams)
  • telnyx (Call Control v2)
  • plivo (Voice API + transferência XML + fala GetInput)
  • mock (dev/sem rede)
Modelo mental rápido:
  • Instale o plugin
  • Reinicie o Gateway
  • Configure em plugins.entries.voice-call.config
  • Use openclaw voicecall ... ou a ferramenta voice_call

​
Onde ele roda (local vs remoto)

O plugin de Chamada de Voz roda dentro do processo do Gateway. Se você usar um Gateway remoto, instale/configure o plugin na máquina que executa o Gateway, depois reinicie o Gateway para carregá-lo.

​
Instalação

​
Opção A: instalar a partir do npm (recomendado)

openclaw plugins install @openclaw/voice-call
Reinicie o Gateway depois.

​
Opção B: instalar a partir de uma pasta local (dev, sem cópia)

openclaw plugins install ./extensions/voice-call
cd ./extensions/voice-call && pnpm install
Reinicie o Gateway depois.

​
Configuração

Defina a configuração em plugins.entries.voice-call.config: 
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // or "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234",
          toNumber: "+15550005678",

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

          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,
            streamPath: "/voice/stream",
          },
        },
      },
    },
  },
}
Notas:
  • Twilio/Telnyx exigem uma URL de webhook publicamente acessível.
  • Plivo exige uma URL de webhook publicamente acessível.
  • mock é um provedor local de dev (sem chamadas de rede).
  • Telnyx requer telnyx.publicKey (ou TELNYX_PUBLIC_KEY), a menos que skipSignatureVerification seja true.
  • skipSignatureVerification é apenas para testes locais.
  • Se você usar o plano gratuito do ngrok, defina publicUrl para a URL exata do ngrok; a verificação de assinatura é sempre aplicada.
  • tunnel.allowNgrokFreeTierLoopbackBypass: true permite webhooks do Twilio com assinaturas inválidas somente quando tunnel.provider="ngrok" e serve.bind é loopback (agente local do ngrok). Use apenas para dev local.
  • URLs do plano gratuito do ngrok podem mudar ou adicionar comportamento intermediário; se publicUrl variar, as assinaturas do Twilio falharão. Para produção, prefira um domínio estável ou um funnel do Tailscale.

​
Segurança de Webhook

Quando um proxy ou túnel fica na frente do Gateway, o plugin reconstrói a URL pública para verificação de assinatura. Essas opções controlam quais headers encaminhados são confiáveis. webhookSecurity.allowedHosts cria uma lista de permissões de hosts a partir dos headers de encaminhamento. webhookSecurity.trustForwardingHeaders confia nos headers encaminhados sem uma lista de permissões. webhookSecurity.trustedProxyIPs só confia nos headers encaminhados quando o IP remoto da requisição corresponde à lista. Exemplo com um host público estável: 
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          publicUrl: "https://voice.example.com/voice/webhook",
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
          },
        },
      },
    },
  },
}

​
TTS para chamadas

Chamada de Voz usa a configuração principal de messages.tts (OpenAI ou ElevenLabs) para streaming de fala nas chamadas. Você pode sobrescrevê-la na configuração do plugin com o mesmo formato — ela é mesclada em profundidade com messages.tts. 
{
  tts: {
    provider: "elevenlabs",
    elevenlabs: {
      voiceId: "pMsXgVXv3BLzUgSXRplE",
      modelId: "eleven_multilingual_v2",
    },
  },
}
Notas:
  • O Edge TTS é ignorado para chamadas de voz (o áudio de telefonia precisa de PCM; a saída do Edge é pouco confiável).
  • O TTS principal é usado quando o streaming de mídia do Twilio está habilitado; caso contrário, as chamadas recorrem às vozes nativas do provedor.

​
Mais exemplos

Usar apenas o TTS principal (sem sobrescrever): 
{
  messages: {
    tts: {
      provider: "openai",
      openai: { voice: "alloy" },
    },
  },
}
Sobrescrever para ElevenLabs apenas para chamadas (manter o padrão principal em outros lugares): 
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          tts: {
            provider: "elevenlabs",
            elevenlabs: {
              apiKey: "elevenlabs_key",
              voiceId: "pMsXgVXv3BLzUgSXRplE",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}
Sobrescrever apenas o modelo OpenAI para chamadas (exemplo de mesclagem profunda): 
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          tts: {
            openai: {
              model: "gpt-4o-mini-tts",
              voice: "marin",
            },
          },
        },
      },
    },
  },
}

​
Chamadas de entrada

A política de entrada padrão é disabled. Para habilitar chamadas de entrada, defina: 
{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Hello! How can I help?",
}
As respostas automáticas usam o sistema de agentes. Ajuste com:
  • responseModel
  • responseSystemPrompt
  • responseTimeoutMs

​
CLI

openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
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 expose --mode funnel

​
Ferramenta de agente

Nome da ferramenta: voice_call Ações:
  • initiate_call (message, to?, mode?)
  • continue_call (callId, message)
  • speak_to_user (callId, message)
  • end_call (callId)
  • get_status (callId)
Este repositório inclui um documento de skill correspondente em skills/voice-call/SKILL.md.

​
RPC do Gateway

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