Firecrawl

1. Firecrawl là gì?

Firecrawl là công cụ lấy nội dung từ trang web và trả về dạng văn bản sạch (Markdown hoặc dữ liệu có cấu trúc), bỏ hết menu, quảng cáo và phần thừa. Bạn đưa một đường link, nó trả lại phần chữ chính của trang. Nó cũng tìm kiếm trên web, quét cả một website, hoặc liệt kê mọi đường link của một trang. Mục đích chính là cấp dữ liệu web cho các trợ lý AI.

Firecrawl có hai dạng. Bản đám mây tại firecrawl.dev: đăng ký là dùng, tính theo "credit" (điểm sử dụng), có gói miễn phí. Bản mã nguồn mở (giấy phép AGPL-3.0): tự chạy trên máy hoặc máy chủ của bạn bằng Docker, không mất phí dịch vụ nhưng thiếu một số tính năng của bản đám mây.

Nói thẳng: Firecrawl là công cụ cho lập trình viên và người làm việc với AI. Tuy vậy, người không rành kỹ thuật vẫn thử được ngay trên web mà không cần cài gì.

Hợp với bạn nếu:

• Bạn muốn chép nội dung bài viết, tài liệu trên web thành văn bản gọn để đưa cho ChatGPT, Claude hay công cụ AI khác.
• Bạn dùng Claude Code, Cursor, Codex và muốn trợ lý tự đọc được web.
• Bạn làm sản phẩm cần dữ liệu web và không muốn tự viết trình thu thập.

Chưa hợp nếu:

• Bạn chỉ cần lưu một hai trang: bấm chép và dán nhanh hơn.
• Bạn muốn một ứng dụng có cửa sổ, nút bấm để cài lên máy. Firecrawl không có bản như vậy.
• Bạn định thu thập dữ liệu cá nhân hoặc nội dung mà trang web cấm. Dự án ghi rõ người dùng tự chịu trách nhiệm tuân thủ chính sách của từng trang.

2. Cần chuẩn bị gì?

Tùy cách dùng, thứ cần chuẩn bị khác nhau:

Cách dùng	Cần gì	Có mất tiền không
Thử trên web (Playground)	Trình duyệt; có thể cần tài khoản Firecrawl	Gói miễn phí
Dòng lệnh (CLI)	Máy tính, Node.js	Miễn phí trong hạn mức; có khóa miễn phí thì hạn mức cao hơn
Gắn vào trợ lý AI	Node.js, một trợ lý như Claude Code, Cursor, Codex, OpenCode	Tính credit theo tài khoản Firecrawl
Tự chạy (self-host)	Git, Docker, máy đủ khỏe	Không phí dịch vụ, tự lo máy

Giải thích các phần mềm:

• Node.js: nền để chạy các chương trình viết bằng JavaScript; đi kèm hai lệnh npm và npx. Tải tại https://nodejs.org/.
• Git: công cụ tải mã nguồn. Tải tại https://git-scm.com/downloads.
• Docker Desktop: chạy phần mềm trong các "hộp" riêng (container). Tải tại https://www.docker.com/.

Khóa API: đăng ký tại https://firecrawl.dev để nhận khóa, có dạng bắt đầu bằng fc-. Theo trang thanh toán (billing) của Firecrawl, gói miễn phí có 1.000 credit mỗi tháng (credit chưa dùng không cộng dồn; hết credit thì yêu cầu bị từ chối cho tới chu kỳ sau). Cách tính: lấy một trang tốn 1 credit; tìm kiếm tốn 2 credit cho mỗi 10 kết quả. Giá các gói trả phí thay đổi theo thời gian, xem tại https://www.firecrawl.dev/pricing.

3. Cài đặt từng bước

Bước 1: Thử ngay trên web (dễ nhất, không cài gì)

1. Mở https://firecrawl.dev và đăng ký tài khoản (miễn phí) nếu trang yêu cầu.
2. Mở https://firecrawl.dev/playground.
3. Dán một đường link bài viết vào ô nhập và chạy.

Thấy gì là đúng: trang trả về nội dung bài viết ở dạng văn bản Markdown (tiêu đề có dấu #, danh sách có dấu -), không còn menu hay quảng cáo.

Nếu chỉ cần thỉnh thoảng lấy nội dung vài trang, bạn có thể dừng ở đây.

Bước 2: Cài công cụ dòng lệnh (CLI)

Cài Node.js trước, rồi chạy:

npm install -g firecrawl-cli

Kiểm tra:

firecrawl --status

Thấy gì là đúng: hiện tên "firecrawl cli" kèm số phiên bản và trạng thái đăng nhập.

Bước 3: Đăng nhập

firecrawl login

Lệnh này mở trình duyệt để bạn đăng nhập, hoặc hỏi khóa API. Nếu đã có khóa, có thể đăng nhập thẳng (thay bằng khóa thật của bạn):

firecrawl login --api-key fc-YOUR-API-KEY

Thấy gì là đúng: chạy lại firecrawl --status thấy dòng báo đã xác thực ("Authenticated") và số credit còn lại.

Lưu ý: Theo tài liệu, một số lệnh như lấy một trang (scrape) và tìm kiếm (search) vẫn chạy được khi chưa đăng nhập, nhưng bị giới hạn số lần mỗi ngày theo địa chỉ mạng của bạn.

Bước 4 (tùy chọn): Gắn Firecrawl vào trợ lý AI

Nếu bạn dùng Claude Code, Cursor, Codex hoặc OpenCode, một lệnh sau sẽ cài "kỹ năng" Firecrawl cho mọi trợ lý tìm thấy trên máy và mở trình duyệt để đăng nhập:

npx -y firecrawl-cli@latest init --all --browser

Sau đó khởi động lại trợ lý. Thấy gì là đúng: bạn bảo trợ lý "dùng Firecrawl đọc trang này giúp tôi" và nó làm được.

Với ứng dụng dùng chuẩn MCP (cách để trợ lý AI gọi công cụ bên ngoài), thêm khối sau vào file cấu hình MCP của ứng dụng, thay khóa bằng khóa của bạn:

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY"
      }
    }
  }
}

Bước 5 (nâng cao): Tự chạy Firecrawl bằng Docker

Chỉ làm khi bạn thật sự cần tự kiểm soát hạ tầng. Tài liệu chính thức khuyên dùng bản đám mây nếu bạn chỉ muốn bắt đầu nhanh. Hướng dẫn tự chạy được kiểm chứng với bản v2.11.162.

Tải mã nguồn và chuyển về đúng bản đó:

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
git checkout v2.11.162

Tạo file tên .env ở thư mục gốc firecrawl với bốn dòng sau. Thay mật khẩu bằng một chuỗi ngẫu nhiên dài ít nhất 32 ký tự:

USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres

Mở Docker Desktop, rồi dựng và khởi động:

docker compose up --build -d
docker compose ps --all

Cảnh báo về các biến tùy chọn chưa đặt là bình thường. Kiểm tra dịch vụ đã lên chưa:

curl --fail --silent --show-error --max-time 5 http://localhost:3002/v0/health/readiness

Thấy gì là đúng: kết quả là {"status":"ok"}. Sau đó trỏ CLI vào bản tự chạy và thử lấy một trang:

firecrawl --api-url http://localhost:3002 scrape https://example.com

Lưu ý: Cấu hình trên tắt xác thực, ai truy cập được cổng 3002 cũng dùng được. Chỉ chạy trong mạng bạn tin cậy, không mở ra Internet.

4. Dùng lần đầu

Sau khi có CLI, thử ba việc sau.

Lấy nội dung chính của một trang và lưu thành file:

firecrawl https://example.com --only-main-content -o output.md

Thấy gì là đúng: trong thư mục hiện tại có file output.md. Mở bằng Notepad sẽ thấy phần chữ của trang.

Tìm kiếm trên web và lấy 5 kết quả:

firecrawl search "firecrawl" --limit 5

Chụp ảnh màn hình một trang:

firecrawl https://example.com --screenshot

Các khả năng chính của Firecrawl:

Tên	Làm gì
Scrape	Biến một đường link thành Markdown, HTML, ảnh chụp hoặc dữ liệu có cấu trúc
Search	Tìm trên web và lấy luôn nội dung các kết quả
Crawl	Quét mọi trang của một website trong một lần yêu cầu
Map	Liệt kê mọi đường link của một website
Interact	Lấy trang rồi thao tác tiếp (bấm, gõ) bằng lời nhắc hoặc mã
Agent	Mô tả dữ liệu cần tìm, để AI tự tìm và gom về

Lưu ý: Crawl có thể tiêu rất nhiều credit vì mỗi trang tính một credit. Luôn đặt giới hạn số trang khi quét cả website.

5. Lỗi thường gặp và cách sửa

Không nhận ra lệnh npm, npx hoặc firecrawl

• Dấu hiệu: "command not found" hoặc "is not recognized".
• Nguyên nhân: chưa cài Node.js, hoặc cửa sổ dòng lệnh mở trước khi cài.
• Cách sửa: cài Node.js, đóng và mở lại cửa sổ dòng lệnh, rồi chạy lại lệnh ở Bước 2.

Bị từ chối với mã 429

• Dấu hiệu: yêu cầu trả về lỗi 429.
• Nguyên nhân: vượt giới hạn số yêu cầu mỗi phút hoặc số việc chạy song song của gói; hoặc đang dùng không có khóa và đã hết hạn mức trong ngày.
• Cách sửa: chờ rồi thử lại chậm hơn. Đăng nhập bằng khóa miễn phí để có hạn mức cao hơn.

Hết credit khi quét website (mã 402)

• Dấu hiệu: lệnh crawl bị từ chối với mã 402.
• Nguyên nhân: số credit còn lại không đủ cho yêu cầu.
• Cách sửa: xem số credit bằng firecrawl --status, giảm giới hạn số trang, hoặc nâng gói.

Trợ lý AI không thấy Firecrawl sau khi cài

• Dấu hiệu: đã chạy lệnh init nhưng trợ lý nói không có công cụ.
• Nguyên nhân: trợ lý chưa được khởi động lại.
• Cách sửa: thoát hẳn và mở lại trợ lý. Với MCP, kiểm tra khóa trong khối env đã điền đúng chưa.

Bản tự chạy: container không lên hoặc cổng 3002 không phản hồi

• Dấu hiệu: docker compose ps --all cho thấy dịch vụ đã thoát, hoặc lệnh kiểm tra ở Bước 5 báo lỗi.
• Nguyên nhân: Docker thiếu CPU, bộ nhớ hoặc ổ cứng; file .env sai cú pháp; cổng 3002 đang bị chương trình khác dùng.
• Cách sửa: xem nhật ký bằng lệnh dưới đây. Tăng tài nguyên cho Docker, giữ nguyên POSTGRES_DB=postgres, và tắt chương trình đang chiếm cổng 3002.

docker compose logs --tail=200

Bản tự chạy: không chụp được ảnh màn hình, không dùng được Agent

• Dấu hiệu: các lệnh chạy tốt trên bản đám mây lại không chạy trên bản tự chạy.
• Nguyên nhân: tài liệu ghi rõ bản tự chạy mặc định không có ảnh chụp màn hình, thao tác trang, Agent và Interact.
• Cách sửa: dùng bản đám mây cho các tính năng đó.

6. Gỡ cài đặt / cập nhật

CLI:

• Đăng xuất để xóa thông tin đăng nhập đã lưu:

firecrawl logout

• Gỡ bằng lệnh chuẩn của npm:

npm uninstall -g firecrawl-cli

• Cập nhật: chạy lại lệnh cài ở Bước 2. Nếu dùng qua npx ... firecrawl-cli@latest thì mỗi lần chạy đã lấy bản mới nhất.

Bản tự chạy:

• Dừng và gỡ các container:

docker compose down

• Xóa thư mục firecrawl để gỡ sạch mã nguồn.
• Cập nhật: tài liệu dặn xem file docker-compose.yaml và ghi chú tự chạy của bản mới trước, vì cấu hình có thể đổi giữa các bản. Sau đó git checkout sang thẻ phiên bản mới và dựng lại.

Phiên bản: trang Releases trên GitHub ghi bản gần nhất là v2.11.0 (ngày 19/6/2026); repo vẫn tiếp tục gắn thẻ các bản nhỏ hơn sau đó, và hướng dẫn tự chạy chính thức dùng thẻ v2.11.162.

Tài khoản: nếu không dùng nữa, đăng nhập firecrawl.dev và quản lý khóa API trong trang tài khoản của bạn.

7. Câu hỏi hay gặp

Có mất tiền không? Có gói miễn phí: gói miễn phí có 1.000 credit mỗi tháng, và một số lệnh chạy được cả khi không có khóa với hạn mức thấp theo ngày. Dùng nhiều hơn thì trả tiền theo gói. Bản tự chạy không mất phí dịch vụ nhưng bạn tự lo máy.

Có cần mạng không? Có. Firecrawl lấy dữ liệu từ Internet, kể cả bản tự chạy cũng phải kết nối ra ngoài để tải trang.

Dữ liệu có bị gửi đi đâu không? Với bản đám mây và CLI, đường link và nội dung lấy về đi qua máy chủ của Firecrawl. Với bản tự chạy, việc xử lý diễn ra trên máy bạn, nhưng máy vẫn gửi yêu cầu tới các trang web cần lấy.

Lấy dữ liệu web như vậy có hợp pháp không? Tùy trang và tùy cách dùng. Dự án nêu rõ: người dùng tự chịu trách nhiệm tôn trọng chính sách của các trang web, và mặc định Firecrawl tuân theo file robots.txt (file mà trang web dùng để nói phần nào không cho máy quét).

Máy yếu có chạy được không? Bản đám mây và CLI rất nhẹ vì việc nặng chạy trên máy chủ. Bản tự chạy cần dựng và chạy nhiều dịch vụ cùng lúc; Firecrawl không công bố cấu hình tối thiểu cho trường hợp này.