浏览器自动化

CrabCode 支持默认的内置浏览器模式（crabcode-browser）和真实 Chrome 扩展模式：导航、点击、读 console、截图、监听网络。

是什么

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

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

默认后端是 crabcode-browser —— 一个原生守护进程（agent-browser 的 Apache-2.0 分支），驱动独立 Chromium 会话；桌面发行包已内置该可执行文件，首次使用会自动下载 Chrome for Testing（或复用本机已装的 Chrome）。历史版本文档提到的 playwright-cli 后端已经移除。模型和桌面端浏览器自动化页面默认走内置浏览器模式；只有用户明确要求真实 Chrome、任务需要登录态/OAuth/SSO，或内置后端无法访问目标页面时，才切到扩展模式。

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

何时会看到这个文档

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

内置浏览器模式：默认浏览器自动化

内置浏览器模式通过 crabcode browser ... 与 crabcode-browser 守护进程通信，启动独立 Chromium profile。它不依赖 Chrome 扩展，也不会读取你日常 Chrome 的登录态。

典型流程：

bash

crabcode browser status --json      # 报告 "backend":"crabcode-browser"
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full --profile dev
crabcode browser stop --profile dev
crabcode browser status --json      # 报告 "backend":"crabcode-browser"
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full --profile dev
crabcode browser stop --profile dev

常用能力包括：

会话与 profile：status、start、stop、profiles、create-profile、delete-profile、reset-profile
标签页与导航：tabs、open、focus、close、navigate、back、forward、reload
检查：DOM snapshot（元素引用为 @eN）、screenshot、pdf、console、errors、requests（支持 --filter <regex>、--clear、--static）
动作：click、type、press、hover、scrollintoview、drag、select、fill、upload、dialog、wait、evaluate、highlight
存储与产物：cookies、storage、download、waitfordownload、trace、set（offline / headers / credentials / geolocation / media / device）

网络请求读取是 id-based 单命令：先 crabcode browser requests --json [--filter <regex>] 列出请求并取 id，再 crabcode browser network request <id> 一次拿到该请求的 request + response 详情（headers + body）。没有按 index 分开读 headers / body 的命令；旧的 responsebody <pattern> 形式已废弃，会返回 unsupported_action。

crabcode-browser 可执行文件的查找顺序是：CRABCODE_BROWSER_BINARY 指向的自定义可执行文件、运行程序同目录、<exe>/bin/、最后是 ~/.crabcode/bin/。高风险动作（evaluate 任意 JS、upload、download、fill --submit 提交表单、JS wait 断言）需要显式授权或 CRABCODE_BROWSER_ALLOW_RISKY。

扩展模式：真实 Chrome 登录态

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

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

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

shell

/chrome
/chrome

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

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

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

模型可用的工具（公开 40 项）

扩展模式下模型会使用 crabcode-in-chrome skill 和一组 mcp__chrome-automation__* 工具（内置浏览器模式对应 crabcode-browser skill）。40 项公开工具按用途分组如下：

自动化（点击 / 输入 / 表单 / 导航）

工具	用途	风险
`computer`	单击元素	可见写入
`form_input`	输入到表单字段	敏感写入
`form_fill_form`	批量填写表单	敏感写入
`navigate` / `navigate_back` / `navigate_forward` / `reload_page`	URL 导航 / 前进 / 后退 / 刷新	可见写入
`resize_window`	调整窗口大小	可见写入
`handle_dialog`	处理 alert / confirm / prompt	可见写入
`shortcuts_execute`	模拟按键	可见写入
`tabs_create_mcp`	开新标签	可见写入
`update_plan`	提交计划（模型→用户确认）	只读

观察（读页面 / 读元素 / 读日志）

工具	用途	风险
`read_page` / `get_page_text`	读 DOM / 读纯文本	只读
`find`	元素查找	只读
`take_screenshot`	截图（轻量）	只读
`read_console_messages`	读 console（支持 `pattern` 正则过滤）	只读
`read_network_requests`	读网络请求	只读
`tabs_context_mcp` / `shortcuts_list`	列标签 / 列可用快捷键	只读
`wait_for`	等待元素 / 条件	只读
`session_list` / `session_inspect` / `cdp_list`	列出会话 / 查看会话 / 列 CDP target	只读

产物（GIF / PDF / HAR / trace / playback）

工具	用途	风险
`gif_creator`	录 GIF（多步操作回放）	敏感写入
`print_pdf`	把页面导出为 PDF	敏感写入
`export_har`	导出 HAR（网络抓包）	敏感读取
`export_trace`	导出 trace（可回放追踪）	敏感读取
`export_playback`	导出 playback manifest（可回放）	敏感读取

存储 / 上传

工具	用途	风险
`upload_image`	上传文件到表单	敏感写入

高风险（执行任意 JS）

工具	用途	风险
`javascript_tool`	在页面上下文执行任意 JavaScript	高风险

高级会话（session / CDP）

工具	用途	风险
`session_create` / `session_select` / `session_pause` / `session_resume` / `session_close` / `session_reset`	创建 / 选择 / 暂停 / 恢复 / 关闭 / 重置会话	可见写入
`cdp_attach` / `cdp_detach`	接 / 离开外部 CDP target	可见写入
`cdp_command`	直接发 CDP command	敏感写入

怎么选

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

典型用例

shell

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

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

shell

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

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

限制与注意

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

故障排查

现象	常见原因	修复
桌面端提示「未找到内置浏览器」	发行包缺 `crabcode-browser` 可执行文件	更新到最新版 CrabCode 桌面端（发行包已自带）；或设 `CRABCODE_BROWSER_BINARY` 指向 `crabcode-browser` 可执行文件
内置浏览器模式页面没有你的登录态	内置浏览器模式使用独立 Chromium profile	改用扩展模式，或在内置浏览器 profile 中单独登录
扩展模式提示浏览器桥未连接	扩展未安装、native host 未注册或当前页面未连接	打开扩展安装向导，确认 `chrome://extensions` 已启用扩展并重新连接
扩展 side panel 显示未连接	native host manifest 未匹配扩展 id	设置 `CRABCODE_CHROME_EXTENSION_ID` 为 Chrome 显示的真实扩展 id 后重启 CrabCode