Skill: zhengxiangqi/chrome-control-proxy (version 1.0.2)

--- name: chrome-control-proxy description: 宿主机 chrome-control-proxy 服务调用指南。通过 HTTP 控制 Chrome 生命周期与 Playwright（page-dom 快照、run 脚本）。适用于 OpenClaw 在容器内访问 host.docker.internal:3333 或宿主机直接访问 127.0.0.1:3333。必读以避免 Playwright 与请求顺序踩坑。 version: 1.0.2 metadata: openclaw: emoji: 🌐 homepage: https://github.com/zhengxiangqi/chrome-control-proxy os: - macos - linux - windows requires: bins: - node --- # chrome-control-proxy 服务（OpenClaw） ## 前置条件 1. 宿主机已安装 **Node ≥ 18**，并全局安装服务包：`npm install -g chrome-control-proxy`。 2. 服务已启动：宿主机执行 `ccp start`，默认 **`http://127.0.0.1:3333`**。 3. 自动化前通常需 **Chrome 已带远程调试**：`POST /browser/start`（或你手动用 `--remote-debugging-port=9222` 启动）。 4. 容器内将主机换为 **`host.docker.internal:3333`**（Linux Docker 可能需配置 `extra_hosts`）。 --- ## 推荐调用顺序（自动化任务） 1. `GET /health` → 确认 HTTP 服务可用；`browser.running` 为 false 时先 `POST /browser/start`。 2. `GET /playwright/status` → 确认 CDP 可连（失败则检查 Chrome 是否在 `CHROME_PORT` 监听）。 3. 需要页面结构时：`POST /playwright/page-dom`，优先传 `selector` 与 `playwrightSnapshotMode: "compact"`。 4. 只执行动作：`POST /playwright/run`；动作前后都要拿快照时优先用 `POST /playwright/pipeline`。 `page-dom`、`pipeline` 与 `run` 在服务端 **串行队列**，不要假设并行请求能同时操作同一标签页。 --- ## POST /playwright/page-dom 用于把页面信息交给模型生成脚本，**优先用 Playwright 专用快照减 token**。 **建议 body：** - `url`：要打开的地址（可选；不传则对当前 `target` 对应标签页快照）。 - `waitUntil`：如 `domcontentloaded`、`networkidle`、`load`。**页面分析优先 `domcontentloaded`**。 - `timeout`：导航超时毫秒数。 - `target`：`first` | `last` | `new`。 - **`includeHtml: false`**：不需要整页 HTML 时务必关闭。 - **`includePlaywrightSnapshot: true`**：返回 `playwright.targets[]`，每项含 `tag`、`name`、`placeholder`、`suggestedLocator` 等，便于写 `page.locator` / `getByRole`。 - **`playwrightSnapshotMode: "compact"`**：只保留精简的 `targets[]` 字段，更适合高频分析链路。 - `selector`：只截取某子树（如主内容区）。 - `includeInnerText` / `includeAccessibility`：按需。 响应中 `playwright` 过大可能被截断，注意 `playwrightTruncated`。 --- ## POST /playwright/pipeline 用于一次请求完成以下任意组合： - 外层导航到目标页 - `beforePageDom`：执行前快照 - `script`：执行脚本 - `afterPageDom`：执行后快照 适合“点击后还要继续分析页面状态”的链路，避免额外再调一次 `page-dom`。 --- ## POST /playwright/run Body 中 **`script`** 为字符串，内容是 **async 函数体**（不是完整 `async function(){ }` 包裹），可： - `await page.goto(...)` - `await page.locator(...).click()` - `return { ok: true, ... }` 把结果回传给 HTTP JSON。 注入变量：**`page`、`context`、`browser`**（与当前 CDP 浏览器一致）。 ### 踩坑 1：外层 `url` 与脚本内导航 若请求 body 里带了 **`url`**，服务会 **先对该 URL 执行 `goto`，再执行脚本**。 - **登出再登入、先清 Cookie 再打开登录页**：请 **不要** 在外层传 `url`，只在脚本里写 `await page.context().clearCookies()`、`localStorage.clear()`、`sessionStorage.clear()` 后再 `goto` 业务站。否则会出现「先跳进已登录态页面，再清 Cookie」的顺序错误。 ### 踩坑 2：会话与多步 OAuth 统一登录常跳转到独立域名（如 OAuth）。多步流程（账号 → 租户）可用 **多次 `run`**，且 **`target` 保持一致**（如 `first`），除非有意新开标签页用 `new`。 ### 踩坑 3：便捷登录 / 确认框 若出现「便捷登录」等 **Element Plus / Dialog**，优先点 **主按钮**：如 `.el-message-box__btns .el-button--primary`、`.el-dialog__footer .el-button--primary`，或 `getByRole('button', { name: /确认|确定|继续/ })`。 仅在 **`input[name="account"]` 等元素可见** 时再填账号密码验证码，避免「不必等输密码」的场景下仍机械填表。 ### 踩坑 4：UI 退出登录 不要直接点隐藏菜单里的「退出登录」节点（可能被首页层遮挡）。优先 **`clearCookies` + 存储清理** 或先展开用户下拉再点退出。 ### 踩坑 5：超时 大页面或慢网络：增大 `timeout`（导航）与 **`scriptTimeout`**（脚本总执行时间，受 `PLAYWRIGHT_RUN_DEFAULT_MS` 等影响）。 ### 踩坑 6：安全 脚本在沙箱中执行，**不要对公网暴露** 本服务；勿向不可信方开放 `/playwright/run`。 --- ## 与浏览器控制接口的关系 | 能力 | 路径 | |------|------| | 启停 Chrome | `POST /browser/start`、`stop`、`restart` | | 健康检查 | `GET /health`、`GET /browser/status` | | Playwright | `GET /playwright/status`、`POST /playwright/page-dom`、`POST /playwright/pipeline`、`POST /playwright/run` | 停止 Chrome 会断开 Playwright 的 CDP 连接；再次自动化前需重新 `browser/start` 并确保 Playwright 能连上。 --- ## CLI 备忘（宿主机） 全局安装包后可用 **`ccp start|stop|restart|status`** 管理 HTTP 进程，详见项目 **`README.md`**。


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)