Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Tavily is a search API designed for AI applications. OpenClaw exposes it in two ways:
  • as the web_search provider for the generic search tool
  • as explicit plugin tools: tavily_search and tavily_extract
Tavily returns structured results optimized for LLM consumption with configurable search depth, topic filtering, domain filters, AI-generated answer summaries, and content extraction from URLs (including JavaScript-rendered pages).
PropertyValue
Plugin idtavily
AuthTAVILY_API_KEY or config apiKey
Base URLhttps://api.tavily.com (default)
Bundled toolstavily_search, tavily_extract

​
Getting started

1

Get an API key

Create a Tavily account at tavily.com, then generate an API key in the dashboard.
2

Configure the plugin and provider

{
  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",
      },
    },
  },
}
3

Verify search runs

Trigger a web_search from any agent, or call tavily_search directly.
Choosing Tavily in onboarding or openclaw configure --section web enables the bundled Tavily plugin automatically.

​
Tool reference

Use this when you want Tavily-specific search controls instead of generic web_search.
ParameterTypeConstraints / defaultDescription
querystringrequiredSearch query string. Keep under 400 characters.
search_depthenumbasic (default), advancedadvanced is slower but higher relevance.
topicenumgeneral (default), news, financeFilter by topic family.
max_resultsinteger1-20Number of results.
include_answerbooleandefault falseInclude a Tavily AI-generated answer summary.
time_rangeenumday, week, month, yearFilter results by recency.
include_domainsstring array(none)Only include results from these domains.
exclude_domainsstring array(none)Exclude results from these domains.
Search depth tradeoff:
DepthSpeedRelevanceBest for
basicFasterHighGeneral-purpose queries (default).
advancedSlowerHighestPrecision research and fact-finding.

​
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.
ParameterTypeConstraints / defaultDescription
urlsstring arrayrequired, 1-20URLs to extract content from.
querystring(optional)Rerank extracted chunks by relevance to this query.
extract_depthenumbasic (default), advancedUse advanced for JS-heavy pages, SPAs, or dynamic tables.
chunks_per_sourceinteger1-5; requires queryChunks returned per URL. Errors if set without query.
include_imagesbooleandefault falseInclude image URLs in results.
Extract depth tradeoff:
DepthWhen to use
basicSimple pages. Try this first.
advancedJS-rendered SPAs, dynamic content, tables.
Batch larger URL lists into multiple tavily_extract calls (max 20 per request). Use query plus chunks_per_source to get only relevant content instead of full pages.

​
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
The generic web_search tool with Tavily as provider supports query and count (up to 20 results). For Tavily-specific controls (search_depth, topic, include_answer, domain filters, time range), use tavily_search instead.

​
Advanced configuration

The Tavily client looks up its API key in this order:
  1. plugins.entries.tavily.config.webSearch.apiKey (resolved through SecretRefs).
  2. TAVILY_API_KEY from the gateway environment.
tavily_extract raises a setup error if neither is present.
Override plugins.entries.tavily.config.webSearch.baseUrl if you front Tavily through a proxy. The default is https://api.tavily.com.
tavily_extract rejects calls that pass chunks_per_source without a query. Tavily ranks chunks by query relevance, so the parameter is meaningless without one.

Web Search overview

All providers and auto-detection rules.

Firecrawl

Search plus scraping with content extraction.

Exa Search

Neural search with content extraction.

Configuration

Full config schema for plugin entries and tool routing.