配置
插件配置键、呼叫所有者、完整配置参考表以及会话范围。属于 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→fromNumberstreaming.sttProvider→streaming.providerstreaming.openaiApiKey→streaming.providers.openai.apiKeystreaming.sttModel→streaming.providers.openai.modelstreaming.silenceDurationMs→streaming.providers.openai.silenceDurationMsstreaming.vadThreshold→streaming.providers.openai.vadThresholdrealtime.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