OpenSkillIndex← back to search
claude-codeopenclawresearch

Skills tavily-web-search

Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/brucetangc/tavily-web-search-full" ~/.claude/skills/openclaw-skills-tavily-web-search && rm -rf "$T"
OpenClaw · Install into ~/.openclaw/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/brucetangc/tavily-web-search-full" ~/.openclaw/skills/openclaw-skills-tavily-web-search && rm -rf "$T"
manifest: skills/brucetangc/tavily-web-search-full/SKILL.md
tags
#web-search#data-extraction#api-integration#crawling#research#data-analysis
source content

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-date
YYYY-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-parameters
AI 自动配置
精确匹配
--exact-match
精确短语匹配

📦 安装

从 ClawHub 安装（推荐）

clawhub install tavily-web-search-full

本地使用

Skill 已放置在：

~/.openclaw/workspace/skills/tavily-web-search/

配置 API Key

# 方法 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（搜索）

# 简单搜索（默认 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 内容提取）

# 提取单个 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（使用量查询）

# 查看使用量（简洁模式）
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

# 爬取网站（必须使用 --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

# 生成网站地图
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

# 深度研究（必须使用 --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

新闻搜索

# 今日新闻
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

深度研究

# 高级模式（最高相关性，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

域名过滤

# 只搜索特定网站
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"

国家/地区定向

# 美国科技新闻
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

图片搜索

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

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

快速搜索（低延迟）

# 快速模式（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

自动参数

# 让 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

精确匹配

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

📋 完整参数说明

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

必需参数

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

搜索深度

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

💡 最佳实践

查询优化

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

搜索深度选择

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

结果过滤

# 按相关性分数过滤
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 URL
Extractadvanced2/5 URL2,500 URL
Usage查询免费无限

高级 API（默认禁用 ⚠️）

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

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

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

免费额度: 1000 信用/月

安全控制

API默认状态启用方式
Search✅ 启用直接使用
Extract✅ 启用直接使用
Usage✅ 启用直接使用
Map❌ 禁用
--enable
Crawl❌ 禁用
--enable
Research❌ 禁用
--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 搜索1
advanced 搜索2
include_answer (advanced)+1
include_raw_content+1
include_images+1

免费额度: 1000 信用/月

节省信用技巧

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

🔄 自动更新

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

手动检查更新

# 检查是否有更新
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 任务：

# 编辑 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

📁 文件位置

~/.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"

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

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

"Search failed after 3 attempts"

清除缓存

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

禁用缓存

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

📚 参考链接