Tavily

기준일: 2026-07-26
난이도: 중급
공식 기준: Tavily

개요

이 페이지는 OpenClaw Tavily 도구(파라미터, 권한, 설정, CLI)를 공식 문서 기준으로 정리합니다.

공식 요약: Tavily search and extract tools

도구 가시성은 profile / allow·deny policy / sandbox / channel 권한에 따라 달라집니다. 최신 스키마는 항상 공식 문서를 우선합니다.

공식 문서 기반 상세

아래는 공식 tools/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
Package	@openclaw/tavily-plugin
Auth	TAVILY_API_KEY env var or config apiKey
Base URL	https://api.tavily.com (default); TAVILY_BASE_URL env var or config baseUrl to override
Timeouts	30s search, 60s extract (default)
Tools	tavily_search, tavily_extract

시작하기

Install the plugin

```bash
openclaw plugins install @openclaw/tavily-plugin
```

Get an API key

Create a Tavily account at [tavily.com](https://tavily.com), then generate an API key in the dashboard.

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",
      },
    },
  },
}
```

Verify search runs

Trigger a `web_search` from any agent, or call `tavily_search` directly.

Choosing Tavily in onboarding or openclaw configure --section web installs and enables the official Tavily plugin when needed.

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.
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, default 5	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.

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.

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

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.

고급 설정

API key resolution order

The Tavily client looks up its API key in this order:

1. `plugins.entries.tavily.config.webSearch.apiKey` (resolved through SecretRefs).
2. `TAVILY_API_KEY` from the gateway environment.

`tavily_search` and `tavily_extract` both raise a setup error if neither is present.

Custom base URL

Override `plugins.entries.tavily.config.webSearch.baseUrl`, or set `TAVILY_BASE_URL`, if you front Tavily through a proxy. Config takes priority over the env var. The default is `https://api.tavily.com`.

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.

관련 문서

All providers and auto-detection rules.


Search plus scraping with content extraction.


Neural search with content extraction.


Full config schema for plugin entries and tool routing.

검증 체크리스트

• 해당 tool이 활성 profile/policy에서 허용되는지 확인
• sandbox / elevated / host 실행 경로 정책을 이해했는지 확인
• 채널·에이전트 권한과 충돌하지 않는지 확인
• 공식 CLI/--help와 문서 옵션이 버전과 맞는지 확인

관련

• Tools 목록 인덱스
• 공식: Tools overview, Tools and custom providers