Crawl4AI crwl CLI 深度解析：命令面、配置体系与 Profile 身份爬取实战

Crawl4AI 通过 crwl 命令（入口定义于 pyproject.toml，映射到 crawl4ai.cli:main）把「爬取网页、抽取结构化数据、管理浏览器身份」整合到一套终端命令中，无需编写 Python 脚本即可完成从一次性抓取到登录态复用的完整工作流。本文以 docs/codebase/cli.md 的命令面文档为骨架，结合 crawl4ai/cli.py 的实现源码，逐一讲解每个子命令的参数、配置层级与底层调用链，帮助你把 Crawl4AI 的 CLI 当作日常爬虫工具与 CI 脚本组件来使用。

一、CLI 架构总览与默认别名机制

从源码结构看，crwl 基于 Click 构建：crawl4ai/cli.py 中定义了顶层 @click.group（命令描述为 "Crawl4AI CLI - Web content extraction and browser profile management tool"），并挂载了 cloud、browser、config、profiles 等命令组。

入口函数 main()（crawl4ai/cli.py）实现了一个关键的“回退到 crawl”逻辑：当第一个参数不是已注册子命令时，会自动在 sys.argv 中插入 crawl，这正是 crwl https://site.com 这种简短写法的来源——默认命令（@cli.command(name="")，crawl4ai/cli.py）持有与 crawl 完全同构的参数集，最终通过 ctx.invoke(crawl_cmd, ...) 转发执行。

完整命令面如下（继承自 docs/codebase/cli.md 的表格，并按源码补全了 start、restart、shrink、cdp 等文档未逐一列出的命令）：

命令	输入 / 标志	作用
profiles	无参数进入交互管理器；子命令 create <name>、list、delete <name> [-f]	管理保存在 ~/.crawl4ai/profiles 下的浏览器身份档案，支持列出、创建、删除、直接选档爬取
browser status	–	显示常驻 builtin 浏览器是否在运行，输出 CDP URL、PID、浏览器类型、用户数据目录、启动时间
browser start	--browser-type/-b (chromium/firefox)、--port/-p (默认 9222)、--headless/--no-headless	启动可被代码以 browser_mode="builtin" 复用的后台浏览器
browser stop	–	终止 builtin 浏览器并删除其状态文件
browser view	--url, -u（可选）	弹出 builtin 浏览器的可见窗口，导航到指定 URL 或 about:blank
browser restart	同 start（缺省继承当前配置）	先停后启，保留原浏览器类型与端口
cdp	--user-data-dir, -d、--port, -P（默认 9222）、--browser-type, -b、--headless、--incognito	启动带 CDP 调试端点的独立浏览器，打印 CDP URL 供 Puppeteer/Playwright 附着，按 q 退出
config list / get <key> / set <key> <value>	见第七节	查看/修改全局设置，持久化到 ~/.crawl4ai/global.yml
examples	–	打印真实可用的 CLI 用法样例（与 crwl --example 相同内容）
shrink <profile> [-l level] [-n]	level: light/medium/aggressive/minimal（默认 aggressive）	缩减 profile 体积，仅保留认证数据
crawl	见下一节的完整标志表	一次性爬取 + 抽取，可组合内联参数或 YAML/JSON 配置文件，支持命名 profile 与深爬
(默认别名)	与 crawl 相同，另加 --example	允许直接 crwl https://site.com；未知子命令统一回退到 crawl

原文档给出的“心智模型”值得保留，它精准概括了各命令组的分工：

profiles = 管理身份（identities）， browser ... = 控制长跑的无头 Chrome（所有爬取可搭便车）， crawl = 真正干活， config = 调整全局默认值， 其余都是语法糖。

二、crawl 子命令：完整参数说明

crawl 是功能密度最高的命令。以下参数表基于 crawl4ai/cli.py 的实际定义整理：

标志	说明
url（位置参数）	待爬取目标，必填
--browser-config, -B	浏览器配置文件路径（YAML/JSON），加载后交给 BrowserConfig.load()
--crawler-config, -C	爬虫运行配置路径，加载后交给 CrawlerRunConfig.load()
--filter-config, -f	内容过滤器配置（bm25 / pruning 两种 type）
--extraction-config, -e	抽取策略配置，type 支持 llm、json-css、json-xpath
--json-extract, -j [desc]	带值时开启 LLM 结构化抽取并注入自定义指令；不带值则使用内置通用指令。该选项优先于 -e
--schema, -s	抽取所用的 JSON Schema 文件路径
--browser, -b	k1=v1,k2=v2 形式的浏览器内联参数
--crawler, -c	同上形式的爬虫运行参数
--output, -o	all（默认）/json/markdown(md)/markdown-fit(md-fit)
--output-file, -O	输出写入文件，缺省打印到 stdout
--bypass-cache, -bc	缓存绕过（flag，默认启用）
--question, -q	对爬取到的 markdown 内容向 LLM 提问并流式输出回答
--verbose, -v	打印 BrowserConfig / CrawlerRunConfig 的完整 dump
--profile, -p	按名字引用已保存的 profile
--deep-crawl	bfs / dfs / best-first，启用深爬（源码固定 max_depth=3）
--max-pages	深爬最大页面数，默认 10
--json-ensure-ascii/--no-json-ensure-ascii	控制 JSON 输出的非 ASCII 转义，缺省取全局配置

2.1 k=v 内联参数的类型解析

-b/-c 参数由回调 parse_key_values（crawl4ai/cli.py）解析，它按逗号切分后对每个值做自动类型推断：

• true/false → 布尔值；
• 纯数字 → int，带单个小数点 → float；
• [a, b] → 列表；{"k": "v"} → 解析为 JSON 对象（解析失败抛出 BadParameter）；
• 其余按字符串处理；
• 无法按 key=value 切分的片段会直接报错 Invalid key=value pair。

这一行为在 tests/cli/test_cli.py 中有回归验证："key1=value1,key2=true" 应解析为 {'key1': 'value1', 'key2': True}，而 "invalid_format" 必须抛出 click.BadParameter。

配置文件加载由 load_config_file（crawl4ai/cli.py）完成：按扩展名区分 YAML 与 JSON，文件不存在或解析失败时报 BadParameter——这也是为什么所有 -B/-C/-e/-s/-f 选项都声明了 type=click.Path(exists=True)。

2.2 参数覆盖顺序与配置构建

从源码执行顺序看，crawl_cmd 的配置组装遵循明确的优先级：

1. -p <profile> 最先处理：通过 BrowserProfiler().get_profile_path(profile) 按名字查路径（查找失败会列出全部可用 profile），命中后向浏览器参数注入 user_data_dir=<profile 路径> 且 use_managed_browser=True（crawl4ai/cli.py）；
2. -B 文件 → BrowserConfig.load(...)，-C 文件 → CrawlerRunConfig.load(...) 作为基线；
3. -b/-c 内联参数通过 browser_cfg.clone(**browser) 覆盖在文件配置之上，即“CLI 覆盖文件”；
4. 缓存：--bypass-cache 默认 default=True，只要传入就会把 cache_mode 设为 CacheMode.BYPASS；
5. 全局配置收尾：VERBOSE 从 ~/.crawl4ai/global.yml 读取并覆盖两个配置对象的 verbose 字段；JSON_ENSURE_ASCII 按「CLI 标志 > 全局配置 > 默认值」的优先级生效。

爬取本身收敛在 run_crawler（crawl4ai/cli.py）：AsyncWebCrawler(config=browser_cfg) 上下文管理器内执行 await crawler.arun(url=url, config=crawler_cfg)，异常统一包装为 click.ClickException。

2.3 抽取：-j、-e/-s 与 -f 三种能力

• -j（LLM 快速抽取）：首次使用会调用 setup_llm_config 交互询问 provider 与 token（格式 company/model，如 ollama/llama3.3、openai/gpt-4），并持久化到全局配置。指令选择逻辑在 crawl4ai/cli.py：无参 -j 使用内置的通用结构化抽取指令（识别列表页抽数组、文章页抽对象），带参 -j "..." 则把用户描述拼进指令模板。底层构造 LLMExtractionStrategy（extraction_type="schema"、force_json_response=True）。若未显式指定 -o，会自动降级为 json 输出。
• -e + -s（策略文件抽取）：type 仅接受 llm / json-css / json-xpath，分别映射到 LLMExtractionStrategy、JsonCssExtractionStrategy、JsonXPathExtractionStrategy；llm 类型强制要求 provider 与 api_token 字段，params 中的键值会展开进策略构造。
• -f（内容过滤）：配置文件 type 为 bm25 时构建 BM25ContentFilter（bm25_threshold 默认 1.0、use_stemming 默认 True）；为 pruning 时构建 PruningContentFilter（threshold 默认 0.48），两者都会重新包装进 DefaultMarkdownGenerator 并挂到 crawler_cfg.markdown_generator。注意源码中一个隐含行为：即使不传 -f，只要 -o markdown-fit/md-fit 就会自动应用 pruning 过滤（阈值 0.48）。

2.4 深爬与输出格式

--deep-crawl 会把 BFSDeepCrawlStrategy / DFSDeepCrawlStrategy / BestFirstCrawlingStrategy 挂到 crawler_cfg.deep_crawl_strategy，三者统一 max_depth=3、max_pages 取 --max-pages（默认 10，crawl4ai/cli.py）。

深爬时 arun 返回结果列表，CLI 的输出分支会逐页拼接：markdown/markdown-fit 输出为每页一个 # <url> 分隔块；all/json 输出为 JSON 数组。多页全量输出的行为在 tests/cli/test_cli.py 的 TestDeepCrawlOutput 中有专门回归（断言三页 URL 与正文都出现在 stdout 或 -O 文件中）。

2.5 -q：基于爬取结果的 LLM 问答

-q "问题" 走独立链路：先完成常规爬取，取 main_result.markdown.raw_markdown 作为上下文，由 stream_llm_response（crawl4ai/cli.py）构造 system 提示（"You are Crawl4ai assistant, answering user question based on the provided context which is crawled from {url}"）后经 LiteLLM 流式输出。注意使用 -q 后命令直接返回，不再走 -o 输出分支。

三、Profile 实战：身份化爬取的完整工作流

Profile 是 CLI 的核心场景——把一个真实登录过的浏览器 user-data-dir 保存为命名档案，让后续爬取自动携带登录态。所有档案统一存放在 ~/.crawl4ai/profiles/<name>。

以下为原文档的命令速查表（可直接复制执行）：

场景	命令	说明
打开交互式 Profile Manager	crwl profiles	TUI 菜单：1 列出、2 创建、3 删除、4 选档爬取、5 退出
创建新 profile	crwl profiles → 选 2 → 输入名字 → 浏览器弹出 → 登录 → 终端按 q	保存至 ~/.crawl4ai/profiles/<name>
列出已存 profile	crwl profiles → 选 1	展示名字、浏览器类型、体积、修改时间
删除 profile	crwl profiles → 选 3 → 选索引 → 确认	删除对应目录
用 profile 爬取（默认别名）	crwl https://site.com/dashboard -p my-profile	保留登录 cookie，底层自动设置 use_managed_browser=true
profile + 详细 JSON 输出	crwl https://site.com -p my-profile -o json -v	其余 crawl 标志同样可用
叠加浏览器微调	crwl https://site.com -p my-profile -b "headless=true,viewport_width=1680"	CLI 覆盖优先于 profile
显式子命令写法	crwl crawl https://site.com -p my-profile	与默认别名完全等价
在 Profile Manager 内选档爬取	crwl profiles → 选 4 → 选 profile → 输入 URL	适合向非命令行用户演示
一次性指定 profile 目录路径（不走名字注册表）	crwl https://site.com -b "user_data_dir=$HOME/.crawl4ai/profiles/my-profile,use_managed_browser=true"	绕过注册表，适合 CI 脚本
以相同身份在 CDP 端口拉起调试浏览器	crwl cdp -d $HOME/.crawl4ai/profiles/my-profile -P 9223	便于 Puppeteer/Playwright 附着调试

源码层面，交互式创建对应 create_profile_interactive（crawl4ai/cli.py），内部调用 BrowserProfiler.create_profile() 弹出可见浏览器，人工登录后在终端按 q 触发压缩保存；“选档爬取”对应 crawl_with_profile_cli（crawl4ai/cli.py），它固定构造 BrowserConfig(headless=False, use_managed_browser=True, user_data_dir=profile_path) 并可选择 all/json/markdown/title 四种输出。交互式菜单与子命令 create/list/delete 的完整实现见 crawl4ai/cli.py。

3.1 shrink：缩减 profile 体积

长期登录的 profile 会积累缓存与历史。crwl shrink <name> [--level light|medium|aggressive|minimal] [--dry-run]（crawl4ai/cli.py）按白名单策略删除非认证数据，各等级的保留清单定义在 crawl4ai/browser_profiler.py 的 KEEP_PATTERNS：

• light：仅删缓存，保留 History、Bookmarks、Web Data 等；
• medium：缓存 + 历史/收藏一并移除；
• aggressive（默认，推荐）：只留 Network、Cookies、Local Storage、IndexedDB、Preferences 与 storage_state.json；
• minimal：只留 Network、Cookies、Local Storage 与 storage_state.json。

所有等级都强制保留 storage_state.json（Playwright 的可移植 cookie 格式），以保证跨机器迁移可用性；--dry-run 只报告将删除的内容。命令会打印移除/保留条目数、释放空间与前后体积。

四、builtin 浏览器管理（browser 子命令）

builtin 浏览器是一个常驻后台的 Chromium 实例，状态记录在本地 JSON 文件中（含 wsEndpoint、pid、started_at），供所有 browser_mode="builtin" 的爬取复用，避免每次冷启动浏览器。

• crwl browser status：调用 BrowserProfiler.get_builtin_browser_status，运行中时以 Rich Panel 展示 CDP URL、PID、浏览器类型、用户数据目录与启动时间；
• crwl browser start --browser-type chromium --port 9222：若已有实例在跑会拒绝并提示用 restart；否则调用 launch_builtin_browser 启动并打印 CDP URL；
• crwl browser stop：调用 kill_builtin_browser 终止进程并清理状态文件；
• crwl browser view --url https://example.com：按平台选择 Chrome 可执行路径（macOS 为 /Applications/Google Chrome.app/...，Linux 为 google-chrome，Windows 为 Program Files 路径），用同一 --remote-debugging-port 弹出可见窗口；
• crwl browser restart：先读当前配置再停后启，未指定的参数继承现状（注意源码中 headless 在继承时按 True 假设，crawl4ai/cli.py）。

与 builtin 不同的还有 crwl cdp（crawl4ai/cli.py）：它启动的是独立调试浏览器而非 builtin 实例，-d 可指定/自动创建 user-data-dir，--incognito 会忽略该目录，浏览器保持运行直到按 q，期间 CDP URL 可直接交给其他自动化工具使用。

五、全局配置：config 子命令与 USER_SETTINGS

config list/get/set 管理的设置项定义在 crawl4ai/config.py 的 USER_SETTINGS 中，共 8 项：

设置键	默认值	类型 / 可选值	说明
DEFAULT_LLM_PROVIDER	openai/gpt-4o	string	默认 LLM provider（company/model 格式）
DEFAULT_LLM_PROVIDER_TOKEN	空	string（secret，列表时掩码为 ********）	默认 provider 的 API token
VERBOSE	false	boolean	全局详细输出
BROWSER_HEADLESS	true	boolean	浏览器默认无头模式
BROWSER_TYPE	chromium	string（chromium/firefox）	默认浏览器类型
CACHE_MODE	bypass	string（bypass/use/refresh）	默认缓存模式
USER_AGENT_MODE	default	string（default/random/mobile）	默认 User-Agent 模式
JSON_ENSURE_ASCII	true	boolean	JSON 输出是否转义非 ASCII 字符

几个实现细节值得注意：

• 持久化位置：get_global_config/save_global_config（crawl4ai/cli.py）读写的是 ~/.crawl4ai/global.yml——这与 docs/codebase/cli.md 中 “stored under ~/.crawl4ai/config.yml” 的描述略有出入，以当前源码实现为准；
• 键名不区分大小写：get/set 都会先把键 upper() 后再匹配（crawl4ai/cli.py），即 crwl config set verbose true 与 VERBOSE 等价；
• 类型校验：boolean 接受 true/yes/1/y 与 false/no/0/n；带 options 约束的字符串项（如 BROWSER_TYPE）传入非法值会报错并列出可选值；
• -q/-j 自动落盘：首次交互配置 LLM 后，provider 与 token 自动写入 global.yml，之后可免交互使用，也可预先 crwl config set DEFAULT_LLM_PROVIDER "anthropic/claude-3-sonnet" 与 crwl config set DEFAULT_LLM_PROVIDER_TOKEN "..." 提前设置。

六、典型配置组合与示例文件

crwl examples（或 crwl --example）打印的样例（crawl4ai/cli.py）本身就是一份可运行的操作手册，摘取其中几类组合：

# 基础：默认设置 / 只要 markdown / JSON + 详细 + 绕过缓存
crwl https://example.com
crwl https://example.com -o markdown
crwl https://example.com -o json -v --bypass-cache

# 配置文件组合（文件参数 + 内联覆盖）
crwl https://example.com -B browser.yml -C crawler.yml
crwl https://example.com -B browser.yml -b "headless=false,viewport_width=1920"

# CSS 抽取
crwl https://example.com -e extract_css.yml -s css_schema.json -o json

# LLM 快速抽取（首次会询问 provider）
crwl https://example.com -j
crwl https://example.com -j "Extract product details including name, price, and features"

# 内联浏览器/爬虫参数
crwl https://example.com -b "headless=true,viewport_width=1280,user_agent_mode=random"
crwl https://example.com -c "css_selector=#main,delay_before_return_html=2,scan_full_page=true"

# 登录态爬取
crwl https://login-required-site.com -p my-authenticated-profile -c "css_selector=.dashboard-content" -o markdown

# 内容过滤
crwl https://example.com -f filter_bm25.yml -o markdown-fit

# 问答
crwl https://example.com -q "What is the main topic discussed?"

样例中给出的配套配置文件内容同样值得存档（摘自 show_examples）：

browser.yml：

headless: true
viewport_width: 1280
user_agent_mode: "random"
verbose: true
ignore_https_errors: true

extract_css.yml 与 css_schema.json：

type: "json-css"
params:
    verbose: true

{
  "name": "ArticleExtractor",
  "baseSelector": ".article",
  "fields": [
    {"name": "title", "selector": "h1.title", "type": "text"},
    {"name": "link", "selector": "a.read-more", "type": "attribute", "attribute": "href"}
  ]
}

extract_llm.yml 与 llm_schema.json：

type: "llm"
provider: "openai/gpt-4"
instruction: "Extract all articles with their titles and links"
api_token: "your-token"
params:
    temperature: 0.3
    max_tokens: 1000

{
  "title": "Article",
  "type": "object",
  "properties": {
    "title": {"type": "string", "description": "The title of the article"},
    "link": {"type": "string", "description": "URL to the full article"}
  }
}

这些文件与 tests/cli/test_cli.py 中 sample_configs 夹具的结构一致，后者验证了 YAML 配置加载（headless: True、viewport_width: 1280）与 JSON Schema 加载（两个 fields）都能被 load_config_file 正确解析。

七、源码级实现要点与测试依据

把 CLI 的关键调用链串起来，可以帮助定位问题：

1. 参数层：Click 选项 → parse_key_values（k=v 类型推断）/load_config_file（YAML/JSON 加载）；
2. 构建层：profile 注入 → BrowserConfig.load/CrawlerRunConfig.load → clone(**内联参数) 覆盖 → 过滤器/抽取策略挂载 → CacheMode.BYPASS → 全局 VERBOSE 与 JSON_ENSURE_ASCII 收尾；
3. 执行层：anyio.run(run_crawler, ...) → AsyncWebCrawler.arun(url, config)，深爬时返回 CrawlResult 列表，单页爬取返回单个对象，输出分支据此区分处理；
4. 问答层：-q 触发 setup_llm_config + stream_llm_response（LiteLLM 流式），provider 配置缓存在 ~/.crawl4ai/global.yml。

CLI 行为的可验证依据集中在 tests/cli/test_cli.py：--help/--example 冒烟、parse_key_values 的正反例、配置文件加载（含不存在路径与非法 schema 必须失败）、以及 TestDeepCrawlOutput 对深爬多页输出的 stdout/文件两种通道的完整断言。

浏览器侧的命令行为则由 crawl4ai/browser_profiler.py 中的 BrowserProfiler 支撑（profile 增删查、builtin 浏览器启停、CDP 独立启动、profile shrink），其与 CLI 的分工在 docs/codebase/browser.md 有对照说明，可作为延伸阅读。

八、适用前提与使用注意

• 以上命令基于当前仓库 crwl 入口（pyproject.toml 第 83 行）安装后的行为；
• -j、-q 及 type: llm 的抽取依赖 LiteLLM 可达的 provider，Ollama 本地模型（ollama/... 前缀）可免 token；
• --bypass-cache 是 flag 且默认为 true，即默认命令总是绕过缓存，若需命中缓存需通过 -C 配置文件显式指定 cache_mode；
• profile 相关命令依赖本机可弹出可见浏览器窗口（创建/登录流程为人工交互），无显示环境请使用一次性 -b "user_data_dir=...,use_managed_browser=true" 方式复用已有档案目录；
• 深爬目前固定 max_depth=3，CLI 仅开放 --max-pages 调节广度上限，如需更细策略应改用 Python API 中的 BFSDeepCrawlStrategy 等构造参数。