DEV Community

Cover image for Firecrawl Local là gì? Cách chạy Firecrawl trên máy của bạn
Sebastian Petrus
Sebastian Petrus

Posted on Originally published at apidog.com

Firecrawl Local là gì? Cách chạy Firecrawl trên máy của bạn

Firecrawl Local là gì? Scrape, crawl và map trên máy bạn

Firecrawl Local là một tệp nhị phân Rust duy nhất giúp scrape, crawl và lập bản đồ các trang web thành markdown sạch ngay trên máy của bạn. Bạn cài đặt nó bằng cargo install firecrawl-local, và nó có thể phục vụ Firecrawl v2 API trên localhost:3002 mà không cần API key, không cần database, không cần queue và không cần container. Tính năng tìm kiếm và một vài tính năng khác vẫn phải gọi đến Firecrawl Cloud, và bạn có thể tắt chế độ này đi.

Dùng thử Apidog ngay hôm nay

Dưới đây là: những gì chạy trên laptop của bạn, những gì gửi lên cloud, cách cài đặt, các route API mà nó phục vụ, giới hạn của nó, và cách để coding agent của bạn kiểm thử API local với Apidog CLI.

Firecrawl Local là gì?

Firecrawl Local là phiên bản mã nguồn mở, chạy trên thiết bị của Firecrawl. Đây là một tệp nhị phân duy nhất dùng để tải các trang web, làm sạch chúng bằng chính đoạn mã làm sạch HTML mà Firecrawl API bản hosted sử dụng, rồi trả về markdown, HTML hoặc links. Nó chạy như một CLI, như một MCP server cho AI agent, hoặc như một bản sao local của Firecrawl v2 API.

Firecrawl công bố nó vào ngày 18 tháng 11 năm 2026 trong một bài đăng ra mắt trên X, và mã nguồn nằm trong thư mục apps/local của kho lưu trữ Firecrawl. Gói được phát hành trên crates.io với tên firecrawl-local, và kho lưu trữ được cấp phép theo AGPL-3.0.

Firecrawl tuyên bố nó nhanh hơn 37 lần so với Firecrawl tự host và dùng ít bộ nhớ hơn 230 lần (11 MB khi rảnh rỗi). README không công bố phương pháp benchmark nào, nên hãy coi đây là tuyên bố của nhà cung cấp.

Nếu bạn đã quen với API bản hosted hoặc Firecrawl CLI, ý tưởng rất đơn giản: cùng các lệnh gọi đó, nhưng được trả lời ngay trên máy của bạn.

Firecrawl Local hoạt động thế nào: một tệp nhị phân, mười lệnh

Mọi tính năng nằm sau một subcommand của firecrawl-local. Đây là danh sách đầy đủ từ README:

Lệnh Chức năng Chạy trên
scrape <urls...> Scrape một hoặc nhiều URL Máy của bạn
crawl <url> Theo các liên kết từ một URL bắt đầu Máy của bạn
map <url> Liệt kê các URL của một trang từ sitemap và trang bắt đầu Máy của bạn
serve Chạy Firecrawl v2 API trên localhost Máy của bạn
mcp Chạy Firecrawl MCP server qua stdio Máy của bạn, một số công cụ trên cloud
init Thêm MCP server vào các công cụ AI trên máy này Máy của bạn
search <query> Tìm kiếm trên web Firecrawl Cloud
find-tools <query> Tìm các nhà cung cấp dữ liệu Alexandria Firecrawl Cloud, cần đăng nhập
data <provider> <capability> Chạy một nhà cung cấp dữ liệu Alexandria Firecrawl Cloud, cần đăng nhập
login Đăng nhập Firecrawl trên trình duyệt Firecrawl Cloud

Ba lệnh là đủ cho hầu hết nhu cầu hằng ngày:

# Print one page as markdown
firecrawl-local scrape https://example.com --markdown

# Crawl up to 50 pages and save one markdown file per page
firecrawl-local crawl https://docs.firecrawl.dev --limit 50 --out ./pages

# List every URL on a site
firecrawl-local map https://firecrawl.dev
Enter fullscreen mode Exit fullscreen mode

Nếu không có --markdown, scrape sẽ in ra JSON của Firecrawl API. --format chấp nhận các giá trị markdown, html, rawHtml và links. Các tệp PDF và tài liệu Office cũng được phân tích cục bộ.

Với các trang dùng JavaScript, nó sẽ điều khiển Chrome hoặc Chromium mà bạn đã có sẵn. Nếu không có, các trang tĩnh vẫn hoạt động bình thường và trang nào cần trình duyệt sẽ trả về cảnh báo. Tham số --browser auto|never|always quyết định khi nào Chrome được dùng.

Cái gì chạy local, cái gì chạy trên Firecrawl Cloud

Scrape, crawl, lập bản đồ và phân tích tài liệu đều chạy trên máy bạn và không gửi gì đến Firecrawl. Ba tính năng phải gọi đến Firecrawl Cloud vì laptop không có index, không có mạng lưới và không có dữ liệu:

  • Tìm kiếm. Máy của bạn không có search index. Tìm kiếm không cần key vẫn hoạt động nhưng bị giới hạn tốc độ.
  • Các trang từ chối máy của bạn. Nếu một trang chặn cả việc fetch thông thường lẫn trình duyệt local, Firecrawl Cloud sẽ tải nó. Không cần tài khoản.
  • Các nhà cung cấp dữ liệu Alexandria. Những dịch vụ này chạy trên Firecrawl Cloud và cần tài khoản miễn phí. Bài giải thích về Firecrawl Alexandria của chúng tôi có nói rõ chúng là gì.

Firecrawl Local split: scrape, crawl, map and PDF and Office parsing run on your machine with optional Chrome, while search, the blocked-page fallback and Alexandria data go to Firecrawl Cloud under FIRECRAWL_CLOUD=auto, switchable to search or off

Biến môi trường FIRECRAWL_CLOUD kiểm soát việc chuyển giao này:

Giá trị Hiệu ứng
auto (mặc định) Tìm kiếm, fallback trang bị chặn và Alexandria đều hoạt động
search Chỉ tìm kiếm mới gửi đến Firecrawl Cloud
off Không gửi gì đến Firecrawl Cloud

Giá trị không được nhận diện sẽ được coi là off. Kết quả tải từ cloud sẽ có "source": "firecrawl-cloud"; nếu cloud cũng thất bại, bạn sẽ nhận được "blocked": true.

Các lệnh gọi cloud mang theo một install ID ngẫu nhiên và tên công cụ đang gọi, đó là cách Firecrawl đếm số lượt cài đặt.

Cách cài đặt Firecrawl Local

Bạn cần Rust và một trình biên dịch C. Sau đó:

  1. Cài đặt build tools. Trên macOS chạy xcode-select --install. Trên Debian hoặc Ubuntu cài build-essential.
  2. Thêm Chrome hoặc Chromium (tùy chọn) nếu bạn cần các trang render bằng JavaScript hoặc chụp màn hình.
  3. Thêm Node.js 22 trở lên (tùy chọn) nếu bạn muốn dùng MCP server, vốn chạy gói npm firecrawl-mcp thông qua npx.
  4. Đăng nhập (tùy chọn) bằng firecrawl-local login để dùng các nhà cung cấp Alexandria.

Cài đặt tệp nhị phân từ crates.io.

cargo install firecrawl-local
firecrawl-local --version
Enter fullscreen mode Exit fullscreen mode

Nếu muốn build mã mới nhất, hãy chạy cargo build --release trong apps/local của một bản clone kho lưu trữ.

Firecrawl Local API: các route v2 trên localhost:3002

Lệnh firecrawl-local serve phục vụ Firecrawl v2 API trên cổng 3002. Không cần API key cho các route local.

firecrawl-local serve

# in another terminal
curl -s http://localhost:3002/v2/scrape \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com","formats":["markdown"]}'
Enter fullscreen mode Exit fullscreen mode

Những route sau chạy trên máy của bạn:

Route Chức năng
POST /v2/scrape Scrape một URL
POST /v2/map Liệt kê các URL của một trang
POST /v2/crawl, GET và DELETE /v2/crawl/{id} Bắt đầu, kiểm tra và hủy một crawl
POST /v2/batch/scrape, GET và DELETE /v2/batch/scrape/{id} Bắt đầu, kiểm tra và hủy một batch scrape
GET /health Kiểm tra trạng thái

Mọi route /v2 khác, chẳng hạn /v2/search, sẽ được chuyển tiếp đến Firecrawl Cloud trừ khi FIRECRAWL_CLOUD quy định khác. Các route v0 và v1 không được phục vụ.

Mã hiện có có thể chuyển sang bằng cách thay đổi một thiết lập: trỏ API URL của bất kỳ Firecrawl SDK nào về http://localhost:3002. Scraper hay pipeline RAG của bạn giữ nguyên mã, và bạn không còn tốn cloud credit trong lúc lặp thử. Để có cái nhìn tổng quát hơn về các pipeline scraping, hãy xem hướng dẫn scraping web với Firecrawl của chúng tôi.

Firecrawl Local như một MCP server cho AI agent

Lệnh firecrawl-local init đăng ký Firecrawl Local như một Model Context Protocol server trong mọi công cụ AI mà nó tìm thấy. Nó hỗ trợ Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI và Codex, sao lưu từng tệp cấu hình trước, và có tùy chọn --dry-run để xem trước thay đổi hoặc --agent cursor để chỉ thiết lập một công cụ.

Agent của bạn sẽ nhận được các công cụ Firecrawl MCP tiêu chuẩn: scrape, crawl, map và batch scrape chạy local, phần còn lại gọi đến Firecrawl Cloud.

Nếu agent của bạn duyệt các trang web mà bạn không tin tưởng, hãy đăng ký nó bằng firecrawl-local mcp --public-only. Nếu không, một trang có chứa hướng dẫn ẩn có thể điều khiển agent mở một URL nội bộ trong mạng của bạn.

Giới hạn của Firecrawl Local

Firecrawl Local không phải là Firecrawl server đầy đủ. README liệt kê những gì còn thiếu:

  • Không có định dạng json hay summary ở local. Scrape local sẽ bỏ qua chúng kèm cảnh báo, vì chúng cần một model.
  • Không có actions trên trình duyệt. Các bước click, cuộn và gõ phím sẽ bị bỏ qua.
  • Chụp màn hình cần Chrome.
  • Các job nằm trong bộ nhớ. Crawl và batch job sẽ hết hạn một giờ sau khi bắt đầu và bị mất khi serve dừng.
  • Không có route API v0 hoặc v1.

Đối với queue, worker và mọi định dạng, server đầy đủ trong apps/api vẫn tồn tại, được trình bày trong hướng dẫn tự host của Firecrawl.

Những thiết lập bảo mật mặc định bạn nên biết

Các thiết lập mặc định khác nhau tùy theo lệnh, vì serve nhận request từ các chương trình khác:

  • scrape, crawl, map và mcp chạy cho người ngồi trước bàn phím, nên chúng có thể truy cập localhost và mạng riêng của bạn. scrape, crawl và mcp chấp nhận --public-only để từ chối các địa chỉ đó.
  • serve chỉ bind vào 127.0.0.1 và từ chối các đích localhost và private trừ khi bạn truyền --allow-private. Bind một địa chỉ khác bằng --host yêu cầu --token.
  • Các địa chỉ link-local và cloud metadata luôn bị chặn, kể cả sau khi redirect và phân giải DNS.

Chrome chạy headless và được sandbox với một profile tạm thời. Khi crawl, Firecrawl Local đọc robots.txt theo Robots Exclusion Protocol, trong đó chủ trang có thể gọi nó bằng tên FirecrawlLocal.

Firecrawl Local phù hợp với ai

  • Các nhà phát triển xây dựng scraper hoặc pipeline RAG muốn lặp thử miễn phí, nhanh chóng trước khi trả tiền cho khối lượng cloud.
  • Người dùng coding agent muốn đọc web bên trong Claude Code, Cursor hoặc Codex mà không phải gửi mọi trang qua một bên thứ ba.
  • Các nhóm có quy định về dữ liệu cần nội dung được tải về vẫn ở trên máy, dùng FIRECRAWL_CLOUD=off.

Nó kém phù hợp hơn nếu bạn phụ thuộc vào trích xuất json, browser action hay các job crawl tồn tại lâu dài. Nếu bạn chỉ cần tìm kiếm cho agent, hãy xem bài tổng hợp của chúng tôi về tìm kiếm web mã nguồn mở cho Claude.

Để coding agent của bạn kiểm thử API local với Apidog CLI

Khi serve đang chạy, bạn có một HTTP API thực sự trên localhost:3002. Trước khi nối một pipeline vào đó, hãy kiểm tra xem các route có trả lời đúng như mã của bạn mong đợi không. Hãy đưa cho coding agent của bạn Apidog CLI và một prompt duy nhất thay vì click qua từng request.

Thiết lập một lần:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Enter fullscreen mode Exit fullscreen mode

Sau đó yêu cầu agent của bạn:

Start firecrawl-local serve in the background. Write an OpenAPI 3 file for its
local routes (POST /v2/scrape, POST /v2/map, GET /health) and import it into
Apidog project <id>. Create an environment pointing at http://localhost:3002,
add test cases that assert /health returns 200 and /v2/scrape returns
success: true with non-empty data.markdown for https://example.com, then run
them and summarize any failures.
Enter fullscreen mode Exit fullscreen mode

Coding agent workflow: the agent starts firecrawl-local serve on localhost:3002, Apidog CLI imports the spec, creates test cases and runs them against POST /v2/scrape, POST /v2/map and GET /health, and writes a cli, json or junit report

Agent sẽ đọc schema, kiểm tra payload của nó và chạy các lệnh như sau:

firecrawl-local serve &
apidog import --project <id> --format openapi --file ./firecrawl-local-v2.yaml
apidog environment create firecrawl-local --project <id> --base-url http://localhost:3002
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file ./case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json
Enter fullscreen mode Exit fullscreen mode

Apidog CLI gửi request từ máy của bạn, nên localhost:3002 có thể truy cập được. Thay -r cli,json bằng -r junit và cùng lượt chạy đó sẽ đi vào CI; hướng dẫn CI/CD với Apidog CLI của chúng tôi có chỉ cách thiết lập, và Apidog CLI trong Claude Code đi qua phía agent. Gói Free của Apidog hỗ trợ các nhóm tối đa 4 người dùng.

Câu hỏi thường gặp

Firecrawl Local có miễn phí không? Tệp nhị phân là mã nguồn mở theo AGPL-3.0, và việc scrape, crawl và lập bản đồ ở local không cần API key. Tìm kiếm, fallback trang bị chặn và Alexandria đều gọi đến Firecrawl Cloud, và Alexandria cần tài khoản miễn phí.

Tôi có thể dùng mã Firecrawl SDK hiện tại với Firecrawl Local không? Có, đối với các route local. Đặt API URL của SDK thành http://localhost:3002. Scrape, map, crawl và batch scrape chạy local; các route v0 và v1 không được phục vụ.

Làm sao để Firecrawl Local ngừng gọi cloud? Đặt FIRECRAWL_CLOUD=off. Tìm kiếm và fallback trang bị chặn sẽ ngừng hoạt động, và không có gì rời khỏi máy bạn ngoại trừ một lệnh login được thực hiện rõ ràng.

Firecrawl Local khác gì so với Firecrawl tự host? Firecrawl tự host là server đầy đủ trong apps/api, có queue, worker và mọi định dạng. Firecrawl Local là một tệp nhị phân duy nhất nhẹ hơn, bỏ đi các định dạng json và summary, browser action và các job tồn tại lâu dài.

Top comments (0)