Skip to content

Commit b36e456

Browse files
lakshyaag-tavilygumadeiras
lakshyaag-tavily
and
gumadeiras
authored
feat: add Tavily as a bundled web search plugin with search and extract tools (#49200)
Merged via squash. Prepared head SHA: ece9226 Co-authored-by: lakshyaag-tavily <[email protected]> Co-authored-by: gumadeiras <[email protected]> Reviewed-by: @gumadeiras
1 parent 914fc26 commit b36e456

37 files changed

Lines changed: 1378 additions & 124 deletions

‎.github/labeler.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,10 @@
293293
- changed-files:
294294
- any-glob-to-any-file:
295295
- "extensions/synthetic/**"
296+
"extensions: tavily":
297+
- changed-files:
298+
- any-glob-to-any-file:
299+
- "extensions/tavily/**"
296300
"extensions: talk-voice":
297301
- changed-files:
298302
- any-glob-to-any-file:

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ Docs: https://docs.openclaw.ai
4747
- Plugins/Xiaomi: switch the bundled Xiaomi provider to the `/v1` OpenAI-compatible endpoint and add MiMo V2 Pro plus MiMo V2 Omni to the built-in catalog. (#49214) thanks @DJjjjhao.
4848
- Plugins/Matrix: add `allowBots` room policy so configured Matrix bot accounts can talk to each other, with optional mention-only gating. Thanks @gumadeiras.
4949
- Plugins/Matrix: add per-account `allowPrivateNetwork` opt-in for private/internal homeservers, while keeping public cleartext homeservers blocked. Thanks @gumadeiras.
50+
- Web tools/Tavily: add Tavily as a bundled web-search provider with dedicated `tavily_search` and `tavily_extract` tools, using canonical plugin-owned config under `plugins.entries.tavily.config.webSearch.*`. (#49200) thanks @lakshyaag-tavily.
5051

5152
### Fixes
5253

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1031,6 +1031,7 @@
10311031
"tools/exec",
10321032
"tools/exec-approvals",
10331033
"tools/firecrawl",
1034+
"tools/tavily",
10341035
"tools/llm-task",
10351036
"tools/lobster",
10361037
"tools/loop-detection",

‎docs/reference/secretref-credential-surface.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ Scope intent:
3838
- `plugins.entries.moonshot.config.webSearch.apiKey`
3939
- `plugins.entries.perplexity.config.webSearch.apiKey`
4040
- `plugins.entries.firecrawl.config.webSearch.apiKey`
41+
- `plugins.entries.tavily.config.webSearch.apiKey`
4142
- `tools.web.search.apiKey`
4243
- `tools.web.search.gemini.apiKey`
4344
- `tools.web.search.grok.apiKey`

‎docs/reference/secretref-user-supplied-credentials-matrix.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -551,6 +551,13 @@
551551
"path": "tools.web.search.perplexity.apiKey",
552552
"secretShape": "secret_input",
553553
"optIn": true
554+
},
555+
{
556+
"id": "plugins.entries.tavily.config.webSearch.apiKey",
557+
"configFile": "openclaw.json",
558+
"path": "plugins.entries.tavily.config.webSearch.apiKey",
559+
"secretShape": "secret_input",
560+
"optIn": true
554561
}
555562
]
556563
}

‎docs/tools/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,7 @@ Enable with `tools.loopDetection.enabled: true` (default is `false`).
256256

257257
### `web_search`
258258

259-
Search the web using Brave, Firecrawl, Gemini, Grok, Kimi, or Perplexity.
259+
Search the web using Brave, Firecrawl, Gemini, Grok, Kimi, Perplexity, or Tavily.
260260

261261
Core parameters:
262262

‎docs/tools/tavily.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
summary: "Tavily search and extract tools"
3+
read_when:
4+
- You want Tavily-backed web search
5+
- You need a Tavily API key
6+
- You want Tavily as a web_search provider
7+
- You want content extraction from URLs
8+
title: "Tavily"
9+
---
10+
11+
# Tavily
12+
13+
OpenClaw can use **Tavily** in two ways:
14+
15+
- as the `web_search` provider
16+
- as explicit plugin tools: `tavily_search` and `tavily_extract`
17+
18+
Tavily is a search API designed for AI applications, returning structured results
19+
optimized for LLM consumption. It supports configurable search depth, topic
20+
filtering, domain filters, AI-generated answer summaries, and content extraction
21+
from URLs (including JavaScript-rendered pages).
22+
23+
## Get an API key
24+
25+
1. Create a Tavily account at [tavily.com](https://tavily.com/).
26+
2. Generate an API key in the dashboard.
27+
3. Store it in config or set `TAVILY_API_KEY` in the gateway environment.
28+
29+
## Configure Tavily search
30+
31+
```json5
32+
{
33+
plugins: {
34+
entries: {
35+
tavily: {
36+
enabled: true,
37+
config: {
38+
webSearch: {
39+
apiKey: "tvly-...", // optional if TAVILY_API_KEY is set
40+
baseUrl: "https://api.tavily.com",
41+
},
42+
},
43+
},
44+
},
45+
},
46+
tools: {
47+
web: {
48+
search: {
49+
provider: "tavily",
50+
},
51+
},
52+
},
53+
}
54+
```
55+
56+
Notes:
57+
58+
- Choosing Tavily in onboarding or `openclaw configure --section web` enables
59+
the bundled Tavily plugin automatically.
60+
- Store Tavily config under `plugins.entries.tavily.config.webSearch.*`.
61+
- `web_search` with Tavily supports `query` and `count` (up to 20 results).
62+
- For Tavily-specific controls like `search_depth`, `topic`, `include_answer`,
63+
or domain filters, use `tavily_search`.
64+
65+
## Tavily plugin tools
66+
67+
### `tavily_search`
68+
69+
Use this when you want Tavily-specific search controls instead of generic
70+
`web_search`.
71+
72+
| Parameter | Description |
73+
| ----------------- | --------------------------------------------------------------------- |
74+
| `query` | Search query string (keep under 400 characters) |
75+
| `search_depth` | `basic` (default, balanced) or `advanced` (highest relevance, slower) |
76+
| `topic` | `general` (default), `news` (real-time updates), or `finance` |
77+
| `max_results` | Number of results, 1-20 (default: 5) |
78+
| `include_answer` | Include an AI-generated answer summary (default: false) |
79+
| `time_range` | Filter by recency: `day`, `week`, `month`, or `year` |
80+
| `include_domains` | Array of domains to restrict results to |
81+
| `exclude_domains` | Array of domains to exclude from results |
82+
83+
**Search depth:**
84+
85+
| Depth | Speed | Relevance | Best for |
86+
| ---------- | ------ | --------- | ----------------------------------- |
87+
| `basic` | Faster | High | General-purpose queries (default) |
88+
| `advanced` | Slower | Highest | Precision, specific facts, research |
89+
90+
### `tavily_extract`
91+
92+
Use this to extract clean content from one or more URLs. Handles
93+
JavaScript-rendered pages and supports query-focused chunking for targeted
94+
extraction.
95+
96+
| Parameter | Description |
97+
| ------------------- | ---------------------------------------------------------- |
98+
| `urls` | Array of URLs to extract (1-20 per request) |
99+
| `query` | Rerank extracted chunks by relevance to this query |
100+
| `extract_depth` | `basic` (default, fast) or `advanced` (for JS-heavy pages) |
101+
| `chunks_per_source` | Chunks per URL, 1-5 (requires `query`) |
102+
| `include_images` | Include image URLs in results (default: false) |
103+
104+
**Extract depth:**
105+
106+
| Depth | When to use |
107+
| ---------- | ----------------------------------------- |
108+
| `basic` | Simple pages - try this first |
109+
| `advanced` | JS-rendered SPAs, dynamic content, tables |
110+
111+
Tips:
112+
113+
- Max 20 URLs per request. Batch larger lists into multiple calls.
114+
- Use `query` + `chunks_per_source` to get only relevant content instead of full pages.
115+
- Try `basic` first; fall back to `advanced` if content is missing or incomplete.
116+
117+
## Choosing the right tool
118+
119+
| Need | Tool |
120+
| ------------------------------------ | ---------------- |
121+
| Quick web search, no special options | `web_search` |
122+
| Search with depth, topic, AI answers | `tavily_search` |
123+
| Extract content from specific URLs | `tavily_extract` |
124+
125+
See [Web tools](/tools/web) for the full web tool setup and provider comparison.

‎docs/tools/web.md‎

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
summary: "Web search + fetch tools (Brave, Firecrawl, Gemini, Grok, Kimi, and Perplexity providers)"
2+
summary: "Web search + fetch tools (Brave, Firecrawl, Gemini, Grok, Kimi, Perplexity, and Tavily providers)"
33
read_when:
44
- You want to enable web_search or web_fetch
55
- You need provider API key setup
@@ -11,7 +11,7 @@ title: "Web Tools"
1111

1212
OpenClaw ships two lightweight web tools:
1313

14-
- `web_search` — Search the web using Brave Search API, Firecrawl Search, Gemini with Google Search grounding, Grok, Kimi, or Perplexity Search API.
14+
- `web_search` — Search the web using Brave Search API, Firecrawl Search, Gemini with Google Search grounding, Grok, Kimi, Perplexity Search API, or Tavily Search API.
1515
- `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).
1616

1717
These are **not** browser automation. For JS-heavy sites or logins, use the
@@ -25,8 +25,9 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
2525
(HTML → markdown/text). It does **not** execute JavaScript.
2626
- `web_fetch` is enabled by default (unless explicitly disabled).
2727
- The bundled Firecrawl plugin also adds `firecrawl_search` and `firecrawl_scrape` when enabled.
28+
- The bundled Tavily plugin also adds `tavily_search` and `tavily_extract` when enabled.
2829

29-
See [Brave Search setup](/tools/brave-search) and [Perplexity Search setup](/tools/perplexity-search) for provider-specific details.
30+
See [Brave Search setup](/tools/brave-search), [Perplexity Search setup](/tools/perplexity-search), and [Tavily Search setup](/tools/tavily) for provider-specific details.
3031

3132
## Choosing a search provider
3233

@@ -38,6 +39,7 @@ See [Brave Search setup](/tools/brave-search) and [Perplexity Search setup](/too
3839
| **Grok** | AI-synthesized answers + citations | — | Uses xAI web-grounded responses | `XAI_API_KEY` |
3940
| **Kimi** | AI-synthesized answers + citations | — | Uses Moonshot web search | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
4041
| **Perplexity Search API** | Structured results with snippets | `country`, `language`, time, `domain_filter` | Supports content extraction controls; OpenRouter uses Sonar compatibility path | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
42+
| **Tavily Search API** | Structured results with snippets | Use `tavily_search` for Tavily-specific search options | Search depth, topic filtering, AI answers, URL extraction via `tavily_extract` | `TAVILY_API_KEY` |
4143

4244
### Auto-detection
4345

@@ -49,6 +51,7 @@ The table above is alphabetical. If no `provider` is explicitly set, runtime aut
4951
4. **Kimi** — `KIMI_API_KEY` / `MOONSHOT_API_KEY` env var or `plugins.entries.moonshot.config.webSearch.apiKey`
5052
5. **Perplexity** — `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
5153
6. **Firecrawl** — `FIRECRAWL_API_KEY` env var or `plugins.entries.firecrawl.config.webSearch.apiKey`
54+
7. **Tavily** — `TAVILY_API_KEY` env var or `plugins.entries.tavily.config.webSearch.apiKey`
5255

5356
If no keys are found, it falls back to Brave (you'll get a missing-key error prompting you to configure one).
5457

@@ -97,6 +100,7 @@ See [Perplexity Search API Docs](https://docs.perplexity.ai/guides/search-quicks
97100
- Grok: `plugins.entries.xai.config.webSearch.apiKey`
98101
- Kimi: `plugins.entries.moonshot.config.webSearch.apiKey`
99102
- Perplexity: `plugins.entries.perplexity.config.webSearch.apiKey`
103+
- Tavily: `plugins.entries.tavily.config.webSearch.apiKey`
100104

101105
All of these fields also support SecretRef objects.
102106

@@ -108,6 +112,7 @@ All of these fields also support SecretRef objects.
108112
- Grok: `XAI_API_KEY`
109113
- Kimi: `KIMI_API_KEY` or `MOONSHOT_API_KEY`
110114
- Perplexity: `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
115+
- Tavily: `TAVILY_API_KEY`
111116

112117
For a gateway install, put these in `~/.openclaw/.env` (or your service environment). See [Env vars](/help/faq#how-does-openclaw-load-environment-variables).
113118

@@ -176,6 +181,36 @@ For a gateway install, put these in `~/.openclaw/.env` (or your service environm
176181

177182
When you choose Firecrawl in onboarding or `openclaw configure --section web`, OpenClaw enables the bundled Firecrawl plugin automatically so `web_search`, `firecrawl_search`, and `firecrawl_scrape` are all available.
178183

184+
**Tavily Search:**
185+
186+
```json5
187+
{
188+
plugins: {
189+
entries: {
190+
tavily: {
191+
enabled: true,
192+
config: {
193+
webSearch: {
194+
apiKey: "tvly-...", // optional if TAVILY_API_KEY is set
195+
baseUrl: "https://api.tavily.com",
196+
},
197+
},
198+
},
199+
},
200+
},
201+
tools: {
202+
web: {
203+
search: {
204+
enabled: true,
205+
provider: "tavily",
206+
},
207+
},
208+
},
209+
}
210+
```
211+
212+
When you choose Tavily in onboarding or `openclaw configure --section web`, OpenClaw enables the bundled Tavily plugin automatically so `web_search`, `tavily_search`, and `tavily_extract` are all available.
213+
179214
**Brave LLM Context mode:**
180215

181216
```json5
@@ -326,6 +361,7 @@ Search the web using your configured provider.
326361
- **Grok**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
327362
- **Kimi**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey`
328363
- **Perplexity**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
364+
- **Tavily**: `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey`
329365
- All provider key fields above support SecretRef objects.
330366

331367
### Config
@@ -369,6 +405,8 @@ If you set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, use
369405

370406
Firecrawl `web_search` supports `query` and `count`. For Firecrawl-specific controls like `sources`, `categories`, result scraping, or scrape timeout, use `firecrawl_search` from the bundled Firecrawl plugin.
371407

408+
Tavily `web_search` supports `query` and `count` (up to 20 results). For Tavily-specific controls like `search_depth`, `topic`, `include_answer`, or domain filters, use `tavily_search` from the bundled Tavily plugin. For URL content extraction, use `tavily_extract`. See [Tavily](/tools/tavily) for details.
409+
372410
**Examples:**
373411

374412
```javascript

‎extensions/brave/openclaw.plugin.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
{
22
"id": "brave",
3+
"providerAuthEnvVars": {
4+
"brave": ["BRAVE_API_KEY"]
5+
},
36
"uiHints": {
47
"webSearch.apiKey": {
58
"label": "Brave Search API Key",

‎extensions/firecrawl/openclaw.plugin.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
{
22
"id": "firecrawl",
3+
"providerAuthEnvVars": {
4+
"firecrawl": ["FIRECRAWL_API_KEY"]
5+
},
36
"uiHints": {
47
"webSearch.apiKey": {
58
"label": "Firecrawl Search API Key",

0 commit comments

Comments
 (0)