稗官无印1. 先搞清楚：为什么 OpenClaw 需要 Tavily 这个 Skill
1.1 OpenClaw 本身不联网，搜索是刚需
先聊一个很多刚接触 OpenClaw 的人容易忽略的问题：OpenClaw 这个开源智能体框架，核心能力是"调度"和"执行"，它本身并不自带联网搜索能力。你在本地部署好 OpenClaw、配好模型之后，让它写代码、整理文档、调用 API 都没问题，但一旦问它"帮我查一下最近三天某某产品的发布动态"，它大概率会卡住，或者只能基于模型训练时的旧知识硬答。
原因不复杂。大型语言模型的知识是静态的，训练时间点之后发生的事情它根本不知道。而 OpenClaw 作为个人智能体框架，它的价值恰恰在于"帮我干活"，活里面很大一部分需要实时信息：今日行情、最新文档、竞品动态、技术圈讨论。没有搜索能力，这个智能体就瘸了一条腿。
这时候就需要给 OpenClaw 装上一个"网络感知层"，也就是 Skill 体系里的搜索类 Skill。Tavily 是专门为 AI Agent 设计的搜索 API，OpenClaw 社区里大多数人配置的第一个 Skill 就是它。这个组合解决的核心问题就是：让智能体在回答问题时，能够实时去网上查资料，再把拿到的信息回传给模型，最后生成带实时依据的回答。
1.2 Tavily 与普通搜索 API 的区别（为什么选它）
我在最初选型的时候，其实先试过直接调普通搜索引擎的 API，也试过自己封装爬虫。最后换成 Tavily 不是没有原因的，用一张表来说清楚差异：
| 对比维度 | 普通搜索引擎 API | Tavily |
|---|---|---|
| 返回内容 | 一串链接，需要自己再解析 | 已经清理过的内容片段（标题、摘要、相关内容） |
| Agent 友好度 | 一般，结果格式偏向人阅读 | 专为 LLM 设计，结果可直接塞给模型 |
| 内容抽取 | 需要自己实现正文抽取 | 内置内容提取和去重 |
| 答案模式 | 无 | 可以选择返回一个直接生成的答案 |
| 精度控制 | 需要自己过滤广告/垃圾站 | 结果按相关性和权威性排序，质量更高 |
| 配置成本 | 接口文档长，参数复杂 | 一个 API Key，几十行配置搞定 |
简单说，Tavily 的设计思路是"让搜索结果的产出链路尽量短"。它把搜索、抓取、清洗、去重这几步都做在了 API 内部，你拿到的是一个结构化、干净的结果列表，直接喂给大模型或者作为工具的上下文都可以。这一点对于 OpenClaw 这种以"执行任务"为核心的框架来说特别重要——Agent 的上下文窗口本来就不宽裕，如果搜索结果还是满屏的 HTML 标签和广告链接，等于白白浪费 token。
另外要说一下，Tavily 本身不是一家刚冒出来的小公司，它是专门做"面向 AI 的搜索基础设施"的，很多知名的 Agent 框架默认都支持它。和直接自己爬网页相比，省掉了反爬、页面结构变化、去重、正文抽取这一大堆脏活。维护成本低很多。
1.3 适用场景与前提条件
配置 Tavily Skill 之后，OpenClaw 能做什么？结合我自己的使用体验，这些场景是最常用的：
- 实时资讯查询：让 Agent 帮你查最新的行业动态、产品发布、版本更新信息。
- 技术文档检索：写代码报错时，让 Agent 直接搜最新的 GitHub Issue 或官方文档。
- 竞品调研：让 Agent 同时搜索多个关键词，汇总各家产品的功能对比。
- 内容创作辅助：写文章前，让 Agent 先搜索一批参考资料，然后基于这些材料生成初稿。
- 常识性校验：不确定某个信息是否准确时，让 Agent 用搜索验证后再回答。
当然，配置之前你得先满足几个前提：一台能稳定运行 OpenClaw 的环境（本机或服务器均可）、一个 OpenAI 兼容/或其他受支持的模型 API 配置、以及一个有效的 Tavily API Key。这三个缺一不可，尤其是 API Key，这一步很多人漏掉，后面我会单独说。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 配置前需要准备的几件事
2.1 注册 Tavily 并获取 API Key
Tavily 官网的注册流程很简单，用邮箱或者 GitHub 账号就能登录。登录之后，进入控制台的 API Keys 页面，点击 Create New Key，给它起个名字（比如 openclaw），复制生成的那串字符串。这串 Key 就是你以后 OpenClaw 搜索时使用的凭证。
需要注意，Tavily 的 Key 有两种使用模式：一种是直接通过 API 调用，另一种是走 Tavily 的 MCP 服务端（如果你用的是支持 MCP 的客户端，可以走这条链路）。在 OpenClaw 里，社区主流做法是直接使用 REST API 调用，所以你的 Skill 本质上就是封装了一个对 api.tavily.com/search 这个接口的请求。
新注册用户一般会有免费的额度，具体查询次数以官网显示为准。日常个人使用绰绰有余，如果只是偶尔让 Agent 查点资料，基本用不完；如果重度使用，再考虑升级付费档位。
2.2 确认 OpenClaw 的 Skill 目录规范与版本要求
OpenClaw 的 Skill 体系，说白了就是"在指定目录里放一个符合规范的文件夹，里面包含一个说明文件和一个可执行脚本（或一套脚本）"。OpenClaw 启动时，会在配置中指定的 Skill 目录下扫描所有子目录，发现带有 skill 描述文件（一般是 SKILL.md）的文件夹，就会把它注册为可用 Skill。
这里有个重要的认知：Skill 文件放在什么位置，取决于你的 OpenClaw 版本。早期版本通常在部署目录下的 skills/ 文件夹里，后期版本越来越规范，一般会集中在用户目录下，比如 ~/.openclaw/skills/。拿到 OpenClaw 之后，先别急着放文件，打开你的配置文件确认一下 skills 目录路径。我见过太多人把 Skill 文件放错位置，结果怎么重启都不加载，最后才发现路径根本不对。
检查方法很简单：打开 OpenClaw 的用户级配置文件（YAML 格式），搜索 skills 字段，会看到类似这样的内容：
yaml复制skills:
directory: ~/.openclaw/skills
enabled: true
如果你看到的是默认值，那说明 Skill 目录就是 ~/.openclaw/skills，把 Tavily 相关文件丢进去即可。
2.3 配置原理：Skill 的本质是一个可执行模块
在动手之前，我想先花点时间把 Skill 的机制讲透，因为理解了原理，后面遇到报错你自己就能排。
OpenClaw 里的一个 Skill，本质上是一个由"描述文件 + 可执行代码"组成的模块。描述文件（SKILL.md）的核心作用不是给人看的文档，而是给模型看的工具说明书。模型读到这个文件，就知道"哦，我手里有一个叫 tavily_search 的工具，它接收哪些参数，能帮我干什么"。可执行代码则是真正去调用 Tavily API 的脚本，接收模型传来的参数，执行网络请求，返回格式化结果。
你可以把它理解成：模型是大脑，Skill 是一双手套。大脑看到工具箱里的说明（SKILL.md），知道手套能抓什么东西、怎么戴；真正去抓的时候，手套（脚本）负责和外部世界打交道。OpenClaw 本身是一个调度框架，它不关心你的 Skill 是用 Python 写的还是用 Node.js 写的，只要脚本能被执行，并且输入输出格式符合约定就行。
所以配置 Tavily Skill，本质上做三件事：把 Skill 文件放到 OpenClaw 能发现的地方，让模型知道这个工具的存在和用法，以及把 API Key 提供给脚本使用。后面所有操作都是围绕这三件事展开的。
3. 为 OpenClaw 配置 Tavily 搜索 Skill 的完整操作步骤
3.1 拉取 Skill 文件到正确目录
OpenClaw 社区里已经有现成的 Tavily Skill 实现，如果你用的是官方仓库或社区维护的版本，最简单的方式是直接 clone 或下载现成文件。以常见的方式为例：
bash复制# 进入你的 openclaw skills 目录（以 ~/.openclaw/skills 为例）
cd ~/.openclaw/skills
# 从仓库拉取 tavily skill（这里以社区常见仓库为例，实际按你所在社区的推荐地址为准）
git clone https://github.com/your-skill-repo/tavily-search-skill.git tavily-search
如果你拿到的压缩包，直接解压到 ~/.openclaw/skills/ 下就行。解压完之后，确认一下目录里是否包含 SKILL.md 文件和主脚本文件。如果从仓库拉下来之后发现文件名不叫 SKILL.md，记得改成这个标准名（具体名以你所用 OpenClaw 版本约定的文件名为准），因为 OpenClaw 扫描时就是靠识别这个文件名来判定"这是一个 Skill"。
安装完之后，可以顺手做一次结构检查，目录应该长这样：
text复制~/.openclaw/skills/
└── tavily-search/
├── SKILL.md
├── tavily_search.py # 主逻辑脚本，也可能是 .js 或 .sh
├── requirements.txt # Python 依赖描述
└── config.yaml # 可选，Skill 内部的行为配置
3.2 配置 API Key 与环境变量
Tavily 的 API Key 不适合直接硬编码在 Skill 脚本里，因为 Skill 文件可能随仓库更新，Key 会丢失，而且有泄露风险。正确做法是放在环境变量或 OpenClaw 的全局配置里。
最通用、最推荐的做法是写入 OpenClaw 启动时的环境变量文件（比如 .env 或你自己的 shell 配置文件），然后让 Skill 脚本从环境变量里读取：
bash复制# 写入你的 ~/.openclaw/.env 或 /etc/profile（取决于你的启动方式）
export TAVILY_API_KEY="tvly-你的密钥字符串"
如果你习惯在 OpenClaw 的 YAML 配置里统一管理密钥，也可以定义一个配置字段，然后让 Skill 脚本读取配置文件里的值。比如：
yaml复制# 在 OpenClaw 配置文件中
tavily:
api_key: "tvly-你的密钥字符串"
这里有一个非常容易踩的坑：很多 Skill 脚本认的环境变量名是 TAVILY_API_KEY，但你在配置文件里写成了 TAVILY_KEY，差一个字母，脚本读不到，就会一直报 401 Unauthorized 或者 API key not found。正确做法是：先看 Skill 脚本源码，确认它到底读取的是哪个变量名，然后再写入对应的配置。不要想当然。
3.3 调整 Skill 的行为参数（搜索深度、结果数量、领域过滤）
Tavily API 最有价值的地方，是它提供了几个关键的搜索参数，你在 Skill 的配置文件里可以按需调整。我常用的几个配置项解释一下：
search_depth（搜索深度）：basic 或 advanced。basic 速度快、token 消耗少，适合普通资讯查询；advanced 会返回更深入的内容，适合技术调研、竞品分析。代价是响应时间更长、结果内容更大，API 调用费也略高。日常用 basic 完全够，只有项目研究时才切 advanced。
max_results（结果数量）：控制返回几条搜索结果。默认 5，我推荐日常设置 3~5。数量多了不会让回答质量更高，只会让上下文塞太满，模型反而抓不住重点。
include_answer（是否返回直接答案）：Tavily 可以根据搜索结果直接生成一段简短答案。如果你希望 Agent 的反应更快、回答更直接，可以打开；如果希望 Agent 自己综合判断，就不开。
topic（搜索类型）：支持 general、news、finance 等。需要查最新动态时，建议用 news，它会优先返回新闻类网站的结果。比如让 Agent 查"OpenClaw 最近有什么更新"，用 news 明显比 general 结果准。
days（时间范围）：只搜索最近 N 天内的内容。这个参数对过滤旧信息特别有用，查产品发布时，限定 days: 30 能避开大量过时内容。
配置文件里可以这样设置：
yaml复制# tavily-search/config.yaml
search_depth: basic
max_results: 5
include_answer: true
topic: general
days: 7
我能给的最重要的一条调参建议是：不要一次开全所有高级参数。 刚开始把 search_depth 设成 basic、max_results 设为 5、topic 用 general，跑通链路之后再根据实际效果逐步微调。这样出了问题你才好定位是哪个环节造成的。
3.4 重启与加载验证
配置完文件之后，需要重启 OpenClaw 服务让它扫描到新的 Skill。这一步骤取决于你的启动方式：
如果是命令行前台启动，直接 Ctrl+C 停掉再重新运行。如果是用 systemd 或 Docker 部署，重启对应服务即可：
bash复制# 以 systemd 为例
sudo systemctl restart openclaw
重启之后不要急着使用，先确认 Skill 有没有被加载成功。启动日志里通常会输出类似 Loaded skill: tavily-search 或者 Found skill: tavily_search 的信息。如果你用的是 Control UI，可以在 Skill 管理页面看到新出现的 tavily-search 条目。
看到这个条目，说明 OpenClaw 已经认识这个 Skill 了，接下来进测试环节。
4. 验证是否真的生效：从日志到一次真实搜索
4.1 通过日志确认 Skill 被加载
验证 Skill 是否被加载，最直接的方法是看日志。很多人在这一步就翻车了：文件确实放在 skills/ 目录下了，但日志里完全没有出现这个 Skill 的名字。怀疑人生之前，先把日志翻到最后 100 行，重点看这几个关键字：
- Loaded skill 或 registered skill：出现这个，说明 Skill 注册成功。
- No skill found 或 skipped：说明 OpenClaw 发现了这个目录，但没认出来是 Skill，大概率是
SKILL.md文件缺失或命名不对。 - Error loading skill：说明这个 Skill 脚本本身有问题（依赖缺失、语法错误等）。
如果你用的版本支持 openclaw skills list 之类的 CLI 子命令，也可以直接跑一条命令查看当前已加载的 Skill 列表，比翻日志更直接。
4.2 用一条真实搜索指令测试效果
Skill 加载成功只是第一步，真正验证它能不能干活，得看模型能不能正确调用它。在 OpenClaw 对话界面里，给 Agent 发一条明确的搜索指令：
用 tavily 搜索一下最近一周关于 OpenClaw 的版本更新信息。
然后观察 Agent 的行为。理想情况下，你会看到两个关键现象：第一，Agent 识别出应该调用 tavily_search 这个 Skill，并且在回答前有一段类似"正在搜索..."的过程；第二，最终回答中带上了搜索结果里的具体信息，而不是凭空编造。
如果 Agent 回复"我没有搜索功能"或者直接给出一个不相关的回答，说明模型没有正确理解到 Skill 的调用方式。这时候问题大多出在 SKILL.md 的说明写得不够清晰，模型不知道怎么用。可以先手动在对话中告诉 Agent："你有一个工具叫 tavily_search，传入查询关键词就能获取搜索结果"，看它是否能理解并执行。
4.3 结果反馈解读与调参
测试通过后，先别急着开始用，花两分钟看一下实际返回的结果质量。我一般会做三件事：
第一，看结果的新鲜度。如果搜"最近一周"的内容，返回结果却是一年前的文章，说明 days 参数没有生效或者该 topic 下没有新内容。第二，看结果的准确性。如果返回的内容和问题完全不相关，检查一下是不是 topic 设置错了。第三，看结果的密度。如果一条搜索结果就占了巨长的 token，说明 include_raw_content 被打开了，正常情况下只留摘要就够，没必要把网页全文都拉进来。
调参没有标准答案，完全是"看场景下菜"。我自己是这么分的：
| 使用场景 | search_depth | max_results | topic | include_answer |
|---|---|---|---|---|
| 日常闲聊/知识问答 | basic | 3 | general | false |
| 写文章的素材搜集 | advanced | 8 | general | false |
| 查最新技术动态 | advanced | 5 | news | true |
| 快速找答案 | basic | 3 | general | true |
这套配置不是最优解，但它能覆盖我 90% 的使用场景。你可以根据自己的使用习惯调整，核心是每次调整只改一个参数，改完看效果再决定下一步。
5. 我踩过的坑与排查思路（建议收藏）
5.1 API Key 没生效，排查链路
这是我遇到最多的问题，也是最好排查的问题。如果 Agent 调用 tavily_search 后返回报错信息，先看错误码：
- 401 Unauthorized：几乎可以断定是 API Key 的问题。按这个顺序排查：确认环境变量是否真的注入了（
echo $TAVILY_API_KEY看有没有值）；确认 Skill 脚本读取的变量名和环境变量里的名字是否完全一致；确认 Key 复制时有没有多出空格或断行。 - 403 Forbidden：Key 本身可能有效，但相应的额度或权限被限制了，去 Tavily 控制台看账户状态。
- 429 Too Many Requests：请求太频繁，超出了速率限制。检查一下是不是 Skill 里没有做请求间隔设置，或者你的 Agent 在循环里反复调用搜索。
有一次我配了一个小时后还是 401，最后发现是因为我把 Key 写到了 ~/.bashrc，但 OpenClaw 是 systemd 服务，启动时根本没有加载 ~/.bashrc 的环境变量。后来把 Key 写进 systemd 服务文件里的 Environment 行，问题立刻解决。这个坑值得记住：环境变量注入的方式必须与你启动 OpenClaw 的方式一致。
5.2 Skill 文件放对目录却未被加载
这个问题的特征很迷惑：目录没错、文件看起来也对，但日志里就是没有这个 Skill。我排查过几次之后发现，最常见的原因有三个：
第一，主文件没有可执行权限。如果 Skill 是一个 Python 脚本，OpenClaw 需要以 python3 /path/to/skill.py 这种形式执行；如果 Skill 是编译好的二进制文件或 Shell 脚本，没有 +x 权限会直接执行失败。修复方式：
bash复制chmod +x ~/.openclaw/skills/tavish-search/tavish_search.py
第二，SKILL.md 文件的格式有问题。OpenClaw 对 SKILL.md 的解析依赖 frontmatter 结构，比如 name、description 这类的头信息。如果你不小心把 YAML 格式写错了（缩进错误、冒号后面没空格等），OpenClaw 解析失败就会跳过这个目录。用 YAML 语法检查工具过一遍，或者找一个已知正常工作的 Skill 的 SKILL.md 对照一下头部格式。
第三，Skill 名字和已有 Skill 冲突。某个版本之前，我同时装了两个功能相近的搜索 Skill，一个是 tavily-search，一个是 web-search，结果它们在 OpenClaw 的注册表里出现冲突，导致两个都没加载成功。改名之后就好了。
5.3 搜索返回空结果的常见原因
Skill 正常工作了，但搜索结果为空，这种问题比完全不加载更让人崩溃。根据我的排查经验，原因大概率出在以下几个方面：
- 关键词处理不当：Agent 传给 Skill 的搜索词过于复杂，包含了太多布尔逻辑或引号，Tavily 处理不了，返回空列表。这时候把搜索词精简成 3~5 个核心关键词就好。
- 时间范围太窄：
days: 1表示只搜一天内，在很多垂直领域可能真的没新内容。放宽到 7 天或 30 天试试。 - topic 类型太窄：如果你设置了
topic: news，但搜的内容偏知识类（不是新闻类），结果可能是空的。改成general再试。 - 网络层面的偶发问题：偶尔 API 请求超时，Skill 脚本如果没做重试机制，你会看到空结果或超时报错。可以在 Skill 脚本里加一个简单的重试逻辑：
python复制import time
for attempt in range(3):
try:
result = tavily_search(query, **params)
break
except Exception as e:
if attempt == 2:
raise e
time.sleep(2)
5.4 与 Agent 调用模型的兼容性问题
这个坑更隐蔽，它不在 Skill 本身，而在 OpenClaw 的模型调度层。有些模型对工具调用的指令遵循能力比较弱，或者对参数格式有严格要求。具体表现是：Agent 明明加载了 Skill，也知道该用，但在构造参数时传错了格式，导致 Skill 脚本报错。
我之前遇到过一种情况：模型把 query 参数传成了 JSON 对象而不是字符串，脚本直接报 TypeError。排查半天，最后通过给 SKILL.md 的 description 里加上"query 参数必须是一个纯字符串"这样的强化说明，情况才好转。
还有一点，如果你用的模型上下文窗口偏小，而搜索结果又被设置得很多（比如 max_results: 10 且 include_raw_content: true），模型会因为上下文溢出而报错，或干脆忽略工具返回的结果。遇到这种问题，先降低 max_results，关闭 include_raw_content，再试。
6. 进阶使用：让 Tavily 搜索真正融入你的日常工作流
6.1 组合 Skill：搜索 → 摘要 → 写作
单个搜索 Skill 装好之后，它的潜力才算发挥出三成。OpenClaw 真正的优势在于多个 Skill 可以组合使用。我平时最常用的组合是"搜索 + 摘要 + 写作"三段式。
比如你让 Agent 写一份"OpenClaw 最新功能梳理"的博客草稿，它会先调用 tavily_search 搜索"OpenClaw 最近更新"，拿到几篇来源文章；然后调用摘要类 Skill 或直接让模型压缩成要点；最后基于这些要点生成文章初稿。整个过程不需要你手动打开任何一个网页，Agent 把资料收集、整理、成稿的链路都串起来了。
实现这个组合不需要额外配置，只要你把多个 Skill 都装好，模型在对话中会自己判断什么时候该调哪个工具。你能做的就是给 Agent 一个足够清晰的任务描述，让它知道"先查资料，再写总结"这个先后顺序。
6.2 自定义指令，让搜索更精准
用好 Tavily 的关键不在于参数调得多花哨，而在于你能不能把"搜索意图"准确传达给模型。我习惯在 OpenClaw 的系统指令里加一小段话：
当用户要求查询实时信息时，先使用 tavily_search 获取结果，再结合结果回答。搜索关键词要精简，优先使用用户原话中的核心术语。如果搜索结果为空，尝试更换同义词后重新搜索一次。
就这么简单的一段指令，让整个 Agent 的搜索行为一下子变得靠谱了很多。之前模型经常搜一些特别绕的句子，现在会先提炼关键词，搜不到也知道换词重试。这也算是不改一行代码、纯靠 prompt 提升效果的小技巧。
6.3 成本控制与限额管理
最后聊一下成本。Tavily 免费额度对个人使用是够的，但如果你把 OpenClaw 部署成团队公用的智能体，或者用来高频巡检网站信息，难免会碰到额度告警。我的建议是三条：
第一，按场景限制 max_results。日常问答用 3 条结果就够，没必要每问一次就拉回 10 条结果。多出的结果不仅费 token，也费 API 额度。第二，给 Skill 加一个请求频率上限。在脚本里做一个简单的限流，比如 10 秒内最多请求一次，避免 Agent 在循环任务里疯狂调用。第三，定期去控制台查看用量。Tavily 控制台会显示每天/每月的请求数，养成每周看一次的习惯，不要等到收到扣款通知才慌。
另外一个省钱思路：不是所有问题都要搜索。像"Python 里怎么读文件"这种成熟的知识，模型本身就知道，没必要搜。你可以给 Agent 加一条规则："只有涉及实时信息或模型可能不知道的新内容时，再调用搜索工具"。这样能让 API 调用量下降一半以上，回答速度也更快。
说实话，配置 Tavily Skill 本身不算一个特别复杂的操作，真正有门槛的是理解 Skill 体系的工作原理——文件放哪、环境变量怎么注、模型怎么发现工具、参数怎么传。把这些弄明白之后，你装的每一个 Skill 都是一个套路，只不过换了个脚本和描述文件而已。
另外分享一个我后期的使用习惯：我会在 OpenClaw 的配置里把 Tavily 设为多个 Agent 共享的基础 Skill，这样不管是我自己对话用的 Agent，还是定时跑任务的自动化 Agent，都能复用搜索能力，避免了重复配置。在使用过程中如果碰到 Skill 偶尔返回异常，别急着怪 Skill 本身，先看一眼是不是 Tavily 服务端在做短暂的维护或限流，等个几分钟再试，往往自己就恢复了。