From 876be2fbf648fa2823a0729edee671bff7415ee7 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 1 May 2026 06:01:45 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/plugins/google-meet.md | 506 +++++++++++++++++------------- docs/zh-CN/plugins/voice-call.md | 353 +++++++++++++-------- 2 files changed, 506 insertions(+), 353 deletions(-) diff --git a/docs/zh-CN/plugins/google-meet.md b/docs/zh-CN/plugins/google-meet.md index 66091e2d0..195918f31 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 通话 - - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输协议 + - 你希望 OpenClaw 智能体加入 Google Meet 通话 + - 你希望 OpenClaw 智能体创建一个新的 Google Meet 通话 + - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输 summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确指定的 Meet URL，并使用实时语音默认设置 title: Google Meet 插件 x-i18n: - generated_at: "2026-05-01T05:44:27Z" + generated_at: "2026-05-01T05:59:30Z" model: gpt-5.5 provider: openai - source_hash: ad42eb664c3dcffe261c2bd7f5d8a3cd87a31e5a1b030d1a6f68c0259ffa53c6 + source_hash: 392628397ba7ae865110ee5589c0e7fc820f108f1611836d3fac8fb0ac994c46 source_path: plugins/google-meet.md workflow: 16 --- -Google Meet 参与者支持在 OpenClaw 中的设计是显式的： +Google Meet 参会者对 OpenClaw 的支持在设计上是显式的： - 它只会加入显式的 `https://meet.google.com/...` URL。 - 它可以通过 Google Meet API 创建新的 Meet 空间，然后加入返回的 URL。 - `realtime` 语音是默认模式。 - 当需要更深入的推理或工具时，实时语音可以回调完整的 OpenClaw 智能体。 -- 智能体使用 `mode` 选择加入行为：使用 `realtime` 进行实时听取/语音回复，或使用 `transcribe` 加入/控制浏览器而不启用实时语音桥接。 -- 凭证从个人 Google OAuth 或已登录的 Chrome 配置文件开始。 -- 不会自动发布同意声明。 -- 默认 Chrome 音频后端是 `BlackHole 2ch`。 -- Chrome 可以在本地运行，也可以在已配对的节点主机上运行。 -- Twilio 接受拨入号码以及可选 PIN 或 DTMF 序列。 -- CLI 命令是 `googlemeet`；`meet` 保留给更广义的智能体电话会议工作流。 +- 智能体通过 `mode` 选择加入行为：使用 `realtime` 进行实时监听/语音回复，或使用 `transcribe` 加入/控制浏览器而不启用实时语音桥接。 +- 身份验证从个人 Google OAuth 或已登录的 Chrome 配置文件开始。 +- 没有自动同意公告。 +- 默认的 Chrome 音频后端是 `BlackHole 2ch`。 +- Chrome 可以在本地运行，也可以在配对的节点主机上运行。 +- Twilio 接受拨入号码，以及可选的 PIN 或 DTMF 序列。 +- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体电话会议工作流。 ## 快速开始 -安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认值；Google Gemini Live 也可与 `realtime.provider: "google"` 配合使用： +安装本地音频依赖并配置后端实时语音提供商。OpenAI 是默认值；Google Gemini Live 也可通过 `realtime.provider: "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,13 +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 时，始终显式预检该传输： + +```bash +openclaw googlemeet setup --transport twilio +``` + +这会在智能体尝试拨入会议之前，捕获缺失的 `voice-call` 接线、Twilio 凭据或无法访问的 webhook 暴露。 加入会议： @@ -112,13 +120,14 @@ 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，用实时语音加入，并把链接发给我。”智能体应调用 `google_meet`，使用 `action: "create"`，然后分享返回的 `meetingUri`。 ```json { @@ -128,19 +137,19 @@ openclaw googlemeet create --no-join } ``` -对于仅观察/浏览器控制加入，请设置 `"mode": "transcribe"`。这不会启动双工实时模型桥接，不需要 BlackHole 或 SoX，也不会向会议中语音回复。此模式下的 Chrome 加入还会避免 OpenClaw 的麦克风/摄像头权限授予，并避免 Meet **使用麦克风** 路径。如果 Meet 显示音频选择插页，自动化会尝试无麦克风路径，否则会报告需要手动操作，而不是打开本地麦克风。 +对于仅观察/浏览器控制加入，设置 `"mode": "transcribe"`。这不会启动双工实时模型桥接，不需要 BlackHole 或 SoX，也不会在会议中语音回复。此模式下的 Chrome 加入还会避开 OpenClaw 的麦克风/摄像头权限授予，并避开 Meet 的 **使用麦克风** 路径。如果 Meet 显示音频选择插页，自动化会尝试无麦克风路径，否则会报告需要手动操作，而不是打开本地麦克风。 -在实时会话期间，`google_meet` Status 包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数器以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可行时处理它。登录、主持人准入以及浏览器/OS 权限提示会作为手动操作报告，并附带原因和消息，供智能体转述。托管 Chrome 会话只会在浏览器健康状态报告 `inCall: true` 后发出介绍或测试短语；否则 Status 会报告 `speechReady: false`，并阻止发声尝试，而不是假装智能体已经在会议中发言。 +实时会话期间，`google_meet` Status 包含浏览器和音频桥接健康状态，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数器以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可行时处理它。登录、主持人准入以及浏览器/OS 权限提示会作为需要手动操作报告，并带有原因和消息，供智能体转述。托管 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 内运行完整的 Gateway 网关或配置模型 API key。在本地运行 Gateway 网关和智能体，然后在 VM 中运行节点主机。在 VM 上启用一次内置插件，使该节点发布 Chrome 命令： -各处运行的内容： +各位置运行的内容： -- Gateway 网关主机：OpenClaw Gateway 网关、Agent 工作区、模型/API key、实时提供商，以及 Google Meet 插件配置。 +- Gateway 网关主机：Gateway 网关、智能体工作区、模型/API key、实时提供商，以及 Google Meet 插件配置。 - Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及已登录 Google 的 Chrome 配置文件。 - VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT key，或模型提供商设置。 @@ -156,7 +165,7 @@ brew install blackhole-2ch sox sudo reboot ``` -重启后，验证 VM 能看到音频设备和 SoX 命令： +重启后，验证 VM 可以看到音频设备和 SoX 命令： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -175,14 +184,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 \ @@ -190,16 +199,16 @@ 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 网关主机批准节点： +从 Gateway 网关主机批准该节点： ```bash openclaw devices list openclaw devices approve ``` -确认 Gateway 网关能看到节点，并且节点通告了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`： +确认 Gateway 网关能看到该节点，并且它发布了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`： ```bash openclaw nodes status @@ -241,81 +250,57 @@ openclaw nodes status openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -或要求智能体使用 `google_meet` 工具并设置 `transport: "chrome-node"`。 +或要求智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。 -如需一个单命令冒烟测试来创建或复用会话、说出已知短语并打印会话健康状态： +对于一次性冒烟测试，用一个命令创建或复用会话、说出已知短语并打印会话健康状态： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -在实时加入期间，OpenClaw 浏览器自动化会填写访客名称，点击加入/请求加入，并在 Meet 首次运行的“使用麦克风”选项出现时接受它。在仅观察加入或仅浏览器创建会议期间，当可用时，它会在不使用麦克风的情况下继续通过相同提示。如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要实时加入的麦克风/摄像头权限，或 Meet 卡在自动化无法解决的提示上，加入/test-speech 结果会报告 `manualActionRequired: true`，并附带 `manualActionReason` 和 `manualActionMessage`。智能体应停止重试加入，报告该确切消息以及当前的 `browserUrl`/`browserTitle`，并且仅在手动浏览器操作完成后重试。 +实时加入期间，OpenClaw 浏览器自动化会填写访客名称，点击加入/请求加入，并在 Meet 首次运行的“使用麦克风”选项出现时接受它。在仅观察加入或仅浏览器创建会议期间，如果可用，它会在不使用麦克风的情况下继续通过相同提示。如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要实时加入所需的麦克风/摄像头权限，或 Meet 卡在自动化无法解决的提示上，加入/`test-speech` 结果会报告 `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 虚拟音频驱动。它会创建 `BlackHole 2ch` - 音频设备，供 Chrome/Meet 路由音频。 +- `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`，加入会以设置错误失败，而不是在没有音频路径的情况下静默加入。 +将 Chrome 麦克风和扬声器音频通过本地 OpenClaw 音频桥接路由。如果未安装 `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 节点上启用： +在 Gateway 网关主机上启用 Voice Call 插件，而不是在 Chrome 节点上： ```json5 { @@ -340,7 +325,7 @@ Twilio 传输方式是委托给 Voice Call 插件的严格拨号计划。它不 } ``` -通过环境或配置提供 Twilio 凭据。环境变量可避免密钥进入 `openclaw.json`： +通过环境或配置提供 Twilio 凭证。环境变量可避免将密钥放入 `openclaw.json`： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -348,7 +333,7 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -启用 `voice-call` 后重启或重新加载 Gateway 网关；插件配置更改在重新加载前不会出现在已运行的 Gateway 网关进程中。 +启用 `voice-call` 后重启或重新加载 Gateway 网关；插件配置变更在重新加载前不会出现在已运行的 Gateway 网关进程中。 然后验证： @@ -358,9 +343,7 @@ 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 \ @@ -369,7 +352,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -当会议需要自定义序列时使用 `--dtmf-sequence`： +当会议需要自定义序列时，使用 `--dtmf-sequence`： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -382,21 +365,20 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ OAuth 对创建 Meet 链接是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你需要官方 API 创建、空间解析或 Meet Media API 预检检查时，请配置 OAuth。 -Google Meet API 访问使用用户 OAuth：创建 Google Cloud OAuth 客户端，请求所需 scope，授权一个 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 项目。 2. 为该项目启用 **Google Meet REST API**。 3. 配置 OAuth 同意屏幕。 - - 对 Google Workspace 组织来说，**Internal** 最简单。 + - **Internal** 对 Google Workspace 组织最简单。 - **External** 适用于个人/测试设置；当应用处于 Testing 状态时，将每个会授权该应用的 Google 账号添加为测试用户。 -4. 添加 OpenClaw 请求的 scope： +4. 添加 OpenClaw 请求的范围： - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` @@ -410,19 +392,17 @@ OAuth 不会替代 Chrome 加入路径。使用浏览器参与时，Chrome 和 C 6. 复制客户端 ID 和客户端密钥。 -Google Meet `spaces.create` 需要 `meetings.space.created`。 -`meetings.space.readonly` 让 OpenClaw 可以将 Meet URL/代码解析为空间。 -`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体工作；Google 可能要求为实际 Media API 使用加入 Developer Preview。如果你只需要基于浏览器的 Chrome 加入，请完全跳过 OAuth。 +Google Meet `spaces.create` 需要 `meetings.space.created`。`meetings.space.readonly` 允许 OpenClaw 将 Meet URL/代码解析为空间。`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体工作；Google 可能要求加入 Developer Preview 才能实际使用 Media API。如果你只需要基于浏览器的 Chrome 加入，请完全跳过 OAuth。 ### 生成刷新令牌 -配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，或将它们作为环境变量传入，然后运行： +配置 `oauth.clientId` 和可选的 `oauth.clientSecret`，或将它们作为环境变量传入，然后运行： ```bash openclaw googlemeet auth login --json ``` -该命令会打印包含刷新令牌的 `oauth` 配置块。它使用 PKCE、`http://localhost:8085/oauth2callback` 上的 localhost 回调，以及通过 `--manual` 进行的手动复制/粘贴流程。 +该命令会打印一个包含刷新令牌的 `oauth` 配置块。它使用 PKCE、`http://localhost:8085/oauth2callback` 上的 localhost 回调，以及带有 `--manual` 的手动复制/粘贴流程。 示例： @@ -432,7 +412,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -当浏览器无法访问本地回调时使用手动模式： +当浏览器无法访问本地回调时，使用手动模式： ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -455,7 +435,7 @@ JSON 输出包含： } ``` -将 `oauth` 对象存储到 Google Meet 插件配置下： +将 `oauth` 对象存储在 Google Meet 插件配置下： ```json5 { @@ -476,54 +456,50 @@ JSON 输出包含： } ``` -如果你不希望刷新令牌出现在配置中，请优先使用环境变量。如果配置和环境值同时存在，插件会先解析配置，然后回退到环境。 +如果你不想将刷新令牌放入配置，请优先使用环境变量。如果配置和环境值同时存在，插件会先解析配置，然后再回退到环境。 -OAuth 同意包含 Meet 空间创建、Meet 空间读取访问，以及 Meet 会议媒体读取访问。如果你在会议创建支持出现前已完成身份验证，请重新运行 -`openclaw googlemeet auth login --json`，使刷新令牌具备 -`meetings.space.created` scope。 +OAuth 同意包含 Meet 空间创建、Meet 空间读取访问权限，以及 Meet 会议媒体读取访问权限。如果你在会议创建支持存在前已完成身份验证，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌拥有 `meetings.space.created` 范围。 ### 使用 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` scope，请运行会产生副作用的创建检查： +如果还要证明 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` scope 时使用它。 +`--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 已禁用、已同意的刷新令牌缺少所需 scope，或 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 +516,13 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij 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,9 +530,10 @@ 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 查找可以先从 Google Calendar 解析会议 URL，再读取 Meet 产物： ```bash openclaw googlemeet latest --today @@ -565,9 +542,11 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 Calendar 事件。使用 `--event ` 搜索匹配的事件文本，并使用 `--calendar ` 指定非主日历。日历查找需要一次包含 Calendar events readonly scope 的新 OAuth 登录。`calendar-events` 会预览匹配的 Meet 事件，并标记 `latest`、`artifacts`、`attendance` 或 `export` 将选择的事件。 +`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 Calendar 事件。 +使用 `--event ` 搜索匹配的事件文本，使用 `--calendar ` 指定非主日历。Calendar 查找需要一次包含 Calendar events 只读作用域的全新 OAuth 登录。 +`calendar-events` 会预览匹配的 Meet 事件，并标记 `latest`、`artifacts`、`attendance` 或 `export` 将选择的事件。 -如果你已经知道会议记录 ID，可以直接引用它： +如果你已经知道会议记录 ID，可以直接指定它： ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -575,7 +554,7 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -写入可读报告： +写入一份可读报告： ```bash openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \ @@ -590,9 +569,11 @@ 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` 可调整提前离开检测。 +当 Google 为该会议公开数据时，`artifacts` 会返回会议记录元数据，以及参与者、录制、转录、结构化转录条目和智能笔记资源元数据。使用 `--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 文本；这需要一次包含 Drive Meet readonly scope 的新 OAuth 登录。如果不使用 `--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 文本；这需要一次包含 Drive Meet 只读作用域的全新 OAuth 登录。不使用 `--include-doc-bodies` 时，导出只包含 Meet 元数据和结构化转录条目。如果 Google 返回部分产物失败，例如智能笔记列表、转录条目或 Drive 文档正文错误，摘要和清单会保留警告，而不是让整个导出失败。 +使用 `--dry-run` 可获取相同的产物/出席数据并打印清单 JSON，而不创建文件夹或 ZIP。这适合在写入大型导出之前使用，或在智能体只需要计数、所选记录和警告时使用。 智能体也可以通过 `google_meet` 工具创建相同的包： @@ -606,9 +587,9 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ } ``` -设置 `"dryRun": true` 可仅返回导出清单并跳过文件写入。 +设置 `"dryRun": true` 可只返回导出清单并跳过文件写入。 -针对真实保留会议运行受保护的实时冒烟测试： +针对一个真实保留的会议运行受保护的实时冒烟测试： ```bash OPENCLAW_LIVE_TEST=1 \ @@ -619,22 +600,33 @@ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts 实时冒烟测试环境： - `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 + 客户端 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 空间： +创建一个新的 Meet 空间： ```bash 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 { @@ -654,7 +646,7 @@ openclaw googlemeet create } ``` -如果浏览器后备在创建 URL 前遇到 Google 登录或 Meet 权限阻断，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化详情，而不是纯字符串： +如果浏览器回退在创建 URL 前遇到 Google 登录或 Meet 权限阻断，Gateway 网关方法会返回失败响应，`google_meet` 工具会返回结构化详情，而不是纯字符串： ```json { @@ -672,9 +664,11 @@ openclaw googlemeet create } ``` -当智能体看到 `manualActionRequired: true` 时，应报告 `manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成浏览器步骤。 +当智能体看到 `manualActionRequired: true` 时，它应报告 +`manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 +Meet 标签页，直到操作员完成浏览器步骤。 -来自 API 创建的示例 JSON 输出： +API 创建的 JSON 输出示例： ```json { @@ -695,13 +689,13 @@ openclaw googlemeet create } ``` -创建 Meet 默认会加入会议。Chrome 或 Chrome 节点传输仍需要已登录的 Google Chrome 配置文件才能通过浏览器加入。如果配置文件已退出登录，OpenClaw 会报告 `manualActionRequired: true` 或浏览器后备错误，并要求操作员完成 Google 登录后重试。 +创建 Meet 默认会加入会议。Chrome 或 Chrome 节点传输仍需要已登录的 Google Chrome 配置文件，才能通过浏览器加入。如果配置文件已登出，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员完成 Google 登录后再重试。 -仅在确认你的 Cloud 项目、OAuth 主体和会议参与者已注册 Google Workspace Developer Preview Program for Meet media APIs 后，才设置 `preview.enrollmentAcknowledged: true`。 +仅在确认你的 Cloud 项目、OAuth 主体和会议参与者均已加入适用于 Meet 媒体 API 的 Google Workspace Developer Preview Program 后，才设置 `preview.enrollmentAcknowledged: true`。 ## 配置 -常见的 Chrome 实时路径只需要启用插件、BlackHole、SoX 和一个后端实时语音提供商密钥。OpenAI 是默认值；设置 `realtime.provider: "google"` 可使用 Google Gemini Live： +常见的 Chrome 实时路径只需要启用插件、BlackHole、SoX，以及一个后端实时语音提供商密钥。OpenAI 是默认值；设置 `realtime.provider: "google"` 可使用 Google Gemini Live： ```bash brew install blackhole-2ch sox @@ -731,20 +725,22 @@ export GEMINI_API_KEY=... - `defaultMode: "realtime"` - `chromeNode.node`：用于 `chrome-node` 的可选节点 ID/名称/IP - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`：在已退出登录的 Meet 访客屏幕上使用的名称 +- `chrome.guestName: "OpenClaw Agent"`：在已登出的 Meet 访客屏幕上使用的名称 - `chrome.autoJoin: true`：通过 `chrome-node` 上的 OpenClaw 浏览器自动化，尽力填写访客名称并点击 Join Now - `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页 -- `chrome.waitForInCallMs: 20000`：在触发实时介绍前，等待 Meet 标签页报告已在通话中 -- `chrome.audioFormat: "pcm16-24khz"`：命令对音频格式。仅对仍输出电话音频的旧版/自定义命令对使用 `"g711-ulaw-8khz"`。 +- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已在通话中，然后触发实时开场 +- `chrome.audioFormat: "pcm16-24khz"`：命令对音频格式。仅对仍然输出电话音频的旧版/自定义命令对使用 + `"g711-ulaw-8khz"`。 - `chrome.audioInputCommand`：从 CoreAudio `BlackHole 2ch` 读取并以 `chrome.audioFormat` 写入音频的 SoX 命令 - `chrome.audioOutputCommand`：以 `chrome.audioFormat` 读取音频并写入 CoreAudio `BlackHole 2ch` 的 SoX 命令 - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`：简短口头回复，使用 `openclaw_agent_consult` 获取更深入的回答 -- `realtime.introMessage`：实时桥接连接时的简短口头就绪检查；将其设置为 `""` 可静默加入 +- `realtime.instructions`：简短口语回复，并使用 + `openclaw_agent_consult` 获取更深入的回答 +- `realtime.introMessage`：实时桥接连接时的简短口语就绪检查；将其设置为 `""` 可静默加入 - `realtime.agentId`：用于 `openclaw_agent_consult` 的可选 OpenClaw 智能体 ID；默认值为 `main` -可选覆盖： +可选覆盖项： ```json5 { @@ -791,7 +787,7 @@ export GEMINI_API_KEY=... } ``` -`voiceCall.enabled` 默认值为 `true`；使用 Twilio 传输时，它会将实际 PSTN 呼叫和 DTMF 委托给 Voice Call 插件。如果 `voice-call` 未启用，Google Meet 仍可验证并记录拨号计划，但无法发起 Twilio 呼叫。 +`voiceCall.enabled` 默认值为 `true`；使用 Twilio 传输时，它会将实际 PSTN 呼叫和 DTMF 委托给 Voice Call 插件。如果未启用 `voice-call`，Google Meet 仍可验证并记录拨号计划，但无法发起 Twilio 呼叫。 ## 工具 @@ -806,20 +802,21 @@ export GEMINI_API_KEY=... } ``` -当 Chrome 在 Gateway 网关主机上运行时，使用 `transport: "chrome"`。当 Chrome 在配对节点（例如 Parallels VM）上运行时，使用 -`transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都在 Gateway 网关主机上运行，因此模型凭证会保留在那里。 +当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在配对节点（例如 Parallels VM）上时，使用 +`transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 +Gateway 网关主机上，因此模型凭证会保留在那里。 -使用 `action: "status"` 列出活动会话或检查会话 ID。使用 -`action: "speak"` 搭配 `sessionId` 和 `message`，让实时智能体立即说话。使用 `action: "test_speech"` 创建或复用会话、触发一个已知短语，并在 Chrome 主机可以报告时返回 `inCall` 健康状态。`test_speech` 始终强制使用 `mode: "realtime"`，如果被要求以 `mode: "transcribe"` 运行则会失败，因为仅观察会话有意不能发出语音。它的 `speechOutputVerified` 结果基于本次测试调用期间实时音频输出字节数的增加，因此复用的会话中较早的音频不会被计为新的成功语音检查。使用 `action: "leave"` 将会话标记为已结束。 +使用 `action: "status"` 列出活动会话，或检查某个会话 ID。使用 +`action: "speak"` 搭配 `sessionId` 和 `message`，让实时智能体立即发言。使用 `action: "test_speech"` 创建或复用会话、触发一句已知短语，并在 Chrome 主机能够报告时返回 `inCall` 健康状态。`test_speech` 始终强制使用 `mode: "realtime"`，如果要求它以 `mode: "transcribe"` 运行则会失败，因为仅观察会话有意不能发出语音。它的 `speechOutputVerified` 结果基于本次测试调用期间实时音频输出字节数是否增加，因此复用会话中的旧音频不会被计为一次新的成功语音检查。使用 `action: "leave"` 将会话标记为已结束。 `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`：最近一次从桥接收到或发送到桥的音频时间 +- `lastInputAt` / `lastOutputAt`：桥接端最近一次收到或发送音频的时间 ```json { @@ -833,26 +830,27 @@ export GEMINI_API_KEY=... Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会听取会议音频，并通过配置的音频桥发声。当实时模型需要更深入的推理、当前信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 -咨询工具会在幕后运行常规 OpenClaw 智能体，带上最近的会议转录上下文，并向实时语音会话返回简短的口语回答。随后语音模型可以把该回答说回会议中。它使用与 Voice Call 相同的共享实时咨询工具。 +咨询工具会在后台运行常规 OpenClaw 智能体，携带近期会议转录上下文，并向实时语音会话返回一条简洁的口播答案。语音模型随后可以把该答案说回会议中。它使用与 Voice Call 相同的共享实时咨询工具。 -默认情况下，咨询会针对 `main` 智能体运行。当某条 Meet 通道应咨询专用 OpenClaw Agent 工作区、模型默认值、工具策略、记忆和会话历史时，设置 `realtime.agentId`。 +默认情况下，咨询会针对 `main` 智能体运行。当某个 Meet 通道应咨询专用的 OpenClaw 智能体工作区、模型默认值、工具策略、记忆和会话历史时，设置 `realtime.agentId`。 `realtime.toolPolicy` 控制咨询运行： -- `safe-read-only`：暴露咨询工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 +- `safe-read-only`：暴露咨询工具，并将常规智能体限制为 + `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 -- `owner`：暴露咨询工具，并允许常规智能体使用正常的智能体工具策略。 +- `owner`：暴露咨询工具，并让常规智能体使用正常的智能体工具策略。 - `none`：不要向实时语音模型暴露咨询工具。 -咨询会话键按每个 Meet 会话限定范围，因此在同一场会议期间，后续咨询调用可以复用之前的咨询上下文。 +咨询会话键按每个 Meet 会话限定作用域，因此后续咨询调用可以在同一次会议期间复用之前的咨询上下文。 -要在 Chrome 完全加入通话后强制执行语音就绪检查： +要在 Chrome 完全加入通话后强制执行口播就绪检查： ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -完整的加入并说话冒烟测试： +完整的加入并发声冒烟测试： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -862,7 +860,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## 实时测试清单 -在将会议交给无人值守的智能体之前，使用以下顺序： +在把会议交给无人值守智能体之前，使用以下顺序： ```bash openclaw googlemeet setup @@ -872,15 +870,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`。 +- 当 Chrome-node 是默认传输协议或固定了某个节点时，`googlemeet setup` 包含 `chrome-node-connected`。 - `nodes status` 显示所选节点已连接。 -- 所选节点同时公布 `googlemeet.chrome` 和 `browser.proxy`。 -- Meet 标签页加入通话，且 `test-speech` 返回包含 `inCall: true` 的 Chrome 健康状态。 +- 所选节点同时通告 `googlemeet.chrome` 和 `browser.proxy`。 +- Meet 标签页加入通话，并且 `test-speech` 返回包含 `inCall: true` 的 Chrome 健康状态。 -对于远程 Chrome 主机（例如 Parallels macOS VM），这是更新 Gateway 网关或 VM 之后最短的安全检查： +对于远程 Chrome 主机（例如 Parallels macOS VM），这是更新 Gateway 网关或 VM 后最短的安全检查： ```bash openclaw googlemeet setup @@ -891,9 +889,9 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -这可以证明 Gateway 网关插件已加载、VM 节点已使用当前令牌连接，并且在智能体打开真实会议标签页之前，Meet 音频桥可用。 +这会证明 Gateway 网关插件已加载，VM 节点已使用当前令牌连接，并且在智能体打开真实会议标签页之前，Meet 音频桥可用。 -对于 Twilio 冒烟测试，使用公开电话拨入详情的会议： +对于 Twilio 冒烟测试，请使用公开电话拨入详情的会议： ```bash openclaw googlemeet setup @@ -903,10 +901,10 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -预期的 Twilio 状态： +预期 Twilio 状态： - `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 `twilio-voice-call-webhook` 检查。 -- Gateway 网关重新加载后，`voicecall` 可在 CLI 中使用。 +- Gateway 网关重新加载后，CLI 中可用 `voicecall`。 - 返回的会话包含 `transport: "twilio"` 和 `twilio.voiceCallId`。 - `googlemeet leave ` 会挂断委托的语音通话。 @@ -921,7 +919,7 @@ openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -如果你刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到当前 Gateway 网关进程注册的插件工具。 +如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到当前 Gateway 网关进程注册的插件工具。 ### 没有已连接且支持 Google Meet 的节点 @@ -954,8 +952,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 \ @@ -966,41 +963,40 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -然后重新加载节点服务并重新运行： +然后重新加载节点服务并再次运行： ```bash openclaw googlemeet setup openclaw nodes status --connected ``` -### 浏览器已打开，但智能体无法加入 +### 浏览器已打开但智能体无法加入 运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并在浏览器操作完成前停止重试。 -常见的手动操作： +常见手动操作： - 登录 Chrome 配置文件。 - 从 Meet 主持人账号准入访客。 -- 当 Chrome 的原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。 +- 当 Chrome 原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。 - 关闭或修复卡住的 Meet 权限对话框。 -不要仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。这是 Meet 的音频选择中间页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真实会议状态。对于仅创建的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。 +不要仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告 “not signed in”。这是 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` 和 +- 对于 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` 和 +- 对于浏览器后备路径：该节点上的 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`。 ### 智能体已加入但不说话 @@ -1011,35 +1007,35 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -使用 `mode: "realtime"` 进行监听/回话。`mode: "transcribe"` 有意不会启动双工实时语音桥。`googlemeet test-speech` 始终检查实时路径，并报告在该次调用中是否观察到桥输出字节。如果 `speechOutputVerified` 为 false 且 -`speechOutputTimedOut` 为 true，则实时提供商可能已经接受了语句，但 OpenClaw 没有看到新的输出字节到达 Chrome 音频桥。 +使用 `mode: "realtime"` 进行监听/回话。`mode: "transcribe"` 有意不会启动双工实时语音桥。`googlemeet test-speech` 始终检查实时路径，并报告本次调用是否观察到桥接输出字节。如果 `speechOutputVerified` 为 false 且 +`speechOutputTimedOut` 为 true，则实时提供商可能已经接受了发言内容，但 OpenClaw 没有看到新的输出字节到达 Chrome 音频桥。 还要验证： - Gateway 网关主机上可用实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 - `BlackHole 2ch` 在 Chrome 主机上可见。 -- Chrome 主机上存在 `sox`。 -- Meet 麦克风和扬声器已通过 OpenClaw 使用的虚拟音频路径路由。 +- `sox` 存在于 Chrome 主机上。 +- Meet 麦克风和扬声器通过 OpenClaw 使用的虚拟音频路径路由。 -`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 设置检查失败 -`twilio-voice-call-plugin` 会在不允许或未启用 `voice-call` 时失败。 -将它添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 +`twilio-voice-call-plugin` 会在 `voice-call` 未被允许或未启用时失败。 +将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 Gateway 网关。 `twilio-voice-call-credentials` 会在 Twilio 后端缺少账号 -SID、auth token 或主叫号码时失败。在 Gateway 网关主机上设置这些项： +SID、身份验证令牌或主叫号码时失败。在 Gateway 网关主机上设置这些内容： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1048,34 +1044,75 @@ export TWILIO_FROM_NUMBER=+15550001234 ``` `twilio-voice-call-webhook` 会在 `voice-call` 没有公开 webhook -暴露，或 `publicUrl` 指向回环地址或私有网络地址空间时失败。 -将 `plugins.entries.voice-call.config.publicUrl` 设置为公开的提供商 URL，或 +暴露，或 `publicUrl` 指向回环或私有网络空间时失败。 +将 `plugins.entries.voice-call.config.publicUrl` 设置为公开提供商 URL，或 配置一个 `voice-call` 隧道/Tailscale 暴露。 -然后重启或重新加载 Gateway 网关并运行： +回环和私有 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： + +```json5 +{ + plugins: { + entries: { + "voice-call": { + enabled: true, + config: { + provider: "twilio", + fromNumber: "+15550001234", + publicUrl: "https://voice.example.com/voice/webhook", + }, + }, + }, + }, +} +``` + +对于本地开发，请使用隧道或 Tailscale 暴露，而不是私有 +主机 URL： + +```json5 +{ + plugins: { + entries: { + "voice-call": { + config: { + tunnel: { provider: "ngrok" }, + // or + tailscale: { mode: "funnel", path: "/voice/webhook" }, + }, + }, + }, + }, +} +``` + +然后重启或重新加载 Gateway 网关，并运行： ```bash -openclaw googlemeet setup +openclaw googlemeet setup --transport twilio 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 事件暴露了电话拨入详情。传入准确的拨入 +确认 Meet 事件公开了电话拨入详情。传入准确的拨入 号码和 PIN，或自定义 DTMF 序列： ```bash @@ -1085,33 +1122,52 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -如果提供商需要在输入 PIN 前暂停，请在 `--dtmf-sequence` 中使用前导 `w` 或逗号。 +如果提供商在输入 PIN 前需要暂停，请在 `--dtmf-sequence` 中使用前导 `w` 或逗号。 + +如果电话通话已创建，但 Meet 名单中始终没有显示拨入 +参与者： + +- 运行 `openclaw voicecall status --call-id `，并确认通话仍处于 + 活跃状态。 +- 运行 `openclaw voicecall tail`，并检查 Twilio webhook 是否正在到达 + Gateway 网关。 +- 重新运行 `openclaw googlemeet setup --transport twilio`；绿色的设置检查是 + 必需的，但不能证明会议 PIN 序列正确。 +- 确认拨入号码与 PIN 属于同一个 Meet 邀请和区域。 +- 如果 Meet 接听较慢，请增加 `--dtmf-sequence` 中的前导暂停，例如 + `wwww123456#`。 +- 如果参与者已加入，但你错过了第一句语音，请增加 + `plugins.entries.google-meet.config.voiceCall.postDtmfSpeechDelayMs`，让 + 开场语音在 Meet 完成电话参与者准入后再播放。 + +如果 webhook 没有到达，请先调试 Voice Call 插件：提供商必须 +能够访问 `plugins.entries.voice-call.config.publicUrl` 或已配置的隧道。 +请参阅[语音通话故障排除](/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` 管道传输音频。默认 Chrome 路径为 + 实时模型桥接，并在这些命令与所选实时语音提供商之间以 + `chrome.audioFormat` 传送音频。默认 Chrome 路径为 24 kHz PCM16；8 kHz G.711 mu-law 仍可用于旧版命令对。 - `chrome.audioBridgeCommand`：外部桥接命令拥有整个本地 音频路径，并且必须在启动或验证其守护进程后退出。 -要获得清晰的双工音频，请通过独立的 -虚拟设备或 Loopback 风格的虚拟设备图路由 Meet 输出和 Meet 麦克风。单个共享的 +为了获得清晰的双工音频，请通过单独的虚拟设备或 Loopback 风格的虚拟设备图 +路由 Meet 输出和 Meet 麦克风。单个共享的 BlackHole 设备可能会把其他参与者的声音回传到通话中。 -`googlemeet speak` 会为 Chrome -会话触发活动的实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委托的 Twilio 会话，`leave` 还会挂断底层语音通话。 +`googlemeet speak` 会触发 Chrome 会话的活跃实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委托的 Twilio 会话，`leave` 还会挂断底层语音通话。 -## 相关 +## 相关内容 -- [语音通话插件](/zh-CN/plugins/voice-call) -- [Talk 模式](/zh-CN/nodes/talk) +- [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 fceca5368..452d4fe57 100644 --- a/docs/zh-CN/plugins/voice-call.md +++ b/docs/zh-CN/plugins/voice-call.md @@ -1,45 +1,39 @@ --- read_when: - - 你想从 OpenClaw 发起外呼语音通话 + - 你想从 OpenClaw 发起一通外拨语音通话 - 你正在配置或开发语音通话插件 - - 你需要电话场景下的实时语音或流式转录 + - 你需要在电话系统中使用实时语音或流式转写 sidebarTitle: Voice call -summary: 通过 Twilio、Telnyx 或 Plivo 拨打外呼语音电话并接听呼入语音电话，并可选择启用实时语音和流式转录 +summary: 通过 Twilio、Telnyx 或 Plivo 发起外呼语音通话并接听来电，可选择启用实时语音和流式转写 title: 语音通话插件 x-i18n: - generated_at: "2026-05-01T05:39:45Z" + generated_at: "2026-05-01T05:59:30Z" model: gpt-5.5 provider: openai - source_hash: 08690f9f27de8a3d4d2c6056cd08edcc42f60f0592272a464c07cb1dc7fee26e + source_hash: ce208e4c23e6ac6f844dce23a7e6a565b4deb1f32b8018aae7f56ea196d5245c source_path: plugins/voice-call.md workflow: 16 --- -通过插件为 OpenClaw 提供语音通话。支持出站通知、 -多轮对话、全双工实时语音、流式转写， -以及带 allowlist 策略的入站通话。 +通过插件为 OpenClaw 提供语音通话。支持出站通知、多轮对话、全双工实时语音、流式转写，以及带允许列表策略的呼入通话。 -**当前提供商：** `twilio`（Programmable Voice + Media Streams）， -`telnyx`（Call Control v2），`plivo`（Voice API + XML transfer + GetInput -speech），`mock`（开发/无网络）。 +**当前提供商：** `twilio`（Programmable Voice + Media Streams）、`telnyx`（Call Control v2）、`plivo`（Voice API + XML transfer + GetInput speech）、`mock`（开发/无网络）。 -Voice Call 插件在 **Gateway 网关进程内** 运行。如果你使用 -远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件， -然后重启 Gateway 网关以加载它。 +Voice Call 插件在 **Gateway 网关进程内部**运行。如果你使用远程 Gateway 网关，请在运行 Gateway 网关的机器上安装并配置该插件，然后重启 Gateway 网关以加载它。 ## 快速开始 - + - + ```bash openclaw plugins install @openclaw/voice-call ``` - + ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin openclaw plugins install "$PLUGIN_SRC" @@ -48,37 +42,29 @@ Voice Call 插件在 **Gateway 网关进程内** 运行。如果你使用 - 如果 npm 报告 OpenClaw 拥有的软件包已弃用，该软件包版本 - 来自较旧的外部软件包发布线；请使用当前打包的 OpenClaw - 构建，或在较新的 npm 软件包发布前使用本地文件夹路径。 + 如果 npm 报告 OpenClaw 拥有的软件包已弃用，则该软件包版本来自较旧的外部软件包发布线；请使用当前打包的 OpenClaw 构建，或在发布更新的 npm 软件包之前使用本地文件夹路径。 - 之后重启 Gateway 网关，以便插件加载。 + 之后重启 Gateway 网关，以便加载插件。 - - 在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方 - [配置](#configuration)）。至少需要： - `provider`、提供商凭证、`fromNumber`，以及可公开访问的 webhook URL。 + + 在 `plugins.entries.voice-call.config` 下设置配置（完整结构见下方[配置](#configuration)）。至少需要：`provider`、提供商凭证、`fromNumber`，以及可公开访问的 webhook URL。 - + ```bash openclaw voicecall setup ``` - 默认输出适合在聊天日志和终端中阅读。它会检查 - 插件启用状态、提供商凭证、webhook 暴露情况，以及是否 - 只有一种音频模式（`streaming` 或 `realtime`）处于活动状态。脚本可使用 - `--json`。 + 默认输出可在聊天日志和终端中阅读。它会检查插件启用状态、提供商凭证、webhook 暴露情况，以及是否只有一种音频模式（`streaming` 或 `realtime`）处于活动状态。脚本请使用 `--json`。 - + ```bash openclaw voicecall smoke openclaw voicecall smoke --to "+15555550123" ``` - 两者默认都是 dry run。添加 `--yes` 才会实际发起一次简短的 - 出站通知通话： + 默认情况下两者都是试运行。添加 `--yes` 可实际发起一次简短的出站通知通话： ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -88,21 +74,15 @@ Voice Call 插件在 **Gateway 网关进程内** 运行。如果你使用 -对于 Twilio、Telnyx 和 Plivo，设置必须解析为 **公共 webhook URL**。 -如果 `publicUrl`、隧道 URL、Tailscale URL 或 serve fallback -解析为 loopback 或专用网络空间，设置会失败，而不是 -启动无法接收运营商 webhook 的提供商。 +对于 Twilio、Telnyx 和 Plivo，设置必须解析到一个**公共 webhook URL**。如果 `publicUrl`、隧道 URL、Tailscale URL 或 serve 回退解析到 loopback 或私有网络空间，设置会失败，而不是启动一个无法接收运营商 webhook 的提供商。 ## 配置 -如果 `enabled: true` 但所选提供商缺少凭证， -Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失键名， -并跳过启动运行时。命令、RPC 调用和智能体工具在使用时仍会 -返回确切缺失的提供商配置。 +如果 `enabled: true` 但所选提供商缺少凭证，Gateway 网关启动时会记录 setup-incomplete 警告，并列出缺少的键名，同时跳过运行时启动。命令、RPC 调用和智能体工具在使用时仍会返回确切缺失的提供商配置。 -语音通话凭证支持 SecretRef。`plugins.entries.voice-call.config.twilio.authToken` 和 `plugins.entries.voice-call.config.tts.providers.*.apiKey` 会通过标准 SecretRef 界面解析；见 [SecretRef 凭证界面](/zh-CN/reference/secretref-credential-surface)。 +Voice-call 凭证接受 SecretRef。`plugins.entries.voice-call.config.twilio.authToken` 和 `plugins.entries.voice-call.config.tts.providers.*.apiKey` 会通过标准 SecretRef 表面解析；参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。 ```json5 @@ -163,31 +143,27 @@ Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失 ``` - - - Twilio、Telnyx 和 Plivo 都需要一个 **可公开访问** 的 webhook URL。 - - `mock` 是本地开发提供商（不发起网络调用）。 + + - Twilio、Telnyx 和 Plivo 都需要一个**可公开访问**的 webhook URL。 + - `mock` 是本地开发提供商（无网络调用）。 - Telnyx 需要 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`），除非 `skipSignatureVerification` 为 true。 - `skipSignatureVerification` 仅用于本地测试。 - - 在 ngrok 免费层上，将 `publicUrl` 设置为确切的 ngrok URL；始终会强制执行签名验证。 - - `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅当 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时，才允许签名无效的 Twilio webhook。仅限本地开发。 + - 在 ngrok 免费层，将 `publicUrl` 设置为确切的 ngrok URL；始终强制执行签名验证。 + - `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时，允许带有无效签名的 Twilio webhook。仅限本地开发。 - Ngrok 免费层 URL 可能变化或添加插页行为；如果 `publicUrl` 偏移，Twilio 签名会失败。生产环境：优先使用稳定域名或 Tailscale funnel。 - - - `streaming.preStartTimeoutMs` 会关闭从未发送有效 `start` 帧的套接字。 - - `streaming.maxPendingConnections` 限制未认证 pre-start 套接字总数。 - - `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证 pre-start 套接字数。 - - `streaming.maxConnections` 限制打开的媒体流套接字总数（pending + active）。 + + - `streaming.preStartTimeoutMs` 会关闭从未发送有效 `start` 帧的 socket。 + - `streaming.maxPendingConnections` 限制未认证的 pre-start socket 总数。 + - `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证 pre-start socket 数量。 + - `streaming.maxConnections` 限制打开的媒体流 socket 总数（pending + active）。 - - 使用 `provider: "log"`、`twilio.from` 或旧版 - `streaming.*` OpenAI 键的旧配置会由 `openclaw doctor --fix` 重写。 - 运行时 fallback 目前仍接受旧的 voice-call 键，但 - 重写路径是 `openclaw doctor --fix`，兼容 shim 是 - 临时的。 + + 使用 `provider: "log"`、`twilio.from` 或旧版 `streaming.*` OpenAI 键的较旧配置会由 `openclaw doctor --fix` 重写。目前运行时回退仍接受旧的 voice-call 键，但重写路径是 `openclaw doctor --fix`，且兼容 shim 是临时的。 - 自动迁移的 streaming 键： + 自动迁移的流式键： - `streaming.sttProvider` → `streaming.provider` - `streaming.openaiApiKey` → `streaming.providers.openai.apiKey` @@ -200,42 +176,37 @@ Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失 ## 实时语音对话 -`realtime` 为实时通话音频选择一个全双工实时语音提供商。 -它与 `streaming` 分开，后者只会将音频转发给 -实时转写提供商。 +`realtime` 为实时通话音频选择全双工实时语音提供商。它与 `streaming` 分离，后者只会将音频转发给实时转写提供商。 -`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话请选择一种 -音频模式。 +`realtime.enabled` 不能与 `streaming.enabled` 组合使用。每次通话只能选择一种音频模式。 当前运行时行为： - Twilio Media Streams 支持 `realtime.enabled`。 - `realtime.provider` 是可选的。如果未设置，Voice Call 会使用第一个已注册的实时语音提供商。 -- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由它们的提供商插件注册。 +- 内置实时语音提供商：Google Gemini Live（`google`）和 OpenAI（`openai`），由各自的提供商插件注册。 - 提供商拥有的原始配置位于 `realtime.providers.` 下。 -- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。当来电者请求更深入的推理、当前信息或普通 OpenClaw 工具时，实时模型可以调用它。 -- 如果 `realtime.provider` 指向未注册的提供商，或根本没有注册任何实时语音提供商，Voice Call 会记录警告并跳过实时媒体，而不是让整个插件失败。 -- consult 会话键会在可用时复用现有语音会话，然后回退到主叫/被叫电话号码，以便后续 consult 调用在通话期间保持上下文。 +- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。当来电者要求更深入的推理、当前信息或普通 OpenClaw 工具时，实时模型可以调用它。 +- 如果 `realtime.provider` 指向未注册的提供商，或者根本没有注册实时语音提供商，Voice 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` | 暴露咨询工具，并将常规智能体限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 | +| `owner` | 暴露咨询工具，并让常规智能体使用正常的智能体工具策略。 | +| `none` | 不暴露咨询工具。自定义 `realtime.tools` 仍会传递给实时提供商。 | ### 实时提供商示例 - 默认值：API key 来自 `realtime.providers.google.apiKey`、 - `GEMINI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY`；模型 - `gemini-2.5-flash-native-audio-preview-12-2025`；语音 `Kore`。 + 默认值：API key 来自 `realtime.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY`；模型 `gemini-2.5-flash-native-audio-preview-12-2025`；语音 `Kore`。 ```json5 { @@ -290,28 +261,25 @@ Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失 -有关提供商专用的实时语音选项，请参阅 [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`），由它们的提供商插件注册。 +- 内置实时转写提供商：Deepgram（`deepgram`）、ElevenLabs（`elevenlabs`）、Mistral（`mistral`）、OpenAI（`openai`）和 xAI（`xai`），由各自的提供商插件注册。 - 提供商拥有的原始配置位于 `streaming.providers.` 下。 -- Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间通过转写提供商排队入站媒体，并且仅在实时转写准备就绪后开始初始问候。 -- 如果 `streaming.provider` 指向未注册的提供商，或没有任何提供商注册，Voice Call 会记录警告并跳过媒体流式传输，而不是让整个插件失败。 +- Twilio 发送已接受的流 `start` 消息后，Voice Call 会立即注册该流，在提供商连接期间通过转写提供商排队处理入站媒体，并且仅在实时转写就绪后启动初始问候语。 +- 如果 `streaming.provider` 指向未注册的提供商，或者没有注册任何提供商，Voice Call 会记录警告并跳过媒体流式传输，而不是让整个插件失败。 ### 流式提供商示例 - 默认值：API key `streaming.providers.openai.apiKey` 或 - `OPENAI_API_KEY`；模型 `gpt-4o-transcribe`；`silenceDurationMs: 800`； - `vadThreshold: 0.5`。 + 默认值：API key `streaming.providers.openai.apiKey` 或 `OPENAI_API_KEY`；模型 `gpt-4o-transcribe`；`silenceDurationMs: 800`；`vadThreshold: 0.5`。 ```json5 { @@ -373,9 +341,10 @@ Gateway 网关启动时会记录一条设置未完成警告，其中包含缺失 -## 通话的 TTS +## 调用的 TTS -Voice Call 使用核心 `messages.tts` 配置来处理通话中的流式语音。你可以在插件配置下用**相同结构**覆盖它 — 它会与 `messages.tts` 深度合并。 +Voice Call 使用核心 `messages.tts` 配置为调用提供流式 +语音。你可以在插件配置下用**相同结构**覆盖它，它会与 `messages.tts` 深度合并。 ```json5 { @@ -392,16 +361,17 @@ Voice Call 使用核心 `messages.tts` 配置来处理通话中的流式语音 ``` -**语音通话会忽略 Microsoft speech。** 电话音频需要 PCM；当前 Microsoft 传输不公开电话 PCM 输出。 +**Microsoft speech 会在语音调用中被忽略。** 电话音频需要 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 媒体流时会使用核心 TTS；否则调用会回退到提供商原生语音。 +- 如果 Twilio 媒体流已处于活动状态，Voice Call 不会回退到 TwiML ``。如果在该状态下电话 TTS 不可用，播放请求会失败，而不是混用两条播放路径。 +- 当电话 TTS 回退到次级提供商时，Voice Call 会记录一条包含提供商链（`from`、`to`、`attempts`）的警告，便于调试。 +- 当 Twilio 打断或流拆除清空待处理 TTS 队列时，已排队的播放请求会完成结算，而不是让调用方一直等待播放完成。 ### TTS 示例 @@ -468,9 +438,9 @@ Voice Call 使用核心 `messages.tts` 配置来处理通话中的流式语音 -## 来电 +## 入站调用 -来电策略默认值为 `disabled`。要启用来电，请设置： +入站策略默认为 `disabled`。要启用入站调用，请设置： ```json5 { @@ -481,52 +451,63 @@ 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 会将严格的语音输出契约附加到系统提示词： +对于自动响应，Voice Call 会向 system prompt 追加严格的语音输出契约： ```text {"spoken":"..."} ``` -Voice Call 会防御性地提取语音文本： +Voice Call 会以防御性方式提取语音文本： -- 忽略标记为推理/错误内容的负载。 +- 忽略标记为推理/错误内容的载荷。 - 解析直接 JSON、围栏 JSON 或内联 `"spoken"` 键。 -- 回退到纯文本，并移除可能的规划/元信息开头段落。 +- 回退到纯文本，并移除看起来像规划/元信息引入的段落。 -这会让语音播放聚焦于面向调用方的文本，并避免将规划文本泄漏到音频中。 +这会让语音播放聚焦于面向来电方的文本，并避免 +将规划文本泄漏到音频中。 ### 对话启动行为 -对于出站 `conversation` 通话，首条消息处理与实时播放状态绑定： +对于出站 `conversation` 调用，首条消息处理与实时 +播放状态绑定： -- 仅当初始问候正在主动播放时，才会抑制插话队列清空和自动响应。 -- 如果初始播放失败，通话会返回 `listening`，且初始消息仍保留在队列中以便重试。 -- Twilio 流式传输的初始播放会在流连接时开始，不会额外延迟。 -- 插话会中止活动播放，并清除已排队但尚未播放的 Twilio TTS 条目。清除的条目会解析为已跳过，因此后续响应逻辑可以继续，而无需等待永远不会播放的音频。 -- 实时语音对话使用实时流自己的开场回合。Voice Call **不会**为该初始消息发布旧版 `` TwiML 更新，因此出站 `` 会话会保持连接。 +- 仅当初始问候正在主动播放时，才会抑制打断队列清空和自动响应。 +- 如果初始播放失败，调用会返回 `listening`，初始消息会保持排队以便重试。 +- Twilio 流式传输的初始播放会在流连接时启动，不会额外延迟。 +- 打断会中止活动播放，并清空已排队但尚未播放的 Twilio TTS 条目。被清空的条目会解析为已跳过，因此后续响应逻辑可以继续，而无需等待永远不会播放的音频。 +- Realtime 语音对话使用 realtime 流自己的开场轮次。Voice Call **不会**为该初始消息发布旧版 `` TwiML 更新，因此出站 `` 会话会保持附着。 ### Twilio 流断开宽限期 -当 Twilio 媒体流断开时，Voice Call 会等待 **2000 ms** 后再自动结束通话： +当 Twilio 媒体流断开时，Voice Call 会等待 **2000 ms** 后再 +自动结束调用： -- 如果流在该窗口内重新连接，则取消自动结束。 -- 如果宽限期后没有流重新注册，则结束通话，防止活动通话卡住。 +- 如果流在该窗口内重新连接，自动结束会被取消。 +- 如果宽限期后没有流重新注册，调用会被结束，以防止活动调用卡住。 -## 过期通话清理器 +## 过期调用清理器 -使用 `staleCallReaperSeconds` 结束从未收到终止 webhook 的通话（例如从未完成的 notify 模式通话）。默认值为 `0`（禁用）。 +使用 `staleCallReaperSeconds` 结束从未收到终止 +webhook 的调用（例如永不完成的通知模式调用）。默认值 +为 `0`（禁用）。 -建议范围： +推荐范围： -- **生产环境：** 对于通知式流程，使用 `120`–`300` 秒。 -- 保持该值**高于 `maxDurationSeconds`**，以便正常通话能够完成。一个良好的起点是 `maxDurationSeconds + 30–60` 秒。 +- **生产环境：**用于通知式流程时设为 `120`–`300` 秒。 +- 将此值保持为**高于 `maxDurationSeconds`**，这样正常呼叫才能完成。一个合适的起点是 `maxDurationSeconds + 30–60` 秒。 ```json5 { @@ -545,26 +526,26 @@ Voice Call 会防御性地提取语音文本： ## Webhook 安全 -当代理或隧道位于 Gateway 网关前面时，该插件会重建用于签名验证的公开 URL。这些选项控制信任哪些转发标头： +当代理或隧道位于 Gateway 网关前面时，插件会重建用于签名验证的公共 URL。这些选项控制信任哪些转发标头： - 允许列表中的转发标头主机。 + 允许来自转发标头的主机列表。 - 在没有允许列表的情况下信任转发标头。 + 不使用允许列表也信任转发标头。 - 仅当请求远程 IP 与列表匹配时，才信任转发标头。 + 仅当请求远端 IP 匹配列表时才信任转发标头。 额外保护： -- Twilio 和 Plivo 已启用 webhook **重放保护**。重放的有效 webhook 请求会被确认，但会跳过副作用。 -- Twilio 对话回合在 `` 回调中包含每回合 token，因此过期/重放的语音回调无法满足较新的待处理转录回合。 -- 当缺少提供商所需的签名标头时，未认证的 webhook 请求会在读取正文前被拒绝。 -- voice-call webhook 使用共享的预认证正文配置（64 KB / 5 秒），并在签名验证前施加按 IP 统计的进行中请求上限。 +- Twilio 和 Plivo 已启用 Webhook **重放保护**。重放的有效 Webhook 请求会被确认，但会跳过副作用。 +- Twilio 对话轮次会在 `` 回调中包含每轮 token，因此过期或重放的语音回调无法满足新的待处理转录轮次。 +- 当缺少提供商要求的签名标头时，未经认证的 Webhook 请求会在读取正文前被拒绝。 +- voice-call Webhook 使用共享的预认证正文配置（64 KB / 5 秒），并在签名验证前应用按 IP 统计的进行中请求上限。 -使用稳定公开主机的示例： +使用稳定公共主机的示例： ```json5 { @@ -598,9 +579,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 网关拥有的 voice-call 运行时，因此 CLI 不会绑定第二个 Webhook 服务器。如果无法连接到 Gateway 网关，这些命令会回退到独立的 CLI 运行时。 -`latency` 从默认 voice-call 存储路径读取 `calls.jsonl`。使用 `--file ` 指向不同日志，并使用 `--last ` 将分析限制为最后 N 条记录（默认 200）。输出包括回合延迟和听取等待时间的 p50/p90/p99。 +`latency` 会从默认 voice-call 存储路径读取 `calls.jsonl`。使用 `--file ` 指向不同日志，使用 `--last ` 将分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。 ## 智能体工具 @@ -615,7 +596,7 @@ openclaw voicecall expose --mode funnel | `end_call` | `callId` | | `get_status` | `callId` | -此仓库在 `skills/voice-call/SKILL.md` 提供匹配的 skill 文档。 +此仓库在 `skills/voice-call/SKILL.md` 提供了匹配的 skill 文档。 ## Gateway 网关 RPC @@ -628,8 +609,124 @@ openclaw voicecall expose --mode funnel | `voicecall.end` | `callId` | | `voicecall.status` | `callId` | -## 相关内容 +## 故障排除 -- [Talk 模式](/zh-CN/nodes/talk) +### 设置无法暴露 Webhook + +请从运行 Gateway 网关的同一环境中运行设置： + +```bash +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`。 + +使用一种公共暴露路径： + +```json5 +{ + plugins: { + entries: { + "voice-call": { + config: { + publicUrl: "https://voice.example.com/voice/webhook", + // or + tunnel: { provider: "ngrok" }, + // or + tailscale: { mode: "funnel", path: "/voice/webhook" }, + }, + }, + }, + }, +} +``` + +更改配置后，重启或重新加载 Gateway 网关，然后运行： + +```bash +openclaw voicecall setup +openclaw 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 网关，直到它重启或重新加载其环境。 + +### 调用开始但提供商 webhooks 未到达 + +确认提供商控制台指向确切的公开 webhook URL： + +```text +https://voice.example.com/voice/webhook +``` + +然后检查运行时状态： + +```bash +openclaw voicecall status --call-id +openclaw voicecall tail +``` + +常见原因： + +- `publicUrl` 指向的路径与 `serve.path` 不同。 +- 隧道 URL 在 Gateway 网关启动后发生了变化。 +- 代理转发了请求，但剥离或重写了 host/proto 标头。 +- 防火墙或 DNS 将公开主机名路由到了 Gateway 网关以外的位置。 +- Gateway 网关重启时未启用 Voice Call 插件。 + +当 Gateway 网关前面有反向代理或隧道时，将 `webhookSecurity.allowedHosts` 设置为公开主机名，或对已知代理地址使用 `webhookSecurity.trustedProxyIPs`。仅当代理边界由你控制时，才使用 `webhookSecurity.trustForwardingHeaders`。 + +### 签名验证失败 + +提供商签名会根据 OpenClaw 从传入请求重建的公开 URL 进行检查。如果签名失败： + +- 确认提供商 webhook URL 与 `publicUrl` 完全匹配，包括 scheme、host 和 path。 +- 对于 ngrok 免费层级 URL，当隧道主机名变化时更新 `publicUrl`。 +- 确保代理保留原始 host 和 proto 标头，或配置 `webhookSecurity.allowedHosts`。 +- 不要在本地测试之外启用 `skipSignatureVerification`。 + +### Google Meet Twilio 加入失败 + +Google Meet 使用此插件进行 Twilio 拨入加入。首先验证 Voice Call： + +```bash +openclaw voicecall setup +openclaw voicecall smoke --to "+15555550123" +``` + +然后显式验证 Google Meet 传输： + +```bash +openclaw googlemeet setup --transport twilio +``` + +如果 Voice Call 状态正常，但 Meet 参与者从未加入，请检查 Meet 拨入号码、PIN 和 `--dtmf-sequence`。电话呼叫可能正常，而会议会拒绝或忽略不正确的 DTMF 序列。 + +Google Meet 会静默启动 Voice Call，发送 DTMF，然后让 Voice Call 在 `voiceCall.postDtmfSpeechDelayMs` 之后朗读开场白。如果第一句话在 Meet 允许电话参与者加入之前就被朗读，请在 Google Meet 插件配置中增加该延迟。 + +### 实时通话没有语音 + +确认只启用了一种音频模式。`realtime.enabled` 和 `streaming.enabled` 不能同时为 true。 + +对于实时 Twilio 通话，还要验证： + +- 已加载并注册实时提供商插件。 +- `realtime.provider` 未设置，或命名了已注册的提供商。 +- Gateway 网关进程可以使用提供商 API key。 +- `openclaw voicecall tail` 在初始问候之前显示媒体流已被接受，且实时提供商已就绪。 + +## 相关 + +- [对话模式](/zh-CN/nodes/talk) - [文本转语音](/zh-CN/tools/tts) - [语音唤醒](/zh-CN/nodes/voicewake)