chore(i18n): refresh zh-CN translations

2026-05-01 06:26:21 +00:00 · 2026-05-01 06:26:21 +00:00 · 2aceec25cc
commit 2aceec25cc
parent 5582b9f1ac
2 changed files with 165 additions and 184 deletions
--- 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`（开发/无网络）。

 <Note>
-Voice Call 插件在 **Gateway 网关进程内**运行。如果你使用
-远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件，
-然后重启 Gateway 网关以加载它。
+Voice Call 插件在 **Gateway 网关进程内部**运行。如果你使用远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件，然后重启 Gateway 网关以加载它。
 </Note>

 ## 快速开始
@ -48,28 +42,20 @@ Voice Call 插件在 **Gateway 网关进程内**运行。如果你使用
      </Tab>
    </Tabs>

-    如果 npm 报告 OpenClaw 拥有的软件包已弃用，该软件包版本
-    来自较旧的外部软件包发布线；请使用当前打包的 OpenClaw
-    构建，或在发布更新的 npm 软件包之前使用本地文件夹路径。
+    如果 npm 报告 OpenClaw 拥有的软件包已弃用，该软件包版本来自较旧的外部软件包发布线；请使用当前打包的 OpenClaw 构建，或在新的 npm 软件包发布前使用本地文件夹路径。

-    之后重启 Gateway 网关，以便加载插件。
+    随后重启 Gateway 网关，以便加载插件。

  </Step>
  <Step title="配置提供商和 webhook">
-    在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方
-    [配置](#configuration)）。至少需要：
-    `provider`、提供商凭证、`fromNumber`，以及一个公开
-    可访问的 webhook URL。
+    在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方的[配置](#configuration)）。至少需要：`provider`、提供商凭证、`fromNumber`，以及一个可公开访问的 webhook URL。
  </Step>
  <Step title="验证设置">
    ```bash
    openclaw voicecall setup
    ```

-    默认输出可在聊天日志和终端中阅读。它会检查
-    插件启用状态、提供商凭证、webhook 暴露情况，以及是否
-    仅启用了一个音频模式（`streaming` 或 `realtime`）。脚本可使用
-    `--json`。
+    默认输出适合在聊天日志和终端中阅读。它会检查插件是否启用、提供商凭证、webhook 暴露情况，以及是否只有一种音频模式（`streaming` 或 `realtime`）处于活动状态。脚本请使用 `--json`。

  </Step>
  <Step title="冒烟测试">
@ -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 网关进程内**运行。如果你使用
 </Steps>

 <Warning>
-对于 Twilio、Telnyx 和 Plivo，设置必须解析为一个**公开 webhook URL**。
-如果 `publicUrl`、隧道 URL、Tailscale URL，或 serve 回退
-解析到 loopback 或私有网络空间，设置会失败，而不是
-启动一个无法接收运营商 webhook 的提供商。
+对于 Twilio、Telnyx 和 Plivo，设置必须解析为一个**公开 webhook URL**。如果 `publicUrl`、隧道 URL、Tailscale URL 或 serve 回退解析到 loopback 或专用网络空间，设置会失败，而不是启动一个无法接收运营商 webhook 的提供商。
 </Warning>

 ## 配置

-如果 `enabled: true`，但所选提供商缺少凭证，
-Gateway 网关启动时会记录一个 setup-incomplete 警告，其中包含缺失键名，
-并跳过启动运行时。命令、RPC 调用和 agent 工具在使用时仍会
-返回确切缺失的提供商配置。
+如果 `enabled: true`，但所选提供商缺少凭证，Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失键名，并跳过启动运行时。命令、RPC 调用和智能体工具在使用时仍会返回确切缺失的提供商配置。

 <Note>
-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)。
 </Note>

 ```json5
@ -166,29 +145,25 @@ Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.au
 <AccordionGroup>
  <Accordion title="提供商暴露与安全说明">
    - 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。

  </Accordion>
  <Accordion title="流式连接上限">
-    - `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` 限制打开的媒体流套接字总数（待处理 + 活动）。

  </Accordion>
  <Accordion title="旧版配置迁移">
-    使用 `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` 分离，后者只会将音频转发给实时转写提供商。

 <Warning>
-`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话请选择一个
-音频模式。
+`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每个呼叫请选择一种音频模式。
 </Warning>

 当前运行时行为：

 - Twilio Media Streams 支持 `realtime.enabled`。
 - `realtime.provider` 是可选的。如果未设置，Voice Call 会使用第一个已注册的实时语音提供商。
- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由各自的提供商插件注册。
+- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由它们的提供商插件注册。
 - 提供商拥有的原始配置位于 `realtime.providers.<providerId>` 下。
- 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` 仍会透传给实时提供商。                               |

 ### 实时提供商示例

 <Tabs>
  <Tab title="Google Gemini Live">
-    默认值：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
  </Tab>
 </Tabs>

-有关提供商特定的实时语音选项，请参见 [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.<providerId>` 下。
- Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间通过转录提供商排队入站媒体，并且仅在实时转录准备就绪后才开始初始问候。
- 如果 `streaming.provider` 指向未注册的提供商，或没有注册任何提供商，Voice Call 会记录警告并跳过媒体流式传输，而不是让整个插件失败。
+- 在 Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间将入站媒体通过转写提供商排队，并且仅在实时转写就绪后才开始初始问候。
+- 如果 `streaming.provider` 指向未注册的提供商，或没有注册任何提供商，Voice Call 会记录警告并跳过媒体流，而不是让整个插件失败。

 ### 流式提供商示例

 <Tabs>
  <Tab title="OpenAI">
-    默认值：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
  </Tab>
  <Tab title="xAI">
    默认值：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` 配置为通话提供流式语音。你
 ```

 <Warning>
-**Microsoft speech 会被语音通话忽略。** 电话音频需要 PCM；当前 Microsoft 传输协议不暴露电话 PCM 输出。
+**Microsoft speech 会在语音通话中被忽略。** 电话音频需要 PCM；
+当前 Microsoft 传输层未暴露电话 PCM 输出。
 </Warning>

 行为说明：

- 插件配置内的旧版 `tts.<provider>` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）会由 `openclaw doctor --fix` 修复；提交的配置应使用 `tts.providers.<provider>`。
+- 插件配置中的旧版 `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 插话或流拆除清空待处理的 TTS 队列时，已排队的播放请求会结束结算，而不是让呼叫方一直等待播放完成。
+- 如果 Twilio 媒体流已经处于活动状态，Voice Call 不会回退到 TwiML `<Say>`。如果该状态下电话 TTS 不可用，播放请求会失败，而不是混用两条播放路径。
+- 当电话 TTS 回退到次级提供商时，Voice Call 会记录包含提供商链（`from`、`to`、`attempts`）的警告，方便调试。
+- 当 Twilio 插话或流拆除清空待处理 TTS 队列时，排队的播放请求会完成结算，而不是让呼叫者一直等待播放完成。

 ### TTS 示例

 <Tabs>
-  <Tab title="Core TTS only">
+  <Tab title="仅核心 TTS">
 ```json5
 {
  messages: {
@ -421,7 +390,7 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你
 }
 ```
  </Tab>
-  <Tab title="Override to ElevenLabs (calls only)">
+  <Tab title="覆盖到 ElevenLabs（仅通话）">
 ```json5
 {
  plugins: {
@ -445,7 +414,7 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你
 }
 ```
  </Tab>
-  <Tab title="OpenAI model override (deep-merge)">
+  <Tab title="OpenAI 模型覆盖（深度合并）">
 ```json5
 {
  plugins: {
@ -469,9 +438,9 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你
  </Tab>
 </Tabs>

-## 入站通话
+## 来电

-入站策略默认是 `disabled`。要启用入站通话，请设置：
+来电策略默认为 `disabled`。要启用来电，请设置：

 ```json5
 {
@ -482,52 +451,62 @@ Voice Call 使用核心 `messages.tts` 配置为通话提供流式语音。你
 ```

 <Warning>
-`inboundPolicy: "allowlist"` 是低保证级别的来电号码筛选。插件会规范化提供商提供的 `From` 值，并将其与 `allowFrom` 比较。Webhook 验证会验证提供商投递和负载完整性，但它**不能**证明 PSTN/VoIP 来电号码的所有权。请将 `allowFrom` 视为来电号码过滤，而不是强来电方身份。
+`inboundPolicy: "allowlist"` 是低可信度的来电号码筛选。该
+插件会规范化提供商给出的 `From` 值，并将其与
+`allowFrom` 比较。Webhook 验证会认证提供商投递和
+payload 完整性，但它**不能**证明 PSTN/VoIP 主叫号码
+所有权。请将 `allowFrom` 视为来电号码过滤，而不是强来电者
+身份。
 </Warning>

-自动响应使用智能体系统。使用 `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 **不会**为该初始消息发布旧版 `<Say>` TwiML 更新，因此出站 `<Connect><Stream>` 会话会保持连接。
+- 仅当初始问候语正在主动播放时，才会抑制插话队列清空和自动回复。
+- 如果初始播放失败，通话会回到 `listening`，初始消息仍会排队以便重试。
+- Twilio 流式传输的初始播放会在流连接时立即开始，不添加额外延迟。
+- 插话会中止活动播放，并清除已排队但尚未播放的 Twilio TTS 条目。被清除的条目会解析为已跳过，因此后续回复逻辑可以继续，而无需等待永远不会播放的音频。
+- 实时语音对话使用实时流自己的开场轮次。Voice Call **不会**为该初始消息发布旧版 `<Say>` TwiML 更新，因此出站 `<Connect><Stream>` 会话会保持附加状态。

 ### 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。以下选项控制信任哪些转发头：

 <ParamField path="webhookSecurity.allowedHosts" type="string[]">
-  允许列表中的转发标头主机。
+  允许列表中的转发头主机。
 </ParamField>
 <ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
-  在没有允许列表的情况下信任转发标头。
+  无需允许列表即可信任转发头。
 </ParamField>
 <ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
-  仅当请求远程 IP 与列表匹配时，才信任转发标头。
+  仅当请求远程 IP 匹配列表时，才信任转发头。
 </ParamField>

-额外保护：
+附加防护：

- Twilio 和 Plivo 启用了 webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。
- Twilio 对话轮次会在 `<Gather>` 回调中包含每轮 token，因此陈旧/重放的语音回调无法满足较新的待处理转录轮次。
- 当缺少提供商所需的签名标头时，未认证的 webhook 请求会在读取正文前被拒绝。
+- Twilio 和 Plivo 已启用 Webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。
+- Twilio 对话轮次会在 `<Gather>` 回调中包含逐轮 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 <path>` 指向其他日志，并使用 `--last <n>` 将分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。
+`latency` 会从默认 voice-call 存储路径读取 `calls.jsonl`。
+使用 `--file <path>` 指向不同日志，使用 `--last <n>` 将
+分析限制为最后 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)
--- 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.<id>.mode = "oauth"` 时不受支持）
- `profiles.*.tokenRef`（`type: "token"`；当 `auth.profiles.<id>.mode = "oauth"` 时不受支持）
+- `profiles.*.keyRef`（`type: "api_key"`；当 `auth.profiles.<id>.mode = "oauth"` 时不支持）
+- `profiles.*.tokenRef`（`type: "token"`；当 `auth.profiles.<id>.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:<ENV_VAR>` 标记字符串会被拒绝；请运行 `openclaw doctor --fix` 迁移有效标记。
- OAuth 策略防护：`auth.profiles.<id>.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:<ENV_VAR>` 标记字符串会在 SecretRef 凭证路径上被拒绝；运行 `openclaw doctor --fix` 以迁移有效标记。
+- OAuth 策略保护：`auth.profiles.<id>.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.<plugin>.config.webSearch.*`。
+  - 在显式提供商模式（已设置 `tools.web.search.provider`）下，只有所选提供商密钥处于活动状态。
+  - 在自动模式（未设置 `tools.web.search.provider`）下，只有第一个按优先级解析成功的提供商密钥处于活动状态。
+  - 在自动模式下，未选中的提供商引用在被选中前会被视为非活动。
+  - 旧版 `tools.web.search.*` 提供商路径在兼容窗口内仍会解析，但规范的 SecretRef 表面是 `plugins.entries.<plugin>.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)