Tavily Search 🔎

AI-powered web search platform with 5 modes: Search, Extract, Crawl, Map, and Research.

Requirements

• - TAVILY_API_KEY environment variable

Configuration

Set in OpenClaw config:
CODEBLOCK0

Script Location

CODEBLOCK1

Commands

search — Web Search (Default)

General-purpose web search with optional LLM-synthesized answer.

CODEBLOCK2

Examples:
CODEBLOCK3

Output format (text):

Answer: <LLM-synthesized answer if --answer>

Results:
  1. Result Title
     https://example.com/article
     Content snippet from the page...

  2. Another Result
     https://example.com/other
     Another snippet...

news — News Search

Search optimized for news articles. Sets topic=news.

CODEBLOCK5

Examples:

python3 lib/tavily_search.py news "AI regulation"
python3 lib/tavily_search.py news "Israel tech" --time day --answer
python3 lib/tavily_search.py news "stock market" --time week -n 10

finance — Finance Search

Search optimized for financial data and news. Sets topic=finance.

CODEBLOCK7

Examples:

python3 lib/tavily_search.py finance "NVIDIA stock analysis"
python3 lib/tavily_search.py finance "cryptocurrency market trends" --time month
python3 lib/tavily_search.py finance "S&P 500 forecast 2026" --answer

extract — Extract Content from URLs

Extract readable content from one or more URLs.

CODEBLOCK9

Parameters:

• - urls: One or more URLs to extract (positional args)
• INLINECODE5: Extraction depth
• INLINECODE6: Output format (default: markdown)
• INLINECODE7: Rerank extracted chunks by relevance to query

Examples:
CODEBLOCK10

Output format:

URL: https://example.com/article
─────────────────────────────────
<Extracted content in markdown/text>

URL: https://another.com/page
─────────────────────────────────
<Extracted content>

crawl — Crawl a Website

Crawl a website starting from a root URL, following links.

CODEBLOCK12

Parameters:

• - url: Root URL to start crawling
• INLINECODE9: Crawl depth
• INLINECODE10: Maximum link depth to follow (default: 2)
• INLINECODE11: Maximum pages per depth level (default: 10)
• INLINECODE12: Maximum total pages (default: 10)
• INLINECODE13: Natural language crawl instructions
• INLINECODE14: Only crawl these path patterns
• INLINECODE15: Skip these path patterns
• INLINECODE16: Output format

Examples:
CODEBLOCK13

Output format:

Crawled 5 pages from https://docs.example.com

Page 1: https://docs.example.com/intro
─────────────────────────────────
<Content>

Page 2: https://docs.example.com/guide
─────────────────────────────────
<Content>

map — Sitemap Discovery

Discover all URLs on a website (sitemap).

CODEBLOCK15

Parameters:

• - url: Root URL to map
• INLINECODE18: Depth to follow (default: 2)
• INLINECODE19: Breadth per level (default: 20)
• INLINECODE20: Maximum URLs (default: 50)

Examples:
CODEBLOCK16

Output format:

Sitemap for https://example.com (42 URLs found):

  1. https://example.com/
  2. https://example.com/about
  3. https://example.com/blog
  ...

research — Deep Research

Comprehensive AI-powered research on a topic with citations.

CODEBLOCK18

Parameters:

• - query: Research question
• INLINECODE22: Research model (default: auto)

• - --json: JSON output (supports structured output schema)

Examples:
CODEBLOCK19

Output format:

Research: Impact of AI on healthcare in 2026

<Comprehensive research report with citations>

Sources:
  [1] https://source1.com
  [2] https://source2.com
  ...

Options Reference

Error Handling

• - Missing API key: Clear error message with setup instructions.
• 401 Unauthorized: Invalid API key.
• 429 Rate Limit: Rate limit exceeded, try again later.
• Network errors: Descriptive error with cause.
• No results: Clean "No results found." message.
• Timeout: 30-second timeout on all HTTP requests.

Credits & Pricing

Install

CODEBLOCK21