1. 为什么要把 OpenClaw 的搜索从 Brave 换成 TavilyOpenClaw 默认的联网搜索走的是 Brave Search API早期个人开发者用起来没什么负担但最近 Brave 调整了策略免费额度收紧、超出后按订阅计费对于只是想让 Agent 偶尔查个资料、跑个日报的场景来说成本一下子变得不划算。我自己的 OpenClaw 实例每天大概触发几十次搜索按 Brave 的新规则算下来一个月要额外掏一笔实在没必要。Tavily 是专门为 LLM 设计的搜索 API返回的是已经清洗过的结构化结果不像传统搜索那样塞一堆广告和导航栏。它每月给 1000 次免费调用邮箱注册即可不用绑卡对个人开发者和小团队非常友好。更关键的是Tavily 的返回格式天然适合喂给大模型OpenClaw 拿到结果后不需要再做太多解析直接就能拼进上下文。这篇教程聚焦一件事把 OpenClaw 的搜索服务从 Brave 完整迁移到 Tavily。我会带你走完 API Key 获取、插件安装、openclaw.json配置骨架、重启验证、以及迁移后怎么确认 Tavily 真的生效了。如果你之前没配过 Brave也可以直接按这篇从零接入 Tavily跳过卸载 Brave 那一步即可。适合谁看已经在用 OpenClaw 并且配了 Brave 搜索、想换掉的刚装好 OpenClaw 想直接上 Tavily 的以及想搞清楚 OpenClaw 插件配置结构、方便以后换其他搜索后端的。全程命令和配置都可以直接复制改掉 Key 就能跑。2. 迁移前先准备好 Tavily 的 API Key2.1 注册 Tavily 账号并拿到 Key打开 Tavily 官网点右上角 Sign Up选 Continue with Email填邮箱、收验证邮件、设密码整个过程两三分钟。登录后会自动进 Dashboard在首页就能看到 API Key格式一般是tvly-dev-开头的一长串。点复制按钮存到安全的地方后面配置要用。注意这个 Key 等同于你的调用凭证不要提交到 Git 仓库、不要贴在公开的 issue 里。生产环境建议用环境变量注入而不是硬编码在配置文件里。2.2 确认 OpenClaw 版本和插件目录在终端跑一下版本命令确认 OpenClaw 是较新的版本老版本可能不认 Tavily 插件的配置字段openclaw --version如果版本低于 2026.2.26先升级再继续。然后看一眼插件目录是否存在ls -la ~/.openclaw/extensions/这个目录是插件安装的落点后面装完 Tavily 插件会在这里多一个文件夹。如果目录不存在说明 OpenClaw 还没初始化过先跑一次openclaw gateway start让它生成默认结构。2.3 备份现有配置迁移前把当前配置备份一份万一改坏了能快速回滚cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak这一步别省。我试过直接改配置结果 JSON 少了个逗号整个 gateway 起不来有备份的话一条命令就恢复了。3. 安装 Tavily 插件并写配置骨架3.1 用对话方式安装最省事OpenClaw 支持直接用自然语言让它装插件。在对话界面里发一句请帮我安装 tavily-search 插件API Key 是 tvly-dev-你的真实Key系统会识别意图自动去 ClawHub 拉取插件、写入配置、提示你重启。这种方式适合不想碰命令行的同学缺点是出错时不好定位是哪一步的问题。3.2 手动安装插件更可控的方式是走命令行。执行openclaw plugins install clawhub/tavily-search安装成功后终端会提示插件已落到~/.openclaw/extensions/tavily-search。你可以进去看一眼目录结构确认有manifest.json和入口文件ls ~/.openclaw/extensions/tavily-search/3.3 编辑 openclaw.json 配置骨架用编辑器打开主配置文件vim ~/.openclaw/openclaw.json在tools节点下加入 Tavily 的配置。如果原来有 Brave 的配置建议先注释掉或删掉避免两个搜索后端同时启用导致路由混乱。完整的骨架长这样{ tools: { tavily-search: { enabled: true, apiKey: tvly-dev-你的真实Key, maxResults: 5, searchDepth: basic } } }几个参数说明一下。enabled控制插件是否启用迁移期间先设 true。apiKey填你复制的那个。maxResults是每次搜索返回的结果条数默认 5 条对大多数场景够用调大能拿到更多候选但也会更耗额度。searchDepth有basic和advanced两档basic 更快更省advanced 会做更深的抓取和摘要按需选。提示如果你更习惯图形界面也可以访问http://127.0.0.1:18789/config点 Raw 按钮进原始编辑模式把上面的 JSON 片段贴进去保存效果一样。3.4 重启 gateway 让配置生效改完配置必须重启插件才会重新加载openclaw gateway restart重启后看日志有没有报错openclaw gateway logs --tail 50如果看到tavily-search plugin loaded之类的字样说明插件已经挂上了。如果报invalid apiKey或plugin not found往下看第 5 节的排查。4. 验证 Tavily 是否真的接管了搜索4.1 用对话触发一次搜索在 OpenClaw 对话界面发一条明确要求联网的指令请帮我搜索今天 AI 领域的热点新闻用 markdown 列表返回每条附上来源链接如果 Tavily 生效你会看到它返回一组带标题、摘要和 URL 的结果而不是模型凭记忆瞎编。重点看两点结果里有没有真实可点的链接以及内容是不是近期的。如果返回的是「我无法访问实时信息」这类话说明搜索没被调用。4.2 直接打 Tavily API 做对照想确认是 Key 本身没问题还是 OpenClaw 配置的问题可以绕过 OpenClaw 直接调一次 Tavilycurl -X POST https://api.tavily.com/search \ -H Content-Type: application/json \ -d { api_key: tvly-dev-你的真实Key, query: OpenClaw Tavily migration, max_results: 3 }返回 JSON 里有results数组且非空说明 Key 和网络都正常问题就出在 OpenClaw 的配置或插件加载上。如果这里就报 401那 Key 本身有问题回 Tavily 控制台重新复制。4.3 看日志确认调用链路再跑一次对话搜索同时盯日志openclaw gateway logs -f | grep -i tavily正常的话能看到类似tavily-search: query... results5的记录。如果日志里出现的是 brave 相关的字样说明旧配置没清干净搜索还在走 Brave回第 3.3 节把 Brave 节点删掉再重启。5. 迁移过程中容易踩的坑5.1 搜索无结果或返回空数组最常见的原因是apiKey字段拼错或者带了多余空格。JSON 里字符串两边的引号内不要留空格复制 Key 时也注意别把换行带进去。改完记得重启 gateway配置不是热加载的。另一个可能是maxResults设成了 0 或者负数插件会直接返回空。检查一下这个值是不是正整数。5.2 提示 Rate Limit 或 429Tavily 免费额度是每月 1000 次超了就会返回 429。先确认是不是自己调用太频繁比如 Agent 在一个循环里反复搜索。可以在配置里把maxResults调小、searchDepth设成 basic 来降低单次消耗。如果确实用量大去 Tavily 控制台看用量面板必要时升级套餐。5.3 插件加载失败报plugin not found通常是插件没装成功或者装到了错误的目录。重新跑一次openclaw plugins install clawhub/tavily-search然后确认~/.openclaw/extensions/tavily-search存在。如果报版本不兼容检查 OpenClaw 版本是否满足插件要求必要时锁定插件版本安装openclaw plugins install clawhub/tavily-search1.2.0具体版本号以 ClawHub 上标注的为准。5.4 配置改了但不生效九成是忘了重启 gateway。OpenClaw 的插件配置在启动时读取运行中改文件不会自动重载。养成改完就openclaw gateway restart的习惯。另外确认你改的是~/.openclaw/openclaw.json而不是项目目录下的某个副本路径错了自然不生效。5.5 网络能通但搜索超时Tavily 的接口域名是api.tavily.com确认服务器出站能访问它。如果是容器环境检查 DNS 和防火墙规则。超时时间太短也会导致失败可以在插件配置里适当调大 timeout 字段如果插件支持的话。6. 迁移完成后的收尾与后续接入到这一步OpenClaw 的搜索后端应该已经从 Brave 切到 Tavily 了。回对话界面再跑一次搜索确认返回的是带链接的实时结果日志里出现 tavily 字样就说明迁移成功。把之前备份的openclaw.json.bak留着观察一两天没问题再删。如果你还想给 OpenClaw 接更多模型能力或者想统一管理多个服务的 Key可以到 TaoToken 的模型对话页面看看它把常用模型的调用入口收在一起省得每个服务单独配一遍。长期跑编码类 Agent 的话Coding Plan 那套方案更适合持续调用场景额度管理比按次计费省心。接入过程中如果遇到 Key 配置或插件加载的问题直接翻接入文档对照排查大部分报错里面都有对应说明。搜索服务迁移本身不复杂核心就三件事拿到 Tavily 的 Key、把插件装上、在openclaw.json里写对配置并重启。真正容易翻车的是细节——Key 多复制了个空格、忘了重启、旧 Brave 配置没删干净。按上面的步骤一步步来基本一次就能过。 OpenClaw 搜索服务迁移教程：从 Brave 到 Tavily 的 API Key 与插件配置
1. 为什么要把 OpenClaw 的搜索从 Brave 换成 TavilyOpenClaw 默认的联网搜索走的是 Brave Search API早期个人开发者用起来没什么负担但最近 Brave 调整了策略免费额度收紧、超出后按订阅计费对于只是想让 Agent 偶尔查个资料、跑个日报的场景来说成本一下子变得不划算。我自己的 OpenClaw 实例每天大概触发几十次搜索按 Brave 的新规则算下来一个月要额外掏一笔实在没必要。Tavily 是专门为 LLM 设计的搜索 API返回的是已经清洗过的结构化结果不像传统搜索那样塞一堆广告和导航栏。它每月给 1000 次免费调用邮箱注册即可不用绑卡对个人开发者和小团队非常友好。更关键的是Tavily 的返回格式天然适合喂给大模型OpenClaw 拿到结果后不需要再做太多解析直接就能拼进上下文。这篇教程聚焦一件事把 OpenClaw 的搜索服务从 Brave 完整迁移到 Tavily。我会带你走完 API Key 获取、插件安装、openclaw.json配置骨架、重启验证、以及迁移后怎么确认 Tavily 真的生效了。如果你之前没配过 Brave也可以直接按这篇从零接入 Tavily跳过卸载 Brave 那一步即可。适合谁看已经在用 OpenClaw 并且配了 Brave 搜索、想换掉的刚装好 OpenClaw 想直接上 Tavily 的以及想搞清楚 OpenClaw 插件配置结构、方便以后换其他搜索后端的。全程命令和配置都可以直接复制改掉 Key 就能跑。2. 迁移前先准备好 Tavily 的 API Key2.1 注册 Tavily 账号并拿到 Key打开 Tavily 官网点右上角 Sign Up选 Continue with Email填邮箱、收验证邮件、设密码整个过程两三分钟。登录后会自动进 Dashboard在首页就能看到 API Key格式一般是tvly-dev-开头的一长串。点复制按钮存到安全的地方后面配置要用。注意这个 Key 等同于你的调用凭证不要提交到 Git 仓库、不要贴在公开的 issue 里。生产环境建议用环境变量注入而不是硬编码在配置文件里。2.2 确认 OpenClaw 版本和插件目录在终端跑一下版本命令确认 OpenClaw 是较新的版本老版本可能不认 Tavily 插件的配置字段openclaw --version如果版本低于 2026.2.26先升级再继续。然后看一眼插件目录是否存在ls -la ~/.openclaw/extensions/这个目录是插件安装的落点后面装完 Tavily 插件会在这里多一个文件夹。如果目录不存在说明 OpenClaw 还没初始化过先跑一次openclaw gateway start让它生成默认结构。2.3 备份现有配置迁移前把当前配置备份一份万一改坏了能快速回滚cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak这一步别省。我试过直接改配置结果 JSON 少了个逗号整个 gateway 起不来有备份的话一条命令就恢复了。3. 安装 Tavily 插件并写配置骨架3.1 用对话方式安装最省事OpenClaw 支持直接用自然语言让它装插件。在对话界面里发一句请帮我安装 tavily-search 插件API Key 是 tvly-dev-你的真实Key系统会识别意图自动去 ClawHub 拉取插件、写入配置、提示你重启。这种方式适合不想碰命令行的同学缺点是出错时不好定位是哪一步的问题。3.2 手动安装插件更可控的方式是走命令行。执行openclaw plugins install clawhub/tavily-search安装成功后终端会提示插件已落到~/.openclaw/extensions/tavily-search。你可以进去看一眼目录结构确认有manifest.json和入口文件ls ~/.openclaw/extensions/tavily-search/3.3 编辑 openclaw.json 配置骨架用编辑器打开主配置文件vim ~/.openclaw/openclaw.json在tools节点下加入 Tavily 的配置。如果原来有 Brave 的配置建议先注释掉或删掉避免两个搜索后端同时启用导致路由混乱。完整的骨架长这样{ tools: { tavily-search: { enabled: true, apiKey: tvly-dev-你的真实Key, maxResults: 5, searchDepth: basic } } }几个参数说明一下。enabled控制插件是否启用迁移期间先设 true。apiKey填你复制的那个。maxResults是每次搜索返回的结果条数默认 5 条对大多数场景够用调大能拿到更多候选但也会更耗额度。searchDepth有basic和advanced两档basic 更快更省advanced 会做更深的抓取和摘要按需选。提示如果你更习惯图形界面也可以访问http://127.0.0.1:18789/config点 Raw 按钮进原始编辑模式把上面的 JSON 片段贴进去保存效果一样。3.4 重启 gateway 让配置生效改完配置必须重启插件才会重新加载openclaw gateway restart重启后看日志有没有报错openclaw gateway logs --tail 50如果看到tavily-search plugin loaded之类的字样说明插件已经挂上了。如果报invalid apiKey或plugin not found往下看第 5 节的排查。4. 验证 Tavily 是否真的接管了搜索4.1 用对话触发一次搜索在 OpenClaw 对话界面发一条明确要求联网的指令请帮我搜索今天 AI 领域的热点新闻用 markdown 列表返回每条附上来源链接如果 Tavily 生效你会看到它返回一组带标题、摘要和 URL 的结果而不是模型凭记忆瞎编。重点看两点结果里有没有真实可点的链接以及内容是不是近期的。如果返回的是「我无法访问实时信息」这类话说明搜索没被调用。4.2 直接打 Tavily API 做对照想确认是 Key 本身没问题还是 OpenClaw 配置的问题可以绕过 OpenClaw 直接调一次 Tavilycurl -X POST https://api.tavily.com/search \ -H Content-Type: application/json \ -d { api_key: tvly-dev-你的真实Key, query: OpenClaw Tavily migration, max_results: 3 }返回 JSON 里有results数组且非空说明 Key 和网络都正常问题就出在 OpenClaw 的配置或插件加载上。如果这里就报 401那 Key 本身有问题回 Tavily 控制台重新复制。4.3 看日志确认调用链路再跑一次对话搜索同时盯日志openclaw gateway logs -f | grep -i tavily正常的话能看到类似tavily-search: query... results5的记录。如果日志里出现的是 brave 相关的字样说明旧配置没清干净搜索还在走 Brave回第 3.3 节把 Brave 节点删掉再重启。5. 迁移过程中容易踩的坑5.1 搜索无结果或返回空数组最常见的原因是apiKey字段拼错或者带了多余空格。JSON 里字符串两边的引号内不要留空格复制 Key 时也注意别把换行带进去。改完记得重启 gateway配置不是热加载的。另一个可能是maxResults设成了 0 或者负数插件会直接返回空。检查一下这个值是不是正整数。5.2 提示 Rate Limit 或 429Tavily 免费额度是每月 1000 次超了就会返回 429。先确认是不是自己调用太频繁比如 Agent 在一个循环里反复搜索。可以在配置里把maxResults调小、searchDepth设成 basic 来降低单次消耗。如果确实用量大去 Tavily 控制台看用量面板必要时升级套餐。5.3 插件加载失败报plugin not found通常是插件没装成功或者装到了错误的目录。重新跑一次openclaw plugins install clawhub/tavily-search然后确认~/.openclaw/extensions/tavily-search存在。如果报版本不兼容检查 OpenClaw 版本是否满足插件要求必要时锁定插件版本安装openclaw plugins install clawhub/tavily-search1.2.0具体版本号以 ClawHub 上标注的为准。5.4 配置改了但不生效九成是忘了重启 gateway。OpenClaw 的插件配置在启动时读取运行中改文件不会自动重载。养成改完就openclaw gateway restart的习惯。另外确认你改的是~/.openclaw/openclaw.json而不是项目目录下的某个副本路径错了自然不生效。5.5 网络能通但搜索超时Tavily 的接口域名是api.tavily.com确认服务器出站能访问它。如果是容器环境检查 DNS 和防火墙规则。超时时间太短也会导致失败可以在插件配置里适当调大 timeout 字段如果插件支持的话。6. 迁移完成后的收尾与后续接入到这一步OpenClaw 的搜索后端应该已经从 Brave 切到 Tavily 了。回对话界面再跑一次搜索确认返回的是带链接的实时结果日志里出现 tavily 字样就说明迁移成功。把之前备份的openclaw.json.bak留着观察一两天没问题再删。如果你还想给 OpenClaw 接更多模型能力或者想统一管理多个服务的 Key可以到 TaoToken 的模型对话页面看看它把常用模型的调用入口收在一起省得每个服务单独配一遍。长期跑编码类 Agent 的话Coding Plan 那套方案更适合持续调用场景额度管理比按次计费省心。接入过程中如果遇到 Key 配置或插件加载的问题直接翻接入文档对照排查大部分报错里面都有对应说明。搜索服务迁移本身不复杂核心就三件事拿到 Tavily 的 Key、把插件装上、在openclaw.json里写对配置并重启。真正容易翻车的是细节——Key 多复制了个空格、忘了重启、旧 Brave 配置没删干净。按上面的步骤一步步来基本一次就能过。