Skillppx logo

Chromium

基于CDP协议的持久化无头Chromium，支持自动化页面操作与登录态保持。

已扫描
适合谁
自动化测试工程师、网页数据采集开发者
不适合谁
无技术基础的普通用户、仅需简单浏览的用户
国内可用性
需网络配置。可能需要网络配置或第三方服务可访问。
安装难度
中等（★★☆）。基于终端操作、依赖、API Key 和本地环境要求的初步判断。

安装与下载

openclaw skills install @redf426/chromium
下载官方 ZIP

Skill 说明

命令、参数、文件名以原文为准

Chromium（持久化无头配置）

功能说明

  • 以无头模式启动 Chromium 浏览器，并使用持久化用户配置文件（登录状态、Cookie、localStorage 在重启后仍保留）。
  • 在 127.0.0.1 上暴露 Chrome DevTools Protocol（CDP），支持与其他浏览器工具集成。
  • 支持导入 Cookie，实现已登录会话的复用。

快速上手

1. 启动 Chromium

~/.openclaw/workspace/skills/chromium/scripts/start_chromium.sh

环境变量（全部可选）：

变量默认值说明
CHROMIUM_PROFILE_DIR$HOME/.openclaw/workspace/chromium-profile用户数据目录
CHROMIUM_DEBUG_PORT18801CDP 远程调试端口
CHROMIUM_LOG_FILE$HOME/.openclaw/workspace/logs/chromium.log日志文件路径
CHROMIUM_BIN自动检测（chromium、chromium-browser、google-chrome）浏览器可执行文件路径

2. 验证 CDP 是否就绪

curl -s http://127.0.0.1:18801/json/version

若返回包含 Browser 和 webSocketDebuggerUrl 的 JSON 内容，则表示已就绪。

3. 使用浏览器工具

browser navigate url=https://example.com
browser wait --load networkidle
browser snapshot

浏览器工具速查表

操作命令
打开页面browser navigate url=<URL>
等待加载完成browser wait --load networkidle
获取页面内容快照browser snapshot
点击元素browser click ref=<ref>
输入文本browser type ref=<ref> text=<text>
滚动至元素可视区域browser scrollintoview <ref>
截图browser screenshot
执行 JavaScriptbrowser evaluate --fn "document.title"

快照格式 — 重要提示

始终使用默认快照格式（不添加额外参数）：

browser snapshot

不要使用：

  • refs=aria — 返回无障碍树，但不包含可操作的引用标识符
  • depth=2 或其他深度限制 — 会导致 DOM 被截断，部分内容不可见

默认的 AI 格式返回完整的页面文本，并附带引用标识符（如 e12、e293 等），适用于点击和输入操作。

处理动态页面（SPA 应用）

单页应用（如 React、Next.js 等）会持续更新 DOM，导致引用标识符在快照之间失效。

每次导航后：

browser wait --load networkidle
browser snapshot

点击前：

browser scrollintoview <ref>
browser click <ref>

如果点击失败（提示“元素未找到或不可见”）：

  1. 重新执行 browser snapshot — 切勿复用旧的引用标识符
  2. 使用 browser screenshot 查看当前视觉状态
  3. 对于链接，直接通过 URL 导航，而非点击
  4. 作为最后手段，使用 JavaScript 执行：browser evaluate --fn "document.querySelector('...').click()"

Cookie 导入（已登录会话复用）

若需访问需要登录的网站，可从已登录的浏览器中导出 Cookie 并导入到当前环境。

步骤 1 — 导出 Cookie（在常规浏览器中操作）：

  • 安装 [Cookie-Editor](https://cookie-editor.com/) 插件
  • 访问目标网站（确保已登录）
  • 将 Cookie 导出为 JSON 格式，保存为 cookies.json
  • 上传至服务器：scp cookies.json server:/tmp/

步骤 2 — 导入

python3 ~/.openclaw/workspace/skills/chromium/scripts/import_cookies.py \
  /tmp/cookies.json \
  --domain example.com

步骤 3 — 验证：访问目标网站，确认是否保持登录状态。

数据存储位置

内容路径
浏览器配置文件$CHROMIUM_PROFILE_DIR（默认：~/.openclaw/workspace/chromium-profile）
启动日志$CHROMIUM_LOG_FILE（默认：~/.openclaw/workspace/logs/chromium.log）

故障排查

若启动后 3 秒内 CDP 无响应，请检查日志：

cat ~/.openclaw/workspace/logs/chromium.log

常见问题：

  • “地址已被占用” — 另一个 Chromium 实例正在运行。脚本会自动终止旧实例，如需手动处理，可执行：pkill -f "chromium.*remote-debugging"
  • SingletonLock 错误 — 存在过期的锁文件。脚本会在检测到无运行实例时自动删除。
  • **找不到 chromium 可执行文件** — 请设置 CHROMIUM_BIN 为正确的路径（例如 /usr/bin/google-chrome）。

系统要求

  • 主机上安装有 Chromium、Chromium Browser 或 Google Chrome
  • Python 3（用于 Cookie 导入脚本）
  • OpenClaw（具备浏览器工具支持）
R
@redf426

已收录 1 个 Skill

相关推荐