Chrome Use OpenClaw Skill
Control your local Chrome browser via chrome.debugger API using a Chrome extension. Provides Playwright-like functionality with full browser control using your existing Chrome profile, with improved stealth against bot detection.
How to Use (Read First)
⚠️ Non-Headless Mode Required
Do NOT use headless Chrome. Cloudflare and anti-bot systems detect and block headless browsers. Always launch Chrome with the built-in
launchChrome() method. If running in a headless environment (no display), Chrome must still be launched in non-headless mode — the extension and debugger API require it.
⚠️ Initialization Sequence
The extension requires 15 seconds to initialize after Chrome starts. Calling
connect() too early will fail.
CODEBLOCK0
When implementing: always use the built-in launchChrome() function — never spawn Chrome yourself or use other launch methods.
Rules
- - Always import from
./index.js (relative path), NOT from INLINECODE5 - Do NOT run
google-chrome or chromium commands directly - Do NOT use CDP protocol or
chrome.debugger directly - Always wait 15 seconds after
launchChrome() before calling INLINECODE10 - Chrome can be running already —
launchChrome() will open a new window if Chrome is already running - If port 9224 is in use: run
fuser -k 9224/tcp first
Features
- - Stealth First: Uses
chrome.debugger API via extension to evade anti-bot detection (Cloudflare, reCAPTCHA, fingerprinting) - Auto WebSocket Server: Automatically starts and manages WebSocket server for extension communication
- Real Browser Rendering: Access JavaScript-rendered content and SPAs that standard search cannot
- Direct Search Engine Access: Query Google, Bing, etc. as a real user - returns unfiltered, real-time results
- Full Browser Control - Navigate, click, fill, hover, scroll, screenshot, execute JavaScript
- Tab Management - List, create, close, and switch tabs
- Cross-Platform - Supports macOS, Windows, and Linux
Installation (One-time)
Chrome extension must be installed manually (one-time):
- 1. Open Chrome → INLINECODE14
- Enable "Developer mode" (toggle in top right)
- Click "Load unpacked"
- Select the
extension/ folder in the skill directory
After this, the extension loads automatically every time Chrome starts — no need to reload it each session.
Install npm dependencies:
CODEBLOCK1
Functions
Connection Management
connect()
Connect to Chrome via extension WebSocket server. Starts the WebSocket server and waits for the extension to connect. Does NOT launch Chrome - you must call
launchChrome() first.
CODEBLOCK2
disconnect()
Disconnect from Chrome browser. Does NOT close Chrome - leaves it running.
isConnected()
Check if currently connected to Chrome extension. Returns: boolean
launchChrome()
Launch Chrome with the extension loaded. After calling this,
you MUST wait 15 seconds before calling
connect().
CODEBLOCK3
Page Operations
navigate(url)
Navigate to a URL.
evaluate(script)
Execute JavaScript synchronously.
CODEBLOCK4
getHtml()
Get the page HTML. Returns: string
screenshot(fullPage?)
Take a screenshot.
fullPage (boolean, optional): Capture full page or just viewport (default: false). Returns: string (Base64 PNG)
Element Interaction
click(selector)
Click an element using CSS selector.
fill(selector, value)
Input text into an element.
Tab Management
listTabs()
List all open tabs.
CODEBLOCK5
switchTab(tabId)
Switch to a different tab.
closeTab(tabId)
Close a tab.
newTab(url?)
Create a new tab.
Common Mistakes
| Don't Do This | Why |
|---|
| INLINECODE19 | Not a npm package. Use INLINECODE20 |
| INLINECODE21 |
Use
launchChrome() instead |
|
npm install chrome-use | Not published to npm |
| Calling
connect() immediately after
launchChrome() | Always wait 15 seconds first |
| Port 9224 in use | Run
fuser -k 9224/tcp first |
Troubleshooting
connect() fails
- 1. Did you wait 15 seconds after
launchChrome()? - Is port 9224 free? (
fuser -k 9224/tcp) - Is the extension installed in Chrome?
Port 9224 already in use
CODEBLOCK6
Notes
- - Node.js starts a WebSocket server (port 9224) via
connect(); the Chrome extension connects to Node.js as a WebSocket client, then uses chrome.debugger API to control Chrome - INLINECODE31 does NOT close Chrome by default
- All selectors use CSS selector syntax
Chrome Use OpenClaw 技能
通过 Chrome 扩展程序使用 chrome.debugger API 控制本地 Chrome 浏览器。提供类似 Playwright 的功能，可使用现有 Chrome 配置文件实现完整的浏览器控制，并具有更强的反机器人检测隐身能力。
使用方法（请先阅读）
⚠️ 需要非无头模式
不要使用无头 Chrome。 Cloudflare 和反机器人系统会检测并阻止无头浏览器。始终使用内置的 launchChrome() 方法启动 Chrome。如果在无显示环境（无显示器）中运行，Chrome 仍必须以非无头模式启动——扩展程序和调试器 API 需要此模式。
⚠️ 初始化顺序
扩展程序在 Chrome 启动后需要 15 秒进行初始化。 过早调用 connect() 会失败。
javascript
// 从 ./index.js 导入（相对路径，不是 chrome-use）
import { connect, navigate, evaluate, click, fill, screenshot, disconnect } from ./index.js;
import { launchChrome } from ./index.js;
// 步骤 1：启动 Chrome 并加载扩展程序
await launchChrome();
// 步骤 2：等待 15 秒让扩展程序服务工作线程初始化
await new Promise(r => setTimeout(r, 15000));
// 步骤 3：连接到 Chrome
await connect();
// 步骤 4：使用
await navigate(https://example.com);
// ... 执行操作 ...
// 完成后断开连接
disconnect();
实现时：始终使用内置的 launchChrome() 函数——不要自行启动 Chrome 或使用其他启动方法。
规则
- - 始终从 ./index.js（相对路径）导入，而不是从 chrome-use 导入
- 不要直接运行 google-chrome 或 chromium 命令
- 不要直接使用 CDP 协议或 chrome.debugger
- 在调用 launchChrome() 后始终等待 15 秒再调用 connect()
- Chrome 可以已经在运行——如果 Chrome 已在运行，launchChrome() 将打开一个新窗口
- 如果端口 9224 被占用：先运行 fuser -k 9224/tcp
功能特性
- - 隐身优先：通过扩展程序使用 chrome.debugger API 来规避反机器人检测（Cloudflare、reCAPTCHA、指纹识别）
- 自动 WebSocket 服务器：自动启动和管理用于扩展程序通信的 WebSocket 服务器
- 真实浏览器渲染：访问标准搜索无法获取的 JavaScript 渲染内容和单页应用
- 直接搜索引擎访问：以真实用户身份查询 Google、Bing 等——返回未过滤的实时结果
- 完整浏览器控制 - 导航、点击、填写、悬停、滚动、截图、执行 JavaScript
- 标签页管理 - 列出、创建、关闭和切换标签页
- 跨平台 - 支持 macOS、Windows 和 Linux
安装（一次性）
Chrome 扩展程序需要手动安装（一次性）：
- 1. 打开 Chrome → chrome://extensions/
- 启用开发者模式（右上角开关）
- 点击加载已解压的扩展程序
- 选择技能目录中的 extension/ 文件夹
之后，扩展程序会在每次 Chrome 启动时自动加载——无需每次会话重新加载。
安装 npm 依赖：
bash
cd ~/workspace/skills/chrome-use && npm install
函数
连接管理
connect()
通过扩展程序 WebSocket 服务器连接到 Chrome。启动 WebSocket 服务器并等待扩展程序连接。不会启动 Chrome——必须先调用 launchChrome()。
javascript
await launchChrome();
await new Promise(r => setTimeout(r, 15000));
await connect();
// 返回：{ status: connected, mode: debugger, port: 9224, extensioninstalled: true, tabid: 12345 }
disconnect()
断开与 Chrome 浏览器的连接。不会关闭 Chrome——保持其运行状态。
isConnected()
检查当前是否已连接到 Chrome 扩展程序。返回：布尔值
launchChrome()
启动加载了扩展程序的 Chrome。调用此函数后，
必须等待 15 秒再调用 connect()。
javascript
{ status: launched, pid: 12345 }
页面操作
navigate(url)
导航到指定 URL。
evaluate(script)
同步执行 JavaScript。
javascript
const title = await evaluate(document.title);
getHtml()
获取页面 HTML。返回：字符串
screenshot(fullPage?)
截取屏幕截图。fullPage（布尔值，可选）：捕获整个页面或仅视口（默认：false）。返回：字符串（Base64 编码的 PNG）
元素交互
click(selector)
使用 CSS 选择器点击元素。
fill(selector, value)
向元素输入文本。
标签页管理
listTabs()
列出所有打开的标签页。
javascript
[
{ id: 708554825, title: Google, url: https://google.com, active: true },
{ id: 708554826, title: Example, url: https://example.com, active: false }
]
switchTab(tabId)
切换到不同的标签页。
closeTab(tabId)
关闭标签页。
newTab(url?)
创建新标签页。
常见错误
| 不要这样做 | 原因 |
|---|
| import ... from chrome-use | 不是 npm 包。使用 from ./index.js |
| google-chrome --load-extension=... |
改用 launchChrome() |
| npm install chrome-use | 未发布到 npm |
| 在 launchChrome() 后立即调用 connect() | 始终先等待 15 秒 |
| 端口 9224 被占用 | 先运行 fuser -k 9224/tcp |
故障排除
connect() 失败
- 1. 是否在 launchChrome() 后等待了 15 秒？
- 端口 9224 是否空闲？（fuser -k 9224/tcp）
- 扩展程序是否已在 Chrome 中安装？
端口 9224 已被占用
bash
fuser -k 9224/tcp
说明
- - Node.js 通过 connect() 启动 WebSocket 服务器（端口 9224）；Chrome 扩展程序作为 WebSocket 客户端连接到 Node.js，然后使用 chrome.debugger API 控制 Chrome
- disconnect() 默认不会关闭 Chrome
- 所有选择器使用 CSS 选择器语法
