Tavily Search and Extract Tools

Tavily is a search API built for AI applications. OpenClaw makes it available through two interfaces:

the web_search provider within the generic search tool
dedicated plugin tools: tavily_search and tavily_extract

Tavily delivers structured results tailored for LLM consumption, offering adjustable search depth, topic filtering, domain restrictions, AI-generated answer summaries, and URL content extraction (including JavaScript-rendered pages).

Property	Value
Plugin id	`tavily`
Package	`@openclaw/tavily-plugin`
Auth	`TAVILY_API_KEY` env var or config `apiKey`
Base URL	`https://api.tavily.com` (default); `TAVILY_BASE_URL` env var or config `baseUrl` to override
Timeouts	30s search, 60s extract (default)
Tools	`tavily_search`, `tavily_extract`

Getting started

Install the plugin

openclaw plugins install @openclaw/tavily-plugin

Get an API key

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

Verify search runs

Run a web_search from any agent, or invoke tavily_search directly.

Tip

Selecting Tavily during onboarding or in openclaw configure --section web installs and activates the official Tavily plugin as needed.

Tool reference

`tavily_search`

Use this when you need Tavily-specific search controls rather than the generic web_search.

Parameter	Type	Constraints / default	Description
`query`	string	required	Search query string.
`search_depth`	enum	`basic` (default), `advanced`	`advanced` is slower but higher relevance.
`topic`	enum	`general` (default), `news`, `finance`	Filter by topic family.
`max_results`	integer	1-20, default `5`	Number of results.
`include_answer`	boolean	default `false`	Include a Tavily AI-generated answer summary.
`time_range`	enum	`day`, `week`, `month`, `year`	Filter results by recency.
`include_domains`	string array	(none)	Only include results from these domains.
`exclude_domains`	string array	(none)	Exclude results from these domains.

Search depth tradeoff:

Depth	Speed	Relevance	Best for
`basic`	Faster	High	General-purpose queries (default).
`advanced`	Slower	Highest	Precision research and fact-finding.

`tavily_extract`

Employ this to pull clean content from one or more URLs. It handles JavaScript-rendered pages and supports query-focused chunking for targeted extraction.

Parameter	Type	Constraints / default	Description
`urls`	string array	required, 1-20	URLs whose content should be extracted.
`query`	string	(optional)	Reorder extracted chunks based on relevance to this query.
`extract_depth`	enum	`basic` (default), `advanced`	Pick `advanced` for JavaScript-heavy pages, single-page apps, or dynamic tables.
`chunks_per_source`	integer	1-5; requires `query`	Number of chunks returned per URL. Fails if `query` is missing.
`include_images`	boolean	default `false`	Whether to include image URLs in the output.

Extract depth tradeoff:

Depth	When to use
`basic`	Simple pages. Start here.
`advanced`	JS-rendered SPAs, dynamic content, tables.

Tip

Split large URL batches across several tavily_extract calls (20 per request max). Combine query with chunks_per_source to pull only relevant content instead of entire pages.

Choosing the right tool

Need	Tool
Quick web search, no special options	`web_search`
Search with depth, topic, AI answers	`tavily_search`
Extract content from specific URLs	`tavily_extract`

Note

The generic web_search tool using Tavily as its provider supports query and count (up to 20 results). For Tavily-specific parameters (search_depth, topic, include_answer, domain filters, time range), go with tavily_search instead.

Advanced configuration

API key resolution order

The Tavily client checks for an API key in this sequence:

plugins.entries.tavily.config.webSearch.apiKey (resolved via SecretRefs).
TAVILY_API_KEY from the gateway environment.

If neither is available, both tavily_search and tavily_extract raise a setup error.

Custom base URL

Override plugins.entries.tavily.config.webSearch.baseUrl, or configure TAVILY_BASE_URL, when routing Tavily through a proxy. The config value takes precedence over the environment variable. The fallback is https://api.tavily.com.

`chunks_per_source` requires `query`

tavily_extract rejects requests that supply chunks_per_source without a query. Tavily orders chunks by relevance to the query, so the parameter has no purpose 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.