什么是 Tavily AI 搜索？

Tavily AI 搜索是一款专为 AI 智能体和 LLM 应用构建的先进搜索工具。与返回杂乱 HTML 和广告的传统搜索引擎不同，此技能提供结构化、无噪点的内容，可立即供 AI 模型处理。通过将其集成到您的 Openclaw Skills 集合中，您可以使您的智能体能够轻松进行高速事实查询或深入的技术研究。

该技能支持多种运行模式，包括用于快速响应的基础模式和用于全面分析的高级模式。它在提取干净内容和生成自动化答案摘要方面表现卓越，是任何构建自主研究工作流或数据收集智能体的开发者的必备组件。

下载入口:https://github.com/openclaw/skills/tree/main/skills/bert-builder/tavily

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install tavily

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 tavily。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Tavily AI 搜索 应用场景

• 对量子计算或软件架构等复杂技术主题进行全面研究。
• 使用具有时效性的新闻主题过滤器追踪时事和突发新闻。
• 将搜索限制在权威文档或学术领域，如 GitHub、arXiv 或官方项目站点。
• 提取原始 HTML 内容，用于深入的情感分析或自定义数据抓取项目。
• 生成搜索结果的快速合成摘要，无需手动浏览即可提供即时回答。

Tavily AI 搜索 工作原理

1. AI 智能体通过 Openclaw Skills 界面发起查询，指定搜索深度和主题焦点等参数。
2. 该技能应用域名过滤器来包含或排除特定网站，确保高信噪比。
3. Tavily API 执行搜索，根据用户要求抓取网页或特定新闻来源。
4. 解析搜索结果以提取干净的文本片段、相关性评分以及可选的原始 HTML 或图像。
5. 如果有要求，AI 模型会将发现的结果合成为简明扼要的答案摘要。
6. 最终的结构化负载将返回给智能体，为其提供基于事实的真实世界信息。

Tavily AI 搜索 配置指南

要将此搜索功能集成到您的 Openclaw Skills 工作流中，请遵循以下安装步骤：

1. 安装 Tavily Python SDK：

pip install tavily-python

2. 从 Tavily 控制面板获取 API 密钥并将其设置为环境变量：

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

3. 或者，将配置添加到您的智能体设置中：

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

Tavily AI 搜索 数据架构与分类体系

该技能将其输出组织成针对上下文窗口优化的结构化格式。这种结构是 Openclaw Skills 生态系统中质量的标志。

属性	描述
answer	搜索结果的合成摘要，用于快速理解。
results	包含标题、URL 和优化内容片段的数组。
score	表示每个结果质量的数值相关性评分 (0-1)。
raw_content	页面的完整 HTML 内容（如果要求进行深度分析）。
images	搜索过程中发现的相关视觉内容的 URL 列表。

name: tavily
description: AI-optimized web search using Tavily Search API. Use when you need comprehensive web research, current events lookup, domain-specific search, or AI-generated answer summaries. Tavily is optimized for LLM consumption with clean structured results, answer generation, and raw content extraction. Best for research tasks, news queries, fact-checking, and gathering authoritative sources.

Tavily AI Search

Overview

Tavily is a search engine specifically optimized for Large Language Models and AI applications. Unlike traditional search APIs, Tavily provides AI-ready results with optional answer generation, clean content extraction, and domain filtering capabilities.

Key capabilities:

• AI-generated answer summaries from search results
• Clean, structured results optimized for LLM processing
• Fast (basic) and comprehensive (advanced) search modes
• Domain filtering (include/exclude specific sources)
• News-focused search for current events
• Image search with relevant visual content
• Raw content extraction for deeper analysis

Architecture

graph TB
    A[User Query] --> B{Search Mode}
    B -->|basic| C[Fast Search<br/>1-2s response]
    B -->|advanced| D[Comprehensive Search<br/>5-10s response]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{Topic Filter}
    F -->|general| G[Broad Web Search]
    F -->|news| H[News Sources<br/>Last 7 days]
    
    G --> I[Domain Filtering]
    H --> I
    
    I --> J{Include Domains?}
    J -->|yes| K[Filter to Specific Domains]
    J -->|no| L{Exclude Domains?}
    K --> M[Search Results]
    L -->|yes| N[Remove Unwanted Domains]
    L -->|no| M
    N --> M
    
    M --> O{Response Options}
    O --> P[AI Answer<br/>Summary]
    O --> Q[Structured Results<br/>Title, URL, Content, Score]
    O --> R[Images<br/>if requested]
    O --> S[Raw HTML Content<br/>if requested]
    
    P --> T[Return to Agent]
    Q --> T
    R --> T
    S --> T
    
    style E fill:#4A90E2
    style P fill:#7ED321
    style Q fill:#7ED321
    style R fill:#F5A623
    style S fill:#F5A623

Quick Start

Basic Search

# Simple query with AI answer
scripts/tavily_search.py "What is quantum computing?"

# Multiple results
scripts/tavily_search.py "Python best practices" --max-results 10

Advanced Search

# Comprehensive research mode
scripts/tavily_search.py "Climate change solutions" --depth advanced

# News-focused search
scripts/tavily_search.py "AI developments 2026" --topic news

Domain Filtering

# Search only trusted domains
scripts/tavily_search.py "Python tutorials" r
  --include-domains python.org docs.python.org realpython.com

# Exclude low-quality sources
scripts/tavily_search.py "How to code" r
  --exclude-domains w3schools.com geeksforgeeks.org

With Images

# Include relevant images
scripts/tavily_search.py "Eiffel Tower architecture" --images

Search Modes

Basic vs Advanced

Decision tree:

1. Need a quick fact or definition? → Use basic
2. Researching a complex topic? → Use advanced
3. Need multiple perspectives? → Use advanced
4. Time-sensitive query? → Use basic

General vs News

Decision tree:

1. Query contains "latest", "recent", "current", "today"? → Use news
2. Looking for historical or evergreen content? → Use general
3. Need up-to-date information? → Use news

API Key Setup

Option 1: Clawdbot Config (Recommended)

Add to your Clawdbot config:

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

Access in scripts via Clawdbot's config system.

Option 2: Environment Variable

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

Add to ~/.clawdbot/.env or your shell profile.

Getting an API Key

1. Visit https://tavily.com
2. Sign up for an account
3. Navigate to your dashboard
4. Generate an API key (starts with tvly-)
5. Note your plan's rate limits and credit allocation

Common Use Cases

1. Research & Fact-Finding

# Comprehensive research with answer
scripts/tavily_search.py "Explain quantum entanglement" --depth advanced

# Multiple authoritative sources
scripts/tavily_search.py "Best practices for REST API design" r
  --max-results 10 r
  --include-domains github.com microsoft.com google.com

2. Current Events

# Latest news
scripts/tavily_search.py "AI policy updates" --topic news

# Recent developments in a field
scripts/tavily_search.py "quantum computing breakthroughs" r
  --topic news r
  --depth advanced

3. Domain-Specific Research

# Academic sources only
scripts/tavily_search.py "machine learning algorithms" r
  --include-domains arxiv.org scholar.google.com ieee.org

# Technical documentation
scripts/tavily_search.py "React hooks guide" r
  --include-domains react.dev

4. Visual Research

# Gather visual references
scripts/tavily_search.py "modern web design trends" r
  --images r
  --max-results 10

5. Content Extraction

# Get raw HTML content for deeper analysis
scripts/tavily_search.py "Python async/await" r
  --raw-content r
  --max-results 5

Response Handling

AI Answer

The AI-generated answer provides a concise summary synthesized from search results:

{
  "answer": "Quantum computing is a type of computing that uses quantum-mechanical phenomena..."
}

Use when:

• Need a quick summary
• Want synthesized information from multiple sources
• Looking for a direct answer to a question

Skip when (--no-answer):

• Only need source URLs
• Want to form your own synthesis
• Conserving API credits

Structured Results

Each result includes:

• title: Page title
• url: Source URL
• content: Extracted text snippet
• score: Relevance score (0-1)
• raw_content: Full HTML (if --raw-content enabled)

Images

When --images is enabled, returns URLs of relevant images found during search.

Best Practices

1. Choose the Right Search Depth

• Start with basic for most queries (faster, cheaper)
• Escalate to advanced only when:
  • Initial results are insufficient
  • Topic is complex or nuanced
  • Need comprehensive coverage

2. Use Domain Filtering Strategically

Include domains for:

• Academic research (.edu domains)
• Official documentation (official project sites)
• Trusted news sources
• Known authoritative sources

Exclude domains for:

• Known low-quality content farms
• Irrelevant content types (Pinterest for non-visual queries)
• Sites with paywalls or access restrictions

3. Optimize for Cost

• Use basic depth as default
• Limit max_results to what you'll actually use
• Disable include_raw_content unless needed
• Cache results locally for repeated queries

4. Handle Errors Gracefully

The script provides helpful error messages:

# Missing API key
Error: Tavily API key required
Setup: Set TAVILY_API_KEY environment variable or pass --api-key

# Package not installed
Error: tavily-python package not installed
To install: pip install tavily-python

Integration Patterns

Programmatic Usage

from tavily_search import search

result = search(
    query="What is machine learning?",
    api_key="tvly-...",
    search_depth="advanced",
    max_results=10
)

if result.get("success"):
    print(result["answer"])
    for item in result["results"]:
        print(f"{item['title']}: {item['url']}")

JSON Output for Parsing

scripts/tavily_search.py "Python tutorials" --json > results.json

Chaining with Other Tools

# Search and extract content
scripts/tavily_search.py "React documentation" --json | r
  jq -r '.results[].url' | r
  xargs -I {} curl -s {}

Comparison with Other Search APIs

vs Brave Search:

• ? AI answer generation
• ? Raw content extraction
• ? Better domain filtering
• ? Slower than Brave
• ? Costs credits

vs Perplexity:

• ? More control over sources
• ? Raw content available
• ? Dedicated news mode
• ≈ Similar answer quality
• ≈ Similar speed

vs Google Custom Search:

• ? LLM-optimized results
• ? Answer generation
• ? Simpler API
• ? Smaller index
• ≈ Similar cost structure

Troubleshooting

Script Won't Run

# Make executable
chmod +x scripts/tavily_search.py

# Check Python version (requires 3.6+)
python3 --version

# Install dependencies
pip install tavily-python

API Key Issues

# Verify API key format (should start with tvly-)
echo $TAVILY_API_KEY

# Test with explicit key
scripts/tavily_search.py "test" --api-key "tvly-..."

Rate Limit Errors

• Check your plan's credit allocation at https://tavily.com
• Reduce max_results to conserve credits
• Use basic depth instead of advanced
• Implement local caching for repeated queries

Resources

See api-reference.md for:

• Complete API parameter documentation
• Response format specifications
• Error handling details
• Cost and rate limit information
• Advanced usage examples

Dependencies

• Python 3.6+
• tavily-python package (install: pip install tavily-python)
• Valid Tavily API key

Credits & Attribution

• Tavily API: https://tavily.com
• Python SDK: https://github.com/tavily-ai/tavily-python
• Documentation: https://docs.tavily.com