跳转至

浏览器配置

配置

浏览器设置位于 ~/.openclaw/openclaw.json。

启用 Gateway 热重载后,更改 browser.enabled、browser.evaluateEnabled 或 browser.ssrfPolicy 只会替换浏览器控制服务。待处理的浏览器操作会被取消,并且在新策略生效前,OpenClaw 拥有的 Chrome 进程会关闭。Gateway 和其他插件会继续运行。已附加和远程浏览器进程会保持打开,但 OpenClaw 会断开其控制会话。启用后,浏览器控制会在下一次请求时重新启动;来自已退役进程的受管标签页不会被保留。扩展中继配置仍然需要重启 Gateway。

{
  browser: {
    enabled: true, // default: true
    evaluateEnabled: true, // default: true; false disables act:evaluate (arbitrary JS)
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowedHostnames: ["localhost"],
      // allowRfc2544BenchmarkRange: true, // trusted fake-IP proxy range
      // allowIpv6UniqueLocalRange: true, // trusted fake-IP proxy IPv6 range
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    tabCleanup: {
      enabled: true, // default: true
    },
    // snapshotDefaults: { mode: "efficient" }, // default snapshot mode when the caller omits one
    defaultProfile: "openclaw",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800 },
      work: {
        cdpPort: 18801,
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: {
        driver: "existing-session",
        attachOnly: true,
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222" },
    },
  },
}

browser.snapshotDefaults.mode: "efficient" 会在调用方未显式传递 snapshotFormat 或 mode 时,更改默认的 snapshot 提取模式。更改会应用于下一次快照;有关每次调用的快照选项,请参阅 Browser control API。

在具有稳定文档标识的驱动程序上,对同一标签页、文档和选项族重复进行 AI 或角色快照时,新出现的带有 ref 的元素会被标记为 [new]。第一个快照——以及导航后的第一个快照——会设置一个未标记的基线。现有会话快照会省略差异。

标签页清理所有权

会话标签页清理仅适用于会话拥有的标签页:由 OpenClaw 浏览器工具使用 action: "open" 创建的标签页,以及从控制 UI 中该会话的浏览器面板打开的标签页。OpenClaw 不会接管已经打开、在 OpenClaw 之外打开或以其他方式所有权未知的标签页。browser.tabCleanup 块控制主会话的定期空闲和上限清理。更改会在下一次清理时生效,无需重启浏览器;禁用它不会禁用显式会话生命周期清理。

所有权包括代理身份:使用相同会话密钥(例如 global)的两个代理具有独立的标签页成员关系和清理。没有代理限定身份的旧持久化记录会在清理读取标签页存储时作为无效簿记被丢弃。它们的标签页会保持打开:OpenClaw 不会猜测所有者,也不会将它们接管到另一个会话。如有需要,请手动关闭这些标签页。

定期清理属于浏览器插件服务,并在首次启动浏览器控制的请求结束后继续运行。停止或重新加载该服务会取消未来的清理,并等待活动清理完成。

OpenClaw 管理的 Chrome 在打开标签页时还会应用一个独立的、尽力而为的八个页面标签页上限。此上限独立于 browser.tabCleanup;远程和仅附加配置文件不使用它。

对于主机本地打开,具有稳定原生 CDP 目标和浏览器身份的所有权会存储在共享 SQLite 状态中。这些记录会在 Gateway 重启后保留,并且仍然符合 /new 和其他会话生命周期清理条件;会话生命周期清理包括子代理、cron 和 ACP 会话结束。工具面向目标为原生 CDP 目标的记录在重启后也仍然符合空闲和每会话上限清理条件。Chrome MCP 目标句柄是进程本地的,因此冷启动的现有会话记录会等待生命周期清理,而不是在重启后对无法安全归因的活动进行空闲清理。此持久化路径可以覆盖 OpenClaw 管理的配置文件、常规远程 CDP 配置文件,以及具有显式 cdpUrl 的现有会话配置文件,前提是 OpenClaw 能够解析原生目标和稳定的浏览器身份。在关闭持久化记录之前,OpenClaw 会验证配置的配置文件和浏览器实例是否仍然匹配。

Chrome MCP --autoConnect、/json/version 响应中缺少稳定浏览器身份的 CDP 端点,以及无法解析原生目标的打开操作,仍保持为进程本地的尽力而为跟踪。它们可以在该 Gateway 进程运行时被清理,但在 Gateway 重启后不会自动关闭。在持久化跟踪可用之前保持打开的标签页不会被追溯接管;请手动关闭这些标签页。

清理是尽力而为的,并不保证每个符合条件的标签页都会立即关闭。临时所有权检查或关闭失败会使持久化清理保持待处理状态,以便稍后重试。重试不是无限制的:当浏览器持续不可达且标签页超过一天未使用时,跟踪行会被退役,以便持久化存储不会因永远无法再次验证的标签页而填满。

截图视觉(仅文本模型支持)

当主模型仅支持文本(不支持视觉/多模态)时,浏览器截图返回的图像块是模型无法读取的。浏览器截图会复用现有的图像理解配置,因此为媒体理解配置的图像模型可以将截图描述为文本,而无需任何浏览器特定的模型设置。

{
  tools: {
    media: {
      models: [
        { provider: "bytedance", model: "doubao-seed-2.0-pro", capabilities: ["image"] },
        // Add fallback candidates; first success wins
        { provider: "openai", model: "gpt-4o", capabilities: ["image"] },
      ],
    },
  },
  agents: {
    defaults: {
      // Existing image-model defaults are also honored.
      // imageModel: { primary: "openai/gpt-4o" },
    },
  },
}

工作原理:

  1. 智能体调用 browser screenshot,图像会像往常一样捕获到磁盘。
  2. 浏览器工具会询问现有的图像理解运行时,是否可以使用已配置的媒体图像模型、共享媒体模型、图像模型默认值或基于身份验证的图像提供商来描述该截图。
  3. 视觉模型返回文本描述,该描述会用 wrapExternalContent(提示注入防护)包装,并作为文本块而不是图像块返回给智能体。
  4. 如果图像理解不可用、被跳过或失败,浏览器会回退为返回原始图像块。

截图图像块是私有工具结果:智能体可以检查它们,但 OpenClaw 不会自动将它们附加到频道回复中。若要共享截图,请要求智能体使用消息工具显式发送它。

使用 tools.media.models 配置模型回退、超时、字节限制、配置文件和提供商请求设置。为支持截图的条目标记 image 能力。

如果当前主模型已经支持视觉,并且未配置显式图像理解模型,OpenClaw 会保留正常图像结果,以便主模型可以直接读取截图。

端口与可达性
  • 控制服务绑定到回环地址,端口由 gateway.port 派生(默认 18791 = gateway + 2)。OPENCLAW_GATEWAY_PORT 优先于 gateway.port;两者都会使同一族中的派生端口发生偏移。
  • 本地 openclaw 配置文件使用从控制端口上方 9 个端口开始的 CDP 端口范围(默认 18800-18899)。OpenClaw 会为隐式默认配置文件以及通过 openclaw browser create-profile 创建的配置文件从该范围中分配端口,并将所选的 cdpPort 写入配置。手动声明的配置文件必须自行设置 cdpPort,或者为远程端点设置 cdpUrl:如果两者都未设置,模式会拒绝 openclaw 或 clawd 配置文件,并提示 Profile must set cdpPort or cdpUrl。 existing-session 配置文件使用 cdpUrl,除非 mcpArgs 中的有效端点参数会覆盖它;参见 自定义 Chrome MCP 启动。 它们忽略 cdpPort;extension 配置文件拥有自己的中继端口,并拒绝 cdpUrl。
  • 远程和 attachOnly CDP 可达性、WebSocket 握手以及本地托管 Chrome 启动使用内置超时。
  • 托管 Chrome 的重复启动/就绪失败会按配置文件进行熔断。连续多次失败后,OpenClaw 会短暂暂停新的启动尝试,而不是在每次浏览器工具调用时都启动 Chromium。请修复启动问题,如果不需要浏览器则禁用它,或在修复后重启 Gateway。
SSRF 策略
  • 浏览器导航和打开标签页请求会经过预检。在操作期间以及有界的操作后宽限期内,受保护的 Playwright 交互(点击、坐标点击、悬停、拖拽、滚动、选择、按键、输入、表单填充和 evaluate)会在 HTTP 请求字节之前拦截策略拒绝的顶层和子框架文档加载,然后尽力重新检查最终的 http(s) URL。
  • 每次全新启动 OpenClaw 托管的 Chrome 之前,OpenClaw 会尽力禁用网络预测,以抑制 Chromium 针对这些被拒绝加载所观察到的推测性预连接。这是纵深防御,而不是策略边界:跨控制服务重启复用的浏览器以及其他浏览器后端可能不会共享这些加固。Playwright 路由仍然不是网络防火墙,不会拦截重定向跳转、弹出窗口的第一个请求、Service Worker 流量、在有界保护窗口之后运行的页面代码,或所有后台/子资源路径。完整的出口隔离需要所有者侧隔离或策略执行代理。
  • 在严格 SSRF 模式下,远程 CDP 端点发现以及 /json/version 检查(cdpUrl)也会被检查。
  • 受保护的远程 CDP 连接现在会在所选驱动程序无法将已批准的端点绑定到实际套接字时失败关闭。对于 Browserless、Browserbase、Notte 或其他受保护的远程 CDP 提供商,请使用常规 openclaw 驱动程序。带有显式 cdpUrl 或 --browserUrl/--wsEndpoint MCP 参数的 existing-session/Chrome MCP 配置文件会在默认严格浏览器策略下被拒绝,因为 Chrome MCP 无法跨越其子进程边界传递 OpenClaw 的固定 DNS 查找或受保护发现结果。只有当明确信任私有网络浏览器访问时,它们才继续受支持。否则,请省略显式端点,并将 Chrome MCP 附加到主机本地 Chrome 配置文件,或将配置文件切换到常规驱动程序以使用受保护的 CDP。
  • 将 CDP 发现重定向到不同的权威仍不受支持,除非当前策略明确允许该权威变更。仅重新验证返回的主机名是不够的;WebSocket 传输必须使用通过策略验证的端点。
  • Gateway/提供商的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY 环境变量不会自动代理 OpenClaw 托管的浏览器。托管 Chrome 默认直接启动,因此提供商代理设置不会削弱浏览器 SSRF 检查。
  • OpenClaw 托管的本地 CDP 就绪检查和 DevTools WebSocket 连接会针对确切启动的回环端点绕过托管网络代理,因此当操作员代理阻止回环出口时,openclaw browser start 仍然有效。
  • 若要代理托管浏览器本身,请通过 browser.extraArgs 传递显式 Chrome 代理标志,例如 --proxy-server=... 或 --proxy-pac-url=...。严格 SSRF 模式会阻止显式浏览器代理路由,除非有意启用私有网络浏览器访问。
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 默认关闭;仅在有意信任私有网络浏览器访问时启用。
  • browser.ssrfPolicy.allowedHostnames 授予精确主机,同时私有网络的其余部分仍被阻止。
  • browser.ssrfPolicy.allowRfc2544BenchmarkRange 和 browser.ssrfPolicy.allowIpv6UniqueLocalRange 仅窄范围允许受信任的 fake-IP 代理范围。
配置文件行为
  • attachOnly: true 表示从不启动本地浏览器;仅在已有浏览器运行时附加。
  • headless 可全局设置,也可按本地托管配置文件设置。配置文件级值会覆盖 browser.headless,因此一个本地启动的配置文件可以保持无头模式,而另一个保持可见。
  • POST /start?headless=true 和 openclaw browser start --headless 请求对本地托管配置文件进行一次性无头启动,而不会重写 browser.headless 或配置文件设置。现有会话、仅附加和远程 CDP 配置文件会拒绝该覆盖,因为 OpenClaw 不会启动这些浏览器进程。
  • 在缺少 DISPLAY 或 WAYLAND_DISPLAY 的 Linux 主机上,当环境变量和配置文件/全局配置都未显式选择有界面模式时,本地托管配置文件会自动默认使用无头模式。使用无歧义的浏览器级形式 openclaw browser --json status;末尾的 openclaw browser status --json 也可用,因为 status 未定义自己的 --json。该命令将 headlessSource 报告为 env、profile、config、request、linux-display-fallback 或 default。
  • OPENCLAW_BROWSER_HEADLESS=1 强制当前进程的本地托管启动使用无头模式。OPENCLAW_BROWSER_HEADLESS=0 强制普通启动使用有界面模式,并在缺少显示服务器的 Linux 主机上返回可操作的错误;显式的 start --headless 请求仍对该次启动生效。
  • 浏览器控制路由和编程客户端会保留无显示错误的人类可读 error,并暴露稳定原因 no_display_for_headed_profile。其 details 仅包含 profile、requestedHeadless、headlessSource 和 displayPresent,因此 API 客户端无需匹配消息文本即可选择正确的修复措施。
  • 对于正在运行的本地托管配置文件,status 和 doctor 会查询 Chrome 的浏览器级 CDP 端点,以获取渲染器、后端、设备/驱动、功能状态、驱动变通方案和加速视频能力。结果会针对该浏览器进程缓存,并由 openclaw browser --json status 完整暴露。被动的 status 调用不会启动 Chrome。现有会话、扩展、远程 CDP 和沙箱浏览器保持独立,不会通过此托管主机路径进行检查。
  • 无头托管 Chrome 仍使用保守的 --disable-gpu 默认值。诊断不会启用加速、添加全局加速设置,或授予沙箱浏览器设备访问权限。
  • executablePath 可全局设置,也可按本地托管配置文件设置。配置文件级值会覆盖 browser.executablePath,因此不同的托管配置文件可以启动不同的基于 Chromium 的浏览器。两种形式都接受 ~ 表示操作系统主目录。
  • 默认配置文件为 openclaw(托管独立)。使用 defaultProfile: "user" 可选择使用已登录的用户浏览器。
  • 自动检测顺序:如果系统默认浏览器基于 Chromium,则使用它;否则依次为 Chrome、Brave、Edge、Chromium、Chrome Canary。
  • driver: "existing-session" 使用 Chrome DevTools MCP 而非原始 CDP。它可以通过 Chrome MCP 自动连接附加,或者在你已拥有正在运行的浏览器的 DevTools 端点时通过 cdpUrl 附加。
  • driver: "extension" 通过 OpenClaw Chrome 扩展 驱动你已登录的 Chrome。中继拥有其回环端点,因此这些配置文件不接受 cdpUrl。这是唯一在无人值守时也能工作的已登录浏览器模式。
  • 当现有会话配置文件应附加到非默认 Chromium 用户配置文件(Brave、Edge 等)时,设置 browser.profiles.<name>.userDataDir。此路径也接受 ~ 表示操作系统主目录。

使用 Brave 或其他基于 Chromium 的浏览器

如果你的系统默认浏览器基于 Chromium(Chrome/Brave/Edge 等), OpenClaw 会自动使用它。设置 browser.executablePath 可覆盖 自动检测。顶层和配置文件级 executablePath 值都接受 ~ 表示操作系统主目录:

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work '{"cdpPort":18801,"executablePath":"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"}' --strict-json --merge

或在配置中按平台设置:

{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
  },
}
{
  browser: {
    executablePath: "/usr/bin/brave-browser",
  },
}

配置文件级 executablePath 仅影响 OpenClaw 启动的本地托管配置文件。existing-session 配置文件改为附加到已在运行的浏览器, 而远程 CDP 配置文件使用 cdpUrl 背后的浏览器。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw