How to Connect Tavily Search to Your OpenClaw Agent

Brave Search averages 669 ms latency per call in OpenClaw benchmarks, while Tavily comes in at 998 ms. Brave also scores higher on raw agent benchmarks, roughly 14.89 versus 13.67. So why would you pick the slower option?

Because latency and benchmark scores measure the wrong thing for research-heavy agents. Tavily is an AI-native search API built specifically for agent workflows, returning structured results optimized for LLM consumption rather than raw HTML pages. When an agent needs to compare three APIs based on developer feedback, track company positioning changes over time, or synthesize information across multiple sources, the quality of what comes back matters more than how fast the first byte arrives.

Generic search APIs return snippets and URLs. The agent then has to fetch each page, parse the HTML, extract the relevant content, and hope the page hasn't changed since the snippet was generated. Tavily collapses that into one call: you get clean JSON with extracted content, optional answer summaries, and domain filtering built in. For a five-step research task, that difference compounds. Fewer intermediate fetches means fewer failure points, less token spend on HTML parsing, and more consistent results across runs.

Tavily is one of nine API-backed search providers in OpenClaw. It ranks at auto-detection priority order 70, which places it seventh in the fallback chain, after Brave, Gemini, Grok, Kimi, Perplexity, and Firecrawl, but ahead of Exa and DuckDuckGo. That order only matters if you let OpenClaw auto-detect. Most developers set a specific provider in their config file and skip the detection entirely.

OpenClaw supports Tavily as a first-party search plugin. No extra packages to install, no MCP servers to run. You need a Tavily API key and a few lines of config.

Get your API key

Sign up at app.tavily.com. The free tier gives you 1,000 API credits per month with no credit card required. Basic searches cost 1 credit each. Advanced searches cost 2 credits. Paid plans start at $30 per month for the Researcher tier, or $0.008 per credit on pay-as-you-go once you exceed your plan's limit.

Option 1: Environment variable

The fast path. Set the variable and OpenClaw detects Tavily automatically:

export TAVILY_API_KEY="tvly-YOUR_API_KEY"

To persist the key across sessions, add the export line to your shell profile (.bashrc, .zshrc, or equivalent). OpenClaw reads standard environment variables at startup, so any method that makes the variable available before launch works.

Option 2: Config file

For more control, add a Tavily plugin entry to your OpenClaw configuration file. The OpenClaw web tools docs describe the exact config structure:

{
  "plugins": {
    "entries": {
      "tavily": {
        "enabled": true,
        "config": {
          "webSearch": {
            "apiKey": "tvly-YOUR_API_KEY"
          }
        }
      }
    }
  },
  "tools": {
    "web": {
      "search": {
        "provider": "tavily"
      }
    }
  }
}

Setting "provider": "tavily" in the tools.web.search block bypasses auto-detection entirely. Your agent always uses Tavily, regardless of what other API keys you have configured.

Option 3: Interactive CLI

Run openclaw configure --section web and select Tavily when prompted. This writes the same config file for you.

Verify it works

Launch OpenClaw and run a test query. You should see Tavily attribution in the search results. If the key is missing or invalid, OpenClaw falls back to the next available provider in its detection chain.

The native plugin covers web_search with basic query and count parameters. If you need Tavily's full feature set, including crawling, URL extraction, and usage tracking, Composio's MCP integration exposes five Tavily tools instead of one.

What Composio adds

Composio is a tool platform that wraps third-party APIs as MCP servers. Its Tavily integration exposes:

• Tavily Search: web search with filters for topic, domain inclusion/exclusion, and search depth
• Tavily Extract: parse and extract content from specific URLs
• Tavily Crawl: graph-based website crawling for deeper research
• Tavily Map Website: discover all pages on a domain
• Get Tavily Usage: check your API credit consumption

Installation

Install the Composio plugin for OpenClaw:

openclaw plugins install @composio/openclaw-plugin

Get your consumer key from dashboard.composio.dev, then configure it:

openclaw config set plugins.entries.composio.config.consumerKey "ck_your_key_here"

Restart the gateway to pick up the new plugin:

openclaw gateway restart

Configuration in JSON

If you prefer editing the config file directly:

{
  "plugins": {
    "entries": {
      "composio": {
        "enabled": true,
        "config": {
          "consumerKey": "ck_your_key_here"
        }
      }
    }
  }
}

The Composio plugin connects to its MCP server at https://connect.composio.dev/mcp. Once authenticated, you can use Tavily tools from any OpenClaw interface: the TUI, Telegram, WhatsApp, or the web dashboard.

When to use which path

The native plugin is simpler and cheaper. You deal with one API key and one config block. If your agent's search needs are straightforward, query-in, results-out, the native plugin is the right choice.

The Composio path makes sense when your agent does multi-step research: crawling entire domains, extracting specific content from known URLs, or monitoring credit usage programmatically. The tradeoff is an additional dependency (Composio account and plugin) and a second authentication layer.

Give your research agent persistent memory

Store Tavily search outputs in an indexed workspace your whole team can query. 50 GB free, no credit card, MCP endpoint ready for your OpenClaw agent.

Sign Up Free

Once Tavily is configured, OpenClaw exposes it through three different tool interfaces. Each serves a different depth of search.

web_search (provider mode)

This is the generic OpenClaw search tool that routes through whichever provider you've configured. With Tavily, it supports two parameters:

• query (required): your search terms
• count (1 to 10, default 5): number of results

That's it. Country, language, and freshness filters are not available through web_search when Tavily is the backend. The OpenClaw docs are explicit about this: "Firecrawl and Tavily only support query and count through web_search." If you need those filters, use the dedicated tools below.

tavily_search (dedicated tool)

This tool exposes Tavily's full search API. Parameters include:

• search_depth: basic or advanced (advanced costs 2 credits instead of 1)
• topic: filter by content category
• max_results: control result count
• time_range: freshness filter for recent content
• include_domains / exclude_domains: scope searches to specific sites
• include_answer: get a synthesized answer alongside raw results

The include_answer parameter is particularly useful for agents that need a quick factual response without parsing multiple results. Tavily generates a short answer from the search results and returns it alongside the full result set.

tavily_extract (content extraction)

Not a search tool, but worth knowing about. Pass one or more URLs and get back clean, structured content. Parameters include:

• urls: one or more pages to extract from
• query: optional context to guide extraction
• extract_depth: how deep to parse
• chunks_per_source: control output granularity
• include_images: whether to capture image references

The practical workflow: use tavily_search to find relevant pages, then tavily_extract on the top results to get full article content for deeper analysis. This two-step pattern replaces the fetch-parse-extract cycle that agents typically do manually.

Both providers ship with OpenClaw and both have free tiers of 1,000 monthly requests. The choice depends on what your agent actually does.

Pick Brave when:

• Speed matters more than depth. Brave's 669 ms average latency is about 33% faster than Tavily's 998 ms.
• Your agent does general discovery, news monitoring, or simple fact lookups.
• You want the default. Brave sits at priority order 10 in OpenClaw's auto-detection, so it's the first API provider checked.
• Budget is tight. Brave costs roughly $5 per 1,000 requests versus Tavily's $8.

Pick Tavily when:

• Your agent does multi-step research that requires synthesizing information from multiple sources.
• You need structured JSON responses with extracted content, not just snippets and links.
• Domain filtering matters. Tavily's dedicated search tool lets you scope results to specific sites or exclude others.
• You want optional answer generation. The include_answer parameter saves your agent from having to synthesize its own summary from raw results.

Use both

Some developers pair providers. Brave handles fast discovery and link gathering, Tavily handles deep content extraction on the most promising results. You can switch providers per query by using dedicated tools (brave_search or tavily_search) instead of the generic web_search tool.

A practical pattern: use Brave's web_search for initial topic scanning, then pass the top URLs to tavily_extract for full content. This gives you Brave's speed for the broad sweep and Tavily's structured output for the deep read.

For persistent research output, both providers integrate the same way with external storage. Your agent runs the search, processes the results, and needs somewhere to put the synthesis. Local filesystems work for single-session experiments. For agents that run continuously, hand off results to other agents, or need to share research with humans, a persistent workspace layer makes more sense.

Fast.io provides that layer with a free agent tier: 50 GB of storage, 5,000 monthly credits, five workspaces, and MCP access at /storage-for-agents/. Your OpenClaw agent writes research outputs to a Fast.io workspace via MCP, and anyone on the team can access the results through the web UI or API. No local file juggling, no manual syncing.

"No search provider found" error

OpenClaw checks providers in auto-detection order and uses the first one with a valid API key. If you see this error, your TAVILY_API_KEY environment variable isn't being picked up. Check for typos, make sure the variable is exported (not just set), and verify the key starts with tvly-.

Search returns empty results

Tavily's web_search integration supports only query and count. If you're passing country, language, or freshness parameters through web_search, they're silently ignored. Switch to tavily_search for those filters.

Credit exhaustion

The free tier provides 1,000 credits per month. Basic searches cost 1 credit, advanced searches cost 2. If you hit the limit, Tavily returns an error rather than degraded results. You can check remaining credits with the get_tavily_usage tool (available through the Composio integration) or on the Tavily dashboard.

Composio plugin not loading

After installing @composio/openclaw-plugin, you must restart the gateway with openclaw gateway restart. The plugin won't activate on a config reload alone. Also verify your consumer key format, it should start with ck_.

Mixing native and Composio configs

You can use both paths simultaneously. The native Tavily plugin handles web_search routing, while the Composio plugin provides the five dedicated Tavily tools. They use separate authentication (Tavily API key vs. Composio consumer key) and don't conflict. Just make sure both keys are valid.

Rate limiting

Tavily's free tier doesn't publish explicit rate limits beyond the monthly credit cap. If you're running high-volume agent workflows, the Researcher plan at $30 per month or pay-as-you-go at $0.008 per credit gives you headroom without hard cutoffs.

For agents that run research tasks continuously, consider storing intermediate results in a persistent workspace rather than re-running the same searches. Fast.io's Intelligence Mode auto-indexes uploaded files, so your agent can search its own prior research without burning additional Tavily credits. Upload a batch of research outputs, enable Intelligence on the workspace, and subsequent queries hit the indexed content instead of making fresh API calls.