浏览器（由 OpenClaw 管理）

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 可以把它看作一个独立的、仅供智能体使用的浏览器。
• openclaw 配置文件不会触碰你的个人浏览器配置文件。
• 智能体可以在一条安全通道中打开标签页、读取页面、点击和输入。
• 内置的 user 配置文件会通过 Chrome MCP 附加到你真实的、已登录的 Chrome 会话。

​

你将获得什么

• 一个名为 openclaw 的独立浏览器配置文件（默认使用橙色强调色）。
• 可预测的标签页控制（列出/打开/聚焦/关闭）。
• 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。
• 一个内置的 browser-automation Skills，在启用浏览器插件时，会教会智能体使用快照、稳定标签页、过期引用和手动阻塞恢复循环。
• 可选的多配置文件支持（openclaw、work、remote，等等）。

​

快速开始

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

​

插件控制

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

​

智能体指引

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

• browser 工具说明携带了精简的始终启用契约：选择正确的配置文件，在同一个标签页中保持引用，使用 tabId/标签 来定位标签页，并在多步骤任务中加载浏览器 Skills。
• 内置的 browser-automation Skills 携带了更完整的操作循环：先检查状态/标签页，给任务标签页加标签，操作前先做快照，在 UI 变化后重新快照，过期引用恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为需要手动操作，而不是靠猜测处理。

​

缺少浏览器命令或工具

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

​

配置文件：openclaw 与 user

• openclaw：受管理、隔离的浏览器（无需扩展）。
• user：内置的 Chrome MCP 附加配置文件，用于你的真实已登录 Chrome 会话。

• 默认：使用隔离的 openclaw 浏览器。
• 当现有已登录会话很重要，并且用户就在电脑前可以点击/批准任何附加提示时，优先使用 profile="user"。
• 当你想要特定浏览器模式时，profile 是显式覆盖项。

​

配置

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

​

使用 Brave 或其他 Chromium 系浏览器

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

{
  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",
  },
}

​

本地控制与远程控制

• 本地控制（默认）： Gateway 网关 启动 loopback 控制服务，并且可以启动本地浏览器。
• 远程控制（节点主机）： 在拥有浏览器的机器上运行一个节点主机；Gateway 网关 会将浏览器操作代理到该节点主机。
• 远程 CDP： 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以附加到远程的 Chromium 系浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
• 对于运行在 loopback 上的外部管理 CDP 服务（例如在 Docker 中发布到 127.0.0.1 的 Browserless），还要设置 attachOnly: true。如果 loopback CDP 未设置 attachOnly，则会被视为本地的 OpenClaw 受管理浏览器配置文件。
• headless 仅影响由 OpenClaw 启动的本地受管理配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。
• executablePath 遵循相同的本地受管理配置文件规则。在一个正在运行的本地受管理配置文件上更改它时，该配置文件会被标记为需要重启/协调，以便下一次启动时使用新的二进制文件。

• 本地受管理配置文件：openclaw browser stop 会停止由 OpenClaw 启动的浏览器进程
• attach-only 和远程 CDP 配置文件：openclaw browser stop 会关闭活动控制会话，并释放 Playwright/CDP 模拟覆盖（视口、配色方案、区域设置、时区、离线模式及类似状态），即使没有任何浏览器进程是由 OpenClaw 启动的

• 查询参数 token（例如 https://provider.example?token=<token>）
• HTTP Basic 认证（例如 https://user:pass@provider.example）

​

节点浏览器代理（默认零配置）

• 节点主机会通过一个代理命令暴露其本地浏览器控制服务器。
• 配置文件来自节点自己的 browser.profiles 配置（与本地相同）。
• nodeHost.browserProxy.allowProfiles 是可选的。留空即可保留旧版/默认行为：所有已配置的配置文件都仍可通过代理访问，包括配置文件创建/删除路由。
• 如果你设置了 nodeHost.browserProxy.allowProfiles，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的配置文件可以作为目标，并且持久化配置文件创建/删除路由会在代理表面被阻止。
• 如果你不想启用它，可将其禁用：
  • 在节点上：nodeHost.browserProxy.enabled=false
  • 在 gateway 上：gateway.nodes.browser.mode="off"

​

Browserless（托管远程 CDP）

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

• 将 <BROWSERLESS_API_KEY> 替换为你的真实 Browserless token。
• 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。
• 如果 Browserless 提供的是 HTTPS 基础 URL，你可以将其转换为 wss:// 以建立直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw 去发现 /json/version。

​

同一主机上的 Browserless Docker

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

​

直接 WebSocket CDP 提供商

• HTTP(S) 发现 — http://host[:port] 或 https://host[:port]。
  OpenClaw 调用 /json/version 来发现 WebSocket 调试器 URL，然后进行连接。没有 WebSocket 回退。
• 直接 WebSocket 端点 — ws://host[:port]/devtools/<kind>/<id> 或
  wss://...，路径为 /devtools/browser|page|worker|shared_worker|service_worker/<id>。OpenClaw 直接通过 WebSocket 握手连接，并完全跳过 /json/version。
• 裸 WebSocket 根路径 — ws://host[:port] 或 wss://host[:port]，没有 /devtools/... 路径（例如 Browserless、Browserbase）。OpenClaw 会先尝试 HTTP /json/version 发现（将协议规范化为 http/https）；如果发现结果返回了 webSocketDebuggerUrl，则使用它，否则 OpenClaw 会回退到裸根路径上的直接 WebSocket 握手。如果通告的 WebSocket 端点拒绝 CDP 握手，但配置的裸根路径可以接受，OpenClaw 也会回退到该根路径。这使得指向本地 Chrome 的裸 ws:// 仍然可以连接，因为 Chrome 只接受来自 /json/version 中特定每目标路径的 WebSocket 升级；而托管提供商在其发现端点通告了不适合 Playwright CDP 的短时效 URL 时，仍可以使用其根 WebSocket 端点。

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

• 注册 后，从概览仪表板复制你的 API Key。
• 将 <BROWSERBASE_API_KEY> 替换为你的真实 Browserbase API key。
• Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此不需要手动创建会话。
• 免费层每月允许一个并发会话和一个浏览器小时。
  付费计划限制请参见 pricing。
• 完整的 API 参考、SDK 指南和集成示例，请参见 Browserbase docs。

​

安全性

• 浏览器控制仅限 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 并将其持久化到配置中。
• 当 gateway.auth.mode 已经是 password、none 或 trusted-proxy 时，OpenClaw 不会自动生成该 token。
• 请将 Gateway 网关 和任何节点主机保持在私有网络中（Tailscale）；避免公开暴露。
• 请将远程 CDP URL/token 视为机密；优先使用环境变量或密钥管理器。

• 尽可能优先使用加密端点（HTTPS 或 WSS）以及短时效 token。
• 避免将长期有效的 token 直接嵌入配置文件。

​

配置文件（多浏览器）

• 由 OpenClaw 管理：一个专用的 Chromium 系浏览器实例，拥有自己的用户数据目录 + CDP 端口
• 远程：显式的 CDP URL（在其他地方运行的 Chromium 系浏览器）
• 现有会话：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件

• 如果缺少，openclaw 配置文件会自动创建。
• user 配置文件是内置的，用于 Chrome MCP existing-session 附加。
• 除 user 外，existing-session 配置文件需要显式启用；请使用 --driver existing-session 创建。
• 本地 CDP 端口默认从 18800–18899 分配。
• 删除配置文件时，会将其本地数据目录移到废纸篓。

​

通过 Chrome DevTools MCP 使用现有会话

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

• 内置的 user 配置文件使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome 配置文件。

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

1. 打开该浏览器用于远程调试的 inspect 页面。
2. 启用远程调试。
3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。

• Chrome：chrome://inspect/#remote-debugging
• Brave：brave://inspect/#remote-debugging
• Edge：edge://inspect/#remote-debugging

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
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

• 目标 Chromium 系浏览器版本为 144+
• 已在该浏览器的 inspect 页面中启用远程调试
• 浏览器已显示附加同意提示，并且你已接受
• openclaw doctor 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已本地安装，但它无法替你在浏览器端启用远程调试

• 当你需要用户已登录的浏览器状态时，请使用 profile="user"。
• 如果你使用的是自定义 existing-session 配置文件，请传递该显式配置文件名称。
• 仅当用户就在电脑前可以批准附加提示时，才选择此模式。
• Gateway 网关 或节点主机可以生成 npx chrome-devtools-mcp@latest --autoConnect

• 与隔离的 openclaw 配置文件相比，这条路径风险更高，因为它可以在你已登录的浏览器会话内执行操作。
• 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。
• OpenClaw 在这里使用官方的 Chrome DevTools MCP --autoConnect 流程。如果设置了 userDataDir，则会将其透传，以便定位到该用户数据目录。
• existing-session 可以附加到所选主机上，或通过已连接的浏览器节点进行附加。如果 Chrome 位于其他地方，且没有浏览器节点连接，请改用远程 CDP 或节点主机。

​

自定义 Chrome MCP 启动

• http(s)://... → --browserUrl <url>（DevTools HTTP 发现端点）。
• ws(s)://... → --wsEndpoint <url>（直接 CDP WebSocket）。

​

隔离保证

• 专用用户数据目录：绝不会触碰你的个人浏览器配置文件。
• 专用端口：避免使用 9222，以防与开发工作流冲突。
• 可预测的标签页控制：tabs 会先返回 suggestedTargetId，然后是稳定的 tabId 句柄（如 t1）、可选标签以及原始 targetId。智能体应复用 suggestedTargetId；原始 id 仍可用于调试和兼容性场景。

​

浏览器选择

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS：检查 /Applications 和 ~/Applications。
• Linux：检查 /usr/bin、/snap/bin、/opt/google、/opt/brave.com、/usr/lib/chromium 和 /usr/lib/chromium-browser 下常见的 Chrome/Brave/Edge/Chromium 位置。
• Windows：检查常见安装位置。

​

控制 API（可选）

​

故障排除

​

CDP 启动失败 与 导航 SSRF 阻止

• CDP 启动或就绪失败 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。
• 导航 SSRF 阻止 表示浏览器控制平面是健康的，但页面导航目标因策略而被拒绝。

• CDP 启动或就绪失败：
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw，当 loopback 外部 CDP 服务配置时未设置 attachOnly: true
• 导航 SSRF 阻止：
  • open、navigate、snapshot 或打开标签页流程因浏览器/网络策略错误而失败，但 start 和 tabs 仍然正常

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

• 如果 start 因 not reachable after start 失败，请先排查 CDP 就绪问题。
• 如果 start 成功但 tabs 失败，则控制平面仍不健康。请将其视为 CDP 可达性问题，而不是页面导航问题。
• 如果 start 和 tabs 成功，但 open 或 navigate 失败，则浏览器控制平面已启动，故障出在导航策略或目标页面上。
• 如果 start、tabs 和 open 全部成功，则基础的受管理浏览器控制路径是健康的。

• 即使你没有配置 browser.ssrfPolicy，浏览器配置默认也会采用失败即关闭的 SSRF 策略对象。
• 对于本地 loopback 的 openclaw 受管理配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制。
• 导航保护是独立的。start 或 tabs 成功，并不意味着后续的 open 或 navigate 目标一定被允许。

• 不要默认放宽浏览器 SSRF 策略。
• 优先使用精确的主机例外，例如 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 接受：
  • profile，用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。
  • target（sandbox | host | node），用于选择浏览器所在位置。
  • 在沙箱隔离会话中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
  • 如果省略 target：沙箱隔离会话默认使用 sandbox，非沙箱会话默认使用 host。
  • 如果已连接支持浏览器的节点，除非你固定指定 target="host" 或 target="node"，否则该工具可能会自动路由到该节点。

​

相关内容

• 工具概览 — 所有可用的智能体工具
• 沙箱隔离 — 沙箱隔离环境中的浏览器控制
• 安全性 — 浏览器控制的风险与加固