Openclaw实战篇(四):Tavily API 搜索技能配置与优化实战

引言

Tavily 是专为 AI 优化的搜索引擎，支持结构化结果、时间范围过滤、主题过滤等功能。本文复盘了 Tavily API 从注册、配置到优化的完整流程，包含真实踩坑记录和解决方案。

核心价值： 结构化返回、时间过滤、主题过滤、AI 摘要

一、需求接收与拆解

1.1 原始需求

在汽车行业晨报项目中，需要：

1. 自动搜索全网新闻（每日）

2. 按分类搜索（6 大分类）

3. 返回结果带原始链接

4. 支持时间范围过滤（day/week）

1.2 任务拆解

总计耗时： 约 40 分钟

二、Tavily 账号注册

2.1 注册流程

1. 访问官网：https://tavily.com/

2. 点击「Sign Up」注册账号

3. 验证邮箱（必须）

4. 登录 Dashboard

2.2 获取 API Key

操作步骤：

1. 登录后进入 Dashboard

2. 选择「API Keys」页面

3. 点击「Create API Key」

4. 复制 Key（格式：tvly-dev-xxxxxxxxxxxxxxxxxxxxxxxx）

⚠️ 安全提示： API Key 属于敏感信息，需脱敏存储！

2.3 免费额度

建议： 个人使用 Free 套餐足够。

三、OpenClaw 配置

3.1 配置文件

编辑 ~/.openclaw/openclaw.json：{  "plugins": {    "entries": {      "tavily": {        "enabled": true,        "config": {          "webSearch": {            "apiKey": "tvly-dev-****...****"          }        }      }    }  }}

3.2 命令行方式（推荐）

openclaw config set plugins.entries.tavily.config.webSearch.apiKey "tvly-dev-xxxxx" --jsonopenclaw gateway restart

3.3 验证配置

tavily_search --query "test" --max_results 1

返回结果即表示配置成功。

四、搜索词优化技巧

4.1 中英文对比

测试结果：

结论： 英文搜索词覆盖更广，返回质量更高。

4.2 分类搜索词配置

4.3 时间范围参数

time_range = "day"     # 今天（晨报推荐）time_range = "week"    # 本周（周报推荐）time_range = "month"   # 本月（月报推荐）

五、常见错误排查

5.1 错误 1：返回结果为空

现象：

{  "count": 0,  "results": []}

解决方案：

1. 改用英文搜索词

2. 扩大时间范围（week）

3. 简化搜索词

5.2 错误 2：snippet 为空

现象：

{  "title": "文章标题",  "snippet": "",  "url": "https://..."}

解决方案：

# 如果 snippet 为空，使用 title 兜底if len(clean_snippet) < 10:    clean_snippet = title

5.3 错误 3：API Key 无效

现象：

Error: web_search (tavily) needs a Tavily API key

解决方案：

1. 检查配置文件

2. 重启网关

六、经验总结

6.1 关键成功因素

1. 英文搜索词：覆盖更广，质量更高

2. 时间范围合理：日报用 day，周报用 week

3. 错误兜底机制：snippet 为空时用 title

6.2 踩坑记录

6.3 可复用场景

• 新闻搜索（晨报系统）

• 竞品监控

• 舆情分析

• 技术趋势分析

七、系统状态

结语

Tavily API 配置简单，搜索质量高，特别适合 AI 驱动的新闻搜索、竞品监控、舆情分析等场景。核心技巧在于使用英文搜索词、合理设置时间范围、做好错误兜底。