跳转至

配置

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

配置

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

Note

Voice-call 凭据接受 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 */ },
        },
      },
    },
  },
}

选择呼叫所有者

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

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

配置参考

上述未显示的 plugins.entries.voice-call.config 顶层键:

键 默认值 说明
enabled false 主开关。
inboundPolicy "disabled" disabled | allowlist | pairing | open。参见 入站呼叫。
allowFrom [] 用于 inboundPolicy: "allowlist" 的 E.164 允许列表。
callbacks disabled 实时呼叫仅接受最近的出站接收方;经典 STT/TTS 仍应用入站策略。
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 唯一 agent 用于响应生成和会话存储的 Agent。存在多个 agent 时需显式设置。
responseModel 未设置 覆盖经典(非实时)响应的默认模型。
responseSystemPrompt 生成 经典响应的自定义系统提示词。
responseTimeoutMs 30000 经典响应生成的超时时间(毫秒)。

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

Twilio 语音信箱检测调优

设置 voicemail.detection: "twilio" 以启用答录机检测。 以下可选的 voicemail 键用于调整 Twilio 在出站呼叫上的检测:

键 默认值 允许范围
machineDetectionSpeechThresholdMs 6000 1000–6000 ms
machineDetectionSpeechEndThresholdMs 1200 500–5000 ms
machineDetectionSilenceTimeoutMs 5000 2000–10000 ms
machineDetectionTimeoutMs 30000 3000–59000 ms,且为 1000 的倍数

语音阈值默认采用 Twilio 的最大值六秒,以减少将健谈人类和较长商务问候语误判为机器的情况。 Twilio 自身的默认值为 2400 ms。更高的阈值也会延迟机器检测;它无法可靠地将连续说话三十秒而不停顿的人类分类为人类。请在具有代表性的问候语和运营商之间进行调整。

其他默认值与 Twilio 一致。所有值均为毫秒整数; 插件会将 machineDetectionTimeoutMs 转换为整数秒,用于 Calls API 的 MachineDetectionTimeout。其余三个值以毫秒直接传递。允许范围遵循 Twilio 的 AMD 调优参考 及其无效检测配置错误。

提供商暴露与安全说明
  • Twilio、Telnyx 和 Plivo 都需要一个可公开访问的 webhook URL。
  • mock 是本地开发提供商(无网络调用)。
  • Telnyx 需要 telnyx.publicKey(或 TELNYX_PUBLIC_KEY),除非 skipSignatureVerification 为 true。
  • skipSignatureVerification 仅用于本地测试。
  • 在 ngrok 免费套餐中,请将 publicUrl 设置为确切的 ngrok URL;签名验证始终强制执行。
  • tunnel.allowNgrokFreeTierLoopbackBypass: true 在 tunnel.provider="ngrok" 且 serve.bind 为 loopback(ngrok 本地代理)时,信任来自 loopback 请求的转发头。这会重建用于签名的公开 URL;仍需要有效的 Twilio 签名。
  • 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)限制所有打开的媒体流套接字(待处理 + 活动)。
旧版配置迁移

Voice Call 接受当前配置结构。2026 年 7 月之前已弃用的结构不再包含迁移。请使用以下替换项手动更新旧配置,并保留任何现有当前值:

  • 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 已移除。使用共享上下文解析器的宿主始终包含 agent-context 指导;realtime.agentContext 控制可选的已配置身份和配置文件。受支持的旧版宿主保留其可选的、有界的上下文胶囊。参见 Agent 语音上下文。

会话作用域

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

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

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

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