diff --git a/docs/zh-CN/plugins/voice-call.md b/docs/zh-CN/plugins/voice-call.md index d870d42fc..98b5a309b 100644 --- a/docs/zh-CN/plugins/voice-call.md +++ b/docs/zh-CN/plugins/voice-call.md @@ -1,32 +1,26 @@ --- read_when: - - 你想从 OpenClaw 发起一通外拨语音电话 + - 你想从 OpenClaw 发起外拨语音通话 - 你正在配置或开发语音通话插件 - - 你需要在电话通信中使用实时语音或流式转录 + - 你需要电话场景中的实时语音或流式转录 sidebarTitle: Voice call -summary: 通过 Twilio、Telnyx 或 Plivo 拨打外呼并接听呼入语音通话，并可选择启用实时语音和流式转录 +summary: 通过 Twilio、Telnyx 或 Plivo 发起出站语音通话并接收入站语音通话，支持可选的实时语音和流式转录 title: 语音通话插件 x-i18n: - generated_at: "2026-05-01T06:21:21Z" + generated_at: "2026-05-01T06:25:06Z" model: gpt-5.5 provider: openai - source_hash: ea655c1fab7a92056a8469018e9719e015c6492d96419dc3a6757efd90c14508 + source_hash: 60ee0997676d6bb800184197b7bbb2ccde40ec30d9487c58e7b5b95b0762a6d0 source_path: plugins/voice-call.md workflow: 16 --- -通过插件为 OpenClaw 提供语音通话。支持出站通知、 -多轮对话、全双工实时语音、流式 -转录，以及带允许列表策略的入站通话。 +通过插件为 OpenClaw 提供语音通话。支持出站通知、多轮对话、全双工实时语音、流式转写，以及带允许列表策略的入站呼叫。 -**当前提供商：** `twilio`（Programmable Voice + Media Streams）、 -`telnyx`（Call Control v2）、`plivo`（Voice API + XML transfer + GetInput -speech）、`mock`（开发/无网络）。 +**当前提供商：** `twilio`（Programmable Voice + Media Streams）、`telnyx`（Call Control v2）、`plivo`（Voice API + XML transfer + GetInput speech）、`mock`（开发/无网络）。 -Voice Call 插件在 **Gateway 网关进程内**运行。如果你使用 -远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件， -然后重启 Gateway 网关以加载它。 +Voice Call 插件在 **Gateway 网关进程内部**运行。如果你使用远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件，然后重启 Gateway 网关以加载它。 ## 快速开始 @@ -48,28 +42,20 @@ Voice Call 插件在 **Gateway 网关进程内**运行。如果你使用 - 如果 npm 报告 OpenClaw 拥有的软件包已弃用，该软件包版本 - 来自较旧的外部软件包发布线；请使用当前打包的 OpenClaw - 构建，或在发布更新的 npm 软件包之前使用本地文件夹路径。 + 如果 npm 报告 OpenClaw 拥有的软件包已弃用，该软件包版本来自较旧的外部软件包发布线；请使用当前打包的 OpenClaw 构建，或在新的 npm 软件包发布前使用本地文件夹路径。 - 之后重启 Gateway 网关，以便加载插件。 + 随后重启 Gateway 网关，以便加载插件。 - 在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方 - [配置](#configuration)）。至少需要： - `provider`、提供商凭证、`fromNumber`，以及一个公开 - 可访问的 webhook URL。 + 在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方的[配置](#configuration)）。至少需要：`provider`、提供商凭证、`fromNumber`，以及一个可公开访问的 webhook URL。 ```bash openclaw voicecall setup ``` - 默认输出可在聊天日志和终端中阅读。它会检查 - 插件启用状态、提供商凭证、webhook 暴露情况，以及是否 - 仅启用了一个音频模式（`streaming` 或 `realtime`）。脚本可使用 - `--json`。 + 默认输出适合在聊天日志和终端中阅读。它会检查插件是否启用、提供商凭证、webhook 暴露情况，以及是否只有一种音频模式（`streaming` 或 `realtime`）处于活动状态。脚本请使用 `--json`。 @@ -78,8 +64,7 @@ Voice Call 插件在 **Gateway 网关进程内**运行。如果你使用 openclaw voicecall smoke --to "+15555550123" ``` - 两者默认都是空运行。添加 `--yes` 才会实际发起一个简短的 - 出站通知通话： + 两者默认都是试运行。添加 `--yes` 才会实际发起一个简短的出站通知呼叫： ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -89,21 +74,15 @@ Voice Call 插件在 **Gateway 网关进程内**运行。如果你使用 -对于 Twilio、Telnyx 和 Plivo，设置必须解析为一个**公开 webhook URL**。 -如果 `publicUrl`、隧道 URL、Tailscale URL，或 serve 回退 -解析到 loopback 或私有网络空间，设置会失败，而不是 -启动一个无法接收运营商 webhook 的提供商。 +对于 Twilio、Telnyx 和 Plivo，设置必须解析为一个**公开 webhook URL**。如果 `publicUrl`、隧道 URL、Tailscale URL 或 serve 回退解析到 loopback 或专用网络空间，设置会失败，而不是启动一个无法接收运营商 webhook 的提供商。 ## 配置 -如果 `enabled: true`，但所选提供商缺少凭证， -Gateway 网关启动时会记录一个 setup-incomplete 警告，其中包含缺失键名， -并跳过启动运行时。命令、RPC 调用和 agent 工具在使用时仍会 -返回确切缺失的提供商配置。 +如果 `enabled: true`，但所选提供商缺少凭证，Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失键名，并跳过启动运行时。命令、RPC 调用和智能体工具在使用时仍会返回确切缺失的提供商配置。 -Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.authToken` 和 `plugins.entries.voice-call.config.tts.providers.*.apiKey` 会通过标准 SecretRef 表面解析；参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。 +语音通话凭证接受 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 凭证表面](/zh-CN/reference/secretref-credential-surface)。 ```json5 @@ -166,29 +145,25 @@ Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.au - Twilio、Telnyx 和 Plivo 都需要一个**可公开访问**的 webhook URL。 - - `mock` 是本地开发提供商（不进行网络调用）。 + - `mock` 是本地开发提供商（无网络调用）。 - Telnyx 需要 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`），除非 `skipSignatureVerification` 为 true。 - `skipSignatureVerification` 仅用于本地测试。 - - 在 ngrok 免费层，请将 `publicUrl` 设置为确切的 ngrok URL；签名验证始终强制执行。 - - `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地 agent）时，允许签名无效的 Twilio webhook。仅限本地开发。 - - Ngrok 免费层 URL 可能会变化，或添加中间提示行为；如果 `publicUrl` 偏移，Twilio 签名会失败。生产环境：优先使用稳定域名或 Tailscale funnel。 + - 在 ngrok 免费层上，将 `publicUrl` 设置为精确的 ngrok URL；始终强制执行签名验证。 + - `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时，允许带无效签名的 Twilio webhook。仅限本地开发。 + - Ngrok 免费层 URL 可能会变化，或加入中间页行为；如果 `publicUrl` 漂移，Twilio 签名会失败。生产环境：优先使用稳定域名或 Tailscale funnel。 - - `streaming.preStartTimeoutMs` 会关闭从未发送有效 `start` 帧的 socket。 - - `streaming.maxPendingConnections` 限制未认证 pre-start socket 的总数。 - - `streaming.maxPendingConnectionsPerIp` 限制每个来源 IP 的未认证 pre-start socket 数量。 - - `streaming.maxConnections` 限制打开的媒体流 socket 总数（pending + active）。 + - `streaming.preStartTimeoutMs` 会关闭从未发送有效 `start` 帧的套接字。 + - `streaming.maxPendingConnections` 限制未认证的预启动套接字总数。 + - `streaming.maxPendingConnectionsPerIp` 限制每个来源 IP 的未认证预启动套接字数量。 + - `streaming.maxConnections` 限制打开的媒体流套接字总数（待处理 + 活动）。 - 使用 `provider: "log"`、`twilio.from` 或旧版 - `streaming.*` OpenAI 键的旧配置，会由 `openclaw doctor --fix` 重写。 - 运行时回退目前仍接受旧的 voice-call 键，但 - 重写路径是 `openclaw doctor --fix`，兼容 shim - 是临时的。 + 使用 `provider: "log"`、`twilio.from` 或旧版 `streaming.*` OpenAI 键的旧配置会由 `openclaw doctor --fix` 重写。运行时回退目前仍接受旧的 voice-call 键，但重写路径是 `openclaw doctor --fix`，兼容垫片是临时的。 - 自动迁移的流式键： + 自动迁移的 streaming 键： - `streaming.sttProvider` → `streaming.provider` - `streaming.openaiApiKey` → `streaming.providers.openai.apiKey` @@ -201,24 +176,21 @@ Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.au ## 实时语音对话 -`realtime` 为实时通话音频选择全双工实时语音提供商。 -它不同于 `streaming`，后者只会将音频转发给 -实时转录提供商。 +`realtime` 为实时通话音频选择全双工实时语音提供商。它与 `streaming` 分离，后者只会将音频转发给实时转写提供商。 -`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话请选择一个 -音频模式。 +`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每个呼叫请选择一种音频模式。 当前运行时行为： - Twilio Media Streams 支持 `realtime.enabled`。 - `realtime.provider` 是可选的。如果未设置，Voice Call 会使用第一个已注册的实时语音提供商。 -- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由各自的提供商插件注册。 +- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由它们的提供商插件注册。 - 提供商拥有的原始配置位于 `realtime.providers.` 下。 -- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。当调用者请求更深入推理、当前信息或普通 OpenClaw 工具时，实时模型可以调用它。 -- 如果 `realtime.provider` 指向未注册的提供商，或完全没有注册实时语音提供商，Voice Call 会记录警告并跳过实时媒体，而不是让整个插件失败。 -- 咨询会话键会在可用时复用现有语音会话，然后回退到主叫/被叫电话号码，以便后续咨询调用在通话期间保持上下文。 +- Voice Call 默认公开共享的 `openclaw_agent_consult` 实时工具。当来电者要求更深入的推理、当前信息或普通 OpenClaw 工具时，实时模型可以调用它。 +- 如果 `realtime.provider` 指向未注册的提供商，或根本没有注册实时语音提供商，Voice Call 会记录警告并跳过实时媒体，而不是让整个插件失败。 +- 咨询会话键会在可用时复用现有语音会话，然后回退到主叫/被叫电话号码，以便后续咨询调用在通话期间保留上下文。 ### 工具策略 @@ -226,17 +198,15 @@ Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.au | 策略 | 行为 | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `safe-read-only` | 暴露咨询工具，并将常规 agent 限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 | -| `owner` | 暴露咨询工具，并允许常规 agent 使用普通 agent 工具策略。 | -| `none` | 不暴露咨询工具。自定义 `realtime.tools` 仍会传递给实时提供商。 | +| `safe-read-only` | 暴露咨询工具，并将常规智能体限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 | +| `owner` | 暴露咨询工具，并允许常规智能体使用普通智能体工具策略。 | +| `none` | 不暴露咨询工具。自定义 `realtime.tools` 仍会透传给实时提供商。 | ### 实时提供商示例 - 默认值：API key 来自 `realtime.providers.google.apiKey`、 - `GEMINI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY`；模型 - `gemini-2.5-flash-native-audio-preview-12-2025`；语音 `Kore`。 + 默认值：API key 来自 `realtime.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY`；模型 `gemini-2.5-flash-native-audio-preview-12-2025`；语音 `Kore`。 ```json5 { @@ -291,28 +261,25 @@ Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.au -有关提供商特定的实时语音选项，请参见 [Google 提供商](/zh-CN/providers/google) 和 -[OpenAI provider](/zh-CN/providers/openai)。 +有关提供商特定的实时语音选项，请参阅 [Google 提供商](/zh-CN/providers/google) 和 [OpenAI provider](/zh-CN/providers/openai)。 -## 流式转录 +## 流式转写 -`streaming` 为实时通话音频选择实时转录提供商。 +`streaming` 为实时通话音频选择实时转写提供商。 当前运行时行为： -- `streaming.provider` 是可选的。如果未设置，Voice Call 会使用第一个已注册的实时转录提供商。 -- 内置实时转录提供商：Deepgram（`deepgram`）、ElevenLabs（`elevenlabs`）、Mistral（`mistral`）、OpenAI（`openai`）和 xAI（`xai`），由各自的提供商插件注册。 +- `streaming.provider` 是可选的。如果未设置，Voice Call 会使用第一个已注册的实时转写提供商。 +- 内置实时转写提供商：Deepgram（`deepgram`）、ElevenLabs（`elevenlabs`）、Mistral（`mistral`）、OpenAI（`openai`）和 xAI（`xai`），由它们的提供商插件注册。 - 提供商拥有的原始配置位于 `streaming.providers.` 下。 -- Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间通过转录提供商排队入站媒体，并且仅在实时转录准备就绪后才开始初始问候。 -- 如果 `streaming.provider` 指向未注册的提供商，或没有注册任何提供商，Voice Call 会记录警告并跳过媒体流式传输，而不是让整个插件失败。 +- 在 Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间将入站媒体通过转写提供商排队，并且仅在实时转写就绪后才开始初始问候。 +- 如果 `streaming.provider` 指向未注册的提供商，或没有注册任何提供商，Voice Call 会记录警告并跳过媒体流，而不是让整个插件失败。 ### 流式提供商示例 - 默认值：API key 为 `streaming.providers.openai.apiKey` 或 - `OPENAI_API_KEY`；模型 `gpt-4o-transcribe`；`silenceDurationMs: 800`； - `vadThreshold: 0.5`。 + 默认值：API key `streaming.providers.openai.apiKey` 或 `OPENAI_API_KEY`；模型 `gpt-4o-transcribe`；`silenceDurationMs: 800`；`vadThreshold: 0.5`。 ```json5 { @@ -343,7 +310,7 @@ Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.au 默认值：API key `streaming.providers.xai.apiKey` 或 `XAI_API_KEY`； - 端点 `wss://api.x.ai/v1/stt`；编码 `mulaw`；采样率 `8000`； + endpoint `wss://api.x.ai/v1/stt`；编码 `mulaw`；采样率 `8000`； `endpointingMs: 800`；`interimResults: true`。 ```json5 @@ -376,7 +343,8 @@ Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.au ## 通话的 TTS -Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你可以在插件配置下用**相同结构**覆盖它，它会与 `messages.tts` 深度合并。 +Voice Call 使用核心 `messages.tts` 配置来为通话提供流式 +语音。你可以在插件配置下用**相同形状**覆盖它 — 它会与 `messages.tts` 深度合并。 ```json5 { @@ -393,21 +361,22 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你 ``` -**Microsoft speech 会被语音通话忽略。** 电话音频需要 PCM；当前 Microsoft 传输协议不暴露电话 PCM 输出。 +**Microsoft speech 会在语音通话中被忽略。** 电话音频需要 PCM； +当前 Microsoft 传输层未暴露电话 PCM 输出。 行为说明： -- 插件配置内的旧版 `tts.` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）会由 `openclaw doctor --fix` 修复；提交的配置应使用 `tts.providers.`。 +- 插件配置中的旧版 `tts.` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）会由 `openclaw doctor --fix` 修复；提交的配置应使用 `tts.providers.`。 - 启用 Twilio 媒体流式传输时会使用核心 TTS；否则通话会回退到提供商原生语音。 -- 如果 Twilio 媒体流已经处于活动状态，Voice Call 不会回退到 TwiML ``。如果在该状态下电话 TTS 不可用，播放请求会失败，而不是混用两条播放路径。 -- 当电话 TTS 回退到次级提供商时，Voice Call 会记录一条包含提供商链（`from`、`to`、`attempts`）的警告，便于调试。 -- 当 Twilio 插话或流拆除清空待处理的 TTS 队列时，已排队的播放请求会结束结算，而不是让呼叫方一直等待播放完成。 +- 如果 Twilio 媒体流已经处于活动状态，Voice Call 不会回退到 TwiML ``。如果该状态下电话 TTS 不可用，播放请求会失败，而不是混用两条播放路径。 +- 当电话 TTS 回退到次级提供商时，Voice Call 会记录包含提供商链（`from`、`to`、`attempts`）的警告，方便调试。 +- 当 Twilio 插话或流拆除清空待处理 TTS 队列时，排队的播放请求会完成结算，而不是让呼叫者一直等待播放完成。 ### TTS 示例 - + ```json5 { messages: { @@ -421,7 +390,7 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你 } ``` - + ```json5 { plugins: { @@ -445,7 +414,7 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你 } ``` - + ```json5 { plugins: { @@ -469,9 +438,9 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你 -## 入站通话 +## 来电 -入站策略默认是 `disabled`。要启用入站通话，请设置： +来电策略默认为 `disabled`。要启用来电，请设置： ```json5 { @@ -482,52 +451,62 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你 ``` -`inboundPolicy: "allowlist"` 是低保证级别的来电号码筛选。插件会规范化提供商提供的 `From` 值，并将其与 `allowFrom` 比较。Webhook 验证会验证提供商投递和负载完整性，但它**不能**证明 PSTN/VoIP 来电号码的所有权。请将 `allowFrom` 视为来电号码过滤，而不是强来电方身份。 +`inboundPolicy: "allowlist"` 是低可信度的来电号码筛选。该 +插件会规范化提供商给出的 `From` 值，并将其与 +`allowFrom` 比较。Webhook 验证会认证提供商投递和 +payload 完整性，但它**不能**证明 PSTN/VoIP 主叫号码 +所有权。请将 `allowFrom` 视为来电号码过滤，而不是强来电者 +身份。 -自动响应使用智能体系统。使用 `responseModel`、`responseSystemPrompt` 和 `responseTimeoutMs` 进行调优。 +自动回复使用智能体系统。可通过 `responseModel`、 +`responseSystemPrompt` 和 `responseTimeoutMs` 调整。 ### 语音输出契约 -对于自动响应，Voice Call 会向系统提示追加严格的语音输出契约： +对于自动回复，Voice Call 会向系统提示追加严格的语音输出契约： ```text {"spoken":"..."} ``` -Voice Call 会以防御方式提取语音文本： +Voice Call 会防御性地提取语音文本： -- 忽略标记为推理/错误内容的负载。 -- 解析直接 JSON、围栏 JSON 或内联 `"spoken"` 键。 +- 忽略标记为推理/错误内容的 payload。 +- 解析直接 JSON、围栏 JSON，或内联 `"spoken"` 键。 - 回退到纯文本，并移除可能的规划/元信息开头段落。 -这会让语音播放聚焦在面向来电方的文本上，并避免将规划文本泄漏到音频中。 +这会让语音播放聚焦于面向来电者的文本，并避免将规划文本泄漏到音频中。 ### 对话启动行为 -对于出站 `conversation` 通话，首条消息处理与实时播放状态绑定： +对于出站 `conversation` 通话，首条消息处理与实时 +播放状态绑定： -- 仅当初始问候正在主动播放时，才会抑制插话队列清空和自动响应。 -- 如果初始播放失败，通话会返回 `listening`，并且初始消息会保留在队列中以便重试。 -- Twilio 流式传输的初始播放会在流连接时开始，不会有额外延迟。 -- 插话会中止活动播放，并清空已排队但尚未播放的 Twilio TTS 条目。被清空的条目会解析为已跳过，因此后续响应逻辑可以继续，而无需等待永远不会播放的音频。 -- 实时语音对话使用实时流自己的开场轮次。Voice Call **不会**为该初始消息发布旧版 `` TwiML 更新，因此出站 `` 会话会保持连接。 +- 仅当初始问候语正在主动播放时，才会抑制插话队列清空和自动回复。 +- 如果初始播放失败，通话会回到 `listening`，初始消息仍会排队以便重试。 +- Twilio 流式传输的初始播放会在流连接时立即开始，不添加额外延迟。 +- 插话会中止活动播放，并清除已排队但尚未播放的 Twilio TTS 条目。被清除的条目会解析为已跳过，因此后续回复逻辑可以继续，而无需等待永远不会播放的音频。 +- 实时语音对话使用实时流自己的开场轮次。Voice Call **不会**为该初始消息发布旧版 `` TwiML 更新，因此出站 `` 会话会保持附加状态。 ### Twilio 流断开宽限期 -当 Twilio 媒体流断开连接时，Voice Call 会等待 **2000 ms** 后再自动结束通话： +当 Twilio 媒体流断开时，Voice Call 会等待 **2000 ms**，然后 +自动结束通话： - 如果流在该窗口内重新连接，则取消自动结束。 - 如果宽限期后没有流重新注册，则结束通话，以防止活动通话卡住。 -## 陈旧通话清理器 +## 过期通话清理器 -使用 `staleCallReaperSeconds` 结束从未收到终止 webhook 的通话（例如永不完成的通知模式通话）。默认值为 `0`（禁用）。 +使用 `staleCallReaperSeconds` 结束从未收到终止 +webhook 的通话（例如从未完成的通知模式通话）。默认值为 +`0`（禁用）。 推荐范围： -- **生产环境：** 对通知式流程使用 `120`–`300` 秒。 -- 保持此值**高于 `maxDurationSeconds`**，这样正常通话才能完成。一个好的起点是 `maxDurationSeconds + 30–60` 秒。 +- **生产：** 对于通知式流程，使用 `120`–`300` 秒。 +- 保持该值**高于 `maxDurationSeconds`**，以便正常通话可以完成。一个好的起点是 `maxDurationSeconds + 30–60` 秒。 ```json5 { @@ -544,25 +523,26 @@ Voice Call 会以防御方式提取语音文本： } ``` -## Webhook 安全性 +## Webhook 安全 -当代理或隧道位于 Gateway 网关前面时，插件会重建公共 URL 以进行签名验证。这些选项控制信任哪些转发标头： +当代理或隧道位于 Gateway 网关前方时，该插件会 +重建用于签名验证的公共 URL。以下选项控制信任哪些转发头： - 允许列表中的转发标头主机。 + 允许列表中的转发头主机。 - 在没有允许列表的情况下信任转发标头。 + 无需允许列表即可信任转发头。 - 仅当请求远程 IP 与列表匹配时，才信任转发标头。 + 仅当请求远程 IP 匹配列表时，才信任转发头。 -额外保护： +附加防护： -- Twilio 和 Plivo 启用了 webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。 -- Twilio 对话轮次会在 `` 回调中包含每轮 token，因此陈旧/重放的语音回调无法满足较新的待处理转录轮次。 -- 当缺少提供商所需的签名标头时，未认证的 webhook 请求会在读取正文前被拒绝。 +- Twilio 和 Plivo 已启用 Webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。 +- Twilio 对话轮次会在 `` 回调中包含逐轮 token，因此过期/重放的语音回调无法满足更新的待处理转录轮次。 +- 当缺少提供商所需的签名头时，未经身份验证的 webhook 请求会在读取正文前被拒绝。 - voice-call webhook 使用共享的预认证正文配置（64 KB / 5 秒），并在签名验证前加上按 IP 计的进行中请求上限。 使用稳定公共主机的示例： @@ -599,15 +579,21 @@ openclaw voicecall latency # summarize turn latency from lo openclaw voicecall expose --mode funnel ``` -当 Gateway 网关已经运行时，操作型 `voicecall` 命令会委托给 Gateway 网关拥有的 voice-call 运行时，因此 CLI 不会绑定第二个 webhook 服务器。如果无法访问 Gateway 网关，这些命令会回退到独立 CLI 运行时。 +当 Gateway 网关已经运行时，操作性 `voicecall` 命令会委托给 +Gateway 网关拥有的 voice-call 运行时，因此 CLI 不会绑定第二个 +webhook 服务器。如果无法访问 Gateway 网关，这些命令会回退到 +独立 CLI 运行时。 -`latency` 从默认 voice-call 存储路径读取 `calls.jsonl`。使用 `--file ` 指向其他日志，并使用 `--last ` 将分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。 +`latency` 会从默认 voice-call 存储路径读取 `calls.jsonl`。 +使用 `--file ` 指向不同日志，使用 `--last ` 将 +分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 +p50/p90/p99。 ## 智能体工具 工具名称：`voice_call`。 -| 操作 | 参数 | +| 操作 | 参数 | | --------------- | ------------------------------------------ | | `initiate_call` | `message`, `to?`, `mode?`, `dtmfSequence?` | | `continue_call` | `callId`, `message` | @@ -616,11 +602,11 @@ openclaw voicecall expose --mode funnel | `end_call` | `callId` | | `get_status` | `callId` | -此仓库在 `skills/voice-call/SKILL.md` 提供了对应的 skill 文档。 +此仓库在 `skills/voice-call/SKILL.md` 提供了匹配的 skill 文档。 ## Gateway 网关 RPC -| 方法 | 参数 | +| 方法 | 参数 | | -------------------- | ------------------------------------------ | | `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` | | `voicecall.continue` | `callId`, `message` | @@ -629,7 +615,8 @@ openclaw voicecall expose --mode funnel | `voicecall.end` | `callId` | | `voicecall.status` | `callId` | -`dtmfSequence` 仅在 `mode: "conversation"` 下有效。通知模式通话如果需要连接后的数字，应在通话存在后使用 `voicecall.dtmf`。 +`dtmfSequence` 仅在 `mode: "conversation"` 下有效。通知模式通话 +如果需要连接后的数字，应在通话存在后使用 `voicecall.dtmf`。 ## 故障排除 @@ -642,9 +629,13 @@ openclaw voicecall setup openclaw voicecall setup --json ``` -对于 `twilio`、`telnyx` 和 `plivo`，`webhook-exposure` 必须为绿色。已配置的 `publicUrl` 如果指向本地或私有网络空间，仍然会失败，因为运营商无法回调到这些地址。不要将 `localhost`、`127.0.0.1`、`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、`192.168.x`、`169.254.x`、`fc00::/7` 或 `fd00::/8` 用作 `publicUrl`。 +对于 `twilio`、`telnyx` 和 `plivo`，`webhook-exposure` 必须为绿色。已 +配置的 `publicUrl` 在指向本地或私有网络空间时仍会失败， +因为运营商无法回调到这些地址。不要将 +`localhost`、`127.0.0.1`、`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、 +`192.168.x`、`169.254.x`、`fc00::/7` 或 `fd00::/8` 用作 `publicUrl`。 -使用一种公共暴露路径： +使用一条公共暴露路径： ```json5 { @@ -671,11 +662,11 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` 是一次试运行，除非你传入 `--yes`。 +除非你传入 `--yes`，否则 `voicecall smoke` 是一次试运行。 ### 提供商凭证失败 -检查所选提供商和必需的凭证字段： +检查所选提供商和必填凭证字段： - Twilio：`twilio.accountSid`、`twilio.authToken` 和 `fromNumber`，或 `TWILIO_ACCOUNT_SID`、`TWILIO_AUTH_TOKEN` 和 `TWILIO_FROM_NUMBER`。 @@ -683,10 +674,9 @@ openclaw voicecall smoke `fromNumber`。 - Plivo：`plivo.authId`、`plivo.authToken` 和 `fromNumber`。 -凭证必须存在于 Gateway 网关主机上。编辑本地 shell profile 不会影响已经运行的 -Gateway 网关，除非它重启或重新加载其环境。 +凭证必须存在于 Gateway 网关主机上。编辑本地 shell 配置文件不会影响已在运行的 Gateway 网关，除非它重启或重新加载其环境。 -### 通话开始但提供商 webhook 未到达 +### 通话已开始但提供商 webhook 未到达 确认提供商控制台指向准确的公开 webhook URL： @@ -704,65 +694,54 @@ openclaw voicecall tail 常见原因： - `publicUrl` 指向的路径与 `serve.path` 不同。 -- 隧道 URL 在 Gateway 网关启动后发生变化。 -- 代理转发了请求，但剥离或重写了 host/proto header。 +- 隧道 URL 在 Gateway 网关启动后发生了变化。 +- 代理转发了请求，但剥离或重写了 host/proto 标头。 - 防火墙或 DNS 将公开主机名路由到了 Gateway 网关以外的位置。 - Gateway 网关重启时未启用 Voice Call 插件。 -当 Gateway 网关前面有反向代理或隧道时，将 -`webhookSecurity.allowedHosts` 设置为公开主机名，或对已知代理地址使用 -`webhookSecurity.trustedProxyIPs`。仅当代理边界由你控制时，才使用 -`webhookSecurity.trustForwardingHeaders`。 +当反向代理或隧道位于 Gateway 网关前面时，将 `webhookSecurity.allowedHosts` 设置为公开主机名，或对已知代理地址使用 `webhookSecurity.trustedProxyIPs`。仅当代理边界由你控制时才使用 `webhookSecurity.trustForwardingHeaders`。 ### 签名验证失败 提供商签名会根据 OpenClaw 从传入请求重建的公开 URL 进行检查。如果签名失败： -- 确认提供商 webhook URL 与 `publicUrl` 完全匹配，包括 - scheme、host 和 path。 -- 对于 ngrok 免费层 URL，当隧道主机名变化时更新 `publicUrl`。 -- 确保代理保留原始 host 和 proto header，或配置 - `webhookSecurity.allowedHosts`。 +- 确认提供商 webhook URL 与 `publicUrl` 完全匹配，包括 scheme、host 和 path。 +- 对于 ngrok 免费层 URL，请在隧道主机名变化时更新 `publicUrl`。 +- 确保代理保留原始 host 和 proto 标头，或配置 `webhookSecurity.allowedHosts`。 - 不要在本地测试之外启用 `skipSignatureVerification`。 ### Google Meet Twilio 加入失败 -Google Meet 使用此插件进行 Twilio 拨入加入。先验证 Voice Call： +Google Meet 使用此插件进行 Twilio 拨入加入。首先验证 Voice Call： ```bash openclaw voicecall setup openclaw voicecall smoke --to "+15555550123" ``` -然后显式验证 Google Meet 传输协议： +然后显式验证 Google Meet 传输： ```bash openclaw googlemeet setup --transport twilio ``` -如果 Voice Call 状态正常，但 Meet 参与者始终未加入，请检查 Meet -拨入号码、PIN 和 `--dtmf-sequence`。电话通话可能是正常的，但会议会拒绝或忽略不正确的 -DTMF 序列。 +如果 Voice Call 正常但 Meet 参与者从未加入，请检查 Meet 拨入号码、PIN 和 `--dtmf-sequence`。电话通话可能是正常的，但会议会拒绝或忽略错误的 DTMF 序列。 -Google Meet 会将 Meet DTMF 序列和介绍文本传给 `voicecall.start`。 -对于 Twilio 通话，Voice Call 会先提供 DTMF TwiML，重定向回 -webhook，然后打开实时媒体流，以便在电话参与者加入会议后生成已保存的介绍内容。 +Google Meet 会将 Meet DTMF 序列和介绍文本传给 `voicecall.start`。对于 Twilio 通话，Voice Call 会先提供 DTMF TwiML，重定向回 webhook，然后打开实时媒体流，以便在电话参与者加入会议后生成已保存的介绍。 ### 实时通话没有语音 -确认只启用了一种音频模式。`realtime.enabled` 和 -`streaming.enabled` 不能同时为 true。 +确认只启用了一个音频模式。`realtime.enabled` 和 `streaming.enabled` 不能同时为 true。 对于实时 Twilio 通话，还要验证： - 已加载并注册实时提供商插件。 - `realtime.provider` 未设置，或命名了一个已注册的提供商。 - 提供商 API key 可供 Gateway 网关进程使用。 -- `openclaw voicecall tail` 显示媒体流已被接受，并且实时 - 提供商在初始问候前已就绪。 +- `openclaw voicecall tail` 在初始问候之前显示媒体流已接受，并且实时提供商已就绪。 ## 相关 -- [说话模式](/zh-CN/nodes/talk) +- [通话模式](/zh-CN/nodes/talk) - [文本转语音](/zh-CN/tools/tts) - [语音唤醒](/zh-CN/nodes/voicewake) diff --git a/docs/zh-CN/reference/secretref-credential-surface.md b/docs/zh-CN/reference/secretref-credential-surface.md index b04a17001..9f0bdc265 100644 --- a/docs/zh-CN/reference/secretref-credential-surface.md +++ b/docs/zh-CN/reference/secretref-credential-surface.md @@ -1,25 +1,25 @@ --- read_when: - 验证 SecretRef 凭证覆盖范围 - - 审查某个凭证是否符合 `secrets configure` 或 `secrets apply` 的适用条件 - - 验证某个凭证为何不在支持的适用范围内 -summary: Canonical 支持与不支持的 SecretRef 凭证适用范围 -title: SecretRef 凭证适用范围 + - 审核某个凭证是否可用于 `secrets configure` 或 `secrets apply` + - 验证凭证为何超出受支持范围 +summary: 规范的受支持与不受支持的 SecretRef 凭据范围 +title: SecretRef 凭证接口面 x-i18n: - generated_at: "2026-04-27T06:21:52Z" - model: gpt-5.4 + generated_at: "2026-05-01T06:25:05Z" + model: gpt-5.5 provider: openai - source_hash: b04902427e9851cc36c1dfd07ed44b46b55450c251075e9955af6696f08bc334 + source_hash: 41111ac82142c906005e0f585c86f2ff0b454afdaec07343c295e6b83571718e source_path: reference/secretref-credential-surface.md - workflow: 15 + workflow: 16 --- -本页定义了规范的 SecretRef 凭证适用范围。 +本页定义规范的 SecretRef 凭证表面。 -适用范围意图： +范围意图： -- 适用范围内：严格限定为用户提供、且 OpenClaw 不会签发或轮换的凭证。 -- 适用范围外：运行时签发或会轮换的凭证、OAuth 刷新材料，以及类似会话的工件。 +- 范围内：严格由用户提供且 OpenClaw 不签发或轮换的凭证。 +- 范围外：运行时签发或轮换的凭证、OAuth 刷新材料，以及类似会话的工件。 ## 支持的凭证 @@ -57,6 +57,8 @@ x-i18n: - `plugins.entries.firecrawl.config.webSearch.apiKey` - `plugins.entries.minimax.config.webSearch.apiKey` - `plugins.entries.tavily.config.webSearch.apiKey` +- `plugins.entries.voice-call.config.realtime.providers.*.apiKey` +- `plugins.entries.voice-call.config.streaming.providers.*.apiKey` - `plugins.entries.voice-call.config.tts.providers.*.apiKey` - `plugins.entries.voice-call.config.twilio.authToken` - `tools.web.search.apiKey` @@ -110,34 +112,34 @@ x-i18n: - `channels.zalo.webhookSecret` - `channels.zalo.accounts.*.botToken` - `channels.zalo.accounts.*.webhookSecret` -- `channels.googlechat.serviceAccount`，通过同级的 `serviceAccountRef`（兼容性例外） -- `channels.googlechat.accounts.*.serviceAccount`，通过同级的 `serviceAccountRef`（兼容性例外） +- `channels.googlechat.serviceAccount` 通过同级 `serviceAccountRef`（兼容性例外） +- `channels.googlechat.accounts.*.serviceAccount` 通过同级 `serviceAccountRef`（兼容性例外） ### `auth-profiles.json` 目标（`secrets configure` + `secrets apply` + `secrets audit`） -- `profiles.*.keyRef`（`type: "api_key"`；当 `auth.profiles..mode = "oauth"` 时不受支持） -- `profiles.*.tokenRef`（`type: "token"`；当 `auth.profiles..mode = "oauth"` 时不受支持） +- `profiles.*.keyRef`（`type: "api_key"`；当 `auth.profiles..mode = "oauth"` 时不支持） +- `profiles.*.tokenRef`（`type: "token"`；当 `auth.profiles..mode = "oauth"` 时不支持） [//]: # "secretref-supported-list-end" -说明： +注意： - Auth-profile 计划目标需要 `agentId`。 - 计划条目以 `profiles.*.key` / `profiles.*.token` 为目标，并写入同级引用（`keyRef` / `tokenRef`）。 -- Auth-profile 引用已包含在运行时解析和审计覆盖范围内。 -- 在 `openclaw.json` 中，SecretRef 必须使用结构化对象，例如 `{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}`。在 SecretRef 凭证路径上，旧版 `secretref-env:` 标记字符串会被拒绝；请运行 `openclaw doctor --fix` 迁移有效标记。 -- OAuth 策略防护：`auth.profiles..mode = "oauth"` 不能与该配置文件的 SecretRef 输入组合使用。违反此策略时，启动/热重载和 auth-profile 解析都会快速失败。 -- 对于由 SecretRef 管理的模型提供商，生成的 `agents/*/agent/models.json` 条目会保留非秘密标记（而不是已解析的秘密值）用于 `apiKey`/请求头适用范围。 -- 标记持久化以源配置为权威：OpenClaw 从当前源配置快照（解析前）写入标记，而不是从已解析的运行时秘密值写入。 +- Auth-profile 引用包含在运行时解析和审计覆盖范围内。 +- 在 `openclaw.json` 中，SecretRef 必须使用结构化对象，例如 `{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}`。旧版 `secretref-env:` 标记字符串会在 SecretRef 凭证路径上被拒绝；运行 `openclaw doctor --fix` 以迁移有效标记。 +- OAuth 策略保护：`auth.profiles..mode = "oauth"` 不能与该配置档案的 SecretRef 输入组合使用。违反此策略时，启动/重新加载和 auth-profile 解析会快速失败。 +- 对于由 SecretRef 管理的模型提供商，生成的 `agents/*/agent/models.json` 条目会为 `apiKey`/标头表面持久化非机密标记（而不是已解析的机密值）。 +- 标记持久化以来源为准：OpenClaw 会从活动来源配置快照（解析前）写入标记，而不是从已解析的运行时机密值写入。 - 对于 Web 搜索： - - 在显式提供商模式下（设置了 `tools.web.search.provider`），只有所选提供商的键处于活动状态。 - - 在自动模式下（未设置 `tools.web.search.provider`），只有按优先级成功解析的第一个提供商键处于活动状态。 - - 在自动模式下，未被选中的提供商引用在被选中前都视为非活动状态。 - - 在兼容性窗口期间，旧版 `tools.web.search.*` 提供商路径仍会解析，但规范的 SecretRef 适用范围是 `plugins.entries..config.webSearch.*`。 + - 在显式提供商模式（已设置 `tools.web.search.provider`）下，只有所选提供商密钥处于活动状态。 + - 在自动模式（未设置 `tools.web.search.provider`）下，只有第一个按优先级解析成功的提供商密钥处于活动状态。 + - 在自动模式下，未选中的提供商引用在被选中前会被视为非活动。 + - 旧版 `tools.web.search.*` 提供商路径在兼容窗口内仍会解析，但规范的 SecretRef 表面是 `plugins.entries..config.webSearch.*`。 ## 不支持的凭证 -不在适用范围内的凭证包括： +范围外凭证包括： [//]: # "secretref-unsupported-list-start" @@ -153,11 +155,11 @@ x-i18n: [//]: # "secretref-unsupported-list-end" -原因： +理由： -- 这些凭证属于已签发、会轮换、携带会话状态，或 OAuth 持久化类别，不适合只读的外部 SecretRef 解析。 +- 这些凭证属于已签发、会轮换、承载会话，或 OAuth 持久类，不适合只读外部 SecretRef 解析。 -## 相关内容 +## 相关 -- [Secrets 管理](/zh-CN/gateway/secrets) +- [机密管理](/zh-CN/gateway/secrets) - [Auth 凭证语义](/zh-CN/auth-credential-semantics)