Tavily Web Search

Full-featured Tavily web search with auto-update. All official API parameters supported. AI-optimized search for agents and RAG workflows.

BruceTangc@brucetangc

Install

openclaw skills install @brucetangc/tavily-web-search-full

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 安装（推荐）

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 摘要	1
`fast`	低	良好	相关片段	1
`basic`	中等	高	NLP 摘要	1
`advanced`	较高	最高	相关片段	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	操作	信用消耗	免费额度可用次数
Search	basic/fast/ultra-fast	1/次	1,000 次
Search	advanced	2/次	500 次
Extract	basic	1/5 URL	5,000 URL
Extract	advanced	2/5 URL	2,500 URL
Usage	查询	免费	无限

高级 API（默认禁用 ⚠️）

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

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

API	模型	信用消耗	免费额度可用次数
Research	mini	4-110/次	9-250 次
Research	pro	15-250/次	4-66 次

免费额度: 1000 信用/月

安全控制

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

节省信用技巧

日常使用 Search/Extract/Usage
启用缓存（默认开启）
设置合理的 max-results（3-5 足够）
避免不必要的 include_raw_content
批量提取 URL（5 个 URL = 1 信用）
谨慎使用 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 信用/月

节省信用技巧

使用 basic 深度进行日常搜索
启用缓存（默认开启）
设置合理的 max-results（3-5 足够）
避免不必要的 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

Tavily Web Search

Install

Tavily Web Search

✨ 功能特性

核心功能

官方 API 完整支持

📦 安装

从 ClawHub 安装（推荐）

本地使用

配置 API Key

🚀 使用示例

🔍 Search API（搜索）

📄 Extract API（URL 内容提取）

📊 Usage API（使用量查询）

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

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

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

新闻搜索

深度研究

域名过滤

国家/地区定向

图片搜索

快速搜索（低延迟）

自动参数

精确匹配

📋 完整参数说明

必需参数

搜索深度

💡 最佳实践

查询优化

搜索深度选择

结果过滤

成本优化

💰 API 信用说明

日常 API（推荐）

高级 API（默认禁用 ⚠️）

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

安全控制

节省信用技巧

主题分类

时间过滤

输出格式

💰 API 信用说明

节省信用技巧

🔄 自动更新

手动检查更新

自动更新（推荐）

更新日志

📁 文件位置

🔧 故障排除

"Missing TAVILY_API_KEY"

"Search failed after 3 attempts"

清除缓存

禁用缓存

📚 参考链接

Related skills