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: json { "env": { "TAVILY_API_KEY": "tvly-..." } }

Script Location

python3 skills/tavily/lib/tavily_search.py <command> "query" [options]

Commands

search — Web Search (Default)

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

python3 lib/tavily_search.py search "query" [options]

Examples: ```bash

Basic search

python3 lib/tavily_search.py search "latest AI news"

With LLM answer

python3 lib/tavily_search.py search "what is quantum computing" --answer

Advanced depth (better results, 2 credits)

python3 lib/tavily_search.py search "climate change solutions" --depth advanced

Time-filtered

python3 lib/tavily_search.py search "OpenAI announcements" --time week

Domain filtering

python3 lib/tavily_search.py search "machine learning" --include-domains arxiv.org,nature.com

Country boost

python3 lib/tavily_search.py search "tech startups" --country US

With raw content and images

python3 lib/tavily_search.py search "solar energy" --raw --images -n 10

JSON output

python3 lib/tavily_search.py search "bitcoin price" --json ```

Output format (text): ``` Answer:

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

1. Another Result https://example.com/other Another snippet... ```

news — News Search

Search optimized for news articles. Sets topic=news.

python3 lib/tavily_search.py news "query" [options]

Examples: bash 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.

python3 lib/tavily_search.py finance "query" [options]

Examples: bash 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.

python3 lib/tavily_search.py extract URL [URL...] [options]

Parameters: - urls: One or more URLs to extract (positional args) - --depth basic|advanced: Extraction depth - --format markdown|text: Output format (default: markdown) - --query "text": Rerank extracted chunks by relevance to query

Examples: ```bash

Extract single URL

python3 lib/tavily_search.py extract "https://example.com/article"

Extract multiple URLs

python3 lib/tavily_search.py extract "https://url1.com" "https://url2.com"

Advanced extraction with relevance reranking

python3 lib/tavily_search.py extract "https://arxiv.org/paper" --depth advanced --query "transformer architecture"

Text format output

python3 lib/tavily_search.py extract "https://example.com" --format text ```

Output format: ``` URL: https://example.com/article ─────────────────────────────────

URL: https://another.com/page ───────────────────────────────── ```

crawl — Crawl a Website

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

python3 lib/tavily_search.py crawl URL [options]

Parameters: - url: Root URL to start crawling - --depth basic|advanced: Crawl depth - --max-depth N: Maximum link depth to follow (default: 2) - --max-breadth N: Maximum pages per depth level (default: 10) - --limit N: Maximum total pages (default: 10) - --instructions "text": Natural language crawl instructions - --select-paths p1,p2: Only crawl these path patterns - --exclude-paths p1,p2: Skip these path patterns - --format markdown|text: Output format

Examples: ```bash

Basic crawl

python3 lib/tavily_search.py crawl "https://docs.example.com"

Focused crawl with instructions

python3 lib/tavily_search.py crawl "https://docs.python.org" --instructions "Find all asyncio documentation" --limit 20

Crawl specific paths only

python3 lib/tavily_search.py crawl "https://example.com" --select-paths "/blog,/docs" --max-depth 3 ```

Output format: ``` Crawled 5 pages from https://docs.example.com

Page 1: https://docs.example.com/intro ─────────────────────────────────

Page 2: https://docs.example.com/guide ───────────────────────────────── ```

map — Sitemap Discovery

Discover all URLs on a website (sitemap).

python3 lib/tavily_search.py map URL [options]

Parameters: - url: Root URL to map - --max-depth N: Depth to follow (default: 2) - --max-breadth N: Breadth per level (default: 20) - --limit N: Maximum URLs (default: 50)

Examples: ```bash

Map a site

python3 lib/tavily_search.py map "https://example.com"

Deep map

python3 lib/tavily_search.py map "https://docs.python.org" --max-depth 3 --limit 100 ```

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.

python3 lib/tavily_search.py research "query" [options]

Parameters: - query: Research question - --model mini|pro|auto: Research model (default: auto) - mini: Faster, cheaper - pro: More thorough - auto: Let Tavily decide - --json: JSON output (supports structured output schema)

Examples: ```bash

Basic research

python3 lib/tavily_search.py research "Impact of AI on healthcare in 2026"

Pro model for thorough research

python3 lib/tavily_search.py research "Comparison of quantum computing approaches" --model pro

JSON output

python3 lib/tavily_search.py research "Electric vehicle market analysis" --json ```

Output format: ``` Research: Impact of AI on healthcare in 2026

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

bash skills/tavily/install.sh