文档
中 / EN主站控制台
推荐给好友，福利领不停！好友同步开通最高 1000 万词元额度 · 后续消费分佣最高 30%。
+50万 Token生成链接

浏览器自动化

CrabCode 支持默认的 playwright-cli 模式和真实 Chrome 扩展模式：导航、点击、读 console、截图、监听网络。

是什么

CrabCode 的浏览器自动化不是单一的 Chrome 扩展能力，而是两套相互独立的后端：

模式使用的浏览器连接方式适用场景
CLI 模式（默认）本机独立 Chromiumplaywright-cli 子进程自动化脚本、CI、隔离会话、常规前端调试
扩展模式你日常使用的 ChromeCrabCode in Chrome 扩展 + native host真实登录态、OAuth/SSO、内网页面、需要复用日常 Chrome 的场景

默认后端是 playwright-cli。模型和桌面端浏览器自动化页面默认走 CLI 模式；只有用户明确要求真实 Chrome、任务需要登录态/OAuth/SSO，或 CLI 后端无法访问目标页面时，才切到扩展模式。

两种模式不共享上下文：cookies、登录态、本地存储、下载目录、扩展权限都是独立的。CrabCode 不会静默把任务从一个后端切到另一个后端；需要切换时，桌面端会给出明确提示，由用户决定。

何时会看到这个文档

  • 在 TUI 里输入 /chrome 后的引导界面
  • 桌面端「浏览器自动化」页面的帮助入口
  • 扩展模式未连接、需安装扩展或需重新连接时

CLI 模式：默认浏览器自动化

CLI 模式通过 crabcode browser ... 调用 playwright-cli，启动独立 Chromium profile。它不依赖 Chrome 扩展，也不会读取你日常 Chrome 的登录态。

典型流程：

bash
crabcode browser status --json
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full-page --profile dev
crabcode browser stop --profile dev
crabcode browser status --json
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full-page --profile dev
crabcode browser stop --profile dev

常用能力包括：

  • profile、tab、导航与页面刷新
  • DOM snapshot、截图、PDF、console、errors
  • 网络请求列表与按 1-based index 读取 request / response body
  • 点击、输入、选择、上传、下载、等待、执行 JS
  • cookies、storage、trace、locator 高亮

playwright-cli 的查找顺序是：CRABCODE_PLAYWRIGHT_CLI 指向的自定义可执行文件、项目内 node_modules/.bin/playwright-cli、最后是 PATH。高风险动作（例如任意 JS、上传、下载、提交表单）需要显式授权或 CRABCODE_BROWSER_ALLOW_RISKY。

扩展模式：真实 Chrome 登录态

扩展模式通过 CrabCode in Chrome 挂到你正在使用的 Chrome。它能复用真实账号、cookies、浏览器扩展和站点权限，适合调试必须登录的业务系统、OAuth/SSO、内网页面和只在日常 Chrome 里能访问的场景。

安装包和图文步骤在这里：CrabCode 浏览器扩展安装向导。

在 TUI 里也可以进入扩展设置：

shell
/chrome
/chrome

引导菜单会按当前状态显示：

  1. Install Chrome extension —— 打开 扩展安装向导
  2. Reconnect extension —— 重新建立扩展 ↔ CrabCode 连接
  3. Manage permissions —— 跳到扩展的站点权限管理
  4. Enabled by default: Yes/No —— 控制新会话是否自动启用扩展模式

如果 Chrome 分配的扩展 id 与 CrabCode 默认占位 id 不同，需要把真实 id 写入 CRABCODE_CHROME_EXTENSION_ID 后重启 CrabCode，native host manifest 才会允许扩展连接。

扩展模式下模型会使用 crabcode-in-chrome skill 和 mcp__chrome-automation__* 工具，能力包括读页面、读 console / network、点击输入、导航、截图、GIF、PDF、HAR、trace、外部 CDP 和会话管理等。

怎么选

任务推荐模式
打开 localhost 做前端验证、截图、读 consoleCLI 模式
CI / 自动化脚本 / 希望隔离浏览器 profileCLI 模式
要复用你 Chrome 里的登录态、cookies、扩展扩展模式
OAuth / SSO / 公司内网 / 人机验证后页面扩展模式
不确定先用哪个先用 CLI 模式，需要真实登录态时再显式切到扩展模式

典型用例

shell
帮我打开 localhost:3000，登录然后看看 dashboard 有没有 console error
帮我打开 localhost:3000，登录然后看看 dashboard 有没有 console error

默认会优先走 CLI 模式：开独立 Chromium → 导航 → 填表 → 等加载 → 读取 console → 报告。

shell
用我当前 Chrome 登录态打开公司后台，检查订单页网络请求。
用我当前 Chrome 登录态打开公司后台，检查订单页网络请求。

这类任务需要扩展模式：先确认 CrabCode in Chrome 已安装并连接，再读取当前 Chrome 标签页和网络请求。

限制与注意

  • 不要把扩展当作默认模式：扩展模式能看到你的真实登录态，用完建议断开；常规页面验证优先用 CLI 模式。
  • 两种模式不共享状态：CLI 模式里登录过，不代表扩展模式已登录；反过来也一样。
  • 不要触发原生对话框：alert / confirm / prompt 会阻塞扩展；必要时先让模型使用 dialog 处理能力。
  • console 默认全量：让模型按 pattern 或关键字过滤，减少噪声。
  • 失败 2-3 次就停：不要让模型在浏览器里反复尝试同一失败动作。
  • 敏感页面谨慎截图和导出：邮箱、支付、后台、身份认证页面可能包含令牌或隐私信息。

故障排查

现象常见原因修复
桌面端提示「未找到 playwright-cli」CLI 模式找不到可执行文件安装或修复 @playwright/cli，或设置 CRABCODE_PLAYWRIGHT_CLI=/abs/path/to/playwright-cli
CLI 模式页面没有你的登录态CLI 模式使用独立 Chromium profile改用扩展模式，或在 CLI profile 中单独登录
扩展模式提示浏览器桥未连接扩展未安装、native host 未注册或当前页面未连接打开 扩展安装向导，确认 chrome://extensions 已启用扩展并重新连接
扩展 side panel 显示未连接native host manifest 未匹配扩展 id设置 CRABCODE_CHROME_EXTENSION_ID 为 Chrome 显示的真实扩展 id 后重启 CrabCode

相关