Xpersona
agentCLAWHUBUnverified

Tavily Web Search

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

OpenClaw
View on ClawHubHomepage

Rank

62

Safety

84

Downloads

1.8k

Updated

Oct 10, 2026

Version

2.0.6

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.8K downloads reported by the source. Last updated 10/10/2026.

Avoid when

  • Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor
Clawhubvendor · observed Oct 10, 2026
Protocol compatibility
OpenClawcompatibility · observed Oct 10, 2026
Adoption signal
1.8K downloadsadoption · observed Oct 10, 2026
Latest release
2.0.6release · observed Mar 22, 2026
Handshake status
UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17c86x64fn6cy26y1t8rwnn4983f35d:tavily-web-search-full
  1. Install using `clawhub skill install s17c86x64fn6cy26y1t8rwnn4983f35d:tavily-web-search-full` in an isolated environment before connecting it to live workloads.
  2. No published capability contract is available yet, so validate auth and request/response behavior manually.
  3. Review the upstream CLAWHUB listing at https://clawhub.ai/brucetangc/tavily-web-search-full before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/snapshot"

Documentation

CLAWHUB

148,063 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: tavily-web-search
description: Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.
homepage: https://tavily.com
version: 2.0.3
metadata: {
  "clawdbot": {
    "emoji": "🔍",
    "requires": {
      "bins": ["python3"],
      "env": ["TAVILY_API_KEY"]
    },
    "primaryEnv": "TAVILY_API_KEY"
  }
}
---

# 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 {base

README.md

# Tavily Web Search Skill - v2.0.0

完整功能的 Tavily 工具包，包含所有 6 个官方 API。基于官方 API 文档实现。

## 📦 ClawHub 发布

- **Slug**: `tavily-web-search-full`
- **版本**: 2.0.0
- **发布**: ✅ 已发布到 ClawHub
- **APIs**: Search + Extract + Usage + Crawl + Map + Research

## 🚀 快速开始

### ✅ 日常 API（默认启用）

```bash
# Search - 网络搜索
python3 scripts/search.py --query "你的问题"

# Extract - URL 内容提取
python3 scripts/extract.py --urls "https://example.com/article"

# Usage - 查看使用量
python3 scripts/usage.py
```

### ⚠️ 高级 API（默认禁用 - 需 `--enable`）

```bash
# Crawl - 网站爬取（3-5 信用/10 页）
python3 scripts/crawl.py --url "https://example.com" --enable

# Map - 网站地图（1-2 信用/10 页）
python3 scripts/map.py --url "https://example.com" --enable
```

### ⚠️⚠️ 研究 API（极度昂贵 - 需 `--enable --confirm`）

```bash
# Research - 深度研究（4-250 信用/次）
python3 scripts/research.py --query "AI impact" --enable --confirm
```

## 📊 API 对比

| API | 默认 | 成本 | 启用方式 |
|-----|------|------|---------|
| **Search** | ✅ | 1-2 信用/次 | 直接使用 |
| **Extract** | ✅ | 1-2 信用/5 URL | 直接使用 |
| **Usage** | ✅ | 免费 | 直接使用 |
| **Crawl** | ❌ | 3-5 信用/10 页 | `--enable` |
| **Map** | ❌ | 1-2 信用/10 页 | `--enable` |
| **Research** | ❌ | 4-250 信用/次 | `--enable --confirm` |

## 💰 成本说明

### 免费额度（1000 信用/月）可做：

- **Search (basic)**: 1,000 次
- **Extract (basic)**: 5,000 个 URL
- **Map**: 5,000-10,000 页
- **Crawl**: 2,000-3,300 页
- **Research (mini)**: 9-250 次
- **Research (pro)**: 4-66 次

### 建议

- ✅ **日常使用**: Search + Extract + Usage
- ⚠️ **偶尔使用**: Crawl + Map（需要时加 `--enable`）
- ❌ **谨慎使用**: Research（太贵，除非必要）

## 📁 文件结构

```
tavily-web-search/
├── SKILL.md              # 完整文档
├── README.md             # 本文件
├── CHANGELOG.md          # 更新日志
├── _meta.json            # v2.0.0
└── scripts/
    ├── search.py         # Search API ✅
    ├── extract.py        # Extract API ✅
    ├── usage.py          # Usage API ✅
    ├── crawl.py          # Crawl API ❌ (--enable)
    ├── map.py            # Map API ❌ (--enable)
    ├── research.py       # Research API ❌ (--enable --confirm)
    ├── update.py         # 自动更新
    └── test_all.py       # 测试套件
```

## 🔧 配置

需要 API Key，添加到 `~/.openclaw/.env`:
```
TAVILY_API_KEY=tvly-your-key-here
```

获取 Key: https://app.tavily.com/home（1000 免费信用/月）

## 📚 文档

详细文档见 `SKILL.md` 或运行：
```bash
python3 scripts/search.py --help
python3 scripts/extract.py --help
python3 scripts/crawl.py --help
python3 scripts/map.py --help
python3 scripts/research.py --help
```

## 🔗 链接

- ClawHub: https://clawhub.com/skills/tavily-web-search-full
- Tavily 官方：https://tavily.com
- API 文档：https://docs.tavily.com

_meta.json

{
  "ownerId": "kn7afdk9ag1ftxjn0btmw2tj3h82y30x",
  "slug": "tavily-web-search-full",
  "version": "2.0.6",
  "publishedAt": 1774191396782
}

CHANGELOG.md

# Tavily Web Search Skill - 更新总结

## 📦 版本 2.0.0 更新内容（重大更新）

### 新增 API（默认禁用）

#### 1. Crawl API（网站爬取）⚠️
- **脚本**: `scripts/crawl.py`
- **成本**: 3-5 信用/10 页
- **安全控制**: 必须使用 `--enable` 标志
- **特性**:
  - ✅ 智能网站遍历
  - ✅ 自然语言指令
  - ✅ 深度/广度控制
  - ✅ 路径/域名过滤
  - ✅ 自动缓存（2 小时）

**使用示例**:
```bash
# 必须使用 --enable
python3 scripts/crawl.py --url "https://example.com" --enable

# 带指令
python3 scripts/crawl.py --url "https://example.com" --enable --instructions "find all pricing pages"
```

#### 2. Map API（网站地图）⚠️
- **脚本**: `scripts/map.py`
- **成本**: 1-2 信用/10 页
- **安全控制**: 必须使用 `--enable` 标志
- **特性**:
  - ✅ 快速生成网站地图
  - ✅ 自然语言指令
  - ✅ 多种输出格式（包括 URL 列表）
  - ✅ 自动缓存

**使用示例**:
```bash
# 必须使用 --enable
python3 scripts/map.py --url "https://example.com" --enable

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

#### 3. Research API（深度研究）⚠️⚠️
- **脚本**: `scripts/research.py`
- **成本**: 4-250 信用/次（非常贵！）
- **安全控制**: 必须使用 `--enable --confirm` 双重确认
- **特性**:
  - ✅ 深度研究报告
  - ✅ 两种模型（mini/pro）
  - ✅ 多源分析
  - ✅ 自动缓存（24 小时）

**使用示例**:
```bash
# 必须使用 --enable AND --confirm
python3 scripts/research.py --query "AI impact on healthcare" --enable --confirm

# Pro 模型
python3 scripts/research.py --query "market analysis" --model pro --enable --confirm
```

### 安全控制策略

| API | 默认状态 | 启用要求 | 原因 |
|-----|---------|---------|------|
| Search | ✅ 启用 | 无 | 便宜（1-2 信用） |
| Extract | ✅ 启用 | 无 | 便宜（1-2 信用/5 URL） |
| Usage | ✅ 启用 | 无 | 免费 |
| Crawl | ❌ 禁用 | `--enable` | 较贵（3-5 信用/10 页） |
| Map | ❌ 禁用 | `--enable` | 中等（1-2 信用/10 页） |
| Research | ❌ 禁用 | `--enable --confirm` | 极贵（4-250 信用） |

### 设计理念

1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景
2. **高级 API 需要确认** - 防止误用导致信用快速消耗
3. **研究 API 双重确认** - 极端成本，必须明确意图

---

## 📦 版本 1.1.0 更新内容

### 新增功能

#### 1. Extract API（URL 内容提取）
- **脚本**: `scripts/extract.py`
- **功能**: 从指定 URL 提取完整内容
- **成本**: 1 信用/5 个 URL（basic）或 2 信用/5 个 URL（advanced）
- **特性**:
  - ✅ 支持单个或多个 URL
  - ✅ 查询重排（按相关性排序内容块）
  - ✅ 两种提取深度（basic/advanced）
  - ✅ 支持图片提取
  - ✅ 支持 favicon
  - ✅ 多种输出格式（markdown/text/JSON）
  - ✅ 自动缓存

**使用示例**:
```bash
# 提取单个 URL
python3 scripts/extract.py --urls "https://example.com/article"

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

# 带查询提取（重排内容）
python3 scripts/extract.py --urls "https://example.com" --query "find pricing info"
```

#### 2. Usage API（使用量查询）
- **脚本**: `scripts/usage.py`
- **功能**: 查询 API 使用量和信用余额
- **成本**: 免费
- **特性**:
  - ✅ 显示已用/剩余/总信用
  - ✅ 可视化使用进度条
  - ✅ 按端点分类统计
  - ✅ 支持项目过滤
  - ✅ 多种输出格式（compact/md/JSON）

**使用示例**:
```bash
# 查看使用量
python3 scripts/usage.py

# 详细输出
python3 scripts/usage.py --md

# JSON 输出
python3 scripts/usage.py --json
```

### 改进功能

#### 1. 更新脚本增强
- **脚本**: `scripts/update.py`
- **改进**:
  - ✅ 支持 Extract API 参数追踪
  - ✅ 更详细的更新日志
  - ✅ 自动版本号递增

#### 2. 测试套件
- **脚本**: `scripts/test_all.py`
- **功能**: 自动化测试所有 API
- **使用**:
  ```bash
  # 快速测试（仅 Search）
  python3 scripts/test_all.py --quick
  
  # 完整测试
  python3 scripts/test_all.py
  ```

### 文档更新

-

RATE_LIMIT.md

# Rate Limit 处理实现说明

## 📊 Tavily 官方速率限制

根据官方文档：https://docs.tavily.com/documentation/rate-limits.md

| API | Development | Production |
|-----|-------------|------------|
| **Search/Extract/Map** | 100 RPM | 1,000 RPM |
| **Crawl** | 100 RPM | 100 RPM |
| **Research** | 20 RPM | 20 RPM |
| **Usage** | 10 次/10 分钟 | 10 次/10 分钟 |

## 🔧 实现方式

### 1. 统一 Rate Limit 处理器

创建了 `rate_limit.py` 模块，提供：

- ✅ 429 错误自动检测
- ✅ `retry-after` 头解析
- ✅ 指数退避重试
- ✅ 可配置的重试次数和延迟
- ✅ 装饰器模式，易于集成

### 2. 核心功能

```python
@rate_limit_handler(
    max_retries=3,           # 最多重试 3 次
    base_delay=1.0,          # 基础延迟 1 秒
    max_delay=300.0,         # 最大延迟 5 分钟
    exponential_base=2.0,    # 指数退避底数
    log_func=log             # 日志函数
)
def api_call():
    # API 调用代码
    pass
```

### 3. 重试策略

| 尝试次数 | 延迟时间 | 说明 |
|---------|---------|------|
| 1 | - | 首次请求 |
| 2 | 1-2 秒 | 第一次重试 |
| 3 | 2-4 秒 | 第二次重试 |
| 4 | 4-8 秒 | 第三次重试（如果 max_retries=4） |

如果服务器返回 `retry-after` 头，则使用服务器指定的时间。

### 4. 429 错误处理流程

```
请求 API
   ↓
收到 429 错误
   ↓
检查 retry-after 头
   ↓
计算等待时间
   ↓
等待指定时间
   ↓
重试请求
   ↓
成功 或 达到最大重试次数
```

## 📁 已更新的脚本

| 脚本 | 状态 | 说明 |
|------|------|------|
| `rate_limit.py` | ✅ 新建 | 通用 Rate Limit 处理器 |
| `search.py` | ✅ 已更新 | 集成 Rate Limit 处理 |
| `extract.py` | ✅ 已更新 | 集成 Rate Limit 处理 |
| `crawl.py` | ⏳ 待更新 | - |
| `map.py` | ⏳ 待更新 | - |
| `research.py` | ⏳ 待更新 | - |
| `usage.py` | ⏳ 待更新 | - |

## 🧪 测试

```bash
# 运行测试套件
python3 scripts/test_all.py --quick

# 输出
✅ Passed: 4/4 (100%)
```

## 💡 使用示例

### 正常情况
```bash
$ python3 scripts/search.py --query "test"

[DEBUG] Request attempt 1/3: test...
[INFO] Success: 5 results
```

### 遇到 Rate Limit
```bash
$ python3 scripts/search.py --query "test"

[DEBUG] Request attempt 1/3: test...
[WARN] Rate limited. Waiting 2.0s before retry...
[DEBUG] Request attempt 2/3: test...
[INFO] Success: 5 results
```

### 超过限制
```bash
$ python3 scripts/search.py --query "test"

[DEBUG] Request attempt 1/3: test...
[WARN] Rate limited. Waiting 2.0s before retry...
[DEBUG] Request attempt 2/3: test...
[WARN] Rate limited. Waiting 4.0s before retry...
[DEBUG] Request attempt 3/3: test...
[ERROR] All 3 retries failed: Rate limit exceeded
```

## 🎯 最佳实践

### 1. 批量请求时的延迟

```python
# ❌ 不好 - 快速连续请求
for query in queries:
    search(query)

# ✅ 好 - 添加延迟
import time
for query in queries:
    search(query)
    time.sleep(0.5)  # 每秒 2 个请求
```

### 2. 监控使用量

```bash
# 定期检查使用量
python3 scripts/usage.py
```

### 3. 使用缓存

```bash
# 启用缓存（默认开启）
python3 scripts/search.py --query "test"

# 强制刷新（禁用缓存）
python3 scripts/search.py --query "test" --no-cache
```

### 4. 了解限制

- **Development Key**: 100 RPM = 每秒~1.6 个请求
- **Production Key**: 1,000 RPM = 每秒~16 个请求

## 📚 相关文件

- `scripts/rate_limit.py` - Rate Limit 处理器
- `scripts/search.py` - 已集成
- `scripts/extract.py` - 已集成
- https://docs.tavily.com/documentation/rate-limits.md - 官方文档

## 🔄 后续更新

待更新的脚本：
- [ ] `crawl.py`
- [ ] `map.py`
- [ ] `research.py`
- [ ] `usage.py`

更新方法：
```python
# 1. 添加导入
from rate_limit import

Related agents

Same protocol, similar job.

Github ReposUpdated 10h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW
Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW
Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.

MCPOPENCLAW
Github ReposUpdated 7mo agoRank 70

CopilotKit

The Frontend for Agents & Generative UI. React + Angular

OPENCLAW

Machine-readable data

The same record, as JSON, for agents and crawlers.

{
  "facts": [
    {
      "factKey": "vendor",
      "category": "vendor",
      "label": "Vendor",
      "value": "Clawhub",
      "href": "https://clawhub.ai/brucetangc/skills/tavily-web-search-full",
      "sourceUrl": "https://clawhub.ai/brucetangc/skills/tavily-web-search-full",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-10T00:52:17.899Z",
      "isPublic": true
    },
    {
      "factKey": "protocols",
      "category": "compatibility",
      "label": "Protocol compatibility",
      "value": "OpenClaw",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/contract",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/contract",
      "sourceType": "contract",
      "confidence": "medium",
      "observedAt": "2026-10-10T00:52:17.899Z",
      "isPublic": true
    },
    {
      "factKey": "traction",
      "category": "adoption",
      "label": "Adoption signal",
      "value": "1.8K downloads",
      "href": "https://clawhub.ai/brucetangc/tavily-web-search-full",
      "sourceUrl": "https://clawhub.ai/brucetangc/tavily-web-search-full",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-10T00:52:17.899Z",
      "isPublic": true
    },
    {
      "factKey": "latest_release",
      "category": "release",
      "label": "Latest release",
      "value": "2.0.6",
      "href": "https://clawhub.ai/brucetangc/tavily-web-search-full",
      "sourceUrl": "https://clawhub.ai/brucetangc/tavily-web-search-full",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-03-22T14:56:36.782Z",
      "isPublic": true
    },
    {
      "factKey": "handshake_status",
      "category": "security",
      "label": "Handshake status",
      "value": "UNKNOWN",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/trust",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/trust",
      "sourceType": "trust",
      "confidence": "medium",
      "observedAt": null,
      "isPublic": true
    }
  ],
  "events": [
    {
      "eventType": "release",
      "title": "Release 2.0.6",
      "description": "v2.0.6: Fixed metadata declarations (network access) + Security scan improvements",
      "href": "https://clawhub.ai/brucetangc/tavily-web-search-full",
      "sourceUrl": "https://clawhub.ai/brucetangc/tavily-web-search-full",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-03-22T14:56:36.782Z",
      "isPublic": true
    }
  ]
}

Record generated Oct 10, 2026.

Sponsored

Ads related to Tavily Web Search and adjacent AI workflows.