OpenClaw Chrome Relay Helper - Mac
Automates attaching the OpenClaw Browser Relay Chrome extension to a live tab on macOS. Once attached, the browser(profile="chrome") tool works — you can navigate, snapshot, click, and scrape using your real Chrome session.
macOS only. Requires Peekaboo (macOS UI automation CLI).
Quickstart
CODEBLOCK0
Outputs one of:
- -
ALREADY_ATTACHED — already connected, nothing to do - INLINECODE2 — freshly connected, ready to use
- INLINECODE3 — check
~/.openclaw/media/relay-attach-fail.png for a debug screenshot
Then navigate and automate:
CODEBLOCK1
Typical wall time: ~29s on a clean launch.
Prerequisites
1. Peekaboo (macOS UI automation CLI)
CODEBLOCK2
Peekaboo reads Chrome's accessibility tree to find the extension icon by description — no pixel coordinates needed.
2. Accessibility permission for node
Go to System Settings → Privacy & Security → Accessibility and add your node binary. Without this, Peekaboo cannot send click events.
Find your node path with: INLINECODE7
3. openclaw.json browser profile
Add this to your ~/.openclaw/openclaw.json:
CODEBLOCK3
Restart the gateway after editing: INLINECODE9
4. Extension loaded and pinned in Chrome
The OpenClaw Browser Relay extension must be loaded as an unpacked extension in Chrome. It's included with OpenClaw at:
CODEBLOCK4
Load it via chrome://extensions → Developer mode ON → Load unpacked.
The extension must also be pinned to the toolbar. The script finds the icon via Chrome's accessibility tree, which only exposes toolbar-pinned extensions — not icons hidden inside the Extensions panel. To pin: click the puzzle-piece icon → click the pin icon next to "OpenClaw Browser Relay".
How it works
The script finds the extension icon using Chrome's accessibility tree — not pixel coordinates. The icon's description changes based on state:
- - Detached: INLINECODE11
- Attached: INLINECODE12
Peekaboo scans for a pop-up button element whose description starts with "OpenClaw Browser Relay", determines state, and clicks to attach if needed. Retries up to 8× (every 2s) to handle slow Chrome startup.
Window maximize is required before scanning — Chrome's toolbar icons are not visible in the accessibility tree on a small or default-sized window.
What the script does (step by step)
- 1. Fast path — if Chrome is running and badge already shows "attached", exits immediately (~2s)
- Kill any running Chrome instance
- Patch
~/Library/Application Support/Google/Chrome/Default/Preferences to suppress the "Restore Pages?" dialog on relaunch - Open Chrome to
https://info.cern.ch/ — the world's first website, a 428-byte static HTML file with zero anti-bot tech, JS, cookies, or Cloudflare - Maximize the window via Peekaboo (required for toolbar visibility)
- Scan accessibility tree for the extension icon (retries up to 8×, 2s apart)
- Click the icon to attach
- Verify state changed to "attached" before returning
Known pitfalls
| Approach | Why it doesn't work |
|---|
| Hardcoded pixel coordinates | Breaks at any screen size other than what they were measured on |
AppleScript keystroke with Ctrl+Shift |
Modifier keys are silently dropped — only the bare key fires |
| Chrome extension keyboard shortcut | The extension manifest has no
commands — shortcuts don't trigger attach |
| Vision model to locate icon | Not reliable enough for toolbar UI at any resolution |
| Skipping window maximize | Toolbar icons don't appear in the accessibility tree on a small window |
| Extension not pinned to toolbar | Unpinned extensions are hidden inside the Extensions panel — not visible in the accessibility tree |
| Wrong profile name or port in config |
browser(profile="chrome") requires the profile named exactly
chrome pointing to port
18792 |
Token efficiency tips
CODEBLOCK5
Integration pattern
Any skill that needs Chrome relay should call this first:
CODEBLOCK6
OpenClaw Chrome Relay Helper - Mac
在macOS上自动化将OpenClaw Browser Relay Chrome扩展附加到活动标签页。附加后，browser(profile=chrome)工具即可工作——您可以使用真实的Chrome会话进行导航、截图、点击和抓取。
仅限macOS。 需要Peekaboo（macOS UI自动化CLI工具）。
快速开始
bash
bash /scripts/attach.sh
输出以下之一：
- - ALREADY_ATTACHED — 已连接，无需操作
- ATTACHED — 新连接，准备就绪
- FAILED: — 检查 ~/.openclaw/media/relay-attach-fail.png 查看调试截图
然后导航并自动化：
python
browser(action=navigate, profile=chrome, targetUrl=https://example.com)
browser(action=snapshot, profile=chrome, compact=True) # 读取页面内容
典型耗时：全新启动约29秒。
前提条件
1. Peekaboo（macOS UI自动化CLI工具）
bash
brew install steipete/tap/peekaboo
Peekaboo通过描述读取Chrome的无障碍树来查找扩展图标——无需像素坐标。
2. 为node授予辅助功能权限
前往系统设置 → 隐私与安全性 → 辅助功能，添加您的node二进制文件。没有此权限，Peekaboo无法发送点击事件。
使用以下命令查找node路径：which node
3. openclaw.json浏览器配置文件
将此内容添加到您的~/.openclaw/openclaw.json：
json
browser: {
profiles: {
chrome: {
cdpUrl: http://127.0.0.1:18792,
driver: extension,
color: #FF5A36
}
}
}
编辑后重启网关：openclaw gateway restart
4. 在Chrome中加载并固定扩展
OpenClaw Browser Relay扩展必须以解压扩展的形式加载到Chrome中。它随OpenClaw一起提供，位于：
~/.openclaw/browser/chrome-extension
通过chrome://extensions → 开发者模式开启 → 加载已解压的扩展程序加载。
扩展还必须固定到工具栏。 脚本通过Chrome的无障碍树查找图标，该树只暴露固定到工具栏的扩展——不显示隐藏在扩展面板内的图标。固定方法：点击拼图图标 → 点击OpenClaw Browser Relay旁边的图钉图标。
工作原理
脚本使用Chrome的无障碍树（而非像素坐标）查找扩展图标。图标的描述根据状态变化：
- - 未附加： OpenClaw Browser Relay（点击附加/分离）
- 已附加： OpenClaw Browser Relay：已附加（点击分离）
Peekaboo扫描描述以OpenClaw Browser Relay开头的弹出按钮元素，确定状态，并在需要时点击附加。最多重试8次（每2秒一次），以应对Chrome启动缓慢的情况。
扫描前需要最大化窗口——Chrome的工具栏图标在小型或默认大小的窗口的无障碍树中不可见。
脚本执行步骤
- 1. 快速路径 — 如果Chrome正在运行且徽章显示已附加，立即退出（约2秒）
- 终止所有正在运行的Chrome实例
- 修改~/Library/Application Support/Google/Chrome/Default/Preferences以抑制重新启动时的恢复页面？对话框
- 打开Chrome访问https://info.cern.ch/——世界上第一个网站，一个428字节的静态HTML文件，无任何反机器人技术、JavaScript、Cookie或Cloudflare
- 通过Peekaboo最大化窗口（工具栏可见性必需）
- 扫描无障碍树查找扩展图标（最多重试8次，间隔2秒）
- 点击图标进行附加
- 返回前验证状态已变为已附加
已知陷阱
| 方法 | 失败原因 |
|---|
| 硬编码像素坐标 | 在非测量时的任何屏幕尺寸下都会失效 |
| 使用Ctrl+Shift的AppleScript keystroke |
修饰键被静默丢弃——只有裸键触发 |
| Chrome扩展键盘快捷键 | 扩展清单没有commands——快捷键不触发附加 |
| 使用视觉模型定位图标 | 在任何分辨率下对工具栏UI都不够可靠 |
| 跳过窗口最大化 | 工具栏图标在小型窗口的无障碍树中不出现 |
| 扩展未固定到工具栏 | 未固定的扩展隐藏在扩展面板内——在无障碍树中不可见 |
| 配置中的配置文件名称或端口错误 | browser(profile=chrome)要求配置文件名称恰好为chrome并指向端口18792 |
Token效率提示
python
✅ 使用snapshot读取页面内容（约3k tokens）
browser(action=snapshot, profile=chrome, compact=True)
❌ 避免使用截图+视觉模型进行UI元素检测
→ 对工具栏/坐标识别不可靠
→ 比snapshot贵10–50倍
集成模式
任何需要Chrome中继的技能都应首先调用此脚本：
bash
1. 附加
bash
/scripts/attach.sh
2. 导航
browser(action=navigate, profile=chrome, targetUrl=https://target.com)
3. 自动化
browser(action=snapshot, profile=chrome, compact=True)
browser(action=act, profile=chrome, request={kind: click, ref: ...})
