From 3758fc282eb7534954bae08e99a044f6fdce82bf Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 07:25:06 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/browser.md | 53 ++-- docs/zh-CN/concepts/memory-builtin.md | 67 ++--- docs/zh-CN/concepts/memory-qmd.md | 95 +++--- docs/zh-CN/concepts/memory-search.md | 50 ++-- docs/zh-CN/logging.md | 134 +++++---- docs/zh-CN/plugins/google-meet.md | 416 ++++++++++++++------------ docs/zh-CN/tools/browser.md | 330 ++++++++++---------- 7 files changed, 603 insertions(+), 542 deletions(-) diff --git a/docs/zh-CN/cli/browser.md b/docs/zh-CN/cli/browser.md index 5dd145e77..40809f7fa 100644 --- a/docs/zh-CN/cli/browser.md +++ b/docs/zh-CN/cli/browser.md @@ -1,22 +1,22 @@ --- read_when: - - 你使用 `openclaw browser`，并且想要查看常见任务的示例 + - 你会使用 `openclaw browser`，并且想查看常见任务的示例 - 你想通过一个节点主机来控制另一台机器上运行的浏览器 - 你想通过 Chrome MCP 连接到你本地已登录的 Chrome summary: '`openclaw browser` 的 CLI 参考（生命周期、配置文件、标签页、操作、状态和调试）' title: 浏览器 x-i18n: - generated_at: "2026-04-25T06:35:01Z" + generated_at: "2026-04-25T07:22:23Z" model: gpt-5.4 provider: openai - source_hash: 03994a04839214fca41a8b53f21ddfb71560455039ff2e14b309b887eb86f5f9 + source_hash: 292fc15c72de0aea069b1b87de471e645dbaa3e568e2c7fa493cbcd7c6791a9e source_path: cli/browser.md workflow: 15 --- # `openclaw browser` -管理 OpenClaw 的浏览器控制界面并运行浏览器操作（生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试）。 +管理 OpenClaw 的浏览器控制界面，并运行浏览器操作（生命周期、配置文件、标签页、快照、截图、导航、输入、状态模拟和调试）。 相关内容： @@ -24,12 +24,12 @@ x-i18n: ## 常用标志 -- `--url `：Gateway 网关 WebSocket URL（默认使用配置中的值）。 +- `--url `：Gateway 网关 WebSocket URL（默认来自配置）。 - `--token `：Gateway 网关令牌（如果需要）。 -- `--timeout `：请求超时时间（毫秒）。 +- `--timeout `：请求超时（毫秒）。 - `--expect-final`：等待最终的 Gateway 网关响应。 -- `--browser-profile `：选择一个浏览器配置文件（默认使用配置中的默认值）。 -- `--json`：机器可读输出（在支持时）。 +- `--browser-profile `：选择一个浏览器配置文件（默认来自配置）。 +- `--json`：机器可读输出（在支持的地方）。 ## 快速开始（本地） @@ -46,7 +46,7 @@ openclaw browser --browser-profile openclaw snapshot 如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪状态。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面是健康的，失败通常是导航 SSRF 策略导致的。 -最小操作序列： +最小排查步骤： ```bash openclaw browser --browser-profile openclaw doctor @@ -69,7 +69,7 @@ openclaw browser --browser-profile openclaw reset-profile 说明： -- 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身并未启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖项。 +- 对于 `attachOnly` 和远程 CDP 配置文件，即使 OpenClaw 本身没有启动浏览器进程，`openclaw browser stop` 也会关闭当前控制会话并清除临时模拟覆盖。 - 对于本地受管配置文件，`openclaw browser stop` 会停止已启动的浏览器进程。 ## 如果命令缺失 @@ -92,9 +92,9 @@ openclaw browser --browser-profile openclaw reset-profile ## 配置文件 -配置文件是命名的浏览器路由配置。实际使用中： +配置文件是具名的浏览器路由配置。实际使用中： -- `openclaw`：启动或连接到专用的 OpenClaw 托管 Chrome 实例（隔离的用户数据目录）。 +- `openclaw`：启动或连接到一个专用的由 OpenClaw 管理的 Chrome 实例（隔离的用户数据目录）。 - `user`：通过 Chrome DevTools MCP 控制你现有的已登录 Chrome 会话。 - 自定义 CDP 配置文件：指向本地或远程 CDP 端点。 @@ -106,7 +106,7 @@ openclaw browser create-profile --name remote --cdp-url https://browser-host.exa openclaw browser delete-profile --name work ``` -使用指定配置文件： +使用特定配置文件： ```bash openclaw browser --browser-profile work tabs @@ -125,7 +125,7 @@ openclaw browser focus docs openclaw browser close t1 ``` -`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId`（如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回 `focus`、`close`、快照和操作中使用。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 id、原始 target id 以及唯一的 target-id 前缀都可被接受。 +`tabs` 会先返回 `suggestedTargetId`，然后返回稳定的 `tabId`（例如 `t1`）、可选标签以及原始 `targetId`。智能体应将 `suggestedTargetId` 传回 `focus`、`close`、快照和操作中使用。你可以使用 `open --label`、`tab new --label` 或 `tab label` 分配标签；标签、标签页 ID、原始目标 ID 以及唯一的目标 ID 前缀都可被接受。 ## 快照 / 截图 / 操作 @@ -147,10 +147,10 @@ openclaw browser screenshot --labels 说明： -- `--full-page` 仅用于页面截图；不能与 `--ref` 或 `--element` 组合使用。 -- `existing-session` / `user` 配置文件支持页面截图和基于快照输出中 `--ref` 的截图，但不支持基于 CSS `--element` 的截图。 +- `--full-page` 仅用于整页截图；不能与 `--ref` 或 `--element` 组合使用。 +- `existing-session` / `user` 配置文件支持整页截图和基于快照输出的 `--ref` 截图，但不支持 CSS `--element` 截图。 - `--labels` 会在截图上叠加当前快照引用标签。 -- `snapshot --urls` 会将发现的链接目标追加到 AI 快照中，这样智能体可以选择直接的导航目标，而不是仅根据链接文本猜测。 +- `snapshot --urls` 会将已发现的链接目标追加到 AI 快照中，这样智能体就可以选择直接的导航目标，而不必仅根据链接文本猜测。 导航 / 点击 / 输入（基于 ref 的 UI 自动化）： @@ -169,7 +169,7 @@ openclaw browser wait --text "Done" openclaw browser evaluate --fn '(el) => el.textContent' --ref ``` -文件 + 对话框辅助功能： +文件 + 对话框辅助： ```bash openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref @@ -195,7 +195,7 @@ openclaw browser set headers '{"x-test":"1"}' openclaw browser set credentials myuser mypass ``` -Cookie + 存储： +Cookies + 存储： ```bash openclaw browser cookies @@ -230,29 +230,30 @@ openclaw browser create-profile --name brave-live --driver existing-session --us openclaw browser --browser-profile chrome-live tabs ``` -这一路径仅适用于主机本机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。 +此路径仅适用于宿主机。对于 Docker、无头服务器、Browserless 或其他远程设置，请改用 CDP 配置文件。 当前 existing-session 的限制： - 基于快照的操作使用 ref，而不是 CSS 选择器 +- 当调用方省略 `timeoutMs` 时，`browser.actionTimeoutMs` 会将受支持的 `act` 请求默认设置为 60000 毫秒；但单次调用的 `timeoutMs` 仍然优先生效。 - `click` 仅支持左键点击 - `type` 不支持 `slowly=true` - `press` 不支持 `delayMs` -- `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 会拒绝按调用设置的超时覆盖 +- `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 会拒绝单次调用的超时覆盖 - `select` 仅支持一个值 - 不支持 `wait --load networkidle` -- 文件上传要求使用 `--ref` / `--input-ref`，不支持 CSS `--element`，并且当前一次只支持一个文件 +- 文件上传需要 `--ref` / `--input-ref`，不支持 CSS `--element`，并且当前一次仅支持一个文件 - 对话框钩子不支持 `--timeout` -- 截图支持页面截图和 `--ref`，但不支持 CSS `--element` +- 截图支持整页截图和 `--ref`，但不支持 CSS `--element` - `responsebody`、下载拦截、PDF 导出和批量操作仍然需要受管浏览器或原始 CDP 配置文件 ## 远程浏览器控制（节点主机代理） -如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome / Brave / Edge / Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。 +如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome / Brave / Edge / Chromium 的机器上运行一个**节点主机**。Gateway 网关会将浏览器操作代理到该节点（无需单独的浏览器控制服务器）。 -使用 `gateway.nodes.browser.mode` 控制自动路由，并使用 `gateway.nodes.browser.node` 在连接了多个节点时固定到特定节点。 +使用 `gateway.nodes.browser.mode` 控制自动路由，并在连接了多个节点时使用 `gateway.nodes.browser.node` 固定到特定节点。 -安全性 + 远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全性](/zh-CN/gateway/security) +安全性和远程设置：[浏览器工具](/zh-CN/tools/browser)、[远程访问](/zh-CN/gateway/remote)、[Tailscale](/zh-CN/gateway/tailscale)、[安全](/zh-CN/gateway/security) ## 相关内容 diff --git a/docs/zh-CN/concepts/memory-builtin.md b/docs/zh-CN/concepts/memory-builtin.md index b3abcd1cb..243a6e197 100644 --- a/docs/zh-CN/concepts/memory-builtin.md +++ b/docs/zh-CN/concepts/memory-builtin.md @@ -1,21 +1,21 @@ --- read_when: - - 你想了解默认记忆后端 + - 你想了解默认的 Memory 后端 - 你想配置嵌入提供商或混合搜索 -summary: 默认基于 SQLite 的记忆后端，支持关键词、向量和混合搜索 -title: 内置记忆引擎 +summary: 默认基于 SQLite 的 Memory 后端，支持关键词、向量和混合搜索 +title: 内置 Memory 引擎 x-i18n: - generated_at: "2026-04-24T02:14:46Z" + generated_at: "2026-04-25T07:22:18Z" model: gpt-5.4 provider: openai - source_hash: f82c1f4dc37b4fc6c075a7fcd2ec78bfcbfbebbcba7e48d366a1da3afcaff508 + source_hash: 9ccf0b70bd3ed4e2138ae1d811573f6920c95eb3f8117693b242732012779dc6 source_path: concepts/memory-builtin.md workflow: 15 --- -内置引擎是默认的记忆后端。它会将你的记忆索引存储在每个智能体专属的 SQLite 数据库中，入门时无需额外依赖。 +内置引擎是默认的 Memory 后端。它将你的内存索引存储在每个智能体各自的 SQLite 数据库中，入门时无需任何额外依赖。 -## 它提供的功能 +## 它提供的能力 - **关键词搜索**：通过 FTS5 全文索引（BM25 评分）实现。 - **向量搜索**：通过任意受支持提供商提供的嵌入实现。 @@ -25,7 +25,7 @@ x-i18n: ## 入门指南 -如果你拥有 OpenAI、Gemini、Voyage 或 Mistral 的 API 密钥，内置引擎会自动检测并启用向量搜索。无需配置。 +如果你有 OpenAI、Gemini、Voyage 或 Mistral 的 API 密钥，内置引擎会自动检测并启用向量搜索。无需配置。 如需显式设置提供商： @@ -43,7 +43,7 @@ x-i18n: 如果没有嵌入提供商，则只能使用关键词搜索。 -如需强制使用内置本地嵌入提供商，请将 `local.modelPath` 指向一个 GGUF 文件： +如果你想强制使用内置的本地嵌入提供商，请在 OpenClaw 旁边安装可选的 `node-llama-cpp` 运行时包，然后将 `local.modelPath` 指向一个 GGUF 文件： ```json5 { @@ -63,29 +63,28 @@ x-i18n: ## 支持的嵌入提供商 -| 提供商 | ID | 自动检测 | 说明 | -| -------- | --------- | ------------- | ----------------------------------- | -| OpenAI | `openai` | 是 | 默认：`text-embedding-3-small` | -| Gemini | `gemini` | 是 | 支持多模态（图像 + 音频） | -| Voyage | `voyage` | 是 | | -| Mistral | `mistral` | 是 | | -| Ollama | `ollama` | 否 | 本地，需显式设置 | -| Local | `local` | 是（优先） | GGUF 模型，下载大小约 0.6 GB | +| 提供商 | ID | 自动检测 | 说明 | +| ------ | --------- | -------- | ----------------------------------- | +| OpenAI | `openai` | 是 | 默认：`text-embedding-3-small` | +| Gemini | `gemini` | 是 | 支持多模态（图像 + 音频） | +| Voyage | `voyage` | 是 | | +| Mistral | `mistral` | 是 | | +| Ollama | `ollama` | 否 | 本地，需显式设置 | +| Local | `local` | 是（优先） | 可选的 `node-llama-cpp` 运行时 | -自动检测会按照上表顺序，选择第一个可解析出 API 密钥的提供商。设置 `memorySearch.provider` 可覆盖此行为。 +自动检测会按表中所示顺序，选择第一个能够解析出 API 密钥的提供商。设置 `memorySearch.provider` 可覆盖此行为。 ## 索引的工作方式 -OpenClaw 会将 `MEMORY.md` 和 `memory/*.md` 索引为若干块（约 400 个 token，重叠 80 个 token），并将它们存储在每个智能体专属的 SQLite 数据库中。 +OpenClaw 会将 `MEMORY.md` 和 `memory/*.md` 索引为分块（约 400 个 token，带 80 个 token 重叠），并将其存储在每个智能体各自的 SQLite 数据库中。 - **索引位置：** `~/.openclaw/memory/.sqlite` -- **文件监视：** 记忆文件发生变化时，会触发带防抖的重新索引（1.5 秒）。 +- **文件监听：** 对内存文件的更改会触发防抖后的重新索引（1.5 秒）。 - **自动重新索引：** 当嵌入提供商、模型或分块配置发生变化时，整个索引会自动重建。 - **按需重新索引：** `openclaw memory index --force` -你还可以使用 `memorySearch.extraPaths` 为工作区外的 Markdown 文件建立索引。参见 -[配置参考](/zh-CN/reference/memory-config#additional-memory-paths)。 +你也可以使用 `memorySearch.extraPaths` 为工作区外部的 Markdown 文件建立索引。参见[配置参考](/zh-CN/reference/memory-config#additional-memory-paths)。 ## 何时使用 @@ -97,35 +96,33 @@ OpenClaw 会将 `MEMORY.md` 和 `memory/*.md` 索引为若干块（约 400 个 t - 支持所有嵌入提供商。 - 混合搜索结合了两种检索方式的优势。 -如果你需要重排序、查询扩展，或者希望为工作区外的目录建立索引，可以考虑切换到 [QMD](/zh-CN/concepts/memory-qmd)。 +如果你需要重排、查询扩展，或者想为工作区外的目录建立索引，可以考虑切换到 [QMD](/zh-CN/concepts/memory-qmd)。 -如果你希望获得跨会话记忆以及自动用户建模，可以考虑 [Honcho](/zh-CN/concepts/memory-honcho)。 +如果你想要带有自动用户建模的跨会话记忆，可以考虑 [Honcho](/zh-CN/concepts/memory-honcho)。 ## 故障排除 -**记忆搜索被禁用？** 检查 `openclaw memory status`。如果未检测到提供商，请显式设置一个，或添加 API 密钥。 +**Memory 搜索已禁用？** 检查 `openclaw memory status`。如果未检测到提供商，请显式设置一个提供商或添加 API 密钥。 -**未检测到本地提供商？** 确认本地路径存在，并运行： +**未检测到本地提供商？** 确认本地路径存在，然后运行： ```bash openclaw memory status --deep --agent main openclaw memory index --force --agent main ``` -独立 CLI 命令和 Gateway 网关使用相同的 `local` 提供商 ID。 -当提供商设置为 `auto` 时，只有在 `memorySearch.local.modelPath` 指向一个现有本地文件的情况下，才会优先考虑本地嵌入。 +独立的 CLI 命令和 Gateway 网关 都使用相同的 `local` 提供商 ID。如果提供商设置为 `auto`，只有当 `memorySearch.local.modelPath` 指向一个存在的本地文件时，才会优先考虑本地嵌入。 -**结果过时？** 运行 `openclaw memory index --force` 以重建索引。监视器在极少数边缘情况下可能会漏掉变更。 +**结果过时？** 运行 `openclaw memory index --force` 进行重建。监听器在极少数边界情况下可能会漏掉更改。 -**sqlite-vec 无法加载？** OpenClaw 会自动回退到进程内余弦相似度计算。请检查日志以查看具体加载错误。 +**sqlite-vec 无法加载？** OpenClaw 会自动回退到进程内余弦相似度计算。请检查日志以获取具体的加载错误。 ## 配置 -有关嵌入提供商设置、混合搜索调优（权重、MMR、时间衰减）、批量索引、多模态记忆、sqlite-vec、额外路径以及所有其他配置项，请参见 -[记忆配置参考](/zh-CN/reference/memory-config)。 +有关嵌入提供商设置、混合搜索调优（权重、MMR、时间衰减）、批量索引、多模态 Memory、sqlite-vec、额外路径以及所有其他配置项，请参见 [Memory 配置参考](/zh-CN/reference/memory-config)。 ## 相关内容 -- [记忆概览](/zh-CN/concepts/memory) -- [记忆搜索](/zh-CN/concepts/memory-search) -- [活跃记忆](/zh-CN/concepts/active-memory) +- [Memory 概览](/zh-CN/concepts/memory) +- [Memory 搜索](/zh-CN/concepts/memory-search) +- [Active memory](/zh-CN/concepts/active-memory) diff --git a/docs/zh-CN/concepts/memory-qmd.md b/docs/zh-CN/concepts/memory-qmd.md index 24c80e317..3cb13abb3 100644 --- a/docs/zh-CN/concepts/memory-qmd.md +++ b/docs/zh-CN/concepts/memory-qmd.md @@ -1,27 +1,27 @@ --- read_when: - - 你想将 QMD 设置为你的记忆后端 - - 你想要高级记忆功能，例如重排或额外的索引路径 -summary: 本地优先的搜索 sidecar，具备 BM25、向量、重排和查询扩展功能 -title: QMD 记忆引擎 + - 你想将 QMD 设置为你的 memory 后端 + - 你想要高级 memory 功能，例如重排序或额外的索引路径 +summary: 本地优先的搜索 sidecar，具备 BM25、向量、重排序和查询扩展功能 +title: QMD memory 引擎 x-i18n: - generated_at: "2026-04-23T22:56:50Z" + generated_at: "2026-04-25T07:22:21Z" model: gpt-5.4 provider: openai - source_hash: 7d7af326291e194a04a17aa425901bf7e2517c23bae8282cd504802d24e9e522 + source_hash: 89e6a5e0c8f5fb8507dffd08975fec0ca6fda03883079a27c2a28a1d09e95368 source_path: concepts/memory-qmd.md workflow: 15 --- -[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 一同运行。它将 BM25、向量搜索和重排组合进同一个二进制文件中，并且可以索引超出你的工作区记忆文件范围的内容。 +[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到同一个二进制中，并且可以为超出你的工作区 memory 文件范围的内容建立索引。 -## 相比内置功能增加了什么 +## 相比 builtin 增加了什么 -- **重排和查询扩展**，以获得更好的召回效果。 -- **索引额外目录** —— 项目文档、团队笔记、磁盘上的任何内容。 -- **索引会话转录** —— 回忆更早的对话。 -- **完全本地** —— 通过 Bun + node-llama-cpp 运行，并自动下载 GGUF 模型。 -- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到内置引擎。 +- **重排序和查询扩展**，以获得更好的召回效果。 +- **为额外目录建立索引** —— 项目文档、团队笔记、磁盘上的任何内容。 +- **为会话转录建立索引** —— 回忆更早的对话。 +- **完全本地** —— 使用可选的 `node-llama-cpp` 运行时包，并自动下载 GGUF 模型。 +- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到 builtin 引擎。 ## 入门指南 @@ -29,8 +29,8 @@ x-i18n: - 安装 QMD：`npm install -g @tobilu/qmd` 或 `bun install -g @tobilu/qmd` - 支持扩展的 SQLite 构建版本（在 macOS 上使用 `brew install sqlite`）。 -- QMD 必须位于 Gateway 网关的 `PATH` 中。 -- macOS 和 Linux 可开箱即用。Windows 最佳支持方式是通过 WSL2。 +- QMD 必须存在于 Gateway 网关的 `PATH` 中。 +- macOS 和 Linux 开箱即用。Windows 最适合通过 WSL2 使用。 ### 启用 @@ -42,25 +42,23 @@ x-i18n: } ``` -OpenClaw 会在 `~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会由它为你处理。 -它会优先使用当前的 QMD collection 和 MCP 查询结构，但在需要时仍会回退到旧版 `--mask` collection 标志和较早的 MCP 工具名称。 -启动时的协调还会在检测到存在同名旧 QMD collection 时，将过时的受管集合重新创建为其规范模式。 +OpenClaw 会在 `~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会由它处理。它会优先使用当前的 QMD 集合和 MCP 查询形态，但在需要时仍会回退到旧版的 `--mask` 集合标志和更旧的 MCP 工具名称。启动时的协调流程还会在检测到存在同名旧版 QMD 集合时，将过期的托管集合重新创建为其规范模式。 ## sidecar 的工作方式 -- OpenClaw 会根据你的工作区记忆文件以及任何已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地（默认为每 5 分钟）运行 `qmd update` + `qmd embed`。 -- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会被索引为根记忆文件。 -- 启动刷新会在后台运行，因此不会阻塞聊天启动。 -- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。如果某个模式失败，OpenClaw 会使用 `qmd query` 重试。 -- 如果 QMD 完全失败，OpenClaw 会回退到内置 SQLite 引擎。 +- OpenClaw 会根据你的工作区 memory 文件以及所有已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地（默认每 5 分钟）运行 `qmd update` + `qmd embed`。 +- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会作为根 memory 文件建立索引。 +- 启动时刷新会在后台运行，因此不会阻塞聊天启动。 +- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。如果某种模式失败，OpenClaw 会使用 `qmd query` 重试。 +- 如果 QMD 完全失败，OpenClaw 会回退到 builtin SQLite 引擎。 -首次搜索可能会很慢 —— QMD 会在首次运行 `qmd query` 时自动下载用于重排和查询扩展的 GGUF 模型（约 2 GB）。 +第一次搜索可能会很慢 —— QMD 会在首次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。 ## 模型覆盖 -QMD 模型环境变量会原样从 Gateway 网关进程透传，因此你可以在不添加新的 OpenClaw 配置的情况下全局调优 QMD： +QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以在不新增 OpenClaw 配置的情况下全局调优 QMD： ```bash export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf" @@ -68,11 +66,11 @@ export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf" export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" ``` -更改嵌入模型后，请重新运行嵌入，使索引与新的向量空间匹配。 +更改嵌入模型后，请重新运行嵌入，以确保索引与新的向量空间匹配。 -## 索引额外路径 +## 为额外路径建立索引 -将 QMD 指向其他目录，以便让它们也可搜索： +将 QMD 指向其他目录，使其可被搜索： ```json5 { @@ -85,9 +83,9 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -来自额外路径的片段会在搜索结果中显示为 `qmd//`。`memory_get` 能识别这个前缀，并从正确的 collection 根目录读取。 +来自额外路径的片段会在搜索结果中显示为 `qmd//`。`memory_get` 能理解这个前缀，并从正确的集合根目录读取内容。 -## 索引会话转录 +## 为会话转录建立索引 启用会话索引以回忆更早的对话： @@ -102,11 +100,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -转录会作为经过清理的用户/助手轮次导出到专用的 QMD collection 中，位置为 `~/.openclaw/agents//qmd/sessions/`。 +转录内容会作为经过净化的用户 / 助手轮次导出到位于 `~/.openclaw/agents//qmd/sessions/` 下的专用 QMD 集合中。 ## 搜索范围 -默认情况下，QMD 搜索结果会显示在私聊和渠道会话中（不包括群组）。可配置 `memory.qmd.scope` 来更改这一点： +默认情况下，QMD 搜索结果会显示在直接会话和渠道会话中（不包括群组）。通过配置 `memory.qmd.scope` 来更改此行为： ```json5 { @@ -121,46 +119,45 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -当范围规则拒绝某次搜索时，OpenClaw 会记录一条警告，其中包含推导出的渠道和聊天类型，以便更容易调试空结果。 +当范围规则拒绝某次搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，以便更容易调试空结果问题。 ## 引用 -当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含 `Source: ` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍在内部将路径传递给智能体。 +当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含一个 `Source: ` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍在内部将路径传递给智能体。 ## 何时使用 当你需要以下能力时，请选择 QMD： -- 通过重排获得更高质量的结果。 -- 搜索工作区之外的项目文档或笔记。 +- 使用重排序获得更高质量的结果。 +- 搜索工作区外的项目文档或笔记。 - 回忆过去的会话对话。 -- 完全本地搜索，无需 API 密钥。 +- 完全本地的搜索，无需 API 密钥。 -对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在没有额外依赖的情况下也能很好地工作。 +对于更简单的设置，[builtin 引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。 ## 故障排除 -**找不到 QMD？** 请确保该二进制文件位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接： +**找不到 QMD？** 确保该二进制位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接： `sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`。 -**首次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录运行 `qmd query "test"` 进行预热。 +**第一次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录运行 `qmd query "test"` 进行预热。 **搜索超时？** 增加 `memory.qmd.limits.timeoutMs`（默认：4000ms）。对于较慢的硬件，可设置为 `120000`。 -**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认只允许私聊和渠道会话。 +**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认只允许直接会话和渠道会话。 -**根记忆搜索突然变得过宽？** 重启 Gateway 网关，或等待下一次启动协调。OpenClaw 在检测到同名冲突时，会将过时的受管集合重新创建回规范的 `MEMORY.md` 和 `memory/` 模式。 +**根 memory 搜索突然变得过于宽泛？** 重启 Gateway 网关，或等待下一次启动协调。OpenClaw 会在检测到同名冲突时，将过期的托管集合重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。 -**工作区中可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** -QMD 当前的遍历遵循底层 QMD 扫描器行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 暴露出防循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在 `.tmp/` 之类的隐藏目录下，或放在已索引 QMD 根目录之外。 +**工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** QMD 当前的遍历行为遵循底层 QMD 扫描器的行为，而不是 OpenClaw builtin 的符号链接规则。在 QMD 提供具备循环安全的遍历或显式排除控制之前，请将临时 monorepo 检出保存在 `.tmp/` 这样的隐藏目录下，或放在已建立索引的 QMD 根目录之外。 ## 配置 -有关完整配置表面（`memory.qmd.*`）、搜索模式、更新间隔、范围规则及所有其他旋钮，请参见 -[记忆配置参考](/zh-CN/reference/memory-config)。 +如需查看完整的配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及其他所有可调参数，请参阅 +[Memory 配置参考](/zh-CN/reference/memory-config)。 ## 相关内容 -- [记忆概览](/zh-CN/concepts/memory) -- [内置记忆引擎](/zh-CN/concepts/memory-builtin) -- [Honcho 记忆](/zh-CN/concepts/memory-honcho) +- [Memory 概览](/zh-CN/concepts/memory) +- [Builtin memory 引擎](/zh-CN/concepts/memory-builtin) +- [Honcho memory](/zh-CN/concepts/memory-honcho) diff --git a/docs/zh-CN/concepts/memory-search.md b/docs/zh-CN/concepts/memory-search.md index 6b9d1b991..5e62a15ab 100644 --- a/docs/zh-CN/concepts/memory-search.md +++ b/docs/zh-CN/concepts/memory-search.md @@ -1,49 +1,49 @@ --- read_when: - - 你想了解 `memory_search` 的工作原理 + - 你想了解 `memory_search` 是如何工作的 - 你想选择一个嵌入提供商 - - 你想调优搜索质量 + - 你想调整搜索质量 summary: 记忆搜索如何使用嵌入和混合检索来查找相关笔记 title: 记忆搜索 x-i18n: - generated_at: "2026-04-23T22:56:51Z" + generated_at: "2026-04-25T07:22:21Z" model: gpt-5.4 provider: openai - source_hash: 04db62e519a691316ce40825c082918094bcaa9c36042cc8101c6504453d238e + source_hash: 5cc6bbaf7b0a755bbe44d3b1b06eed7f437ebdc41a81c48cca64bd08bbc546b7 source_path: concepts/memory-search.md workflow: 15 --- -`memory_search` 会从你的记忆文件中查找相关笔记，即使措辞与原文不同也可以。它通过将记忆索引为小块，并使用嵌入、关键词或两者结合来进行搜索。 +`memory_search` 会从你的记忆文件中查找相关笔记，即使措辞与原始文本不同也可以。它通过将记忆索引为小块，并使用嵌入、关键词或两者结合来搜索这些内容。 ## 快速开始 -如果你已配置 GitHub Copilot 订阅，或 OpenAI、Gemini、Voyage、Mistral 的 API key，记忆搜索会自动生效。若要显式设置提供商： +如果你已配置 GitHub Copilot 订阅、OpenAI、Gemini、Voyage 或 Mistral 的 API key，记忆搜索会自动生效。要显式设置提供商： ```json5 { agents: { defaults: { memorySearch: { - provider: "openai", // or "gemini", "local", "ollama", etc. + provider: "openai", // 或 "gemini"、"local"、"ollama" 等 }, }, }, } ``` -对于不使用 API key 的本地嵌入，请使用 `provider: "local"`（需要 `node-llama-cpp`）。 +如果你想使用无需 API key 的本地嵌入，请在 OpenClaw 旁边安装可选的 `node-llama-cpp` 运行时包，并使用 `provider: "local"`。 ## 支持的提供商 | 提供商 | ID | 需要 API key | 说明 | | -------------- | ---------------- | ------------- | ---------------------------------------------------- | -| Bedrock | `bedrock` | 否 | 当 AWS 凭证链可解析时自动检测 | +| Bedrock | `bedrock` | 否 | 当 AWS 凭证链解析成功时自动检测 | | Gemini | `gemini` | 是 | 支持图像/音频索引 | | GitHub Copilot | `github-copilot` | 否 | 自动检测，使用 Copilot 订阅 | | Local | `local` | 否 | GGUF 模型，下载大小约 0.6 GB | | Mistral | `mistral` | 是 | 自动检测 | -| Ollama | `ollama` | 否 | 本地提供商，必须显式设置 | +| Ollama | `ollama` | 否 | 本地，必须显式设置 | | OpenAI | `openai` | 是 | 自动检测，速度快 | | Voyage | `voyage` | 是 | 自动检测 | @@ -62,28 +62,28 @@ flowchart LR M --> R["Top Results"] ``` -- **向量搜索** 用于查找语义相近的笔记（例如 “gateway host” 可匹配 “the machine running OpenClaw”）。 -- **BM25 关键词搜索** 用于查找精确匹配项（ID、错误字符串、配置键）。 +- **向量搜索** 会查找语义相近的笔记（“gateway host” 可匹配 “the machine running OpenClaw”）。 +- **BM25 关键词搜索** 会查找精确匹配（ID、错误字符串、配置键）。 -如果只有一条路径可用（没有嵌入或没有 FTS），则仅运行另一条路径。 +如果只有一条路径可用（没有嵌入或没有 FTS），则只运行另一条路径。 -当嵌入不可用时，OpenClaw 仍会基于 FTS 结果使用词法排序，而不是只回退到原始精确匹配顺序。在这种降级模式下，它会提升查询词覆盖度更高且文件路径更相关的块，因此即使没有 `sqlite-vec` 或嵌入提供商，召回效果仍然可用。 +当嵌入不可用时，OpenClaw 仍会对 FTS 结果使用词法排序，而不是只退回到原始精确匹配顺序。这种降级模式会提升那些查询词覆盖更强、文件路径更相关的内容块，因此即使没有 `sqlite-vec` 或嵌入提供商，也能保持较好的召回效果。 -## 提升搜索质量 +## 改进搜索质量 -当你有大量笔记历史时，两个可选功能会很有帮助： +当你拥有大量笔记历史时，有两个可选功能会很有帮助： ### 时间衰减 -旧笔记的排名权重会逐渐降低，因此最近的信息会优先显示。使用默认的 30 天半衰期时，上个月的笔记得分会降至原始权重的 50%。像 `MEMORY.md` 这样的常青文件永远不会衰减。 +旧笔记的排序权重会逐渐降低，因此最近的信息会优先显示。使用默认的 30 天半衰期时，上个月的笔记得分会降到原始权重的 50%。像 `MEMORY.md` 这样的常青文件永远不会衰减。 -如果你的智能体已有数月的每日笔记，并且过时信息总是排在最新上下文前面，请启用时间衰减。 +如果你的智能体已经积累了数月的每日笔记，而过时信息总是排在最近上下文之前，请启用时间衰减。 ### MMR（多样性） -减少重复结果。如果有五条笔记都提到同一个路由器配置，MMR 会确保顶部结果覆盖不同主题，而不是重复展示。 +减少重复结果。如果五条笔记都提到了同一个路由器配置，MMR 会确保顶部结果覆盖不同主题，而不是重复相同内容。 如果 `memory_search` 总是从不同的每日笔记中返回几乎重复的片段，请启用 MMR。 @@ -110,28 +110,28 @@ flowchart LR ## 多模态记忆 -通过 Gemini Embedding 2，你可以将图像和音频文件与 Markdown 一起建立索引。搜索查询仍然是文本，但它们会匹配视觉和音频内容。设置方法请参见[记忆配置参考](/zh-CN/reference/memory-config)。 +使用 Gemini Embedding 2 时，你可以在 Markdown 之外为图像和音频文件建立索引。搜索查询仍然是文本，但会匹配视觉和音频内容。设置方法请参阅[记忆配置参考](/zh-CN/reference/memory-config)。 ## 会话记忆搜索 -你也可以选择为会话转录建立索引，这样 `memory_search` 就能回忆更早的对话。这是通过 `memorySearch.experimental.sessionMemory` 主动启用的。详见[配置参考](/zh-CN/reference/memory-config)。 +你还可以选择为会话转录建立索引，这样 `memory_search` 就能回忆更早的对话。这是通过 `memorySearch.experimental.sessionMemory` 选择启用的。详情请参阅[配置参考](/zh-CN/reference/memory-config)。 ## 故障排除 **没有结果？** 运行 `openclaw memory status` 检查索引。如果为空，运行 `openclaw memory index --force`。 -**只有关键词匹配？** 你的嵌入提供商可能未配置。检查 `openclaw memory status --deep`。 +**只有关键词匹配？** 你的嵌入提供商可能尚未配置。检查 `openclaw memory status --deep`。 **找不到 CJK 文本？** 使用 `openclaw memory index --force` 重建 FTS 索引。 ## 延伸阅读 - [Active Memory](/zh-CN/concepts/active-memory) -- 用于交互式聊天会话的子智能体记忆 -- [记忆](/zh-CN/concepts/memory) -- 文件布局、后端、工具 +- [Memory](/zh-CN/concepts/memory) -- 文件布局、后端、工具 - [记忆配置参考](/zh-CN/reference/memory-config) -- 所有配置项 -## 相关 +## 相关内容 - [记忆概览](/zh-CN/concepts/memory) -- [Active Memory](/zh-CN/concepts/active-memory) +- [Active memory](/zh-CN/concepts/active-memory) - [内置记忆引擎](/zh-CN/concepts/memory-builtin) diff --git a/docs/zh-CN/logging.md b/docs/zh-CN/logging.md index 84ecf471f..14a2bafb2 100644 --- a/docs/zh-CN/logging.md +++ b/docs/zh-CN/logging.md @@ -6,26 +6,26 @@ read_when: summary: 日志概览：文件日志、控制台输出、CLI 尾随查看，以及 Control UI title: 日志概览 x-i18n: - generated_at: "2026-04-25T07:01:13Z" + generated_at: "2026-04-25T07:22:21Z" model: gpt-5.4 provider: openai - source_hash: 7f9593b117ef2ba76dbe91d5b38e3f463b358631961c9d44beed3aee6152f9a2 + source_hash: c1a8ec7992c0c1b59036ccfd2b6d1d844c68f78cec14ff8eebddeac67f3fc607 source_path: logging.md workflow: 15 --- # 日志 -OpenClaw 有两个主要的日志界面： +OpenClaw 有两个主要的日志表面： - 由 Gateway 网关写入的**文件日志**（JSON 行）。 - 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。 -Control UI 的**日志**标签页会尾随显示 gateway 文件日志。本页说明日志位于哪里、如何读取，以及如何配置日志级别和格式。 +Control UI 的**日志**标签页会尾随显示 gateway 文件日志。此页面会说明日志位于哪里、如何读取日志，以及如何配置日志级别和格式。 -## 日志位置 +## 日志存放位置 -默认情况下，Gateway 网关会将滚动日志文件写入以下位置： +默认情况下，Gateway 网关会在以下位置写入滚动日志文件： `/tmp/openclaw/openclaw-YYYY-MM-DD.log` @@ -51,32 +51,32 @@ Control UI 的**日志**标签页会尾随显示 gateway 文件日志。本页 openclaw logs --follow ``` -当前实用选项： +当前有用的选项： -- `--local-time`：使用你的本地时区渲染时间戳 +- `--local-time`：使用你的本地时区显示时间戳 - `--url ` / `--token ` / `--timeout `：标准 Gateway 网关 RPC 标志 -- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（此处通过共享客户端层接受） +- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（通过共享客户端层在此处接受） 输出模式： -- **TTY 会话**：美观、彩色、结构化的日志行。 +- **TTY 会话**：美观、带颜色、结构化的日志行。 - **非 TTY 会话**：纯文本。 - `--json`：按行分隔的 JSON（每行一个日志事件）。 - `--plain`：在 TTY 会话中强制使用纯文本。 - `--no-color`：禁用 ANSI 颜色。 -当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要身份验证，请自行包含 `--token`。 +当你显式传入 `--url` 时，CLI 不会自动应用配置或环境变量中的凭证；如果目标 Gateway 网关需要认证，请自行附带 `--token`。 -在 JSON 模式下，CLI 会输出带 `type` 标签的对象： +在 JSON 模式下，CLI 会输出带 `type` 标记的对象： - `meta`：流元数据（文件、游标、大小） - `log`：已解析的日志条目 - `notice`：截断 / 轮转提示 - `raw`：未解析的原始日志行 -如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式 `--url` 目标不会使用此回退。 +如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式指定的 `--url` 目标不会使用此回退机制。 -如果 Gateway 网关不可达，CLI 会打印一条简短提示，建议运行： +如果 Gateway 网关无法连接，CLI 会打印一个简短提示，建议运行： ```bash openclaw doctor @@ -84,7 +84,7 @@ openclaw doctor ### Control UI（网页） -Control UI 的**日志**标签页会使用 `logs.tail` 尾随查看同一个文件。 +Control UI 的**日志**标签页使用 `logs.tail` 尾随查看同一个文件。 有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。 ### 仅渠道日志 @@ -103,7 +103,7 @@ openclaw channels logs --channel whatsapp ### 控制台输出 -控制台日志是**TTY 感知的**，并针对可读性进行了格式化： +控制台日志是**感知 TTY** 的，并针对可读性进行了格式化： - 子系统前缀（例如 `gateway/channels/whatsapp`） - 级别颜色（info/warn/error） @@ -113,11 +113,11 @@ openclaw channels logs --channel whatsapp ### Gateway 网关 WebSocket 日志 -`openclaw gateway` 还支持用于 RPC 流量的 WebSocket 协议日志： +`openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志： -- 普通模式：仅显示重要结果（错误、解析错误、慢调用） -- `--verbose`：显示所有请求 / 响应流量 -- `--ws-log auto|compact|full`：选择详细日志的渲染样式 +- 普通模式：仅显示值得关注的结果（错误、解析错误、慢调用） +- `--verbose`：显示所有请求/响应流量 +- `--ws-log auto|compact|full`：选择详细输出的渲染样式 - `--compact`：`--ws-log compact` 的别名 示例： @@ -128,9 +128,9 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## 配置日志记录 +## 配置日志 -所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。 +所有日志配置都位于 `~/.openclaw/openclaw.json` 中的 `logging` 下。 ```json { @@ -150,7 +150,7 @@ openclaw gateway --verbose --ws-log full - `logging.level`：**文件日志**（JSONL）级别。 - `logging.consoleLevel`：**控制台**详细程度级别。 -你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level `**（例如，`openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。 +你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传入全局 CLI 选项 **`--log-level `**（例如，`openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。 `--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 @@ -159,48 +159,48 @@ openclaw gateway --verbose --ws-log full `logging.consoleStyle`： - `pretty`：适合人工阅读、带颜色、带时间戳。 -- `compact`：更紧凑的输出（最适合长时间会话）。 -- `json`：每行一个 JSON（用于日志处理器）。 +- `compact`：更紧凑的输出（适合长时间会话）。 +- `json`：每行一个 JSON（适用于日志处理器）。 ### 脱敏 -工具摘要可以在输出到控制台之前，对敏感令牌进行脱敏： +工具摘要在输出到控制台之前可以对敏感令牌进行脱敏： - `logging.redactSensitive`：`off` | `tools`（默认：`tools`） - `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表 脱敏**仅影响控制台输出**，不会修改文件日志。 -## Diagnostics + OpenTelemetry +## 诊断 + OpenTelemetry -诊断是面向模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了向指标、追踪和其他导出器提供数据。 +诊断是用于模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了向指标、追踪和其他导出器提供数据。 诊断事件会在进程内发出，但只有在启用 diagnostics 和导出器插件后，导出器才会附加。 -### OpenTelemetry 与 OTLP +### OpenTelemetry 与 OTLP 的区别 - **OpenTelemetry（OTel）**：用于追踪、指标和日志的数据模型 + SDK。 -- **OTLP**：用于将 OTel 数据导出到采集器 / 后端的线协议。 +- **OTLP**：用于将 OTel 数据导出到收集器 / 后端的线协议。 - OpenClaw 当前通过 **OTLP/HTTP（protobuf）** 导出。 ### 导出的信号 -- **指标**：计数器 + 直方图（令牌使用、消息流、排队）。 -- **追踪**：用于模型使用和 webhook / 消息处理的 span。 -- **日志**：当启用 `diagnostics.otel.logs` 时，通过 OTLP 导出。日志量可能很大；请留意 `logging.level` 和导出器过滤器。 +- **指标**：计数器 + 直方图（令牌使用量、消息流、排队）。 +- **追踪**：用于模型使用 + webhook / 消息处理的 span。 +- **日志**：当启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请留意 `logging.level` 和导出器过滤器。 ### 诊断事件目录 模型使用： -- `model.usage`：令牌、成本、持续时间、上下文、provider / 模型 / 渠道、会话 id。 +- `model.usage`：令牌、成本、持续时间、上下文、提供商 / 模型 / 渠道、会话 ID。 消息流： -- `webhook.received`：每个渠道的 webhook 入站。 +- `webhook.received`：按渠道统计的 webhook 入站。 - `webhook.processed`：webhook 已处理 + 持续时间。 - `webhook.error`：webhook 处理器错误。 -- `message.queued`：消息已入队等待处理。 +- `message.queued`：消息已加入处理队列。 - `message.processed`：结果 + 持续时间 + 可选错误。 队列 + 会话： @@ -208,13 +208,17 @@ openclaw gateway --verbose --ws-log full - `queue.lane.enqueue`：命令队列 lane 入队 + 深度。 - `queue.lane.dequeue`：命令队列 lane 出队 + 等待时间。 - `session.state`：会话状态转换 + 原因。 -- `session.stuck`：会话卡住警告 + 已持续时长。 +- `session.stuck`：会话卡住警告 + 持续时长。 - `run.attempt`：运行重试 / 尝试元数据。 -- `diagnostic.heartbeat`：聚合计数器（webhooks / queue / session）。 +- `diagnostic.heartbeat`：聚合计数器（webhook / 队列 / 会话）。 + +执行： + +- `exec.process.completed`：终端 exec 进程结果、持续时间、目标、模式、退出码和失败类型。不包含命令文本和工作目录。 ### 启用 diagnostics（无导出器） -如果你希望 diagnostics 事件可供插件或自定义接收器使用，请使用此配置： +如果你希望 diagnostics 事件可供插件或自定义接收端使用，请使用此配置： ```json { @@ -224,10 +228,9 @@ openclaw gateway --verbose --ws-log full } ``` -### Diagnostics 标志（定向日志） +### diagnostics 标志（定向日志） -使用标志启用额外的、定向的调试日志，而无需提高 `logging.level`。 -标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。 +使用标志可以在不提高 `logging.level` 的情况下开启额外的定向调试日志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。 ```json { @@ -245,14 +248,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload 说明： -- 标志日志会进入标准日志文件（与 `logging.file` 相同）。 -- 输出仍会按照 `logging.redactSensitive` 进行脱敏。 +- 标志日志会写入标准日志文件（与 `logging.file` 相同）。 +- 输出仍会根据 `logging.redactSensitive` 进行脱敏。 - 完整指南：[/diagnostics/flags](/zh-CN/diagnostics/flags)。 ### 导出到 OpenTelemetry -Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。 -这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 采集器 / 后端。 +可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出 diagnostics。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器 / 后端。 ```json { @@ -293,14 +295,14 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。 - 你也可以使用 `openclaw plugins enable diagnostics-otel` 启用该插件。 - `protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。 -- 指标包括令牌使用、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhooks、排队、会话状态、队列深度 / 等待）。 -- 可以通过 `traces` / `metrics` 切换追踪 / 指标（默认：开启）。启用时，追踪包括模型使用 span，以及 webhook / 消息处理 span。 -- 默认不会导出原始模型 / 工具内容。仅当你的采集器和保留策略已获批准，可处理提示词、响应、工具或系统提示词文本时，才使用 `diagnostics.otel.captureContent`。 -- 当你的采集器需要身份验证时，请设置 `headers`。 +- 指标包括令牌使用量、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhook、排队、会话状态、队列深度 / 等待时间）。 +- 可以使用 `traces` / `metrics` 开关来控制是否导出追踪 / 指标（默认：开启）。启用后，追踪包括模型使用 span，以及 webhook / 消息处理 span。 +- 默认不会导出原始模型 / 工具内容。仅当你的收集器和保留策略已批准保存提示词、响应、工具或系统提示文本时，才使用 `diagnostics.otel.captureContent`。 +- 当你的收集器需要认证时，请设置 `headers`。 - 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。 -- 当另一个预加载项或宿主进程已经注册了全局 OpenTelemetry SDK 时，请设置 `OPENCLAW_OTEL_PRELOADED=1`。在该模式下，插件不会启动或关闭其自己的 SDK，但它仍会连接 OpenClaw 诊断监听器，并遵循 `diagnostics.otel.traces`、`metrics` 和 `logs`。 +- 当另一个预加载项或宿主进程已经注册全局 OpenTelemetry SDK 时，设置 `OPENCLAW_OTEL_PRELOADED=1`。在该模式下，插件不会启动或关闭它自己的 SDK，但仍会连接 OpenClaw 诊断监听器，并遵循 `diagnostics.otel.traces`、`metrics` 和 `logs`。 -### 导出的指标（名称 + 类型） +### 已导出的指标（名称 + 类型） 模型使用： @@ -329,7 +331,11 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。 - `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`） - `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`） -### 导出的 span（名称 + 关键属性） +执行： + +- `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`） + +### 已导出的 span（名称 + 关键属性） - `openclaw.model.usage` - `openclaw.channel`、`openclaw.provider`、`openclaw.model` @@ -344,6 +350,10 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。 - `openclaw.tool.execution` - `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、 `openclaw.tool.params.*` +- `openclaw.exec` + - `openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、 + `openclaw.failureKind`、`openclaw.exec.command_length`、 + `openclaw.exec.exit_code`、`openclaw.exec.timed_out` - `openclaw.webhook.processed` - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId` - `openclaw.webhook.error` @@ -355,7 +365,7 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。 - `openclaw.session.stuck` - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth` -当显式启用内容捕获时，模型 / 工具 span 还可以包含有界且已脱敏的 `openclaw.content.*` 属性，适用于你明确选择启用的特定内容类别。 +当显式启用内容捕获时，模型 / 工具 span 还可以包含有界且已脱敏的 `openclaw.content.*` 属性，用于你选择启用的特定内容类别。 ### 采样 + 刷新 @@ -364,12 +374,12 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。 ### 协议说明 -- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或 - `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。 +- 可以通过 `diagnostics.otel.endpoint` 或 + `OTEL_EXPORTER_OTLP_ENDPOINT` 设置 OTLP/HTTP 端点。 - 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则会按原样使用。 -- 如果端点已包含 `/v1/logs`，则日志也会按原样使用该端点。 +- 如果端点已包含 `/v1/logs`，则会按原样用于日志。 - `OPENCLAW_OTEL_PRELOADED=1` 会复用外部已注册的 OpenTelemetry SDK - 来处理追踪 / 指标，而不是启动由插件拥有的 NodeSDK。 + 用于追踪 / 指标，而不是启动由插件拥有的 NodeSDK。 - `diagnostics.otel.logs` 会为主日志记录器输出启用 OTLP 日志导出。 ### 日志导出行为 @@ -377,13 +387,13 @@ Diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。 - OTLP 日志使用与写入 `logging.file` 相同的结构化记录。 - 遵循 `logging.level`（文件日志级别）。控制台脱敏**不会**应用于 OTLP 日志。 -- 高日志量的部署应优先使用 OTLP 采集器的采样 / 过滤功能。 +- 对于高流量安装，应该优先使用 OTLP 收集器采样 / 过滤。 ## 故障排除提示 -- **Gateway 网关不可达？** 先运行 `openclaw doctor`。 -- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在写入 `logging.file` - 中的文件路径。 +- **Gateway 网关无法连接？** 请先运行 `openclaw doctor`。 +- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在向 + `logging.file` 中的文件路径写入。 - **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。 ## 相关内容 diff --git a/docs/zh-CN/plugins/google-meet.md b/docs/zh-CN/plugins/google-meet.md index 35182644c..a753bff8f 100644 --- a/docs/zh-CN/plugins/google-meet.md +++ b/docs/zh-CN/plugins/google-meet.md @@ -1,36 +1,37 @@ --- read_when: - - 你希望一个 OpenClaw 智能体加入 Google Meet 通话 - - 你希望一个 OpenClaw 智能体创建一个新的 Google Meet 通话 + - 你想让一个 OpenClaw 智能体加入 Google Meet 通话 + - 你想让一个 OpenClaw 智能体创建新的 Google Meet 通话 - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输方式 -summary: Google Meet 插件：通过 Chrome 或 Twilio 加入显式的 Meet URL，并默认启用实时语音 +summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确的 Meet URL，并使用默认的实时语音设置 title: Google Meet 插件 x-i18n: - generated_at: "2026-04-25T07:07:51Z" + generated_at: "2026-04-25T07:22:35Z" model: gpt-5.4 provider: openai - source_hash: 16291e144ff60b88af8ca182d5b67233af1ff3b00ea414fae18c46fb2ef909fb + source_hash: e03741b598614233496d208b2fff85077f31a4c37814c1c915dc6d6fda32ef2e source_path: plugins/google-meet.md workflow: 15 --- -OpenClaw 的 Google Meet 参与者支持——该插件在设计上是显式的： +OpenClaw 的 Google Meet 参会支持——该插件在设计上就是显式的： -- 它只会加入显式的 `https://meet.google.com/...` URL。 -- 它可以通过 Google Meet API 创建一个新的 Meet 空间，然后加入返回的 URL。 +- 它只会加入明确的 `https://meet.google.com/...` 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` 保留给更广义的智能体电话会议工作流。 +- 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 @@ -39,13 +40,13 @@ 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,9 +74,9 @@ command -v rec play openclaw googlemeet setup ``` -设置输出旨在便于智能体读取。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟的实时介绍，以及在配置了 Twilio 委托时，`voice-call` 插件和 Twilio 凭证是否已就绪。 -将任何 `ok: false` 的检查都视为阻塞项，在要求智能体加入之前先解决。 -脚本或机器可读输出请使用 `openclaw googlemeet setup --json`。 +设置输出旨在让智能体可读。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟实时介绍，以及在配置了 Twilio 委派时，`voice-call` 插件和 Twilio 凭证是否已就绪。 +在要求智能体加入之前，应将任何 `ok: false` 检查视为阻塞项。 +对脚本或机器可读输出，请使用 `openclaw googlemeet setup --json`。 加入会议： @@ -94,13 +95,13 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij } ``` -创建一个新会议并加入： +创建新会议并加入： ```bash openclaw googlemeet create --transport chrome-node --mode realtime ``` -仅创建 URL 而不加入： +只创建 URL 而不加入： ```bash openclaw googlemeet create --no-join @@ -108,14 +109,17 @@ openclaw googlemeet create --no-join `googlemeet create` 有两条路径： -- API 创建：当配置了 Google Meet OAuth 凭证时使用。这是最可预测的路径，并且不依赖浏览器 UI 状态。 +- API 创建：当已配置 Google Meet OAuth 凭证时使用。这是最确定性的路径，不依赖浏览器 UI 状态。 - 浏览器回退：当缺少 OAuth 凭证时使用。OpenClaw 会使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。这条路径要求节点上的 OpenClaw Chrome 配置文件已经登录 Google。 - 浏览器自动化会处理 Meet 自身的首次运行麦克风提示；该提示不会被视为 Google 登录失败。 - 加入和创建流程也会尝试复用现有的 Meet 标签页，而不是新开一个。匹配时会忽略像 `authuser` 这样的无害 URL 查询字符串，因此智能体重试时应聚焦到已经打开的会议，而不是创建第二个 Chrome 标签页。 + 浏览器自动化会处理 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，用实时语音加入，然后把链接发给我。” 智能体应当使用 `action: "create"` 调用 `google_meet`，然后分享返回的 `meetingUri`。 +你也可以告诉智能体：“创建一个 Google Meet，用实时语音加入它，然后把链接发给我。” +智能体应使用 `action: "create"` 调用 `google_meet`，然后分享返回的 `meetingUri`。 ```json { @@ -125,17 +129,18 @@ openclaw googlemeet create --no-join } ``` -若只需观察/控制浏览器的加入方式，请设置 `"mode": "transcribe"`。这不会启动双向实时模型桥接，因此它不会在会议中回话。 +对于仅观察/浏览器控制的加入，请将 `"mode"` 设为 `"transcribe"`。这样不会启动双向实时模型桥接，因此它不会在会议中回话。 -在实时会话期间，`google_meet` 状态会包含浏览器和音频桥接的健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近的输入/输出时间戳、字节计数，以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可能时处理它。登录、主持人准入，以及浏览器/操作系统权限提示会作为手动操作报告，并附带原因和消息，供智能体转达。 +在实时会话期间，`google_meet` 状态会包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、 +`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可能时处理它。登录、主持人准入以及浏览器/操作系统权限提示会作为手动操作报告，并带有原因和消息，供智能体转达。 -Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选择 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。若要获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能会产生回声。 +Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选择 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足够完成首次冒烟测试，但可能会产生回声。 ### 本地 Gateway 网关 + Parallels Chrome -你**不**需要在 macOS VM 中运行完整的 OpenClaw Gateway 网关或配置模型 API 密钥，仅仅为了让 VM 托管 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会宣告 Chrome 命令： +你**不**需要在 macOS VM 中运行完整的 OpenClaw Gateway 网关或模型 API 密钥，仅仅为了让 VM 承担 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会通告 Chrome 命令： -各组件运行位置如下： +各组件运行位置： - Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型/API 密钥、实时提供商，以及 Google Meet 插件配置。 - Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及一个已登录 Google 的 Chrome 配置文件。 @@ -147,13 +152,13 @@ Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选 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 @@ -172,14 +177,14 @@ openclaw plugins enable google-meet openclaw node run --host --port 18789 --display-name parallels-macos ``` -如果 `` 是局域网 IP，且你没有使用 TLS，则除非你显式为该受信任私有网络启用明文 WebSocket，否则节点会拒绝连接： +如果 `` 是局域网 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 \ @@ -187,23 +192,24 @@ 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 ``` -在 Gateway 网关主机上将 Meet 路由到该节点： +在 Gateway 网关主机上通过该节点路由 Meet： ```json5 { @@ -233,7 +239,7 @@ openclaw nodes status } ``` -现在你就可以在 Gateway 网关主机上像平常一样加入： +现在你可以从 Gateway 网关主机正常加入： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -241,52 +247,60 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij 或者要求智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。 -如果你想做一个单命令冒烟测试，用来创建或复用会话、说出一段已知短语，并打印会话健康状态： +对于一个单命令冒烟测试，它会创建或复用会话、说出已知短语并打印会话健康状态： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -在加入过程中，OpenClaw 浏览器自动化会填写访客名称、点击“加入/请求加入”，并在出现时接受 Meet 首次运行的“使用麦克风”选择。在仅浏览器创建会议期间，如果 Meet 没有显示“使用麦克风”按钮，它也可以在不使用麦克风的情况下继续通过相同提示。 -如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或者 Meet 卡在某个自动化无法解决的提示上，则加入/`test-speech` 结果会报告 `manualActionRequired: true`，并附带 `manualActionReason` 和 `manualActionMessage`。智能体应停止重复重试加入，原样报告该消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后再重试。 +在加入期间，OpenClaw 浏览器自动化会填写访客名称，点击“加入/请求加入”，并在出现该提示时接受 Meet 首次运行的“使用麦克风”选项。在仅浏览器创建会议期间，如果 Meet 没有暴露使用麦克风按钮，它也可以在不启用麦克风的情况下继续通过同一个提示。 +如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或者 Meet 卡在自动化无法解决的提示上，那么加入/`test-speech` 结果会报告 +`manualActionRequired: true`，并包含 `manualActionReason` 和 +`manualActionMessage`。智能体应停止重试加入，报告该精确消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后重试。 -如果省略 `chromeNode.node`，OpenClaw 只有在恰好只有一个已连接节点同时宣告 `googlemeet.chrome` 和浏览器控制时，才会自动选择该节点。如果连接了多个具备能力的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。 +如果省略了 `chromeNode.node`，只有在恰好只有一个已连接节点同时通告 `googlemeet.chrome` 和浏览器控制时，OpenClaw 才会自动选择。 +如果连接了多个有能力的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。 常见故障检查： -- `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"]` 允许这两个节点命令。 +- `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 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 打开了但无法加入：在 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`：命令行音频工具。插件使用它的 `rec` 和 `play` 命令来实现默认的 8 kHz G.711 mu-law 音频桥接。 -- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch` 音频设备，供 Chrome/Meet 路由使用。 +- `sox`：命令行音频工具。插件使用它的 `rec` 和 `play` + 命令作为默认的 8 kHz G.711 mu-law 音频桥接。 +- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch` + 音频设备，供 Chrome/Meet 路由使用。 -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 传输方式会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 之前运行音频桥接健康检查命令和启动命令。当 Chrome/音频运行在 Gateway 网关主机上时使用 `chrome`；当 Chrome/音频运行在已配对节点（例如 Parallels macOS VM）上时使用 `chrome-node`。 +Chrome 传输方式会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查是否存在 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 前运行音频桥接健康检查命令和启动命令。当 Chrome/音频位于 Gateway 网关主机上时，请使用 `chrome`；当 Chrome/音频位于已配对节点（例如 Parallels macOS VM）上时，请使用 `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 节点上： @@ -313,7 +327,7 @@ Twilio 传输方式是一个严格的拨号计划，并委托给 Voice Call 插 } ``` -通过环境变量或配置提供 Twilio 凭证。环境变量可以让密钥不出现在 `openclaw.json` 中： +通过环境变量或配置提供 Twilio 凭证。使用环境变量可以让密钥不出现在 `openclaw.json` 中： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -321,9 +335,9 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -启用 `voice-call` 后，请重启或重新加载 Gateway 网关；在 Gateway 网关重新加载之前，已经运行中的 Gateway 网关进程不会看到插件配置更改。 +启用 `voice-call` 后，重启或重新加载 Gateway 网关；在 Gateway 网关进程重新加载之前，插件配置更改不会出现在已经运行的 Gateway 网关进程中。 -然后进行验证： +然后验证： ```bash openclaw config validate @@ -331,7 +345,8 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -当 Twilio 委托已正确接通时，`googlemeet setup` 会包含成功的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。 +当 Twilio 委派已正确接线时，`googlemeet setup` 会包含成功的 +`twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -351,11 +366,12 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth 和预检 -对于创建 Meet 链接来说，OAuth 是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你需要官方 API 创建、空间解析或 Meet Media API 预检时，再配置 OAuth。 +对于创建 Meet 链接来说，OAuth 是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你想使用官方 API 创建、空间解析或 Meet Media API 预检时，请配置 OAuth。 -Google Meet API 访问使用用户 OAuth：创建一个 Google Cloud OAuth 客户端，请求所需作用域，授权一个 Google 账号，然后将生成的刷新令牌存储到 Google Meet 插件配置中，或提供 `OPENCLAW_GOOGLE_MEET_*` 环境变量。 +Google Meet API 访问使用用户 OAuth：创建一个 Google Cloud OAuth 客户端，请求所需作用域，授权一个 Google 账户，然后将生成的刷新令牌存储到 Google Meet 插件配置中，或提供 +`OPENCLAW_GOOGLE_MEET_*` 环境变量。 -OAuth 不会替代 Chrome 加入路径。当你使用浏览器参与方式时，Chrome 和 chrome-node 传输方式仍然通过一个已登录的 Chrome 配置文件、BlackHole/SoX，以及一个已连接节点来加入。OAuth 只用于官方 Google Meet API 路径：创建会议空间、解析空间，以及执行 Meet Media API 预检。 +OAuth 不能替代 Chrome 加入路径。Chrome 和 Chrome-node 传输方式在你使用浏览器参会时，仍然通过已登录的 Chrome 配置文件、BlackHole/SoX 以及已连接节点进行加入。OAuth 仅用于官方 Google Meet API 路径：创建会议空间、解析空间以及运行 Meet Media API 预检。 ### 创建 Google 凭证 @@ -364,13 +380,13 @@ OAuth 不会替代 Chrome 加入路径。当你使用浏览器参与方式时， 1. 创建或选择一个 Google Cloud 项目。 2. 为该项目启用 **Google Meet REST API**。 3. 配置 OAuth 同意屏幕。 - - 对于 Google Workspace 组织，**Internal** 最简单。 - - 对于个人/测试设置，**External** 也可以；当应用处于 Testing 状态时，将每个会授权该应用的 Google 账号添加为测试用户。 + - **Internal** 对 Google Workspace 组织来说最简单。 + - **External** 适用于个人/测试设置；当应用处于 Testing 状态时，将每个要授权该应用的 Google 账户添加为测试用户。 4. 添加 OpenClaw 请求的作用域： - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` -5. 创建一个 OAuth client ID。 +5. 创建一个 OAuth 客户端 ID。 - 应用类型：**Web application**。 - 已获授权的重定向 URI： @@ -378,22 +394,22 @@ OAuth 不会替代 Chrome 加入路径。当你使用浏览器参与方式时， http://localhost:8085/oauth2callback ``` -6. 复制 client ID 和 client secret。 +6. 复制客户端 ID 和客户端密钥。 `meetings.space.created` 是 Google Meet `spaces.create` 所必需的。 -`meetings.space.readonly` 让 OpenClaw 能将 Meet URL/代码解析为会议空间。 -`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体相关工作；实际使用 Media API 时，Google 可能要求加入 Developer Preview。 -如果你只需要基于浏览器的 Chrome 加入方式，可以完全跳过 OAuth。 +`meetings.space.readonly` 让 OpenClaw 可以将 Meet URL/代码解析为空间。 +`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体相关工作；实际使用 Media API 时，Google 可能要求加入开发者预览计划。 +如果你只需要基于浏览器的 Chrome 加入，请完全跳过 OAuth。 ### 生成刷新令牌 -配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，或者通过环境变量传入它们，然后运行： +配置 `oauth.clientId`，并可选择配置 `oauth.clientSecret`，或者将它们作为环境变量传入，然后运行： ```bash openclaw googlemeet auth login --json ``` -该命令会打印一个包含刷新令牌的 `oauth` 配置块。它使用 PKCE、本地回调 `http://localhost:8085/oauth2callback`，并支持通过 `--manual` 进行手动复制/粘贴流程。 +该命令会打印一个带有刷新令牌的 `oauth` 配置块。它使用 PKCE、本地主机回调 `http://localhost:8085/oauth2callback`，并支持通过 `--manual` 使用手动复制/粘贴流程。 示例： @@ -411,7 +427,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json --manual ``` -JSON 输出包含： +JSON 输出包括： ```json { @@ -447,54 +463,52 @@ JSON 输出包含： } ``` -如果你不希望将刷新令牌写入配置中，优先使用环境变量。 -如果配置和环境变量同时存在，插件会优先解析配置，然后再回退到环境变量。 +如果你不希望将刷新令牌写入配置，优先使用环境变量。 +如果配置值和环境变量值同时存在，插件会优先解析配置，然后再回退到环境变量。 -OAuth 同意范围包括 Meet 空间创建、Meet 空间读取访问和 Meet 会议媒体读取访问。 -如果你是在会议创建支持存在之前完成认证的，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌包含 `meetings.space.created` 作用域。 +OAuth 同意内容包括 Meet 空间创建、Meet 空间读取访问和 Meet conference media 读取访问。如果你在会议创建支持存在之前就已完成身份验证，请重新运行 `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` 和检查消息等状态字段；不会打印访问令牌、刷新令牌或 client secret。 +这不会加载 Chrome 运行时，也不需要连接的 Chrome 节点。它会检查 OAuth 配置是否存在，以及刷新令牌是否能生成访问令牌。JSON 报告只包含 `ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息等状态字段；不会打印访问令牌、刷新令牌或客户端密钥。 常见结果： -| 检查项 | 含义 | -| -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在缓存的访问令牌。 | -| `oauth-token` | 缓存的访问令牌仍然有效，或者刷新令牌已生成新的访问令牌。 | -| `meet-spaces-get` | 可选的 `--meeting` 检查已解析一个现有的 Meet 空间。 | -| `meet-spaces-create` | 可选的 `--create-space` 检查已创建一个新的 Meet 空间。 | +| 检查项 | 含义 | +| --------------------- | ---------------------------------------------------------------------------------------- | +| `oauth-config` | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在缓存的访问令牌。 | +| `oauth-token` | 缓存的访问令牌仍然有效，或者刷新令牌已生成新的访问令牌。 | +| `meet-spaces-get` | 可选的 `--meeting` 检查解析了一个现有 Meet 空间。 | +| `meet-spaces-create` | 可选的 `--create-space` 检查创建了一个新的 Meet 空间。 | -如果还需要证明 Google Meet API 已启用，并且具备 `spaces.create` 作用域，请运行会产生副作用的创建检查： +若还要证明 Google Meet API 已启用以及 `spaces.create` 作用域也可用，请运行带副作用的创建检查： ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，并且授权账号具备 `meetings.space.created` 作用域时，请使用它。 +`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，并且已授权账户具备 `meetings.space.created` 作用域时，请使用它。 -若要证明对现有会议空间具有读取权限： +若要证明对现有会议空间的读取访问： ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` 和 `resolve-space` 可以证明已授权的 Google 账号对其可访问的现有空间具有读取权限。 -这些检查返回 `403` 通常意味着 Google Meet REST API 未启用、已同意的刷新令牌缺少所需作用域，或者该 Google 账号无法访问该 Meet 空间。若是刷新令牌错误，则表示你需要重新运行 `openclaw googlemeet auth login --json`，并存储新的 `oauth` 配置块。 +`doctor --oauth --meeting` 和 `resolve-space` 可以证明对已授权 Google 账户可访问的现有空间具有读取权限。这些检查返回 `403` 通常意味着 Google Meet REST API 未启用、用户同意的刷新令牌缺少所需作用域，或者该 Google 账户无法访问该 Meet 空间。若是刷新令牌错误，则表示需要重新运行 `openclaw googlemeet auth login +--json` 并存储新的 `oauth` 块。 -浏览器回退模式不需要任何 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。 +浏览器回退模式不需要 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。 -以下环境变量可作为回退来源： +接受以下环境变量作为回退： - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET` @@ -511,20 +525,33 @@ 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 创建 conference records 之后，列出会议工件和出席情况： ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij 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 ``` -如果你已经知道 conference record id，可以直接使用它： +配合 `--meeting` 时，`artifacts` 和 `attendance` 默认使用最新的 conference record。若你想获取该会议的所有保留记录，请传递 `--all-conference-records`。 + +Calendar 查找可以先从 Google Calendar 解析会议 URL，然后再读取 Meet 工件： + +```bash +openclaw googlemeet latest --today +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 events readonly 作用域。 + +如果你已经知道 conference record id，可以直接指定它： ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -532,17 +559,21 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -输出一份可读报告： +写出可读报告： ```bash openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \ --format markdown --output meet-artifacts.md openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \ --format markdown --output meet-attendance.md +openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \ + --format csv --output meet-attendance.csv ``` -`artifacts` 会返回会议记录元数据，以及当 Google 为该会议提供这些资源时的参与者、录制、转录、结构化 transcript-entry 和智能笔记资源元数据。对于大型会议，可使用 `--no-transcript-entries` 跳过条目查询。 -`attendance` 会将参与者展开为 participant-session 行，并包含加入/离开时间戳。这些命令只使用 Meet REST API；Google Docs/Drive 文档正文下载被有意排除在范围之外，因为那需要额外的 Google Docs/Drive 访问权限。 +`artifacts` 会返回 conference record 元数据，以及当 Google 为该会议公开这些内容时，参与者、录音、转录、结构化 transcript-entry 和 smart-note 资源元数据。对大型会议，请使用 `--no-transcript-entries` 跳过条目查找。`attendance` 会将参与者展开为 participant-session 行，包含首次/最后出现时间、总会话时长、迟到/提前离开标记，以及按已登录用户或显示名称合并的重复参与者资源。传递 `--no-merge-duplicates` 可保持原始参与者资源彼此分离，传递 `--late-after-minutes` 可调整迟到判定，传递 `--early-before-minutes` 可调整提前离开判定。 + +`export` 会写出一个文件夹，其中包含 `summary.md`、`attendance.csv`、 +`transcript.md`、`artifacts.json` 和 `attendance.json`。这些命令仅对 Meet 资源使用 Meet REST API；Google Docs/Drive 文档正文下载被有意排除在范围之外，因为那需要单独的 Google Docs/Drive 访问权限。 创建一个新的 Meet 空间： @@ -550,9 +581,9 @@ openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \ 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 { @@ -572,15 +603,15 @@ openclaw googlemeet create } ``` -如果浏览器回退在创建 URL 之前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化细节，而不是纯字符串： +如果浏览器回退在创建 URL 之前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化细节，而不是普通字符串： ```json { "source": "browser", - "error": "google-login-required: 在 OpenClaw 浏览器配置文件中登录 Google，然后重试创建会议。", + "error": "google-login-required: Sign in to Google in the OpenClaw browser profile, then retry meeting creation.", "manualActionRequired": true, "manualActionReason": "google-login-required", - "manualActionMessage": "在 OpenClaw 浏览器配置文件中登录 Google，然后重试创建会议。", + "manualActionMessage": "Sign in to Google in the OpenClaw browser profile, then retry meeting creation.", "browser": { "nodeId": "ba0f4e4bc...", "targetId": "tab-1", @@ -590,9 +621,10 @@ openclaw googlemeet create } ``` -当智能体看到 `manualActionRequired: true` 时，它应报告 `manualActionMessage`，以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成该浏览器步骤。 +当智能体看到 `manualActionRequired: true` 时，它应报告 +`manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成该浏览器步骤。 -API 创建的 JSON 输出示例： +来自 API 创建的 JSON 输出示例： ```json { @@ -613,13 +645,14 @@ API 创建的 JSON 输出示例： } ``` -创建 Meet 默认会直接加入。`chrome` 或 `chrome-node` 传输方式仍然需要一个已登录 Google 的 Chrome 配置文件，才能通过浏览器加入。如果该配置文件已登出，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员先完成 Google 登录，再进行重试。 +创建 Meet 默认也会加入。Chrome 或 Chrome-node 传输方式仍然需要一个已登录的 Google Chrome 配置文件，才能通过浏览器加入。如果该配置文件已退出登录，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员先完成 Google 登录，再重试。 -只有在确认你的 Cloud 项目、OAuth 主体以及会议参与者都已加入用于 Meet 媒体 API 的 Google Workspace Developer Preview Program 后，才设置 `preview.enrollmentAcknowledged: true`。 +仅在确认你的 Cloud 项目、OAuth 主体和会议参与者都已加入 Google Workspace Developer Preview Program for Meet media APIs 后，才设置 `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 @@ -647,18 +680,19 @@ 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.autoJoin: true`：通过 OpenClaw 浏览器自动化，在 `chrome-node` 上尽力填写访客名并点击“立即加入” +- `chrome.guestName: "OpenClaw Agent"`：在未登录的 Meet 访客界面上使用的名称 +- `chrome.autoJoin: true`：通过 OpenClaw 浏览器自动化，在 `chrome-node` 上尽力完成访客名称填写并点击“立即加入” - `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页 -- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已在通话中，然后才触发实时介绍 +- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已在通话中，然后再触发实时介绍 - `chrome.audioInputCommand`：将 8 kHz G.711 mu-law 音频写入 stdout 的 SoX `rec` 命令 - `chrome.audioOutputCommand`：从 stdin 读取 8 kHz G.711 mu-law 音频的 SoX `play` 命令 - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`：简短口头回复，需要更深入回答时使用 `openclaw_agent_consult` -- `realtime.introMessage`：当实时桥接连接时，做一个简短口头就绪检查；将其设为 `""` 可静默加入 +- `realtime.instructions`：简短的口语回复，较深入的回答使用 + `openclaw_agent_consult` +- `realtime.introMessage`：实时桥接连接时的简短口头就绪检查；将其设为 `""` 可静默加入 可选覆盖项： @@ -689,7 +723,7 @@ export GEMINI_API_KEY=... } ``` -仅 Twilio 配置： +仅使用 Twilio 的配置： ```json5 { @@ -704,7 +738,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 呼叫。 ## 工具 @@ -719,17 +753,20 @@ 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` 健康状态。使用 `action: "leave"` 可将会话标记为结束。 +使用 `action: "status"` 列出活动会话或检查某个会话 ID。使用 +`action: "speak"` 并提供 `sessionId` 和 `message`，可以让实时智能体立即发言。使用 `action: "test_speech"` 可创建或复用会话、触发一个已知短语，并在 Chrome 主机能够报告时返回 `inCall` 健康状态。使用 `action: "leave"` 将会话标记为结束。 在可用时，`status` 包含 Chrome 健康信息： - `inCall`：Chrome 看起来已进入 Meet 通话 -- `micMuted`：尽力检测的 Meet 麦克风状态 -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授予，或浏览器控制修复后，语音功能才能工作 +- `micMuted`：尽力获取的 Meet 麦克风状态 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授权或浏览器控制修复，语音功能才能正常工作 - `providerConnected` / `realtimeReady`：实时语音桥接状态 -- `lastInputAt` / `lastOutputAt`：最近一次从桥接接收/发送音频的时间 +- `lastInputAt` / `lastOutputAt`：最后一次从桥接收到或发送到桥接的音频时间 ```json { @@ -741,25 +778,27 @@ export GEMINI_API_KEY=... ## 实时智能体咨询 -Chrome 实时模式针对实时语音循环做了优化。实时语音提供商会听取会议音频，并通过配置的音频桥接发声。当实时模型需要更深入的推理、最新信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 +Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会听取会议音频，并通过已配置的音频桥接发声。当实时模型需要更深入的推理、当前信息或普通 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 -咨询工具会在后台运行常规 OpenClaw 智能体，并带上最近的会议转录上下文，然后向实时语音会话返回一个简洁的口头回答。随后语音模型可以将该回答说回会议中。它与 Voice Call 共用同一个实时咨询工具。 +咨询工具会在幕后运行常规 OpenClaw 智能体，并结合最近的会议转录上下文，向实时语音会话返回简洁的口头答复。然后语音模型可以把该答复说回会议中。它与 Voice Call 共用相同的实时咨询工具。 `realtime.toolPolicy` 控制咨询运行方式： -- `safe-read-only`：暴露咨询工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get` -- `owner`：暴露咨询工具，并允许常规智能体使用正常的智能体工具策略 -- `none`：不向实时语音模型暴露咨询工具 +- `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 \ @@ -767,9 +806,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: I'm here and listening." ``` -## 实时测试检查清单 +## 实时测试清单 -在将会议交给无人值守智能体之前，使用以下流程： +在将会议交给无人值守的智能体之前，请使用以下顺序： ```bash openclaw googlemeet setup @@ -779,15 +818,16 @@ 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` 返回的 Chrome 健康状态中包含 + `inCall: true`。 -对于远程 Chrome 主机（如 Parallels macOS VM），在更新 Gateway 网关或 VM 后，这是最短且安全的检查流程： +对于远程 Chrome 主机，例如 Parallels macOS VM，在更新 Gateway 网关或 VM 后，这是最短且安全的检查方式： ```bash openclaw googlemeet setup @@ -798,9 +838,9 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -这可以证明 Gateway 网关插件已加载、VM 节点已使用当前令牌连接，并且 Meet 音频桥接可用，然后智能体才会打开真实的会议标签页。 +这可以证明 Gateway 网关插件已加载、VM 节点使用当前令牌完成连接，并且 Meet 音频桥接可用，然后智能体才会打开真实的会议标签页。 -对于 Twilio 冒烟测试，请使用一个公开电话拨入详情的会议： +对于 Twilio 冒烟测试，请使用一个公开了电话拨入详细信息的会议： ```bash openclaw googlemeet setup @@ -812,24 +852,24 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ 预期的 Twilio 状态： -- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。 +- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 + `twilio-voice-call-credentials` 检查。 - Gateway 网关重新加载后，CLI 中可用 `voicecall`。 - 返回的会话包含 `transport: "twilio"` 和一个 `twilio.voiceCallId`。 -- `googlemeet leave ` 会挂断已委托的语音呼叫。 +- `googlemeet leave ` 会挂断委派出去的语音呼叫。 ## 故障排除 ### 智能体看不到 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 可用节点 @@ -842,7 +882,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -在 Gateway 网关主机上，批准节点并验证命令： +在 Gateway 网关主机上，批准该节点并验证命令： ```bash openclaw devices list @@ -850,7 +890,7 @@ openclaw devices approve openclaw nodes status ``` -该节点必须已连接，并列出 `googlemeet.chrome` 以及 `browser.proxy`。 +节点必须已连接，并列出 `googlemeet.chrome` 和 `browser.proxy`。 Gateway 网关配置必须允许这些节点命令： ```json5 @@ -863,7 +903,8 @@ Gateway 网关配置必须允许这些节点命令： } ``` -如果 `googlemeet setup` 中的 `chrome-node-connected` 失败，或 Gateway 网关日志报告 `gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启节点。对于局域网 Gateway 网关，这通常意味着： +如果 `googlemeet setup` 的 `chrome-node-connected` 检查失败，或者 Gateway 网关日志报告 +`gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启节点。对于局域网 Gateway 网关，通常意味着： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -874,40 +915,44 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -然后重新加载节点服务，并再次运行： +然后重新加载节点服务并再次运行： ```bash openclaw googlemeet setup openclaw nodes status --connected ``` -### 浏览器打开了，但智能体无法加入 +### 浏览器已打开，但智能体无法加入 -运行 `googlemeet test-speech` 并检查返回的 Chrome 健康信息。如果它报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并停止重试，直到浏览器操作完成。 +运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并在浏览器操作完成之前停止重试。 常见的手动操作： - 登录 Chrome 配置文件。 -- 从 Meet 主持人账号允许该访客进入。 -- 当出现 Chrome 原生权限提示时，授予 Chrome 麦克风/摄像头权限。 +- 通过 Meet 主持人账户准入该访客。 +- 当 Chrome 的原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。 - 关闭或修复卡住的 Meet 权限对话框。 -不要仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。那是 Meet 的音频选择过渡页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真正的会议状态。对于仅创建 URL 的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。 +不要仅仅因为 Meet 显示“Do you want people to hear you in the meeting?” 就报告“未登录”。那是 Meet 的音频选择过渡页；在可用时，OpenClaw 会通过浏览器自动化点击 **Use microphone**，并继续等待真正的会议状态。对于仅创建的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。 ### 会议创建失败 -当配置了 OAuth 凭证时，`googlemeet create` 会首先使用 Google Meet API `spaces.create` 端点。 -如果没有 OAuth 凭证，它会回退到固定的 Chrome 节点浏览器。请确认： +当已配置 OAuth 凭证时，`googlemeet create` 会首先使用 Google Meet API 的 `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认： -- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在对应的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。 -- 对于 API 创建：刷新令牌是在添加创建支持之后生成的。旧令牌可能缺少 `meetings.space.created` 作用域；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。 -- 对于浏览器回退：`defaultTransport: "chrome-node"`，并且 `chromeNode.node` 指向一个已连接、具备 `browser.proxy` 和 `googlemeet.chrome` 的节点。 -- 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且可以打开 `https://meet.google.com/new`。 -- 对于浏览器回退：重试会复用现有的 `https://meet.google.com/new` 或 Google 账号提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。 -- 对于浏览器回退：如果工具返回 `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`。 +- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在匹配的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。 +- 对于 API 创建：刷新令牌是在添加创建支持之后生成的。较旧的令牌可能缺少 `meetings.space.created` 作用域；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。 +- 对于浏览器回退：`defaultTransport: "chrome-node"` 和 + `chromeNode.node` 指向一个已连接节点，且该节点具备 `browser.proxy` 和 + `googlemeet.chrome`。 +- 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且能够打开 `https://meet.google.com/new`。 +- 对于浏览器回退：重试会复用现有的 `https://meet.google.com/new` 或 Google 账户提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。 +- 对于浏览器回退：如果工具返回 `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`。 -### 智能体已加入，但不会说话 +### 智能体已加入，但没有说话 检查实时路径： @@ -918,29 +963,31 @@ openclaw googlemeet doctor 使用 `mode: "realtime"` 进行收听/回话。`mode: "transcribe"` 按设计不会启动双向实时语音桥接。 -另外还要验证： +还要验证： -- Gateway 网关主机上可用一个实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 -- `BlackHole 2ch` 在 Chrome 主机上可见。 -- `rec` 和 `play` 在 Chrome 主机上存在。 +- Gateway 网关主机上可用一个实时提供商密钥，例如 + `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 +- 在 Chrome 主机上可以看到 `BlackHole 2ch`。 +- 在 Chrome 主机上存在 `rec` 和 `play`。 - Meet 的麦克风和扬声器已通过 OpenClaw 使用的虚拟音频路径进行路由。 -`googlemeet doctor [session-id]` 会打印会话、节点、通话中状态、手动操作原因、实时提供商连接、`realtimeReady`、音频输入/输出活动、最近音频时间戳、字节计数，以及浏览器 URL。当你需要原始 JSON 时，请使用 `googlemeet status [session-id]`。当你需要在不暴露令牌的情况下验证 Google Meet OAuth 刷新时，请使用 `googlemeet doctor --oauth`；当你还需要 Google Meet API 证明时，添加 `--meeting` 或 `--create-space`。 +`googlemeet doctor [session-id]` 会打印会话、节点、是否在通话中、手动操作原因、实时提供商连接状态、`realtimeReady`、音频输入/输出活动、最近的音频时间戳、字节计数以及浏览器 URL。当你需要原始 JSON 时，请使用 +`googlemeet status [session-id]`。当你需要验证 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`。它会在已配置的 Chrome 节点上聚焦并检查现有的 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行，并且 Chrome 节点必须已连接。 +对应的工具动作是 `recover_current_tab`。它会聚焦并检查已配置 Chrome 节点上的现有 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行，且 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 后端缺少 account SID、auth token 或主叫号码时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置这些变量： +当 Twilio 后端缺少 account SID、auth token 或 caller number 时，`twilio-voice-call-credentials` 会失败。请在 Gateway 网关主机上设置这些值： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -956,13 +1003,13 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` 默认仅做就绪性检查。若要对某个特定号码进行 dry-run： +`voicecall smoke` 默认仅检查就绪状态。若要对特定号码进行 dry-run： ```bash openclaw voicecall smoke --to "+15555550123" ``` -只有在你明确要发起真实的外呼通知电话时，才添加 `--yes`： +只有在你明确想发起真实的出站通知呼叫时，才添加 `--yes`： ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -970,7 +1017,7 @@ openclaw voicecall smoke --to "+15555550123" --yes ### Twilio 呼叫已开始，但始终未进入会议 -确认 Meet 事件公开了电话拨入详情。传入准确的拨入号码以及 PIN 或自定义 DTMF 序列： +确认 Meet 事件公开了电话拨入详细信息。传入准确的拨入号码和 PIN，或自定义 DTMF 序列： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -983,20 +1030,21 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## 说明 -Google Meet 的官方媒体 API 偏向接收，因此要向 Meet 通话中发声，仍然需要一个参与者路径。这个插件让这一边界保持清晰可见： -Chrome 负责浏览器参与和本地音频路由；Twilio 负责电话拨入参与。 +Google Meet 的官方媒体 API 偏向接收，因此要向 Meet 通话中发言，仍然需要一个参会者路径。该插件让这一边界保持可见： +Chrome 负责浏览器参会和本地音频路由；Twilio 负责电话拨入参会。 -Chrome 实时模式需要以下二者之一： +Chrome 实时模式需要以下之一： - `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有实时模型桥接，并在这些命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。 -- `chrome.audioBridgeCommand`：外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。 +- `chrome.audioBridgeCommand`：一个外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。 -若要获得干净的双工音频，请通过独立的虚拟设备或类似 Loopback 的虚拟设备图来分别路由 Meet 输出和 Meet 麦克风。单个共享的 BlackHole 设备可能会把其他参与者的声音回送进通话中。 +为了获得干净的双工音频，请通过独立的虚拟设备或类似 Loopback 的虚拟设备图来路由 Meet 输出和 Meet 麦克风。单个共享的 BlackHole 设备可能会把其他参与者的声音回送到通话中。 -`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委托的 Twilio 会话，`leave` 还会挂断底层语音呼叫。 +`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。 +`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 还会挂断底层语音呼叫。 ## 相关内容 -- [Voice call 插件](/zh-CN/plugins/voice-call) +- [Voice call plugin](/zh-CN/plugins/voice-call) - [Talk mode](/zh-CN/nodes/talk) - [构建插件](/zh-CN/plugins/building-plugins) diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md index 004828030..70b3941e5 100644 --- a/docs/zh-CN/tools/browser.md +++ b/docs/zh-CN/tools/browser.md @@ -1,39 +1,40 @@ --- read_when: - 添加由智能体控制的浏览器自动化 - - 调试为什么 openclaw 会干扰你自己的 Chrome + - 调试为什么 openclaw 正在干扰你自己的 Chrome - 在 macOS 应用中实现浏览器设置 + 生命周期 -summary: 集成式浏览器控制服务 + 操作命令 +summary: 集成的浏览器控制服务 + 操作命令 title: 浏览器（由 OpenClaw 管理） x-i18n: - generated_at: "2026-04-25T06:35:03Z" + generated_at: "2026-04-25T07:22:23Z" model: gpt-5.4 provider: openai - source_hash: f529cbcc4e818a89274fd9fc25e46b3cc5b30913278d62652ee1100e8ae6dcef + source_hash: 3f56eae24f9e247589037a00532c2066699ea7b8595bb18f9e756b4e6a5be2dc source_path: tools/browser.md workflow: 15 --- OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。 -它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理（仅限 loopback）。 +它与你的个人浏览器隔离，并通过 Gateway 网关内的一个小型本地控制服务进行管理 +（仅限 loopback）。 -初学者视角： +新手视角： -- 可以把它理解为一个**独立的、仅供智能体使用的浏览器**。 +- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。 - `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。 -- 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。 +- 智能体可以在安全通道中**打开标签页、读取页面、点击和输入**。 - 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的已登录 Chrome 会话。 -## 你将获得的内容 +## 你将获得什么 - 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。 - 可预测的标签页控制（列出/打开/聚焦/关闭）。 -- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。 -- 一个内置的 `browser-automation` Skills，它会在启用浏览器插件时教会智能体使用 snapshot、stable-tab、stale-ref 和 manual-blocker 恢复循环。 +- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。 +- 一个内置的 `browser-automation` Skills，用于在启用浏览器插件时教会智能体使用快照、稳定标签页、陈旧引用和手动阻塞恢复循环。 - 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。 -这个浏览器**不是**你日常使用的主浏览器。 -它是一个安全、隔离的界面，用于智能体自动化和验证。 +这个浏览器**不是**你日常使用的主浏览器。它是一个安全、隔离的表面，用于 +智能体自动化和验证。 ## 快速开始 @@ -45,13 +46,14 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。 +如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 +Gateway 网关。 -如果根本没有 `openclaw browser`，或者智能体提示浏览器工具不可用，请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 +如果 `openclaw browser` 完全不存在，或者智能体提示浏览器工具不可用，请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 ## 插件控制 -默认的 `browser` 工具是一个内置插件。你可以禁用它，以便用另一个注册相同 `browser` 工具名称的插件替换它： +默认的 `browser` 工具是一个内置插件。你可以禁用它，以便用另一个注册了相同 `browser` 工具名称的插件来替换它： ```json5 { @@ -65,23 +67,22 @@ openclaw browser --browser-profile openclaw snapshot } ``` -默认情况下需要同时设置 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。如果只禁用插件，会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保留，以供替代方案使用。 +默认设置同时需要 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。仅禁用插件会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保持不变，以供替代方案使用。 浏览器配置变更需要重启 Gateway 网关，这样插件才能重新注册其服务。 ## 智能体指引 -浏览器插件附带两级智能体指引： +浏览器插件提供两层智能体指引： -- `browser` 工具描述承载了始终启用的精简契约：选择正确的配置文件、在同一标签页上保持 refs、使用 `tabId`/labels 进行标签页定位，并在进行多步骤工作时加载浏览器 skill。 -- 内置的 `browser-automation` Skills 承载更长的操作循环：先检查状态/标签页，为任务标签页打标签，在操作前先做 snapshot，在 UI 变化后重新 snapshot，遇到 stale refs 时恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。 +- `browser` 工具描述承载了始终启用的精简契约：选择正确的配置文件、在同一标签页上保持引用、使用 `tabId`/标签来定位标签页，以及在多步骤任务中加载浏览器 Skills。 +- 内置的 `browser-automation` Skills 承载更完整的操作循环：先检查状态/标签页、为任务标签页加标签、在操作前做快照、在 UI 变化后重新快照、一次性恢复陈旧引用，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是猜测处理。 -启用插件后，插件内置的 Skills 会显示在智能体的可用技能列表中。 -完整的技能说明按需加载，因此常规轮次不会承担完整的 token 成本。 +当插件启用时，插件内置的 Skills 会列在智能体可用的 Skills 中。完整的 Skills 指令按需加载，因此日常轮次无需承担完整的 token 成本。 ## 缺少浏览器命令或工具 -如果升级后 `openclaw browser` 无法识别、缺少 `browser.request`，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中遗漏了 `browser`。请将它加上： +如果升级后 `openclaw browser` 未知、`browser.request` 缺失，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表遗漏了 `browser`。请把它加上： ```json5 { @@ -91,20 +92,20 @@ openclaw browser --browser-profile openclaw snapshot } ``` -`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代 allowlist 成员资格——allowlist 决定插件是否加载，而工具策略只会在加载之后才生效。完全移除 `plugins.allow` 也会恢复默认行为。 +`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代允许列表成员资格——允许列表控制插件是否加载，而工具策略仅在加载后才会运行。完全移除 `plugins.allow` 也会恢复默认行为。 ## 配置文件：`openclaw` 与 `user` -- `openclaw`：受管理、隔离的浏览器（不需要扩展）。 +- `openclaw`：受管、隔离的浏览器（无需扩展）。 - `user`：内置的 Chrome MCP 附加配置文件，用于你的**真实已登录 Chrome** 会话。 对于智能体浏览器工具调用： - 默认：使用隔离的 `openclaw` 浏览器。 -- 当现有登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。 -- 当你想指定特定浏览器模式时，使用 `profile` 作为显式覆盖。 +- 当现有已登录会话很重要，且用户就在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。 +- 当你希望使用特定浏览器模式时，`profile` 是显式覆盖项。 -如果你想默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。 +如果你希望默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。 ## 配置 @@ -113,20 +114,21 @@ openclaw browser --browser-profile openclaw snapshot ```json5 { browser: { - enabled: true, // 默认：true + enabled: true, // 默认值：true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景下选择启用 - // allowPrivateNetwork: true, // 旧别名 + // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景中显式启用 + // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // 旧的单配置文件覆盖项 - remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒） - remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒） + // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖项 + remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时时间（毫秒） + remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时时间（毫秒） + actionTimeoutMs: 60000, // 默认浏览器 act 超时时间（毫秒） tabCleanup: { - enabled: true, // 默认：true - idleMinutes: 120, // 设为 0 以禁用空闲清理 - maxTabsPerSession: 8, // 设为 0 以禁用每个会话的上限 + enabled: true, // 默认值：true + idleMinutes: 120, // 设为 0 可禁用空闲清理 + maxTabsPerSession: 8, // 设为 0 可禁用每会话上限 sweepMinutes: 5, }, defaultProfile: "openclaw", @@ -164,42 +166,45 @@ openclaw browser --browser-profile openclaw snapshot -- 控制服务绑定到 loopback，其端口由 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会让同一组中的派生端口一起偏移。 -- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 场景下才需要设置这些值。未设置时，`cdpUrl` 默认使用受管本地 CDP 端口。 +- 控制服务绑定到 loopback，其端口基于 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会同步移动同一组派生端口。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要设置这些值。未设置时，`cdpUrl` 默认为受管本地 CDP 端口。 - `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP HTTP 可达性检查；`remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 握手。 -- `tabCleanup` 是对主智能体浏览器会话所打开标签页的尽力清理机制。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们显式跟踪的标签页；主会话会保留活动标签页以便重复使用，然后在后台关闭空闲或超出数量的已跟踪标签页。 +- `actionTimeoutMs` 是浏览器 `act` 请求的默认时间预算，当调用方未传入 `timeoutMs` 时使用。客户端传输层会额外增加一个很小的缓冲窗口，以便长时间等待能完成，而不会在 HTTP 边界超时。 +- `tabCleanup` 是对主智能体浏览器会话所打开标签页的尽力清理。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭其显式跟踪的标签页；主会话会让活动标签页保持可复用，然后在后台关闭空闲或超额的跟踪标签页。 -- 浏览器导航和打开标签页会在导航前经过 SSRF 防护，并在事后对最终 `http(s)` URL 进行尽力复查。 +- 浏览器导航和打开标签页在导航前会受到 SSRF 防护，并会在最终 `http(s)` URL 上进行尽力的再次检查。 - 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。 -- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理由 OpenClaw 管理的浏览器。默认情况下，受管 Chrome 会直接启动，因此提供商代理设置不会削弱浏览器 SSRF 检查。 -- 如果要代理受管浏览器本身，请通过 `browser.extraArgs` 传入显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。除非你明确启用了私有网络浏览器访问，否则严格 SSRF 模式会阻止显式浏览器代理路由。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅在你明确可信任私有网络浏览器访问时启用。 -- `browser.ssrfPolicy.allowPrivateNetwork` 作为旧别名仍然受支持。 +- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动代理由 OpenClaw 管理的浏览器。受管 Chrome 默认直接启动，因此提供商代理设置不会削弱浏览器 SSRF 检查。 +- 如果要代理受管浏览器本身，请通过 `browser.extraArgs` 传入显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式浏览器代理路由，除非已明确启用私有网络浏览器访问。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你有意信任私有网络浏览器访问时才启用。 +- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已经运行时才进行附加。 -- `headless` 可以在全局或每个本地受管配置文件上设置。每个配置文件的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持无头模式，而另一个仍然可见。 -- `executablePath` 可以在全局或每个本地受管配置文件上设置。每个配置文件的值会覆盖 `browser.executablePath`，因此不同的受管配置文件可以启动不同的 Chromium 内核浏览器。 -- `color`（顶层和每个配置文件）会为浏览器 UI 着色，这样你可以看出当前活动的是哪个配置文件。 -- 默认配置文件是 `openclaw`（受管独立模式）。使用 `defaultProfile: "user"` 可切换为已登录用户浏览器。 -- 自动检测顺序：如果系统默认浏览器是 Chromium 内核，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 -- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为这种 driver 设置 `cdpUrl`。 -- 当一个 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。 +- `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已运行时附加。 +- `headless` 可在全局或每个本地受管配置文件上设置。每配置文件的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持无头模式，而另一个仍然可见。 +- `executablePath` 可在全局或每个本地受管配置文件上设置。每配置文件的值会覆盖 `browser.executablePath`，因此不同的受管配置文件可以启动不同的基于 Chromium 的浏览器。 +- `color`（顶层和每配置文件）会为浏览器 UI 着色，便于你看出当前激活的是哪个配置文件。 +- 默认配置文件是 `openclaw`（受管独立模式）。使用 `defaultProfile: "user"` 可切换为已登录的用户浏览器。 +- 自动检测顺序：如果系统默认浏览器基于 Chromium，则使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 +- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为该驱动设置 `cdpUrl`。 +- 当某个 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。 -## 使用 Brave（或其他 Chromium 内核浏览器） +## 使用 Brave（或其他基于 Chromium 的浏览器） -如果你的**系统默认**浏览器是 Chromium 内核（Chrome/Brave/Edge 等），OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖自动检测。`~` 会展开为你的操作系统主目录： +如果你的**系统默认**浏览器基于 Chromium（Chrome/Brave/Edge 等）， +OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖自动检测。 +`~` 会展开为你的操作系统主目录： ```bash openclaw config set browser.executablePath "/usr/bin/google-chrome" @@ -238,47 +243,47 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C -每个配置文件的 `executablePath` 只会影响由 OpenClaw 启动的本地受管配置文件。`existing-session` 配置文件会改为附加到已在运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。 +每配置文件的 `executablePath` 只影响由 OpenClaw 启动的本地受管配置文件。`existing-session` 配置文件会改为附加到已运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。 ## 本地控制与远程控制 -- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并且可以启动本地浏览器。 -- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关会将浏览器操作代理到它。 -- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以附加到远程 Chromium 内核浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 -- `headless` 只影响由 OpenClaw 启动的本地受管配置文件。它不会重启或改变 existing-session 或远程 CDP 浏览器。 -- `executablePath` 也遵循同样的本地受管配置文件规则。在正在运行的本地受管配置文件上更改它，会将该配置文件标记为需要重启/协调，以便下一次启动时使用新的二进制文件。 +- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并可启动本地浏览器。 +- **远程控制（节点主机）：** 在拥有浏览器的机器上运行节点主机；Gateway 网关会将浏览器操作代理到该主机。 +- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以附加到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 +- `headless` 仅影响由 OpenClaw 启动的本地受管配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。 +- `executablePath` 遵循同样的本地受管配置文件规则。在正在运行的本地受管配置文件上更改它时，该配置文件会被标记为需要重启/协调，以便下次启动时使用新的二进制文件。 -停止行为会因配置文件模式不同而有所区别： +停止行为因配置文件模式而异： - 本地受管配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程 -- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前控制会话，并释放 Playwright/CDP 模拟覆盖项（视口、配色方案、区域设置、时区、离线模式以及类似状态），即使 OpenClaw 并未启动任何浏览器进程 +- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭活动控制会话，并释放 Playwright/CDP 仿真覆盖项（视口、配色方案、语言区域、时区、离线模式及类似状态），即使没有任何浏览器进程是由 OpenClaw 启动的 远程 CDP URL 可以包含认证信息： - 查询 token（例如 `https://provider.example?token=`） -- HTTP Basic auth（例如 `https://user:pass@provider.example`） +- HTTP Basic 认证（例如 `https://user:pass@provider.example`） -OpenClaw 在调用 `/json/*` 端点以及连接 CDP WebSocket 时都会保留这些认证信息。 -对于 token，优先使用环境变量或密钥管理器，而不是将它们提交到配置文件中。 +OpenClaw 在调用 `/json/*` 端点以及连接到 CDP WebSocket 时会保留认证信息。 +对于 token，优先使用环境变量或密钥管理器，而不是把它们提交到配置文件中。 ## 节点浏览器代理（默认零配置） -如果你在拥有浏览器的那台机器上运行一个**节点主机**，OpenClaw 可以自动将浏览器工具调用路由到该节点，而无需任何额外的浏览器配置。 +如果你在拥有浏览器的机器上运行了一个**节点主机**，OpenClaw 可以在无需额外浏览器配置的情况下，自动将浏览器工具调用路由到该节点。 这是远程 Gateway 网关的默认路径。 -注意事项： +说明： - 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。 - 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。 -- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空即可保持旧版/默认行为：所有已配置的配置文件都可以通过代理访问，包括配置文件创建/删除路由。 -- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的配置文件可以作为目标，并且持久化配置文件的创建/删除路由会在代理界面上被阻止。 -- 如果你不想使用它，可以禁用： +- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空可保留旧版/默认行为：所有已配置的配置文件都仍可通过代理访问，包括配置文件创建/删除路由。 +- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可作为目标，且持久化配置文件创建/删除路由会在代理表面被阻止。 +- 如果你不想启用它，可以关闭： - 在节点上：`nodeHost.browserProxy.enabled=false` - - 在 Gateway 网关上：`gateway.nodes.browser.mode="off"` + - 在网关上：`gateway.nodes.browser.mode="off"` ## Browserless（托管远程 CDP） -[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 两种形式都支持，但对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。 +[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 两种形式都可以使用，但对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。 示例： @@ -299,27 +304,27 @@ OpenClaw 在调用 `/json/*` 端点以及连接 CDP WebSocket 时都会保留这 } ``` -注意事项： +说明： -- 请将 `` 替换为你真实的 Browserless token。 +- 将 `` 替换为你真实的 Browserless token。 - 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 -- 如果 Browserless 给你的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 以建立直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw 自动发现 `/json/version`。 +- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 以进行直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw 去发现 `/json/version`。 ## 直接 WebSocket CDP 提供商 -有些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略： +一些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略： - **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。 - OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后连接。没有 WebSocket 回退。 + OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后再连接。没有 WebSocket 回退。 - **直接 WebSocket 端点** — `ws://host[:port]/devtools//` 或 - `wss://...` 且路径为 `/devtools/browser|page|worker|shared_worker|service_worker/`。 + `wss://...`，路径为 `/devtools/browser|page|worker|shared_worker|service_worker/`。 OpenClaw 会直接通过 WebSocket 握手连接，并完全跳过 `/json/version`。 -- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，且没有 - `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、[Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP `/json/version` 发现（将协议规范化为 `http`/`https`）；如果发现返回了 `webSocketDebuggerUrl`，则使用它，否则 OpenClaw 会回退为在裸根路径上直接进行 WebSocket 握手。这样一来，指向本地 Chrome 的裸 `ws://` 仍然可以连接，因为 Chrome 只接受在 `/json/version` 返回的特定按目标划分路径上进行 WebSocket 升级。 +- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，没有 + `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、[Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP `/json/version` 发现（将协议规范化为 `http`/`https`）；如果发现结果返回 `webSocketDebuggerUrl`，则使用它，否则 OpenClaw 会回退为在裸根路径上直接进行 WebSocket 握手。这样一来，指向本地 Chrome 的裸 `ws://` 也能连接，因为 Chrome 只接受来自 `/json/version` 所给出的特定每目标路径的 WebSocket 升级。 ### Browserbase -[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行无头浏览器，内置 CAPTCHA 解决、隐身模式和住宅代理。 +[Browserbase](https://www.browserbase.com) 是一个用于运行无头浏览器的云平台，内置 CAPTCHA 求解、隐身模式和住宅代理。 ```json5 { @@ -338,53 +343,55 @@ OpenClaw 在调用 `/json/*` 端点以及连接 CDP WebSocket 时都会保留这 } ``` -注意事项： +说明： -- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。 -- 请将 `` 替换为你真实的 Browserbase API key。 +- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview 仪表板](https://www.browserbase.com/overview) 复制你的 **API Key**。 +- 将 `` 替换为你真实的 Browserbase API key。 - Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此不需要手动创建会话步骤。 - 免费套餐每月允许一个并发会话和一个浏览器小时。 付费套餐限制请参见 [pricing](https://www.browserbase.com/pricing)。 -- 完整 API 参考、SDK 指南和集成示例请参见 [Browserbase docs](https://docs.browserbase.com)。 +- 完整 API 参考、SDK 指南和集成示例请参见 [Browserbase 文档](https://docs.browserbase.com)。 -## 安全性 +## 安全 关键概念： -- 浏览器控制仅限 loopback；访问通过 Gateway 网关认证或节点配对完成。 -- 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**：gateway token bearer auth、`x-openclaw-password`，或使用已配置 gateway 密码的 HTTP Basic auth。 -- Tailscale Serve 身份标头和 `gateway.auth.mode: "trusted-proxy"` **不能**用于认证这个独立的 loopback 浏览器 API。 -- 如果启用了浏览器控制但未配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。 +- 浏览器控制仅限 loopback；访问通过 Gateway 网关认证或节点配对流转。 +- 独立的 loopback 浏览器 HTTP API **仅**使用共享密钥认证： + gateway token bearer 认证、`x-openclaw-password`，或带有已配置 gateway 密码的 HTTP Basic 认证。 +- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"` + **不会**为这个独立的 loopback 浏览器 API 提供认证。 +- 如果启用了浏览器控制且未配置任何共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token`，并将其持久化到配置中。 - 当 `gateway.auth.mode` 已经是 `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。 -- 请将 Gateway 网关和任何节点主机保持在私有网络（Tailscale）中；避免公开暴露。 -- 请将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。 +- 请将 Gateway 网关和任何节点主机放在私有网络（Tailscale）中；避免公开暴露。 +- 将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。 远程 CDP 提示： -- 尽可能优先使用加密端点（HTTPS 或 WSS）以及短期 token。 -- 避免将长期 token 直接嵌入配置文件。 +- 尽可能优先使用加密端点（HTTPS 或 WSS）以及短生命周期 token。 +- 避免将长期有效的 token 直接嵌入配置文件。 ## 配置文件（多浏览器） OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是： -- **由 OpenClaw 管理**：一个专用的 Chromium 内核浏览器实例，拥有自己的用户数据目录 + CDP 端口 -- **远程**：显式 CDP URL（运行在其他位置的 Chromium 内核浏览器） -- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件 +- **由 OpenClaw 管理**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口 +- **远程**：一个显式的 CDP URL（基于 Chromium 的浏览器运行在其他位置） +- **现有会话**：通过 Chrome DevTools MCP 自动连接你的现有 Chrome 配置文件 默认值： -- 如果缺少，`openclaw` 配置文件会自动创建。 -- `user` 配置文件是内置的，用于 Chrome MCP 现有会话附加。 -- 除 `user` 外，existing-session 配置文件需要显式启用；使用 `--driver existing-session` 创建它们。 +- 如果缺少 `openclaw` 配置文件，会自动创建它。 +- `user` 配置文件是内置的，用于 Chrome MCP existing-session 附加。 +- 除 `user` 之外，existing-session 配置文件需要显式启用；可使用 `--driver existing-session` 创建。 - 本地 CDP 端口默认从 **18800–18899** 分配。 -- 删除配置文件会将其本地数据目录移到废纸篓。 +- 删除配置文件时，其本地数据目录会被移到废纸篓。 所有控制端点都接受 `?profile=`；CLI 使用 `--browser-profile`。 -## 通过 Chrome DevTools MCP 连接现有会话 +## 通过 Chrome DevTools MCP 使用现有会话 -OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运行的 Chromium 内核浏览器配置文件。这样可以复用该浏览器配置文件中已经打开的标签页和登录状态。 +OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运行的基于 Chromium 的浏览器配置文件。这样可以复用该浏览器配置文件中已经打开的标签页和登录状态。 官方背景与设置参考： @@ -395,13 +402,13 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运 - `user` -可选：如果你想使用不同的名称、颜色或浏览器数据目录，也可以创建自己的自定义 existing-session 配置文件。 +可选：如果你想使用不同的名称、颜色或浏览器数据目录，可以创建你自己的自定义 existing-session 配置文件。 默认行为： -- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome 配置文件。 +- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，其目标是默认的本地 Google Chrome 配置文件。 -如果要用于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`： +对 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`： ```json5 { @@ -420,11 +427,11 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运 然后在对应的浏览器中： -1. 打开该浏览器用于远程调试的 inspect 页面。 +1. 打开该浏览器的远程调试检查页面。 2. 启用远程调试。 3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。 -常见的 inspect 页面： +常见的检查页面： - Chrome：`chrome://inspect/#remote-debugging` - Brave：`brave://inspect/#remote-debugging` @@ -439,51 +446,51 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -成功时的表现： +成功时应看到： - `status` 显示 `driver: existing-session` - `status` 显示 `transport: chrome-mcp` - `status` 显示 `running: true` -- `tabs` 会列出你已经打开的浏览器标签页 -- `snapshot` 会返回所选实时标签页中的 refs +- `tabs` 列出你已打开的浏览器标签页 +- `snapshot` 返回所选实时标签页中的引用 如果附加不起作用，请检查： -- 目标 Chromium 内核浏览器版本是否为 `144+` -- 该浏览器的 inspect 页面中是否启用了远程调试 -- 浏览器是否显示了附加同意提示，并且你已经接受 -- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器侧的远程调试 +- 目标的基于 Chromium 的浏览器版本为 `144+` +- 该浏览器的检查页面中已启用远程调试 +- 浏览器显示了附加授权提示，且你已接受 +- `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你启用浏览器侧远程调试 智能体使用： -- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。 -- 如果你使用自定义 existing-session 配置文件，请传入该显式配置文件名。 -- 仅当用户就在电脑前可以批准附加提示时才选择此模式。 +- 当你需要用户已登录浏览器状态时，使用 `profile="user"`。 +- 如果你使用自定义 existing-session 配置文件，请传入该明确的配置文件名称。 +- 仅当用户就在电脑前可以批准附加提示时，才选择此模式。 - Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect` -注意事项： +说明： -- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以在你的已登录浏览器会话中操作。 -- 对于这个 driver，OpenClaw 不会启动浏览器；它只会进行附加。 -- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，它会一并传入以定位该用户数据目录。 -- existing-session 可以附加到所选主机上，或者通过已连接的浏览器节点附加。如果 Chrome 位于其他地方且没有连接任何浏览器节点，请改用远程 CDP 或节点主机。 +- 与隔离的 `openclaw` 配置文件相比，此路径风险更高，因为它可以在你已登录的浏览器会话中执行操作。 +- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。 +- OpenClaw 在此处使用官方 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，则会将其一并传递，以定位该用户数据目录。 +- Existing-session 可以附加到所选主机上，也可以通过已连接的浏览器节点附加。如果 Chrome 位于其他地方且未连接任何浏览器节点，请改用远程 CDP 或节点主机。 - + -与受管的 `openclaw` 配置文件相比，existing-session driver 的限制更多： +与受管的 `openclaw` 配置文件相比，existing-session 驱动有更多限制： -- **截图** — 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。 -- **操作** — `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要 snapshot ref。`click` 仅支持鼠标左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用设置超时。`select` 接受单个值。 -- **等待 / 上传 / 对话框** — `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，每次仅一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。 -- **仅受管功能** — 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管浏览器路径。 +- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面截图或基于 ref 的元素截图不需要 Playwright。 +- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要快照 ref（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要快照 ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请改用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用设置超时。`select` 接受单个值。 +- **等待 / 上传 / 对话框** —— `wait --url` 支持精确匹配、子串匹配和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，一次只能上传一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。 +- **仅受管模式功能** —— 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管浏览器路径。 ## 隔离保证 -- **专用用户数据目录**：绝不会接触你的个人浏览器配置文件。 +- **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。 - **专用端口**：避免使用 `9222`，以防与开发工作流冲突。 -- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄，例如 `t1`、可选 labels，以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍然保留，以便调试和兼容。 +- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后返回稳定的 `tabId` 句柄，如 `t1`、可选标签以及原始 `targetId`。智能体应复用 `suggestedTargetId`；原始 id 仍保留用于调试和兼容性。 ## 浏览器选择 @@ -495,7 +502,7 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -你可以通过 `browser.executablePath` 进行覆盖。 +你可以通过 `browser.executablePath` 覆盖此行为。 平台说明： @@ -505,32 +512,33 @@ openclaw browser --browser-profile user snapshot --format ai ## 控制 API（可选） -为了便于脚本编写和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，并提供与之匹配的 `openclaw browser` CLI（快照、refs、wait 增强功能、JSON 输出、调试工作流）。完整参考请参见 [Browser control API](/zh-CN/tools/browser-control)。 +为了便于编写脚本和调试，Gateway 网关暴露了一个小型的**仅 loopback 的 HTTP 控制 API**，以及与之匹配的 `openclaw browser` CLI（快照、引用、等待增强、JSON 输出、调试工作流）。完整参考请参见 +[浏览器控制 API](/zh-CN/tools/browser-control)。 ## 故障排除 -有关 Linux 特定问题（尤其是 snap Chromium），请参见 -[Browser 故障排除](/zh-CN/tools/browser-linux-troubleshooting)。 +对于 Linux 特定问题（尤其是 snap Chromium），请参见 +[浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。 对于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参见 [WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。 -### CDP 启动失败 vs 导航 SSRF 阻止 +### CDP 启动失败与导航 SSRF 拦截 -这是两类不同的失败，它们指向不同的代码路径。 +这是两类不同的失败，它们对应不同的代码路径。 -- **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。 -- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标因策略被拒绝。 +- **CDP 启动或就绪性失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。 +- **导航 SSRF 拦截** 表示浏览器控制平面是健康的，但页面导航目标因策略而被拒绝。 常见示例： -- CDP 启动或就绪失败： +- CDP 启动或就绪性失败： - `Chrome CDP websocket for profile "openclaw" is not reachable after start` - `Remote CDP for profile "" is not reachable at ` -- 导航 SSRF 阻止： - - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器/网络策略错误而失败 +- 导航 SSRF 拦截： + - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、快照或打开标签页流程因浏览器/网络策略错误而失败 -使用以下最小序列来区分两者： +使用下面这个最小序列来区分两者： ```bash openclaw browser --browser-profile openclaw start @@ -540,46 +548,46 @@ openclaw browser --browser-profile openclaw open https://example.com 结果解读方式： -- 如果 `start` 因 `not reachable after start` 失败，请先排查 CDP 就绪性。 -- 如果 `start` 成功但 `tabs` 失败，说明控制平面仍然不健康。请将其视为 CDP 可达性问题，而不是页面导航问题。 -- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，说明浏览器控制平面已经启动，失败点在导航策略或目标页面。 +- 如果 `start` 失败，并显示 `not reachable after start`，请先排查 CDP 就绪性问题。 +- 如果 `start` 成功但 `tabs` 失败，说明控制平面仍然不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。 +- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，说明浏览器控制平面已启动，失败发生在导航策略或目标页面上。 - 如果 `start`、`tabs` 和 `open` 全部成功，说明基础的受管浏览器控制路径是健康的。 重要行为细节： - 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个失败即关闭的 SSRF 策略对象。 -- 对于本地 loopback 的 `openclaw` 受管配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制执行。 +- 对于本地 loopback 的 `openclaw` 受管配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。 - 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着之后的 `open` 或 `navigate` 目标一定被允许。 安全建议： - **不要**默认放宽浏览器 SSRF 策略。 -- 相比广泛开放私有网络访问，优先使用更窄范围的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`。 -- 仅在明确受信任、确实需要并且已审查私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。 +- 优先使用精确的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛的私有网络访问。 +- 仅在明确受信任、确实需要且已审查私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。 ## 智能体工具 + 控制工作方式 -智能体会获得**一个工具**用于浏览器自动化： +智能体获得**一个工具**用于浏览器自动化： - `browser` — doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act -映射关系如下： +它的映射方式如下： - `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。 -- `browser act` 使用 snapshot `ref` ID 来执行点击/输入/拖拽/选择。 -- `browser screenshot` 捕获像素截图（整页、元素或带标签的 refs）。 -- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪情况。 +- `browser act` 使用快照中的 `ref` ID 来执行点击/输入/拖动/选择。 +- `browser screenshot` 捕获像素内容（整页、元素或带标签的引用）。 +- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页的就绪状态。 - `browser` 接受： - - `profile`，用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。 - - `target`（`sandbox` | `host` | `node`），用于选择浏览器所在位置。 + - `profile`：用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。 + - `target`（`sandbox` | `host` | `node`）：用于选择浏览器所在位置。 - 在沙箱隔离会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。 - 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱隔离会话默认使用 `host`。 - - 如果已连接支持浏览器的节点，工具可能会自动路由到该节点，除非你固定指定 `target="host"` 或 `target="node"`。 + - 如果连接了支持浏览器的节点，工具可能会自动路由到该节点，除非你固定指定 `target="host"` 或 `target="node"`。 -这样可以让智能体保持确定性，并避免脆弱的选择器。 +这样可以让智能体保持可预测性，并避免脆弱的选择器。 ## 相关内容 -- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具 +- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 - [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制 -- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固 +- [安全](/zh-CN/gateway/security) — 浏览器控制的风险与加固