Stable Browser
Replace the unreliable browser extension relay with a direct Chrome DevTools Protocol connection.
The Problem
The OpenClaw browser extension relay (profile="chrome") frequently breaks:
- - WebSocket 403 errors
- Port confusion (gateway port vs relay port)
- Dropped connections mid-automation
- "Can't reach browser control service" errors
- Badge/tab attachment confusion
The Fix: Chrome CDP
Launch Chrome with a debug port and connect directly. No extension needed.
Quick Setup
Run the setup script to configure everything:
CODEBLOCK0
This will:
- 1. Create a dedicated Chrome profile at INLINECODE1
- Add
browser.cdpUrl to your OpenClaw config - Create a LaunchAgent (macOS) so Chrome starts on login
- Verify the connection works
Manual Setup
If you prefer to set things up manually, see references/manual-setup.md.
Usage
After setup, always use profile="openclaw" (not profile="chrome"):
CODEBLOCK1
Key Differences from Extension Relay
| Feature | Extension Relay | CDP Direct |
|---|
| Stability | Frequent disconnects | Rock solid |
| Setup |
Install extension + attach tab | One-time script |
| Auth/Cookies | Shares your main Chrome | Dedicated profile |
| Speed | Extra hop through extension | Direct protocol |
| Headless | No | Optional (
--headless=new) |
Dedicated Profile
The CDP browser uses ~/.chrome-debug-profile — a separate Chrome profile. This means:
- - Log into sites once, stays logged in
- Your main Chrome is untouched
- No extension conflicts
- Survives Chrome updates
Tips
- - First run: Log into any sites you need (Google, GitHub, X, LinkedIn, etc.)
- Multiple tabs: CDP manages all tabs — use
targetId to pin a specific tab - Headless mode: Add
--headless=new to the launch command for invisible operation - Port conflict: If port 9222 is taken, change it in both the launch command and config
- Restart Chrome: INLINECODE9
Troubleshooting
- - "Can't reach browser": Chrome isn't running with debug port. Run
setup-cdp.sh or launch manually - Port 9222 in use: Another Chrome or process grabbed it. Kill it: INLINECODE11
- Stale session: Chrome crashed. Kill and restart: INLINECODE12
- Profile corruption: Delete
~/.chrome-debug-profile and re-run setup
Stable Browser
用直接的Chrome DevTools协议连接替代不可靠的浏览器扩展中继。
问题所在
OpenClaw浏览器扩展中继（profile=chrome）频繁出现故障：
- - WebSocket 403错误
- 端口混淆（网关端口与中继端口）
- 自动化过程中连接中断
- 无法访问浏览器控制服务错误
- 徽章/标签页附件混乱
解决方案：Chrome CDP
通过调试端口启动Chrome并直接连接，无需扩展。
快速设置
运行设置脚本配置所有内容：
bash
bash scripts/setup-cdp.sh
该脚本将：
- 1. 在~/.chrome-debug-profile创建专用Chrome配置文件
- 将browser.cdpUrl添加到OpenClaw配置
- 创建LaunchAgent（macOS），使Chrome在登录时启动
- 验证连接是否正常
手动设置
如果更倾向于手动设置，请参阅references/manual-setup.md。
使用方法
设置完成后，始终使用profile=openclaw（而非profile=chrome）：
browser(action=snapshot, profile=openclaw)
browser(action=navigate, profile=openclaw, targetUrl=https://example.com)
browser(action=screenshot, profile=openclaw)
与扩展中继的关键区别
安装扩展 + 附加标签页 | 一次性脚本 |
| 认证/Cookie | 共享主Chrome | 专用配置文件 |
| 速度 | 通过扩展额外跳转 | 直接协议 |
| 无头模式 | 不支持 | 可选（--headless=new） |
专用配置文件
CDP浏览器使用~/.chrome-debug-profile——一个独立的Chrome配置文件。这意味着：
- - 登录网站一次，保持登录状态
- 主Chrome不受影响
- 无扩展冲突
- 可承受Chrome更新
提示
- - 首次运行：登录所需的所有网站（Google、GitHub、X、LinkedIn等）
- 多标签页：CDP管理所有标签页——使用targetId固定特定标签页
- 无头模式：在启动命令中添加--headless=new实现无界面操作
- 端口冲突：如果端口9222被占用，在启动命令和配置中更改
- 重启Chrome：pkill -f remote-debugging-port=9222 && sleep 1 && bash scripts/setup-cdp.sh
故障排除
- - 无法访问浏览器：Chrome未以调试端口运行。运行setup-cdp.sh或手动启动
- 端口9222被占用：另一个Chrome或进程占用了该端口。终止它：lsof -i :9222
- 会话过期：Chrome崩溃。终止并重启：pkill -f chrome-debug-profile
- 配置文件损坏：删除~/.chrome-debug-profile并重新运行设置
