diff --git a/docs/zh-CN/plugins/google-meet.md b/docs/zh-CN/plugins/google-meet.md index 30c10e4de..bbda9ce73 100644 --- a/docs/zh-CN/plugins/google-meet.md +++ b/docs/zh-CN/plugins/google-meet.md @@ -1,36 +1,36 @@ --- read_when: - 你希望一个 OpenClaw 智能体加入 Google Meet 通话 - - 你想让 OpenClaw 智能体创建一个新的 Google Meet 通话 + - 你希望 OpenClaw 智能体创建新的 Google Meet 通话 - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输协议 -summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确指定的 Meet URL，并使用智能体语音回复默认设置 +summary: Google Meet 插件：通过 Chrome 或 Twilio 加入显式 Meet URL，并使用智能体回话默认设置 title: Google Meet 插件 x-i18n: - generated_at: "2026-05-04T03:12:35Z" + generated_at: "2026-05-04T04:47:21Z" model: gpt-5.5 provider: openai - source_hash: a7c35884f9fff49561e884050e1d94099621b1a4acd8a035e82ca8cb0f5a06ff + source_hash: 9caeb2d4540b833c75cd0f3b5f61a99f0a6bb16ca71a96011d25e4ea103a4601 source_path: plugins/google-meet.md workflow: 16 --- -Google Meet 参与者对 OpenClaw 的支持有意设计得很明确： +Google Meet 参与者支持适用于 OpenClaw，插件按设计是显式的： -- 它只会加入明确的 `https://meet.google.com/...` URL。 +- 它只会加入显式的 `https://meet.google.com/...` URL。 - 它可以通过 Google Meet API 创建新的 Meet 空间，然后加入返回的 URL。 -- `agent` 是默认回话模式：实时转录会监听，已配置的 OpenClaw 智能体会回答，常规 OpenClaw TTS 会把语音发送到 Meet。 -- `bidi` 仍可用作后备的直接实时语音模型模式。 -- 智能体通过 `mode` 选择加入行为：使用 `agent` 进行实时监听/回话，使用 `bidi` 作为直接实时语音后备，或使用 `transcribe` 加入/控制浏览器但不启用回话桥接。 -- 身份验证一开始使用个人 Google OAuth 或已登录的 Chrome 配置文件。 -- 不会自动发布同意声明。 -- 默认 Chrome 音频后端是 `BlackHole 2ch`。 +- `agent` 是默认的回话模式：实时转录会监听，已配置的 OpenClaw 智能体会回答，常规 OpenClaw TTS 会在 Meet 中发声。 +- `bidi` 仍可作为备用的直接实时语音模型模式使用。 +- 智能体通过 `mode` 选择加入行为：使用 `agent` 进行实时监听/回话，使用 `bidi` 作为直接实时语音备用模式，或使用 `transcribe` 加入/控制浏览器但不启用回话桥接。 +- 身份验证从个人 Google OAuth 或已登录的 Chrome 配置文件开始。 +- 不会自动播报同意声明。 +- 默认的 Chrome 音频后端是 `BlackHole 2ch`。 - Chrome 可以在本地运行，也可以在已配对的节点主机上运行。 - Twilio 接受拨入号码以及可选的 PIN 或 DTMF 序列；它不能直接拨打 Meet URL。 -- CLI 命令是 `googlemeet`；`meet` 预留给更宽泛的智能体电话会议工作流。 +- CLI 命令是 `googlemeet`；`meet` 保留用于更广泛的智能体电话会议工作流。 ## 快速开始 -安装本地音频依赖，并配置实时转录提供商以及常规 OpenClaw TTS。OpenAI 是默认转录提供商；Google Gemini Live 也可以作为单独的 `bidi` 语音后备使用，配置为 `realtime.voiceProvider: "google"`： +安装本地音频依赖，并配置实时转录提供商和常规 OpenClaw TTS。OpenAI 是默认转录提供商；Google Gemini Live 也可作为单独的 `bidi` 语音备用方案，配合 `realtime.voiceProvider: "google"` 使用： ```bash brew install blackhole-2ch sox @@ -45,7 +45,7 @@ export GEMINI_API_KEY=... sudo reboot ``` -重启后，验证这两个部分： +重启后，验证两个组件： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -73,21 +73,21 @@ command -v sox openclaw googlemeet setup ``` -设置输出旨在供智能体读取，并且感知模式。它会报告 Chrome 配置文件、节点固定情况，以及针对实时 Chrome 加入的 BlackHole/SoX 音频桥接和延迟实时开场检查。对于仅观察加入，请使用 `--mode transcribe` 检查同一传输；该模式会跳过实时音频前置条件，因为它不会通过桥接监听或发声： +设置输出旨在便于智能体读取，并且感知模式。它会报告 Chrome 配置文件、节点固定状态，以及在实时 Chrome 加入场景下报告 BlackHole/SoX 音频桥接和延迟实时开场检查。对于仅观察加入，请使用 `--mode transcribe` 检查同一传输；该模式会跳过实时音频前置条件，因为它不会通过桥接监听或发声： ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -配置 Twilio 委托时，设置还会报告 `voice-call` 插件、Twilio 凭证和公开 webhook 暴露是否已就绪。在让智能体加入之前，应将任何 `ok: false` 检查视为对应传输和模式的阻塞项。脚本或机器可读输出请使用 `openclaw googlemeet setup --json`。在智能体尝试之前，使用 `--transport chrome`、`--transport chrome-node` 或 `--transport twilio` 对特定传输进行预检。 +配置 Twilio 委托后，设置还会报告 `voice-call` 插件、Twilio 凭据和公开 webhook 暴露是否就绪。在请求智能体加入之前，应将任何 `ok: false` 检查视为所检查传输和模式的阻塞项。使用 `openclaw googlemeet setup --json` 获取脚本或机器可读输出。在智能体尝试之前，使用 `--transport chrome`、`--transport chrome-node` 或 `--transport twilio` 对特定传输进行预检。 -对于 Twilio，当默认传输是 Chrome 时，始终显式预检该传输： +对于 Twilio，当默认传输是 Chrome 时，始终显式预检传输： ```bash openclaw googlemeet setup --transport twilio ``` -这样可以在智能体尝试拨入会议之前，发现缺失的 `voice-call` 接线、Twilio 凭证或不可达的 webhook 暴露。 +这会在智能体尝试拨入会议前捕获缺失的 `voice-call` 接线、Twilio 凭据或无法访问的 webhook 暴露。 加入会议： @@ -95,7 +95,7 @@ openclaw googlemeet setup --transport twilio openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -或让智能体通过 `google_meet` 工具加入： +或者让智能体通过 `google_meet` 工具加入： ```json { @@ -106,7 +106,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij } ``` -面向智能体的 `google_meet` 工具在非 macOS 主机上仍可用于制品、日历、设置、转录、Twilio 和 `chrome-node` 流程。本地 Chrome 回话操作会在那里被阻止，因为内置 Chrome 音频路径目前依赖 macOS `BlackHole 2ch`。在 Linux 上，请使用 `mode: "transcribe"`、Twilio 拨入，或使用 macOS `chrome-node` 主机进行 Chrome 回话参与。 +面向智能体的 `google_meet` 工具在非 macOS 主机上仍可用于工件、日历、设置、转录、Twilio 和 `chrome-node` 流程。本地 Chrome 回话操作在这些主机上会被阻止，因为内置的 Chrome 音频路径目前依赖 macOS `BlackHole 2ch`。在 Linux 上，使用 `mode: "transcribe"`、Twilio 拨入，或使用 macOS `chrome-node` 主机参与 Chrome 回话。 创建新会议并加入： @@ -114,17 +114,17 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij openclaw googlemeet create --transport chrome-node --mode agent ``` -对于通过 API 创建的房间，如果希望房间的免敲门策略是显式的，而不是继承自 Google 账号默认值，请使用 Google Meet `SpaceConfig.accessType`： +对于通过 API 创建的房间，当你希望房间的免敲门策略显式设置而不是继承自 Google 账号默认值时，请使用 Google Meet `SpaceConfig.accessType`： ```bash openclaw googlemeet create --access-type OPEN --transport chrome-node --mode agent ``` -`OPEN` 允许任何拥有 Meet URL 的人无需敲门即可加入。`TRUSTED` 允许主办方组织的可信用户、受邀外部用户和拨入用户无需敲门即可加入。`RESTRICTED` 将免敲门进入限制为受邀者。这些设置只适用于官方 Google Meet API 创建路径，因此必须配置 OAuth 凭证。 +`OPEN` 允许任何拥有 Meet URL 的人无需敲门即可加入。`TRUSTED` 允许主持组织的受信任用户、受邀外部用户和拨入用户无需敲门即可加入。`RESTRICTED` 将免敲门进入限制为受邀者。这些设置只适用于官方 Google Meet API 创建路径，因此必须配置 OAuth 凭据。 -如果你在此选项可用之前已验证 Google Meet，请在向 Google OAuth 同意屏幕添加 `meetings.space.settings` scope 后重新运行 `openclaw googlemeet auth login --json`。 +如果你在此选项可用之前已完成 Google Meet 身份验证，请在将 `meetings.space.settings` 作用域添加到你的 Google OAuth 同意屏幕后，重新运行 `openclaw googlemeet auth login --json`。 -只创建 URL 而不加入： +仅创建 URL 而不加入： ```bash openclaw googlemeet create --no-join @@ -132,13 +132,13 @@ openclaw googlemeet create --no-join `googlemeet create` 有两条路径： -- API 创建：在已配置 Google Meet OAuth 凭证时使用。这是最确定性的路径，并且不依赖浏览器 UI 状态。 -- 浏览器后备：在缺少 OAuth 凭证时使用。OpenClaw 会使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。此路径要求节点上的 OpenClaw Chrome 配置文件已经登录 Google。浏览器自动化会处理 Meet 自己的首次运行麦克风提示；该提示不会被视为 Google 登录失败。 - 加入和创建流程也会先尝试复用现有 Meet 标签页，再打开新标签页。匹配时会忽略无害的 URL 查询字符串，例如 `authuser`，因此智能体重试时应聚焦已打开的会议，而不是创建第二个 Chrome 标签页。 +- API 创建：在已配置 Google Meet OAuth 凭据时使用。这是最确定性的路径，不依赖浏览器 UI 状态。 +- 浏览器备用路径：在没有 OAuth 凭据时使用。OpenClaw 使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实会议代码 URL，然后返回该 URL。此路径要求节点上的 OpenClaw Chrome 配置文件已登录 Google。浏览器自动化会处理 Meet 自己的首次运行麦克风提示；该提示不会被视为 Google 登录失败。 + 加入和创建流程还会先尝试复用现有 Meet 标签页，再打开新标签页。匹配会忽略无害的 URL 查询字符串，例如 `authuser`，因此智能体重试时应聚焦已打开的会议，而不是创建第二个 Chrome 标签页。 -命令/工具输出包含 `source` 字段（`api` 或 `browser`），因此智能体可以说明使用了哪条路径。`create` 默认会加入新会议，并返回 `joined: true` 以及加入会话。若只生成 URL，请在 CLI 上使用 `create --no-join`，或向工具传入 `"join": false`。 +命令/工具输出包含 `source` 字段（`api` 或 `browser`），因此智能体可以说明使用了哪条路径。`create` 默认加入新会议，并返回 `joined: true` 以及加入会话。若只生成 URL，请在 CLI 中使用 `create --no-join`，或向工具传递 `"join": false`。 -或者告诉智能体：“创建一个 Google Meet，用智能体回话模式加入，并把链接发给我。”智能体应调用 `google_meet`，设置 `action: "create"`，然后分享返回的 `meetingUri`。 +或者告诉智能体：“创建一个 Google Meet，使用智能体回话模式加入，并把链接发给我。” 智能体应使用 `action: "create"` 调用 `google_meet`，然后分享返回的 `meetingUri`。 ```json { @@ -148,20 +148,20 @@ openclaw googlemeet create --no-join } ``` -对于仅观察/浏览器控制加入，请设置 `"mode": "transcribe"`。这不会启动双工实时语音桥接，不需要 BlackHole 或 SoX，也不会在会议中回话。此模式下的 Chrome 加入还会避免 OpenClaw 的麦克风/摄像头权限授予，并避开 Meet 的 **使用麦克风** 路径。如果 Meet 显示音频选择插页，自动化会尝试无麦克风路径，否则会报告需要手动操作，而不是打开本地麦克风。在转录模式下，托管的 Chrome 传输还会尽力安装 Meet 字幕观察器。`googlemeet status --json` 和 `googlemeet doctor` 会暴露 `captioning`、`captionsEnabledAttempted`、`transcriptLines`、`lastCaptionAt`、`lastCaptionSpeaker`、`lastCaptionText`，以及简短的 `recentTranscript` 尾部，便于操作者判断浏览器是否已加入通话，以及 Meet 字幕是否正在生成文本。 +对于仅观察/浏览器控制加入，请设置 `"mode": "transcribe"`。这不会启动双工实时语音桥接，不需要 BlackHole 或 SoX，也不会在会议中回话。此模式下的 Chrome 加入还会避免 OpenClaw 的麦克风/摄像头权限授予，并避免 Meet **使用麦克风**路径。如果 Meet 显示音频选择插页，自动化会尝试无麦克风路径，否则报告需要手动操作，而不会打开本地麦克风。在转录模式下，托管 Chrome 传输还会安装尽力而为的 Meet 字幕观察器。`googlemeet status --json` 和 `googlemeet doctor` 会显示 `captioning`、`captionsEnabledAttempted`、`transcriptLines`、`lastCaptionAt`、`lastCaptionSpeaker`、`lastCaptionText`，以及简短的 `recentTranscript` 尾部，以便操作员判断浏览器是否已加入通话，以及 Meet 字幕是否正在产生文本。 当你需要是/否探测时，请使用 `openclaw googlemeet test-listen --transport chrome-node`：它会以转录模式加入，等待新的字幕或转录变化，并返回 `listenVerified`、`listenTimedOut`、手动操作字段以及最新字幕健康状态。 -在实时会话期间，`google_meet` 状态包含浏览器和音频桥接健康状态，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最后输入/输出时间戳、字节计数器和桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可行时处理它。登录、主持人准入以及浏览器/操作系统权限提示会作为手动操作报告，并带有原因和消息，供智能体转述。托管的 Chrome 会话只会在浏览器健康状态报告 `inCall: true` 后发出开场白或测试短语；否则状态会报告 `speechReady: false`，并阻止语音尝试，而不是假装智能体已经在会议中发声。 +实时会话期间，`google_meet` Status 包含浏览器和音频桥接健康状态，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数器和桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可行时处理。登录、主持人准入和浏览器/操作系统权限提示会作为手动操作报告，并附带原因和消息，供智能体转述。托管 Chrome 会话只有在浏览器健康状态报告 `inCall: true` 后才会发出开场语或测试短语；否则 Status 会报告 `speechReady: false`，并阻止发声尝试，而不是假装智能体已在会议中发言。 -本地 Chrome 通过已登录的 OpenClaw 浏览器配置文件加入。实时模式要求使用 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。若要获得干净的双工音频，请使用单独的虚拟设备或 Loopback 风格的图；单个 BlackHole 设备足以完成首次冒烟测试，但可能产生回声。 +本地 Chrome 通过已登录的 OpenClaw 浏览器配置文件加入。实时模式需要 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的图；单个 BlackHole 设备足以进行首次冒烟测试，但可能产生回声。 ### 本地 Gateway 网关 + Parallels Chrome -仅为了让 VM 拥有 Chrome，你**不**需要在 macOS VM 内运行完整的 OpenClaw Gateway 网关或配置模型 API key。在本地运行 Gateway 网关和智能体，然后在 VM 中运行节点主机。在 VM 上启用一次内置插件，让节点通告 Chrome 命令： +仅为了让 VM 拥有 Chrome，你**不**需要在 macOS VM 内运行完整的 OpenClaw Gateway 网关或配置模型 API key。在本地运行 Gateway 网关和智能体，然后在 VM 中运行节点主机。在 VM 上启用一次内置插件，以便节点通告 Chrome 命令： 各组件运行位置： -- Gateway 网关主机：OpenClaw Gateway 网关、Agent 工作区、模型/API key、实时提供商，以及 Google Meet 插件配置。 +- Gateway 网关主机：OpenClaw Gateway 网关、Agent 工作区、模型/API key、实时提供商和 Google Meet 插件配置。 - Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及已登录 Google 的 Chrome 配置文件。 - VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT key 或模型提供商设置。 @@ -177,7 +177,7 @@ brew install blackhole-2ch sox sudo reboot ``` -重启后，验证 VM 能看到音频设备和 SoX 命令： +重启后，验证 VM 可以看到音频设备和 SoX 命令： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -196,14 +196,14 @@ openclaw plugins enable google-meet openclaw node run --host --port 18789 --display-name parallels-macos ``` -如果 `` 是 LAN IP 且你没有使用 TLS，除非你为该可信专用网络选择加入，否则节点会拒绝明文 WebSocket： +如果 `` 是 LAN IP 且你未使用 TLS，除非你为该受信任私有网络显式选择加入，否则节点会拒绝明文 WebSocket： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -将节点安装为 LaunchAgent 时使用相同的环境变量： +将节点安装为 LaunchAgent 时使用同一环境变量： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -211,7 +211,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境，而不是 `openclaw.json` 设置。当安装命令中存在它时，`openclaw node install` 会将其存储在 LaunchAgent 环境中。 +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境变量，不是 `openclaw.json` 设置。`openclaw node install` 会在安装命令中存在该变量时，将其存储在 LaunchAgent 环境中。 从 Gateway 网关主机批准节点： @@ -220,7 +220,7 @@ openclaw devices list openclaw devices approve ``` -确认 Gateway 网关能看到该节点，并且该节点通告了 `googlemeet.chrome` 以及浏览器能力/`browser.proxy`： +确认 Gateway 网关可以看到节点，并且节点通告了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`： ```bash openclaw nodes status @@ -262,62 +262,97 @@ openclaw nodes status openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -或要求智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。 +或要求智能体使用带有 `transport: "chrome-node"` 的 `google_meet` 工具。 -对于单命令冒烟测试，它会创建或复用会话、说出已知短语，并打印会话健康状态： +对于一条命令完成的冒烟测试，它会创建或复用会话、说出已知短语，并打印会话健康状态： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -在实时加入期间，OpenClaw 浏览器自动化会填写访客姓名，点击 Join/Ask to join，并在 Meet 首次运行的 “Use microphone” 选项出现时接受它。在仅观察加入或仅浏览器创建会议期间，如果同一提示提供不使用麦克风的选项，它会继续跳过该提示且不启用麦克风。如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限才能实时加入，或者 Meet 卡在自动化无法处理的提示上，加入/test-speech 结果会报告 `manualActionRequired: true`，并带有 `manualActionReason` 和 `manualActionMessage`。智能体应停止重试加入，报告该准确消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后重试。 +实时加入期间，OpenClaw 浏览器自动化会填写访客名称，点击 +Join/Ask to join，并在 Meet 的首次运行 “Use microphone” 选项提示出现时接受它。在仅观察加入或仅浏览器创建会议期间，当同一提示提供无麦克风选项时，它会继续跳过该提示。 +如果浏览器配置文件未登录、Meet 正在等待主持人准入、 +Chrome 需要麦克风/摄像头权限才能进行实时加入，或 Meet 卡在自动化无法解决的提示上，加入/测试语音结果会报告 +`manualActionRequired: true`，并带有 `manualActionReason` 和 +`manualActionMessage`。智能体应停止重试加入，报告该准确消息以及当前的 +`browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后重试。 -如果省略 `chromeNode.node`，OpenClaw 只会在恰好有一个已连接节点同时声明 `googlemeet.chrome` 和浏览器控制时自动选择。如果连接了多个具备能力的节点，请将 `chromeNode.node` 设置为节点 ID、显示名称或远程 IP。 +如果省略 `chromeNode.node`，OpenClaw 只会在恰好有一个已连接节点同时声明 +`googlemeet.chrome` 和浏览器控制能力时自动选择。如果连接了多个具备能力的节点，请将 +`chromeNode.node` 设置为节点 ID、显示名称或远程 IP。 常见失败检查： -- `Configured Google Meet node ... is not usable: offline`：固定的节点已被 Gateway 网关识别但不可用。智能体应将该节点视为诊断状态，而不是可用的 Chrome 主机，并报告设置阻塞项，除非用户要求，否则不要回退到其他传输协议。 -- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，批准配对，并确保已在 VM 中运行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。还要确认 Gateway 网关主机通过 `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` 允许这两个节点命令。 -- `BlackHole 2ch audio device not found`：在被检查的主机上安装 `blackhole-2ch`，并在使用本地 Chrome 音频前重启。 -- `BlackHole 2ch audio device not found on the node`：在 VM 中安装 `blackhole-2ch`，并重启 VM。 -- Chrome 打开但无法加入：在 VM 内的浏览器配置文件中登录，或保持设置 `chrome.guestName` 以便访客加入。访客自动加入通过节点浏览器代理使用 OpenClaw 浏览器自动化；请确保节点浏览器配置指向你想使用的配置文件，例如 `browser.defaultProfile: "user"` 或一个命名的现有会话配置文件。 -- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会先激活同一 Meet URL 的现有标签页，然后再打开新标签页；浏览器会议创建也会先复用进行中的 `https://meet.google.com/new` 或 Google 账号提示标签页，然后再打开另一个。 -- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；使用单独的虚拟设备或 Loopback 风格的路由，以获得干净的双工音频。 +- `Configured Google Meet node ... is not usable: offline`：固定节点已被 + Gateway 网关知道但不可用。智能体应将该节点视为诊断状态，而不是可用的 + Chrome 主机，并报告设置阻塞项，而不是回退到另一种传输协议，除非用户要求这样做。 +- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`， + 批准配对，并确保已在 VM 中运行 `openclaw plugins enable google-meet` 和 + `openclaw plugins enable browser`。同时确认 + Gateway 网关主机允许两个节点命令： + `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`。 +- `BlackHole 2ch audio device not found`：在被检查的主机上安装 + `blackhole-2ch`，并在使用本地 Chrome 音频前重启。 +- `BlackHole 2ch audio device not found on the node`：在 VM 中安装 + `blackhole-2ch`，并重启 VM。 +- Chrome 打开但无法加入：登录 VM 内的浏览器配置文件，或保留 + `chrome.guestName` 以进行访客加入。访客自动加入会通过节点浏览器代理使用 + OpenClaw 浏览器自动化；请确保节点浏览器配置指向你想要的配置文件，例如 + `browser.defaultProfile: "user"` 或命名的现有会话配置文件。 +- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw + 会在打开新标签页前激活同一 Meet URL 的现有标签页，并且浏览器会议创建会在打开另一个标签页前复用正在进行的 + `https://meet.google.com/new` 或 Google 账号提示标签页。 +- 无音频：在 Meet 中，将麦克风/扬声器通过 OpenClaw 使用的虚拟音频设备路径路由；使用单独的虚拟设备或类似 + Loopback 的路由来获得干净的双工音频。 ## 安装说明 -Chrome 回声默认值使用两个外部工具： +Chrome 回传默认使用两个外部工具： -- `sox`：命令行音频实用工具。该插件会为默认的 24 kHz PCM16 音频桥使用显式 CoreAudio 设备命令。 -- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 Chrome/Meet 可路由经过的 `BlackHole 2ch` 音频设备。 +- `sox`：命令行音频工具。该插件为默认 24 kHz PCM16 音频桥接使用显式 + CoreAudio 设备命令。 +- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 Chrome/Meet 可路由经过的 + `BlackHole 2ch` 音频设备。 -OpenClaw 不捆绑或再分发任一软件包。文档要求用户通过 Homebrew 将它们安装为主机依赖项。SoX 的许可证为 `LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你构建的安装器或设备会将 BlackHole 与 OpenClaw 捆绑在一起，请查看 BlackHole 的上游许可条款，或从 Existential Audio 获取单独许可。 +OpenClaw 不捆绑或再分发任一软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。SoX 许可证为 +`LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你构建的安装器或设备将 +BlackHole 与 OpenClaw 捆绑，请审查 BlackHole 的上游许可条款，或从 Existential Audio 获取单独许可证。 ## 传输协议 ### Chrome -Chrome 传输协议通过 OpenClaw 浏览器控制打开 Meet URL，并以已登录的 OpenClaw 浏览器配置文件身份加入。在 macOS 上，插件会在启动前检查 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 前运行音频桥健康检查命令和启动命令。当 Chrome/音频位于 Gateway 网关主机上时使用 `chrome`；当 Chrome/音频位于已配对节点（例如 Parallels macOS VM）上时使用 `chrome-node`。对于本地 Chrome，请使用 `browser.defaultProfile` 选择配置文件；`chrome.browserProfile` 会传递给 `chrome-node` 主机。 +Chrome 传输协议通过 OpenClaw 浏览器控制打开 Meet URL，并以已登录的 +OpenClaw 浏览器配置文件身份加入。在 macOS 上，插件会在启动前检查 +`BlackHole 2ch`。如果已配置，它还会在打开 Chrome 前运行音频桥接健康命令和启动命令。当 +Chrome/音频位于 Gateway 网关主机上时使用 `chrome`；当 Chrome/音频位于已配对节点（例如 +Parallels macOS VM）上时使用 `chrome-node`。对于本地 Chrome，请用 +`browser.defaultProfile` 选择配置文件；`chrome.browserProfile` 会传递给 +`chrome-node` 主机。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -将 Chrome 麦克风和扬声器音频路由到本地 OpenClaw 音频桥。如果未安装 `BlackHole 2ch`，加入会因设置错误失败，而不是在没有音频路径的情况下静默加入。 +通过本地 OpenClaw 音频桥接路由 Chrome 麦克风和扬声器音频。如果未安装 +`BlackHole 2ch`，加入会以设置错误失败，而不是在没有音频路径的情况下静默加入。 ### Twilio -Twilio 传输协议是委托给 Voice Call 插件的严格拨号方案。它不会解析 Meet 页面以获取电话号码。 +Twilio 传输协议是委托给 Voice Call 插件的严格拨号计划。它不会解析 +Meet 页面来获取电话号码。 -当 Chrome 参与不可用，或你想要电话拨入回退时使用此方式。Google Meet 必须为会议公开电话拨入号码和 PIN；OpenClaw 不会从 Meet 页面发现这些信息。 +当无法使用 Chrome 参与，或你想要电话拨入回退时使用此方式。Google Meet 必须为会议公开电话拨入号码和 +PIN；OpenClaw 不会从 Meet 页面发现这些信息。 在 Gateway 网关主机上启用 Voice Call 插件，而不是在 Chrome 节点上： ```json5 { plugins: { - allow: ["google-meet", "voice-call"], + allow: ["google-meet", "voice-call", "google"], entries: { "google-meet": { enabled: true, @@ -330,22 +365,43 @@ Twilio 传输协议是委托给 Voice Call 插件的严格拨号方案。它不 enabled: true, config: { provider: "twilio", + inboundPolicy: "allowlist", + realtime: { + enabled: true, + provider: "google", + instructions: "Join this Google Meet as an OpenClaw agent. Be brief.", + toolPolicy: "safe-read-only", + providers: { + google: { + silenceDurationMs: 500, + startSensitivity: "high", + }, + }, + }, }, }, + google: { + enabled: true, + }, }, }, } ``` -通过环境或配置提供 Twilio 凭证。环境变量可以让密钥不进入 `openclaw.json`： +通过环境或配置提供 Twilio 凭据。环境可让密钥不进入 `openclaw.json`： ```bash export TWILIO_ACCOUNT_SID=AC... export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 +export GEMINI_API_KEY=... ``` -启用 `voice-call` 后重启或重载 Gateway 网关；插件配置变更在 Gateway 网关进程重载前不会出现在已运行的进程中。 +如果那是你的实时语音提供商，请改用 `realtime.provider: "openai"` 搭配 +OpenAI provider 插件和 `OPENAI_API_KEY`。 + +启用 `voice-call` 后重启或重新加载 Gateway 网关；插件配置变更不会出现在已经运行的 +Gateway 网关进程中，直到它重新加载。 然后验证： @@ -355,7 +411,9 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -当 Twilio 委托接线完成后，`googlemeet setup` 会包含成功的 `twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 `twilio-voice-call-webhook` 检查。 +当 Twilio 委托已接好时，`googlemeet setup` 会包含成功的 +`twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 +`twilio-voice-call-webhook` 检查。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -375,29 +433,35 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth 和预检 -OAuth 对创建 Meet 链接是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你想要官方 API 创建、空间解析或 Meet Media API 预检检查时配置 OAuth。 +OAuth 对创建 Meet 链接是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你需要官方 +API 创建、空间解析或 Meet Media API 预检检查时，请配置 OAuth。 -Google Meet API 访问使用用户 OAuth：创建 Google Cloud OAuth 客户端，请求所需范围，授权 Google 账号，然后将生成的刷新令牌存储在 Google Meet 插件配置中，或提供 `OPENCLAW_GOOGLE_MEET_*` 环境变量。 +Google Meet API 访问使用用户 OAuth：创建 Google Cloud OAuth 客户端，请求所需作用域，授权一个 +Google 账号，然后将生成的刷新令牌存储在 Google Meet 插件配置中，或提供 +`OPENCLAW_GOOGLE_MEET_*` 环境变量。 -OAuth 不会取代 Chrome 加入路径。当你使用浏览器参与时，Chrome 和 Chrome-node 传输协议仍会通过已登录的 Chrome 配置文件、BlackHole/SoX 以及已连接节点加入。OAuth 仅用于官方 Google Meet API 路径：创建会议空间、解析空间，以及运行 Meet Media API 预检检查。 +OAuth 不会替代 Chrome 加入路径。当你使用浏览器参与时，Chrome 和 Chrome-node 传输协议仍会通过已登录的 +Chrome 配置文件、BlackHole/SoX 以及已连接节点加入。OAuth 仅用于官方 +Google Meet API 路径：创建会议空间、解析空间，并运行 Meet Media API 预检检查。 -### 创建 Google 凭证 +### 创建 Google 凭据 在 Google Cloud Console 中： -1. 创建或选择 Google Cloud 项目。 +1. 创建或选择一个 Google Cloud 项目。 2. 为该项目启用 **Google Meet REST API**。 3. 配置 OAuth 同意屏幕。 - - 对于 Google Workspace 组织，**Internal** 最简单。 - - **External** 适用于个人/测试设置；当应用处于 Testing 状态时，将每个会授权该应用的 Google 账号添加为测试用户。 -4. 添加 OpenClaw 请求的范围： + - **Internal** 对 Google Workspace 组织最简单。 + - **External** 适用于个人/测试设置；当应用处于 Testing 状态时，将每个会授权该应用的 + Google 账号添加为测试用户。 +4. 添加 OpenClaw 请求的作用域： - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.space.settings` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` 5. 创建 OAuth 客户端 ID。 - 应用类型：**Web application**。 - - 授权重定向 URI： + - 已获授权的重定向 URI： ```text http://localhost:8085/oauth2callback @@ -406,11 +470,14 @@ OAuth 不会取代 Chrome 加入路径。当你使用浏览器参与时，Chrome 6. 复制客户端 ID 和客户端密钥。 `meetings.space.created` 是 Google Meet `spaces.create` 所必需的。 -`meetings.space.readonly` 允许 OpenClaw 将 Meet URL/代码解析为空间。 -`meetings.space.settings` 允许 OpenClaw 在 API 房间创建期间传递 `SpaceConfig` 设置，例如 `accessType`。 -`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体工作；Google 可能要求加入 Developer Preview 才能实际使用 Media API。如果你只需要基于浏览器的 Chrome 加入，请完全跳过 OAuth。 +`meetings.space.readonly` 让 OpenClaw 能够将 Meet URL/代码解析为空间。 +`meetings.space.settings` 让 OpenClaw 能够在 API 房间创建期间传递 +`SpaceConfig` 设置，例如 `accessType`。 +`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体工作；Google 可能要求为实际 +Media API 使用加入 Developer Preview。如果你只需要基于浏览器的 +Chrome 加入，可以完全跳过 OAuth。 -### 签发刷新令牌 +### 生成刷新令牌 配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，或将它们作为环境变量传入，然后运行： @@ -418,7 +485,8 @@ OAuth 不会取代 Chrome 加入路径。当你使用浏览器参与时，Chrome openclaw googlemeet auth login --json ``` -该命令会打印带刷新令牌的 `oauth` 配置块。它使用 PKCE、`http://localhost:8085/oauth2callback` 上的 localhost 回调，以及带 `--manual` 的手动复制/粘贴流程。 +该命令会打印包含刷新令牌的 `oauth` 配置块。它使用 PKCE、`http://localhost:8085/oauth2callback` 上的 +localhost 回调，以及通过 `--manual` 的手动复制/粘贴流程。 示例： @@ -472,58 +540,54 @@ JSON 输出包括： } ``` -如果你不想把刷新令牌放在配置中，优先使用环境变量。如果配置值和环境值都存在，插件会先解析配置，然后回退到环境。 +当你不想在配置中放入刷新令牌时，优先使用环境变量。如果配置和环境值都存在，插件会先解析配置，然后再回退到环境。 -OAuth 同意包括 Meet 空间创建、Meet 空间读取访问和 Meet 会议媒体读取访问。如果你在会议创建支持存在之前已认证，请重新运行 `openclaw googlemeet auth login --json`，让刷新令牌具有 `meetings.space.created` 范围。 +OAuth 同意包含 Meet 空间创建、Meet 空间读取访问和 Meet 会议媒体读取访问。如果你在会议创建支持存在之前已完成身份验证，请重新运行 +`openclaw googlemeet auth login --json`，以便刷新令牌具备 +`meetings.space.created` 作用域。 -### 使用 doctor 验证 OAuth +### 使用 Doctor 验证 OAuth -当你想要快速、非密钥的健康检查时，运行 OAuth doctor： +当你想要快速、非密钥的健康检查时，运行 OAuth Doctor： ```bash openclaw googlemeet doctor --oauth --json ``` -这不会加载 Chrome 运行时，也不需要已连接的 Chrome 节点。它会检查 OAuth 配置是否存在，以及刷新令牌能否签发访问令牌。JSON 报告只包括状态字段，例如 `ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息；它不会打印访问令牌、刷新令牌或客户端密钥。 +这不会加载 Chrome 运行时，也不需要已连接的 Chrome 节点。它会检查 OAuth 配置是否存在，以及刷新令牌是否可以生成访问令牌。JSON 报告仅包含状态字段，例如 +`ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息；它不会打印访问令牌、刷新令牌或客户端密钥。 常见结果： -| 检查 | 含义 | +| 检查 | 含义 | | -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在缓存的访问令牌。 | -| `oauth-token` | 缓存的访问令牌仍然有效，或刷新令牌已签发新的访问令牌。 | -| `meet-spaces-get` | 可选的 `--meeting` 检查已解析现有 Meet 空间。 | -| `meet-spaces-create` | 可选的 `--create-space` 检查已创建新的 Meet 空间。 | +| `oauth-config` | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或缓存的访问令牌。 | +| `oauth-token` | 缓存的访问令牌仍然有效，或刷新令牌已签发新的访问令牌。 | +| `meet-spaces-get` | 可选的 `--meeting` 检查已解析现有的 Meet 空间。 | +| `meet-spaces-create` | 可选的 `--create-space` 检查已创建新的 Meet 空间。 | -若还要证明 Google Meet API 启用状态和 `spaces.create` 范围，请运行会产生副作用的创建检查： +若还要证明 Google Meet API 已启用以及 `spaces.create` 范围可用，请运行有副作用的创建检查： ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 -Google Cloud 项目已启用 Meet API，并且已授权账号拥有 -`meetings.space.created` 作用域时使用它。 +`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，并且已授权账号拥有 `meetings.space.created` 范围时使用它。 -要证明对现有会议空间的读取权限： +若要证明对现有会议空间的读取访问权限： ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` 和 `resolve-space` 会证明对已授权 -Google 账号可访问的现有空间拥有读取权限。这些检查返回 `403` -通常表示 Google Meet REST API 已禁用、已同意授权的刷新令牌缺少所需作用域， -或 Google 账号无法访问该 Meet 空间。刷新令牌错误表示需要重新运行 -`openclaw googlemeet auth login --json` 并存储新的 `oauth` 块。 +`doctor --oauth --meeting` 和 `resolve-space` 可证明对已授权 Google 账号可访问的现有空间具有读取访问权限。这些检查返回 `403` 通常表示 Google Meet REST API 已禁用、已同意授权的刷新令牌缺少所需范围，或 Google 账号无法访问该 Meet 空间。刷新令牌错误表示需要重新运行 `openclaw googlemeet auth login +--json`，并存储新的 `oauth` 块。 -浏览器后备方案不需要 OAuth 凭据。在该模式下，Google -认证来自所选节点上已登录的 Chrome 配置文件，而不是来自 -OpenClaw 配置。 +浏览器回退不需要 OAuth 凭据。在该模式下，Google 身份验证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。 -这些环境变量可作为后备值接受： +这些环境变量可作为回退： - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET` @@ -540,13 +604,13 @@ OpenClaw 配置。 openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -在媒体工作前运行预检： +在处理媒体前运行预检： ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -在 Meet 创建会议记录后列出会议产物和出席情况： +在 Meet 创建会议记录后，列出会议工件和出席情况： ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -554,10 +618,9 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export ``` -带 `--meeting` 时，`artifacts` 和 `attendance` 默认使用最新的会议记录。 -当你想获取该会议保留的每一条记录时，传入 `--all-conference-records`。 +使用 `--meeting` 时，`artifacts` 和 `attendance` 默认使用最新的会议记录。当你需要该会议的所有保留记录时，传入 `--all-conference-records`。 -日历查找可以在读取 Meet 产物前从 Google Calendar 解析会议 URL： +Calendar 查询可在读取 Meet 工件前，从 Google Calendar 解析会议 URL： ```bash openclaw googlemeet latest --today @@ -566,12 +629,8 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 -Calendar 事件。使用 `--event ` 搜索匹配的事件文本，使用 -`--calendar ` 指定非主日历。日历查找需要重新进行 OAuth 登录，并包含 -Calendar 事件只读作用域。 -`calendar-events` 会预览匹配的 Meet 事件，并标记 `latest`、`artifacts`、 -`attendance` 或 `export` 将选择的事件。 +`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 Calendar 事件。使用 `--event ` 搜索匹配的事件文本，并使用 `--calendar ` 指定非主日历。Calendar 查询需要包含 Calendar events readonly 范围的新 OAuth 登录。 +`calendar-events` 会预览匹配的 Meet 事件，并标记 `latest`、`artifacts`、`attendance` 或 `export` 将选择的事件。 如果你已经知道会议记录 ID，可以直接指定它： @@ -581,18 +640,15 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -当你想在通话后关闭房间时，可以结束 API 创建的空间中的活跃会议： +当你想在通话后关闭房间时，可结束 API 创建空间中的活动会议： ```bash openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij ``` -这会调用 Google Meet `spaces.endActiveConference`，并且需要 OAuth 具有 -`meetings.space.created` 作用域，且该空间可由已授权账号管理。 -OpenClaw 接受 Meet URL、会议代码或 `spaces/{id}` 输入，并在结束活跃会议前 -将其解析为 API 空间资源。 -它与 `googlemeet leave` 是分开的：`leave` 会停止 OpenClaw 的本地/会话参与， -而 `end-active-conference` 会请求 Google Meet 结束该空间的活跃会议。 +这会调用 Google Meet `spaces.endActiveConference`，并且对于已授权账号可管理的空间，需要带有 `meetings.space.created` 范围的 OAuth。 +OpenClaw 接受 Meet URL、会议代码或 `spaces/{id}` 输入，并在结束活动会议前将其解析为 API 空间资源。 +它独立于 `googlemeet leave`：`leave` 会停止 OpenClaw 的本地/会话参与，而 `end-active-conference` 会请求 Google Meet 结束该空间的活动会议。 写入可读报告： @@ -609,28 +665,12 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -当 Google 为会议公开这些数据时，`artifacts` 会返回会议记录元数据，以及参与者、 -录制、转录、结构化转录条目和智能笔记资源元数据。对大型会议使用 -`--no-transcript-entries` 跳过条目查找。`attendance` 会将参与者展开为 -参与者会话行，包含首次/最后可见时间、总会话时长、迟到/提前离开标志， -并按已登录用户或显示名称合并重复参与者资源。传入 `--no-merge-duplicates` -可将原始参与者资源保持分离，传入 `--late-after-minutes` 可调整迟到检测， -传入 `--early-before-minutes` 可调整提前离开检测。 +`artifacts` 会在 Google 为会议公开相关内容时，返回会议记录元数据，以及参与者、录制文件、转录稿、结构化转录条目和智能笔记资源元数据。使用 `--no-transcript-entries` 可跳过大型会议的条目查询。`attendance` 会将参与者展开为参与者会话行，其中包含首次/最后出现时间、总会话时长、迟到/提前离开标记，并按已登录用户或显示名称合并重复的参与者资源。传入 `--no-merge-duplicates` 可保持原始参与者资源分离，传入 `--late-after-minutes` 可调整迟到检测，传入 `--early-before-minutes` 可调整提前离开检测。 -`export` 会写入一个包含 `summary.md`、`attendance.csv`、`transcript.md`、 -`artifacts.json`、`attendance.json` 和 `manifest.json` 的文件夹。 -`manifest.json` 会记录所选输入、导出选项、会议记录、输出文件、计数、 -令牌来源、使用过的 Calendar 事件，以及任何部分检索警告。传入 `--zip` -还会在文件夹旁写入一个可移植归档。传入 `--include-doc-bodies` 会通过 -Google Drive `files.export` 导出链接的转录和智能笔记 Google Docs 文本； -这需要重新进行 OAuth 登录，并包含 Drive Meet 只读作用域。不带 -`--include-doc-bodies` 时，导出只包含 Meet 元数据和结构化转录条目。如果 -Google 返回部分产物失败，例如智能笔记列表、转录条目或 Drive 文档正文错误， -摘要和清单会保留警告，而不是让整个导出失败。 -使用 `--dry-run` 获取相同的产物/出席数据并打印清单 JSON，而不创建文件夹或 -ZIP。这在写入大型导出前很有用，或者当智能体只需要计数、所选记录和警告时也很有用。 +`export` 会写入一个文件夹，其中包含 `summary.md`、`attendance.csv`、`transcript.md`、`artifacts.json`、`attendance.json` 和 `manifest.json`。`manifest.json` 会记录所选输入、导出选项、会议记录、输出文件、计数、令牌来源、使用过的 Calendar 事件，以及任何部分检索警告。传入 `--zip` 还会在文件夹旁边写入一个可移植归档。传入 `--include-doc-bodies` 可通过 Google Drive `files.export` 导出链接的转录稿和智能笔记 Google Docs 文本；这需要一次新的 OAuth 登录，并包含 Drive Meet 只读范围。没有 `--include-doc-bodies` 时，导出仅包含 Meet 元数据和结构化转录条目。如果 Google 返回部分工件失败，例如智能笔记列表、转录条目或 Drive 文档正文错误，摘要和清单会保留警告，而不是让整个导出失败。 +使用 `--dry-run` 可获取相同的工件/出勤数据并打印清单 JSON，而不创建文件夹或 ZIP。这在写入大型导出前，或当智能体只需要计数、所选记录和警告时很有用。 -智能体也可以通过 `google_meet` 工具创建相同的包： +智能体也可以通过 `google_meet` 工具创建同一个包： ```json { @@ -644,7 +684,7 @@ ZIP。这在写入大型导出前很有用，或者当智能体只需要计数 设置 `"dryRun": true` 可仅返回导出清单并跳过文件写入。 -智能体也可以创建一个带有显式访问策略的 API 支持房间： +智能体也可以创建一个由 API 支持、带显式访问策略的房间： ```json { @@ -655,7 +695,7 @@ ZIP。这在写入大型导出前很有用，或者当智能体只需要计数 } ``` -并且它们可以结束已知房间的活跃会议： +并且它们可以结束已知房间的活动会议： ```json { @@ -664,7 +704,7 @@ ZIP。这在写入大型导出前很有用，或者当智能体只需要计数 } ``` -对于先监听的验证，智能体应在声称会议有用前使用 `test_listen`： +对于先监听验证，智能体应先使用 `test_listen`，再声称该会议有用： ```json { @@ -683,32 +723,22 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -针对有人员发言且 Meet 字幕可用的会议运行实时的先监听浏览器探测： +针对有人会发言且 Meet 字幕可用的会议运行实时先监听浏览器探测： ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport chrome-node --timeout-ms 30000 ``` -实时冒烟测试环境： +实时冒烟环境： - `OPENCLAW_LIVE_TEST=1` 启用受保护的实时测试。 -- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` 指向保留的 Meet URL、代码或 - `spaces/{id}`。 -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` 提供 OAuth - 客户端 ID。 -- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` 或 `GOOGLE_MEET_REFRESH_TOKEN` 提供 - 刷新令牌。 -- 可选：`OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`、 - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` 和 - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 使用不带 `OPENCLAW_` 前缀的 - 相同后备名称。 +- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` 指向保留的 Meet URL、代码或 `spaces/{id}`。 +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` 提供 OAuth client id。 +- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` 或 `GOOGLE_MEET_REFRESH_TOKEN` 提供刷新令牌。 +- 可选：`OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`、`OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` 和 `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 使用不带 `OPENCLAW_` 前缀的相同回退名称。 -基础产物/出席实时冒烟测试需要 -`https://www.googleapis.com/auth/meetings.space.readonly` 和 -`https://www.googleapis.com/auth/meetings.conference.media.readonly`。日历查找需要 -`https://www.googleapis.com/auth/calendar.events.readonly`。Drive 文档正文导出需要 -`https://www.googleapis.com/auth/drive.meet.readonly`。 +基础工件/出勤实时冒烟测试需要 `https://www.googleapis.com/auth/meetings.space.readonly` 和 `https://www.googleapis.com/auth/meetings.conference.media.readonly`。Calendar 查询需要 `https://www.googleapis.com/auth/calendar.events.readonly`。Drive 文档正文导出需要 `https://www.googleapis.com/auth/drive.meet.readonly`。 创建新的 Meet 空间： @@ -716,11 +746,9 @@ openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport openclaw googlemeet create ``` -该命令会打印新的 `meeting uri`、来源和加入会话。带 OAuth 凭据时，它会使用官方 -Google Meet API。不带 OAuth 凭据时，它会使用固定 Chrome 节点中已登录的浏览器配置文件作为后备方案。智能体可以使用带 `action: "create"` 的 -`google_meet` 工具在一步中创建并加入。若只创建 URL，传入 `"join": false`。 +该命令会打印新的 `meeting uri`、来源和加入会话。使用 OAuth 凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会使用固定 Chrome 节点中已登录的浏览器配置文件作为回退。智能体可以使用带有 `action: "create"` 的 `google_meet` 工具一步完成创建和加入。对于仅创建 URL，传入 `"join": false`。 -浏览器后备方案的 JSON 输出示例： +来自浏览器回退的 JSON 输出示例： ```json { @@ -740,9 +768,7 @@ Google Meet API。不带 OAuth 凭据时，它会使用固定 Chrome 节点中 } ``` -如果浏览器后备方案在创建 URL 前遇到 Google 登录或 Meet 权限阻塞， -Gateway 网关方法会返回失败响应，并且 `google_meet` 工具会返回结构化详情， -而不是普通字符串： +如果浏览器回退在创建 URL 前遇到 Google 登录或 Meet 权限阻断，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化详情，而不是纯字符串： ```json { @@ -760,11 +786,9 @@ Gateway 网关方法会返回失败响应，并且 `google_meet` 工具会返回 } ``` -当智能体看到 `manualActionRequired: true` 时，应报告 -`manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 -Meet 标签页，直到操作员完成浏览器步骤。 +当智能体看到 `manualActionRequired: true` 时，它应报告 `manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成浏览器步骤。 -API 创建的 JSON 输出示例： +来自 API 创建的 JSON 输出示例： ```json { @@ -785,18 +809,22 @@ API 创建的 JSON 输出示例： } ``` -创建 Meet 后默认会加入。Chrome 或 Chrome-node 传输仍需要已登录的 -Google Chrome 配置文件才能通过浏览器加入。如果配置文件已退出登录， -OpenClaw 会报告 `manualActionRequired: true` 或浏览器后备方案错误， -并要求操作员完成 Google 登录后再重试。 +创建 Meet 默认会加入会议。Chrome 或 Chrome-node 传输协议仍然 +需要已登录的 Google Chrome 配置文件，才能通过浏览器加入。如果该 +配置文件已退出登录，OpenClaw 会报告 `manualActionRequired: true` 或 +浏览器回退错误，并要求操作者完成 Google 登录后再重试。 -只有在确认你的 Cloud 项目、OAuth 主体和会议参与者已加入 -Google Workspace Developer Preview Program for Meet media APIs 后，才设置 +仅在确认你的 Cloud 项目、OAuth 主体和会议参与者已加入 Google +Workspace Developer Preview Program for Meet media APIs 后，才设置 `preview.enrollmentAcknowledged: true`。 ## 配置 -常见的 Chrome 智能体路径只需要启用插件、BlackHole、SoX、一个实时转录提供商密钥，以及已配置的 OpenClaw TTS 提供商。OpenAI 是默认转录提供商；将 `realtime.voiceProvider` 设置为 `“google”`，并设置 `realtime.model`，即可在不更改默认智能体模式转录提供商的情况下，将 Google Gemini Live 用于 `bidi` 模式： +通用 Chrome 智能体路径只需要启用插件、BlackHole、SoX、一个 +实时转录提供商密钥，以及一个已配置的 OpenClaw TTS 提供商。 +OpenAI 是默认转录提供商；将 `realtime.voiceProvider` 设为 +`"google"`，并设置 `realtime.model`，即可在 `bidi` 模式下使用 +Google Gemini Live，而无需更改默认智能体模式转录提供商： ```bash brew install blackhole-2ch sox @@ -823,31 +851,56 @@ export GEMINI_API_KEY=... 默认值： - `defaultTransport: "chrome"` -- `defaultMode: "agent"`（`"realtime"` 仅作为 `"agent"` 的旧版兼容别名被接受；新的工具调用应使用 `"agent"`） +- `defaultMode: "agent"`（`"realtime"` 仅作为 `"agent"` 的旧版 + 兼容别名被接受；新的工具调用应使用 `"agent"`） - `chromeNode.node`：可选的 `chrome-node` 节点 ID/名称/IP - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`：在未登录的 Meet 访客屏幕上使用的名称 -- `chrome.autoJoin: true`：通过 `chrome-node` 上的 OpenClaw 浏览器自动化，尽力填写访客名称并点击立即加入 -- `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页 -- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已进入通话后，再触发回话开场白 -- `chrome.audioFormat: "pcm16-24khz"`：命令对音频格式。仅对仍输出电话音频的旧版/自定义命令对使用 `"g711-ulaw-8khz"`。 -- `chrome.audioBufferBytes: 4096`：用于生成的 Chrome 命令对音频命令的 SoX 处理缓冲区。这是 SoX 默认 8192 字节缓冲区的一半，可降低默认管道延迟，同时保留在繁忙主机上调高的空间。低于 SoX 最小值的值会被钳制为 17 字节。 -- `chrome.audioInputCommand`：从 CoreAudio `BlackHole 2ch` 读取并以 `chrome.audioFormat` 写入音频的 SoX 命令 -- `chrome.audioOutputCommand`：以 `chrome.audioFormat` 读取音频并写入 CoreAudio `BlackHole 2ch` 的 SoX 命令 -- `chrome.bargeInInputCommand`：可选的本地麦克风命令，在助手播放处于活跃状态时，为人工插话检测写入有符号 16 位小端单声道 PCM。目前这适用于 Gateway 网关托管的 `chrome` 命令对桥接。 -- `chrome.bargeInRmsThreshold: 650`：在 `chrome.bargeInInputCommand` 上计为人工打断的 RMS 电平 -- `chrome.bargeInPeakThreshold: 2500`：在 `chrome.bargeInInputCommand` 上计为人工打断的峰值电平 +- `chrome.guestName: "OpenClaw Agent"`：在未登录的 Meet 访客 + 屏幕上使用的名称 +- `chrome.autoJoin: true`：通过 `chrome-node` 上的 OpenClaw 浏览器自动化， + 尽力填写访客名称并点击“立即加入” +- `chrome.reuseExistingTab: true`：激活已有的 Meet 标签页，而不是 + 打开重复标签页 +- `chrome.waitForInCallMs: 20000`：在触发回话开场前，等待 Meet 标签页 + 报告已进入通话 +- `chrome.audioFormat: "pcm16-24khz"`：命令对音频格式。仅对仍然输出 + 电话音频的旧版/自定义命令对使用 `"g711-ulaw-8khz"`。 +- `chrome.audioBufferBytes: 4096`：用于生成的 Chrome 命令对音频命令的 + SoX 处理缓冲区。这是 SoX 默认 8192 字节缓冲区的一半，可降低默认管道 + 延迟，同时在繁忙主机上保留增大空间。低于 SoX 最小值的值会被钳制为 + 17 字节。 +- `chrome.audioInputCommand`：从 CoreAudio `BlackHole 2ch` 读取并以 + `chrome.audioFormat` 写入音频的 SoX 命令 +- `chrome.audioOutputCommand`：读取 `chrome.audioFormat` 音频并写入 + CoreAudio `BlackHole 2ch` 的 SoX 命令 +- `chrome.bargeInInputCommand`：可选的本地麦克风命令，在助手播放处于 + 活跃状态时，写入有符号 16 位小端单声道 PCM，用于检测人工插话。当前 + 适用于 Gateway 网关托管的 `chrome` 命令对桥接。 +- `chrome.bargeInRmsThreshold: 650`：在 `chrome.bargeInInputCommand` 上 + 计为人工打断的 RMS 电平 +- `chrome.bargeInPeakThreshold: 2500`：在 `chrome.bargeInInputCommand` 上 + 计为人工打断的峰值电平 - `chrome.bargeInCooldownMs: 900`：重复清除人工打断之间的最小延迟 -- `mode: "agent"`：默认回话模式。参与者语音由已配置的实时转录提供商转录，发送到每场会议子智能体会话中的已配置 OpenClaw 智能体，并通过正常的 OpenClaw TTS 运行时回播。 -- `mode: "bidi"`：后备的直接双向实时模型模式。实时语音提供商直接回答参与者语音，并可调用 `openclaw_agent_consult` 获取更深入/有工具支持的答案。 -- `mode: "transcribe"`：没有回话桥接的仅观察模式。 -- `realtime.provider: "openai"`：当下面的作用域提供商字段未设置时使用的兼容性后备。 -- `realtime.transcriptionProvider: "openai"`：`agent` 模式用于实时转录的提供商 ID。 -- `realtime.voiceProvider`：`bidi` 模式用于直接实时语音的提供商 ID。将其设置为 `"google"` 可使用 Gemini Live，同时让智能体模式转录继续使用 OpenAI。 +- `mode: "agent"`：默认回话模式。参与者语音由已配置的实时转录提供商转录， + 发送到每个会议子智能体会话中的已配置 OpenClaw 智能体，并通过正常的 + OpenClaw TTS 运行时回放。 +- `mode: "bidi"`：回退的直接双向实时模型模式。实时语音提供商直接回答 + 参与者语音，并可调用 `openclaw_agent_consult` 获取更深入/工具支持的答案。 +- `mode: "transcribe"`：无回话桥接的仅观察模式。 +- `realtime.provider: "openai"`：当下面的作用域提供商字段未设置时使用的 + 兼容回退。 +- `realtime.transcriptionProvider: "openai"`：`agent` 模式用于实时转录的 + 提供商 ID。 +- `realtime.voiceProvider`：`bidi` 模式用于直接实时语音的提供商 ID。将其 + 设为 `"google"` 可使用 Gemini Live，同时让智能体模式转录继续使用 + OpenAI。 - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`：简短的语音回复，并使用 `openclaw_agent_consult` 获取更深入答案 -- `realtime.introMessage`：实时桥接连接时的简短语音就绪检查；将其设置为 `""` 可静默加入 -- `realtime.agentId`：用于 `openclaw_agent_consult` 的可选 OpenClaw 智能体 ID；默认为 `main` +- `realtime.instructions`：简短的语音回复，并使用 + `openclaw_agent_consult` 获取更深入的答案 +- `realtime.introMessage`：实时桥接连接时的简短语音就绪检查；将其设为 + `""` 可静默加入 +- `realtime.agentId`：用于 `openclaw_agent_consult` 的可选 OpenClaw + 智能体 ID；默认为 `main` 可选覆盖项： @@ -917,7 +970,11 @@ export GEMINI_API_KEY=... } ``` -`voiceCall.enabled` 默认为 `true`；使用 Twilio 传输时，它会把实际的 PSTN 呼叫、DTMF 和开场问候委托给 Voice Call 插件。Voice Call 会在打开实时媒体流之前播放 DTMF 序列，然后使用保存的开场文本作为初始实时问候。如果未启用 `voice-call`，Google Meet 仍可验证并记录拨号计划，但无法发起 Twilio 呼叫。 +`voiceCall.enabled` 默认为 `true`；使用 Twilio 传输协议时，它会将实际的 +PSTN 呼叫、DTMF 和开场问候委托给 Voice Call 插件。Voice Call 会先播放 +DTMF 序列，再打开实时媒体流，然后将保存的开场文本用作初始实时问候。如果 +未启用 `voice-call`，Google Meet 仍可验证并记录拨号计划，但无法发起 +Twilio 呼叫。 ## 工具 @@ -932,20 +989,40 @@ export GEMINI_API_KEY=... } ``` -当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在配对节点（例如 Parallels VM）上时，使用 `transport: "chrome-node"`。在这两种情况下，模型提供商和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭据保留在那里。使用默认 `mode: "agent"` 时，实时转录提供商负责监听，已配置的 OpenClaw 智能体生成答案，常规 OpenClaw TTS 将其朗读到 Meet 中。当你希望实时语音模型直接回答时，使用 `mode: "bidi"`。原始 `mode: "realtime"` 仍作为 `mode: "agent"` 的旧版兼容别名被接受，但不再在智能体工具 schema 中宣传。 +当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。 +当 Chrome 运行在配对节点（如 Parallels VM）上时，使用 +`transport: "chrome-node"`。两种情况下，模型提供商和 +`openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证 +保留在那里。使用默认 `mode: "agent"` 时，实时转录提供商负责监听，已配置的 +OpenClaw 智能体生成答案，常规 OpenClaw TTS 将其说入 Meet。当你希望 +实时语音模型直接回答时，使用 `mode: "bidi"`。原始的 `mode: "realtime"` +仍作为 `mode: "agent"` 的旧版兼容别名被接受，但不再在智能体工具架构中公开。 -使用 `action: "status"` 列出活跃会话或检查会话 ID。使用带有 `sessionId` 和 `message` 的 `action: "speak"`，让实时智能体立即说话。使用 `action: "test_speech"` 创建或复用会话、触发已知短语，并在 Chrome 主机可报告时返回 `inCall` 健康状态。`test_speech` 始终强制使用 `mode: "agent"`，并且如果被要求以 `mode: "transcribe"` 运行则会失败，因为仅观察会话有意不能发出语音。其 `speechOutputVerified` 结果基于本次测试调用期间实时音频输出字节数增加，因此带有旧音频的复用会话不会计为一次新的成功语音检查。使用 `action: "leave"` 将会话标记为已结束。 +使用 `action: "status"` 列出活动会话或检查某个会话 ID。使用 +`action: "speak"` 搭配 `sessionId` 和 `message`，让实时智能体立即发声。 +使用 `action: "test_speech"` 创建或复用会话、触发已知短语，并在 Chrome +主机可以报告时返回 `inCall` 健康状态。`test_speech` 始终强制使用 +`mode: "agent"`，如果被要求在 `mode: "transcribe"` 下运行则会失败，因为 +仅观察会话有意不能输出语音。其 `speechOutputVerified` 结果基于本次测试 +调用期间实时音频输出字节增加，因此复用的会话中较早的音频不会被计为新的 +成功语音检查。使用 `action: "leave"` 将会话标记为已结束。 -`status` 在可用时包含 Chrome 健康状态： +`status` 会在可用时包含 Chrome 健康状态： -- `inCall`：Chrome 看起来位于 Meet 通话内 -- `micMuted`：尽力判断的 Meet 麦克风状态 -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限，或浏览器控制修复后，语音才能工作 -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`：现在是否允许托管 Chrome 语音。`speechReady: false` 表示 OpenClaw 没有把开场白/测试短语发送到音频桥接。 +- `inCall`：Chrome 似乎已进入 Meet 通话 +- `micMuted`：尽力获取的 Meet 麦克风状态 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`： + 浏览器配置文件需要人工登录、Meet 主持人准入、权限或浏览器控制修复后， + 语音才能工作 +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`：当前是否 + 允许托管 Chrome 语音。`speechReady: false` 表示 OpenClaw 未将开场/测试 + 短语发送进音频桥接。 - `providerConnected` / `realtimeReady`：实时语音桥接状态 -- `lastInputAt` / `lastOutputAt`：上次从桥接看到或发送到桥接的音频 -- `audioOutputRouted` / `audioOutputDeviceLabel`：Meet 标签页的媒体输出是否已主动路由到桥接使用的 BlackHole 设备 -- `lastSuppressedInputAt` / `suppressedInputBytes`：助手播放处于活跃状态时被忽略的 local loopback 输入 +- `lastInputAt` / `lastOutputAt`：桥接最近接收或发送音频的时间 +- `audioOutputRouted` / `audioOutputDeviceLabel`：Meet 标签页的媒体输出是否 + 已主动路由到桥接使用的 BlackHole 设备 +- `lastSuppressedInputAt` / `suppressedInputBytes`：助手播放处于活跃状态时被 + 忽略的 loopback 输入 ```json { @@ -957,28 +1034,45 @@ export GEMINI_API_KEY=... ## 智能体和 Bidi 模式 -Chrome `agent` 模式针对“我的智能体在会议中”的行为进行了优化。实时转录提供商会听取会议音频，最终参与者转录会通过已配置的 OpenClaw 智能体路由，答案则通过正常的 OpenClaw TTS 运行时朗读。当你希望实时语音模型直接回答时，设置 `mode: "bidi"`。在咨询前，相邻的最终转录片段会合并，因此一个口头轮次不会产生多个过时的部分答案。当队列中的助手音频仍在播放时，实时输入也会被抑制，并且在智能体咨询前会忽略最近类似助手的转录回声，以免 BlackHole local loopback 让智能体回答自己的语音。 +Chrome `agent` 模式针对“我的智能体在会议中”的行为进行了优化。实时转录 +提供商听取会议音频，最终的参与者转录会路由到已配置的 OpenClaw 智能体， +答案则通过正常的 OpenClaw TTS 运行时说出。当你希望实时语音模型直接回答时， +设置 `mode: "bidi"`。 +在咨询前，会合并相邻的最终转录片段，避免一个发言轮次产生多个过时的部分答案。 +当排队的助手音频仍在播放时，也会抑制实时输入，并且在智能体咨询前忽略近期类似 +助手的转录回声，避免 BlackHole loopback 让智能体回答自己的语音。 -| 模式 | 由谁决定答案 | 语音输出路径 | 使用场景 | +| 模式 | 由谁决定答案 | 语音输出路径 | 适用场景 | | ------- | ----------------------------- | -------------------------------------- | ----------------------------------------------------- | -| `agent` | 已配置的 OpenClaw 智能体 | 正常 OpenClaw TTS 运行时 | 你想要“我的智能体在会议中”的行为 | -| `bidi` | 实时语音模型 | 实时语音提供商音频响应 | 你想要最低延迟的对话语音循环 | +| `agent` | 已配置的 OpenClaw 智能体 | 正常 OpenClaw TTS 运行时 | 你需要“我的智能体在会议中”的行为 | +| `bidi` | 实时语音模型 | 实时语音提供商音频响应 | 你需要最低延迟的对话式语音循环 | -在 `bidi` 模式下，当实时模型需要更深入的推理、当前信息或正常 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 +在 `bidi` 模式下，当实时模型需要更深入的推理、最新信息或常规 OpenClaw +工具时，它可以调用 `openclaw_agent_consult`。 -咨询工具会在后台使用最近的会议转录上下文运行常规 OpenClaw 智能体，并返回简洁的语音答案。在 `agent` 模式下，OpenClaw 会将该答案直接发送到 TTS 运行时；在 `bidi` 模式下，实时语音模型可以将咨询结果回播到会议中。它使用与 Voice Call 相同的共享咨询机制。 +咨询工具会在后台运行常规 OpenClaw 智能体，并带上最近的会议转录上下文，然后返回 +简洁的语音答案。在 `agent` 模式下，OpenClaw 会将该答案直接发送到 TTS 运行时； +在 `bidi` 模式下，实时语音模型可以将咨询结果说回会议中。它使用与 Voice Call +相同的共享咨询机制。 -默认情况下，咨询会针对 `main` 智能体运行。当某个 Meet 通道应咨询专用的 OpenClaw 智能体工作区、模型默认值、工具策略、记忆和会话历史时，设置 `realtime.agentId`。 +默认情况下，咨询针对 `main` 智能体运行。当某个 Meet 通道应咨询专用的 +OpenClaw 智能体工作区、模型默认值、工具策略、记忆和会话历史时，设置 +`realtime.agentId`。 -智能体模式咨询使用每场会议的 `agent::subagent:google-meet:` 会话键，因此后续问题会保留会议上下文，同时继承已配置智能体的正常智能体策略。 +智能体模式咨询使用每个会议专属的 +`agent::subagent:google-meet:` 会话键，因此后续问题可以保留 +会议上下文，同时继承已配置智能体的正常智能体策略。 `realtime.toolPolicy` 控制咨询运行： -- `safe-read-only`：暴露咨询工具，并将常规智能体限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 -- `owner`：暴露咨询工具，并让常规智能体使用正常的智能体工具策略。 +- `safe-read-only`：暴露咨询工具，并将常规智能体限制为 + `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 + `memory_get`。 +- `owner`：暴露咨询工具，并允许常规智能体使用正常的智能体工具策略。 - `none`：不向实时语音模型暴露咨询工具。 -咨询会话键按每个 Meet 会话设定作用域，因此后续咨询调用可在同一场会议期间复用先前的咨询上下文。 +咨询会话键按每个 Meet 会话限定范围，因此后续咨询调用可以在同一场会议中复用 +先前的咨询上下文。 要在 Chrome 完全加入通话后强制进行语音就绪检查： @@ -986,7 +1080,7 @@ Chrome `agent` 模式针对“我的智能体在会议中”的行为进行了 openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -对于完整的加入并说话冒烟测试： +完整的加入并发言冒烟测试： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -996,7 +1090,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## 实时测试清单 -在将会议交给无人值守的智能体之前，使用此序列： +在把会议交给无人值守的智能体之前，使用此顺序： ```bash openclaw googlemeet setup @@ -1006,15 +1100,15 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: Google Meet speech test complete." ``` -预期 Chrome-node 状态： +预期的 Chrome-node 状态： - `googlemeet setup` 全部为绿色。 -- 当 Chrome-node 是默认传输协议或固定了某个节点时，`googlemeet setup` 会包含 `chrome-node-connected`。 -- `nodes status` 显示所选节点已连接。 -- 所选节点同时公布 `googlemeet.chrome` 和 `browser.proxy`。 -- Meet 标签页加入通话，并且 `test-speech` 返回 Chrome 健康状态，其中包含 `inCall: true`。 +- 当 Chrome-node 是默认传输协议或固定了某个节点时，`googlemeet setup` 包含 `chrome-node-connected`。 +- `nodes status` 显示选定节点已连接。 +- 选定节点同时公布 `googlemeet.chrome` 和 `browser.proxy`。 +- Meet 标签页加入通话，并且 `test-speech` 返回包含 `inCall: true` 的 Chrome 健康状态。 -对于 Parallels macOS 虚拟机这样的远程 Chrome 主机，在更新 Gateway 网关或虚拟机后，这是最短的安全检查： +对于远程 Chrome 主机，例如 Parallels macOS VM，在更新 Gateway 网关或 VM 后，这是最短的安全检查： ```bash openclaw googlemeet setup @@ -1025,7 +1119,7 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -这能证明 Gateway 网关插件已加载，虚拟机节点已使用当前令牌连接，并且 Meet 音频桥可用，然后智能体才会打开真正的会议标签页。 +这证明 Gateway 网关插件已加载，VM 节点已使用当前令牌连接，并且 Meet 音频桥可用，然后智能体再打开真实会议标签页。 对于 Twilio 冒烟测试，请使用公开电话拨入详情的会议： @@ -1042,14 +1136,14 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ - `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 `twilio-voice-call-webhook` 检查。 - Gateway 网关重新加载后，CLI 中可以使用 `voicecall`。 - 返回的会话包含 `transport: "twilio"` 和 `twilio.voiceCallId`。 -- `openclaw logs --follow` 显示先提供 DTMF TwiML，再提供实时 TwiML，然后建立实时桥，并已排队初始问候语。 -- `googlemeet leave ` 会挂断委派的语音通话。 +- `openclaw logs --follow` 显示先提供 DTMF TwiML，再提供实时 TwiML，然后是已排队初始问候语的实时桥。 +- `googlemeet leave ` 会挂断委托的语音通话。 ## 故障排除 ### 智能体看不到 Google Meet 工具 -确认插件已在 Gateway 网关配置中启用，然后重新加载 Gateway 网关： +确认 Gateway 网关配置中已启用该插件，并重新加载 Gateway 网关： ```bash openclaw plugins list | grep google-meet @@ -1058,7 +1152,7 @@ openclaw googlemeet setup 如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到当前 Gateway 网关进程注册的插件工具。 -在非 macOS Gateway 网关主机上，面向智能体的 `google_meet` 工具仍然可见，但本地 Chrome 回传语音操作会在到达音频桥之前被阻止。本地 Chrome 回传音频当前依赖 macOS `BlackHole 2ch`，因此 Linux 智能体应使用 `mode: "transcribe"`、Twilio 拨入，或 macOS `chrome-node` 主机，而不是默认的本地 Chrome 智能体路径。 +在非 macOS Gateway 网关主机上，面向智能体的 `google_meet` 工具仍然可见，但本地 Chrome 回声发言动作会在到达音频桥之前被阻止。本地 Chrome 回声发言音频目前依赖 macOS `BlackHole 2ch`，因此 Linux 智能体应使用 `mode: "transcribe"`、Twilio 拨入或 macOS `chrome-node` 主机，而不是默认的本地 Chrome 智能体路径。 ### 没有已连接且支持 Google Meet 的节点 @@ -1079,7 +1173,7 @@ openclaw devices approve openclaw nodes status ``` -该节点必须已连接，并列出 `googlemeet.chrome` 和 `browser.proxy`。Gateway 网关配置必须允许这些节点命令： +节点必须已连接，并列出 `googlemeet.chrome` 以及 `browser.proxy`。Gateway 网关配置必须允许这些节点命令： ```json5 { @@ -1091,7 +1185,7 @@ openclaw nodes status } ``` -如果 `googlemeet setup` 的 `chrome-node-connected` 失败，或者 Gateway 网关日志报告 `gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启节点。对于 LAN Gateway 网关，这通常意味着： +如果 `googlemeet setup` 的 `chrome-node-connected` 失败，或 Gateway 网关日志报告 `gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启该节点。对于 LAN Gateway 网关，这通常意味着： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -1109,32 +1203,32 @@ openclaw googlemeet setup openclaw nodes status --connected ``` -### 浏览器已打开但智能体无法加入 +### 浏览器打开但智能体无法加入 -对仅观察加入运行 `googlemeet test-listen`，或对实时加入运行 `googlemeet test-speech`，然后检查返回的 Chrome 健康状态。如果任一探针报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并停止重试，直到浏览器操作完成。 +对仅观察加入运行 `googlemeet test-listen`，对实时加入运行 `googlemeet test-speech`，然后检查返回的 Chrome 健康状态。如果任一探测报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并停止重试，直到浏览器操作完成。 -常见手动操作： +常见的手动操作： -- 登录 Chrome 个人资料。 -- 从 Meet 主持人账号准入访客。 +- 登录 Chrome 配置文件。 +- 从 Meet 主持人账号批准访客加入。 - 当 Chrome 原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。 - 关闭或修复卡住的 Meet 权限对话框。 -不要仅仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告 “not signed in”。这是 Meet 的音频选择过渡页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真实会议状态。对于仅创建的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。 +不要仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。这是 Meet 的音频选择插页；可用时，OpenClaw 会通过浏览器自动化点击 **Use microphone**，并继续等待真实会议状态。对于仅创建的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。 ### 会议创建失败 -配置了 OAuth 凭证时，`googlemeet create` 会先使用 Google Meet API 的 `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认： +配置了 OAuth 凭证时，`googlemeet create` 会先使用 Google Meet API `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。确认： - 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在匹配的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。 -- 对于 API 创建：刷新令牌是在添加创建支持之后生成的。较旧的令牌可能缺少 `meetings.space.created` 作用域；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。 -- 对于浏览器回退：`defaultTransport: "chrome-node"` 且 `chromeNode.node` 指向一个已连接的节点，该节点具有 `browser.proxy` 和 `googlemeet.chrome`。 -- 对于浏览器回退：该节点上的 OpenClaw Chrome 个人资料已登录 Google，并且可以打开 `https://meet.google.com/new`。 -- 对于浏览器回退：重试会复用现有的 `https://meet.google.com/new` 或 Google 账号提示标签页，然后再打开新标签页。如果智能体超时，请重试工具调用，而不是手动打开另一个 Meet 标签页。 +- 对于 API 创建：刷新令牌是在添加创建支持之后签发的。较旧的令牌可能缺少 `meetings.space.created` 范围；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。 +- 对于浏览器回退：`defaultTransport: "chrome-node"` 且 `chromeNode.node` 指向一个已连接并具有 `browser.proxy` 和 `googlemeet.chrome` 的节点。 +- 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且可以打开 `https://meet.google.com/new`。 +- 对于浏览器回退：重试会在打开新标签页之前复用现有 `https://meet.google.com/new` 或 Google 账号提示标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。 - 对于浏览器回退：如果工具返回 `manualActionRequired: true`，请使用返回的 `browser.nodeId`、`browser.targetId`、`browserUrl` 和 `manualActionMessage` 指导操作员。在该操作完成之前，不要循环重试。 -- 对于浏览器回退：如果 Meet 显示 “Do you want people to hear you in the meeting?”，请保持标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或在仅创建回退时点击 **Continue without microphone**，并继续等待生成的 Meet URL。如果无法完成，错误应提到 `meet-audio-choice-required`，而不是 `google-login-required`。 +- 对于浏览器回退：如果 Meet 显示 “Do you want people to hear you in the meeting?”，请保持标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或对于仅创建的回退点击 **Continue without microphone**，并继续等待生成的 Meet URL。如果它无法完成，错误应提到 `meet-audio-choice-required`，而不是 `google-login-required`。 -### 智能体加入但不说话 +### 智能体已加入但不说话 检查实时路径： @@ -1143,33 +1237,33 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -对正常的 STT -> OpenClaw 智能体 -> TTS 回传语音路径使用 `mode: "agent"`，或对直接实时语音回退使用 `mode: "bidi"`。`mode: "transcribe"` 有意不会启动回传语音桥。对于仅观察调试，请在参与者发言后运行 `openclaw googlemeet status --json `，并检查 `captioning`、`transcriptLines` 和 `lastCaptionText`。如果 `inCall` 为 true 但 `transcriptLines` 仍为 `0`，Meet 字幕可能已禁用、观察器安装后没有人发言、Meet UI 已变更，或会议语言/账号无法使用实时字幕。 +对正常的 STT -> OpenClaw 智能体 -> TTS 回声发言路径使用 `mode: "agent"`，或对直接实时语音回退使用 `mode: "bidi"`。`mode: "transcribe"` 会有意不启动回声发言桥。对于仅观察调试，请在参与者发言后运行 `openclaw googlemeet status --json `，并检查 `captioning`、`transcriptLines` 和 `lastCaptionText`。如果 `inCall` 为 true，但 `transcriptLines` 保持为 `0`，可能是 Meet 字幕已禁用、自观察器安装以来没有人发言、Meet UI 已变更，或该会议语言/账号无法使用实时字幕。 -`googlemeet test-speech` 始终检查实时路径，并报告此次调用是否观察到桥输出字节。如果 `speechOutputVerified` 为 false 且 `speechOutputTimedOut` 为 true，实时提供商可能已接受话语，但 OpenClaw 没有看到新的输出字节到达 Chrome 音频桥。 +`googlemeet test-speech` 始终检查实时路径，并报告本次调用是否观察到桥输出字节。如果 `speechOutputVerified` 为 false 且 `speechOutputTimedOut` 为 true，实时提供商可能已接受话语，但 OpenClaw 未看到新的输出字节到达 Chrome 音频桥。 -另请验证： +还要验证： - Gateway 网关主机上可用实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 - Chrome 主机上可见 `BlackHole 2ch`。 - Chrome 主机上存在 `sox`。 - Meet 麦克风和扬声器通过 OpenClaw 使用的虚拟音频路径路由。对于本地 Chrome 实时加入，`doctor` 应显示 `meet output routed: yes`。 -`googlemeet doctor [session-id]` 会打印会话、节点、通话中状态、手动操作原因、实时提供商连接、`realtimeReady`、音频输入/输出活动、最近音频时间戳、字节计数器和浏览器 URL。需要原始 JSON 时，使用 `googlemeet status [session-id] --json`。需要在不暴露令牌的情况下验证 Google Meet OAuth 刷新时，使用 `googlemeet doctor --oauth`；如果还需要 Google Meet API 证明，请添加 `--meeting` 或 `--create-space`。 +`googlemeet doctor [session-id]` 会打印会话、节点、通话中状态、手动操作原因、实时提供商连接、`realtimeReady`、音频输入/输出活动、最后音频时间戳、字节计数器和浏览器 URL。当你需要原始 JSON 时，使用 `googlemeet status [session-id] --json`。当你需要验证 Google Meet OAuth 刷新且不暴露令牌时，使用 `googlemeet doctor --oauth`；当你还需要 Google Meet API 证明时，添加 `--meeting` 或 `--create-space`。 -如果智能体超时，而你能看到已经打开的 Meet 标签页，请检查该标签页，不要再打开另一个： +如果智能体超时且你能看到已经打开的 Meet 标签页，请检查该标签页，而不是再打开一个： ```bash openclaw googlemeet recover-tab openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` -等效的工具操作是 `recover_current_tab`。它会针对所选传输协议聚焦并检查现有 Meet 标签页。使用 `chrome` 时，它通过 Gateway 网关使用本地浏览器控制；使用 `chrome-node` 时，它使用已配置的 Chrome 节点。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行；`chrome-node` 还要求 Chrome 节点已连接。 +等效的工具动作是 `recover_current_tab`。它会聚焦并检查选定传输协议的现有 Meet 标签页。使用 `chrome` 时，它通过 Gateway 网关使用本地浏览器控制；使用 `chrome-node` 时，它使用已配置的 Chrome 节点。它不会打开新标签页或创建新会话；它会报告当前阻塞因素，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行；`chrome-node` 还要求 Chrome 节点已连接。 ### Twilio 设置检查失败 -当 `voice-call` 不被允许或未启用时，`twilio-voice-call-plugin` 会失败。将它添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 Gateway 网关。 +当不允许或未启用 `voice-call` 时，`twilio-voice-call-plugin` 会失败。将它添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，并重新加载 Gateway 网关。 -当 Twilio 后端缺少账号 SID、身份验证令牌或主叫号码时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置这些值： +当 Twilio 后端缺少账号 SID、认证令牌或呼叫方号码时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置这些变量： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1177,11 +1271,11 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -当 `voice-call` 没有公开 webhook 暴露，或 `publicUrl` 指向 loopback 或私有网络空间时，`twilio-voice-call-webhook` 会失败。将 `plugins.entries.voice-call.config.publicUrl` 设置为公共提供商 URL，或配置 `voice-call` 隧道/Tailscale 暴露。 +当 `voice-call` 没有公开 webhook 暴露，或 `publicUrl` 指向 loopback 或专用网络空间时，`twilio-voice-call-webhook` 会失败。将 `plugins.entries.voice-call.config.publicUrl` 设置为公开提供商 URL，或配置 `voice-call` 隧道/Tailscale 暴露。 -Loopback 和私有 URL 对运营商回调无效。不要将 `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`。 +Loopback 和专用 URL 不能用于运营商回调。不要将 `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`。 -对于稳定的公共 URL： +对于稳定的公开 URL： ```json5 { @@ -1200,7 +1294,7 @@ Loopback 和私有 URL 对运营商回调无效。不要将 `localhost`、`127.0 } ``` -对于本地开发，请使用隧道或 Tailscale 暴露，而不是私有主机 URL： +对于本地开发，请使用隧道或 Tailscale 暴露，而不是专用主机 URL： ```json5 { @@ -1226,21 +1320,21 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` 默认只检查就绪状态。要对特定号码进行试运行： +`voicecall smoke` 默认只检查就绪状态。要对特定号码进行演练： ```bash openclaw voicecall smoke --to "+15555550123" ``` -只有在你有意发起实时外拨通知电话时，才添加 `--yes`： +只有在你有意发起实时外拨通知通话时，才添加 `--yes`： ```bash openclaw voicecall smoke --to "+15555550123" --yes ``` -### Twilio 通话已开始但从未进入会议 +### Twilio 通话开始但从未进入会议 -确认 Meet 事件公开电话拨入详情。传入准确的拨入号码和 PIN，或自定义 DTMF 序列： +确认 Meet 事件公开电话拨入详情。传入精确的拨入号码和 PIN，或自定义 DTMF 序列： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1249,71 +1343,40 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -如果提供商在输入 PIN 前需要暂停，请在 `--dtmf-sequence` 中使用前导 `w` 或逗号。 +如果提供商需要在输入 PIN 前暂停，请在 `--dtmf-sequence` 中使用前导 `w` 或逗号。 -如果已创建电话呼叫，但 Meet 名单从未显示拨入参与者： +如果电话呼叫已创建，但 Meet 名单始终没有显示拨入参与者： -- 运行 `openclaw googlemeet doctor `，确认委派的 Twilio - 通话 ID、DTMF 是否已排队，以及是否已请求开场问候语。 -- 运行 `openclaw voicecall status --call-id `，确认通话仍处于 - 活跃状态。 -- 运行 `openclaw voicecall tail`，检查 Twilio webhook 是否正在到达 - Gateway 网关。 -- 运行 `openclaw logs --follow`，查找 Twilio Meet 序列：Google - Meet 委派加入，Voice Call 启动电话线路，Google Meet 等待 - `voiceCall.dtmfDelayMs`，使用 `voicecall.dtmf` 发送 DTMF，等待 - `voiceCall.postDtmfSpeechDelayMs`，然后使用 `voicecall.speak` 请求开场语音。 -- 重新运行 `openclaw googlemeet setup --transport twilio`；绿色设置检查是 - 必需的，但不能证明会议 PIN 序列正确。 +- 运行 `openclaw googlemeet doctor `，确认委派的 Twilio 呼叫 ID、DTMF 是否已排队，以及是否已请求开场问候语。 +- 运行 `openclaw voicecall status --call-id `，并确认呼叫仍处于活动状态。 +- 运行 `openclaw voicecall tail`，检查 Twilio webhook 是否到达 Gateway 网关。 +- 运行 `openclaw logs --follow`，查找 Twilio Meet 序列：Google Meet 委派加入，Voice Call 启动电话呼叫段，Google Meet 等待 `voiceCall.dtmfDelayMs`，通过 `voicecall.dtmf` 发送 DTMF，等待 `voiceCall.postDtmfSpeechDelayMs`，然后通过 `voicecall.speak` 请求开场语音。 +- 重新运行 `openclaw googlemeet setup --transport twilio`；绿色设置检查是必需的，但不能证明会议 PIN 序列正确。 - 确认拨入号码与 PIN 属于同一个 Meet 邀请和区域。 -- 如果 Meet 接听缓慢，或者通话转录在发送 DTMF 后仍显示要求输入 PIN 的提示， - 请增大 `voiceCall.dtmfDelayMs`。 -- 如果参与者已加入但你听不到问候语，请检查 - `openclaw logs --follow` 中 DTMF 后的 `voicecall.speak` 请求，以及 - 媒体流 TTS 播放或 Twilio `` 后备方案。如果通话转录仍包含 - “enter the meeting PIN”，说明电话线路尚未加入 Meet 房间，因此会议参与者听不到语音。 +- 如果 Meet 应答较慢，或呼叫转录在 DTMF 发送后仍显示要求输入 PIN 的提示，请增加 `voiceCall.dtmfDelayMs`。 +- 如果参与者已加入但你听不到问候语，请检查 `openclaw logs --follow` 中 DTMF 后的 `voicecall.speak` 请求，以及媒体流 TTS 播放或 Twilio `` 回退。如果呼叫转录中仍包含 “enter the meeting PIN”，则电话呼叫段尚未加入 Meet 房间，因此会议参与者不会听到语音。 -如果 webhook 没有到达，请先调试 Voice Call 插件：提供商必须能够 -访问 `plugins.entries.voice-call.config.publicUrl` 或已配置的隧道。 -参见 [Voice call 故障排除](/zh-CN/plugins/voice-call#troubleshooting)。 +如果 webhook 没有到达，请先调试 Voice Call 插件：提供商必须能够访问 `plugins.entries.voice-call.config.publicUrl` 或配置的隧道。 +请参阅 [Voice Call 故障排除](/zh-CN/plugins/voice-call#troubleshooting)。 ## 备注 -Google Meet 的官方媒体 API 以接收为主，因此要在 Meet -通话中说话仍然需要参与者路径。此插件让该边界保持可见： +Google Meet 的官方媒体 API 以接收为主，因此要在 Meet 呼叫中发言，仍然需要一条参与者路径。此插件会让这个边界保持可见： Chrome 处理浏览器参与和本地音频路由；Twilio 处理电话拨入参与。 -Chrome 回话模式需要 `BlackHole 2ch`，并搭配以下任一方式： +Chrome 回话模式需要 `BlackHole 2ch`，并且还需要以下之一： -- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有该 - 桥接，并在这些命令与所选提供商之间按 `chrome.audioFormat` 管道传输音频。 - 智能体模式使用实时转录加常规 TTS； - 双向模式使用实时语音提供商。默认 Chrome 路径是 24 kHz - PCM16，并设置 `chrome.audioBufferBytes: 4096`；8 kHz G.711 mu-law 仍可用于 - 旧版命令对。 -- `chrome.audioBridgeCommand`：外部桥接命令拥有整个本地 - 音频路径，并且必须在启动或验证其守护进程后退出。这只对 - `bidi` 有效，因为 `agent` 模式需要直接访问命令对来进行 TTS。 +- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有该桥接，并在这些命令与所选提供商之间以 `chrome.audioFormat` 管道传输音频。Agent 模式使用实时转录加常规 TTS；bidi 模式使用实时语音提供商。默认 Chrome 路径是 24 kHz PCM16，并设置 `chrome.audioBufferBytes: 4096`；8 kHz G.711 mu-law 仍可用于旧版命令对。 +- `chrome.audioBridgeCommand`：外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。这仅对 `bidi` 有效，因为 `agent` 模式需要直接访问命令对以进行 TTS。 -为了获得干净的双工音频，请通过单独的虚拟设备，或类似 Loopback 的虚拟设备图， -路由 Meet 输出和 Meet 麦克风。单个共享的 -BlackHole 设备可能会把其他参与者的声音回送到通话中。 +为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风路由到不同的虚拟设备，或路由到 Loopback 风格的虚拟设备图。单个共享的 BlackHole 设备可能会把其他参与者的声音回送到呼叫中。 -使用命令对 Chrome 桥接时，`chrome.bargeInInputCommand` 可以监听 -单独的本地麦克风，并在人开始说话时清除助手播放。 -即使共享的 BlackHole loopback 输入在助手播放期间被临时抑制， -这也能让人的语音优先于助手输出。与 `chrome.audioInputCommand` 和 -`chrome.audioOutputCommand` 一样，它是由操作员配置的本地命令。 -请使用显式的可信命令路径或参数列表，不要将它指向不受信任位置的脚本。 +使用命令对 Chrome 桥接时，`chrome.bargeInInputCommand` 可以监听单独的本地麦克风，并在人类开始说话时清除助手播放。即使共享的 BlackHole loopback 输入在助手播放期间被临时抑制，这也能让人类语音优先于助手输出。与 `chrome.audioInputCommand` 和 `chrome.audioOutputCommand` 一样，它是由操作员配置的本地命令。请使用显式的可信命令路径或参数列表，不要将其指向来自不受信任位置的脚本。 -`googlemeet speak` 会触发 Chrome 会话的活跃回话音频桥接。 -`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 -Twilio 会话，`leave` 还会挂断底层语音通话。 -当你还想关闭 API 管理空间中的活跃 Google Meet 会议时，请使用 -`googlemeet end-active-conference`。 +`googlemeet speak` 会触发 Chrome 会话的活动回话音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 也会挂断底层语音呼叫。当你还想关闭 API 管理空间的活动 Google Meet 会议时，请使用 `googlemeet end-active-conference`。 -## 相关 +## 相关内容 -- [Voice call 插件](/zh-CN/plugins/voice-call) +- [Voice Call 插件](/zh-CN/plugins/voice-call) - [通话模式](/zh-CN/nodes/talk) - [构建插件](/zh-CN/plugins/building-plugins) diff --git a/docs/zh-CN/plugins/voice-call.md b/docs/zh-CN/plugins/voice-call.md index 1ba5cbdbe..1dffae3da 100644 --- a/docs/zh-CN/plugins/voice-call.md +++ b/docs/zh-CN/plugins/voice-call.md @@ -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`（开发/无网络）。 -Voice Call 插件运行在 **Gateway 网关进程内**。如果你使用 -远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件， -然后重启 Gateway 网关以加载它。 +Voice Call 插件在 **Gateway 网关进程内部**运行。如果你使用远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件，然后重启 Gateway 网关以加载它。 ## 快速开始 - + - + ```bash openclaw plugins install @openclaw/voice-call ``` - + ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin openclaw plugins install "$PLUGIN_SRC" @@ -48,36 +42,29 @@ Voice Call 插件运行在 **Gateway 网关进程内**。如果你使用 - 使用裸包名以跟随当前官方发布标签。只有在需要可复现安装时， - 才固定到精确版本。 + 使用裸包名可跟随当前官方发布标签。只有在需要可复现安装时，才固定到精确版本。 - 随后重启 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`。 - + ```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 网关进程内**。如果你使用 -对于 Twilio、Telnyx 和 Plivo，设置必须解析到一个**公开 webhook URL**。 -如果 `publicUrl`、隧道 URL、Tailscale URL 或 serve 回退地址 -解析到 loopback 或私有网络空间，设置会失败，而不是启动一个 -无法接收运营商 webhook 的提供商。 +对于 Twilio、Telnyx 和 Plivo，设置必须解析为一个**公网 webhook URL**。如果 `publicUrl`、隧道 URL、Tailscale URL，或服务回退地址解析到 loopback 或私有网络空间，设置会失败，而不是启动一个无法接收运营商 webhook 的提供商。 ## 配置 -如果 `enabled: true` 但所选提供商缺少凭证， -Gateway 网关启动时会记录一条设置未完成警告，列出缺失键名， -并跳过启动运行时。命令、RPC 调用和智能体工具在使用时仍会 -返回精确缺失的提供商配置。 +如果 `enabled: true`，但所选提供商缺少凭证，Gateway 网关启动时会记录一条 setup-incomplete 警告，其中包含缺失键名，并跳过启动运行时。命令、RPC 调用和 agent 工具在使用时仍会返回精确缺失的提供商配置。 -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)。 ```json5 @@ -174,29 +155,25 @@ Voice Call 凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.a ``` - - - Twilio、Telnyx 和 Plivo 都需要一个**可公开访问**的 webhook URL。 + + - 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。 - + - `streaming.preStartTimeoutMs` 会关闭从未发送有效 `start` 帧的套接字。 - - `streaming.maxPendingConnections` 限制未经认证的预启动套接字总数。 - - `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未经认证预启动套接字数。 - - `streaming.maxConnections` 限制打开的媒体流套接字总数（待处理 + 活动）。 + - `streaming.maxPendingConnections` 限制未认证预启动套接字总数。 + - `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证预启动套接字数量。 + - `streaming.maxConnections` 限制打开的媒体流套接字总数（pending + active）。 - - 使用 `provider: "log"`、`twilio.from` 或旧版 - `streaming.*` OpenAI 键的较旧配置会由 `openclaw doctor --fix` 重写。 - 运行时回退目前仍会接受旧的 voice-call 键，但 - 重写路径是 `openclaw doctor --fix`，兼容垫片是 - 临时的。 + + 使用 `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 -## 会话作用域 +## 会话范围 -默认情况下，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` 分离，后者只会将音频转发给实时转写提供商。 -`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话请选择一种 -音频模式。 +`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话选择一种音频模式。 当前运行时行为： -- `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.` 下。 -- 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.` 下。 +- 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` 仍会透传给实时提供商。 | ### 实时提供商示例 - 默认值：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 -有关提供商特定的实时语音选项，请参阅 [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 会记录警告并跳过媒体流式传输，而不是让整个插件失败。 ### 流式传输提供商示例 @@ -392,9 +364,10 @@ Voice Call 凭证接受 SecretRefs。`plugins.entries.voice-call.config.twilio.a -## 通话的 TTS +## 通话 TTS -Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输出。你可以在插件配置下用**相同结构**覆盖它，它会与 `messages.tts` 深度合并。 +Voice Call 使用核心 `messages.tts` 配置为通话提供流式 +语音。你可以在插件配置下用**相同结构**覆盖它，它会与 `messages.tts` 深度合并。 ```json5 { @@ -411,22 +384,22 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输 ``` -**Microsoft speech 会被语音通话忽略。** 电话音频需要 PCM； -当前 Microsoft 传输协议未公开电话 PCM 输出。 +**Microsoft 语音会被语音通话忽略。** 电话音频需要 PCM； +当前 Microsoft 传输不公开电话 PCM 输出。 行为说明： - 插件配置中的旧版 `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: { @@ -440,7 +413,7 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输 } ``` - + ```json5 { plugins: { @@ -464,7 +437,7 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输 } ``` - + ```json5 { plugins: { @@ -490,7 +463,7 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输 ## 入站通话 -入站策略默认是 `disabled`。要启用入站通话，请设置： +入站策略默认值为 `disabled`。要启用入站通话，请设置： ```json5 { @@ -501,17 +474,29 @@ Voice Call 使用核心 `messages.tts` 配置来为通话进行流式语音输 ``` -`inboundPolicy: "allowlist"` 是低保障的来电号码筛选。该插件会规范化提供商提供的 `From` 值并将其与 `allowFrom` 比较。Webhook 验证会认证提供商投递和载荷完整性，但它**不能**证明 PSTN/VoIP 来电号码所有权。请将 `allowFrom` 视为来电号码过滤，而不是强来电身份认证。 +`inboundPolicy: "allowlist"` 是一种低保证的主叫号码筛选。 +插件会规范化提供商提供的 `From` 值，并将其与 +`allowFrom` 比较。Webhook 验证会认证提供商投递和 +负载完整性，但它**不能**证明 PSTN/VoIP 主叫号码 +所有权。请将 `allowFrom` 视为主叫号码过滤，而不是强主叫方 +身份验证。 -自动响应使用智能体系统。通过 `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 **不会**为该初始消息发布旧版 `` 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 { @@ -607,24 +598,26 @@ Voice Call 会以防御性方式提取语音文本： ## Webhook 安全 -当代理或隧道位于 Gateway 网关前方时，该插件会重建用于签名验证的公开 URL。这些选项控制哪些转发标头受信任： +当代理或隧道位于 Gateway 网关 前方时，插件 +会重建用于签名验证的公开 URL。这些选项 +控制信任哪些转发头： - 允许来自转发标头的主机名单。 + 来自转发头的主机 allowlist。 - 在没有允许名单的情况下信任转发标头。 + 在没有 allowlist 的情况下信任转发头。 - 仅当请求远程 IP 与列表匹配时才信任转发标头。 + 仅当请求远程 IP 与列表匹配时才信任转发头。 -其他防护： +其他保护： -- Twilio 和 Plivo 已启用 webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。 -- Twilio 对话轮次在 `` 回调中包含按轮次生成的令牌，因此过期/重放的语音回调无法满足较新的待处理转写轮次。 -- 当缺少提供商所需的签名标头时，未经认证的 webhook 请求会在读取正文之前被拒绝。 -- voice-call webhook 使用共享的预认证正文配置（64 KB / 5 秒），并在签名验证前加上按 IP 限制的进行中请求上限。 +- 已为 Twilio 和 Plivo 启用 Webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。 +- Twilio 会话轮次在 `` 回调中包含每轮 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 ` 指向不同的日志，并使用 `--last ` 将分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。 +`latency` 会从默认语音通话存储路径读取 `calls.jsonl`。使用 `--file ` 指向不同日志，使用 `--last ` 将分析限制为最后 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 通知模式外呼会在创建通话请求中直接发送其初始 `` TwiML，因此第一条语音消息不依赖 Twilio 获取 webhook TwiML。状态回调、对话通话、接通前 DTMF、实时流和接通后通话控制仍然需要公开 webhook。 +Twilio notify-mode 外呼会在创建通话请求中直接发送初始 `` 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) diff --git a/docs/zh-CN/providers/google.md b/docs/zh-CN/providers/google.md index a793de490..05c5d24c3 100644 --- a/docs/zh-CN/providers/google.md +++ b/docs/zh-CN/providers/google.md @@ -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/*`。 ## 入门指南 -选择你偏好的认证方式并按照设置步骤操作。 +选择你偏好的认证方式，并按照设置步骤操作。 - **最适合：**通过 Google AI Studio 进行标准 Gemini API 访问。 + **最适合：** 通过 Google AI Studio 进行标准 Gemini API 访问。 @@ -36,7 +37,7 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、 openclaw onboard --auth-choice gemini-api-key ``` - 或直接传入密钥： + 或者直接传入密钥： ```bash openclaw onboard --non-interactive \ @@ -64,21 +65,21 @@ Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、 - 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可以使用。使用你已经配置好的那个即可。 + 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可接受。使用你已经配置好的那个即可。 - **最适合：**通过 PKCE OAuth 复用现有 Gemini CLI 登录，而不是使用单独的 API key。 + **最适合：** 通过 PKCE OAuth 复用现有 Gemini CLI 登录，而不是使用单独的 API key。 - `google-gemini-cli` 提供商是非官方集成。一些用户报告以这种方式使用 OAuth 时遇到账户限制。请自行承担风险。 + `google-gemini-cli` 提供商是非官方集成。一些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。 - 本地 `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 提供图像生成、媒体理解（图像/音频/视频）、 - 如果浏览器流程开始前登录失败，请确保本地 `gemini` - 命令已安装并位于 `PATH` 上。 + 如果登录在浏览器流程开始前失败，请确保本地 `gemini` + 命令已安装并且在 `PATH` 上。 - `google-gemini-cli/*` 模型引用是旧版兼容别名。新的配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli` + `google-gemini-cli/*` 模型引用是旧版兼容别名。新的 + 配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli` 运行时。 @@ -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) 了解提供商特定的工具行为。 -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`。 @@ -217,16 +219,16 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw ``` -参见[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。 +请参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。 ## 视频生成 -内置的 `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 ``` -参见[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。 +请参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。 ## 音乐生成 -内置的 `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 ``` -参见[音乐生成](/zh-CN/tools/music-generation)，了解共享工具参数、提供商选择和故障转移行为。 +请参阅[音乐生成](/zh-CN/tools/music-generation)，了解共享工具参数、提供商选择和故障转移行为。 ## 文本转语音 -内置的 `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. ``` -限制为 Gemini API 的 Google Cloud Console API key 可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。 +限制为 Gemini API 的 Google Cloud Console API key 对此 +提供商有效。这不是单独的 Cloud Text-to-Speech API 路径。 ## 实时语音 -内置的 `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 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 路径上的语言代码提示。 Control UI Talk 支持使用受限一次性令牌的 Google Live 浏览器会话。 -仅后端实时语音提供商也可以通过通用 Gateway 网关中继传输运行， -这会将提供商凭证保留在 Gateway 网关上。 +仅后端的实时语音提供商也可以通过通用 Gateway 网关中继传输运行， +这样提供商凭据会保留在 Gateway 网关上。 对于维护者实时验证，请运行 `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`。 ## 高级配置 对于直接 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 - 使用 `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。 - 如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `GEMINI_API_KEY` - 可供该进程使用（例如，在 `~/.openclaw/.env` 中，或通过 + 如果 Gateway 网关作为守护进程（launchd/systemd）运行，请确保 `GEMINI_API_KEY` + 可用于该进程（例如，在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。