配置

插件配置键、呼叫所有者、完整配置参考表以及会话作用域。属于 Voice call plugin 指南的一部分。

配置¶

如果 enabled: true 但所选提供商缺少凭据，Gateway 启动时会记录一条 setup-incomplete 警告，其中包含缺失的键，并跳过启动运行时。命令、RPC 调用和代理工具在使用时仍会返回确切的缺失配置。

Note

语音呼叫凭据支持 SecretRefs。plugins.entries.voice-call.config.twilio.authToken、plugins.entries.voice-call.config.realtime.providers.*.apiKey、plugins.entries.voice-call.config.streaming.providers.*.apiKey 和 plugins.entries.voice-call.config.tts.providers.*.apiKey 通过标准 SecretRef 凭据表面解析；参见SecretRef 凭据表面。

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // or "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio
          toNumber: "+15550005678",
          sessionScope: "per-phone", // per-phone | per-call | main
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, how can I help?",
              responseSystemPrompt: "You are a concise baseball card specialist.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // optional: us1 | ie1 | au1; defaults to us1
          },
          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Telnyx webhook public key from the Mission Control Portal
            // (Base64; can also be set via TELNYX_PUBLIC_KEY).
            publicKey: "...",
          },
          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", port: 8443, path: "/voice/webhook" },

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

          streaming: { enabled: true /* Twilio only; see Streaming transcription */ },
          realtime: { enabled: false /* see Realtime voice conversations */ },
        },
      },
    },
  },
}

选择呼叫所有者¶

如果只配置了一个代理，Voice Call 会自动使用该代理。如果有多个代理，请将 plugins.entries.voice-call.config.agentId 设置为预期的响应与会话所有者。main 是一个普通的代理 ID，而不是多代理集群的后备选项。按号码路由可以为入站呼叫选择不同的代理，但不能替换插件的启动所有者。

如果启动时报告 Voice Call 没有显式所有者，请使用 openclaw agents list 列出你的代理，设置现有的 agentId 字段，然后重新运行 openclaw voicecall setup。在默认的混合重载模式下，配置更改会自动重载插件；参见热重载。现有的旧版默认代理选择会被保留；新的多代理配置应使用显式所有者。参见代理配置。

配置参考¶

上述未列出的 plugins.entries.voice-call.config 下的顶级键：

键	默认值	说明
`enabled`	`false`	主开关。
`inboundPolicy`	`"disabled"`	`disabled` \| `allowlist` \| `pairing` \| `open`。参见入站呼叫。
`allowFrom`	`[]`	用于 `inboundPolicy: "allowlist"` 的 E.164 允许列表。
`maxDurationSeconds`	`300`	每次呼叫的硬性时长上限，无论是否已接听都会强制执行。
`staleCallReaperSeconds`	`120`	参见过期呼叫回收器。`0` 会禁用它。
`silenceTimeoutMs`	`800`	经典（非实时）流程中的语音结束静音检测。
`transcriptTimeoutMs`	`180000`	在放弃当前轮次之前，等待呼叫者转录的最大时长。
`ringTimeoutMs`	`30000`	出站呼叫的振铃超时。
`maxConcurrentCalls`	`1`	超出此限制的出站呼叫会被拒绝。
`outbound.notifyHangupDelaySec`	`3`	在 notify 模式下，TTS 之后自动挂断前等待的秒数。

键	默认值	说明
`skipSignatureVerification`	`false`	仅用于本地测试；切勿在生产环境中启用。
`store`	未设置	覆盖默认的 `$OPENCLAW_STATE_DIR/voice-calls` 路径（通常为 `~/.openclaw/voice-calls`）。
`agentId`	唯一代理	用于响应生成和会话存储的代理。存在多个代理时需显式设置。
`responseModel`	未设置	覆盖传统（非实时）响应的默认模型。
`responseSystemPrompt`	生成	传统响应的自定义系统提示词。
`responseTimeoutMs`	`30000`	传统响应生成的超时时间（毫秒）。

Twilio 默认使用其 US1 REST 端点。要在受支持的非美国区域处理呼叫，请将 twilio.region 设置为 ie1 或 au1，并使用该区域的凭据。参见 Twilio 非美国 REST API 指南。

提供商暴露与安全说明

Twilio、Telnyx 和 Plivo 都需要一个可公开访问的 webhook URL。
mock 是本地开发提供商（无网络调用）。
除非 skipSignatureVerification 为 true，否则 Telnyx 需要 telnyx.publicKey（或 TELNYX_PUBLIC_KEY）。
skipSignatureVerification 仅用于本地测试。
在 ngrok 免费套餐中，请将 publicUrl 设置为确切的 ngrok URL；签名验证始终强制执行。
tunnel.allowNgrokFreeTierLoopbackBypass: true 仅当 tunnel.provider="ngrok" 且 serve.bind 为 loopback（ngrok 本地代理）时，才允许签名无效的 Twilio webhook。仅限本地开发。
Ngrok 免费套餐 URL 可能会变化或增加中间页行为；如果 publicUrl 发生漂移，Twilio 签名会失败。生产环境：建议使用稳定域名或 Tailscale funnel。
Tailscale Serve 和 Funnel 会在启用相应音频模式时自动暴露实时或流式 WebSocket 路径。
tailscale.port 为 tailscale.mode 以及统一的 tunnel.provider: "tailscale-serve" | "tailscale-funnel" 选择外部 HTTPS 端口。默认值为 443；当另一个 HTTPS 服务器占用 443 端口时，请使用 8443。Funnel 仅接受 443、8443 或 10000，而 Serve 接受任何有效 TCP 端口。非默认端口会出现在 webhook 和实时流 URL 中。

流式连接上限

streaming.preStartTimeoutMs（默认 5000）会关闭从未发送有效 start 帧的套接字。
streaming.maxPendingConnections（默认 32）限制未认证的预启动套接字总数。
streaming.maxPendingConnectionsPerIp（默认 4）限制每个源 IP 的未认证预启动套接字数量。
streaming.maxConnections（默认 128）限制所有打开的媒体流套接字（待处理 + 活动）。

旧版配置迁移

运行 openclaw doctor --fix 以将这些旧版键重写为规范形式。Voice Call 插件负责迁移；运行时配置解析仅接受当前键。当旧设置和当前设置同时存在时，Doctor 会保留当前设置，删除旧版键，并报告其保留了哪个目标。旧版值仅填充缺失的当前字段：

provider: "log" → provider: "mock"
twilio.from → fromNumber
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
realtime.agentContext.includeSystemPrompt 已移除。具有共享上下文解析器的主机始终包含代理上下文指导；realtime.agentContext 控制可选的配置身份和配置文件。受支持的旧版主机会保留其可选、有界的上下文胶囊。参见代理语音上下文。

会话范围¶

默认情况下，Voice Call 使用 sessionScope: "per-phone"，以便同一来电者的重复呼叫保留对话记忆。当每次运营商呼叫都应从全新上下文开始时，请设置 sessionScope: "per-call"，例如前台接待、预订、IVR 或 Google Meet 桥接流程，其中同一电话号码可能代表不同的会议。

设置 sessionScope: "main" 可将每个呼叫路由到已配置代理的主会话 agent:<agentId>:main；当核心 session.scope 为 "global" 时，则为 global。自定义核心 session.mainKey 值会被忽略。原始呼叫轮次随后会与代理的主会话共享历史，因此仅当该共享上下文是有意为之时才使用此设置。

对于 per-phone 和 per-call，Voice Call 会在已配置的代理命名空间（agent:<agentId>:voice:*）下存储生成的会话键。原始显式集成键会解析到同一命名空间：规范的 agent:<configuredAgentId>:* 键会保留该所有者，并遵循核心主会话/全局作用域别名；外部或格式错误的 agent:* 输入会作为不透明键限定在已配置代理下；global 和 unknown 仍保持为全局哨兵值。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw