crawl

Crawl 技能

爬取网站，从多个页面提取内容。适用于文档、知识库和全站内容提取。

身份验证

此脚本通过 Tavily MCP 服务使用 OAuth。无需手动设置——首次运行时，脚本会：

1. 检查 ~/.mcp-auth/ 中是否已有令牌
2. 如果没有找到，则自动打开浏览器进行 OAuth 身份验证

注意： 你必须拥有现有的 Tavily 账户。OAuth 流程仅支持登录，无法通过此流程创建账户。如果你还没有账户，请先在 tavily.com 注册。

替代方案：API 密钥

如果你更倾向于使用 API 密钥，请前往 https://tavily.com 获取密钥，并将其添加到 ~/.claude/settings.json：

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  }
}

快速开始

使用脚本

./scripts/crawl.sh '<json>' [output_dir]

示例：

# Basic crawl
./scripts/crawl.sh '{"url": "https://docs.example.com"}'

# Deeper crawl with limits
./scripts/crawl.sh '{"url": "https://docs.example.com", "max_depth": 2, "limit": 50}'

# Save to files
./scripts/crawl.sh '{"url": "https://docs.example.com", "max_depth": 2}' ./docs

# Focused crawl with path filters
./scripts/crawl.sh '{"url": "https://example.com", "max_depth": 2, "select_paths": ["/docs/.*", "/api/.*"], "exclude_paths": ["/blog/.*"]}'

# With semantic instructions (for agentic use)
./scripts/crawl.sh '{"url": "https://docs.example.com", "instructions": "Find API documentation", "chunks_per_source": 3}'

提供 output_dir 时，每个爬取的页面都会另存为一个 Markdown 文件。

基础爬取

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 1,
    "limit": 20
  }'

使用指令进行定向爬取

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find API documentation and code examples",
    "chunks_per_source": 3,
    "select_paths": ["/docs/.*", "/api/.*"]
  }'

API 参考

端点

POST https://api.tavily.com/crawl

请求头

请求头	值
Authorization	Bearer <TAVILY_API_KEY>
Content-Type	application/json

请求正文

字段	类型	默认值	说明
url	字符串	必填	开始爬取的根 URL
max_depth	整数	1	爬取深度（1-5）
max_breadth	整数	20	每页链接数
limit	整数	50	页面总数上限
instructions	字符串	null	用于指定爬取重点的自然语言指引
chunks_per_source	整数	3	每页的文本块数（1-5，需要提供 instructions）
extract_depth	字符串	"basic"	basic 或 advanced
format	字符串	"markdown"	markdown 或 text
select_paths	数组	null	要包含的正则表达式模式
exclude_paths	数组	null	要排除的正则表达式模式
allow_external	布尔值	true	是否包含外部域名的链接
timeout	浮点数	150	最大等待时间（10-150 秒）

响应格式

{
  "base_url": "https://docs.example.com",
  "results": [
    {
      "url": "https://docs.example.com/page",
      "raw_content": "# Page Title\n\nContent..."
    }
  ],
  "response_time": 12.5
}

深度与性能

深度	典型页面数	耗时
1	10-50	秒
2	50-500	分钟
3	500-5000	多分钟

从 max_depth=1 开始，仅在需要时增加深度。

用于上下文还是数据收集

用于 Agent（将结果输入上下文）： 始终使用 instructions + chunks_per_source。这样只会返回相关文本块，而非完整页面，从而防止上下文窗口溢出。

用于数据收集（保存到文件）： 省略 chunks_per_source，以获取完整页面内容。

示例

用于上下文：Agent 式研究（推荐）

在将爬取结果输入大模型上下文时使用：

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find API documentation and authentication guides",
    "chunks_per_source": 3
  }'

每个页面仅返回最相关的文本块（每块最多 500 个字符），适合放入上下文而不会造成内容过载。

用于上下文：针对性技术文档

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com",
    "max_depth": 2,
    "instructions": "Find all documentation about authentication and security",
    "chunks_per_source": 3,
    "select_paths": ["/docs/.*", "/api/.*"]
  }'

用于数据收集：完整页面归档

在将内容保存到文件以供后续处理时使用：

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/blog",
    "max_depth": 2,
    "max_breadth": 50,
    "select_paths": ["/blog/.*"],
    "exclude_paths": ["/blog/tag/.*", "/blog/category/.*"]
  }'

返回完整页面内容——使用脚本的 output_dir 将内容保存为 Markdown 文件。

Map API（URL 发现）

如果只需要 URL 而非内容，请使用 map 代替 crawl：

curl --request POST \
  --url https://api.tavily.com/map \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find all API docs and guides"
  }'

仅返回 URL（比 crawl 更快）：

{
  "base_url": "https://docs.example.com",
  "results": [
    "https://docs.example.com/api/auth",
    "https://docs.example.com/guides/quickstart"
  ]
}

提示

• Agent 工作流始终使用 chunks_per_source——将结果输入大模型时可防止上下文溢出
• 仅在数据收集时省略 chunks_per_source——即将完整页面保存到文件时
• 从保守设置开始（max_depth=1、limit=20），再逐步提高
• 使用路径模式聚焦于相关部分
• 完整爬取前先使用 Map了解网站结构
• 始终设置 limit，防止爬取失控