From 3f5df4234044eae56658178e5186e9059a0845e5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 1 May 2026 08:07:15 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/plugins/google-meet.md | 520 +++++++++++++-------- docs/zh-CN/plugins/sdk-provider-plugins.md | 196 ++++---- 2 files changed, 425 insertions(+), 291 deletions(-) diff --git a/docs/zh-CN/plugins/google-meet.md b/docs/zh-CN/plugins/google-meet.md index dc4269883..7479b01b3 100644 --- a/docs/zh-CN/plugins/google-meet.md +++ b/docs/zh-CN/plugins/google-meet.md @@ -1,36 +1,42 @@ --- read_when: - - 你希望 OpenClaw 智能体加入 Google Meet 通话 - - 你希望 OpenClaw 智能体创建一个新的 Google Meet 通话 - - 你正在将 Chrome、Chrome node 或 Twilio 配置为 Google Meet 传输协议 -summary: Google Meet 插件：通过 Chrome 或 Twilio 加入显式 Meet URL，并使用实时语音默认值 + - 你想让 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-01T06:42:53Z" + generated_at: "2026-05-01T08:04:54Z" model: gpt-5.5 provider: openai - source_hash: 8a52bdd2fe7d080797241471e632d38a4f6aac9f0ca6d855547e364540ff2fd3 + source_hash: a9d0d195fc709e487ef1bf5603fdb32fade1b6a0a13aa9bed5110979490f92ff source_path: plugins/google-meet.md workflow: 16 --- -Google Meet 对 OpenClaw 的参会者支持在设计上是显式的： +Google Meet 参会者对 OpenClaw 的支持——该插件在设计上是显式的： - 它只会加入显式的 `https://meet.google.com/...` URL。 -- 它可以通过 Google Meet API 创建新的 Meet 空间，然后加入返回的 URL。 +- 它可以通过 Google Meet API 创建新的 Meet 空间，然后加入返回的 + URL。 - `realtime` 语音是默认模式。 - 当需要更深入的推理或工具时，实时语音可以回调完整的 OpenClaw 智能体。 -- 智能体通过 `mode` 选择加入行为：使用 `realtime` 进行实时收听/语音回复，或使用 `transcribe` 加入/控制浏览器，而不使用实时语音桥接。 -- 凭证一开始可以是个人 Google OAuth，或已登录的 Chrome 配置文件。 +- 智能体通过 `mode` 选择加入行为：使用 `realtime` 进行实时 + 监听/语音回应，或使用 `transcribe` 加入/控制浏览器，而不使用 + 实时语音桥接。 +- 认证从个人 Google OAuth 或已登录的 Chrome 配置文件开始。 - 没有自动同意公告。 - 默认 Chrome 音频后端是 `BlackHole 2ch`。 - Chrome 可以在本地运行，也可以在已配对的节点主机上运行。 - Twilio 接受拨入号码，以及可选的 PIN 或 DTMF 序列。 -- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体电话会议工作流。 +- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体 + 电话会议工作流。 ## 快速开始 -安装本地音频依赖项，并配置一个后端实时语音提供商。OpenAI 是默认值；Google Gemini Live 也可以配合 `realtime.provider: "google"` 使用： +安装本地音频依赖并配置一个后端实时语音 +提供商。OpenAI 是默认值；Google Gemini Live 也可与 +`realtime.provider: "google"` 一起使用： ```bash brew install blackhole-2ch sox @@ -39,13 +45,14 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装器需要重启后，macOS 才会公开该设备： +`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的 +安装器需要重启后，macOS 才会暴露该设备： ```bash sudo reboot ``` -重启后，验证这两项： +重启后，验证两项内容： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -73,21 +80,32 @@ 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 暴露。 加入会议： @@ -120,13 +138,27 @@ 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 { @@ -136,35 +168,59 @@ openclaw googlemeet create --no-join } ``` -对于仅观察/浏览器控制加入，请设置 `"mode": "transcribe"`。这不会启动双工实时模型桥接，不需要 BlackHole 或 SoX，也不会在会议中语音回复。此模式下的 Chrome 加入还会避免 OpenClaw 的麦克风/摄像头权限授予，并避开 Meet **Use microphone** 路径。如果 Meet 显示音频选择插页，自动化会尝试无麦克风路径，否则会报告需要手动操作，而不是打开本地麦克风。 +对于仅观察/浏览器控制加入，设置 `"mode": "transcribe"`。这不会 +启动双工实时模型桥接，不需要 BlackHole 或 SoX， +并且不会向会议中语音回应。此模式下的 Chrome 加入还会避免 +OpenClaw 的麦克风/摄像头权限授予，并避开 Meet **使用 +麦克风** 路径。如果 Meet 显示音频选择中间页，自动化会尝试 +无麦克风路径，否则报告需要手动操作，而不是打开 +本地麦克风。 -在实时会话期间，`google_meet` 状态包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最后输入/输出时间戳、字节计数器，以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可行时处理。登录、主持人准入以及浏览器/OS 权限提示会作为手动操作报告，并带有原因和消息，供智能体转述。托管 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 网关、智能体工作区、模型/API key、实时提供商，以及 Google Meet 插件配置。 -- Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及已登录 Google 的 Chrome 配置文件。 -- VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT key，或模型提供商设置。 +- Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型/API keys、实时 + 提供商，以及 Google Meet 插件配置。 +- Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch， + 以及已登录 Google 的 Chrome 配置文件。 +- VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT key 或模型 + 提供商设置。 -安装 VM 依赖项： +安装 VM 依赖： ```bash brew install blackhole-2ch sox ``` -安装 BlackHole 后重启 VM，让 macOS 公开 `BlackHole 2ch`： +安装 BlackHole 后重启 VM，让 macOS 暴露 `BlackHole 2ch`： ```bash sudo reboot ``` -重启后，验证 VM 可以看到音频设备和 SoX 命令： +重启后，验证 VM 能看到音频设备和 SoX 命令： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -183,14 +239,15 @@ 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 \ @@ -198,7 +255,9 @@ 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 网关主机批准节点： @@ -207,13 +266,14 @@ openclaw devices list openclaw devices approve ``` -确认 Gateway 网关能看到该节点，并且该节点通告了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`： +确认 Gateway 网关能看到该节点，并且它通告了 `googlemeet.chrome` +以及浏览器能力/`browser.proxy`： ```bash openclaw nodes status ``` -在 Gateway 网关主机上将 Meet 路由到该节点： +在 Gateway 网关主机上通过该节点路由 Meet： ```json5 { @@ -249,61 +309,78 @@ 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 浏览器自动化会填写访客名称，点击加入/请求加入，并在出现 Meet 首次运行的 “Use microphone” 选择时接受它。在仅观察加入或仅浏览器创建会议期间，如果可用，它会在同一提示中选择不使用麦克风继续。如果浏览器配置文件未登录、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 主机，并报告设置阻塞项； - 除非用户要求，否则不要回退到其他传输方式。 + 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 音频前重启。 + `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"` 或一个命名的现有会话配置文件。 + `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 的路由。 +- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径； + 使用单独的虚拟设备或类似 Loopback 的路由来实现干净的双工音频。 ## 安装说明 Chrome 实时默认设置使用两个外部工具： -- `sox`：命令行音频工具。插件使用显式的 CoreAudio - 设备命令来实现默认的 24 kHz PCM16 音频桥接。 -- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 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 @@ -311,13 +388,14 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome ``` 将 Chrome 麦克风和扬声器音频路由到本地 OpenClaw 音频桥接。如果未安装 -`BlackHole 2ch`，加入会失败并显示设置错误，而不是在没有音频路径的情况下静默加入。 +`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 节点上启用： @@ -344,7 +422,7 @@ Twilio 传输方式是委派给 Voice Call 插件的严格拨号计划。它不 } ``` -通过环境或配置提供 Twilio 凭证。环境变量可以让密钥不进入 `openclaw.json`： +通过环境或配置提供 Twilio 凭证。环境可避免将机密写入 `openclaw.json`： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -352,7 +430,8 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -启用 `voice-call` 后重启或重新加载 Gateway 网关；插件配置变更在已运行的 Gateway 网关进程重新加载前不会出现。 +启用 `voice-call` 后重启或重新加载 Gateway 网关；插件配置更改在重新加载前不会出现在已运行的 +Gateway 网关进程中。 然后验证： @@ -362,7 +441,7 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -当 Twilio 委派已连接时，`googlemeet setup` 会包含成功的 +当 Twilio 委派已接通时，`googlemeet setup` 会包含成功的 `twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 `twilio-voice-call-webhook` 检查。 @@ -382,14 +461,18 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -## OAuth 和预检 +## OAuth 与预检 -创建 Meet 链接时 OAuth 是可选的，因为 `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 插件配置中，或提供 +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 凭证 @@ -398,15 +481,16 @@ OAuth 不会替代 Chrome 加入路径。Chrome 和 Chrome-node 传输方式在 1. 创建或选择一个 Google Cloud 项目。 2. 为该项目启用 **Google Meet REST API**。 3. 配置 OAuth 同意屏幕。 - - 对于 Google Workspace 组织，**内部** 最简单。 - - **外部** 适用于个人/测试设置；当应用处于测试阶段时，将每个会授权该应用的 Google 账号添加为测试用户。 -4. 添加 OpenClaw 请求的作用域： + - 对于 Google Workspace 组织，**Internal** 最简单。 + - **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.conference.media.readonly` 5. 创建 OAuth 客户端 ID。 - - 应用类型：**Web 应用**。 - - 已获授权的重定向 URI： + - 应用类型：**Web application**。 + - 授权重定向 URI： ```text http://localhost:8085/oauth2callback @@ -416,17 +500,20 @@ OAuth 不会替代 Chrome 加入路径。Chrome 和 Chrome-node 传输方式在 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。 +`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体工作；实际使用 +Media API 时，Google 可能要求加入 Developer Preview。如果你只需要基于浏览器的 +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` 的手动复制/粘贴流程。 示例： @@ -444,7 +531,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json --manual ``` -JSON 输出包含： +JSON 输出包括： ```json { @@ -480,38 +567,43 @@ 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` | 缓存的访问令牌仍然有效，或刷新令牌已生成新的访问令牌。 | +| `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` 范围时使用它。 若要证明对现有会议空间的读取访问： @@ -520,12 +612,15 @@ openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hi 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` @@ -542,13 +637,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 @@ -556,9 +651,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`。 -Calendar 查找可以在读取 Meet 工件前从 Google Calendar 解析会议 URL： +Calendar 查找可以先从 Google Calendar 解析会议 URL，再读取 Meet 工件： ```bash openclaw googlemeet latest --today @@ -567,9 +662,9 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 Calendar 事件。使用 `--event ` 搜索匹配的事件文本，使用 `--calendar ` 指定非主日历。Calendar 查找需要重新进行 OAuth 登录，并包含 Calendar 事件只读权限范围。`calendar-events` 会预览匹配的 Meet 事件，并标记 `latest`、`artifacts`、`attendance` 或 `export` 将选择的事件。 +`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 Calendar 事件。使用 `--event ` 搜索匹配的事件文本，并使用 `--calendar ` 指定非主日历。Calendar 查找需要重新进行 OAuth 登录，并包含 Calendar events readonly 作用域。`calendar-events` 会预览匹配的 Meet 事件，并标记 `latest`、`artifacts`、`attendance` 或 `export` 将选择的事件。 -如果你已经知道会议记录 ID，可以直接引用它： +如果你已经知道会议记录 ID，可以直接指定它： ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -592,9 +687,9 @@ 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 文本；这需要重新进行 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 readonly 作用域。不使用 `--include-doc-bodies` 时，导出仅包含 Meet 元数据和结构化转录条目。如果 Google 返回部分工件失败，例如智能笔记列表、转录条目或 Drive 文档正文错误，摘要和清单会保留该警告，而不是让整个导出失败。使用 `--dry-run` 可获取相同的工件/出席数据，并打印清单 JSON，而不创建文件夹或 ZIP。这适合在写入大型导出前使用，或者在智能体只需要计数、所选记录和警告时使用。 智能体也可以通过 `google_meet` 工具创建相同的包： @@ -610,7 +705,7 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ 设置 `"dryRun": true` 可仅返回导出清单并跳过文件写入。 -针对一个真实保留的会议运行带保护的实时冒烟测试： +针对真实保留会议运行受保护的实时冒烟测试： ```bash OPENCLAW_LIVE_TEST=1 \ @@ -620,23 +715,19 @@ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts 实时冒烟测试环境： -- `OPENCLAW_LIVE_TEST=1` 启用带保护的实时测试。 +- `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_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_ACCESS_TOKEN_EXPIRES_AT` 使用相同的回退名称，但不带 + `OPENCLAW_` 前缀。 -基础工件/出席情况实时冒烟测试需要 -`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`。 +基础工件/出席实时冒烟测试需要 `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 空间： @@ -644,9 +735,9 @@ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts openclaw googlemeet create ``` -该命令会打印新的 `meeting uri`、来源和加入会话。使用 OAuth 凭据时，它使用官方 Google Meet API。没有 OAuth 凭据时，它使用已固定 Chrome 节点中已登录的浏览器配置文件作为回退。智能体可以使用 `google_meet` 工具并设置 `action: "create"`，一步创建并加入。若只创建 URL，传入 `"join": false`。 +该命令会打印新的 `meeting uri`、来源和加入会话。使用 OAuth 凭据时，它会使用官方 Google Meet API。没有 OAuth 凭据时，它会使用固定 Chrome 节点的已登录浏览器配置文件作为回退。智能体可以使用 `google_meet` 工具并设置 `action: "create"`，一步完成创建和加入。若只创建 URL，传入 `"join": false`。 -浏览器回退的示例 JSON 输出： +浏览器回退的 JSON 输出示例： ```json { @@ -666,7 +757,7 @@ openclaw googlemeet create } ``` -如果浏览器回退在创建 URL 前遇到 Google 登录或 Meet 权限阻止，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化详情，而不是普通字符串： +如果浏览器回退在创建 URL 前遇到 Google 登录或 Meet 权限阻断，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化详情，而不是普通字符串： ```json { @@ -684,9 +775,9 @@ openclaw googlemeet create } ``` -当智能体看到 `manualActionRequired: true` 时，应报告 `manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成浏览器步骤。 +当智能体看到 `manualActionRequired: true` 时，应报告 `manualActionMessage` 以及浏览器节点/标签页上下文，并在操作员完成浏览器步骤之前停止打开新的 Meet 标签页。 -API 创建的示例 JSON 输出： +API 创建的 JSON 输出示例： ```json { @@ -707,13 +798,13 @@ API 创建的示例 JSON 输出： } ``` -创建 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 主体和会议参与者已加入 Google Workspace Developer Preview Program 的 Meet media API 后，才设置 `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 @@ -741,24 +832,26 @@ export GEMINI_API_KEY=... - `defaultTransport: "chrome"` - `defaultMode: "realtime"` -- `chromeNode.node`：用于 `chrome-node` 的可选节点 ID/名称/IP +- `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 命令 +- `chrome.bargeInInputCommand`：可选的本地麦克风命令，用于在助手播放处于活动状态时写入有符号 16 位小端单声道 PCM，以检测人工插话。这当前适用于 Gateway 网关托管的 `chrome` 命令对桥接。 +- `chrome.bargeInRmsThreshold: 650`：在 `chrome.bargeInInputCommand` 上计为人工打断的 RMS 电平 +- `chrome.bargeInPeakThreshold: 2500`：在 `chrome.bargeInInputCommand` 上计为人工打断的峰值电平 +- `chrome.bargeInCooldownMs: 900`：重复清除人工打断之间的最小延迟 - `realtime.provider: "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` -可选覆盖项： +可选覆盖： ```json5 { @@ -771,6 +864,24 @@ export GEMINI_API_KEY=... chrome: { guestName: "OpenClaw Agent", waitForInCallMs: 30000, + bargeInInputCommand: [ + "sox", + "-q", + "-t", + "coreaudio", + "External Microphone", + "-r", + "24000", + "-c", + "1", + "-b", + "16", + "-e", + "signed-integer", + "-t", + "raw", + "-", + ], }, chromeNode: { node: "parallels-macos", @@ -805,7 +916,7 @@ 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 呼叫。 ## 工具 @@ -820,18 +931,19 @@ 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。使用带有 `sessionId` 和 `message` 的 `action: "speak"`，让实时智能体立即说话。使用 `action: "test_speech"` 创建或复用会话、触发已知短语，并在 Chrome 主机能够报告时返回 `inCall` 健康状态。`test_speech` 总是强制使用 `mode: "realtime"`，如果要求它以 `mode: "transcribe"` 运行则会失败，因为仅观察会话有意不能发出语音。它的 `speechOutputVerified` 结果基于此次测试呼叫期间实时音频输出字节数是否增加，因此复用会话中的旧音频不会算作一次新的成功语音检查。使用 `action: "leave"` 将会话标记为已结束。 +使用 `action: "status"` 可列出活动会话或检查会话 ID。使用带有 `sessionId` 和 `message` 的 `action: "speak"` 可让实时智能体立即说话。使用 `action: "test_speech"` 可创建或复用会话，触发一个已知短语，并在 Chrome 主机可以报告时返回 `inCall` 健康状态。`test_speech` 始终强制 `mode: "realtime"`，如果要求它以 `mode: "transcribe"` 运行则会失败，因为仅观察会话被有意设计为不能发出语音。它的 `speechOutputVerified` 结果基于本次测试呼叫期间实时音频输出字节数的增加，因此复用带有旧音频的会话不算一次新的成功语音检查。使用 `action: "leave"` 可将会话标记为已结束。 `status` 会在可用时包含 Chrome 健康状态： -- `inCall`：Chrome 看起来位于 Meet 通话中 +- `inCall`：Chrome 看起来已进入 Meet 通话 - `micMuted`：尽力判断的 Meet 麦克风状态 -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限，或在语音可工作前修复浏览器控制 -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`：托管 Chrome 语音当前是否被允许。`speechReady: false` 表示 OpenClaw 未将开场/测试短语发送到音频桥。 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授予或浏览器控制修复，语音才能工作 +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`：当前是否允许托管 Chrome 语音。`speechReady: false` 表示 OpenClaw 未将开场/测试短语发送到音频桥。 - `providerConnected` / `realtimeReady`：实时语音桥状态 -- `lastInputAt` / `lastOutputAt`：上次从桥接收或发送到桥的音频时间 +- `lastInputAt` / `lastOutputAt`：从桥接收到或发送到桥的最后音频时间 +- `lastSuppressedInputAt` / `suppressedInputBytes`：助手播放处于活动状态时被忽略的 loopback 输入 ```json { @@ -843,27 +955,27 @@ export GEMINI_API_KEY=... ## 实时智能体咨询 -Chrome 实时模式针对实时语音循环优化。实时语音提供商会听取会议音频，并通过配置的音频桥发声。当实时模型需要更深入的推理、当前信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 +Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会听取会议音频，并通过配置的音频桥说话。当实时模型需要更深入的推理、当前信息或常规 OpenClaw 工具时，可以调用 `openclaw_agent_consult`。 -咨询工具会在幕后运行常规 OpenClaw 智能体，附带最近的会议转录上下文，并向实时语音会话返回简洁的口述答案。语音模型随后可以把该答案说回会议中。它使用与 Voice Call 相同的共享实时咨询工具。 +咨询工具会在后台运行常规 OpenClaw 智能体，并带上最近的会议转录上下文，然后向实时语音会话返回简洁的口语回答。语音模型随后可以将该回答说回会议。它使用与 Voice Call 相同的共享实时咨询工具。 -默认情况下，咨询针对 `main` 智能体运行。当某个 Meet 通道应咨询专用的 OpenClaw Agent 工作区、模型默认值、工具策略、记忆和会话历史时，请设置 `realtime.agentId`。 +默认情况下，咨询针对 `main` 智能体运行。当某个 Meet 通道应咨询专用的 OpenClaw Agent 工作区、模型默认值、工具策略、记忆和会话历史时，设置 `realtime.agentId`。 `realtime.toolPolicy` 控制咨询运行： -- `safe-read-only`：暴露咨询工具，并将常规智能体限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 +- `safe-read-only`：暴露咨询工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 - `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 \ @@ -871,9 +983,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: I'm here and listening." ``` -## 实时测试检查清单 +## 实时测试清单 -在把会议交给无人值守智能体之前，使用此序列： +在把会议交给无人值守的智能体之前，使用此序列： ```bash openclaw googlemeet setup @@ -886,9 +998,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ 预期的 Chrome-node 状态： - `googlemeet setup` 全部为绿色。 -- 当 Chrome-node 是默认传输或固定了某个节点时，`googlemeet setup` 包含 `chrome-node-connected`。 +- 当 Chrome-node 是默认传输或已固定节点时，`googlemeet setup` 包含 `chrome-node-connected`。 - `nodes status` 显示所选节点已连接。 -- 所选节点同时公布 `googlemeet.chrome` 和 `browser.proxy`。 +- 所选节点同时通告 `googlemeet.chrome` 和 `browser.proxy`。 - Meet 标签页加入通话，并且 `test-speech` 返回带有 `inCall: true` 的 Chrome 健康状态。 对于远程 Chrome 主机（例如 Parallels macOS VM），这是更新 Gateway 网关或 VM 后最短的安全检查： @@ -902,9 +1014,9 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -这会证明 Gateway 网关插件已加载、VM 节点已使用当前令牌连接，并且在智能体打开真实会议标签页前，Meet 音频桥可用。 +这证明 Gateway 网关插件已加载，VM 节点已使用当前令牌连接，并且在智能体打开真实会议标签页之前，Meet 音频桥可用。 -对于 Twilio 冒烟测试，请使用公开电话拨入详情的会议： +对于 Twilio 冒烟检查，使用一个公开电话拨入详情的会议： ```bash openclaw googlemeet setup @@ -917,23 +1029,23 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ 预期的 Twilio 状态： - `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，然后是已排队初始问候的实时桥。 +- Gateway 网关重载后，CLI 中可用 `voicecall`。 +- 返回的会话具有 `transport: "twilio"` 和 `twilio.voiceCallId`。 +- `openclaw logs --follow` 显示在实时 TwiML 之前提供 DTMF TwiML，然后显示一个已排队初始问候的实时桥。 - `googlemeet leave ` 会挂断委托的语音呼叫。 ## 故障排除 -### 智能体无法看到 Google Meet 工具 +### 智能体看不到 Google Meet 工具 -确认插件已在 Gateway 网关配置中启用，并重新加载 Gateway 网关： +确认插件已在 Gateway 网关配置中启用，并重载 Gateway 网关： ```bash openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到当前 Gateway 网关进程注册的插件工具。 +如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重载 Gateway 网关。正在运行的智能体只能看到当前 Gateway 网关进程注册的插件工具。 ### 没有已连接且支持 Google Meet 的节点 @@ -954,7 +1066,7 @@ openclaw devices approve openclaw nodes status ``` -该节点必须已连接，并列出 `googlemeet.chrome` 以及 `browser.proxy`。Gateway 网关配置必须允许这些节点命令： +节点必须已连接，并列出 `googlemeet.chrome` 加 `browser.proxy`。Gateway 网关配置必须允许这些节点命令： ```json5 { @@ -966,7 +1078,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 \ @@ -977,7 +1089,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -然后重新加载节点服务并再次运行： +然后重载节点服务并重新运行： ```bash openclaw googlemeet setup @@ -986,28 +1098,28 @@ openclaw nodes status --connected ### 浏览器打开但智能体无法加入 -运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告 `manualActionRequired: true`，请向操作员展示 `manualActionMessage`，并在浏览器操作完成前停止重试。 +运行 `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?” 就报告“未登录”。这是 Meet 的音频选择插页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真实会议状态。对于仅创建的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。 ### 会议创建失败 -配置了 OAuth 凭证时，`googlemeet create` 会先使用 Google Meet API `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认： +`googlemeet create` 会在配置了 OAuth 凭证时首先使用 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` 的节点。 +- 对于 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`。 +- 对于浏览器回退：重试会在打开新标签页之前复用现有的 `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`。 ### 智能体加入但不说话 @@ -1018,31 +1130,31 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -将 `mode: "realtime"` 用于监听/回话。`mode: "transcribe"` 有意不会启动双工实时语音桥。`googlemeet test-speech` 总是检查实时路径，并报告此次调用是否观察到桥输出字节。如果 `speechOutputVerified` 为 false 且 `speechOutputTimedOut` 为 true，实时提供商可能已经接受话语，但 OpenClaw 没有看到新的输出字节到达 Chrome 音频桥。 +对 listen/talk-back 使用 `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 使用的虚拟音频路径路由。 -`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... @@ -1050,7 +1162,7 @@ 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` 指向 local 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`。 @@ -1091,7 +1203,7 @@ Loopback 和私有 URL 对运营商回调无效。不要将 `localhost`、`127.0 } ``` -然后重启或重新加载 Gateway 网关并运行： +然后重启或重新加载 Gateway 网关，并运行： ```bash openclaw googlemeet setup --transport twilio @@ -1099,21 +1211,21 @@ openclaw voicecall setup openclaw voicecall smoke ``` -默认情况下，`voicecall smoke` 仅检查就绪状态。要对特定号码进行试运行： +`voicecall smoke` 默认仅检查就绪状态。要对特定号码进行 dry-run： ```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 \ @@ -1122,35 +1234,37 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -如果提供商需要在输入 PIN 前暂停，请在 `--dtmf-sequence` 中使用前导 `w` 或逗号。 +如果提供商需要在输入 PIN 前暂停，请在 `--dtmf-sequence` 中使用开头的 `w` 或逗号。 -如果电话呼叫已创建，但 Meet 名单中从未显示拨入参与者： +如果电话通话已创建，但 Meet 名单始终没有显示拨入参与者： -- 运行 `openclaw voicecall status --call-id `，并确认呼叫仍处于活动状态。 -- 运行 `openclaw voicecall tail`，并检查 Twilio webhooks 是否到达 Gateway 网关。 -- 运行 `openclaw logs --follow`，并查找 Twilio Meet 序列：Google Meet 委托加入，Voice Call 存储预连接 DTMF TwiML，提供该初始 TwiML，然后提供实时 TwiML，并以 `initialGreeting=queued` 启动实时桥接。 +- 运行 `openclaw voicecall status --call-id `，并确认通话仍处于活动状态。 +- 运行 `openclaw voicecall tail`，并检查 Twilio webhook 是否到达 Gateway 网关。 +- 运行 `openclaw logs --follow`，查找 Twilio Meet 序列：Google Meet 委派加入，Voice Call 存储预连接 DTMF TwiML，提供该初始 TwiML，然后提供实时 TwiML，并以 `initialGreeting=queued` 启动实时桥接。 - 重新运行 `openclaw googlemeet setup --transport twilio`；绿色设置检查是必需的，但不能证明会议 PIN 序列正确。 -- 确认拨入号码与 PIN 属于同一个 Meet 邀请和地区。 -- 如果 Meet 接听较慢，请增加 `--dtmf-sequence` 中的前导暂停，例如 `wwww123456#`。 -- 如果参与者已加入但你听不到问候语，请在 `openclaw logs --follow` 中检查实时 TwiML、实时桥接启动和 `initialGreeting=queued`。问候语会在实时桥接连接后，根据初始 `voicecall.start` 消息生成。 +- 确认拨入号码与 PIN 属于同一个 Meet 邀请和区域。 +- 如果 Meet 应答较慢，请增加 `--dtmf-sequence` 开头的暂停，例如 `wwww123456#`。 +- 如果参与者已加入但你听不到问候语，请检查 `openclaw logs --follow` 中的实时 TwiML、实时桥接启动和 `initialGreeting=queued`。问候语是在实时桥接连接后，由初始 `voicecall.start` 消息生成的。 -如果 webhooks 未到达，请先调试 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` 或已配置的隧道。请参阅[语音通话故障排除](/zh-CN/plugins/voice-call#troubleshooting)。 -## 备注 +## 说明 -Google Meet 的官方媒体 API 以接收为导向，因此向 Meet 通话中说话仍然需要参与者路径。此插件让该边界保持可见：Chrome 处理浏览器参与和本地音频路由；Twilio 处理电话拨入参与。 +Google Meet 的官方媒体 API 偏向接收，因此在 Meet 通话中发言仍然需要参与者路径。此插件会保持该边界清晰可见：Chrome 处理浏览器参与和本地音频路由；Twilio 处理电话拨入参与。 -Chrome 实时模式需要 `BlackHole 2ch`，并满足以下任一条件： +Chrome 实时模式需要 `BlackHole 2ch`，并且还需要以下之一： -- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有实时模型桥接，并在这些命令与所选实时语音提供商之间以 `chrome.audioFormat` 管道传输音频。默认 Chrome 路径是 24 kHz PCM16；8 kHz G.711 mu-law 仍可用于旧版命令对。 +- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有实时模型桥接，并在这些命令与所选实时语音提供商之间，以 `chrome.audioFormat` 管道传输音频。默认 Chrome 路径是 24 kHz PCM16；8 kHz G.711 mu-law 仍可用于旧版命令对。 - `chrome.audioBridgeCommand`：外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。 -要获得干净的双工音频，请通过单独的虚拟设备或 Loopback 风格的虚拟设备图来路由 Meet 输出和 Meet 麦克风。单个共享的 BlackHole 设备可能会将其他参与者的声音回传到通话中。 +为获得干净的双工音频，请将 Meet 输出和 Meet 麦克风通过独立的虚拟设备或 Loopback 风格的虚拟设备图路由。单个共享的 BlackHole 设备可能会把其他参与者的声音回传进通话。 -`googlemeet speak` 会为 Chrome 会话触发活动的实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委托的 Twilio 会话，`leave` 还会挂断底层语音呼叫。 +使用命令对 Chrome 桥接时，`chrome.bargeInInputCommand` 可以监听单独的本地麦克风，并在人类开始说话时清除助手播放。这样即使共享的 BlackHole loopback 输入在助手播放期间被暂时抑制，也能让人类语音优先于助手输出。与 `chrome.audioInputCommand` 和 `chrome.audioOutputCommand` 一样，它是由操作员配置的本地命令。请使用明确的受信任命令路径或参数列表，不要将其指向来自不受信任位置的脚本。 + +`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 还会挂断底层语音通话。 ## 相关 -- [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/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index a505ec817..c92114005 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -1,21 +1,21 @@ --- read_when: - - 你正在构建一个新的模型提供商插件 - - 你想将兼容 OpenAI 的代理或自定义 LLM 添加到 OpenClaw - - 你需要了解提供商身份验证、目录和运行时钩子 + - 你正在构建新的模型提供商插件 + - 你想向 OpenClaw 添加一个 OpenAI 兼容代理或自定义大型语言模型 + - 你需要了解提供商凭证、目录和运行时钩子 sidebarTitle: Provider plugins summary: 构建 OpenClaw 模型提供商插件的分步指南 title: 构建提供商插件 x-i18n: - generated_at: "2026-04-29T04:06:10Z" + generated_at: "2026-05-01T08:04:54Z" model: gpt-5.5 provider: openai - source_hash: 1404594fe1d1e11a612f903512c1002c8f3a804dee53d4204457b534eae93381 + source_hash: 3f9d721673bdfef0b9c1979b4b8b4c86f19d114374d6b941facb928c3574cd1b source_path: plugins/sdk-provider-plugins.md workflow: 16 --- -本指南将介绍如何构建一个提供商插件，用于向 OpenClaw 添加模型提供商（LLM）。完成后，你将拥有一个带有模型目录、API 密钥凭证和动态模型解析的提供商。 +本指南讲解如何构建一个为 OpenClaw 添加模型提供商（LLM）的提供商插件。完成后，你将拥有一个包含模型目录、API key 凭证和动态模型解析的提供商。 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 @@ -23,13 +23,13 @@ x-i18n: - 提供商插件会把模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过拥有线程、压缩或工具事件的原生智能体守护进程运行，请将该提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心。 + 提供商插件会把模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过一个原生智能体守护进程运行，并由它拥有线程、压缩或工具事件，请将提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 配合使用，而不要把守护进程协议细节放进核心。 ## 演练 - + ```json package.json { @@ -87,11 +87,11 @@ x-i18n: ``` - 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的凭证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，根据 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你在 ClawHub 上发布该提供商，则 `package.json` 中必须包含这些 `openclaw.compat` 和 `openclaw.build` 字段。 + 该清单声明了 `providerAuthEnvVars`，这样 OpenClaw 可以在不加载你的插件运行时的情况下检测凭据。当某个提供商变体应复用另一个提供商 ID 的凭证时，添加 `providerAuthAliases`。`modelSupport` 是可选项，它让 OpenClaw 能够在运行时钩子存在之前，根据 `acme-large` 这样的模型 ID 简写自动加载你的提供商插件。如果你在 ClawHub 上发布该提供商，则 `package.json` 中必须包含这些 `openclaw.compat` 和 `openclaw.build` 字段。 - + 一个最小提供商需要 `id`、`label`、`auth` 和 `catalog`： ```typescript index.ts @@ -163,7 +163,7 @@ x-i18n: }); ``` - 这就是一个可工作的提供商。用户现在可以执行 + 这就是一个可工作的提供商。用户现在可以运行 `openclaw onboard --acme-ai-api-key `，并选择 `acme-ai/acme-large` 作为他们的模型。 @@ -186,8 +186,7 @@ x-i18n: `input` 会在传输前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析自己的控制标记或渠道投递之前，重写助手文本增量和最终文本。 - 对于仅注册一个带 API 密钥凭证且由单个目录支持运行时的文本提供商的内置提供商，优先使用范围更窄的 - `defineSingleProviderPluginEntry(...)` 辅助函数： + 对于只注册一个带 API-key 凭证的文本提供商，并且只有一个由目录支持的运行时的内置提供商，优先使用范围更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -227,21 +226,19 @@ x-i18n: }); ``` - `buildProvider` 是 OpenClaw 能够解析真实提供商凭证时使用的实时目录路径。它可以执行提供商特定的设备发现。仅将 `buildStaticProvider` 用于在配置凭证前可以安全显示的离线行；它不得要求凭证，也不得发起网络请求。OpenClaw 当前的 `models list --all` 显示只会为内置提供商插件执行静态目录，并且使用空配置、空环境，且没有智能体/工作区路径。 + `buildProvider` 是 OpenClaw 能够解析真实提供商凭证时使用的实时目录路径。它可以执行提供商特定的发现。仅将 `buildStaticProvider` 用于在配置凭证前可安全展示的离线行；它不得需要凭据或发起网络请求。OpenClaw 的 `models list --all` 显示目前只会对内置提供商插件执行静态目录，并使用空配置、空环境且不提供智能体/工作区路径。 - 如果你的凭证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用来自 - `openclaw/plugin-sdk/provider-onboard` 的预设辅助函数。范围最窄的辅助函数是 + 如果你的凭证流程还需要在新手引导期间修补 `models.providers.*`、别名和智能体默认模型，请使用来自 `openclaw/plugin-sdk/provider-onboard` 的预设辅助函数。范围最窄的辅助函数是 `createDefaultModelPresetAppliers(...)`、 `createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 - 当提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 - `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 - `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持，因此即使插件使用自定义提供商 id，原生 Moonshot/DashScope 风格端点仍可选择启用。 + 当提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 ID 检查。`supportsNativeStreamingUsageCompat(...)` 和 + `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持情况，因此即使某个插件使用自定义提供商 ID，原生 Moonshot/DashScope 风格端点仍会选择启用。 - + 如果你的提供商接受任意模型 ID（例如代理或路由器），请添加 `resolveDynamicModel`： ```typescript @@ -263,14 +260,14 @@ x-i18n: }); ``` - 如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热——它完成后会再次运行 `resolveDynamicModel`。 + 如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热 — 它完成后会再次运行 `resolveDynamicModel`。 - - 大多数提供商只需要 `catalog` + `resolveDynamicModel`。根据提供商需求逐步添加钩子。 + + 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需要它们，再逐步添加钩子。 - 共享辅助构建器现在覆盖了最常见的重放/工具兼容系列，因此插件通常不需要逐个手动接线每个钩子： + 共享辅助构建器现在覆盖了最常见的重放/工具兼容系列，因此插件通常不需要逐个手动连接每个钩子： ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -294,39 +291,39 @@ x-i18n: | 系列 | 接入内容 | 内置示例 | | --- | --- | --- | - | `openai-compatible` | 用于 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、assistant-first 排序修复，以及传输需要时的通用 Gemini 轮次校验 | `moonshot`, `ollama`, `xai`, `zai` | - | `anthropic-by-model` | 由 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic 消息传输只有在解析后的模型确实是 Claude id 时，才会获得 Claude 特定的思考块清理 | `amazon-bedrock`, `anthropic-vertex` | - | `google-gemini` | 原生 Gemini 重放策略，以及引导重放清理和带标签的推理输出模式 | `google`, `google-gemini-cli` | - | `passthrough-gemini` | 适用于通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini 思考签名清理；不会启用原生 Gemini 重放校验或引导重写 | `openrouter`, `kilocode`, `opencode`, `opencode-go` | - | `hybrid-anthropic-openai` | 适用于在一个插件中混合 Anthropic 消息和 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude 思考块丢弃会保持在 Anthropic 侧范围内 | `minimax` | + | `openai-compatible` | 面向 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 ID 清理、助手优先顺序修正，以及传输需要时的通用 Gemini 轮次校验 | `moonshot`、`ollama`、`xai`、`zai` | + | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic 消息传输仅在解析后的模型确实是 Claude ID 时，才获得 Claude 特定的 thinking-block 清理 | `amazon-bedrock`、`anthropic-vertex` | + | `google-gemini` | 原生 Gemini 重放策略，以及启动重放清理和带标签的 reasoning-output 模式 | `google`、`google-gemini-cli` | + | `passthrough-gemini` | 通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或启动重写 | `openrouter`、`kilocode`、`opencode`、`opencode-go` | + | `hybrid-anthropic-openai` | 面向在一个插件中混合 Anthropic 消息和 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude thinking-block 丢弃会限定在 Anthropic 侧 | `minimax` | - 当前可用的流系列： + 当前可用的流式传输系列： | 系列 | 接入内容 | 内置示例 | | --- | --- | --- | - | `google-thinking` | 共享流路径上的 Gemini thinking 载荷规范化 | `google`, `google-gemini-cli` | - | `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，带有 `kilo/auto`，且不支持的代理推理 ID 会跳过注入的 thinking | `kilocode` | - | `moonshot-thinking` | 从配置 + `/think` 级别映射 Moonshot 二进制原生 thinking 载荷 | `moonshot` | - | `minimax-fast-mode` | 共享流路径上的 MiniMax 快速模式模型改写 | `minimax`, `minimax-portal` | - | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因标头、`/fast`/`serviceTier`、文本详略度、原生 Codex Web 搜索、推理兼容载荷整形，以及 Responses 上下文管理 | `openai`, `openai-codex` | - | `openrouter-thinking` | 代理路由的 OpenRouter 推理包装器，集中处理不支持模型/`auto` 跳过 | `openrouter` | - | `tool-stream-default-on` | 面向 Z.AI 等提供商的默认开启 `tool_stream` 包装器，除非显式禁用，否则它们需要工具流式传输 | `zai` | + | `google-thinking` | 共享流路径上的 Gemini 思考载荷规范化 | `google`, `google-gemini-cli` | + | `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，并会跳过 `kilo/auto` 和不受支持的代理推理 ID 的注入思考 | `kilocode` | + | `moonshot-thinking` | 从配置 + `/think` 级别映射 Moonshot 二进制原生思考载荷 | `moonshot` | + | `minimax-fast-mode` | 共享流路径上的 MiniMax 快速模式模型重写 | `minimax`, `minimax-portal` | + | `openai-responses-defaults` | 共享原生 OpenAI/Codex Responses 包装器：归因标头、`/fast`/`serviceTier`、文本详略度、原生 Codex Web 搜索、推理兼容载荷整形，以及 Responses 上下文管理 | `openai`, `openai-codex` | + | `openrouter-thinking` | 用于代理路由的 OpenRouter 推理包装器，并集中处理不受支持模型/`auto` 的跳过逻辑 | `openrouter` | + | `tool-stream-default-on` | 面向 Z.AI 这类提供商的默认开启 `tool_stream` 包装器，除非显式禁用，否则启用工具流式传输 | `zai` | - - 每个系列构建器都由同一包导出的较低层级公共辅助工具组成；当某个提供商需要偏离通用模式时，你可以使用这些辅助工具： + + 每个系列构建器都由同一包导出的较低层级公开辅助函数组合而成。当某个提供商需要偏离通用模式时，你可以使用它们： - - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)`，以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助工具（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）和端点/模型辅助工具（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。 - - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享的 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）、DeepSeek V4 OpenAI 兼容包装器（`createDeepSeekV4OpenAICompatibleThinkingWrapper`）、Anthropic Messages thinking 预填充清理（`createAnthropicThinkingPrefillPayloadWrapper`），以及共享代理/提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。 - - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助工具（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`），以及 xAI 兼容辅助工具（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置 xAI 插件将 `normalizeResolvedModel` + `contributeResolvedModelCompat` 与这些工具结合使用，确保 xAI 规则由提供商自行拥有。 + - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)`，以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助函数（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）以及端点/模型辅助函数（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。 + - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享的 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）、DeepSeek V4 OpenAI 兼容包装器（`createDeepSeekV4OpenAICompatibleThinkingWrapper`）、Anthropic Messages 思考预填充清理（`createAnthropicThinkingPrefillPayloadWrapper`），以及共享代理/提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。 + - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助函数（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`），以及 xAI 兼容辅助函数（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置的 xAI 插件会配合这些辅助函数使用 `normalizeResolvedModel` + `contributeResolvedModelCompat`，以确保 xAI 规则由该提供商拥有。 - 有些流辅助工具会有意保留在提供商本地。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及较低层级的 Anthropic 包装器构建器保留在它自己的公共 `api.ts` / `contract-api.ts` 接缝中，因为它们编码了 Claude OAuth beta 处理和 `context1m` 门控。xAI 插件同样将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中（`/fast` 别名、默认 `tool_stream`、不支持严格工具清理、移除 xAI 专属推理载荷）。 + 有些流辅助函数会有意保留在提供商本地。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及较低层级的 Anthropic 包装器构建器保留在自己的公开 `api.ts` / `contract-api.ts` 接口中，因为它们编码了 Claude OAuth beta 处理和 `context1m` 门控。xAI 插件也同样将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中（`/fast` 别名、默认 `tool_stream`、不受支持的严格工具清理、xAI 专属推理载荷移除）。 - 同一个包根模式也支撑 `@openclaw/openai-provider`（提供商构建器、默认模型辅助工具、实时提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器以及新手引导/配置辅助工具）。 + 同样的包根模式也支撑 `@openclaw/openai-provider`（提供商构建器、默认模型辅助函数、实时提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器，以及新手引导/配置辅助函数）。 - 对于需要在每次推理调用前进行令牌交换的提供商： + 对于每次推理调用前都需要令牌交换的提供商： ```typescript prepareRuntimeAuth: async (ctx) => { @@ -340,7 +337,7 @@ x-i18n: ``` - 对于需要自定义请求标头或正文修改的提供商： + 对于需要自定义请求标头或修改请求体的提供商： ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -358,7 +355,7 @@ x-i18n: ``` - 对于需要在通用 HTTP 或 WebSocket 传输上使用原生请求/会话标头或元数据的提供商： + 对于需要在通用 HTTP 或 WebSocket 传输上设置原生请求/会话标头或元数据的提供商： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -379,7 +376,7 @@ x-i18n: ``` - 对于公开用量/计费数据的提供商： + 对于暴露用量/计费数据的提供商： ```typescript resolveUsageAuth: async (ctx) => { @@ -394,70 +391,73 @@ x-i18n: - OpenClaw 会按此顺序调用钩子。大多数提供商只使用 2-3 个： - OpenClaw 不再调用的仅兼容提供商字段，例如 `ProviderPlugin.capabilities` 和 `suppressBuiltInModel`，未在此列出。 + OpenClaw 按以下顺序调用钩子。大多数提供商只使用 2-3 个： + 仅用于兼容性的提供商字段，例如 OpenClaw 不再调用的 `ProviderPlugin.capabilities` 和 `suppressBuiltInModel`，未在此列出。 - | # | 钩子 | 使用场景 | + | # | 钩子 | 使用时机 | | --- | --- | --- | | 1 | `catalog` | 模型目录或基础 URL 默认值 | - | 2 | `applyConfigDefaults` | 配置具象化期间由提供商拥有的全局默认值 | + | 2 | `applyConfigDefaults` | 配置物化期间由提供商拥有的全局默认值 | | 3 | `normalizeModelId` | 查找前清理旧版/预览模型 ID 别名 | - | 4 | `normalizeTransport` | 通用模型组装前清理提供商系列 `api` / `baseUrl` | + | 4 | `normalizeTransport` | 通用模型组装前清理提供商系列的 `api` / `baseUrl` | | 5 | `normalizeConfig` | 规范化 `models.providers.` 配置 | - | 6 | `applyNativeStreamingUsageCompat` | 配置提供商的原生流式用量兼容改写 | + | 6 | `applyNativeStreamingUsageCompat` | 面向配置提供商的原生流式用量兼容重写 | | 7 | `resolveConfigApiKey` | 由提供商拥有的环境标记凭证解析 | | 8 | `resolveSyntheticAuth` | 本地/自托管或配置支持的合成凭证 | - | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储 profile 占位符降级到环境/配置凭证之后 | + | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储配置档占位符降到环境/配置凭证之后 | | 10 | `resolveDynamicModel` | 接受任意上游模型 ID | | 11 | `prepareDynamicModel` | 解析前异步获取元数据 | - | 12 | `normalizeResolvedModel` | 运行器前的传输改写 | - | 13 | `contributeResolvedModelCompat` | 另一个兼容传输背后的厂商模型兼容标志 | + | 12 | `normalizeResolvedModel` | 运行器前的传输重写 | + | 13 | `contributeResolvedModelCompat` | 面向位于另一种兼容传输之后的厂商模型的兼容标志 | | 14 | `normalizeToolSchemas` | 注册前由提供商拥有的工具 schema 清理 | | 15 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 | - | 16 | `resolveReasoningOutputMode` | 标记式与原生推理输出契约 | + | 16 | `resolveReasoningOutputMode` | 标签式与原生推理输出契约 | | 17 | `prepareExtraParams` | 默认请求参数 | | 18 | `createStreamFn` | 完全自定义的 StreamFn 传输 | - | 19 | `wrapStreamFn` | 普通流路径上的自定义标头/正文包装器 | + | 19 | `wrapStreamFn` | 正常流路径上的自定义标头/请求体包装器 | | 20 | `resolveTransportTurnState` | 原生逐轮标头/元数据 | - | 21 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却时间 | - | 22 | `formatApiKey` | 自定义运行时令牌形态 | + | 21 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却 | + | 22 | `formatApiKey` | 自定义运行时令牌形状 | | 23 | `refreshOAuth` | 自定义 OAuth 刷新 | | 24 | `buildAuthDoctorHint` | 凭证修复指引 | | 25 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 | - | 26 | `classifyFailoverReason` | 由提供商拥有的速率限制/过载分类 | - | 27 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 | + | 26 | `classifyFailoverReason` | 由提供商拥有的限速/过载分类 | + | 27 | `isCacheTtlEligible` | 提示缓存 TTL 门控 | | 28 | `buildMissingAuthMessage` | 自定义缺失凭证提示 | | 29 | `augmentModelCatalog` | 合成的前向兼容行 | | 30 | `resolveThinkingProfile` | 模型专属 `/think` 选项集 | - | 31 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 | + | 31 | `isBinaryThinking` | 二进制思考开/关兼容性 | | 32 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 | | 33 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 | - | 34 | `isModernModelRef` | 实时/smoke 模型匹配 | + | 34 | `isModernModelRef` | 实时/冒烟模型匹配 | | 35 | `prepareRuntimeAuth` | 推理前令牌交换 | | 36 | `resolveUsageAuth` | 自定义用量凭证解析 | | 37 | `fetchUsageSnapshot` | 自定义用量端点 | - | 38 | `createEmbeddingProvider` | 由提供商拥有、用于 memory/search 的嵌入适配器 | + | 38 | `createEmbeddingProvider` | 用于记忆/搜索且由提供商拥有的嵌入适配器 | | 39 | `buildReplayPolicy` | 自定义转录重放/压缩策略 | - | 40 | `sanitizeReplayHistory` | 通用清理后的提供商专属重放改写 | + | 40 | `sanitizeReplayHistory` | 通用清理后按提供商执行的重放重写 | | 41 | `validateReplayTurns` | 嵌入式运行器前的严格重放轮次验证 | | 42 | `onModelSelected` | 选择后的回调（例如遥测） | 运行时回退说明： - - `normalizeConfig` 会先检查匹配的提供商，然后检查其他具备钩子能力的提供商插件，直到某个钩子确实修改了配置。如果没有提供商钩子改写受支持的 Google 系列配置条目，内置 Google 配置规范化器仍会应用。 - - `resolveConfigApiKey` 在暴露时使用提供商钩子。内置 `amazon-bedrock` 路径在这里也有内置 AWS 环境标记解析器，尽管 Bedrock 运行时凭证本身仍使用 AWS SDK 默认链。 - - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知能力的系统提示词指引。当行为属于一个提供商/模型系列，并且应保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。 + - `normalizeConfig` 会先检查匹配的提供商，然后检查其他支持钩子的提供商插件，直到有一个真正更改配置为止。如果没有提供商钩子重写受支持的 Google 系列配置条目，仍会应用内置 Google 配置规范化器。 + - `resolveConfigApiKey` 会在暴露时使用提供商钩子。内置的 `amazon-bedrock` 路径在这里也有内置 AWS 环境标记解析器，即使 Bedrock 运行时凭证本身仍使用 AWS SDK 默认链。 + - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入缓存感知的系统提示指引。当行为属于一个提供商/模型系列，并且应保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。 - 有关详细描述和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 + 如需详细说明和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 - 提供商插件可以在文本推理之外，同时注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取和 Web 搜索。OpenClaw 将此归类为 **混合能力** 插件，这是公司插件（每个厂商一个插件）的推荐模式。请参阅 - [内部机制：能力所有权](/zh-CN/plugins/architecture#capability-ownership-model)。 + 提供商插件可以在文本推理之外注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取和 Web 搜索。OpenClaw 将其归类为 + **混合能力** 插件，这是公司插件的推荐模式 + （每个厂商一个插件）。请参阅 + [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 - 在 `register(api)` 中，将每项能力与现有的 `api.registerProvider(...)` 调用一起注册。只选择你需要的标签页： + 在 `register(api)` 内、与你现有的 + `api.registerProvider(...)` 调用一起注册每项能力。只选择你需要的标签页： @@ -495,10 +495,15 @@ x-i18n: }); ``` - 对提供商 HTTP 失败使用 `assertOkOrThrowProviderError(...)`，这样插件可共享有上限的错误正文读取、JSON 错误解析和请求 ID 后缀。 + 对提供商 HTTP 失败使用 `assertOkOrThrowProviderError(...)`，这样 + 插件会共享受限的错误正文读取、JSON 错误解析和 + 请求 ID 后缀。 - 优先使用 `createRealtimeTranscriptionWebSocketSession(...)` —— 这个共享辅助函数会处理代理捕获、重连退避、关闭刷新、就绪握手、音频排队和关闭事件诊断。你的插件只需要映射上游事件。 + 优先使用 `createRealtimeTranscriptionWebSocketSession(...)` — 这个共享 + helper 会处理代理捕获、重连退避、关闭时刷新、就绪 + 握手、音频排队和关闭事件诊断。你的插件 + 只需映射上游事件。 ```typescript api.registerRealtimeTranscriptionProvider({ @@ -536,7 +541,11 @@ x-i18n: }); ``` - 通过 POST 上传 multipart 音频的批处理 STT 提供商应使用来自 `openclaw/plugin-sdk/provider-http` 的 `buildAudioTranscriptionFormData(...)`。该辅助函数会规范化上传文件名，包括为兼容的转录 API 需要 M4A 风格文件名的 AAC 上传。 + 通过 POST 发送 multipart 音频的批量 STT 提供商应使用 + `openclaw/plugin-sdk/provider-http` 中的 + `buildAudioTranscriptionFormData(...)`。该 helper 会规范化上传 + 文件名，包括需要 M4A 风格文件名以兼容 + 转录 API 的 AAC 上传。 ```typescript @@ -552,6 +561,7 @@ x-i18n: connect: async () => {}, sendAudio: () => {}, setMediaTimestamp: () => {}, + handleBargeIn: () => {}, submitToolResult: () => {}, acknowledgeMark: () => {}, close: () => {}, @@ -559,6 +569,9 @@ x-i18n: }), }); ``` + + 当传输协议可以检测到人工正在打断助手播放，且提供商支持截断或 + 清除当前音频响应时，实现 `handleBargeIn`。 ```typescript @@ -571,7 +584,12 @@ x-i18n: ``` - 视频能力使用一种**模式感知**的结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段不足以清晰声明转换模式支持或已禁用的模式。音乐生成也遵循相同模式，使用显式的 `generate` / `edit` 块。 + 视频能力使用一种**模式感知**的形状：`generate`、 + `imageToVideo` 和 `videoToVideo`。像 + `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段不足以 + 清晰地表明对转换模式的支持或已禁用的模式。 + 音乐生成也遵循相同模式，使用显式的 `generate` / + `edit` 块。 ```typescript api.registerImageGenerationProvider({ @@ -598,7 +616,7 @@ x-i18n: }); ``` - + ```typescript api.registerWebFetchProvider({ id: "acme-ai-fetch", @@ -674,7 +692,8 @@ clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -不要在这里使用旧的仅技能发布别名；插件包应使用 `clawhub package publish`。 +不要在这里使用旧版的仅 Skills 发布别名；插件包应使用 +`clawhub package publish`。 ## 文件结构 @@ -690,21 +709,22 @@ clawhub package publish your-org/your-plugin ## 目录顺序参考 -`catalog.order` 控制你的目录相对于内置提供商的合并时机： +`catalog.order` 控制你的目录相对于内置 +提供商的合并时机： -| 顺序 | 时机 | 用例 | +| 顺序 | 时机 | 使用场景 | | --------- | ------------- | ----------------------------------------------- | | `simple` | 第一轮 | 普通 API key 提供商 | -| `profile` | 在 simple 后 | 由认证档案控制的提供商 | -| `paired` | 在 profile 后 | 合成多个相关条目 | +| `profile` | simple 之后 | 受凭证档案限制的提供商 | +| `paired` | profile 之后 | 合成多个相关条目 | | `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） | ## 后续步骤 -- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 如果你的插件也提供渠道 -- [SDK 运行时](/zh-CN/plugins/sdk-runtime) —— `api.runtime` 辅助函数（TTS、搜索、子智能体） -- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 完整的子路径导入参考 -- [插件内部机制](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) —— 钩子细节和内置示例 +- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件还提供渠道 +- [SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` helper（TTS、搜索、子智能体） +- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 +- [插件内部机制](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) — 钩子细节和内置示例 ## 相关内容