适用场景：OpenClaw 2026.x 版本对接 Chrome/Edge 浏览器远程调试，解决 DevToolsActivePort/Profile not found 等常见报错

一、核心原理

OpenClaw 通过 Chrome DevTools Protocol (CDP) 协议对接浏览器远程调试功能，只需在 Chrome/Edge 开启远程调试端口，再在 OpenClaw 配置中指向该端口即可完成对接。

Chrome 和 Edge（Chromium 内核）的配置逻辑完全通用，仅需替换浏览器启动方式和调试地址。

二、前置准备

1. 环境要求

• Chrome ≥ 144 / Edge ≥ 123（Chromium 内核）

• OpenClaw 2026.x 版本

• 操作系统：macOS/Windows/Linux（本文以 macOS 为例）

2. 关键路径说明

|
浏览器
|
远程调试入口
|
默认调试端口
|
配置文件路径（macOS）
|
| — | — | — | — |
|
Chrome
| chrome://inspect/#remote-debugging |
9222
| ~/.openclaw/openclaw.json |
|
Edge
| edge://inspect/#remote-debugging |
9222
| ~/.openclaw/openclaw.json |

三、步骤1：开启浏览器远程调试

方式1：GUI 界面开启（推荐）

1. 打开 Chrome/Edge，地址栏输入对应调试入口：

• Chrome：chrome://inspect/#remote-debugging

• Edge：edge://inspect/#remote-debugging

3. 勾选「Allow remote debugging for this browser instance」（允许外部应用控制浏览器）；

4. 确认页面显示「Server running at: 127.0.0.1:9222」，表示调试端口已开启。

方式2：终端命令启动（兜底方案）

若 GUI 配置不生效，可通过终端强制启动带调试参数的浏览器：

# Chrome 启动命令 /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ --remote-debugging-port=9222 \ --remote-debugging-address=0.0.0.0 \ --user-data-dir=/tmp/chrome-debug &  # Edge 启动命令 /Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge \ --remote-debugging-port=9222 \ --remote-debugging-address=0.0.0.0 \ --user-data-dir=/tmp/edge-debug &

说明：--user-data-dir 用于新建临时会话，避免复用无调试参数的旧窗口。

四、步骤2：验证调试端口可用性

执行以下命令，确认端口可访问（返回 JSON 即正常）：

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

正常返回示例：

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

五、步骤3：配置 OpenClaw 对接调试端口

1. 编辑核心配置文件

打开 OpenClaw 配置文件：

vim ~/.openclaw/openclaw.json

2. 完整配置模板（直接复制）

{   // 保留原有其他配置（如 env/agents/channels 等）   "tools": {     "allow": [       "exec",       "process",       "read",       "write",       "edit",       "apply_patch",       "browser"  // 必须启用 browser 工具权限     ],     "deny": [       "canvas"     ],     "exec": {       "host": "gateway",       "security": "full",       "ask": "off",       "backgroundMs": 10000,       "timeoutSec": 1800,       "cleanupMs": 1800000     }   },   "browser": {     "enabled": true,     "defaultProfile": "user",     "profiles": {       "user": {         "driver": "existing-session",  // 保留原有会话模式         "cdpUrl": "http://127.0.0.1:9222",  // 指向浏览器调试端口         "attachOnly": true,         "color": "#00AA00"       }     },     "remoteCdpTimeoutMs": 10000,     "remoteCdpHandshakeTimeoutMs": 15000   } }

3. 关键配置说明

|
参数
|
作用
|
| — | — |
| tools.allow
 包含 browser
|
必须启用，否则 OpenClaw 无法调用浏览器功能
|
| cdpUrl: "http://127.0.0.1:9222" |
核心参数，指向浏览器调试端口
|
| skipChromeSessionScan: true |
避免 OpenClaw 优先扫描 Chrome 会话（Edge 对接必加）
|
| forceCdpForExistingSession: true |
强制 existing-session 模式使用 CDP 协议
|

六、步骤4：生效并验证配置

1. 自动修复配置兼容问题

openclaw doctor --fix

2. 重启 OpenClaw

openclaw stop && openclaw start

3. 验证连接状态

openclaw browser --browser-profile user status

成功标志

输出包含以下内容即为对接成功：

◇  browser:user status   - cdpReady: true   - cdpUrl: http://127.0.0.1:9222   - attachOnly: true   - driver: existing-session (forced CDP)

七、常见问题排查

问题1：DevToolsActivePort 报错

• 原因：浏览器复用了无调试参数的旧会话

• 解决：彻底关闭浏览器，用终端命令（带 --user-data-dir）重新启动

问题2：Profile "user" not found

• 原因：配置未生效或格式错误

• 解决：执行 openclaw doctor --fix，重启 OpenClaw

问题3：cdpReady: false

• 原因：调试端口不可访问

• 解决：

1. 检查端口占用：lsof -i :9222

2. 确认浏览器调试开关已开启

3. 关闭防火墙/代理，重试 curl http://127.0.0.1:9222/json/version

八、核心总结

1. 浏览器侧

   ：必须开启远程调试，确保 9222 端口可访问；

2. OpenClaw 侧

   ：启用 browser 工具权限，配置 cdpUrl 指向调试端口；

3. Edge 专属

   ：添加 skipChromeSessionScan 和 forceCdpForExistingSession 强制对接；

4. 验证标准

   ：openclaw browser --browser-profile user status 返回 cdpReady: true。

提示：Chrome 和 Edge 配置仅需替换浏览器启动方式，其余步骤完全通用。若需切换端口（如 9223），只需同步修改浏览器启动参数和 OpenClaw 的 cdpUrl 即可。