ContextQMD
Back to Openclaw

Tavily

docs/tools/tavily.md

2026.5.54.5 KB
Original Source

OpenClaw can use Tavily in two ways:

  • as the web_search provider
  • as explicit plugin tools: tavily_search and tavily_extract

Tavily is a search API designed for AI applications, returning structured results optimized for LLM consumption. It supports configurable search depth, topic filtering, domain filters, AI-generated answer summaries, and content extraction from URLs (including JavaScript-rendered pages).

Get an API key

  1. Create a Tavily account at tavily.com.
  2. Generate an API key in the dashboard.
  3. Store it in config or set TAVILY_API_KEY in the gateway environment.
json5
{
  plugins: {
    entries: {
      tavily: {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "tvly-...", // optional if TAVILY_API_KEY is set
            baseUrl: "https://api.tavily.com",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "tavily",
      },
    },
  },
}

Notes:

  • Choosing Tavily in onboarding or openclaw configure --section web enables the bundled Tavily plugin automatically.
  • Store Tavily config under plugins.entries.tavily.config.webSearch.*.
  • web_search with Tavily supports query and count (up to 20 results).
  • For Tavily-specific controls like search_depth, topic, include_answer, or domain filters, use tavily_search.

Tavily plugin tools

Use this when you want Tavily-specific search controls instead of generic web_search.

ParameterDescription
querySearch query string (keep under 400 characters)
search_depthbasic (default, balanced) or advanced (highest relevance, slower)
topicgeneral (default), news (real-time updates), or finance
max_resultsNumber of results, 1-20 (default: 5)
include_answerInclude an AI-generated answer summary (default: false)
time_rangeFilter by recency: day, week, month, or year
include_domainsArray of domains to restrict results to
exclude_domainsArray of domains to exclude from results

Search depth:

DepthSpeedRelevanceBest for
basicFasterHighGeneral-purpose queries (default)
advancedSlowerHighestPrecision, specific facts, research

tavily_extract

Use this to extract clean content from one or more URLs. Handles JavaScript-rendered pages and supports query-focused chunking for targeted extraction.

ParameterDescription
urlsArray of URLs to extract (1-20 per request)
queryRerank extracted chunks by relevance to this query
extract_depthbasic (default, fast) or advanced (for JS-heavy pages)
chunks_per_sourceChunks per URL, 1-5 (requires query)
include_imagesInclude image URLs in results (default: false)

Extract depth:

DepthWhen to use
basicSimple pages - try this first
advancedJS-rendered SPAs, dynamic content, tables

Tips:

  • Max 20 URLs per request. Batch larger lists into multiple calls.
  • Use query + chunks_per_source to get only relevant content instead of full pages.
  • Try basic first; fall back to advanced if content is missing or incomplete.

Choosing the right tool

NeedTool
Quick web search, no special optionsweb_search
Search with depth, topic, AI answerstavily_search
Extract content from specific URLstavily_extract