浏览器（OpenClaw 管理）
集成浏览器控制服务 + 操作命令
OpenClaw 可以运行一个专用的 Chrome/Brave/Edge/Chromium 配置文件，由代理控制。
它与您的个人浏览器隔离，并通过网关内的小型本地
控制服务进行管理（仅环回）。
初学者视角：
- 把它看作一个独立的、仅限代理的浏览器。
- ''openclaw'' 配置文件''不会''触及您的个人浏览器配置文件。
- 代理可以在安全通道中打开标签页、读取页面、点击和输入。
- 默认的 ''chrome'' 配置文件通过
扩展中继使用''系统默认 Chromium 浏览器''；切换到 ''openclaw'' 以获得隔离的管理浏览器。
您能得到什么
- 一个名为 openclaw 的独立浏览器配置文件（默认橙色主题）。
- 确定性的标签页控制（列表/打开/聚焦/关闭）。
- 代理操作（点击/输入/拖动/选择）、快照、截图、PDF。
- 可选的多配置文件支持（''openclaw''、''work''、''remote'' 等）。
此浏览器不是您的日常浏览器。它是一个安全的、隔离的表面，用于
代理自动化和验证。
快速开始
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
如果您收到"浏览器已禁用"，请在配置中启用它（见下文）并重启
网关。
配置文件：`openclaw` vs `chrome`
- ''openclaw''：管理的、隔离的浏览器（无需扩展）。
- ''chrome''：扩展中继到您的''系统浏览器''（需要 OpenClaw
扩展附加到标签页）。
如果您希望默认使用管理模式，请设置 ''browser.defaultProfile: "openclaw"''。
配置
浏览器设置位于 ''~/.openclaw/openclaw.json''。
{
browser: {
enabled: true, // default: true
// 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)
defaultProfile: "chrome",
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" },
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
},
},
}注意：
- 浏览器控制服务绑定到从 ''gateway.port'' 派生的环回端口
（默认：''18791''，即网关 + 2）。中继使用下一个端口（''18792''）。
- 如果您覆盖网关端口（''gateway.port'' 或 ''OPENCLAW_GATEWAY_PORT''），
派生的浏览器端口会相应调整以保持在同一"家族"中。
- ''cdpUrl'' 未设置时默认为中继端口。
- ''remoteCdpTimeoutMs'' 适用于远程（非环回）CDP 可达性检查。
- ''remoteCdpHandshakeTimeoutMs'' 适用于远程 CDP WebSocket 可达性检查。
- ''attachOnly: true'' 意味着"从不启动本地浏览器；仅在已运行时附加。"
- ''color'' + 每配置文件的 ''color'' 为浏览器 UI 着色，以便您可以看到哪个配置文件处于活动状态。
- 默认配置文件是 ''chrome''（扩展中继）。使用 ''defaultProfile: "openclaw"'' 获得管理浏览器。
- 自动检测顺序：如果基于 Chromium 则为系统默认浏览器；否则为 Chrome → Brave → Edge → Chromium → Chrome Canary。
- 本地 ''openclaw'' 配置文件自动分配 ''cdpPort''/''cdpUrl'' — 仅在远程 CDP 时设置这些。
使用 Brave（或其他基于 Chromium 的浏览器）
如果您的系统默认浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），
OpenClaw 会自动使用它。设置 ''browser.executablePath'' 以覆盖
自动检测：
CLI 示例：
openclaw config set browser.executablePath "/usr/bin/google-chrome"
// macOS
{
browser: {
executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
}
}
// Windows
{
browser: {
executablePath: "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
}
}
// Linux
{
browser: {
executablePath: "/usr/bin/brave-browser"
}
}本地 vs 远程控制
- 本地控制（默认）：网关启动环回控制服务并可以启动本地浏览器。
- 远程控制（节点主机）：在拥有浏览器的机器上运行节点主机；网关将浏览器操作代理到它。
- ''远程 CDP：''设置 ''browser.profiles.<name>.cdpUrl''（或 ''browser.cdpUrl''）以
附加到远程基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
远程 CDP URL 可以包含认证：
- 查询令牌（例如，''https://provider.example?token=<token>''）
- HTTP 基本认证（例如，''https://user:[email protected]''）
OpenClaw 在调用 ''/json/*'' 端点和连接
CDP WebSocket 时保留认证。优先使用环境变量或密钥管理器来
存储令牌，而不是将它们提交到配置文件。
节点浏览器代理（零配置默认）
如果您在拥有浏览器的机器上运行节点主机，OpenClaw 可以
自动将浏览器工具调用路由到该节点，无需任何额外的浏览器配置。
这是远程网关的默认路径。
注意：
- 节点主机通过代理命令公开其本地浏览器控制服务器。
- 配置文件来自节点自己的 ''browser.profiles'' 配置（与本地相同）。
- 如果您不想要它，请禁用：
- 在节点上：''nodeHost.browserProxy.enabled=false''
- 在网关上：''gateway.nodes.browser.mode="off"''
Browserless（托管远程 CDP）
''Browserless'' 是一个托管的 Chromium 服务，通过 HTTPS 公开
CDP 端点。您可以将 OpenClaw 浏览器配置文件指向
Browserless 区域端点并使用您的 API 密钥进行认证。
示例：
{
browser: {
enabled: true,
defaultProfile: "browserless",
remoteCdpTimeoutMs: 2000,
remoteCdpHandshakeTimeoutMs: 4000,
profiles: {
browserless: {
cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
color: "#00AA00",
},
},
},
}注意：
- 将 ''<BROWSERLESS_API_KEY>'' 替换为您的真实 Browserless 令牌。
- 选择与您的 Browserless 账户匹配的区域端点（参见其文档）。
安全
关键理念：
- 浏览器控制仅限环回；访问通过网关的认证或节点配对进行。
- 将网关和任何节点主机保持在私有网络（Tailscale）上；避免公共暴露。
- 将远程 CDP URL/令牌视为机密；优先使用环境变量或密钥管理器。
远程 CDP 提示：
- 尽可能优先使用 HTTPS 端点和短期令牌。
- 避免在配置文件中直接嵌入长期令牌。
配置文件（多浏览器）
OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是：
- openclaw 管理：专用的基于 Chromium 的浏览器实例，具有自己的用户数据目录 + CDP 端口
- 远程：明确的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
- 扩展中继：通过本地中继 + Chrome 扩展的现有 Chrome 标签页
默认：
- 如果缺失，''openclaw'' 配置文件会自动创建。
- ''chrome'' 配置文件是 Chrome 扩展中继的内置配置（默认指向 ''http://127.0.0.1:18792''）。
- 本地 CDP 端口默认从 18800–18899 分配。
- 删除配置文件会将其本地数据目录移动到回收站。
所有控制端点接受 ''?profile=<name>''；CLI 使用 ''--browser-profile''。
Chrome 扩展中继（使用您现有的 Chrome）
OpenClaw 还可以通过本地 CDP 中继 + Chrome 扩展驱动您现有的 Chrome 标签页（无需单独的 "openclaw" Chrome 实例）。
完整指南：''Chrome 扩展''
流程：
- 网关在本地运行（同一台机器）或节点主机在浏览器机器上运行。
- 本地''中继服务器''在环回 ''cdpUrl''（默认：''http://127.0.0.1:18792''）上监听。
- 您点击标签页上的OpenClaw 浏览器中继扩展图标以附加（它不会自动附加）。
- 代理通过正常的 ''browser'' 工具控制该标签页，通过选择正确的配置文件。
如果网关在其他地方运行，请在浏览器机器上运行节点主机，以便网关可以代理浏览器操作。
沙盒会话
如果代理会话是沙盒化的，''browser'' 工具可能默认为 ''target="sandbox"''（沙盒浏览器）。
Chrome 扩展中继接管需要主机浏览器控制，因此要么：
- 在非沙盒环境中运行会话，或
- 设置 ''agents.defaults.sandbox.browser.allowHostControl: true'' 并在调用工具时使用 ''target="host"''。
设置
1. 加载扩展（开发/解压）：
openclaw browser extension install
- Chrome → ''chrome://extensions'' → 启用"开发者模式"
- "加载已解压的扩展程序" → 选择 ''openclaw browser extension path'' 打印的目录
- 固定扩展，然后在您想要控制的标签页上点击它（徽章显示 ''ON''）。
2. 使用它：
- CLI：''openclaw browser --browser-profile chrome tabs''
- 代理工具：''browser'' 并设置 ''profile="chrome"''
可选：如果您想要不同的名称或中继端口，请创建自己的配置文件：
openclaw browser create-profile --name my-chrome --driver extension --cdp-url http://127.0.0.1:18792 --color "#00AA00"
注意：
- 此模式依赖 Playwright-on-CDP 进行大多数操作（截图/快照/操作）。
- 再次点击扩展图标以分离。
隔离保证
- 专用用户数据目录：从不触及您的个人浏览器配置文件。
- ''专用端口''：避免 ''9222'' 以防止与开发工作流冲突。