From f67d097d722fc25be75925f25536fdabbf8bea35 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 08:55:55 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/tools/browser-control.md | 165 +++++++++++++++------------- 1 file changed, 87 insertions(+), 78 deletions(-) diff --git a/docs/zh-CN/tools/browser-control.md b/docs/zh-CN/tools/browser-control.md index c69735b4c..13d4c066f 100644 --- a/docs/zh-CN/tools/browser-control.md +++ b/docs/zh-CN/tools/browser-control.md @@ -1,32 +1,32 @@ --- read_when: - - 通过本地控制 API 对智能体浏览器进行脚本操作或调试 - - 正在查找 `openclaw browser` CLI 参考 + - 通过 local control API 对智能体浏览器进行脚本操作或调试 + - 查找 `openclaw browser` CLI 参考 - 添加带有快照和 refs 的自定义浏览器自动化 summary: OpenClaw 浏览器控制 API、CLI 参考和脚本操作 title: 浏览器控制 API x-i18n: - generated_at: "2026-04-25T06:34:57Z" + generated_at: "2026-04-25T08:55:01Z" model: gpt-5.4 provider: openai - source_hash: e9d18da48dfb6cf127fabbaa056411162640ab62e15690617138af3c23ee19c9 + source_hash: 179d2422fa5db219a81486ad6e0d34a79cfb08a3f827c69cba8f6578a00fb2c0 source_path: tools/browser-control.md workflow: 15 --- 有关设置、配置和故障排除，请参阅 [Browser](/zh-CN/tools/browser)。 -本页是本地控制 HTTP API、`openclaw browser` -CLI，以及脚本模式（快照、refs、等待、调试流程）的参考文档。 +本页是 local control HTTP API、`openclaw browser` +CLI，以及脚本模式（快照、refs、等待、调试流程）的参考。 ## 控制 API（可选） -仅用于本地集成时，Gateway 网关会暴露一个小型的 loopback HTTP API： +仅用于本地集成时，Gateway 网关会暴露一个小型 loopback HTTP API： -- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop` +- Status/启动/停止：`GET /`、`POST /start`、`POST /stop` - 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId` - 快照/截图：`GET /snapshot`、`POST /screenshot` - 操作：`POST /navigate`、`POST /act` -- 钩子：`POST /hooks/file-chooser`、`POST /hooks/dialog` +- Hooks：`POST /hooks/file-chooser`、`POST /hooks/dialog` - 下载：`POST /download`、`POST /wait/download` - 调试：`GET /console`、`POST /pdf` - 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight` @@ -37,19 +37,19 @@ CLI，以及脚本模式（快照、refs、等待、调试流程）的参考文 所有端点都接受 `?profile=`。 -如果配置了共享密钥 Gateway 网关认证，浏览器 HTTP 路由也需要认证： +如果已配置共享密钥 Gateway 网关认证，浏览器 HTTP 路由也需要认证： - `Authorization: Bearer ` - `x-openclaw-password: ` 或使用该密码的 HTTP Basic auth 注意： -- 这个独立的 loopback 浏览器 API **不会** 使用受信任代理或 +- 这个独立的 loopback 浏览器 API **不会**使用 trusted-proxy 或 Tailscale Serve 身份标头。 - 如果 `gateway.auth.mode` 是 `none` 或 `trusted-proxy`，这些 loopback 浏览器 - 路由不会继承这些携带身份信息的模式；请将它们仅保留在 loopback 中使用。 + 路由不会继承这些携带身份信息的模式；请将它们保持为仅 loopback 可用。 -### `/act` 错误契约 +### `/act` 错误约定 `POST /act` 对路由级验证和 策略失败使用结构化错误响应： @@ -61,48 +61,47 @@ CLI，以及脚本模式（快照、refs、等待、调试流程）的参考文 当前的 `code` 值： - `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或无法识别。 -- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载未通过规范化或验证。 +- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载在规范化或验证时失败。 - `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不支持的操作类型中使用了 `selector`。 - `ACT_EVALUATE_DISABLED`（HTTP 403）：配置中禁用了 `evaluate`（或 `wait --fn`）。 -- `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批量 `targetId` 与请求目标冲突。 -- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：现有会话配置文件不支持此操作。 +- `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批量的 `targetId` 与请求目标冲突。 +- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：现有会话 profile 不支持该操作。 -其他运行时故障仍可能返回 `{ "error": "" }`，而没有 +其他运行时失败仍可能返回 `{ "error": "" }`，而没有 `code` 字段。 ### Playwright 要求 某些功能（navigate/act/AI snapshot/role snapshot、元素截图、 PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回 -明确的 501 错误。 +清晰的 501 错误。 -在没有 Playwright 时仍可使用的功能： +没有 Playwright 时仍可使用的功能： - ARIA 快照 -- 当托管的 `openclaw` 浏览器具有每标签页 CDP - WebSocket 可用时的页面截图 -- `existing-session` / Chrome MCP 配置文件的页面截图 -- 从快照输出生成的 `existing-session` 基于 ref 的截图（`--ref`） +- 当每个标签页的 CDP + WebSocket 可用时，受管 `openclaw` 浏览器的页面截图 +- `existing-session` / Chrome MCP profiles 的页面截图 +- 来自 snapshot 输出的 `existing-session` 基于 ref 的截图（`--ref`） 仍然需要 Playwright 的功能： - `navigate` - `act` - AI 快照 / role 快照 -- 基于 CSS 选择器的元素截图（`--element`） +- CSS-selector 元素截图（`--element`） - 完整浏览器 PDF 导出 元素截图也会拒绝 `--full-page`；该路由会返回 `fullPage is not supported for element screenshots`。 -如果你看到 `Playwright is not available in this gateway build`，请修复 -内置浏览器插件运行时依赖，确保已安装 `playwright-core`， -然后重启 Gateway 网关。对于打包安装，请运行 `openclaw doctor --fix`。 -对于 Docker，还需按下文所示安装 Chromium 浏览器二进制文件。 +如果你看到 `Playwright is not available in this gateway build`，请修复内置浏览器插件运行时依赖，确保已安装 +`playwright-core`，然后重启 Gateway 网关。对于打包安装，请运行 `openclaw doctor --fix`。 +对于 Docker，还请按下文所示安装 Chromium 浏览器二进制文件。 #### Docker Playwright 安装 -如果你的 Gateway 网关运行在 Docker 中，请避免使用 `npx playwright`（会有 npm 覆盖冲突）。 +如果你的 Gateway 网关运行在 Docker 中，请避免使用 `npx playwright`（npm 覆盖冲突）。 请改用内置 CLI： ```bash @@ -110,17 +109,17 @@ docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -如需持久化浏览器下载内容，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如， +要持久化浏览器下载内容，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如 `/home/node/.cache/ms-playwright`），并确保通过 -`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化 `/home/node`。参见 [Docker](/zh-CN/install/docker)。 +`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化 `/home/node`。请参阅 [Docker](/zh-CN/install/docker)。 ## 工作原理（内部） -一个小型 loopback 控制服务器接受 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（点击/输入/快照/PDF）通过 CDP 之上的 Playwright 完成；当缺少 Playwright 时，仅提供非 Playwright 操作。智能体看到的是一个稳定接口，而底层的本地/远程浏览器和配置文件可以自由切换。 +一个小型 loopback 控制服务器接收 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（点击/输入/快照/PDF）通过 CDP 之上的 Playwright 执行；当缺少 Playwright 时，只有非 Playwright 操作可用。智能体看到的是一个稳定接口，而底层的本地/远程浏览器和 profiles 可以自由切换。 ## CLI 快速参考 -所有命令都接受 `--browser-profile ` 以定位到特定配置文件，并接受 `--json` 以输出机器可读格式。 +所有命令都接受 `--browser-profile ` 以指定特定 profile，并支持 `--json` 以获得机器可读输出。 @@ -129,9 +128,9 @@ docker compose run --rm openclaw-cli \ ```bash openclaw browser status openclaw browser start -openclaw browser stop # 也会清除仅附加/远程 CDP 上的模拟状态 +openclaw browser stop # 也会清除仅附加/远程 CDP 上的仿真设置 openclaw browser tabs -openclaw browser tab # 当前标签页的快捷方式 +openclaw browser tab # 当前标签页的快捷命令 openclaw browser tab new openclaw browser tab select 2 openclaw browser tab close 2 @@ -166,7 +165,7 @@ openclaw browser responsebody "**/api" --max-chars 5000 - + ```bash openclaw browser navigate https://example.com @@ -194,7 +193,7 @@ openclaw browser trace stop - + ```bash openclaw browser cookies @@ -205,7 +204,7 @@ openclaw browser storage local set theme dark openclaw browser storage session clear openclaw browser set offline on openclaw browser set headers --headers-json '{"X-Debug":"1"}' -openclaw browser set credentials user pass # 使用 --clear 删除 +openclaw browser set credentials user pass # 使用 --clear 移除 openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com" openclaw browser set media dark openclaw browser set timezone America/New_York @@ -219,19 +218,19 @@ openclaw browser set device "iPhone 14" 注意： -- `upload` 和 `dialog` 是**预设**调用；请在触发文件选择器/对话框的点击或按键之前运行它们。 -- `click` / `type` / 等操作需要来自 `snapshot` 的 `ref`（数字 `12` 或 role ref `e12`）。操作有意不支持 CSS 选择器。当可见视口位置是唯一可靠目标时，请使用 `click-coords`。 -- 下载、trace 和 upload 路径被限制在 OpenClaw 临时根目录中：`/tmp/openclaw{,/downloads,/uploads}`（回退为：`${os.tmpdir()}/openclaw/...`）。 -- `upload` 还可以通过 `--input-ref` 或 `--element` 直接设置文件输入。 +- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的点击或按键之前运行它们。 +- `click`/`type`/等操作需要来自 `snapshot` 的 `ref`（数字 `12`、role ref `e12`，或可操作的 ARIA ref `ax12`）。操作有意不支持 CSS selectors。只有在可见视口位置是唯一可靠目标时，才使用 `click-coords`。 +- 下载、trace 和上传路径被限制在 OpenClaw 临时根目录下：`/tmp/openclaw{,/downloads,/uploads}`（回退为：`${os.tmpdir()}/openclaw/...`）。 +- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。 快照标志一览： -- `--format ai`（安装 Playwright 时的默认值）：带数字 refs 的 AI 快照（`aria-ref=""`）。 -- `--format aria`：无障碍树，无 refs；仅用于检查。 -- `--efficient`（或 `--mode efficient`）：紧凑的 role 快照预设。设置 `browser.snapshotDefaults.mode: "efficient"` 可将其设为默认值（参见 [Gateway configuration](/zh-CN/gateway/configuration-reference#browser)）。 -- `--interactive`、`--compact`、`--depth`、`--selector` 会强制生成 role 快照，并使用 `ref=e12` refs。`--frame "