Tavily Web Search#

完整功能的 Tavily 网络搜索工具，基于官方 API 文档实现。专为 AI Agent 和 RAG 工作流设计。

✨ 功能特性#

核心功能#

• 🔄 自动重试 - 3 次重试 + 指数退避
• 💾 查询缓存 - 1 小时 TTL，节省 API 额度
• 📝 详细日志 - ~/.openclaw/logs/tavily.log
• 🎯 多种输出 - JSON / Brave 兼容 / Markdown

官方 API 完整支持#

功能参数说明搜索深度--search-depth``basic / advanced / fast / ultra-fast主题分类--topic``general / news / finance时间过滤--time-range``day / week / month / year日期范围--start-date / --end-dateYYYY-MM-DD 格式域名过滤--include-domains / --exclude-domains逗号分隔国家定向--country``united states / china 等AI 答案--include-answer / --answer-type``basic / advanced完整内容--include-raw-content``markdown / text图片搜索--include-images包含图片结果自动参数--auto-parametersAI 自动配置精确匹配--exact-match精确短语匹配

📦 安装#

从 ClawHub 安装（推荐）#

bash

clawhub install tavily-web-search-full

本地使用#

Skill 已放置在： ~/.openclaw/workspace/skills/tavily-web-search/

配置 API Key#

bash

# 方法 1: 添加到 ~/.openclaw/.env
echo "TAVILY_API_KEY=tvly-your-key-here" >> ~/.openclaw/.env

# 方法 2: 环境变量
export TAVILY_API_KEY="tvly-your-key-here"

获取 API Key: https://app.tavily.com/home (每月 1000 免费信用)

🚀 使用示例#

🔍 Search API（搜索）#

bash

# 简单搜索（默认 compact Markdown 输出）
python3 {baseDir}/scripts/search.py --query "Python tutorial"

# 指定结果数量
python3 {baseDir}/scripts/search.py --query "Docker compose" --max-results 10

# 新闻搜索
python3 {baseDir}/scripts/search.py --query "AI breakthrough" --topic news --time-range day

# 深度研究
python3 {baseDir}/scripts/search.py --query "LLM architecture" --search-depth advanced

# 域名过滤
python3 {baseDir}/scripts/search.py --query "React" --include-domains "github.com,dev.to"

📄 Extract API（URL 内容提取）#

bash

# 提取单个 URL
python3 {baseDir}/scripts/extract.py --urls "https://example.com/article"

# 提取多个 URL
python3 {baseDir}/scripts/extract.py --urls "https://a.com,https://b.com,https://c.com"

# 带查询提取（按相关性重排内容）
python3 {baseDir}/scripts/extract.py --urls "https://example.com" --query "find pricing information"

# 高级提取（更详细，2 信用/5 URL）
python3 {baseDir}/scripts/extract.py --urls "https://example.com" --extract-depth advanced

# 包含图片
python3 {baseDir}/scripts/extract.py --urls "https://example.com" --include-images

# 输出为纯文本
python3 {baseDir}/scripts/extract.py --urls "https://example.com" --format text

📊 Usage API（使用量查询）#

bash

# 查看使用量（简洁模式）
python3 {baseDir}/scripts/usage.py

# 详细 Markdown 输出
python3 {baseDir}/scripts/usage.py --md

# JSON 输出
python3 {baseDir}/scripts/usage.py --json

# 查询特定项目
python3 {baseDir}/scripts/usage.py --project-id "my-project-123"

🕷️ Crawl API（网站爬取）⚠️ 默认禁用#

成本: 3-5 信用/10 页 | 必须使用 --enable

bash

# 爬取网站（必须使用 --enable）
python3 {baseDir}/scripts/crawl.py --url "https://example.com" --enable

# 带指令爬取
python3 {baseDir}/scripts/crawl.py --url "https://example.com" --enable --instructions "find all pricing pages"

# 限制页数
python3 {baseDir}/scripts/crawl.py --url "https://example.com" --enable --limit 20

🗺️ Map API（网站地图）⚠️ 默认禁用#

成本: 1-2 信用/10 页 | 必须使用 --enable

bash

# 生成网站地图
python3 {baseDir}/scripts/map.py --url "https://example.com" --enable

# 带指令
python3 {baseDir}/scripts/map.py --url "https://example.com" --enable --instructions "find all blog posts"

# 输出 URL 列表
python3 {baseDir}/scripts/map.py --url "https://example.com" --enable --output urls

📚 Research API（深度研究）⚠️⚠️ 强烈建议默认禁用#

成本: 4-250 信用/次 | 必须使用 --enable --confirm

bash

# 深度研究（必须使用 --enable AND --confirm）
python3 {baseDir}/scripts/research.py --query "AI impact on healthcare" --enable --confirm

# Pro 模型（更贵但质量更高）
python3 {baseDir}/scripts/research.py --query "market analysis" --model pro --enable --confirm

新闻搜索#

bash

# 今日新闻
python3 {baseDir}/scripts/search.py --query "AI breakthrough" --topic news --time-range day

# 本周财经
python3 {baseDir}/scripts/search.py --query "stock market" --topic finance --time-range week

# 指定日期范围
python3 {baseDir}/scripts/search.py --query "election results" --start-date 2025-01-01 --end-date 2025-01-31

深度研究#

bash

# 高级模式（最高相关性，2 信用/次）
python3 {baseDir}/scripts/search.py --query "LLM architecture" --search-depth advanced

# 包含完整页面内容
python3 {baseDir}/scripts/search.py --query "React best practices" --include-raw-content markdown

# 详细 AI 答案
python3 {baseDir}/scripts/search.py --query "climate change impact" --answer-type advanced

域名过滤#

bash

# 只搜索特定网站
python3 {baseDir}/scripts/search.py --query "JavaScript tips" --include-domains "github.com,dev.to,medium.com"

# 排除某些网站
python3 {baseDir}/scripts/search.py --query "Python tutorial" --exclude-domains "w3schools.com"

# 组合使用
python3 {baseDir}/scripts/search.py --query "Rust programming" --include-domains "rust-lang.org,docs.rs" --exclude-domains "reddit.com"

国家/地区定向#

bash

# 美国科技新闻
python3 {baseDir}/scripts/search.py --query "tech startups" --country "united states" --topic news

# 中国财经
python3 {baseDir}/scripts/search.py --query "stock market" --country "china" --topic finance

图片搜索#

bash

# 搜索图片
python3 {baseDir}/scripts/search.py --query "sunset photography" --include-images

# 带描述
python3 {baseDir}/scripts/search.py --query "machine learning" --include-images --include-image-descriptions

快速搜索（低延迟）#

bash

# 快速模式（1 信用，低延迟）
python3 {baseDir}/scripts/search.py --query "weather today" --search-depth fast

# 超快速（1 信用，最低延迟）
python3 {baseDir}/scripts/search.py --query "stock price" --search-depth ultra-fast

自动参数#

bash

# 让 Tavily 自动配置（可能使用 advanced=2 信用）
python3 {baseDir}/scripts/search.py --query "comprehensive analysis of AI trends" --auto-parameters

# 自动参数但手动控制深度（控制成本）
python3 {baseDir}/scripts/search.py --query "research query" --auto-parameters --search-depth basic

精确匹配#

bash

# 精确搜索人名/公司名
python3 {baseDir}/scripts/search.py --query '"John Smith" CEO Acme Corp' --exact-match

📋 完整参数说明#

bash

python3 {baseDir}/scripts/search.py --help

必需参数#

参数说明--query搜索关键词（建议 <400 字符）

搜索深度#

参数值延迟相关性内容类型信用ultra-fast最低较低NLP 摘要1fast低良好相关片段1basic中等高NLP 摘要1advanced较高最高相关片段2

💡 最佳实践#

查询优化#

• ✅ 保持查询简洁 - 建议 <400 字符
• ✅ 复杂查询拆分 - 分成多个小查询
• ✅ 使用精确匹配 - 人名/公司名用 --exact-match
• ✅ 合理设置 max-results - 3-5 个足够（默认 5）

搜索深度选择#

• basic - 日常搜索（推荐）
• advanced - 深度研究（特定问题）
• fast / ultra-fast - 实时应用

结果过滤#

bash

# 按相关性分数过滤
python3 scripts/search.py --query "Python" --min-score 0.7

# 只搜索特定域名
python3 scripts/search.py --query "React" --include-domains "github.com,dev.to"

# 排除低质量站点
python3 scripts/search.py --query "AI" --exclude-domains "content-farm.com"

成本优化#

• ⚠️ auto_parameters 可能使用 advanced（2 信用）
• ✅ 手动设置 --search-depth basic 控制成本
• ✅ 使用缓存（默认开启）
• ✅ 批量提取 URL（5 个 URL = 1 信用）

💰 API 信用说明#

日常 API（推荐）#

API操作信用消耗免费额度可用次数Searchbasic/fast/ultra-fast1/次1,000 次Searchadvanced2/次500 次Extractbasic1/5 URL5,000 URLExtractadvanced2/5 URL2,500 URLUsage查询免费无限

高级 API（默认禁用 ⚠️）#

API操作信用消耗免费额度可用次数Map标准1/10 页10,000 页Map带指令2/10 页5,000 页Crawlbasic3/10 页3,300 页Crawladvanced5/10 页2,000 页

研究 API（极度昂贵 ⚠️⚠️）#

API模型信用消耗免费额度可用次数Researchmini4-110/次9-250 次Researchpro15-250/次4-66 次

免费额度: 1000 信用/月

安全控制#

API默认状态启用方式Search✅ 启用直接使用Extract✅ 启用直接使用Usage✅ 启用直接使用Map❌ 禁用--enableCrawl❌ 禁用--enableResearch❌ 禁用--enable --confirm

节省信用技巧#

1. 日常使用 Search/Extract/Usage
2. 启用缓存（默认开启）
3. 设置合理的 max-results（3-5 足够）
4. 避免不必要的 include_raw_content
5. 批量提取 URL（5 个 URL = 1 信用）
6. 谨慎使用 Crawl/Map/Research

主题分类#

• general - 通用搜索（默认）
• news - 新闻（包含 published_date）
• finance - 财经

时间过滤#

• --time-range: day / week / month / year
• --start-date: YYYY-MM-DD
• --end-date: YYYY-MM-DD

输出格式#

• compact - 简洁 Markdown（默认）
• md - 详细 Markdown（包含分数、完整内容）
• brave - JSON（兼容 web_search 格式）
• raw - 原始 JSON（包含所有字段）

💰 API 信用说明#

操作信用消耗basic/fast/ultra-fast 搜索1advanced 搜索2include_answer (advanced)+1include_raw_content+1include_images+1

免费额度: 1000 信用/月

节省信用技巧#

1. 使用 basic 深度进行日常搜索
2. 启用缓存（默认开启）
3. 设置合理的 max-results（3-5 足够）
4. 避免不必要的 include_raw_content

🔄 自动更新#

Tavily API 约每月更新 1-2 次。Skill 包含自动更新功能，定期检查官方 API 变更。

手动检查更新#

bash

# 检查是否有更新
python3 {baseDir}/scripts/update.py --check-only

# 应用更新
python3 {baseDir}/scripts/update.py

# 强制更新（即使无变更）
python3 {baseDir}/scripts/update.py --force

# 查看状态
python3 {baseDir}/scripts/update.py --status

自动更新（推荐）#

添加每周检查的 cron 任务：

bash

# 编辑 crontab
crontab -e

# 添加每周日 9:00 检查更新
0 9 * * 0 cd ~/.openclaw/workspace/skills/tavily-web-search && python3 scripts/update.py >> /tmp/tavily-update.log 2>&1

更新日志#

• 更新记录： {baseDir}/update.log
• 最后检查： {baseDir}/.last_check
• 版本信息： {baseDir}/_meta.json

📁 文件位置#

text

~/.openclaw/
├── .env                          # API key 配置
├── cache/tavily/                 # 缓存目录
│   ├── search/                   # Search 缓存
│   ├── extract/                  # Extract 缓存
│   ├── crawl/                    # Crawl 缓存
│   ├── map/                      # Map 缓存
│   └── research/                 # Research 缓存
├── logs/
│   ├── tavily.log                # Search 日志
│   ├── tavily_extract.log        # Extract 日志
│   ├── tavily_usage.log          # Usage 日志
│   ├── tavily_crawl.log          # Crawl 日志
│   ├── tavily_map.log            # Map 日志
│   └── tavily_research.log       # Research 日志
└── workspace/skills/tavily-web-search/
    ├── SKILL.md                  # 本文档
    ├── README.md                 # 快速开始
    ├── CHANGELOG.md              # 更新日志
    ├── _meta.json                # 版本信息
    ├── update.log                # 更新日志
    ├── .last_check               # 最后检查记录
    └── scripts/
        ├── search.py             # Search API（搜索）✅ 默认启用
        ├── extract.py            # Extract API（URL 提取）✅ 默认启用
        ├── usage.py              # Usage API（使用量查询）✅ 默认启用
        ├── crawl.py              # Crawl API（网站爬取）❌ 默认禁用
        ├── map.py                # Map API（网站地图）❌ 默认禁用
        ├── research.py           # Research API（深度研究）❌ 默认禁用
        ├── update.py             # 自动更新脚本
        └── test_all.py           # 测试套件

🔧 故障排除#

"Missing TAVILY_API_KEY"#

bash

# 检查配置
cat ~/.openclaw/.env | grep TAVILY

# 或设置环境变量
export TAVILY_API_KEY="tvly-xxx"

"Search failed after 3 attempts"#

• 检查网络连接
• 查看日志： tail -f ~/.openclaw/logs/tavily.log
• 验证 API key: https://app.tavily.com/home

清除缓存#

bash

rm -rf ~/.openclaw/cache/tavily/*

禁用缓存#

bash

python3 {baseDir}/scripts/search.py --query "test" --no-cache

📚 参考链接#

• 官方文档： https://docs.tavily.com
• API 参考： https://docs.tavily.com/documentation/api-reference/endpoint/search
• 最佳实践： https://docs.tavily.com/documentation/best-practices/best-practices-search
• 管理平台： https://app.tavily.com