How to Install Tavily Search in OpenClaw: A Complete Configuration Guide
“
Tested on: OpenClaw 2026.3.x | OS: Windows / macOS / Linux
Prerequisites: OpenClaw already installed, a valid Tavily API Key
Why Your AI Assistant Can’t Search the Web
If you’ve connected OpenClaw to Feishu (Lark), a Slack workspace, or any other channel and found that your AI assistant keeps saying “I don’t have access to real-time information” — or worse, quietly fails to call any search tool at all — you’re not alone.
This isn’t a network issue. It isn’t the model’s fault either. The real reason is architectural: OpenClaw’s built-in web_search tool defaults to Brave Search, while Tavily operates as a separate Skill plugin with its own configuration path. Setting a system environment variable like TAVILY_API_KEY does nothing for channel integrations like Feishu, because those processes launch independently and never read from your OS environment.
This guide walks you through the correct configuration from start to finish — including every error message you’re likely to hit along the way.
What Is Tavily Search, and Why Use It?
Tavily is a search API built specifically for AI agents and large language models. Unlike Google or Bing — which return ranked lists of links designed for humans to click through — Tavily returns structured, summarized content that LLMs can reason over directly. Think of it as a search engine whose output is already formatted for machine consumption.
If you want your AI assistant to proactively look things up during a conversation — without you having to paste in URLs or copy-paste context — Tavily is one of the most reliable options available right now.
Step 1: Get Your Tavily API Key
-
Go to https://tavily.com -
Sign up (Google login is supported) -
Open your dashboard and copy your API key — it looks like: tvly-dev-xxxxxxxxxxxxxxxx
“
Note: The free plan covers 1,000 requests per month, which is more than enough for personal daily use. You’ll need a paid plan for team or high-frequency usage.
Step 2: Understand OpenClaw’s Configuration Structure
Before touching any files, it helps to understand how openclaw.json is organized. Misreading this structure is the root cause of most configuration errors.
The config file lives at:
-
Windows: C:\Users\YourUsername\.openclaw\openclaw.json -
macOS / Linux: ~/.openclaw/openclaw.json
Here’s how the top-level sections map to functionality:
openclaw.json
├── tools → Core tool settings (only accepts a small set of predefined keys)
├── skills → Skill plugins (this is where tavily-search belongs)
├── plugins → Channel/integration plugins (feishu, qwen-portal-auth, etc.)
├── channels → Channel connection config (Feishu appId, appSecret, etc.)
└── gateway → Local gateway settings
The most common mistake: tutorials tell you to add a web_search or searchBackend field under tools or web. OpenClaw’s config validator will reject both immediately:
Config invalid
Problem:
- tools: Unrecognized key: "web_search"
- web: Unrecognized key: "searchBackend"
Neither field exists in the current schema. Don’t add them.
Step 3: Configure Tavily Search Correctly
3.1 Install the Skill via CLI
Open a terminal (PowerShell on Windows, or Terminal on macOS/Linux) and run:
npx clawhub install tavily-search --force
This installs the tavily-search Skill into OpenClaw’s skills directory.
3.2 Edit openclaw.json
Open the config file in a text editor:
# Windows
notepad C:\Users\YourUsername\.openclaw\openclaw.json
# macOS / Linux
nano ~/.openclaw/openclaw.json
Locate the "skills" section and update it to:
"skills": {
"entries": {
"tavily-search": {
"enabled": true,
"env": {
"TAVILY_API_KEY": "tvly-dev-your-actual-api-key"
}
}
}
}
Then, inside "plugins" → "entries", add openclaw-tavily alongside your existing entries:
"plugins": {
"entries": {
"qwen-portal-auth": {
"enabled": true
},
"feishu": {
"enabled": true
},
"openclaw-tavily": {
"enabled": true,
"config": {
"apiKey": "tvly-dev-your-actual-api-key"
}
}
}
}
“
Why do I need to add the key in two places?
Theskills.entriesblock passes the key as an environment variable to the Skill’s runtime process. Theplugins.entriesblock tells OpenClaw’s plugin system to load and register the tool. Both are required — missing either one means the tool either won’t run or won’t be visible to the agent.
3.3 Commands to Avoid
The following commands look plausible but will not work in the current version of OpenClaw:
# ❌ Wrong: --key flag does not exist
openclaw configure --section web --key tavily_api_key --value "xxx"
# ❌ Wrong: tools.web_search is not a valid config path
openclaw config set tools.web_search.provider "tavily"
The correct way to set config values from the command line:
# ✅ Correct
openclaw config set skills.entries.tavily-search.enabled true
Step 4: Validate and Restart
4.1 Validate the config file
openclaw config validate
If the output contains no Problem: lines, your config file is structurally valid.
4.2 Restart the gateway
openclaw gateway restart
4.3 Confirm the Skill loaded
openclaw skills list
You should see tavily-search in the list with a status of enabled.
Complete openclaw.json Reference
Below is a clean, complete configuration example. Replace placeholder values with your actual credentials and keep everything else as-is:
{
"tools": {
"profile": "full"
},
"commands": {
"native": "auto",
"nativeSkills": "auto",
"restart": true,
"ownerDisplay": "raw"
},
"session": {
"dmScope": "per-channel-peer"
},
"channels": {
"feishu": {
"enabled": true,
"appId": "your-feishu-app-id",
"appSecret": "your-feishu-app-secret",
"connectionMode": "websocket",
"domain": "feishu",
"groupPolicy": "allowlist"
}
},
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"auth": {
"mode": "token",
"token": "your-gateway-token"
}
},
"skills": {
"entries": {
"tavily-search": {
"enabled": true,
"env": {
"TAVILY_API_KEY": "tvly-dev-your-actual-api-key"
}
}
}
},
"plugins": {
"entries": {
"qwen-portal-auth": {
"enabled": true
},
"feishu": {
"enabled": true
},
"openclaw-tavily": {
"enabled": true,
"config": {
"apiKey": "tvly-dev-your-actual-api-key"
}
}
}
}
}
Troubleshooting: Common Errors and Fixes
Error 1: Unrecognized key: "web_search"
Config invalid
Problem:
- tools: Unrecognized key: "web_search"
Cause: The tools section has a strict schema. web_search is not a recognized key.
Fix: Remove everything you added under tools except "profile": "full". Nothing else belongs there.
Error 2: Unrecognized key: "searchBackend"
Config invalid
Problem:
- web: Unrecognized key: "searchBackend"
Cause: A previous configuration attempt wrote an invalid web.searchBackend field.
Fix: Find and delete the entire "web": { ... } block from your config, or remove just the searchBackend line if other valid fields are present under web.
Error 3: duplicate plugin id detected
plugins.entries.feishu: plugin feishu: duplicate plugin id detected;
later plugin may be overridden
Cause: The Feishu plugin is being loaded twice, usually because there are multiple Feishu folders in the extensions directory.
Fix:
# Check what's in the extensions directory
ls C:\Users\YourUsername\.openclaw\extensions\
# Reinstall the Feishu plugin cleanly
openclaw plugin uninstall feishu
openclaw plugin install @openclaw/feishu
Error 4: Start-Process: The system cannot find the file specified
Start-Process : Cannot run this command because of the following error:
The system cannot find the file specified.
Cause: The setup-env.ps1 script contains a hardcoded path to Microsoft Edge that doesn’t match your system.
What to know: This error does not affect API key configuration. If the script already printed a ✅ success message, the key was written correctly. This failure only means the “auto-open browser” step didn’t work — which you can safely ignore.
If you want to make the API key permanently available as a system environment variable:
[System.Environment]::SetEnvironmentVariable("TAVILY_API_KEY", "your-api-key", "User")
Then restart PowerShell for the change to take effect.
Error 5: unknown option '--key'
error: unknown option '--key'
Cause: The openclaw configure command is an interactive wizard. It does not accept --key, --section, or --value flags.
Fix: Use openclaw config set with dot-notation paths instead:
openclaw config set skills.entries.tavily-search.env.TAVILY_API_KEY "your-key"
Or edit openclaw.json directly.
Error 6: Search works locally but not in Feishu
This is the most frustrating scenario because everything appears to be set up correctly. There are two likely causes:
Cause A: The API key exists only as a system environment variable, not inside openclaw.json.
→ Feishu’s OpenClaw process is launched independently. It doesn’t inherit your shell’s environment variables. The key must be present in skills.entries and plugins.entries within openclaw.json.
Cause B: The Feishu plugin has a duplicate conflict (see Error 3 above).
→ Reinstall the Feishu plugin and restart the gateway.
How to Use Tavily Search After Setup
Once configured, your AI assistant gains access to a tool called tavily_search — note that this is distinct from the existing web_search tool. Both coexist; the agent selects between them based on context.
You can trigger Tavily search naturally in conversation:
-
“Search for the latest news on AI agents” -
“What’s the current price of the MacBook Pro M4?” -
“Use Tavily to look up the OpenClaw changelog”
If the agent doesn’t automatically pick Tavily, explicitly saying “use Tavily to search” will route the request correctly.
Tavily supports several search modes worth knowing about:
Frequently Asked Questions
Is the Tavily free plan sufficient for personal use?
For individual daily use, 1,000 requests per month is generous. A typical conversation might use 3–5 search calls, so you’d need to have roughly 200–300 search-heavy conversations before hitting the limit. Teams or high-frequency automation scenarios will need a paid plan.
Do I need to restart my computer after changing the config?
No. Running openclaw gateway restart is all that’s needed. The gateway reloads openclaw.json on startup.
Can Tavily and Brave Search be used at the same time?
Yes. OpenClaw’s built-in web_search (Brave) and Tavily’s tavily_search are independent tools that can both be active. The agent will select between them, or you can specify which one you want.
Why doesn’t setting a system environment variable work for Feishu?
Channel integrations like Feishu run inside OpenClaw’s internal process, which is spawned at startup. By the time you set an environment variable in your shell, that process has already launched — and it doesn’t re-read the environment dynamically. Configuration through openclaw.json is the only reliable path for persistent, channel-accessible settings.
What’s the difference between openclaw configure and openclaw config set?
openclaw configure is an interactive setup wizard — it asks you questions and writes values for you, useful for initial setup. openclaw config set directly writes a specific key-value pair to your config using dot-notation paths, better for scripting or precise edits.
I edited the config file and now OpenClaw won’t start. What do I do?
Use the complete configuration example from this guide as a baseline. Copy it into your openclaw.json, then fill in your actual appId, appSecret, gateway token, and API keys. That file has been validated and contains no invalid fields.
Does Tavily work with AI models other than the ones shown in the example config?
Yes. Tavily is a search tool — it’s model-agnostic. Whether you’re running Qwen, GPT, Claude, or a local model via vLLM, the tavily_search tool will work as long as the model supports tool/function calling.
Summary
The core principle to remember: Tavily is a Skill plugin, not a replacement for the built-in web_search tool. Its API key must be written into two specific locations in openclaw.json — skills.entries and plugins.entries — because system environment variables are invisible to channel processes like Feishu.
When you hit a config validation error, read the problem field name carefully. Almost every error in this setup process comes down to either an unrecognized field in the wrong section, or a duplicate plugin entry. Both are easy to fix once you know where to look.
If you’re still stuck after following this guide, run openclaw config validate to get the exact field name causing the problem, then cross-reference it against the schema notes above.
Verified against OpenClaw 2026.3.13. If a future version changes the configuration schema, refer to the official OpenClaw documentation for updated field names.
