跳转至

TTS 和呼入通话

电话 TTS、呼入策略与按号码路由、语音输出契约、对话启动,以及过期呼叫回收器。属于 Voice call 插件 指南的一部分。

通话 TTS

Voice Call 使用核心 tts 配置在通话中流式传输语音。你可以在插件配置中使用相同的结构覆盖它——该配置会与 tts 深度合并。

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

Warning

Microsoft speech 在语音通话中被忽略。 电话合成需要一个实现了电话目标输出的提供商;Microsoft speech 提供商没有实现,因此它会在通话中被跳过,转而尝试回退链中的其他提供商。

行为说明:

  • 插件配置中的旧版 tts.<provider> 键(openai、elevenlabs、microsoft、edge)由 openclaw doctor --fix 修复;已提交的配置应使用 tts.providers.<provider>。
  • 当 Twilio 媒体流启用时,使用核心 TTS;否则通话会回退到提供商原生语音。
  • 如果 Twilio 媒体流已处于活动状态,Voice Call 不会回退到 TwiML <Say>。如果在该状态下电话 TTS 不可用,播放请求将失败,而不会混合两条播放路径。
  • 当电话 TTS 回退到次级提供商时,Voice Call 会记录一条包含提供商链(from、to、attempts)的警告,以便调试。
  • 当 Twilio 插入打断(barge-in)或流拆除清空待处理的 TTS 队列时,排队的播放请求会得到解决,而不会让呼叫者一直等待播放完成。
  • 恢复的呼叫者语音会丢弃仍在生成的较旧自动回复。Twilio 流会对语音开始(speech-start)和部分转写作出反应;运营商 webhook 调用会在新的语音事件到达时作出反应。显式语音请求仍然可用,并且已被接受的智能体工作可以完成,而无需说出过时的回复。

TTS 示例

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

呼入呼叫

呼入策略默认为 disabled。要启用呼入呼叫,请设置:

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

Warning

inboundPolicy: "allowlist" 是一种低保证度的来电显示(caller-ID)筛查。插件会规范化提供商提供的 From 值,并将其与 allowFrom 进行比较。Webhook 验证可以认证提供商的投递与载荷完整性,但不能证明 PSTN/VoIP 呼叫方号码的所有权。请将 allowFrom 视为来电显示过滤,而非强呼叫方身份。

自动回复使用智能体系统。可通过 responseModel、responseSystemPrompt 和 responseTimeoutMs 进行调整。

按号码路由

当一个 Voice Call 插件接收多个电话号码的呼叫,且每个号码应表现为一条不同线路时,可使用 numbers。例如,一个号码可以使用随意的个人助理,而另一个号码使用商务人设、不同的响应智能体以及不同的 TTS 语音。

路由根据提供商提供的被叫 To 号码选择。键必须是 E.164 号码。当呼叫到达时,Voice Call 会一次性解析匹配的路由,将匹配的路由存储在呼叫记录上,并在问候语、经典自动回复路径、实时咨询路径和 TTS 播放中复用该有效配置。如果没有匹配的路由,则使用全局 Voice Call 配置。外呼呼叫不使用 numbers;发起呼叫时请显式传递外呼目标、消息和会话。

路由覆盖仅支持以下字段:

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

tts 路由值会与全局 Voice Call tts 配置进行深度合并,因此你通常只需覆盖提供商语音即可:

{
  inboundGreeting: "Hello from the main line.",
  responseSystemPrompt: "You are the default voice assistant.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, how can I help?",
      responseSystemPrompt: "You are a concise baseball card specialist.",
      tts: {
        providers: {
          openai: { speakerVoice: "alloy" },
        },
      },
    },
  },
}

语音输出契约

对于自动回复,Voice Call 会在系统提示词中附加一个严格的语音输出契约,要求返回 {"spoken":"..."} JSON 回复。Voice Call 会防御性地提取语音文本:

  • 忽略标记为推理/错误内容的载荷。
  • 解析直接 JSON、围栏 JSON 或内联的 "spoken" 键。
  • 回退到纯文本,并移除可能的规划/元引导段落。

这可以使语音播放专注于面向呼叫者的文本,并避免将规划文本泄漏到音频中。

会话启动行为

对于出站 conversation 呼叫,首条消息的处理与实时播放状态相关联:

  • 打断时清空队列和自动响应仅在初始问候语正在主动播放期间被抑制。
  • 如果初始播放失败,呼叫会返回 listening,初始消息仍保留在队列中等待重试。
  • Twilio 流式传输的初始播放会在流连接时开始,没有额外延迟。
  • 打断会中止正在进行的播放,并清除已排队但尚未播放的 Twilio TTS 条目。被清除的条目会解析为已跳过,因此后续响应逻辑可以继续,而无需等待永远不会播放的音频。
  • 实时语音会话使用实时流自身的开场轮次。Voice Call 不会为该初始消息发布旧版 <Say> TwiML 更新,因此出站 <Connect><Stream> 会话保持连接。

Twilio 流断开宽限期

当 Twilio 经典流式传输或实时媒体流断开时,Voice Call 会等待 2000 ms 再自动结束呼叫:

  • 如果流在该窗口内重新连接,则取消自动结束。
  • 如果宽限期结束后没有流重新注册,则结束呼叫,以防止卡住的活跃呼叫。
  • 实时桥接/会话资源、排队音频、转录所有权以及进行中的咨询工作会立即关闭。只有呼叫/提供商最终处理会等待重新连接。

过期呼叫清理器

使用 staleCallReaperSeconds(默认 120)来结束从未被接听且从未进入实时会话状态的呼叫,例如通知模式呼叫,其中提供商从未投递终止 webhook。将其设置为 0 可禁用。

清理器每 30 秒运行一次,并且只结束没有 answeredAt 时间戳且尚未处于终止或实时(speaking/listening)状态的呼叫,因此已接听的会话永远不会被此定时器清理;maxDurationSeconds(默认 300)是单独的上限,用于结束运行时间过长的已接听呼叫。

Gateway 服务负责清理器调度,并在关闭其呼叫管理器之前等待待处理的提供商挂断。在提供商挂断待处理期间,错过的检查会合并。独立 CLI 呼叫绑定到其现有的可执行 CLI 所有者,该所有者保持活动状态,直到呼叫运行时关闭。

对于通知类流程,运营商可能较慢地投递振铃/接听 webhook,请将 staleCallReaperSeconds 提高到默认值以上,以免缓慢但正常的呼叫被过早清理;120-300 秒是合理的生产范围。

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

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