browser-mcp

# Chrome DevTools MCP Browser Skill 通过 Chrome DevTools MCP 协议连接浏览器，实现远程网页控制。 --- ## 运行环境 ### 当前配置 | 项目 | 值 | |------|------| | 操作系统 | Windows 11 Pro | | 宿主软件 | QClaw (OpenClaw) | | 浏览器 | Chrome (老板已登录的浏览器) | | 连接方式 | Chrome DevTools MCP (`profile=user`) | ### 架构示意 ``` ┌─────────────────────────────────────────────────────────┐ │ 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 速查 ### 导航与控制 | Action | 说明 | 示例 | |--------|------|------| | `start` | 启动浏览器 | `browser(action="start", profile="user")` | | `navigate` | 打开网址 | `browser(action="navigate", profile="user", url="...")` | | `snapshot` | 获取页面快照 | `browser(action="snapshot", profile="user", refs="aria")` | | `screenshot` | 截图 | `browser(action="screenshot", profile="user")` | | `status` | 查看浏览器状态 | `browser(action="status", profile="user")` | | `stop` | 关闭浏览器 | `browser(action="stop", profile="user")` | ### 元素操作 | Kind | 说明 | 参数 | |------|------|------| | `click` | 点击元素 | `ref="xxx"` | | `type` | 输入文本 | `ref="xxx", text="内容"` | | `press` | 按键 | `key="Enter"/"Escape"/"ArrowDown"/"ArrowUp"` | | `select` | 下拉选择 | `ref="xxx", values=["选项"]` | | `hover` | 悬停 | `ref="xxx"` | | `wait` | 等待加载 | `timeMs=2000` | | `scroll` | 滚动 | `width=0, height=500` | | `close` | 关闭标签页 | - | ### 特殊操作 | 操作 | 代码 | |------|------| | 粘贴文本 | `browser(action="act", kind="press", key="Control+v")` | | 全选 | `browser(action="act", kind="press", key="Control+a")` | | 后退 | `browser(action="act", kind="press", key="Alt+ArrowLeft")` | | Ctrl+点击新标签打开 | `browser(action="act", ref="xxx", kind="click", modifiers=["Control"])` | --- ## 常用 ref 模式 | 场景 | 方式 | |------|------| | 搜索框输入 | `browser(action="act", ref="搜索框ref", kind="type", text="关键词")` | | 点击搜索/提交按钮 | `browser(action="act", ref="按钮ref", kind="click")` | | 回车提交 | `browser(action="act", kind="press", key="Enter")` | | ESC返回/关闭弹窗 | `browser(action="act", kind="press", key="Escape")` | | 滚动浏览 | `browser(action="act", kind="scroll", height=800)` | | 等待加载 | `browser(action="act", kind="wait", timeMs=3000)` | --- ## 实战模板 ### 模板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 远程调试配置 ```json "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： ```powershell 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 接受外部连接： ```powershell chrome.exe --remote-debugging-port=9222 --remote-allow-origins=* ``` 2. 防火墙配置（允许 9222 端口入站） 3. 获取 Windows 电脑的局域网 IP（如 `192.168.1.100`） #### Agent 端配置 ```json "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)` ### 当前白名单 ```json "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 白名单修改后重启**：配置不会自动生效 ### 常见问题 | 问题 | 解决方法 | |------|----------| | 报错 "Blocked SSRF" | 添加域名到白名单，重启 OpenClaw | | 点击没反应 | 重新 snapshot，ref 可能已变化 | | 页面加载慢 | 增加 wait timeMs 值 | | 浏览器超时 | 重启 OpenClaw 网关 | | 输入内容丢失 | 使用 `fill` 替代 `type`，或先清空再输入 | ### ref 失效规律 - 页面刷新/导航后 ref 全部失效 - 点击链接跳转后 ref 全部失效 - 滚动不会导致 ref 失效 - 每次操作前都重新 snapshot 是最稳妥的 --- ## Chrome 配置检查清单 > 老板的 Chrome 需开启远程调试才能连接： > 1. 地址栏输入 `chrome://inspect/#remote-debugging` > 2. 勾选 "Discover network targets" > 3. 确认显示 `localhost:9222` --- *最后更新：2026-03-25*