浏览器配置

配置¶

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

启用 Gateway 热重载时，更改 browser.enabled、 browser.evaluateEnabled 或 browser.ssrfPolicy 只会替换 Browser 控制服务。待处理的浏览器操作会被取消，并且 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" },
    },
  },
}

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

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

标签页清理所有权¶

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

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

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 会保留正常图像结果，以便主模型直接读取截图。

使用 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 后面的浏览器。