1. 为什么要在 OpenClaw 里接一个 Tavily 搜索 SkillOpenClaw 的 Agent 默认带一个内置web_search工具后端走的是 Brave Search。这个工具在海外环境里表现不错但在国内服务器上经常直接fetch failedAgent 拿不到任何结果只能降级到本地 SearXNG 或者干脆告诉用户“搜索失败”。Tavily 是专门为 AI Agent 设计的搜索 API返回的是结构化摘要而不是一堆链接Agent 拿到就能直接用省掉二次抓取网页的步骤。把 Tavily 做成 OpenClaw 的 Skill等于给 Agent 换了一个更懂 AI 的搜索后端。这篇教程面向的是已经在国内服务器上跑 OpenClaw、想让 Agent 搜索能力更稳的人。我会从 Tavily API Key 的获取开始一步步写 Skill 声明文件、配置环境变量、重启 Gateway最后用一条真实搜索请求验证 Tavily 是否生效。中间会给出可直接复制的SKILL.md、search.mjs和openclaw.json片段也会把国内 npm 镜像踩坑、Gateway 不读.bashrc这类常见问题讲清楚。如果你用的是 OpenClaw 2026.3.8 或相近版本跟着做基本能一次跑通。需要提前说明一点OpenClaw 2026.3.8 的 Agent 在搜索时会优先调用内置web_searchSkill 脚本不一定被主动触发。所以本文除了教你装 Skill还会给出验证 Skill 本身是否可用的方法以及当 Agent 不调用它时怎么排查。搜索能力是否“生效”要分两层看Skill 能不能跑通和 Agent 会不会用它。两层都验证过才算真正跑通。2. 前置准备Tavily API Key 与 OpenClaw 环境确认Tavily 的注册流程很简单打开 app.tavily.com用 Google 或 GitHub 账号登录即可不需要信用卡。免费计划叫 Researcher每月给 1000 次搜索额度对个人 Agent 日常使用完全够。登录后进 Dashboard在 API Keys 区域能看到一串以tvly-开头的 Key复制下来先存到安全的地方后面写配置要用。OpenClaw 这边需要确认三件事。第一OpenClaw 版本用openclaw --version看本文以 2026.3.8 为准。第二Node.js 版本Skill 脚本是.mjs需要 Node 18 以上node -v确认一下太低就用npm install -g n n lts升到 v24。第三确认 OpenClaw 的配置目录默认在~/.openclaw/Skill 放在~/.openclaw/skills/下主配置是~/.openclaw/openclaw.json。还有一点容易被忽略OpenClaw Gateway 是以 systemd 服务方式跑的它不会读取你 shell 里的.bashrc或.zshrc。所以 Tavily 的 Key 不能只 export 在终端里必须写进openclaw.json的env节再同步到 systemd。这一点后面第 5 节会详细写先记住结论就行。如果你之前已经装过 SearXNG 或 Jina Reader不用卸载Tavily 可以和它们共存。Agent 的搜索优先级可以在AGENTS.md里调整Tavily 作为首选、SearXNG 作为兜底这样即使 Tavily 额度用完也不会断搜。环境确认完就可以开始装 Skill 了。3. 可复制配置Skill 声明文件与 search.mjs 脚本OpenClaw 的 Skill 本质就是一个目录里面放一个SKILL.md声明文件加上实际执行的脚本。目录结构如下~/.openclaw/skills/tavily-search/ ├── SKILL.md └── scripts/ └── search.mjs先建目录mkdir -p ~/.openclaw/skills/tavily-search/scripts然后写SKILL.md。这个文件的 frontmatter 里要声明 Skill 名称、依赖的二进制和需要的环境变量OpenClaw 启动时会扫描这些信息cat ~/.openclaw/skills/tavily-search/SKILL.md EOF --- name: tavily description: AI-optimized web search via Tavily API. Returns concise, relevant results for AI agents. homepage: https://tavily.com metadata: {clawdbot:{emoji:,requires:{bins:[node],env:[TAVILY_API_KEY]},primaryEnv:TAVILY_API_KEY}} --- # Tavily Search AI-optimized web search using Tavily API. Designed for AI agents - returns clean, relevant content. ## Search bash node {baseDir}/scripts/search.mjs query node {baseDir}/scripts/search.mjs query -n 10 node {baseDir}/scripts/search.mjs query --deep node {baseDir}/scripts/search.mjs query --topic newsEOF注意 name 字段写的是 tavily后面在 AGENTS.md 里引用工具名时要和它保持一致否则 Agent 找不到对应工具。requires.env 里声明了 TAVILY_API_KEYOpenClaw 会检查这个变量是否存在缺失时 Skill 状态会显示异常。 接着写 search.mjs。这个脚本负责解析命令行参数、拼 Tavily 的请求体、发 HTTPS 请求、把返回的 answer 和 results 格式化输出 bash cat ~/.openclaw/skills/tavily-search/scripts/search.mjs EOF #!/usr/bin/env node import https from https; const API_KEY process.env.TAVILY_API_KEY; if (!API_KEY) { console.error(Error: TAVILY_API_KEY environment variable is not set.); process.exit(1); } const args process.argv.slice(2); let query ; let maxResults 5; let searchDepth basic; let topic general; for (let i 0; i args.length; i) { if (args[i] -n args[i 1]) { maxResults parseInt(args[i 1]); i; } else if (args[i] --deep) { searchDepth advanced; } else if (args[i] --topic args[i 1]) { topic args[i 1]; i; } else if (!args[i].startsWith(-)) { query args[i]; } } if (!query) { console.error(Usage: node search.mjs query [-n count] [--deep] [--topic news|general|finance]); process.exit(1); } const payload JSON.stringify({ api_key: API_KEY, query, max_results: maxResults, search_depth: searchDepth, topic, include_answer: true }); const req https.request(https://api.tavily.com/search, { method: POST, headers: { Content-Type: application/json, Content-Length: Buffer.byteLength(payload) } }, (res) { let data ; res.on(data, (chunk) data chunk); res.on(end, () { try { const result JSON.parse(data); if (result.answer) { console.log(## Answer\n); console.log(result.answer \n); } if (result.results result.results.length 0) { console.log(## Sources\n); result.results.forEach((r, i) { console.log(${i 1}. **${r.title}**); console.log( URL: ${r.url}); if (r.content) console.log( ${r.content.slice(0, 200)}...); console.log(); }); } } catch (e) { console.error(Failed to parse response:, data); } }); }); req.on(error, (e) console.error(Request failed:, e.message)); req.write(payload); req.end(); EOF脚本里include_answer: true是关键Tavily 会额外返回一段直接可用的答案摘要Agent 读起来比纯链接列表省事。--deep对应search_depth: advanced结果更全但消耗额度也更快日常用 basic 就够。写完两个文件确认目录结构find ~/.openclaw/skills/tavily-search/ -type f预期输出两行分别是SKILL.md和scripts/search.mjs。如果只有一行说明某个cat命令没执行成功重新跑一遍。4. 验证请求从命令行到 Agent 的真实搜索测试Skill 文件就位后先别急着让 Agent 调用直接在命令行验证脚本本身能不能跑通。这一步能排除掉脚本语法、Key 加载、网络连通性三类问题。先临时 export Key只是测试用正式配置在第 5 节export TAVILY_API_KEYtvly-你的实际Key node ~/.openclaw/skills/tavily-search/scripts/search.mjs OpenClaw Tavily Skill 配置 -n 3如果一切正常你会看到类似这样的输出## Answer OpenClaw 可以通过 Skill 方式接入 Tavily 搜索需要在 SKILL.md 中声明 TAVILY_API_KEY 环境变量并在 openclaw.json 的 env 节写入 Key。 ## Sources 1. **OpenClaw Skill 开发指南** URL: https://example.com/openclaw-skill OpenClaw 的 Skill 由 SKILL.md 和脚本组成... 2. **Tavily API 文档** URL: https://docs.tavily.com Tavily 提供 search、extract、crawl 等接口...看到## Answer和## Sources两段说明脚本、Key、网络三样都通了。如果只报Error: TAVILY_API_KEY environment variable is not set说明 export 没生效检查一下当前 shell。如果报Request failed先用 curl 测一下 Tavily 的连通性curl -s -o /dev/null -w %{http_code} https://api.tavily.com/search返回 401 说明网络通、只是没带 Key返回 000 或超时才是网络问题。Tavily 是商业 API国内服务器一般能直连不像 GitHub 那样被针对性阻断。命令行通了之后再让 OpenClaw 识别 Skillopenclaw skills list | grep -i tavily预期输出里带✓ ready和 tavily说明 OpenClaw 已经扫描到这个 Skill且依赖检查通过。如果显示的不是 ready通常是TAVILY_API_KEY还没写进openclaw.jsonOpenClaw 检查requires.env时没找到就会标成未就绪。这时候去第 5 节把 Key 写进配置再重启 Gateway 即可。最后一步是 Agent 层验证。在飞书或你用的前端里对 Agent 说用 Tavily 搜索一下今天的 AI 行业新闻观察返回结果的结构。如果 Agent 真的调用了 Tavily Skill输出会是结构化的摘要加来源列表末尾可能标注“数据来源Tavily”。如果 Agent 还是走内置web_search你会看到它先尝试 Brave、失败后降级到 SearXNG末尾标注“数据来源SearXNGTavily 暂不可用”。这两种情况都算“Skill 可用”区别在于 Agent 有没有主动选它。下一节会专门讲这个优先级问题。5. 常见报错排查401、local proxy failed 与 Skill not found配置过程中最容易撞上的几类报错这里按真实日志对照着讲。401 Unauthorized。命令行跑search.mjs时返回 401说明 Key 没被正确带上。先确认echo $TAVILY_API_KEY有值再确认 Key 没有多余空格或换行。如果 Key 是从网页复制的有时会带上不可见字符用echo -n $TAVILY_API_KEY | wc -c看长度是否和预期一致。写进openclaw.json时也要注意 JSON 转义Key 里如果有特殊字符要正确处理。local proxy failed / fetch failed。这类报错通常出现在 Agent 调用内置web_search时日志里是[tools] web_search failed: fetch failed。这不是 Tavily 的问题而是内置工具后端 Brave Search 在国内不可达。解决办法就是本文这套装 Tavily Skill并在AGENTS.md里把搜索优先级改成 Tavily 优先。改完记得openclaw gateway install --force openclaw gateway restart只 restart 不会同步新配置到 systemd。Skill not found。执行npx clawhublatest install tavily-search时报这个错是因为 ClawHub 上没有叫tavily-search的 Skill实际名称是openclaw-tavily-search。正确做法是先搜再装npm_config_registryhttps://registry.npmjs.org npx clawhublatest search tavily npm_config_registryhttps://registry.npmjs.org npx clawhublatest install openclaw-tavily-search国内 npm 镜像上undici^7.24.0可能没同步会报No matching version found加npm_config_registryhttps://registry.npmjs.org前缀强制走官方源即可。OAuth / 认证类报错。如果你在 OpenClaw 里同时配了多个模型供应商偶尔会看到 OAuth token 相关的报错。这类问题一般和 Tavily Skill 无关检查openclaw.json里模型供应商的认证配置是否完整。Tavily 本身只用 API Key不涉及 OAuth。Gateway 环境变量里找不到 TAVILY_API_KEY。改了openclaw.json后用下面这条命令确认 Key 已经进到 Gateway 进程cat /proc/$(pgrep -f openclaw-gateway)/environ | tr \0 \n | grep -i tavily | sed s/.*/******/预期输出TAVILY_API_KEY******。如果没有输出说明配置没同步重新执行openclaw gateway install --force再 restart。Agent 指定用 Tavily 但实际走 SearXNG。检查AGENTS.md里的工具名是否和SKILL.md的name一致。如果SKILL.md写的是name: tavily而AGENTS.md里写的是tavily_searchAgent 找不到对应工具就会回退。用sed -i s/tavily_search/tavily/g ~/.openclaw/workspace/AGENTS.md统一一下。排查完这些Skill 本身的可运行性基本就有保障了。剩下的就是 Agent 调用优先级问题那属于 OpenClaw 版本行为不是配置错误。6. 让搜索能力真正生效接入 TaoToken 与长期 Coding PlanSkill 跑通之后如果你希望 Agent 在编码、调研这类长任务里稳定调用搜索建议把模型接入也一起理顺。TaoToken 提供统一的 API 入口Base URL 是https://taotoken.net/api你可以在控制台生成 Key然后在 OpenClaw 的模型配置里指向它。这样 Agent 的推理和搜索两条链路都走可控的通道排查问题时边界更清晰。具体操作上先去 TaoToken API Keys 页面 生成一个 Key然后在openclaw.json的模型供应商配置里填入 Base URL 和 Key。模型 ID 按你实际用的填比如claude-sonnet-4-6或kimi-k2.5。配置片段大致如下{ models: { provider: custom, baseUrl: https://taotoken.net/api, apiKey: 你的 TaoToken Key, model: claude-sonnet-4-6 } }如果你主要用 Claude Code 做长期编码可以看看 Coding Plan它针对 Agent 类长任务做了额度优化。想先验证模型对话是否通用模型对话页面发一条测试消息即可。接入文档在 doc里面有各语言的调用示例。把模型和搜索都接好之后OpenClaw 的 Agent 才算真正具备“能查、能想、能写”的完整能力。Tavily 负责查TaoToken 上的模型负责想和写两者配合起来日常调研和编码辅助的体验会顺很多。