Crawl4AI crwl CLI 深度解析命令面、配置体系与 Profile 身份爬取实战【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4aiCrawl4AI 通过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_modebuiltin复用的后台浏览器browser stop–终止 builtin 浏览器并删除其状态文件browser view--url, -u可选弹出 builtin 浏览器的可见窗口导航到指定 URL 或about:blankbrowser 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.ymlexamples–打印真实可用的 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 管理身份identitiesbrowser ... 控制长跑的无头 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, -bk1v1,k2v2形式的浏览器内联参数--crawler, -c同上形式的爬虫运行参数--output, -oall默认/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-crawlbfs/dfs/best-first启用深爬源码固定max_depth3--max-pages深爬最大页面数默认 10--json-ensure-ascii/--no-json-ensure-ascii控制 JSON 输出的非 ASCII 转义缺省取全局配置2.1 kv 内联参数的类型解析-b/-c参数由回调parse_key_valuescrawl4ai/cli.py解析它按逗号切分后对每个值做自动类型推断true/false→ 布尔值纯数字 →int带单个小数点 →float[a, b]→ 列表{k: v}→ 解析为 JSON 对象解析失败抛出BadParameter其余按字符串处理无法按keyvalue切分的片段会直接报错Invalid keyvalue pair。这一行为在 tests/cli/test_cli.py 中有回归验证key1value1,key2true应解析为{key1: value1, key2: True}而invalid_format必须抛出click.BadParameter。配置文件加载由load_config_filecrawl4ai/cli.py完成按扩展名区分 YAML 与 JSON文件不存在或解析失败时报BadParameter——这也是为什么所有-B/-C/-e/-s/-f选项都声明了typeclick.Path(existsTrue)。2.2 参数覆盖顺序与配置构建从源码执行顺序看crawl_cmd的配置组装遵循明确的优先级-p profile最先处理通过BrowserProfiler().get_profile_path(profile)按名字查路径查找失败会列出全部可用 profile命中后向浏览器参数注入user_data_dirprofile 路径且use_managed_browserTruecrawl4ai/cli.py-B文件 →BrowserConfig.load(...)-C文件 →CrawlerRunConfig.load(...)作为基线-b/-c内联参数通过browser_cfg.clone(**browser)覆盖在文件配置之上即“CLI 覆盖文件”缓存--bypass-cache默认defaultTrue只要传入就会把cache_mode设为CacheMode.BYPASS全局配置收尾VERBOSE从~/.crawl4ai/global.yml读取并覆盖两个配置对象的verbose字段JSON_ENSURE_ASCII按「CLI 标志 全局配置 默认值」的优先级生效。爬取本身收敛在run_crawlercrawl4ai/cli.pyAsyncWebCrawler(configbrowser_cfg)上下文管理器内执行await crawler.arun(urlurl, configcrawler_cfg)异常统一包装为click.ClickException。2.3 抽取-j、-e/-s 与 -f 三种能力-jLLM 快速抽取首次使用会调用setup_llm_config交互询问 provider 与 token格式company/model如ollama/llama3.3、openai/gpt-4并持久化到全局配置。指令选择逻辑在 crawl4ai/cli.py无参-j使用内置的通用结构化抽取指令识别列表页抽数组、文章页抽对象带参-j ...则把用户描述拼进指令模板。底层构造LLMExtractionStrategyextraction_typeschema、force_json_responseTrue。若未显式指定-o会自动降级为json输出。-e-s策略文件抽取type仅接受llm/json-css/json-xpath分别映射到LLMExtractionStrategy、JsonCssExtractionStrategy、JsonXPathExtractionStrategyllm类型强制要求provider与api_token字段params中的键值会展开进策略构造。-f内容过滤配置文件type为bm25时构建BM25ContentFilterbm25_threshold默认 1.0、use_stemming默认 True为pruning时构建PruningContentFilterthreshold默认 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_depth3、max_pages取--max-pages默认 10crawl4ai/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_responsecrawl4ai/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 Managercrwl profilesTUI 菜单1 列出、2 创建、3 删除、4 选档爬取、5 退出创建新 profilecrwl profiles→ 选2→ 输入名字 → 浏览器弹出 → 登录 → 终端按q保存至~/.crawl4ai/profiles/name列出已存 profilecrwl profiles→ 选1展示名字、浏览器类型、体积、修改时间删除 profilecrwl profiles→ 选3→ 选索引 → 确认删除对应目录用 profile 爬取默认别名crwl https://site.com/dashboard -p my-profile保留登录 cookie底层自动设置use_managed_browsertrueprofile 详细 JSON 输出crwl https://site.com -p my-profile -o json -v其余crawl标志同样可用叠加浏览器微调crwl https://site.com -p my-profile -b headlesstrue,viewport_width1680CLI 覆盖优先于 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_browsertrue绕过注册表适合 CI 脚本以相同身份在 CDP 端口拉起调试浏览器crwl cdp -d $HOME/.crawl4ai/profiles/my-profile -P 9223便于 Puppeteer/Playwright 附着调试源码层面交互式创建对应create_profile_interactivecrawl4ai/cli.py内部调用BrowserProfiler.create_profile()弹出可见浏览器人工登录后在终端按q触发压缩保存“选档爬取”对应crawl_with_profile_clicrawl4ai/cli.py它固定构造BrowserConfig(headlessFalse, use_managed_browserTrue, user_data_dirprofile_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_PATTERNSlight仅删缓存保留 History、Bookmarks、Web Data 等medium缓存 历史/收藏一并移除aggressive默认推荐只留Network、Cookies、Local Storage、IndexedDB、Preferences与storage_state.jsonminimal只留Network、Cookies、Local Storage与storage_state.json。所有等级都强制保留storage_state.jsonPlaywright 的可移植 cookie 格式以保证跨机器迁移可用性--dry-run只报告将删除的内容。命令会打印移除/保留条目数、释放空间与前后体积。四、builtin 浏览器管理browser 子命令builtin 浏览器是一个常驻后台的 Chromium 实例状态记录在本地 JSON 文件中含wsEndpoint、pid、started_at供所有browser_modebuiltin的爬取复用避免每次冷启动浏览器。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 URLcrwl browser stop调用kill_builtin_browser终止进程并清理状态文件crwl browser view --url https://example.com按平台选择 Chrome 可执行路径macOS 为/Applications/Google Chrome.app/...Linux 为google-chromeWindows 为 Program Files 路径用同一--remote-debugging-port弹出可见窗口crwl browser restart先读当前配置再停后启未指定的参数继承现状注意源码中 headless 在继承时按True假设crawl4ai/cli.py。与 builtin 不同的还有crwl cdpcrawl4ai/cli.py它启动的是独立调试浏览器而非 builtin 实例-d可指定/自动创建 user-data-dir--incognito会忽略该目录浏览器保持运行直到按q期间 CDP URL 可直接交给其他自动化工具使用。五、全局配置config 子命令与 USER_SETTINGSconfig list/get/set管理的设置项定义在 crawl4ai/config.py 的USER_SETTINGS中共 8 项设置键默认值类型 / 可选值说明DEFAULT_LLM_PROVIDERopenai/gpt-4ostring默认 LLM providercompany/model格式DEFAULT_LLM_PROVIDER_TOKEN空stringsecret列表时掩码为********默认 provider 的 API tokenVERBOSEfalseboolean全局详细输出BROWSER_HEADLESStrueboolean浏览器默认无头模式BROWSER_TYPEchromiumstringchromium/firefox默认浏览器类型CACHE_MODEbypassstringbypass/use/refresh默认缓存模式USER_AGENT_MODEdefaultstringdefault/random/mobile默认 User-Agent 模式JSON_ENSURE_ASCIItruebooleanJSON 输出是否转义非 ASCII 字符几个实现细节值得注意持久化位置get_global_config/save_global_configcrawl4ai/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 headlessfalse,viewport_width1920 # 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 headlesstrue,viewport_width1280,user_agent_moderandom crwl https://example.com -c css_selector#main,delay_before_return_html2,scan_full_pagetrue # 登录态爬取 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_examplesbrowser.ymlheadless: true viewport_width: 1280 user_agent_mode: random verbose: true ignore_https_errors: trueextract_css.yml与css_schema.jsontype: 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.jsontype: 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 的关键调用链串起来可以帮助定位问题参数层Click 选项 →parse_key_valueskv 类型推断/load_config_fileYAML/JSON 加载构建层profile 注入 →BrowserConfig.load/CrawlerRunConfig.load→clone(**内联参数)覆盖 → 过滤器/抽取策略挂载 →CacheMode.BYPASS→ 全局VERBOSE与JSON_ENSURE_ASCII收尾执行层anyio.run(run_crawler, ...)→AsyncWebCrawler.arun(url, config)深爬时返回CrawlResult列表单页爬取返回单个对象输出分支据此区分处理问答层-q触发setup_llm_configstream_llm_responseLiteLLM 流式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 可达的 providerOllama 本地模型ollama/...前缀可免 token--bypass-cache是 flag 且默认为 true即默认命令总是绕过缓存若需命中缓存需通过-C配置文件显式指定cache_modeprofile 相关命令依赖本机可弹出可见浏览器窗口创建/登录流程为人工交互无显示环境请使用一次性-b user_data_dir...,use_managed_browsertrue方式复用已有档案目录深爬目前固定max_depth3CLI 仅开放--max-pages调节广度上限如需更细策略应改用 Python API 中的BFSDeepCrawlStrategy等构造参数。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考