acrawl

  █████╗  ██████╗██████╗  █████╗ ██╗    ██╗██╗     
 ██╔══██╗██╔════╝██╔══██╗██╔══██╗██║    ██║██║     
 ███████║██║     ██████╔╝███████║██║ █╗ ██║██║     
 ██╔══██║██║     ██╔══██╗██╔══██║██║███╗██║██║     
 ██║  ██║╚██████╗██║  ██║██║  ██║╚███╔███╔╝███████╗
 ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚══╝╚══╝ ╚══════╝

可执行并观察的浏览器自动化 Agent。导航、点击和提取，或检查网络流量、调试控制台错误、分析性能并审计无障碍性。一个 Rust 二进制文件。

单个 Rust 二进制文件。全面的 DevTools 可观测性。43 个工具。25 个大模型提供商。内置 MCP 服务。

为什么选择 acrawl？

大多数浏览器 Agent 止步于导航和点击。acrawl 更进一步：Agent 还能检查网络请求、分析控制台错误、衡量页面性能、审计无障碍性并拦截网络调用——全面覆盖 DevTools 功能，且都可作为一等 Agent 工具使用。

它以单个 Rust 二进制文件的形式交付。无需 Python 运行时、Node 运行时或 Docker。将它放入任意服务端或 CI 流水线，描述目标即可；Agent 会判断要访问什么、点击什么、检查什么，以及何时结束。

• 一个二进制文件，无需运行时。cargo build --release 会生成独立可执行文件。无需 Python 或 Node 运行时——只需 Rust 和用于浏览器自动化的 Chromium 下载。
• **既能执行，也能观察。**Agent 将全面的 DevTools 功能作为一等工具使用：检查带有计时信息的网络请求、分析并去重控制台日志、流式传输 WebSocket 消息、衡量页面性能（TTFB、资源细分）、审计 Cookie 和浏览器存储、衡量 JS/CSS 覆盖率、运行 axe-core WCAG 无障碍审计，以及拦截或模拟网络调用。没有其他 Agent 框架能提供这些功能。
• **能确定的地方用确定性方式，必须用 AI 的地方才用 AI。**将循环、条件和并行分支定义为 JSON 脚本——执行时不会调用任何大模型。页面行为异常时再交由 Agent 处理。两全其美。
• **无需编写代码。**用自然语言描述目标。Agent 会规划、导航并提取内容。
• **智能获取。**静态页面通过 HTTP 提供（速度快）。需要 JavaScript 或交互时，acrawl 会检测 JS 框架标记（__next_data__、__nuxt、__vue、ng-app、React 根节点）、身份验证重定向和过短的 <noscript> 正文，然后无缝升级到无头浏览器。
• **子 Agent 并行处理。**将子 Agent 分派到不同浏览器标签页，各自拥有独立状态和步骤预算。URL 认领注册表可防止同级 Agent 重复爬取同一页面。
• **MCP 客户端和服务端。**通过 Model Context Protocol 服务扩展 Agent，添加自定义工具。也可以反向使用：运行 acrawl mcp，即可向 Claude Code、Cursor、VS Code、Zed 和其他 13 个客户端提供 38 个浏览器与 DevTools 工具，以及 run_goal。
• **25 个大模型提供商。**包括 Anthropic、OpenAI、Google Gemini、DeepSeek、AWS Bedrock、Azure OpenAI、Vertex AI、GitHub Copilot、Groq、Mistral、xAI、Cohere、Alibaba DashScope、OpenRouter 等。也可通过任何兼容 OpenAI 的端点接入自己的提供商。

如何比较？

与 AI 网页 Agent 和抓取工具相比

说明：

• browser-use（GitHub 星标数超过 85k）：基于 Python + Playwright，使用 DOM 和屏幕截图；通过 LiteLLM 支持 GPT/Claude/Gemini/Ollama，WebVoyager 得分为 89.1%。没有单个二进制文件，需要 Python 和 pip install。每个操作都会调用 LLM：每步耗时 2–5 秒，每项任务约 $0.02–0.30。云端版本提供隐身功能；可自托管版本则是纯 Playwright。
• Stagehand（Browserbase，星标数超过 21k）：基于 TypeScript + CDP（v3），结合确定性的 Playwright 与 AI 原语（act()、extract()、observe()）。操作缓存可重用成功的点击，无需再次调用 LLM。需要 Node；用于生产环境时还需要 Browserbase 云托管。
• Skyvern（星标数超过 21k，Apache 2.0）：以视觉为先（仅屏幕截图，不使用 DOM），可处理 DOM 工具难以应对的旧式门户和政府表单。提供免代码云端界面。每一步都会消耗视觉模型令牌，每项任务约 $0.10–0.50。WebVoyager 得分为 85.85%。
• Firecrawl（星标数超过 82k）：托管式抓取 API。可返回适用于 LLM 的 Markdown、提取 JSON，并抓取整个网站。它不是 Agent 式工具，多步骤交互能力有限。提供官方 MCP 服务。按页面计费，价格为每月 $19 起。
• Playwright MCP（Microsoft，星标数超过 29k）：通过无障碍树提供浏览器控制的 MCP 服务。操作耗时低于 100 毫秒，不消耗视觉令牌。它控制 LLM 客户端的浏览器，而非自行推理，因此无法自主根据目标进行导航。用于 GitHub Copilot Agent。

与原生 LLM 提供商的浏览功能相比

大多数 AI 提供商都提供某种形式的浏览功能，但这些功能是为对话式信息检索而设计的，而非程序化网页自动化。主要限制：

说明：

• ChatGPT Agent（OpenAI，2025 年 7 月）：在沙盒云虚拟机中运行，并配有自己的 Chromium 实例。可以浏览、点击和填写表单，但在敏感操作（购买、登录）前会暂停并请求用户确认。提供两种模式：用于研究查询的快速文本浏览器，以及用于交互的可视化浏览器。无法在浏览器中运行代码、安装扩展或访问本地文件系统。容易受到提示词注入攻击。面向 Plus/Pro/Business 订阅用户开放。
• ChatGPT Atlas（OpenAI，2025 年 10 月）：完整的 Chromium 浏览器，集成了作为侧边栏和 Agent 的 ChatGPT。Agent 模式使用与 ChatGPT Agent 相同的沙盒云 VM；核心限制也完全相同。
• Claude Computer Use（Anthropic API，自 2024 年 10 月起处于测试版）：面向任何桌面应用（不只是浏览器）的屏幕截图和鼠标／键盘 API。仅依赖视觉，不支持 DOM 访问。开发者必须提供并管理整个计算环境（通常是包含 Xvfb + Firefox 的 Docker 容器）。不是可直接使用的二进制程序。要在生产环境中运行，需要大量基础设施。
• Claude in Chrome（Anthropic Chrome 扩展，2025 年 11 月起处于测试版）：让 Claude 使用真实的 Cookie 和登录信息，在你现有的 Chrome 会话中操作。面向 Max 计划订阅用户开放。不是开放 API，不支持程序化控制。适合个人交互式任务，不适合批量自动化。
• Gemini / Deep Research（Google）：通过 Google Search API 调用来获取浏览内容，而非使用实时浏览器会话。Deep Research 可综合多次搜索的结果，但无法与页面交互（点击、填写表单、动态导航）。Project Mariner（实验性电脑操作功能）是一个独立且功能有限的研究预览版。
• Copilot / Edge（Microsoft）：Edge 的 Copilot Mode 使用 Bing 检索，并具备一定的页面导航能力。实际测试表明，延迟较高（多页面比较任务耗时超过 6 分钟），且经常会中断并请求用户确认。它不是面向开发者的 API。

快速入门

安装

Linux / macOS（x64 / ARM64）：

curl -fsSL https://raw.githubusercontent.com/Mingye-Lu/AgenticCrawler/main/install.sh | bash

Windows（x64，PowerShell）：

irm https://raw.githubusercontent.com/Mingye-Lu/AgenticCrawler/main/install.ps1 | iex

此操作会下载最新的二进制程序、验证其 SHA256 校验和，并配置 CloakBrowser，以支持隐匿式浏览器自动化。浏览器功能需要 Node.js 20+。

acrawl 会在启动时检查更新，并在有新版本可用时显示通知。

git clone https://github.com/Mingye-Lu/AgenticCrawler.git
cd AgenticCrawler
cargo build --release

# Install CloakBrowser (required for browser automation — binary auto-downloads on first use)
npm install

acrawl Bridge 扩展可以让 acrawl 控制你的真实浏览器（包括你的会话、Cookie 和现有扩展），而不是无头 CloakBrowser 实例。

1. 从 Chrome 网上应用店安装 acrawl Bridge，然后点击 添加至 Chrome。Edge、Brave、Arc、Vivaldi 和 Opera 也可使用同一页面安装。
2. 在 acrawl REPL 中运行 /extension 以启动桥接服务。扩展会在几秒内自动连接，其徽章会变成绿色。

如需在不使用应用商店的情况下安装（例如运行尚未发布的构建版本），请参阅 extension/README.md。其中包含完整的设置说明。

Agent 技能（可选）

如果你通过编码 Agent（使用 acrawl mcp）驱动 acrawl，请安装 acrawl-mcp 技能，让 Agent 知道何时使用直接工具、脚本或 run_goal，以及如何使用网络、控制台和 Cookie 工具进行调试：

npx skills add Mingye-Lu/AgenticCrawler

此操作使用社区 skills CLI。它会检测已安装的 Agent（Claude Code、Cursor、Codex、Gemini CLI、OpenCode 等），并将技能复制到各自的技能目录中。添加 -g 可进行全局（用户级）安装，添加 -a claude-code 可指定单个 Agent。

想跳过 Node？acrawl mcp install --client claude-code --skill 会配置 MCP 服务并一步安装相同的技能（参见快速安装）。

配置

# Set up your LLM provider (interactive prompt)
./target/release/acrawl auth anthropic   # or: openai, other

凭据存储在 ~/.acrawl/credentials.json 中。使用 ACRAWL_CONFIG_HOME 可覆盖配置目录。

运行

# Interactive REPL
./target/release/acrawl

# One-shot mode
./target/release/acrawl prompt "scrape all book titles and prices from books.toscrape.com"

# Resume a saved session
./target/release/acrawl --resume session.json /status /compact

示例

抓取产品目录：

acrawl > scrape all book titles, prices, and ratings from books.toscrape.com

Agent 会访问网站、读取页面、提取数据、遍历全部 50 页，并返回结构化 JSON。

填写并提交表单：

acrawl > go to example.com/contact, fill in name "Jane Doe", email "[email protected]",
         message "Hello", and submit the form

Agent 会定位表单字段、填写内容、点击提交，并确认结果。

监控价格：

acrawl > check the current price of "Rust in Action" on books.toscrape.com

单页提取——Agent 会获取、读取并返回价格，无需进行不必要的页面导航。

提取由 JS 渲染的页面内容：

acrawl > get all repository names and star counts from github.com/trending

静态 HTTP 在此处无法使用。acrawl 会检测 React/Next.js 标记，并自动升级到无头浏览器来渲染 JavaScript。

并行抓取多个页面：

acrawl > scrape the title, author, and price of every book across all 50 pages on books.toscrape.com.
         Fork a sub-agent for each page to speed this up.

Agent 最多会启动 5 个并发子 Agent，每个 Agent 使用独立的浏览器标签页并行抓取页面。所有子 Agent 完成后，系统会合并结果。

功能

43 种工具

导航

内容格式

navigate 工具的 format 参数控制页面的返回方式：

fit_markdown 分两轮处理：

1. 硬性移除：其 class 或 id 属性包含以下任一字符串的元素会立即被移除：nav、footer、header、sidebar、ads、comment、promo、advert、social、share。

2. 基于评分的裁剪：对剩余元素评分；分数低于 0.48 的元素会被移除。评分规则如下：

   0.4 × text_density
   + 0.2 × (1 − link_density)
   + 0.2 × tag_weight
   + 0.1 × class_id_score
   + 0.1 × ln(text_length + 1)
   

   标签权重：article = 1.5 · h1 = 1.2 · h2 = 1.1 · h3/p/section = 1.0 · h4 = 0.9 · h5/table = 0.8 · h6 = 0.7 · span = 0.3 · div/li/ul/ol = 0.5。

以下情况请使用 markdown 而非 fit_markdown： 页面在名为 sidebar、nav 或类似名称的元素中包含重要内容，例如存储在侧边栏 div 中的元数据面板、相关文章链接或作者信息。

如果 fit_markdown 裁剪掉了所有内容（结果为空），工具会自动回退到纯文本。

交互

内容提取

开发者工具与观察

Agent 控制

脚本管理

在没有 Agent 的情况下运行已保存的脚本

已保存的脚本需要浏览器，但不需要大模型，因此 acrawl run 可以从 shell、cron 任务或 CI 步骤中重放脚本，无需提供商凭据：

acrawl run mideast_headlines                                   # saved name → JSON array on stdout
acrawl run ./scripts/news.json --format jsonl --flatten -o headlines.jsonl
acrawl run mideast_headlines --format result                   # full result: status, error, yielded data

退出代码：0 表示已完成，1 表示脚本失败或浏览器无法启动，2 表示脚本未知或无效（在浏览器启动前检查），130 表示通过 Ctrl+C 中断。即使退出代码为 1 或 130，仍会写入部分数据。浏览器后端遵循 browser_backend 设置，因此扩展模式会在你已登录的浏览器中重放脚本。

page_state 参考

交互工具（click、click_at、fill_form、hover、press_key、go_back、scroll、switch_tab、select_option、set_device、refresh）都会返回 page_state 对象。它有两种形式：

完整 page_state，在某个 URL 上首次交互后返回，或在更改过多、无法生成差异时返回：

url: https://example.com/page
title: Page Title
page_map: |
  - main "" [ref=e1]:
    - navigation "Primary" [ref=e2]:
      - link "Docs" [ref=e3]:
        /url: https://example.com/docs
    - heading "Platform" [level=1] [ref=e4]:
    - button "Get Started" [ref=e5]:
    - iframe "Demo" [ref=e6]:
      - button "Play" [ref=e7]:

差异 page_state，在同一 URL 上后续交互时返回，仅显示发生变化的内容：

url: https://example.com/page
title: Page Title
changed: true
changes: |
  + [ref=e5] added:
    - dialog "Confirm" [ref=e5]:
      - button "OK" [ref=e6]:
      - button "Cancel" [ref=e7]:
  - [ref=e3] removed:
    - button "Old Button" [ref=e3]:
  ~ button "Submit" [ref=e2]: [] → [disabled]

如果没有变化，则返回 { "url": "...", "title": "...", "changed": false }。桥接失败时，返回 { "url": "unknown", "title": "unknown", "page_map": null }。操作后的 page_state 会返回仅显示变化内容的 YAML 树差异。如果更改较多，则返回完整的 YAML 快照。

子 Agent 并行处理

Agent 可以派生子 Agent，并发爬取多个页面。每个子 Agent 都有自己的浏览器标签页、步骤预算和独立状态。

URL 声明

派生子 Agent 前，其范围会登记到共享声明注册表中。这可以防止两个同级 Agent 同时爬取同一个 URL。

规则：

• 先声明者优先，如果第二个 Agent 尝试声明已被同级 Agent 声明的 URL，派生会立即失败，并显示一条冲突消息，指出所有者 Agent。父 LLM 会看到此冲突，并可调整范围。
• 三种范围类型： SinglePage（精确 URL）、UrlList（全有或全无的批次）、UrlPattern（正则表达式，会检查是否与所有现有声明重叠）。
• RAII 生命周期，声明在子 Agent 的整个生命周期内有效。子 Agent 完成、被取消或其父级中止设置时，声明会自动释放，URL 随即重新可用。
• 跨类型检查，精确 URL 若匹配任何已声明的正则表达式，就会产生冲突；新正则表达式若能匹配任何已声明的精确 URL，也会产生冲突。
• 列表内去重，如果同一个 URL 在 UrlList 中出现两次，会静默去重（LLM 有时会生成重复项）。

声明是自动的，在子 Agent 启动前由 fork 内部完成，而不是在 navigate 内完成。Agent 不需要显式调用。

智能抓取路由

每次 navigate 调用都会经过两层抓取路由器：

1. 优先使用 HTTP — 基于 reqwest 的快速抓取（超时 30s，最多跟随 10 次重定向）。
2. 自动升级 — 检测到以下任一情况时，请求会透明地在无头浏览器中重放：
   • HTTP 403、429 或 503 响应
   • JS 框架标记：__next_data__、__nuxt、__vue、ng-app、_react、data-reactroot
   • 身份验证重定向：URL 包含 /login、/signin、/auth、/oauth、accounts.google.com
   • 响应正文较短（< 500 个字符）且包含 <noscript> 标签
   • 检测到空 SPA 外壳（多信号评分）：没有嵌入数据的框架资源路径（/_next/static/、/_nuxt/、ng-version=）、空挂载点 div、noscript 中的“启用 JavaScript”消息、打包工具哈希模式，以及结构信号（可见文本稀疏且没有语义元素）。含有嵌入式数据块（__NEXT_DATA__、window.__NUXT__、data-reactroot）的页面会被明确排除，因为其内容已由服务器渲染。

设置 --no-headless / --headed 时，所有抓取都会直接通过浏览器进行。

25 个大模型提供商

如需使用任何兼容 OpenAI 的端点（Ollama、LMStudio、vLLM、本地代理等）：

acrawl auth other

系统会提示你输入基础 URL 和可选的 API 密钥。示例：

这会在 credentials.json 中创建一条包含 auth_method: "api_key" 和你的 base_url 的记录。如果你的服务不需要 API 密钥，请将其留空。

模型采用 provider/model-id 格式：anthropic/claude-sonnet-4-6、openai/gpt-4o、amazon-bedrock/anthropic.claude-sonnet-4-6-20250514-v1:0 等。

使用非标准身份验证的提供商

GitHub Copilot，设备代码流程：

acrawl auth copilot

1. acrawl 会打印一个 URL（https://github.com/login/device）和一个 8 个字符的用户代码，并尝试自动打开浏览器。
2. 在 GitHub 页面输入代码并授权应用。
3. acrawl 会轮询 GitHub，直到授权完成，然后将 GitHub 令牌换取为短期有效的 Copilot API 令牌，并将其存储在 credentials.json 中。

无需 API 密钥，整个流程为交互式。如果授权成功，凭据会自动保存。

GitLab Duo，API 密钥：

acrawl auth gitlab

系统会提示你输入 GitLab Personal Access Token（PAT）。粘贴令牌并按 Enter。无需浏览器重定向。注意：GitLab Duo 不支持工具调用。

Amazon Bedrock，AWS 凭据：

acrawl auth amazon-bedrock

系统会提示你输入 AWS Access Key ID、AWS Secret Access Key 和区域（默认值：us-east-1）。这些信息会直接存储在 credentials.json 中，并用于通过 AWS SigV4 对请求签名。

Azure OpenAI：

acrawl auth azure

系统会提示你输入资源名称（例如 myresource）、部署名称（例如 gpt-4o）和 API 密钥。

交互式 TUI

默认界面是完整的终端 UI，包含：

• Markdown 渲染，支持语法高亮和流式输出
• 斜杠命令浮层 — 输入 / 可查看所有命令，并通过 Tab 补全
• 模型选择器 — /model 会打开可搜索列表，并按提供商类别分组
• 身份验证对话框 — /auth 以交互方式引导完成提供商设置
• 会话标题栏 — 实时显示当前模型、会话 ID、费用和上下文用量
• 调试模式 — /debug 可切换是否在记录中显示原始工具调用输入 / 输出
• 推理力度 — 对于推理模型（o3、o4-mini），按 Ctrl+T 可在高 / 中 / 低之间循环切换

按键绑定：

如果在 stdout 没有 TTY 的情况下运行 acrawl（例如通过管道传输或重定向），程序会报错退出，并提示单次使用时运行 acrawl prompt，会话维护时运行 acrawl --resume。

会话管理

• 自动保存 — 退出时自动保存会话。
• 恢复 — --resume session.json 可重新加载对话。可在命令行末尾追加可安全用于恢复的斜杠命令（/status、/compact、/cost、/config、/version、/export、/help、/clear）。
• 导出 — /export [file] 可生成易于阅读的 Markdown 对话记录。
• 自动压缩：当累计输入令牌超过阈值（默认 200K）时，acrawl 会压缩会话：
  • 原样保留： 最近约 80K 个令牌的消息（至少保留 2 条消息），并保持工具调用配对完整；绝不会让 ToolResult 在没有对应 ToolUse 的情况下单独保留。
  • 作为元数据保留： 消息数量、去重后的工具列表、最近 3 条用户请求（每条 160 个字符）、待办事项（根据包含“todo”“next”“pending”“follow up”“remaining”的消息推断）、最多 10 个关键 URL，以及最近一条非空消息作为“当前工作”。
  • 修剪工具输出： 在计算保留窗口前，将最内层 40K 令牌窗口之前的工具输出截断至 2,000 个字符，并添加 [… output truncated from N chars] 标记。
  • 生成摘要： 默认使用基于模板的方式（不调用大模型）。在 settings.json 中设置 compaction_llm_summarization: true，即可选择使用大模型进行摘要；此时会将移除的消息发送给模型，并将模型输出用作摘要。如果大模型调用失败，则回退到模板。
  • 继续提示词： 压缩后的会话会在开头添加一条系统消息，指示 Agent 直接继续工作，不要复述或提问。
  • 浏览器状态不受影响：压缩只会修改消息历史；当前浏览器标签页、URL、Cookie 和页面状态均保持不变。
• 多个会话 — 使用 /session list 浏览会话，使用 /session switch <id> 切换会话。

工具允许列表

使用 --allowedTools 限制 Agent 可调用的工具（以逗号分隔，可重复指定此标志）：

acrawl prompt "scrape titles" --allowedTools navigate,read_content,screenshot

省略 --allowedTools 可允许使用全部 43 个工具。适用于将爬取任务限制为只读工具，或在不需要子 Agent 并行处理时排除 fork/wait_for_subagents。

MCP 扩展性

acrawl 支持将模型上下文协议服务器用作客户端，以便通过自定义工具扩展 Agent。MCP 工具采用 server_name__tool_name 的命名空间，并可与内置的 43 个工具一同使用。

支持的传输方式：stdio、SSE、HTTP、WebSocket。

MCP 服务（将 acrawl 作为工具提供）

acrawl mcp 会启动内置 MCP 服务，向 Claude Code、Cursor、VS Code、Zed、JetBrains、TRAE、Gemini CLI 或任何兼容 MCP 的客户端等外部 Agent 提供 acrawl 的浏览器自动化功能。

该服务以三种模式提供 40 个工具：

直接浏览器工具（32 个） — 为自行编排操作的客户端提供精细控制： navigate、click、click_at、fill_form、page_map、read_content、screenshot、go_back、get_page_info、scroll、wait、select_option、execute_js、hover、press_key、switch_tab、list_resources、save_file、set_device、refresh、list_network_activity、inspect_request、list_page_logs、inspect_log、list_websocket_activity、inspect_websocket、get_page_performance、inspect_cookies、inspect_storage、measure_coverage、audit_accessibility、intercept_network

脚本工具（7 个） — 无需逐步调用大模型，即可执行确定性的多步自动化： run_script、save_script、list_scripts、read_script、wait_for_scripts、script_status、cancel_script

自主 Agent（1 个） — 委派完整的爬取任务：

• run_goal — 自主执行高层级爬取目标。Agent 使用自己的大模型循环进行规划、导航和数据提取。需要在 ~/.acrawl/credentials.json 中配置模型。

传输方式： 仅支持 stdio（此版本不支持 SSE / HTTP / WebSocket）。

快速安装

acrawl mcp install

交互式安装程序会自动检测 IDE，让你切换要配置的 IDE（按空格键选择，按 Enter 确认），并为每个 IDE 写入正确的配置。支持全局（用户级）和项目级作用域。

支持的客户端：Claude Code、Claude Desktop、Cursor、Windsurf、VS Code (Copilot)、OpenCode、Zed、TRAE、JetBrains IDEs、Gemini CLI、Qwen Code、Codex CLI、Hermes、OpenClaw、Goose、Crush、Aider。

安装程序还会询问是否为支持加载技能的客户端（Claude Code、Cursor、OpenCode、Codex CLI、Gemini CLI）安装捆绑的 acrawl-mcp Agent 技能。非交互模式下，传入 --skill：acrawl mcp install --client claude-code --skill。运行 acrawl mcp uninstall --client claude-code --skill 可将其移除。

手动配置

如果你希望手动配置，请将以下内容添加到 IDE 的 MCP 配置文件中：

{
  "mcpServers": {
    "acrawl": {
      "command": "acrawl",
      "args": ["mcp"]
    }
  }
}

{
  "servers": {
    "acrawl": {
      "command": "acrawl",
      "args": ["mcp"]
    }
  }
}

{
  "mcp": {
    "acrawl": {
      "type": "local",
      "command": ["acrawl", "mcp"]
    }
  }
}

{
  "context_servers": {
    "acrawl": {
      "command": {
        "path": "acrawl",
        "args": ["mcp"],
        "env": {}
      },
      "settings": {}
    }
  }
}

或者直接通过 Claude Code CLI 配置：

claude mcp add acrawl -- acrawl mcp

浏览器工具会在多次调用之间共享持久会话。run_goal 会创建独立的 Agent 和浏览器。

**要求：**38 个浏览器和脚本工具无需任何配置即可使用。run_goal 需要 ~/.acrawl/credentials.json（通过 acrawl auth 获取），供其内部大模型使用。

在 MCP 中使用你的真实浏览器

MCP 服务遵循 browser_backend 设置，因此 MCP 客户端可以驱动你已登录的浏览器，而不是捆绑的无头浏览器：

acrawl config set browser_backend extension   # route MCP browser tools through the extension

桥接服务会在首次调用浏览器工具时启动，并等待扩展程序连接，最长等待时间为 extension_bridge_connect_timeout_secs（默认值为 3）。如果扩展程序始终未连接，工具调用会返回可操作的错误，而不会静默回退到 CloakBrowser。扩展模式旨在复用你的已认证会话，因此改用其他浏览器会造成误导。

Chrome 扩展程序一次只服务一个进程。如果 acrawl REPL 已占用桥接服务，MCP 服务会报告冲突的所有者，而不是争抢端口。运行 acrawl config unset browser_backend 可切回 CloakBrowser。

用法

acrawl [OPTIONS] [COMMAND]

Commands:
  prompt <text>      Run a single goal non-interactively
  mcp                Start MCP server (stdio transport)
  mcp install        Install MCP config into your IDEs interactively
  auth [provider]    Configure provider credentials
  system-prompt      Print the system prompt (for debugging)

Options:
  --model MODEL            Model in provider/id format (e.g. anthropic/claude-sonnet-4-6)
  --output-format FORMAT   text | json
  --resume FILE            Resume a saved session (with optional /commands)
  --compact                Compact history on resume
  --headless[=BOOL]        Force browser headless on/off
  --no-headless, --headed  Launch browser in visible mode
  --allowedTools TOOLS     Restrict available tools (comma-separated, repeatable)
  -p TEXT                  Shorthand for prompt mode
  -V, --version            Print version

斜杠命令

非交互式／Agent 使用

配置一次

acrawl auth anthropic --api-key sk-ant-... acrawl auth openai --api-key sk-... acrawl auth amazon-bedrock --access-key AKIA... --secret-key ... --region us-east-1 acrawl auth other --base-url http://localhost:11434/v1 # Ollama，无需密钥 acrawl config set model anthropic/claude-sonnet-4-6

验证设置

acrawl auth status --check anthropic # 已配置时退出码为 0，未配置时为 3 acrawl auth status --json # 完整凭据表（机密信息已遮蔽）

运行

acrawl prompt "scrape all titles from example.com" --output-format json

设置

acrawl config set headless false acrawl config set optimization.html_diff_mode true acrawl config get model --effective

安装 MCP

acrawl mcp install --client opencode --scope user acrawl mcp install --all --yes acrawl mcp install --client claude-code --skill # 同时安装 Agent 技能

配置

所有配置都存放在 ~/.acrawl/ 中（可通过 ACRAWL_CONFIG_HOME 覆盖）。

credentials.json

通过 acrawl auth 管理。按提供商存储：

Azure 还需要 resource_name 和 deployment_name。Bedrock 需要 aws_access_key_id、aws_secret_access_key 和 region。Vertex 需要 gcp_project_id 和 gcp_region。

settings.json

首次运行时会使用默认值创建此文件。

所有字段均为可选；省略字段时将使用默认值。optimization 块接受一个嵌套对象，其中包含以下字段（默认值均为 false／0／null，可以全部省略）：

环境变量

如果没有 credentials.json 条目，则会将特定于提供商的环境变量（见上文提供商表）作为后备值读取。

性能优化

acrawl 提供 14 项源自供应商的优化（来源包括 browser-use、Stagehand、crawl4ai、Skyvern、Spider、nanobrowser 和 ZeroClaw）。所有优化默认均为禁用状态，可通过 settings.json 按需启用。

以下是启用成本优化配置的 settings.json 示例：

{
  "optimization": {
    "html_diff_mode": true,
    "action_caching": true,
    "page_fingerprinting": true,
    "loop_detection": true,
    "self_healing": true,
    "budget_max_session_cost_usd": 0.50,
    "budget_enforcement": "warn"
  }
}

已知限制

acrawl 在大多数公开网页内容上运行良好，但有些情况超出了 Agent 能够可靠处理的范围：

工作原理

flowchart LR
    Goal([Goal\nnatural language]) --> Plan
    Plan --> Navigate --> Observe --> Act --> Extract
    Extract -->|repeat until done| Plan
    Extract --> Output([Output\nJSON / CSV])

1. Agent 接收目标，并通过 7 部分系统提示词制定多步骤计划，涵盖身份、操作流程、数据完整性、限制、错误恢复、完成协议和并行探索指南。
2. 每轮中，Agent 都会根据其对页面的观察，从 43 个工具中选择工具。
3. navigate 会调用 FetchRouter。FetchRouter 会先尝试 HTTP；当检测到 JavaScript、身份验证重定向或框架标记时，会自动升级为无头 Chromium 浏览器。
4. 浏览器由嵌入式 Node.js 子进程（PlaywrightBridge）驱动，通过 stdio 传输以换行符分隔的 JSON——使用 CloakBrowser 进行隐身浏览，而非标准 Playwright。或者，acrawl 也可以通过 Chrome 扩展（/extension 命令），经由本地 WebSocket 桥接使用 CDP 驱动用户的真实浏览器。
5. 对于多页面任务，Agent 可以将子 Agent fork 到不同的浏览器标签页中，每个子 Agent 都有独立状态和步骤预算。wait_for_subagents 会收集结果；cancel_subagent 会中止正在运行的子 Agent；subagent_status 会轮询状态而不会阻塞。
6. 当上下文变得很大时，自动压缩会对较早的消息进行摘要，同时保留最近的对话轮次、工具使用情况和待处理工作项。
7. 当目标达成且所有子 Agent 均已完成，或达到步骤限制时，Agent 会停止。

架构

crates/
  core/         Shared types, traits, error hierarchy (acrawl-core)
  api/          25 provider clients (Anthropic, OpenAI, Gemini, DeepSeek, Bedrock, Azure, ...), SSE streaming
  browser/      PlaywrightBridge, ExtensionBridge, FetchRouter, BrowserContext, WsBridgeServer
  agent/        43 tools, agent loop, sub-agent fork/join, CrawlState
  runtime/      ConversationRuntime, config, sessions, MCP client stack, OAuth PKCE
  render/       Markdown rendering, tool output formatting, OutputSink
  mcp-server/   Built-in MCP server (JSON-RPC over stdio), IDE installer
  tui/          Ratatui terminal UI (acrawl-tui)
  ui/           Shared application layer (LiveCli, session management, tool executor, auth)
  cli/          Thin binary entry point (main.rs, self_update.rs, uninstall.rs)
  commands/     17 slash commands with resume-safety annotations

11 个 crate、约 40K 行 Rust 代码、1,097 个测试。

开发

cargo build --release                                     # build
cargo test --workspace                                    # run all tests
cargo clippy --workspace --all-targets -- -D warnings     # lint (pedantic)
cargo fmt --check                                         # format check

完整的开发指南请参阅 CONTRIBUTING.md。

更新日志

请参阅 CHANGELOG.md。

安全

有关安全策略以及如何报告漏洞，请参阅 SECURITY.md。

许可证

MIT