Docs
EN / 中Main siteConsole
Refer friends. Keep the rewards coming!Your friend can unlock up to 10M tokens · earn up to 30% revenue share.
+500K TokensGenerate link

浏览器自动化 (Archive)

Archived original-language source from the legacy CrabClaw docs. This page is intentionally not machine-translated.

Crab Claw 内置企业级浏览器自动化系统，通过 Chrome DevTools Protocol (CDP) 深度控制浏览器，支持从简单的网页抓取到复杂的 AI 智能浏览全场景覆盖。

核心优势

四层操控模型

从传统 CSS 选择器到 AI 意图级浏览，逐层升级。ARIA 引用 + SOM 视觉标注让 LLM 精准操控页面元素。

21 个操作指令

覆盖导航、内容提取、元素交互、标签页管理、GIF 录制全场景。单一 browser 工具统一入口。

MCP 标准化接口

18 个 MCP 标准工具，与 Playwright MCP 命名对齐。可被任何符合 MCP 协议的 AI 工具调用。

按需启动零浪费

LazyBrowserController 懒加载——不使用浏览器时零资源消耗，首次调用自动发现或启动 Chrome。

Chrome 扩展增强

MV3 扩展 + Native Messaging 强保活，无需 --remote-debugging-port 启动参数，复用已有浏览器会话。

GIF 操作录制

一键录制浏览器操作为 GIF 动画，适合演示、Bug 复现、自动化流程文档化。

架构总览

shell
┌───────────────────────────────────────────────────────────────┐
│                    智能体运行时 (Agent Runtime)                 │
│                                                               │
│  意图路由器 ──→ tool_executor:executeBrowserTool()             │
│               21 actions — 四层操控模型                         │
│                      │                                        │
│  ┌───────────────────┼────────────────────────────────────┐   │
│  │   BrowserController 接口 (22 methods)                   │   │
│  │   ├─ Navigate / GetContent / Observe                    │   │
│  │   ├─ Click / ClickRef / Type / FillRef                  │   │
│  │   ├─ Screenshot / AnnotateSOM / AIBrowse                │   │
│  │   ├─ Start/Stop GIFRecording                            │   │
│  │   └─ ListTabs / CreateTab / CloseTab / SwitchTab        │   │
│  │                      │                                  │   │
│  │   LazyBrowserController (按需初始化 + 断线重连)           │   │
│  │                      │                                  │   │
│  │   PlaywrightBrowserController (CDP WebSocket)            │   │
│  └───────────────────────────────────────────────────────┘   │
│                      │                                        │
│  ┌───────────────────┼────────────────────────────────────┐   │
│  │   Chrome / Brave / Edge (CDP DevTools)                  │   │
│  │   ┌─────────────────────────────────┐                   │   │
│  │   │  Chrome Extension (MV3)         │                   │   │
│  │   │  chrome.debugger + Native Msg   │                   │   │
│  │   └─────────────────────────────────┘                   │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐   │
│  │  MCP Server — 18 tools (Playwright MCP 命名规范)        │   │
│  │  cmd/browser-mcp — 独立 stdio 二进制                    │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐   │
│  │  Rust CLI (oa-cmd-browser) — 40+ 命令                   │   │
│  └────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│                    智能体运行时 (Agent Runtime)                 │
│                                                               │
│  意图路由器 ──→ tool_executor:executeBrowserTool()             │
│               21 actions — 四层操控模型                         │
│                      │                                        │
│  ┌───────────────────┼────────────────────────────────────┐   │
│  │   BrowserController 接口 (22 methods)                   │   │
│  │   ├─ Navigate / GetContent / Observe                    │   │
│  │   ├─ Click / ClickRef / Type / FillRef                  │   │
│  │   ├─ Screenshot / AnnotateSOM / AIBrowse                │   │
│  │   ├─ Start/Stop GIFRecording                            │   │
│  │   └─ ListTabs / CreateTab / CloseTab / SwitchTab        │   │
│  │                      │                                  │   │
│  │   LazyBrowserController (按需初始化 + 断线重连)           │   │
│  │                      │                                  │   │
│  │   PlaywrightBrowserController (CDP WebSocket)            │   │
│  └───────────────────────────────────────────────────────┘   │
│                      │                                        │
│  ┌───────────────────┼────────────────────────────────────┐   │
│  │   Chrome / Brave / Edge (CDP DevTools)                  │   │
│  │   ┌─────────────────────────────────┐                   │   │
│  │   │  Chrome Extension (MV3)         │                   │   │
│  │   │  chrome.debugger + Native Msg   │                   │   │
│  │   └─────────────────────────────────┘                   │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐   │
│  │  MCP Server — 18 tools (Playwright MCP 命名规范)        │   │
│  │  cmd/browser-mcp — 独立 stdio 二进制                    │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐   │
│  │  Rust CLI (oa-cmd-browser) — 40+ 命令                   │   │
│  └────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────┘

四层操控模型

Crab Claw 提供从低级到高级的四层页面操控方式，适应不同场景需求：

L1: CSS Selector（传统选择器）

最基础的定位方式，直接使用 CSS 选择器：

shell
> 点击 #search-box
> 在 .btn-primary 上输入文字
> 点击 #search-box
> 在 .btn-primary 上输入文字

适用于结构固定、选择器稳定的页面。

L2: ARIA Ref（无障碍引用）— 推荐

通过 observe 操作获取页面的 ARIA 无障碍树，每个可交互元素分配唯一 ref 标识（如 e1、e2）：

shell
observe → 获取 ARIA 树 + ref 标注 + 截图
  ↓
LLM 分析页面结构，选择目标元素 ref
  ↓
click_ref e3 / fill_ref e5 "搜索内容"
observe → 获取 ARIA 树 + ref 标注 + 截图
  ↓
LLM 分析页面结构，选择目标元素 ref
  ↓
click_ref e3 / fill_ref e5 "搜索内容"

优势：语义稳定、跨页面复用、对页面结构变化鲁棒。

L3: SOM 视觉标注（屏幕标注）

使用 annotate_som 在截图上为每个元素标注数字编号，LLM 通过视觉识别选择目标：

shell
annotate_som → 带数字编号的截图 + 元素坐标列表
  ↓
LLM 看图选择: "点击编号 7 的按钮"
  ↓
click_ref 7
annotate_som → 带数字编号的截图 + 元素坐标列表
  ↓
LLM 看图选择: "点击编号 7 的按钮"
  ↓
click_ref 7

优势：不依赖 DOM 结构，适合动态渲染、iframe 嵌套等复杂页面。

L4: 意图级 AI 浏览（最高级）

描述目标，智能体自主导航完成任务：

shell
> ai_browse "在 GitHub 上找到 crabclaw 仓库并 star"
> ai_browse "在 GitHub 上找到 crabclaw 仓库并 star"

系统自动循环执行（最多 20 步）：截图分析 → 决策操作 → 执行 → 验证结果 → 下一步。

优势：零代码、零选择器，用自然语言驱动浏览器。

21 个操作指令完整表

操作参数返回操控层级说明
navigateurl截图基础导航到指定 URL
get_content—ARIA 树/innerText基础获取页面文本内容
observe—ARIA 树 + ref + 截图推荐获取可交互元素列表
annotate_som—SOM 截图 + 元素列表视觉截图上标注元素编号
clickselector截图L1 LegacyCSS 选择器点击
click_refref (e.g. "e1")截图L2 推荐ARIA ref 点击
typeselector, text截图L1 LegacyCSS 选择器输入
fill_refref, text截图L2 推荐ARIA ref 输入
screenshot—JPEG base64基础当前页面截图
evaluatescriptJS 结果高级执行 JavaScript
wait_forselector成功/超时基础等待元素出现
go_back——导航浏览器后退
go_forward——导航浏览器前进
get_url—URL 字符串基础获取当前页面 URL
ai_browsegoal操作日志 + 截图L4 意图级AI 自主浏览 (max 20 步)
start_gif_recording—确认录制开始 GIF 录制
stop_gif_recording—GIF + 帧数 + 字节数录制停止并保存 GIF
list_tabs—Tab 列表 JSON标签页列出所有标签页
create_taburl新 Tab 信息标签页创建新标签页
close_tabtarget_id确认标签页关闭标签页
switch_tabtarget_id确认标签页切换标签页

推荐工作流

shell
observe → 获取 ARIA 树 + ref + 截图
   ↓
LLM 分析页面结构，选择目标元素
   ↓
click_ref / fill_ref → 使用 ARIA ref 操作
   ↓
自动截图验证 → LLM 确认操作结果
   ↓
如需多步复杂操作: ai_browse → 自动循环
   ↓
如需视觉定位: annotate_som → LLM 看编号截图选择
observe → 获取 ARIA 树 + ref + 截图
   ↓
LLM 分析页面结构，选择目标元素
   ↓
click_ref / fill_ref → 使用 ARIA ref 操作
   ↓
自动截图验证 → LLM 确认操作结果
   ↓
如需多步复杂操作: ai_browse → 自动循环
   ↓
如需视觉定位: annotate_som → LLM 看编号截图选择

三种运行时模式

模式触发条件说明
lazy_local未配置 CDP URL（默认）首次使用时自动发现或拉起本地 Chrome，零配置开箱即用
direct_cdp已配置 Chrome CDP 地址直连已有 Chrome 实例，完整 CDP 能力
extension_relay使用浏览器扩展中继通过 MV3 扩展接管现有标签页，复用已登录会话

设计约束：

  • 只有 Gateway 有权判断运行时模式，前端和插件只消费契约，不自行猜测
  • 业务模块不得手工拼接 target WebSocket 地址，必须通过 ResolveTargetWsURL() 发现
  • CDP 连接断开后自动重置，下次调用重新发现/启动（断线重连）

Chrome 扩展

安装 Crab Claw 浏览器扩展（MV3）可显著增强自动化能力：

特性说明
免启动参数无需 --remote-debugging-port，通过 Native Messaging 连接
复用已有会话接管用户当前浏览器标签页，无需重新登录
Tab 管理attach/create/close/switch 完整标签页桥接
稳定连接Native Messaging Host 强保活机制
Cookie 访问读取现有登录态，供媒体子智能体使用

安装后在扩展配置页填入 Gateway 地址（默认 localhost:19001）即可连接。

MCP 标准化接口

Crab Claw 同时提供 18 个 MCP 标准的浏览器工具接口，与 Playwright MCP 命名对齐：

bash
# 启动独立 MCP 浏览器服务
crabclaw browser mcp
# 启动独立 MCP 浏览器服务
crabclaw browser mcp

MCP 工具可被任何支持 MCP 协议的 AI 工具（如 Claude Desktop、其他 MCP 客户端）调用，实现跨系统浏览器自动化。

GIF 操作录制

一键录制浏览器操作为 GIF 动画：

shell
> 开始录制
> (执行一系列浏览器操作)
> 停止录制

✓ 已保存 GIF: login_flow.gif (42 帧, 1.2MB)
> 开始录制
> (执行一系列浏览器操作)
> 停止录制

✓ 已保存 GIF: login_flow.gif (42 帧, 1.2MB)

适用场景：

  • 操作演示与教程制作
  • Bug 复现记录
  • 自动化流程文档化
  • 分享给团队成员

Rust CLI 命令 (40+)

通过 Rust CLI 直接控制浏览器：

bash
# 浏览器控制
crabclaw browser start          # 启动浏览器控制
crabclaw browser status         # 查看浏览器状态
crabclaw browser navigate URL   # 导航到 URL
crabclaw browser screenshot     # 截图
crabclaw browser evaluate "JS"  # 执行 JavaScript

# 标签页管理
crabclaw browser tabs           # 列出标签页
crabclaw browser tab-create URL # 创建新标签页
crabclaw browser tab-switch ID  # 切换标签页

# MCP 服务
crabclaw browser mcp            # 启动 MCP 浏览器服务
# 浏览器控制
crabclaw browser start          # 启动浏览器控制
crabclaw browser status         # 查看浏览器状态
crabclaw browser navigate URL   # 导航到 URL
crabclaw browser screenshot     # 截图
crabclaw browser evaluate "JS"  # 执行 JavaScript

# 标签页管理
crabclaw browser tabs           # 列出标签页
crabclaw browser tab-create URL # 创建新标签页
crabclaw browser tab-switch ID  # 切换标签页

# MCP 服务
crabclaw browser mcp            # 启动 MCP 浏览器服务

所有 CLI 命令通过 browser_rpc() 调用 Gateway 的 browser.request RPC 接口。

端口配置

端口说明默认值
Gateway主服务19001
Browser Control浏览器控制19002
Extension Relay扩展中继19004

端口可在 crabclaw.json 中自定义：

json
{
  "server": {
    "port": 19001
  },
  "browser": {
    "port": 19002,
    "extensionRelayPort": 19004
  }
}
{
  "server": {
    "port": 19001
  },
  "browser": {
    "port": 19002,
    "extensionRelayPort": 19004
  }
}

快速开始

确保系统安装了 Chrome、Brave 或 Edge 浏览器，然后在聊天中直接使用：

shell
> 打开 https://example.com 并截图
> 获取页面上所有可交互元素
> 点击搜索框并输入 "Crab Claw"
> 帮我自动在 GitHub 上搜索并 star 一个项目
> 开始录制我的操作为 GIF
> 打开 https://example.com 并截图
> 获取页面上所有可交互元素
> 点击搜索框并输入 "Crab Claw"
> 帮我自动在 GitHub 上搜索并 star 一个项目
> 开始录制我的操作为 GIF

相关文档：媒体智能体 · 视觉理解智能体 · 安全与审批