ChromeControlProxy(CCP)

宿主机 chrome-control-proxy 服务调用指南。通过 HTTP 控制 Chrome 生命周期与 Playwright（page-dom 快照、run 脚本）。适用于 OpenClaw 在容器内访问 host.docker.internal:3333 或宿主机直接访问 127.0.0.1:3333。...

Security Scan

The skill is an instruction-only guide for talking to a host-side chrome-control-proxy HTTP service; its requirements and instructions are generally consistent with that purpose.

Purpose & Capability

The SKILL.md documents HTTP APIs for a host-side chrome-control-proxy; asking for the node binary is plausible because the upstream proxy is a Node package, but as an instruction-only client the skill itself does not require node to perform HTTP calls. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

Instructions are limited to calling the proxy's HTTP endpoints (health, browser start/stop, playwright page-dom/run) and include practical sequencing and safety guidance. The file does not instruct reading unrelated files, environment variables, or transmitting data to endpoints outside the proxy.

Install Mechanism

There is no install spec and no code files — the skill is instruction-only, which minimizes installation risk. The README advises installing the proxy on the host via npm, but the skill does not perform or automate any downloads itself.

Credentials

The skill does not request any environment variables or credentials (proportional). However, the documented capability (running arbitrary async Playwright script bodies on a host browser) can access page contents and potentially sensitive data; users should treat network access to the proxy as high-privilege.

Persistence & Privilege

The skill is not always-enabled and does not request persistent system-wide privileges or modify other skills. Autonomous invocation is allowed by default (normal for skills) but not an additional flagged privilege here.

Assessment

This skill is coherent: it only documents how to call a host-side chrome-control-proxy service. Before installing/use: (1) verify you trust the host service (the proxy will run Playwright scripts inside a host browser and can read page content); (2) do not expose /playwright/run to untrusted networks or agents; (3) note that the registry metadata lists node as a required binary — that makes sense for running the proxy itself but is not necessary just to make HTTP calls from the agent; (4) if you deploy in Docker ensure host.docker.internal or extra_hosts is configured as described; and (5) review the upstream GitHub repo and the proxy code before installing the proxy on any host you care about.

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（见下文参数）。
4. 执行操作：POST /playwright/run（见下文参数）。

page-dom 与 run 在服务端 串行队列，不要假设并行请求能同时操作同一标签页。

---

POST /playwright/page-dom

用于把页面信息交给模型生成脚本，优先用 Playwright 专用快照减 token。

建议 body：

• url：要打开的地址（可选；不传则对当前 target 对应标签页快照）。
• waitUntil：如 networkidle、load。
• timeout：导航超时毫秒数。
• target：first | last | new。
• includeHtml: false：不需要整页 HTML 时务必关闭。
• includePlaywrightSnapshot: true：返回 playwright.targets[]，每项含 tag、name、placeholder、suggestedLocator 等，便于写 page.locator / getByRole。
• selector：只截取某子树（如主内容区）。
• includeInnerText / includeAccessibility：按需。

响应中 playwright 过大可能被截断，注意 playwrightTruncated。

---

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/run

停止 Chrome 会断开 Playwright 的 CDP 连接；再次自动化前需重新 browser/start 并确保 Playwright 能连上。

---

CLI 备忘（宿主机）

全局安装包后可用 ccp start|stop|restart|status 管理 HTTP 进程，详见项目 README.md。