browser-mcp（浏览器 MCP）

Chrome DevTools MCP Browser Skill

通过 Chrome DevTools MCP 协议连接浏览器，实现远程网页控制。

运行环境

当前配置

架构示意

┌─────────────────────────────────────────────────────────┐
│  QClaw / OpenClaw (本机 Windows 11)                     │
│                                                         │
│  browser(action="navigate", profile="user", ...)         │
│           ↓                                            │
│  Chrome DevTools MCP (CDP)                              │
│           ↓                                            │
│  ws://127.0.0.1:9222 (Chrome Remote Debugging)          │
│           ↓                                            │
│  Chrome Browser (老板的 Chrome) ← 直接操控已登录状态     │
└─────────────────────────────────────────────────────────┘

快速入门

1. 启动浏览器

browser(action="start", profile="user")

2. 打开网站

browser(action="navigate", profile="user", url="https://example.com")

3. 获取页面快照

browser(action="snapshot", profile="user", refs="aria")

4. 操作元素

browser(action="act", profile="user", ref="ref_id", kind="click")   // 点击
browser(action="act", profile="user", ref="ref_id", kind="type", text="内容")  // 输入

核心工作流

标准流程

启动浏览器 → 导航网址 → 获取快照 → 分析内容 → 操作元素 → 等待加载 → 循环重复

多步骤任务流程

1. browser(action="navigate", url="目标网址")
2. browser(action="snapshot", refs="aria")  ← 每次操作前必做
3. 分析快照中的 ref，找到目标元素
4. browser(action="act", kind="click/type/press", ref="xxx", ...)
5. browser(action="act", kind="wait", timeMs=2000)  // 等待加载
6. 返回步骤2，循环直到任务完成

完整 Action 速查

导航与控制

元素操作

特殊操作

常用 ref 模式

实战模板

模板1：搜索任务

1. navigate → 打开搜索引擎（百度/Google）
2. snapshot → 找到搜索框 ref
3. type → 输入搜索关键词
4. press Enter → 提交搜索
5. wait 2s → 等待结果加载
6. snapshot → 查看搜索结果
7. click → 点击目标链接

模板2：登录后操作

1. navigate → 打开目标网站（已登录状态）
2. snapshot → 确认已登录
3. 执行后续操作...

模板3：多页面深入

1. navigate → 打开列表页
2. snapshot → 找到目标条目
3. click → 点进详情
4. wait → 等待加载
5. snapshot → 查看详情内容
6. 重复深入或返回继续

模板4：表单填写提交

1. navigate → 打开表单页
2. snapshot → 获取所有表单项 ref
3. type → 逐项填写（姓名、邮箱等）
4. select → 选择下拉选项
5. click → 提交按钮
6. wait → 等待响应
7. snapshot → 确认提交结果

运行环境配置

Windows 11 + QClaw（当前）

配置文件路径

C:\Users\<your-username>\.qclaw\openclaw.json

Chrome 远程调试配置

"browser": {
  "ssrfPolicy": {
    "dangerouslyAllowPrivateNetwork": false,
    "allowedHostnames": [ ... ]
  },
  "profiles": {
    "user": {
      "driver": "existing-session",
      "attachOnly": true,
      "cdpPort": 9222,
      "cdpUrl": "http://127.0.0.1:9222",  // 本地调试端口，不要暴露
      "color": "#00AA00"
    }
  }
}

Chrome 启动方式

老板的 Chrome 需要开启远程调试：

1. 地址栏输入 chrome://inspect/#remote-debugging
2. 勾选 "Discover network targets"
3. 确认显示 localhost:9222

启动 Chrome 命令（可选）

如果需要手动启动带调试端口的 Chrome：

start chrome.exe --remote-debugging-port=9222

Linux/Mac 远程连接 Windows Chrome（未来支持 🚧）

场景说明

当 Agent 运行在 Linux 或 Mac 系统时，需要远程连接到 Windows 11 老板电脑上的 Chrome 浏览器。

架构示意

┌──────────────────────────────┐      ┌──────────────────────────────┐
│  Linux / Mac (Agent)         │      │  Windows 11 (老板电脑)        │
│                              │      │                              │
│  QClaw / OpenClaw            │ ←──→ │  Chrome + 远程调试端口        │
│  browser(action=...,          │ CDP  │  chrome.exe --remote-        │
│    cdpUrl="ws://WIN_IP:9222")│      │    debugging-port=9222        │
└──────────────────────────────┘      └──────────────────────────────┘

Windows 端配置

1. 允许 Chrome 接受外部连接：

   chrome.exe --remote-debugging-port=9222 --remote-allow-origins=*

1. 防火墙配置（允许 9222 端口入站）

1. 获取 Windows 电脑的局域网 IP（如 192.168.1.100）

Agent 端配置

"browser": {
  "profiles": {
    "user": {
      "driver": "remote",
      "cdpUrl": "ws://<your-windows-ip>:9222",  // 替换为实际 IP
      "attachOnly": false,
      "color": "#00AA00"
    }
  }
}

注意事项

• ⚠️ 仅在可信网络中使用
• ⚠️ 远程连接时老板的 Chrome 需要保持运行
• ⚠️ 老板电脑需要保持开机状态

SSRF 白名单配置

问题现象

Blocked: resolves to private/internal/special-use IP address

解决方案

1. 编辑 C:\Users\<your-username>\.qclaw\openclaw.json
2. 找到 browser.ssrfPolicy.allowedHostnames
3. 添加目标域名（支持泛域名 *.example.com）
4. 重启 OpenClaw：gateway(action=restart)

当前白名单

"allowedHostnames": [
  "*.chatgpt.com", "*.openai.com", "*.oaistatic.com",
  "*.gemini.google.com", "*.google.com",
  "*.twitter.com", "*.x.com",
  "*.facebook.com", "*.fbcdn.net",
  "*.github.com", "*.githubusercontent.com", "*.githubassets.com",
  "*.npmjs.org", "*.pypi.org", "*.pythonhosted.org",
  "*.cloudflare.com", "*.workers.dev", "*.vercel.app",
  "*.googleapis.com", "*.gstatic.com",
  "*.stackoverflow.com", "*.stackexchange.com"
]

注意事项

必须遵守

• 使用 profile=user：连接老板的 Chrome，不是默认 profile
• 操作前先 snapshot：每次页面变化后都要重新获取快照
• 操作后等待 1-2 秒：让页面/内容完全加载
• SSRF 白名单修改后重启：配置不会自动生效

常见问题

ref 失效规律

• 页面刷新/导航后 ref 全部失效
• 点击链接跳转后 ref 全部失效
• 滚动不会导致 ref 失效
• 每次操作前都重新 snapshot 是最稳妥的

Chrome 配置检查清单

老板的 Chrome 需开启远程调试才能连接： 1. 地址栏输入 chrome://inspect/#remote-debugging 2. 勾选 "Discover network targets" 3. 确认显示 localhost:9222

*最后更新：2026-03-25*