# Crawl4AI

Canonical: https://cqbase.net/zh/entry/crawl4ai
Chinese: https://cqbase.net/zh/entry/crawl4ai
English: https://cqbase.net/en/entry/crawl4ai

> 面向 AI 代理的开源网页抓取与提取工具，Apache-2.0，可以自托管。

unclecode/crawl4ai 用 Apache-2.0 发布，是给 AI 代理用的网页抓取和提取工具。仓库说明你可以自托管这套爬虫，也提到有托管云服务和免费额度；本页只介绍开源仓库，不以云套餐为准。

先在你有权访问的站点上跑通一次提取，再接到代理工作流里。看清输出里哪些是原文摘录，不要整页转载。密钥和配额只放在环境变量里。

推荐来源：

- [@0x_rody](https://x.com/0x_rody/status/2121328656094244982) 在 2026 年 11 月 14 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：26 次喜欢，0 次转发）。

## 解决什么问题

[unclecode/crawl4ai](https://github.com/unclecode/crawl4ai) 是给 AI 代理和数据管道用的开源网页抓取与提取库，Apache-2.0 许可。它把页面整理成适合模型阅读的 Markdown，也可以按 CSS、XPath 或大模型策略抽出结构化 JSON。本站这条条目说的是开源仓库和自托管路径，不以托管云的套餐为准。

同一仓库的 README 也介绍了 Crawl4AI Cloud（站点 [crawl4ai.com](https://crawl4ai.com/)）。云服务和开源库共用同一套爬取引擎，但部署、计费和接口并不相同。本文会提到云，方便对照，操作步骤以本地 Python 库和官方 Docker 示例为主。

## 适合谁

适合需要自己跑浏览器、把公开网页变成 RAG 或代理上下文的人。你可以用 Python 库在本机进程里爬，用 `crwl` 命令行试效果，或按 README 用 Docker 起一个带令牌的本地服务。如果你不想维护浏览器和代理，再考虑官方云接口。

请先在你有权访问的站点上跑通一次提取，再接到工作流里。输出里常常含有原文摘录，只能当作资料，不要整页转载成自己的文章。API 密钥和自托管令牌只放在环境变量里。

## 怎么装

核验日期为 2026-11-16（Asia/Shanghai）。命令以仓库 [README](https://github.com/unclecode/crawl4ai/blob/main/README.md) 为准。PyPI 上的 [crawl4ai](https://pypi.org/project/crawl4ai/) 在当天显示稳定版为 v0.9.5（发布说明日期 2026-10-14），要求 Python 3.10 或更新；`pyproject.toml` 写的是 `requires-python = ">=3.10"`，分类器列到 3.13。

先安装库并做一次浏览器初始化：

```bash
pip install -U crawl4ai
crawl4ai-setup
crawl4ai-doctor
```

`crawl4ai-setup` 会安装浏览器依赖，一般做一次即可。如果这一步失败，README 给出的手工补救是：

```bash
python -m playwright install --with-deps chromium
```

预发布版本可用 `pip install crawl4ai --pre`。只想先看一页 Markdown 时，也可用官方 CLI：

```bash
crwl https://docs.crawl4ai.com -o markdown
```

**Docker 自托管**

README 要求先设置令牌。没有令牌时，服务只在容器内部响应。官方示例如下，端口为 `11235`：

```bash
export CRAWL4AI_API_TOKEN="$(openssl rand -hex 32)"
docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g \
  -e CRAWL4AI_API_TOKEN="$CRAWL4AI_API_TOKEN" \
  unclecode/crawl4ai:latest
```

探测接口时要带上 `Authorization: Bearer`。仪表盘在 `http://localhost:11235/dashboard`。更完整的配置见 [Self-hosting guide](https://docs.crawl4ai.com/core/self-hosting/)。

需要对照的是：同一站点的 [Installation](https://docs.crawl4ai.com/core/installation/) 页在当天仍把 Docker 写成 experimental，并出现「2023 Edition」、以及计划在 2025 年第一季度重做镜像等旧表述。这与当前 README 里带令牌的 `unclecode/crawl4ai:latest` 示例并不一致。本文没有自行统一，安装以 README 为准，并请同时打开那篇 Installation 页核对你用的版本。

## 一个实际例子

下面在本机库里抓取官方文档首页，确认安装是否成功。请只对你有权访问的公开页面使用。本次没有实跑，因此不编造返回的 Markdown。

1. 确认 Python 为 3.10 或更新，并已执行上一节的 `pip install`、`crawl4ai-setup`。
2. 保存如下脚本，例如 `try_crawl4ai.py`：

```python
import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(url="https://docs.crawl4ai.com")
        markdown = result.markdown or ""
        print("ok" if markdown else "empty")
        print(len(markdown))

asyncio.run(main())
```

3. 运行 `python try_crawl4ai.py`。预期效果：进程能拉起浏览器并返回非空 Markdown，你应自己打开原页核对标题和段落，而不是把输出再发表出去。
4. 若脚本报浏览器缺失，先重跑 `crawl4ai-setup` 或上一节的 Playwright 命令，再用 `crawl4ai-doctor` 查看环境。

## 常见坑

- 把这条条目当成云套餐说明。条目和本文都以开源仓库为准；云额度、每分钟限速和从 10 美元起的付费方案以 [crawl4ai.com](https://crawl4ai.com/) 当天说明为准，可能调整。
- 只执行了 `pip install`，没有跑 `crawl4ai-setup`。没有浏览器时，第一次 `arun` 通常会失败。
- 忽略文档站 Installation 页与 README 对 Docker 的不同表述。若你按旧文档去拉 `unclecode/crawl4ai:basic` 或把 Docker 一律视为实验功能，可能和当前 README 不一致。
- 把密钥写进脚本或对话。云密钥用 `CRAWL4AI_KEY`，自托管令牌用 `CRAWL4AI_API_TOKEN`，都只应出现在环境变量或请求头里。
- 未阅读 README 的 License & Attribution。项目在 Apache-2.0 之外，还要求使用时加入指定徽章或文字致谢，细节以仓库说明为准。
- 抓取你无权访问、或 robots 与站点条款不允许自动采集的页面。提取结果里的原文不能当成你可以自由发表的内容。

## FAQ

### 开源库和 Crawl4AI Cloud 有什么区别？

开源库在你的 Python 进程或自托管 Docker 里跑浏览器，许可是 Apache-2.0，基础设施费用自负。Cloud 由官方托管浏览器和代理，用 `https://api.crawl4ai.com` 和 `CRAWL4AI_KEY`。README 在核验当天写明：免费额度为每月 1,000 积分、付费方案从 10 美元起；搜索类接口（`/search`、`/serp`、`/answer`）是云侧能力。价格以官网为准。

### 必须用 Docker 吗？

不必。日常验证用 `pip install -U crawl4ai` 和 `AsyncWebCrawler` 即可。Docker 适合你想把爬虫做成带令牌的本地 HTTP 服务，并给代理通过 MCP 或 REST 调用的场景。

### 官方文档为什么有的地方还说 Docker 是实验性的？

[Installation](https://docs.crawl4ai.com/core/installation/) 页在 2026-11-16 仍保留 experimental 和 2025 年规划等旧表述；仓库 README 则给出了带 `CRAWL4AI_API_TOKEN` 的现行 `docker run` 示例，并指向 Self-hosting 指南。两者尚未统一，请以 README 与你检出的版本为准。

### Python 版本最低要求是什么？

以当天 PyPI 与仓库 `pyproject.toml` 为准：需要 Python 3.10 或更新。分类器列到 3.13。若你使用更新的 Python，请先看发行说明是否已经声明支持。

### 使用时必须致谢吗？

仓库 README 的 License & Attribution 一节写明，使用时应加入指定徽章或文字致谢。许可证本身是 Apache-2.0。具体义务以 [LICENSE](https://github.com/unclecode/crawl4ai/blob/main/LICENSE) 和该节说明为准，本文不作额外法律解释。

## 来源与许可

仓库 [unclecode/crawl4ai](https://github.com/unclecode/crawl4ai) 使用 Apache-2.0 许可。本文依据 2026-11-16 查阅的 README、`pyproject.toml`、[docs.crawl4ai.com](https://docs.crawl4ai.com) 和 PyPI 页面，用自己的话写成，供 CQBase 上下文库使用。核验当天仓库最近一次推送为 2026-11-13 21:32（Asia/Shanghai）。若安装命令、Docker 说明或云价格有变，以官方仓库和站点为准。

## 收录信息

- 作者: unclecode
- 许可证: Apache-2.0
- 来源: https://github.com/unclecode/crawl4ai
- 收录: 2026-11-15
- GitHub 星标: 87378（采集 2026-11-15）

