Sesli arama plugin'i

​

Hızlı başlangıç

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

​

Yapılandırma

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // veya "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // veya Twilio için TWILIO_FROM_NUMBER
          toNumber: "+15550005678",
          sessionScope: "per-phone", // per-phone | per-call
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, size nasıl yardımcı olabilirim?",
              responseSystemPrompt: "Kısa ve öz yanıt veren bir beyzbol kartı uzmanısınız.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // isteğe bağlı: us1 | ie1 | au1; varsayılan us1'dir
          },
          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Mission Control Portal'dan Telnyx Webhook genel anahtarı
            // (Base64; TELNYX_PUBLIC_KEY aracılığıyla da ayarlanabilir).
            publicKey: "...",
          },
          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

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

          // Webhook güvenliği (tüneller/proxy'ler için önerilir)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Herkese açık erişim (birini seçin)
          // publicUrl: "https://example.ngrok.app/voice/webhook",
          // tunnel: { provider: "ngrok" },
          // tailscale: { mode: "funnel", path: "/voice/webhook" },

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

          streaming: { enabled: true /* yalnızca Twilio; bkz. Akışlı transkripsiyon */ },
          realtime: { enabled: false /* bkz. Gerçek zamanlı sesli konuşmalar */ },
        },
      },
    },
  },
}

​

Yapılandırma başvurusu

​

Oturum kapsamı

​

Gerçek zamanlı sesli konuşmalar

• realtime.enabled, Twilio ve Telnyx için desteklenir.
• realtime.provider isteğe bağlıdır. Ayarlanmamışsa Voice Call, kaydedilen ilk gerçek zamanlı ses sağlayıcısını kullanır.
• Paketle birlikte gelen gerçek zamanlı ses sağlayıcıları: sağlayıcı pluginleri tarafından kaydedilen Google Gemini Live (google) ve OpenAI (openai).
• Sağlayıcının sahip olduğu ham yapılandırma realtime.providers.<providerId> altında bulunur.
• Voice Call, paylaşılan openclaw_agent_consult gerçek zamanlı aracını varsayılan olarak kullanıma sunar. Arayan kişi daha derin akıl yürütme, güncel bilgi veya normal OpenClaw araçları istediğinde gerçek zamanlı model bu aracı çağırabilir.
• realtime.consultPolicy, gerçek zamanlı modelin openclaw_agent_consult aracını ne zaman çağırması gerektiğine ilişkin isteğe bağlı yönlendirme ekler.
• realtime.agentContext.enabled varsayılan olarak kapalıdır. Etkinleştirildiğinde Voice Call, oturum kurulumu sırasında gerçek zamanlı sağlayıcı talimatlarına sınırlandırılmış bir aracı kimliği ve seçili çalışma alanı dosyalarından oluşan bir kapsül ekler.
• realtime.fastContext.enabled varsayılan olarak kapalıdır. Etkinleştirildiğinde Voice Call, danışma sorusu için önce dizine alınmış bellek/oturum bağlamında arama yapar ve yalnızca realtime.fastContext.fallbackToConsult doğruysa tam danışma aracısına geri dönmeden önce bu parçaları realtime.fastContext.timeoutMs içinde gerçek zamanlı modele döndürür.
• realtime.provider kaydedilmemiş bir sağlayıcıyı gösteriyorsa veya hiçbir gerçek zamanlı ses sağlayıcısı kaydedilmemişse Voice Call bir uyarı kaydeder ve pluginin tamamını başarısız kılmak yerine gerçek zamanlı medyayı atlar.
• realtime.enabled doğru olduğunda inboundPolicy, "disabled" olmamalıdır; validateProviderConfig bu birleşimi reddeder.
• Danışma oturumu anahtarları, mevcut olduğunda depolanan çağrı oturumunu yeniden kullanır; ardından yapılandırılmış sessionScope değerine geri döner (varsayılan olarak per-phone veya yalıtılmış çağrılar için per-call).

​

Araç politikası

​

Aracı ses bağlamı

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

​

Gerçek zamanlı sağlayıcı örnekleri

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          provider: "twilio",
          inboundPolicy: "allowlist",
          allowFrom: ["+15550005678"],
          realtime: {
            enabled: true,
            provider: "google",
            instructions: "Kısa konuş. Daha kapsamlı araçları kullanmadan önce openclaw_agent_consult aracını çağır.",
            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}" },
            },
          },
        },
      },
    },
  },
}

​

Akışlı transkripsiyon

• streaming.provider isteğe bağlıdır. Ayarlanmamışsa Voice Call, kaydedilen ilk gerçek zamanlı transkripsiyon sağlayıcısını kullanır.
• Paketle birlikte gelen gerçek zamanlı transkripsiyon sağlayıcıları: sağlayıcı pluginleri tarafından kaydedilen Deepgram (deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai) ve xAI (xai).
• Sağlayıcının sahip olduğu ham yapılandırma streaming.providers.<providerId> altında bulunur.
• Twilio, kabul edilmiş bir akış start iletisi gönderdikten sonra Voice Call akışı hemen kaydeder, sağlayıcı bağlanırken gelen medyayı transkripsiyon sağlayıcısı üzerinden kuyruğa alır ve ilk karşılamayı yalnızca gerçek zamanlı transkripsiyon hazır olduktan sonra başlatır.
• streaming.provider kaydedilmemiş bir sağlayıcıyı gösteriyorsa veya hiçbir sağlayıcı kaydedilmemişse Voice Call bir uyarı kaydeder ve pluginin tamamını başarısız kılmak yerine medya akışını atlar.

​

Akış sağlayıcısı örnekleri

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "openai",
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // OPENAI_API_KEY ayarlanmışsa isteğe bağlıdır
                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}", // XAI_API_KEY ayarlanmışsa isteğe bağlıdır
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

​

Çağrılar için TTS

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

• Plugin yapılandırmasındaki eski tts.<provider> anahtarları (openai, elevenlabs, microsoft, edge) openclaw doctor --fix tarafından onarılır; kaydedilen yapılandırma tts.providers.<provider> kullanmalıdır.
• Twilio medya akışı etkinleştirildiğinde çekirdek TTS kullanılır; aksi takdirde çağrılar sağlayıcıya özgü seslere geri döner.
• Bir Twilio medya akışı zaten etkinse Voice Call, TwiML <Say> seçeneğine geri dönmez. Bu durumda telefon TTS’i kullanılamıyorsa oynatma isteği iki oynatma yolunu karıştırmak yerine başarısız olur.
• Telefon TTS’i ikincil bir sağlayıcıya geri döndüğünde Voice Call, hata ayıklama için sağlayıcı zincirini (from, to, attempts) içeren bir uyarı kaydeder.
• Twilio araya girme veya akış kapatma işlemi bekleyen TTS kuyruğunu temizlediğinde, kuyruğa alınan oynatma istekleri oynatmanın tamamlanmasını bekleyen arayanları askıda bırakmak yerine sonuçlandırılır.

​

TTS örnekleri

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

​

Gelen aramalar

{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Merhaba! Nasıl yardımcı olabilirim?",
}

​

Numara başına yönlendirme

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

{
  inboundGreeting: "Ana hattan merhaba.",
  responseSystemPrompt: "Varsayılan sesli asistansınız.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, nasıl yardımcı olabilirim?",
      responseSystemPrompt: "Kısa ve öz yanıt veren bir beyzbol kartı uzmanısınız.",
      tts: {
        providers: {
          openai: { speakerVoice: "alloy" },
        },
      },
    },
  },
}

​

Sözlü çıktı sözleşmesi

• Akıl yürütme/hata içeriği olarak işaretlenen yükleri yok sayar.
• Doğrudan JSON’ı, kod çitli JSON’ı veya satır içi "spoken" anahtarlarını ayrıştırır.
• Düz metne geri döner ve muhtemel planlama/meta giriş paragraflarını kaldırır.

​

Konuşma başlatma davranışı

• Araya girme kuyruğunu temizleme ve otomatik yanıt, yalnızca ilk karşılama etkin olarak seslendirilirken engellenir.
• İlk oynatma başarısız olursa arama listening durumuna döner ve ilk mesaj yeniden deneme için kuyrukta kalır.
• Twilio akışı için ilk oynatma, ek gecikme olmadan akış bağlantısında başlar.
• Araya girme, etkin oynatmayı durdurur ve kuyrukta olup henüz oynatılmayan Twilio TTS girdilerini temizler. Temizlenen girdiler atlanmış olarak çözümlenir; böylece sonraki yanıt mantığı, hiçbir zaman oynatılmayacak sesi beklemeden devam edebilir.
• Gerçek zamanlı sesli konuşmalar, gerçek zamanlı akışın kendi açılış sırasını kullanır. Voice Call, bu ilk mesaj için eski bir <Say> TwiML güncellemesi göndermez; böylece giden <Connect><Stream> oturumları bağlı kalır.

​

Twilio akış bağlantısı kesilme ek süresi

• Akış bu süre içinde yeniden bağlanırsa otomatik sonlandırma iptal edilir.
• Ek süre sonrasında hiçbir akış yeniden kaydolmazsa etkin aramaların takılı kalmasını önlemek için arama sonlandırılır.

​

Bayat arama temizleyici

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

​

Webhook güvenliği

• Webhook yeniden oynatma koruması Twilio, Telnyx ve Plivo için etkindir. Yeniden oynatılan geçerli Webhook istekleri onaylanır ancak yan etkileri uygulanmaz.
• Twilio konuşma sıraları, <Gather> geri çağırmalarında sıra başına bir belirteç içerir; böylece eski/yeniden oynatılan konuşma geri çağırmaları daha yeni bir bekleyen döküm sırasını karşılayamaz.
• Kimliği doğrulanmamış Webhook istekleri, sağlayıcının gerekli imza üstbilgileri eksik olduğunda gövde okunmadan önce reddedilir.
• Voice Call Webhook’u, imza doğrulamasından önce paylaşılan kimlik doğrulama öncesi gövde okuma profilini (en fazla 64 KB gövde, 5 saniyelik okuma zaman aşımı) ve anahtar başına devam eden istek sınırını (varsayılan olarak anahtar başına 8 eşzamanlı istek) kullanır.

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

​

CLI

openclaw voicecall call --to "+15555550123" --message "OpenClaw'dan merhaba"
openclaw voicecall start --to "+15555550123"   # call için takma ad
openclaw voicecall continue --call-id <id> --message "Sorunuz var mı?"
openclaw voicecall speak --call-id <id> --message "Bir dakika"
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                      # günlüklerden sıra gecikmesini özetle
openclaw voicecall expose --mode funnel

​

Ajan aracı

​

Gateway RPC

​

Sorun giderme

​

Kurulum Webhook erişimini açamıyor

openclaw voicecall setup
openclaw voicecall setup --json

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

openclaw voicecall setup
openclaw voicecall smoke

​

Sağlayıcı kimlik bilgileri başarısız oluyor

• Twilio: twilio.accountSid, twilio.authToken ve fromNumber veya TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN ve TWILIO_FROM_NUMBER.
• Telnyx: telnyx.apiKey, telnyx.connectionId, telnyx.publicKey ve fromNumber veya TELNYX_API_KEY, TELNYX_CONNECTION_ID ve TELNYX_PUBLIC_KEY.
• Plivo: plivo.authId, plivo.authToken ve fromNumber veya PLIVO_AUTH_ID ve PLIVO_AUTH_TOKEN.

​

Çağrılar başlıyor ancak sağlayıcı Webhook’ları ulaşmıyor

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

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

• publicUrl, serve.path yolundan farklı bir yolu işaret ediyor.
• Gateway başlatıldıktan sonra tünel URL’si değişti.
• Bir proxy isteği iletiyor ancak ana makine/protokol başlıklarını kaldırıyor veya yeniden yazıyor.
• Güvenlik duvarı veya DNS, herkese açık ana makine adını Gateway dışında bir yere yönlendiriyor.
• Gateway, Voice Call Plugin’i etkinleştirilmeden yeniden başlatıldı.

​

İmza doğrulaması başarısız oluyor

• Sağlayıcının Webhook URL’sinin şema, ana makine ve yol dâhil olmak üzere publicUrl ile tam olarak eşleştiğini doğrulayın.
• ngrok ücretsiz katman URL’leri için tünelin ana makine adı değiştiğinde publicUrl değerini güncelleyin.
• Proxy’nin özgün ana makine ve protokol başlıklarını koruduğundan emin olun veya webhookSecurity.allowedHosts yapılandırmasını ayarlayın.
• Yerel testler dışında skipSignatureVerification seçeneğini etkinleştirmeyin.

​

Google Meet Twilio katılımları başarısız oluyor

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

openclaw googlemeet setup --transport twilio

• Google Meet, Twilio katılımını Voice Call’a devreder.
• Voice Call, bağlantı öncesi DTMF TwiML’ini depolar.
• Twilio başlangıç TwiML’i tüketilir ve gerçek zamanlı işlemeden önce sunulur.
• Voice Call, Twilio çağrısı için gerçek zamanlı TwiML sunar.
• Google Meet, DTMF sonrası gecikmenin ardından voicecall.speak ile giriş konuşmasını ister.

​

Gerçek zamanlı çağrıda konuşma yok

• Bir gerçek zamanlı sağlayıcı Plugin’i yüklenmiş ve kaydedilmiş.
• realtime.provider ayarlanmamış veya kayıtlı bir sağlayıcıyı adlandırıyor.
• Sağlayıcı API anahtarı Gateway işlemi tarafından kullanılabiliyor.
• openclaw logs --follow, gerçek zamanlı TwiML’in sunulduğunu, gerçek zamanlı köprünün başladığını ve başlangıç selamlamasının kuyruğa alındığını gösteriyor.

​

İlgili

• Konuşma modu
• Metinden konuşmaya
• Sesle uyandırma