用途
Tavily Crawl Skill 用于遍历整个网站，并在一次 API 调用中从多个页面提取内容。它适合将文档站点、知识库或任何多页面资源摄取到上下文中。
何时使用
- 需要阅读整个文档站点（例如某个库的 API 文档）
- 从网站构建知识库
- 在定向提取之前探索未知的站点结构
- 当 tavily-extract 需要过多单独 URL 时
对比：已有具体 URL 时使用 tavily-extract；需要从起始 URL 发现并读取多个页面时使用本技能。
注意：max_depth ≥ 2 可能耗时数分钟并返回大量数据。请始终从 max_depth=1 和 limit=20 起步。
认证
在 ~/.openclaw/.env.local 中设置 TAVILY_API_KEY：
TAVILY_API_KEY=tvly-your-api-key-here
API 参考
端点：POST https://api.tavily.com/crawl
请求字段：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| url | string | 必填 | 开始爬取的根 URL |
| max_depth | integer | 1 | 跟随链接的深度层级（1–5） |
| max_breadth | integer | 20 | 每页最多跟随的链接数 |
| limit | integer | 50 | 总页数上限 |
| instructions | string | null | 自然语言聚焦指引 |
| chunks_per_source | integer | 3 | 每页相关块数量（1–5，需要 instructions） |
| extract_depth | string | "basic" | basic 或 advanced（用于 JS 渲染站点） |
| format | string | "markdown" | markdown 或 text |
| select_paths | array | null | 要包含的正则模式（例如 ["/docs/.*"]） |
| exclude_paths | array | null | 要排除的正则模式（例如 ["/blog/.*"]） |
| allow_external | boolean | true | 是否跟随指向外部域名的链接 |
| timeout | float | 150 | 最长等待秒数（10–150） |
响应格式
{ "base_url": "https://docs.example.com", "results": [ { "url": "https://docs.example.com/getting-started", "raw_content": "# Getting Started\n\n..." } ], "response_time": 8.3 }
示例
基础爬取（保守起步）
curl -s -X POST https://api.tavily.com/crawl
-H "Authorization: Bearer $TAVILY_API_KEY"
-H "Content-Type: application/json"
-d '{
"url": "https://docs.example.com",
"max_depth": 1,
"limit": 20
}'
面向智能体用途的聚焦爬取（推荐模式）
在将结果送入 LLM 上下文时，始终使用 instructions + chunks_per_source —— 只返回相关块而非整页，防止上下文溢出：
curl -s -X POST https://api.tavily.com/crawl
-H "Authorization: Bearer $TAVILY_API_KEY"
-H "Content-Type: application/json"
-d '{
"url": "https://docs.example.com",
"max_depth": 2,
"instructions": "Find authentication guides and API reference",
"chunks_per_source": 3,
"select_paths": ["/docs/.", "/api/."],
"exclude_paths": ["/changelog/.", "/blog/."]
}'
仅爬取特定区块
curl -s -X POST https://api.tavily.com/crawl
-H "Authorization: Bearer $TAVILY_API_KEY"
-H "Content-Type: application/json"
-d '{
"url": "https://example.com",
"max_depth": 2,
"select_paths": ["/docs/."],
"exclude_paths": ["/docs/legacy/."],
"limit": 30
}'
Map API（仅发现 URL，不获取内容）
当只需要先发现存在哪些页面，再决定爬取或提取哪些时使用 map：
curl -s -X POST https://api.tavily.com/map
-H "Authorization: Bearer $TAVILY_API_KEY"
-H "Content-Type: application/json"
-d '{
"url": "https://docs.example.com",
"max_depth": 2,
"instructions": "Find all API reference and authentication pages"
}'
响应仅返回 URL 列表 —— 比 crawl 快得多。
深度与性能
| max_depth | 典型页数 | 时间 |
|---|---|---|
| 1 | 10–50 | 数秒 |
| 2 | 50–500 | 数分钟 |
| 3+ | 500–5000+ | 很多分钟 |
提示
- 始终从 max_depth=1 和 limit=20 起步，必要时再增加
- 始终设置 limit 以防止爬取失控
- 面向智能体工作流时使用 instructions + chunks_per_source —— 仅在保存整页数据时省略
- 使用 select_paths 聚焦相关站点区块（docs、API、guides）
- 先用 map 了解站点结构，再爬取或提取特定区块
- allow_external: false 可防止离开目标站点