Tavily

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).

Property	Value
Plugin id	tavily
Auth	TAVILY_API_KEY or config apiKey
Base URL	https://api.tavily.com (default)
Bundled tools	tavily_search, tavily_extract

Getting started

<Steps> <Step title="Get an API key"> Create a Tavily account at [tavily.com](https://tavily.com), then generate an API key in the dashboard. </Step> <Step title="Configure the plugin and provider"> ```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", }, }, }, } ``` </Step> <Step title="Verify search runs"> Trigger a `web_search` from any agent, or call `tavily_search` directly. </Step> </Steps> <Tip> Choosing Tavily in onboarding or `openclaw configure --section web` enables the bundled Tavily plugin automatically. </Tip>

Tool reference

tavily_search

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

Parameter	Type	Constraints / default	Description
query	string	required	Search query string. Keep under 400 characters.
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	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

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

Parameter	Type	Constraints / default	Description
urls	string array	required, 1-20	URLs to extract content from.
query	string	(optional)	Rerank extracted chunks by relevance to this query.
extract_depth	enum	basic (default), advanced	Use advanced for JS-heavy pages, SPAs, or dynamic tables.
chunks_per_source	integer	1-5; requires query	Chunks returned per URL. Errors if set without query.
include_images	boolean	default false	Include image URLs in results.

Extract depth tradeoff:

Depth	When to use
basic	Simple pages. Try this first.
advanced	JS-rendered SPAs, dynamic content, tables.

<Tip> 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. </Tip>

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 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. </Note>

Advanced configuration

<AccordionGroup> <Accordion title="API key resolution order"> The Tavily client looks up its API key in this order: </Accordion> <Accordion title="Custom base URL"> Override `plugins.entries.tavily.config.webSearch.baseUrl` if you front Tavily through a proxy. The default is `https://api.tavily.com`. </Accordion> <Accordion title="`chunks_per_source` requires `query`"> `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. </Accordion> </AccordionGroup>

Related

<CardGroup cols={2}> <Card title="Web Search overview" href="/tools/web" icon="magnifying-glass"> All providers and auto-detection rules. </Card> <Card title="Firecrawl" href="/tools/firecrawl" icon="fire"> Search plus scraping with content extraction. </Card> <Card title="Exa Search" href="/tools/exa-search" icon="binoculars"> Neural search with content extraction. </Card> <Card title="Configuration" href="/gateway/configuration" icon="gear"> Full config schema for plugin entries and tool routing. </Card> </CardGroup>