Chrome Control Proxy

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

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。