English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

CLI 命令

浏览器

OmeniaClaw browser

管理 OmeniaClaw 的浏览器控制界面并运行浏览器操作（生命周期、配置档案、标签页、快照、截图、导航、输入、状态模拟和调试）。

相关内容：

常用标志

  • --url <gatewayWsUrl>：Gateway 网关 WebSocket URL（默认来自配置）。
  • --token <token>：Gateway 网关令牌（如果需要）。
  • --timeout <ms>：请求超时时间（毫秒）。
  • --expect-final：等待最终的 Gateway 网关响应。
  • --browser-profile <name>：选择浏览器配置档案（默认来自配置）。
  • --json：机器可读输出（在支持的地方）。

快速开始（本地）

bash
OmeniaClaw browser profilesOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw open https://example.comOmeniaClaw browser --browser-profile OmeniaClaw snapshot

智能体也可以使用同样的就绪检查：browser({ action: "doctor" })。

快速故障排除

如果 start 失败并显示 not reachable after start，请先排查 CDP 就绪状态。如果 start 和 tabs 成功，但 open 或 navigate 失败，说明浏览器控制平面是正常的，而失败通常是导航 SSRF 策略导致的。

最小排查顺序：

bash
OmeniaClaw browser --browser-profile OmeniaClaw doctorOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw tabsOmeniaClaw browser --browser-profile OmeniaClaw open https://example.com

详细指南：浏览器故障排除

生命周期

bash
OmeniaClaw browser statusOmeniaClaw browser doctorOmeniaClaw browser doctor --deepOmeniaClaw browser startOmeniaClaw browser start --headlessOmeniaClaw browser stopOmeniaClaw browser --browser-profile OmeniaClaw reset-profile

说明：

  • doctor --deep 会增加一个实时快照探测。当基础 CDP 就绪状态显示正常，但你想确认当前标签页确实可被检查时，这会很有用。
  • 对于 attachOnly 和远程 CDP 配置档案，OmeniaClaw browser stop 会关闭当前活动控制会话，并清除临时模拟覆盖项，即使 OmeniaClaw 本身没有启动浏览器进程也是如此。
  • 对于本地受管配置档案，OmeniaClaw browser stop 会停止所启动的浏览器进程。
  • OmeniaClaw browser start --headless 仅适用于这一次启动请求，并且只在 OmeniaClaw 启动本地受管浏览器时生效。它不会改写 browser.headless 或配置档案配置，对于已经在运行的浏览器也不会产生效果。
  • 在没有 DISPLAY 或 WAYLAND_DISPLAY 的 Linux 主机上，本地受管配置档案会自动以无头模式运行，除非 OmeniaClaw_BROWSER_HEADLESS=0、browser.headless=false 或 browser.profiles.<name>.headless=false 明确要求显示浏览器界面。

如果命令不存在

如果 OmeniaClaw browser 是未知命令，请检查 ~/.OmeniaClaw/OmeniaClaw.json 中的 plugins.allow。

当存在 plugins.allow 时，请显式列出内置的浏览器插件，除非配置中已经有根级 browser 块：

json5
{  plugins: {    allow: ["telegram", "browser"],  },}

显式的根级 browser 块，例如 browser.enabled=true 或 browser.profiles.<name>，也会在受限的插件允许列表下激活内置浏览器插件。

相关内容：Browser 工具

配置档案

配置档案是具名的浏览器路由配置。实际使用中：

  • OmeniaClaw：启动或连接到专用的 OmeniaClaw 受管 Chrome 实例（隔离的用户数据目录）。
  • user：通过 Chrome DevTools MCP 控制你当前已登录的 Chrome 会话。
  • 自定义 CDP 配置档案：指向本地或远程 CDP 端点。
bash
OmeniaClaw browser profilesOmeniaClaw browser create-profile --name work --color "#FF5A36"OmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name remote --cdp-url https://browser-host.example.comOmeniaClaw browser delete-profile --name work

使用特定配置档案：

bash
OmeniaClaw browser --browser-profile work tabs

标签页

bash
OmeniaClaw browser tabsOmeniaClaw browser tab new --label docsOmeniaClaw browser tab label t1 docsOmeniaClaw browser tab select 2OmeniaClaw browser tab close 2OmeniaClaw browser open https://omeniaclaw.com --label docsOmeniaClaw browser focus docsOmeniaClaw browser close t1

tabs 会先返回 suggestedTargetId，然后是稳定的 tabId（如 t1）、可选标签以及原始 targetId。智能体应将 suggestedTargetId 传回 focus、close、快照和操作命令。你可以通过 open --label、tab new --label 或 tab label 分配标签；标签、标签页 ID、原始目标 ID，以及唯一的目标 ID 前缀都可以使用。 当 Chromium 在导航或表单提交期间替换底层原始目标时，只要 OmeniaClaw 能够确认匹配关系，就会将稳定的 tabId/标签附加到替换后的标签页上。原始目标 ID 仍然是不稳定的；优先使用 suggestedTargetId。

快照 / 截图 / 操作

快照：

bash
OmeniaClaw browser snapshotOmeniaClaw browser snapshot --urls

截图：

bash
OmeniaClaw browser screenshotOmeniaClaw browser screenshot --full-pageOmeniaClaw browser screenshot --ref e12OmeniaClaw browser screenshot --labels

说明：

  • --full-page 仅用于整页截图；不能与 --ref 或 --element 组合使用。
  • existing-session / user 配置档案支持整页截图，以及基于快照输出中的 --ref 的截图，但不支持 CSS --element 截图。
  • --labels 会在截图上叠加当前快照引用标记。
  • snapshot --urls 会将已发现的链接目标地址追加到 AI 快照中，这样智能体就可以选择直接导航目标，而不必仅根据链接文本猜测。

导航 / 点击 / 输入（基于 ref 的 UI 自动化）：

bash
OmeniaClaw browser navigate https://example.comOmeniaClaw browser click <ref>OmeniaClaw browser click-coords 120 340OmeniaClaw browser type <ref> "hello"OmeniaClaw browser press EnterOmeniaClaw browser hover <ref>OmeniaClaw browser scrollintoview <ref>OmeniaClaw browser drag <startRef> <endRef>OmeniaClaw browser select <ref> OptionA OptionBOmeniaClaw browser fill --fields '[{"ref":"1","value":"Ada"}]'OmeniaClaw browser wait --text "Done"OmeniaClaw browser evaluate --fn '(el) => el.textContent' --ref <ref>

在 OmeniaClaw 能够确认替换标签页时，操作响应会在操作触发页面替换后返回当前原始 targetId。对于长生命周期工作流，脚本仍应存储并传递 suggestedTargetId/标签。

文件和对话框辅助命令：

bash
OmeniaClaw browser upload /tmp/OmeniaClaw/uploads/file.pdf --ref <ref>OmeniaClaw browser waitfordownloadOmeniaClaw browser download <ref> report.pdfOmeniaClaw browser dialog --accept

受管 Chrome 配置档案会将普通点击触发的下载保存到 OmeniaClaw 下载目录（默认是 /tmp/OmeniaClaw/downloads，或已配置的临时根目录）。当智能体需要等待特定文件并返回其路径时，请使用 waitfordownload 或 download；这些显式等待器会接管下一次下载。

状态和存储

视口 + 模拟：

bash
OmeniaClaw browser resize 1280 720OmeniaClaw browser set viewport 1280 720OmeniaClaw browser set offline onOmeniaClaw browser set media darkOmeniaClaw browser set timezone Europe/LondonOmeniaClaw browser set locale en-GBOmeniaClaw browser set geo 51.5074 -0.1278 --accuracy 25OmeniaClaw browser set device "iPhone 14"OmeniaClaw browser set headers '{"x-test":"1"}'OmeniaClaw browser set credentials myuser mypass

Cookies + 存储：

bash
OmeniaClaw browser cookiesOmeniaClaw browser cookies set session abc123 --url https://example.comOmeniaClaw browser cookies clearOmeniaClaw browser storage local getOmeniaClaw browser storage local set token abc123OmeniaClaw browser storage session clear

调试

bash
OmeniaClaw browser console --level errorOmeniaClaw browser pdfOmeniaClaw browser responsebody "**/api"OmeniaClaw browser highlight <ref>OmeniaClaw browser errors --clearOmeniaClaw browser requests --filter apiOmeniaClaw browser trace startOmeniaClaw browser trace stop --out trace.zip

通过 MCP 使用现有 Chrome

使用内置的 user 配置档案，或者创建你自己的 existing-session 配置档案：

bash
OmeniaClaw browser --browser-profile user tabsOmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"OmeniaClaw browser --browser-profile chrome-live tabs

这一路径仅适用于主机本机。对于 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 会拒绝每次调用的超时覆盖
  • select 仅支持单个值
  • 不支持 wait --load networkidle
  • 文件上传需要 --ref / --input-ref，不支持 CSS --element，并且当前一次只支持一个文件
  • 对话框钩子不支持 --timeout
  • 截图支持整页截图和 --ref，但不支持 CSS --element
  • responsebody、下载拦截、PDF 导出以及批量操作仍然需要受管浏览器或原始 CDP 配置档案

远程浏览器控制（节点主机代理）

如果 Gateway 网关运行在与浏览器不同的机器上，请在安装了 Chrome/Brave/Edge/Chromium 的机器上运行一个节点主机。Gateway 网关会将浏览器操作代理到该节点（不需要单独的浏览器控制服务器）。

使用 gateway.nodes.browser.mode 控制自动路由，并使用 gateway.nodes.browser.node 在连接了多个节点时固定到特定节点。

安全性与远程设置：Browser 工具、远程访问、Tailscale、安全性

相关内容

Was this useful?
On this page

On this page