chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
de4bf96510
commit
af701e79ae
File diff suppressed because it is too large
Load Diff
@ -4,42 +4,36 @@ read_when:
|
||||
- 你正在配置或开发语音通话插件
|
||||
- 你需要在电话通信中使用实时语音或流式转录
|
||||
sidebarTitle: Voice call
|
||||
summary: 通过 Twilio、Telnyx 或 Plivo 发起外呼并接听来电，支持可选的实时语音和流式转录
|
||||
summary: 通过 Twilio、Telnyx 或 Plivo 发起外呼并接听入站语音通话，可选支持实时语音和流式转录
|
||||
title: 语音通话插件
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T21:57:59Z"
|
||||
generated_at: "2026-05-04T04:47:13Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a
|
||||
source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
通过插件为 OpenClaw 提供语音通话。支持出站通知、
|
||||
多轮对话、全双工实时语音、流式转写，
|
||||
以及带允许列表策略的入站来电。
|
||||
通过插件为 OpenClaw 提供语音通话。支持出站通知、多轮对话、全双工实时语音、流式转写，以及带允许列表策略的入站通话。
|
||||
|
||||
**当前提供商：** `twilio`（Programmable Voice + Media Streams）、
|
||||
`telnyx`（Call Control v2）、`plivo`（Voice API + XML 转接 + GetInput
|
||||
语音）、`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>
|
||||
|
||||
## 快速开始
|
||||
|
||||
<Steps>
|
||||
<Step title="安装插件">
|
||||
<Step title="Install the plugin">
|
||||
<Tabs>
|
||||
<Tab title="来自 npm">
|
||||
<Tab title="From npm">
|
||||
```bash
|
||||
openclaw plugins install @openclaw/voice-call
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="来自本地文件夹（开发）">
|
||||
<Tab title="From a local folder (dev)">
|
||||
```bash
|
||||
PLUGIN_SRC=./path/to/local/voice-call-plugin
|
||||
openclaw plugins install "$PLUGIN_SRC"
|
||||
@ -48,36 +42,29 @@ Voice Call 插件运行在 **Gateway 网关进程内**。如果你使用
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
使用裸包名以跟随当前官方发布标签。只有在需要可复现安装时，
|
||||
才固定到精确版本。
|
||||
使用裸包名可跟随当前官方发布标签。只有在需要可复现安装时，才固定到精确版本。
|
||||
|
||||
随后重启 Gateway 网关，以便插件加载。
|
||||
随后重启 Gateway 网关，让插件加载。
|
||||
|
||||
</Step>
|
||||
<Step title="配置提供商和 webhook">
|
||||
在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方
|
||||
[配置](#configuration)）。至少需要：
|
||||
`provider`、提供商凭证、`fromNumber`，以及一个可公开访问的 webhook URL。
|
||||
<Step title="Configure provider and webhook">
|
||||
在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方[配置](#configuration)）。至少需要：`provider`、提供商凭证、`fromNumber`，以及一个公网可访问的 webhook URL。
|
||||
</Step>
|
||||
<Step title="验证设置">
|
||||
<Step title="Verify setup">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
默认输出适合在聊天日志和终端中阅读。它会检查
|
||||
插件启用状态、提供商凭证、webhook 暴露情况，
|
||||
以及是否只有一种音频模式（`streaming` 或 `realtime`）处于活动状态。
|
||||
脚本请使用 `--json`。
|
||||
默认输出便于在聊天日志和终端中阅读。它会检查插件启用状态、提供商凭证、webhook 暴露情况，以及是否只有一种音频模式（`streaming` 或 `realtime`）处于启用状态。脚本请使用 `--json`。
|
||||
|
||||
</Step>
|
||||
<Step title="冒烟测试">
|
||||
<Step title="Smoke test">
|
||||
```bash
|
||||
openclaw voicecall smoke
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
两者默认都是空运行。添加 `--yes` 可真正发起一次简短的
|
||||
出站通知通话：
|
||||
两者默认都是 dry run。添加 `--yes` 会实际发起一次简短的出站通知通话：
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -87,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，或服务回退地址解析到 loopback 或私有网络空间，设置会失败，而不是启动一个无法接收运营商 webhook 的提供商。
|
||||
</Warning>
|
||||
|
||||
## 配置
|
||||
|
||||
如果 `enabled: true` 但所选提供商缺少凭证，
|
||||
Gateway 网关启动时会记录一条设置未完成警告，列出缺失键名，
|
||||
并跳过启动运行时。命令、RPC 调用和智能体工具在使用时仍会
|
||||
返回精确缺失的提供商配置。
|
||||
如果 `enabled: true`，但所选提供商缺少凭证，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 凭证表面](/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
|
||||
@ -174,29 +155,25 @@ Voice Call 凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.a
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="提供商暴露与安全说明">
|
||||
- Twilio、Telnyx 和 Plivo 都需要一个**可公开访问**的 webhook URL。
|
||||
<Accordion title="Provider exposure and security notes">
|
||||
- Twilio、Telnyx 和 Plivo 都需要一个**公网可访问**的 webhook URL。
|
||||
- `mock` 是本地开发提供商（无网络调用）。
|
||||
- Telnyx 需要 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`），除非 `skipSignatureVerification` 为 true。
|
||||
- 除非 `skipSignatureVerification` 为 true，否则 Telnyx 需要 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`）。
|
||||
- `skipSignatureVerification` 仅用于本地测试。
|
||||
- 在 ngrok 免费层上，将 `publicUrl` 设置为精确的 ngrok URL；签名验证始终强制执行。
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时，允许带无效签名的 Twilio webhook。仅限本地开发。
|
||||
- Ngrok 免费层 URL 可能会变化或增加中间页行为；如果 `publicUrl` 漂移，Twilio 签名会失败。生产环境：优先使用稳定域名或 Tailscale funnel。
|
||||
- 在 ngrok 免费层，将 `publicUrl` 设置为精确的 ngrok URL；签名验证始终强制执行。
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅当 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地 agent）时，允许带无效签名的 Twilio webhook。仅限本地开发。
|
||||
- Ngrok 免费层 URL 可能变化或添加插页行为；如果 `publicUrl` 偏移，Twilio 签名会失败。生产环境：优先使用稳定域名或 Tailscale funnel。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="流式连接上限">
|
||||
<Accordion title="Streaming connection caps">
|
||||
- `streaming.preStartTimeoutMs` 会关闭从未发送有效 `start` 帧的套接字。
|
||||
- `streaming.maxPendingConnections` 限制未经认证的预启动套接字总数。
|
||||
- `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未经认证预启动套接字数。
|
||||
- `streaming.maxConnections` 限制打开的媒体流套接字总数（待处理 + 活动）。
|
||||
- `streaming.maxPendingConnections` 限制未认证预启动套接字总数。
|
||||
- `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证预启动套接字数量。
|
||||
- `streaming.maxConnections` 限制打开的媒体流套接字总数（pending + active）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="旧版配置迁移">
|
||||
使用 `provider: "log"`、`twilio.from` 或旧版
|
||||
`streaming.*` OpenAI 键的较旧配置会由 `openclaw doctor --fix` 重写。
|
||||
运行时回退目前仍会接受旧的 voice-call 键，但
|
||||
重写路径是 `openclaw doctor --fix`，兼容垫片是
|
||||
临时的。
|
||||
<Accordion title="Legacy config migrations">
|
||||
使用 `provider: "log"`、`twilio.from` 或旧版 `streaming.*` OpenAI 键的旧配置会由 `openclaw doctor --fix` 重写。运行时回退目前仍接受旧语音通话键，但重写路径是 `openclaw doctor --fix`，兼容 shim 是临时的。
|
||||
|
||||
自动迁移的流式键：
|
||||
|
||||
@ -209,52 +186,44 @@ Voice Call 凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.a
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 会话作用域
|
||||
## 会话范围
|
||||
|
||||
默认情况下，Voice Call 使用 `sessionScope: "per-phone"`，因此来自
|
||||
同一来电者的重复来电会保留对话记忆。当每次运营商通话都应以
|
||||
全新上下文开始时，请设置 `sessionScope: "per-call"`，例如前台接待、
|
||||
预订、IVR，或同一电话号码可能代表不同会议的 Google Meet 桥接流程。
|
||||
默认情况下，Voice Call 使用 `sessionScope: "per-phone"`，因此来自同一来电者的重复通话会保留对话记忆。当每次运营商通话都应以全新上下文开始时，请设置 `sessionScope: "per-call"`，例如接待、预订、IVR，或 Google Meet 桥接流程中同一个电话号码可能代表不同会议的场景。
|
||||
|
||||
## 实时语音对话
|
||||
|
||||
`realtime` 会为实时通话音频选择一个全双工实时语音提供商。
|
||||
它与 `streaming` 分离，后者只会将音频转发给
|
||||
实时转写提供商。
|
||||
`realtime` 会为实时通话音频选择一个全双工实时语音提供商。它与 `streaming` 分离，后者只会将音频转发给实时转写提供商。
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话请选择一种
|
||||
音频模式。
|
||||
`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话选择一种音频模式。
|
||||
</Warning>
|
||||
|
||||
当前运行时行为：
|
||||
|
||||
- `realtime.enabled` 支持 Twilio Media Streams。
|
||||
- `realtime.provider` 是可选的。如果未设置，Voice Call 会使用第一个注册的实时语音提供商。
|
||||
- Twilio Media Streams 支持 `realtime.enabled`。
|
||||
- `realtime.provider` 是可选项。如果未设置，Voice Call 会使用第一个已注册的实时语音提供商。
|
||||
- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由各自的提供商插件注册。
|
||||
- 提供商拥有的原始配置位于 `realtime.providers.<providerId>` 下。
|
||||
- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。当来电者请求更深入推理、当前信息或普通 OpenClaw 工具时，实时模型可以调用它。
|
||||
- `realtime.fastContext.enabled` 默认关闭。启用后，Voice Call 会先为 consult 问题搜索已索引的记忆/会话上下文，并在 `realtime.fastContext.timeoutMs` 内将这些片段返回给实时模型；只有当 `realtime.fastContext.fallbackToConsult` 为 true 时，才会回退到完整 consult 智能体。
|
||||
- 如果 `realtime.provider` 指向未注册提供商，或完全没有注册实时语音提供商，Voice Call 会记录警告并跳过实时媒体，而不是让整个插件失败。
|
||||
- consult 会话键会在可用时复用已存储的通话会话，然后回退到配置的 `sessionScope`（默认为 `per-phone`，或用于隔离通话的 `per-call`）。
|
||||
- 提供商自有的原始配置位于 `realtime.providers.<providerId>` 下。
|
||||
- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。当来电者请求更深入的推理、当前信息，或普通 OpenClaw 工具时，实时模型可以调用它。
|
||||
- `realtime.fastContext.enabled` 默认关闭。启用后，Voice Call 会先为咨询问题搜索已索引的记忆/会话上下文，并在 `realtime.fastContext.timeoutMs` 内把这些片段返回给实时模型；只有当 `realtime.fastContext.fallbackToConsult` 为 true 时，才会回退到完整咨询 agent。
|
||||
- 如果 `realtime.provider` 指向未注册的提供商，或完全没有注册实时语音提供商，Voice Call 会记录警告并跳过实时媒体，而不是让整个插件失败。
|
||||
- 咨询会话键会在可用时复用已存储的通话会话，然后回退到已配置的 `sessionScope`（默认 `per-phone`，隔离通话则为 `per-call`）。
|
||||
|
||||
### 工具策略
|
||||
|
||||
`realtime.toolPolicy` 控制 consult 运行：
|
||||
`realtime.toolPolicy` 控制咨询运行：
|
||||
|
||||
| 策略 | 行为 |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | 暴露 consult 工具，并将常规智能体限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 |
|
||||
| `owner` | 暴露 consult 工具，并让常规智能体使用普通智能体工具策略。 |
|
||||
| `none` | 不暴露 consult 工具。自定义 `realtime.tools` 仍会传递给实时提供商。 |
|
||||
| `safe-read-only` | 暴露咨询工具，并将常规 agent 限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 |
|
||||
| `owner` | 暴露咨询工具，并允许常规 agent 使用普通 agent 工具策略。 |
|
||||
| `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`；voice 为 `Kore`。`sessionResumption` 和 `contextWindowCompression` 默认开启，用于更长且可重连的通话。使用 `silenceDurationMs`、`startSensitivity` 和 `endSensitivity` 来调优电话音频上的更快轮次切换。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -275,6 +244,8 @@ Voice Call 凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.a
|
||||
apiKey: "${GEMINI_API_KEY}",
|
||||
model: "gemini-2.5-flash-native-audio-preview-12-2025",
|
||||
voice: "Kore",
|
||||
silenceDurationMs: 500,
|
||||
startSensitivity: "high",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -309,20 +280,21 @@ Voice Call 凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.a
|
||||
</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 会记录警告并跳过媒体流式传输，而不是让整个插件失败。
|
||||
|
||||
### 流式传输提供商示例
|
||||
|
||||
@ -392,9 +364,10 @@ Voice Call 凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.a
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 通话的 TTS
|
||||
## 通话 TTS
|
||||
|
||||
Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输出。你可以在插件配置下用**相同结构**覆盖它，它会与 `messages.tts` 深度合并。
|
||||
Voice Call 使用核心 `messages.tts` 配置为通话提供流式
|
||||
语音。你可以在插件配置下用**相同结构**覆盖它，它会与 `messages.tts` 深度合并。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -411,22 +384,22 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech 会被语音通话忽略。** 电话音频需要 PCM；
|
||||
当前 Microsoft 传输协议未公开电话 PCM 输出。
|
||||
**Microsoft 语音会被语音通话忽略。** 电话音频需要 PCM；
|
||||
当前 Microsoft 传输不公开电话 PCM 输出。
|
||||
</Warning>
|
||||
|
||||
行为说明：
|
||||
|
||||
- 插件配置中的旧版 `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="仅核心 TTS">
|
||||
<Tab title="Core TTS only">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -440,7 +413,7 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="覆盖到 ElevenLabs（仅通话）">
|
||||
<Tab title="Override to ElevenLabs (calls only)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -464,7 +437,7 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="OpenAI 模型覆盖（深度合并）">
|
||||
<Tab title="OpenAI model override (deep-merge)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -490,7 +463,7 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输
|
||||
|
||||
## 入站通话
|
||||
|
||||
入站策略默认是 `disabled`。要启用入站通话，请设置：
|
||||
入站策略默认值为 `disabled`。要启用入站通话，请设置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -501,17 +474,29 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` 是低保障的来电号码筛选。该插件会规范化提供商提供的 `From` 值并将其与 `allowFrom` 比较。Webhook 验证会认证提供商投递和载荷完整性，但它**不能**证明 PSTN/VoIP 来电号码所有权。请将 `allowFrom` 视为来电号码过滤，而不是强来电身份认证。
|
||||
`inboundPolicy: "allowlist"` 是一种低保证的主叫号码筛选。
|
||||
插件会规范化提供商提供的 `From` 值，并将其与
|
||||
`allowFrom` 比较。Webhook 验证会认证提供商投递和
|
||||
负载完整性，但它**不能**证明 PSTN/VoIP 主叫号码
|
||||
所有权。请将 `allowFrom` 视为主叫号码过滤，而不是强主叫方
|
||||
身份验证。
|
||||
</Warning>
|
||||
|
||||
自动响应使用智能体系统。通过 `responseModel`、`responseSystemPrompt` 和 `responseTimeoutMs` 调整。
|
||||
自动响应使用智能体系统。可通过 `responseModel`、
|
||||
`responseSystemPrompt` 和 `responseTimeoutMs` 调整。
|
||||
|
||||
### 按号码路由
|
||||
|
||||
当一个 Voice Call 插件接收多个电话号码的通话，并且每个号码都应像不同线路一样运作时，使用 `numbers`。例如，一个号码可以使用轻松的个人助理，而另一个号码使用商务人格、不同的响应智能体以及不同的 TTS 语音。
|
||||
当一个 Voice Call 插件接收多个电话号码的来电，并且每个号码应像不同线路一样运行时，请使用 `numbers`。例如，一个
|
||||
号码可以使用轻松随性的个人助理，而另一个号码使用商务
|
||||
人设、不同的响应智能体和不同的 TTS 语音。
|
||||
|
||||
路由会根据提供商提供的被拨 `To` 号码选择。键必须是 E.164 号码。通话到达时，Voice Call 会解析一次匹配路由，将匹配路由存储在通话记录上，并在问候、经典自动响应路径、实时咨询路径和 TTS 播放中复用该有效配置。如果没有路由匹配，则使用全局 Voice Call 配置。
|
||||
出站通话不使用 `numbers`；发起通话时请显式传入出站目标、消息和会话。
|
||||
路由从提供商提供的被叫 `To` 号码中选择。键必须是
|
||||
E.164 号码。来电到达时，Voice Call 会解析一次匹配路由，
|
||||
将匹配到的路由存储在通话记录上，并在问候语、经典自动响应路径、实时咨询路径和 TTS
|
||||
播放中复用该有效配置。如果没有路由匹配，则使用全局 Voice Call 配置。
|
||||
出站通话不使用 `numbers`；发起通话时请显式传入出站目标、消息和
|
||||
会话。
|
||||
|
||||
路由覆盖目前支持：
|
||||
|
||||
@ -522,7 +507,8 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输
|
||||
- `responseSystemPrompt`
|
||||
- `responseTimeoutMs`
|
||||
|
||||
`tts` 路由值会深度合并到全局 Voice Call `tts` 配置之上，所以通常只需覆盖提供商语音：
|
||||
`tts` 路由值会深度合并到全局 Voice Call `tts` 配置之上，因此
|
||||
你通常只需覆盖提供商语音：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -550,45 +536,50 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输
|
||||
|
||||
### 语音输出契约
|
||||
|
||||
对于自动响应，Voice Call 会向系统提示词追加严格的语音输出契约：
|
||||
对于自动响应，Voice Call 会向系统提示追加严格的语音输出契约：
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
```
|
||||
|
||||
Voice Call 会以防御性方式提取语音文本：
|
||||
Voice Call 会防御性地提取语音文本：
|
||||
|
||||
- 忽略标记为推理/错误内容的载荷。
|
||||
- 解析直接 JSON、围栏 JSON，或内联 `"spoken"` 键。
|
||||
- 忽略标记为推理/错误内容的负载。
|
||||
- 解析直接 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
|
||||
{
|
||||
@ -607,24 +598,26 @@ Voice Call 会以防御性方式提取语音文本：
|
||||
|
||||
## Webhook 安全
|
||||
|
||||
当代理或隧道位于 Gateway 网关前方时，该插件会重建用于签名验证的公开 URL。这些选项控制哪些转发标头受信任：
|
||||
当代理或隧道位于 Gateway 网关 前方时，插件
|
||||
会重建用于签名验证的公开 URL。这些选项
|
||||
控制信任哪些转发头：
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
允许来自转发标头的主机名单。
|
||||
来自转发头的主机 allowlist。
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
在没有允许名单的情况下信任转发标头。
|
||||
在没有 allowlist 的情况下信任转发头。
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
仅当请求远程 IP 与列表匹配时才信任转发标头。
|
||||
仅当请求远程 IP 与列表匹配时才信任转发头。
|
||||
</ParamField>
|
||||
|
||||
其他防护：
|
||||
其他保护：
|
||||
|
||||
- Twilio 和 Plivo 已启用 webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。
|
||||
- Twilio 对话轮次在 `<Gather>` 回调中包含按轮次生成的令牌，因此过期/重放的语音回调无法满足较新的待处理转写轮次。
|
||||
- 当缺少提供商所需的签名标头时，未经认证的 webhook 请求会在读取正文之前被拒绝。
|
||||
- voice-call webhook 使用共享的预认证正文配置（64 KB / 5 秒），并在签名验证前加上按 IP 限制的进行中请求上限。
|
||||
- 已为 Twilio 和 Plivo 启用 Webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。
|
||||
- Twilio 会话轮次在 `<Gather>` 回调中包含每轮 token，因此过期/重放的语音回调无法满足更新的待处理转录轮次。
|
||||
- 当缺少提供商所需的签名头时，未经认证的 webhook 请求会在读取正文前被拒绝。
|
||||
- voice-call webhook 使用共享的预认证正文配置文件（64 KB / 5 秒），并在签名验证前加上按 IP 统计的进行中请求上限。
|
||||
|
||||
使用稳定公开主机的示例：
|
||||
|
||||
@ -660,10 +653,9 @@ 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 网关拥有的语音通话运行时，因此 CLI 不会绑定第二个 webhook 服务器。如果没有可达的 Gateway 网关，这些命令会回退到独立 CLI 运行时。
|
||||
|
||||
`latency` 从默认语音通话存储路径读取 `calls.jsonl`。
|
||||
使用 `--file <path>` 指向不同的日志，并使用 `--last <n>` 将分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。
|
||||
`latency` 会从默认语音通话存储路径读取 `calls.jsonl`。使用 `--file <path>` 指向不同日志，使用 `--last <n>` 将分析限制为最后 N 条记录（默认 200）。输出包含回合延迟和 listen-wait 时间的 p50/p90/p99。
|
||||
|
||||
## 智能体工具
|
||||
|
||||
@ -678,7 +670,7 @@ openclaw voicecall expose --mode funnel
|
||||
| `end_call` | `callId` |
|
||||
| `get_status` | `callId` |
|
||||
|
||||
此仓库在 `skills/voice-call/SKILL.md` 中附带匹配的技能文档。
|
||||
此仓库随附匹配的 skill 文档：`skills/voice-call/SKILL.md`。
|
||||
|
||||
## Gateway 网关 RPC
|
||||
|
||||
@ -691,11 +683,11 @@ openclaw voicecall expose --mode funnel
|
||||
| `voicecall.end` | `callId` |
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
`dtmfSequence` 仅在 `mode: "conversation"` 下有效。通知模式通话如果需要接通后按键，应在通话存在后使用 `voicecall.dtmf`。
|
||||
`dtmfSequence` 仅在 `mode: "conversation"` 下有效。notify-mode 通话如果需要接通后的按键数字，应在通话存在后使用 `voicecall.dtmf`。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 设置时 webhook 暴露失败
|
||||
### 设置失败：webhook 暴露
|
||||
|
||||
从运行 Gateway 网关的同一环境运行设置：
|
||||
|
||||
@ -704,9 +696,9 @@ 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`。
|
||||
|
||||
Twilio 通知模式外呼会在创建通话请求中直接发送其初始 `<Say>` TwiML，因此第一条语音消息不依赖 Twilio 获取 webhook TwiML。状态回调、对话通话、接通前 DTMF、实时流和接通后通话控制仍然需要公开 webhook。
|
||||
Twilio notify-mode 外呼会在创建通话请求中直接发送初始 `<Say>` TwiML，因此第一条语音消息不依赖 Twilio 获取 webhook TwiML。状态回调、会话通话、接通前 DTMF、实时流和接通后通话控制仍需要公开 webhook。
|
||||
|
||||
使用一种公开暴露路径：
|
||||
|
||||
@ -735,21 +727,21 @@ openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
除非你传入 `--yes`，否则 `voicecall smoke` 是一次空运行。
|
||||
除非传入 `--yes`，否则 `voicecall smoke` 是一次试运行。
|
||||
|
||||
### 提供商凭证失败
|
||||
### 提供商凭据失败
|
||||
|
||||
检查所选提供商和必需的凭证字段：
|
||||
检查选定的提供商和必需的凭据字段：
|
||||
|
||||
- Twilio：`twilio.accountSid`、`twilio.authToken` 和 `fromNumber`，或 `TWILIO_ACCOUNT_SID`、`TWILIO_AUTH_TOKEN` 和 `TWILIO_FROM_NUMBER`。
|
||||
- Telnyx：`telnyx.apiKey`、`telnyx.connectionId`、`telnyx.publicKey` 和 `fromNumber`。
|
||||
- Plivo：`plivo.authId`、`plivo.authToken` 和 `fromNumber`。
|
||||
|
||||
凭证必须存在于 Gateway 网关主机上。编辑本地 shell 配置文件不会影响已运行的 Gateway 网关，直到它重启或重新加载其环境。
|
||||
凭据必须存在于 Gateway 网关主机上。编辑本地 shell 配置文件不会影响已经运行的 Gateway 网关，直到它重启或重新加载其环境。
|
||||
|
||||
### 通话已开始但提供商 webhook 未到达
|
||||
### 通话启动但提供商 webhook 未到达
|
||||
|
||||
确认提供商控制台指向准确的公开 webhook URL：
|
||||
确认提供商控制台指向确切的公开 webhook URL：
|
||||
|
||||
```text
|
||||
https://voice.example.com/voice/webhook
|
||||
@ -765,22 +757,22 @@ openclaw logs --follow
|
||||
|
||||
常见原因：
|
||||
|
||||
- `publicUrl` 指向与 `serve.path` 不同的路径。
|
||||
- 隧道 URL 在 Gateway 网关启动后发生了变化。
|
||||
- 代理转发请求，但剥离或重写了 host/proto 标头。
|
||||
- `publicUrl` 指向的路径与 `serve.path` 不同。
|
||||
- Gateway 网关启动后，隧道 URL 已更改。
|
||||
- 代理转发了请求，但剥离或重写了 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`。
|
||||
- 对于 ngrok 免费层 URL，在隧道主机名更改时更新 `publicUrl`。
|
||||
- 确保代理保留原始 host 和 proto 标头，或配置 `webhookSecurity.allowedHosts`。
|
||||
- 不要在本地测试之外启用 `skipSignatureVerification`。
|
||||
- 不要在本地测试以外启用 `skipSignatureVerification`。
|
||||
|
||||
### Google Meet Twilio 加入失败
|
||||
|
||||
@ -797,33 +789,33 @@ openclaw voicecall smoke --to "+15555550123"
|
||||
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，然后打开实时媒体流，以便在电话参与者加入会议后生成保存的介绍语。
|
||||
|
||||
使用 `openclaw logs --follow` 查看实时阶段追踪。健康的 Twilio Meet 加入会按此顺序记录日志：
|
||||
使用 `openclaw logs --follow` 查看实时阶段跟踪。健康的 Twilio Meet 加入会按以下顺序记录日志：
|
||||
|
||||
- Google Meet 将 Twilio 加入委托给 Voice Call。
|
||||
- Voice Call 存储接通前 DTMF TwiML。
|
||||
- Twilio 初始 TwiML 会在实时处理前被消费并提供。
|
||||
- Twilio 初始 TwiML 在实时处理前被消费并提供。
|
||||
- Voice Call 为 Twilio 通话提供实时 TwiML。
|
||||
- 实时桥接启动，并将初始问候语加入队列。
|
||||
|
||||
`openclaw voicecall tail` 仍会显示持久化通话记录；它对通话状态和转录很有用，但并非每个 webhook/实时转换都会出现在其中。
|
||||
`openclaw voicecall tail` 仍会显示持久化的通话记录；它对通话状态和转录很有用，但并非每个 webhook/实时转换都会出现在其中。
|
||||
|
||||
### 实时通话没有语音
|
||||
|
||||
确认只启用了一种音频模式。`realtime.enabled` 和 `streaming.enabled` 不能同时为 true。
|
||||
|
||||
对于实时 Twilio 通话，还要验证：
|
||||
对于实时 Twilio 通话，还需验证：
|
||||
|
||||
- 已加载并注册实时提供商插件。
|
||||
- `realtime.provider` 未设置，或命名了已注册的提供商。
|
||||
- 提供商 API key 对 Gateway 网关进程可用。
|
||||
- 提供商 API key 可供 Gateway 网关进程使用。
|
||||
- `openclaw logs --follow` 显示已提供实时 TwiML、实时桥接已启动，并且初始问候语已加入队列。
|
||||
|
||||
## 相关
|
||||
|
||||
- [Talk 模式](/zh-CN/nodes/talk)
|
||||
- [通话模式](/zh-CN/nodes/talk)
|
||||
- [文本转语音](/zh-CN/tools/tts)
|
||||
- [语音唤醒](/zh-CN/nodes/voicewake)
|
||||
|
||||
@ -1,34 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想将 Google Gemini 模型与 OpenClaw 搭配使用
|
||||
- 你想在 OpenClaw 中使用 Google Gemini 模型
|
||||
- 你需要 API 密钥或 OAuth 认证流程
|
||||
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索）
|
||||
title: Google（Gemini）
|
||||
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、文本转语音、Web 搜索）
|
||||
title: Google (Gemini)
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T04:47:34Z"
|
||||
generated_at: "2026-05-04T04:47:15Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7
|
||||
source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908
|
||||
source_path: providers/google.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并通过
|
||||
Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、文本转语音和 Web 搜索。
|
||||
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支持
|
||||
图像生成、媒体理解（图像/音频/视频）、文本转语音，以及通过
|
||||
Gemini Grounding 进行 Web 搜索。
|
||||
|
||||
- 提供商：`google`
|
||||
- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
|
||||
- API：Google Gemini API
|
||||
- 运行时选项：`agents.defaults.agentRuntime.id: "google-gemini-cli"`
|
||||
会复用 Gemini CLI OAuth，同时将模型引用保持为规范的 `google/*`。
|
||||
复用 Gemini CLI OAuth，同时保持模型引用规范为 `google/*`。
|
||||
|
||||
## 入门指南
|
||||
|
||||
选择你偏好的认证方式并按照设置步骤操作。
|
||||
选择你偏好的认证方式，并按照设置步骤操作。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key">
|
||||
**最适合：**通过 Google AI Studio 进行标准 Gemini API 访问。
|
||||
**最适合：** 通过 Google AI Studio 进行标准 Gemini API 访问。
|
||||
|
||||
<Steps>
|
||||
<Step title="Run onboarding">
|
||||
@ -36,7 +37,7 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、
|
||||
openclaw onboard --auth-choice gemini-api-key
|
||||
```
|
||||
|
||||
或直接传入密钥：
|
||||
或者直接传入密钥：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -64,21 +65,21 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可以使用。使用你已经配置好的那个即可。
|
||||
环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可接受。使用你已经配置好的那个即可。
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Gemini CLI (OAuth)">
|
||||
**最适合：**通过 PKCE OAuth 复用现有 Gemini CLI 登录，而不是使用单独的 API key。
|
||||
**最适合：** 通过 PKCE OAuth 复用现有 Gemini CLI 登录，而不是使用单独的 API key。
|
||||
|
||||
<Warning>
|
||||
`google-gemini-cli` 提供商是非官方集成。一些用户报告以这种方式使用 OAuth 时遇到账户限制。请自行承担风险。
|
||||
`google-gemini-cli` 提供商是非官方集成。一些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
<Step title="Install the Gemini CLI">
|
||||
本地 `gemini` 命令必须在 `PATH` 上可用。
|
||||
本地 `gemini` 命令必须可在 `PATH` 上使用。
|
||||
|
||||
```bash
|
||||
# Homebrew
|
||||
@ -106,7 +107,7 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、
|
||||
- 运行时：`google-gemini-cli`
|
||||
- 别名：`gemini-cli`
|
||||
|
||||
Gemini 3.1 Pro 的 Gemini API 模型 ID 是 `gemini-3.1-pro-preview`。OpenClaw 接受更短的 `google/gemini-3.1-pro` 作为便捷别名，并会在调用提供商之前将其规范化。
|
||||
Gemini 3.1 Pro 的 Gemini API 模型 ID 是 `gemini-3.1-pro-preview`。OpenClaw 接受更短的 `google/gemini-3.1-pro` 作为便捷别名，并会在调用提供商前将其规范化。
|
||||
|
||||
**环境变量：**
|
||||
|
||||
@ -121,11 +122,12 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
如果浏览器流程开始前登录失败，请确保本地 `gemini`
|
||||
命令已安装并位于 `PATH` 上。
|
||||
如果登录在浏览器流程开始前失败，请确保本地 `gemini`
|
||||
命令已安装并且在 `PATH` 上。
|
||||
</Note>
|
||||
|
||||
`google-gemini-cli/*` 模型引用是旧版兼容别名。新的配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli`
|
||||
`google-gemini-cli/*` 模型引用是旧版兼容别名。新的
|
||||
配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli`
|
||||
运行时。
|
||||
|
||||
</Tab>
|
||||
@ -151,7 +153,7 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、
|
||||
|
||||
内置的 `gemini` Web 搜索提供商使用 Gemini Google Search grounding。
|
||||
在 `plugins.entries.google.config.webSearch` 下配置专用搜索密钥，
|
||||
或者让它在 `GEMINI_API_KEY` 之后复用 `models.providers.google.apiKey`：
|
||||
或让它在 `GEMINI_API_KEY` 之后复用 `models.providers.google.apiKey`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -171,24 +173,24 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、
|
||||
}
|
||||
```
|
||||
|
||||
凭据优先级依次为专用 `webSearch.apiKey`、`GEMINI_API_KEY`，
|
||||
然后是 `models.providers.google.apiKey`。`webSearch.baseUrl` 是可选的，
|
||||
用于运营方代理或兼容的 Gemini API 端点；省略时，Gemini Web 搜索会复用 `models.providers.google.baseUrl`。参见
|
||||
[Gemini 搜索](/zh-CN/tools/gemini-search)，了解提供商特定的工具行为。
|
||||
凭据优先级依次为专用的 `webSearch.apiKey`、`GEMINI_API_KEY`，
|
||||
然后是 `models.providers.google.apiKey`。`webSearch.baseUrl` 是可选项，
|
||||
用于操作方代理或兼容的 Gemini API 端点；省略时，
|
||||
Gemini Web 搜索会复用 `models.providers.google.baseUrl`。请参阅
|
||||
[Gemini 搜索](/zh-CN/tools/gemini-search) 了解提供商特定的工具行为。
|
||||
|
||||
<Tip>
|
||||
Gemini 3 模型使用 `thinkingLevel` 而不是 `thinkingBudget`。OpenClaw 会将
|
||||
Gemini 3 模型使用 `thinkingLevel`，而不是 `thinkingBudget`。OpenClaw 会将
|
||||
Gemini 3、Gemini 3.1 和 `gemini-*-latest` 别名的推理控制映射到
|
||||
`thinkingLevel`，这样默认/低延迟运行就不会发送已禁用的
|
||||
`thinkingBudget` 值。
|
||||
|
||||
`/think adaptive` 会保留 Google 的动态思考语义，而不是选择固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 会省略固定的 `thinkingLevel`，以便
|
||||
Google 可以选择级别；Gemini 2.5 会发送 Google 的动态哨兵值
|
||||
`/think adaptive` 会保留 Google 的动态思考语义，而不是选择固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 会省略固定的 `thinkingLevel`，让 Google 选择级别；Gemini 2.5 会发送 Google 的动态哨兵值
|
||||
`thinkingBudget: -1`。
|
||||
|
||||
Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
会将 `thinkingBudget` 重写为 Gemma 4 支持的 Google `thinkingLevel`。
|
||||
将思考设置为 `off` 会保持思考禁用，而不是映射到
|
||||
会为 Gemma 4 将 `thinkingBudget` 改写为受支持的 Google `thinkingLevel`。
|
||||
将思考设置为 `off` 会保留禁用思考状态，而不是映射到
|
||||
`MINIMAL`。
|
||||
</Tip>
|
||||
|
||||
@ -217,16 +219,16 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
```
|
||||
|
||||
<Note>
|
||||
参见[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
请参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
</Note>
|
||||
|
||||
## 视频生成
|
||||
|
||||
内置的 `google` 插件还通过共享的
|
||||
内置的 `google` 插件还会通过共享的
|
||||
`video_generate` 工具注册视频生成。
|
||||
|
||||
- 默认视频模型：`google/veo-3.1-fast-generate-preview`
|
||||
- 模式：文本转视频、图像转视频，以及单视频引用流程
|
||||
- 模式：文本转视频、图像转视频和单视频引用流程
|
||||
- 支持 `aspectRatio`、`resolution` 和 `audio`
|
||||
- 当前时长限制：**4 到 8 秒**
|
||||
|
||||
@ -245,19 +247,19 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
```
|
||||
|
||||
<Note>
|
||||
参见[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
请参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
</Note>
|
||||
|
||||
## 音乐生成
|
||||
|
||||
内置的 `google` 插件还通过共享的
|
||||
内置的 `google` 插件还会通过共享的
|
||||
`music_generate` 工具注册音乐生成。
|
||||
|
||||
- 默认音乐模型：`google/lyria-3-clip-preview`
|
||||
- 还支持 `google/lyria-3-pro-preview`
|
||||
- 提示词控制：`lyrics` 和 `instrumental`
|
||||
- 输出格式：默认是 `mp3`，在 `google/lyria-3-pro-preview` 上还支持 `wav`
|
||||
- 引用输入：最多 10 张图像
|
||||
- 输出格式：默认 `mp3`，在 `google/lyria-3-pro-preview` 上还支持 `wav`
|
||||
- 参考输入：最多 10 张图像
|
||||
- 由会话支持的运行会通过共享任务/Status 流程分离，包括 `action: "status"`
|
||||
|
||||
要将 Google 用作默认音乐提供商：
|
||||
@ -275,15 +277,15 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
```
|
||||
|
||||
<Note>
|
||||
参见[音乐生成](/zh-CN/tools/music-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
请参阅[音乐生成](/zh-CN/tools/music-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
</Note>
|
||||
|
||||
## 文本转语音
|
||||
|
||||
内置的 `google` 语音提供商使用 Gemini API TTS 路径，并使用
|
||||
内置的 `google` 语音提供商使用 Gemini API TTS 路径，并搭配
|
||||
`gemini-3.1-flash-tts-preview`。
|
||||
|
||||
- 默认语音：`Kore`
|
||||
- 默认声音：`Kore`
|
||||
- 认证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
|
||||
- 输出：常规 TTS 附件使用 WAV，语音备注目标使用 Opus，Talk/电话使用 PCM
|
||||
- 语音备注输出：Google PCM 会封装为 WAV，并通过 `ffmpeg` 转码为 48 kHz Opus
|
||||
@ -309,12 +311,13 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
```
|
||||
|
||||
Gemini API TTS 使用自然语言提示词进行风格控制。设置
|
||||
`audioProfile` 可在朗读文本前添加可复用的风格提示词。当你的提示词文本引用命名说话人时，请设置
|
||||
`audioProfile` 可在朗读文本前附加可复用的风格提示词。当你的提示词文本引用具名说话人时，设置
|
||||
`speakerName`。
|
||||
|
||||
Gemini API TTS 还接受文本中的表现性方括号音频标签，
|
||||
例如 `[whispers]` 或 `[laughs]`。要在将标签发送到 TTS 的同时让它们不出现在可见的聊天回复中，请把它们放入 `[[tts:text]]...[[/tts:text]]`
|
||||
块中：
|
||||
例如 `[whispers]` 或 `[laughs]`。要在将标签发送到 TTS 的同时让它们不出现在可见聊天回复中，
|
||||
请将它们放入 `[[tts:text]]...[[/tts:text]]`
|
||||
块内：
|
||||
|
||||
```text
|
||||
Here is the clean reply text.
|
||||
@ -323,12 +326,13 @@ Here is the clean reply text.
|
||||
```
|
||||
|
||||
<Note>
|
||||
限制为 Gemini API 的 Google Cloud Console API key 可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。
|
||||
限制为 Gemini API 的 Google Cloud Console API key 对此
|
||||
提供商有效。这不是单独的 Cloud Text-to-Speech API 路径。
|
||||
</Note>
|
||||
|
||||
## 实时语音
|
||||
|
||||
内置的 `google` 插件注册了一个由
|
||||
内置的 `google` 插件会注册一个由
|
||||
Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
@ -339,12 +343,14 @@ Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Me
|
||||
| VAD 开始灵敏度 | `...google.startSensitivity` | （未设置） |
|
||||
| VAD 结束灵敏度 | `...google.endSensitivity` | （未设置） |
|
||||
| 静音时长 | `...google.silenceDurationMs` | （未设置） |
|
||||
| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` |
|
||||
| 轮次覆盖范围 | `...google.turnCoverage` | Google 默认值，`only-activity` |
|
||||
| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` |
|
||||
| 轮次覆盖范围 | `...google.turnCoverage` | Google 默认值，`only-activity` |
|
||||
| 禁用自动 VAD | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| API 密钥 | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
|
||||
| 会话恢复 | `...google.sessionResumption` | `true` |
|
||||
| 上下文压缩 | `...google.contextWindowCompression` | `true` |
|
||||
| API key | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
|
||||
|
||||
语音通话实时配置示例：
|
||||
Voice Call 实时配置示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -375,35 +381,36 @@ Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Me
|
||||
<Note>
|
||||
Google Live API 通过 WebSocket 使用双向音频和函数调用。
|
||||
OpenClaw 会将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并
|
||||
在共享实时语音契约上保留工具调用。除非你需要更改采样，否则请让 `temperature`
|
||||
保持未设置；OpenClaw 会省略非正值，因为 Google Live 对 `temperature: 0`
|
||||
可能返回没有音频的转录。
|
||||
Gemini API 转录在没有 `languageCodes` 的情况下启用；当前 Google
|
||||
在共享实时语音契约上保留工具调用。除非需要更改采样，否则让 `temperature`
|
||||
保持未设置；OpenClaw 会省略非正值，因为 Google Live 在 `temperature: 0` 时
|
||||
可能返回没有音频的转录文本。
|
||||
Gemini API 转录在不设置 `languageCodes` 的情况下启用；当前 Google
|
||||
SDK 会拒绝此 API 路径上的语言代码提示。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk 支持使用受限一次性令牌的 Google Live 浏览器会话。
|
||||
仅后端实时语音提供商也可以通过通用 Gateway 网关中继传输运行，
|
||||
这会将提供商凭证保留在 Gateway 网关上。
|
||||
仅后端的实时语音提供商也可以通过通用 Gateway 网关中继传输运行，
|
||||
这样提供商凭据会保留在 Gateway 网关上。
|
||||
</Note>
|
||||
|
||||
对于维护者实时验证，请运行
|
||||
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`。
|
||||
Google 这一路径会生成与 Control UI Talk 使用的同一种受限 Live API 令牌形态，
|
||||
打开浏览器 WebSocket 端点，发送初始设置载荷，并等待 `setupComplete`。
|
||||
Google 段会铸造与 Control UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket 端点，发送初始设置负载，
|
||||
并等待 `setupComplete`。
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="直接复用 Gemini 缓存">
|
||||
对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw
|
||||
会将配置的 `cachedContent` 句柄传递给 Gemini 请求。
|
||||
会将已配置的 `cachedContent` 句柄传递给 Gemini 请求。
|
||||
|
||||
- 使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数
|
||||
- 使用 `cachedContent` 或旧版 `cached_content`
|
||||
配置每个模型或全局参数
|
||||
- 如果两者都存在，`cachedContent` 优先
|
||||
- 示例值：`cachedContents/prebuilt-context`
|
||||
- Gemini 缓存命中用量会从上游 `cachedContentTokenCount` 归一化为 OpenClaw `cacheRead`
|
||||
- Gemini 缓存命中用量会从上游 `cachedContentTokenCount` 标准化为 OpenClaw `cacheRead`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -424,20 +431,20 @@ Google 这一路径会生成与 Control UI Talk 使用的同一种受限 Live AP
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gemini CLI JSON 用量说明">
|
||||
使用 `google-gemini-cli` OAuth 提供商时，OpenClaw 会按如下方式归一化
|
||||
使用 `google-gemini-cli` OAuth 提供商时，OpenClaw 会按如下方式标准化
|
||||
CLI JSON 输出：
|
||||
|
||||
- 回复文本来自 CLI JSON `response` 字段。
|
||||
- 回复文本来自 CLI JSON 的 `response` 字段。
|
||||
- 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。
|
||||
- `stats.cached` 会归一化为 OpenClaw `cacheRead`。
|
||||
- `stats.cached` 会标准化为 OpenClaw `cacheRead`。
|
||||
- 如果缺少 `stats.input`，OpenClaw 会从
|
||||
`stats.input_tokens - stats.cached` 派生输入 token 数。
|
||||
`stats.input_tokens - stats.cached` 推导输入 token。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="环境和守护进程设置">
|
||||
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `GEMINI_API_KEY`
|
||||
可供该进程使用（例如，在 `~/.openclaw/.env` 中，或通过
|
||||
如果 Gateway 网关作为守护进程（launchd/systemd）运行，请确保 `GEMINI_API_KEY`
|
||||
可用于该进程（例如，在 `~/.openclaw/.env` 中，或通过
|
||||
`env.shellEnv`）。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user