openclaw-tavily

A Tavily web tools plugin for OpenClaw.

Exposes five agent tools:

| Tool | Description | |------|-------------| | tavily_search | Web search with structured results, AI answers, domain filtering | | tavily_extract | Extract clean markdown/text content from URLs | | tavily_crawl | Crawl a website and extract content from discovered pages | | tavily_map | Discover and list all URLs from a website | | tavily_research | Deep agentic research returning comprehensive reports |

Install

openclaw plugins install openclaw-tavily

Or install from source:

git clone https://github.com/framix-team/openclaw-tavily.git ~/.openclaw/extensions/openclaw-tavily
cd ~/.openclaw/extensions/openclaw-tavily
npm install --omit=dev

Then restart the gateway.

Configuration

1. Set your Tavily API key

Get a key at app.tavily.com.

Either set the environment variable:

export TAVILY_API_KEY=tvly-...

Or configure it in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-tavily": {
        "enabled": true,
        "config": {
          "apiKey": "tvly-..."
        }
      }
    }
  }
}

2. Optional settings

| Key | Type | Default | Description | |-----|------|---------|-------------| | searchDepth | "basic" | "advanced" | "advanced" | Basic is faster/cheaper, advanced is more thorough | | maxResults | number (1-20) | 5 | Number of results per search | | includeAnswer | boolean | true | Include an AI-generated short answer | | includeRawContent | boolean | false | Include full page content (increases token usage) | | timeoutSeconds | number | 30 | Timeout for API requests | | cacheTtlMinutes | number | 15 | In-memory cache TTL (0 to disable) |

Tools

tavily_search

Search the web with structured results and optional AI-generated answers.

| Parameter | Required | Description | |-----------|----------|-------------| | query | yes | Search query string | | count | no | Number of results (1-20) | | search_depth | no | "ultra-fast", "fast", "basic", or "advanced" | | include_answer | no | Include AI answer (true/false/"basic"/"advanced") | | include_raw_content | no | Include raw page content (true/false/"markdown"/"text") | | topic | no | "general", "news", or "finance" | | time_range | no | "day", "week", "month", or "year" | | start_date | no | Start date (ISO format, e.g. "2024-01-01") | | end_date | no | End date (ISO format) | | include_domains | no | Limit to these domains | | exclude_domains | no | Exclude these domains | | chunks_per_source | no | Content chunks per source (1-3, advanced depth only) | | include_images | no | Include images in results | | include_image_descriptions | no | Include image descriptions | | include_favicon | no | Include favicon URLs | | country | no | Country code for geo-boosted results | | auto_parameters | no | Let Tavily optimize parameters automatically |

Example response:

{
  "query": "OpenClaw AI assistant",
  "provider": "tavily",
  "searchDepth": "advanced",
  "topic": "general",
  "count": 3,
  "tookMs": 1842,
  "answer": "OpenClaw is a personal AI assistant you run on your own devices...",
  "results": [
    {
      "title": "OpenClaw - Personal AI Assistant",
      "url": "https://openclaw.ai",
      "snippet": "...",
      "score": 0.98,
      "siteName": "openclaw.ai"
    }
  ]
}

tavily_extract

Extract and clean content from one or more URLs.

| Parameter | Required | Description | |-----------|----------|-------------| | urls | yes | Array of URLs to extract content from | | query | no | Rerank extracted chunks for relevance | | chunks_per_source | no | Max snippets per source | | format | no | "markdown" or "text" (default: "markdown") | | include_favicon | no | Include favicon URLs | | timeout | no | Max seconds before timeout |

Example response:

{
  "results": [
    {
      "url": "https://example.com/article",
      "raw_content": "# Article Title\n\nFull markdown content..."
    }
  ],
  "failed_results": [],
  "provider": "tavily",
  "tookMs": 1234
}

tavily_crawl

Crawl a website starting from a root URL, traversing links and extracting content.

| Parameter | Required | Description | |-----------|----------|-------------| | url | yes | Root URL to start crawling | | instructions | no | Natural language guidance for the crawl | | max_depth | no | Crawl depth (1-5) | | max_breadth | no | Max links per level (1-500) | | limit | no | Total URL cap | | select_paths | no | Regex include filters for paths | | select_domains | no | Regex include filters for domains | | exclude_paths | no | Regex exclude filters for paths | | exclude_domains | no | Regex exclude filters for domains | | allow_external | no | Follow external links | | include_images | no | Include images | | extract_depth | no | "basic" or "advanced" | | format | no | "markdown" or "text" | | include_favicon | no | Include favicons | | timeout | no | Timeout in seconds (10-150) |

Example response:

{
  "base_url": "https://example.com",
  "results": [
    {
      "url": "https://example.com/page1",
      "raw_content": "# Page Title\n\nContent..."
    },
    {
      "url": "https://example.com/page2",
      "raw_content": "# Another Page\n\nMore content..."
    }
  ],
  "provider": "tavily",
  "tookMs": 5678
}

tavily_map

Generate a site map — discover and list all URLs from a website.

| Parameter | Required | Description | |-----------|----------|-------------| | url | yes | URL to map | | instructions | no | Natural language guidance | | max_depth | no | Crawl depth (1-5) | | max_breadth | no | Links per level | | limit | no | Total URL cap | | select_paths | no | Include filters for paths | | select_domains | no | Include filters for domains | | exclude_paths | no | Exclude filters for paths | | exclude_domains | no | Exclude filters for domains | | allow_external | no | Follow external links | | categories | no | Category filters |

Example response:

{
  "results": [
    "https://example.com/",
    "https://example.com/about",
    "https://example.com/docs",
    "https://example.com/docs/getting-started",
    "https://example.com/pricing"
  ],
  "provider": "tavily",
  "tookMs": 2345
}

tavily_research

Run a deep agentic research task with a comprehensive report.

| Parameter | Required | Description | |-----------|----------|-------------| | input | yes | Research question or topic | | model | no | "mini", "pro", or "auto" (default: "auto") | | output_schema | no | JSON schema for structured output | | citation_format | no | "numbered", "mla", "apa", or "chicago" |

Example response:

{
  "output": "# Research Report\n\n## Overview\n\nComprehensive analysis of...",
  "sources": [
    {
      "title": "Source Article",
      "url": "https://example.com/research"
    }
  ],
  "provider": "tavily",
  "tookMs": 45000
}

Features

• In-memory cache — deduplicates identical search queries within the TTL window
• Domain filtering — include/exclude specific domains per search query
• News & finance search — topic + date range support
• AI answers — optional Tavily-generated summary alongside search results
• URL extraction — get clean markdown/text from any web page
• Website crawling — traverse and extract content from entire sites
• Site mapping — discover all URLs before targeted extraction
• Deep research — multi-step agentic research with comprehensive reports
• Graceful degradation — goes idle if no API key is configured

Requirements

• OpenClaw 2025+
• A Tavily API key (free tier available)

Links

• npm: openclaw-tavily
• GitHub: framix-team/openclaw-tavily
• Tavily API docs: docs.tavily.com
• OpenClaw plugin docs: docs.openclaw.ai/tools/plugin

Made by

Framix — Growth Web Presence for Scaling Companies

License

MIT