飞牛OpenClaw连接docker中的浏览器

Thr · 5 小时前

OpenClaw 浏览器配置指南

欢迎交流讨论，目前应用商店的浏览器版本可能不支持，这里提供一个我的部署，web页面https端口3001

services:
  chromium:
    image: linuxserver/chromium:latest
    container_name: chromium
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - LC_ALL=zh_CN.UTF-8
      - CHROME_CLI=https://www.baidu.com --no-sandbox --disable-gpu --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222
    volumes:
      - ./config:/config
    shm_size: "2gb"
    restart: unless-stopped

架构概览

本部署环境（fnOS）：

fnOS 主机
**── OpenClaw Gateway（端口 34480）
**   **── Control UI（Web 管理面板）
**── linuxserver/chromium Docker 容器（host 网络模式）
    **── Chrome DevTools Protocol（端口 9222）
        ↕ localhost 直通

Chromium Docker 容器使用 host 网络模式，与 fnOS 共享网络命名空间
Gateway 和 Chromium 在同一台机器上，通过 localhost 通信

两种浏览器连接模式

模式一：Chrome MCP（`existing-session`）

适用场景： 连接你正在使用的 Chrome 浏览器，复用登录态。

原理： OpenClaw 通过官方 Chrome DevTools MCP 协议，连接本机正在运行的 Chrome 进程。每次连接时 Chrome 会弹出确认框，需要用户点击「允许」。

配置方式：

{
  "browser": {
    "profiles": {
      "user": {
        "driver": "existing-session",
        "attachOnly": true,
        "color": "#00AA00"
      }
    }
  }
}

关键规则：

必须设置 driver: "existing-session"
不能设置 cdpUrl（它通过 Chrome MCP 自动发现）
Chrome 版本必须 ≥ 144
需要在 Chrome 中开启远程调试（chrome://inspect/#remote-debugging）
仅限同机使用（Gateway 和 Chrome 必须在同一台机器上）

支持的功能：

✅ 打开/切换/关闭标签页
✅ 截图（页面 + 元素）
✅ 快照 snapshot
✅ 点击/输入/表单操作
✅ 导航
✅ JavaScript evaluate
✅ Cookie / Storage 操作
✅ 设备模拟（iPhone 等）
❌ PDF 导出
❌ 文件下载拦截
❌ wait --load networkidle

模式二：Raw CDP（远程调试协议）

适用场景： 连接远程或容器化的浏览器，支持跨机器、自动化场景。

原理： 直接通过 Chrome DevTools Protocol 连接浏览器的调试端口。不需要用户确认，连接即可控制。

配置方式：

{
  "browser": {
    "enabled": true,
    "defaultProfile": "chromium",
    "profiles": {
      "chromium": {
        "cdpUrl": "http://127.0.0.1:9222",
        "attachOnly": true,
        "color": "#00AA00"
      }
    }
  }
}

关键规则：

必须设置 cdpUrl（浏览器 CDP 端口地址）
不能设置 driver: "existing-session"
不要求同机，只要网络通就行
无确认弹窗，连接即可控制

支持的功能：

✅ 打开/切换/关闭标签页
✅ 截图（页面 + 元素）
✅ 快照 snapshot
✅ 点击/输入/表单操作
✅ 导航
✅ JavaScript evaluate
✅ Cookie / Storage 操作
✅ 设备模拟（iPhone 等）
✅ PDF 导出
✅ 文件下载拦截
✅ wait --load networkidle

Raw CDP 功能比 Chrome MCP 更全，是自动化场景的首选。

模式对比总结

特性	Chrome MCP	Raw CDP
连接确认	需要用户点「允许」	无确认，直接控制
适用距离	仅同机	同机/跨机均可
配置字段	`driver: "existing-session"`	`cdpUrl: "http://..."`
PDF 导出	❌	✅
下载拦截	❌	✅
networkidle wait	❌	✅
安全性	高（每次确认）	低（谁连谁控制）
适合场景	需要登录态的日常浏览	自动化、容器化浏览器

当前配置

采用 Raw CDP 模式，连接 fnOS 上的 linuxserver/chromium Docker 容器。

{
  "browser": {
    "enabled": true,
    "defaultProfile": "chromium",
    "profiles": {
      "chromium": {
        "cdpUrl": "http://127.0.0.1:9222",
        "attachOnly": true,
        "color": "#00AA00"
      }
    }
  }
}

为什么选 Raw CDP 而不是 Chrome MCP

linuxserver/chromium 是 Docker 容器内的浏览器，不是用户正在交互的桌面浏览器。Chrome MCP 的 existing-session 模式需要在本机桌面环境中运行 Chrome 并手动确认，容器内没有桌面环境，无法使用。

连接过程详解

1. 启动 Chromium 容器

linuxserver/chromium 镜像默认开启远程调试端口：

# Docker Compose 或 docker run 时，确保端口映射或 host 网络
docker run --network host linuxserver/chromium:latest

Chromium 启动参数中包含 --remote-debugging-port=9222。

2. 验证 CDP 端口可用

curl http://127.0.0.1:9222/json/version

正常返回：

{
  "Browser": "Chrome/146.0.7680.164",
  "Protocol-Version": "1.3",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/..."
}

3. 配置 OpenClaw

编辑 ~/.openclaw/openclaw.json，添加 browser 配置（见上方）。

4. 重启 Gateway

# 方式一：发送 SIGUSR1 信号
kill -10 $(pgrep openclaw-gateway)

# 方式二：通过 Gateway 工具重启（需要已配对）
openclaw gateway restart

5. 设备配对（首次）

Agent 首次连接 Gateway 时需要设备配对。两种方式：

Control UI： 在 Web 管理面板上点击「批准」
命令行： openclaw devices approve <请求ID>

查看待批准请求：

openclaw devices list

6. 使用浏览器

Agent 可通过 browser 工具操作 Chromium：

browser open https://example.com — 打开网页
browser snapshot — 获取页面快照（AI 可读的结构化内容）
browser screenshot — 截图
browser click <ref> — 点击元素
browser type <ref> "text" — 输入文字
browser navigate https://other.com — 导航到新页面

安全注意事项

9222 端**露风险： Raw CDP 模式下，任何能访问 9222 端口的程序都能控制浏览器。确保该端口不对外网开放。
host 网络模式： Docker 使用 host 网络时，9222 直接绑定在 fnOS 主机上，需确认防火墙规则。
dangerouslyDisableDeviceAuth： 当前配置中此选项为 true，意味着 Control UI 不弹配对确认。如果需要更高安全性，改为 false。
attachOnly: true： 表示 OpenClaw 不会主动启动浏览器，只连接已有实例，避免意外创建新的浏览器进程。

WSL2 + Windows 跨机场景参考

如果 Gateway 运行在 WSL2，Chrome 运行在 Windows 上，架构类似但需要额外步骤：

Windows 上启动 Chrome：chrome.exe --remote-debugging-port=9222
Windows 上验证：curl http://127.0.0.1:9222/json/version
WSL2 上验证能连到 Windows：curl http://WINDOWS_IP:9222/json/version
配置 cdpUrl 使用 WSL2 能访问到的 Windows 地址

关键原则： 先在本地验证 CDP 端口可用，再从远端验证网络通达，最后配置 OpenClaw。

文档整理于 2026-03-28

Thr · 5 小时前

参考官方文档

WSL2 + Windows + remote Chrome CDP troubleshooting - OpenClaw

		自动登录	找回密码
密码			立即注册