message/tavily-search-skill-plan.md

Tavily Search Skill 实现方案

记录时间

2026-03-01 22:00

来源

https://lua.ren/openclaw/2026-02-21-openclaw-tavily-skills-web-search/index.html

---

📌 问题背景

OpenClaw 默认搜索的问题

• OpenClaw 默认的 web_search 走 Brave Search API
• 如果没有配置 Brave API Key，就无法稳定检索网页
• 设计目标是"轻量搜索工具"，不会自动申请/内置 Key

解决方案

使用 Tavily Search API，通过自定义 Skill 接入 OpenClaw

---

🎯 实现方案

1. 获取 Tavily API Key

1. 访问 Tavily 控制台
2. 注册并获取 API Key
3. 配置环境变量：

   export TAVILY_API_KEY="your-api-key"
   

2. 创建自定义 Skill

Skill 结构

skills/
└── tavily-search/
    ├── SKILL.md          # Skill 说明文档
    └── scripts/
        └── search.mjs    # 搜索脚本

SKILL.md 内容

# Tavily Search Skill

## 目标
使用 Tavily Search API 进行网页搜索，返回结构化搜索结果。

## 使用方法
"用 tavily-search 检索：{查询词}"

## 输出要求
1. 返回最多 5 条结果
2. 每条结果包含：标题、URL、摘要
3. 按相关性排序
4. 附上引用

## 约束
- 使用环境变量 TAVILY_API_KEY
- search_depth: basic（成本可控）
- max_results: 5
- include_raw_content: false（避免过大 payload）

search.mjs 脚本

#!/usr/bin/env node

const TAVILY_API_KEY = process.env.TAVILY_API_KEY;

if (!TAVILY_API_KEY) {
  console.error('Error: TAVILY_API_KEY not set');
  process.exit(1);
}

const args = process.argv.slice(2);
const query = args[0];
const numResults = args[1] || '5';

if (!query) {
  console.error('Usage: node search.mjs "<query>" [num_results]');
  process.exit(1);
}

const response = await fetch('https://api.tavily.com/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: TAVILY_API_KEY,
    query: query,
    search_depth: 'basic',
    max_results: parseInt(numResults),
    include_raw_content: false,
  }),
});

const data = await response.json();

if (data.error) {
  console.error(`Error: ${data.error}`);
  process.exit(1);
}

// 格式化输出
data.results.forEach((item, index) => {
  console.log(`\n${index + 1}. ${item.title}`);
  console.log(`   URL: ${item.url}`);
  console.log(`   Snippet: ${item.snippet}`);
});

3. 配置 OpenClaw

环境变量

export TAVILY_API_KEY="your-api-key"

重要提醒：

• 如果 OpenClaw 以 daemon/systemd/launchd 方式运行，需要在该服务环境里配置
• 不要把 API Key 写进 Skill 文档或提交到仓库

---

✨ 优势

1. 结构化搜索结果

• 标题、URL、摘要、原文片段
• 更利于模型推理和总结

2. 接入成本低

• 拿到 API Key 即可使用
• 不需要修改 OpenClaw 内置代码

3. 与 Skill 非常匹配

• Skill 本质是"可执行操作手册"
• Tavily 是简单的 HTTP API

4. 可维护性强

• 对版本升级友好
• 可按需固化搜索深度、返回条数等参数

---

📊 使用示例

基础搜索

"用 tavily-search 检索：OpenClaw 自我进化"

定向搜索

"用 tavily-search 检索：site:github.com openclaw"

限制结果数

"用 tavily-search 检索：AI agent 自我进化 -n 3"

---

🔧 高级用法

1. 搜索深度选择

• basic: 快速搜索，成本低
• advanced: 深度搜索，质量高

2. 原文内容抓取

• include_raw_content: true - 返回完整内容
• 注意：可能增大 payload

3. 网站限制

• include_domains: 限制搜索域名
• exclude_domains: 排除域名

---

📈 对比：Brave vs Tavily

特性	Brave Search	Tavily
定位	轻量搜索工具	给 Agent/LLM 用的 Search API
结果结构化	中等	高
接入难度	需要配置 Key	拿到 Key 即可用
成本	未知	有免费额度
适合场景	默认搜索	Skill 方式集成

---

🚀 下一步

阶段 1：基础实现（1-2 小时）

1. ✅ 获取 Tavily API Key
2. ✅ 创建 Skill 目录结构
3. ✅ 编写 SKILL.md
4. ✅ 编写 search.mjs 脚本
5. ✅ 测试基本功能

阶段 2：功能增强（2-3 小时）

1. ✅ 添加更多搜索参数
2. ✅ 优化输出格式
3. ✅ 错误处理
4. ✅ 缓存机制

阶段 3：集成优化（1-2 小时）

1. ✅ 与现有工具集成
2. ✅ 搜索结果缓存
3. ✅ 智能搜索策略

---

⚠️ 注意事项

1. API Key 安全

   • 只放环境变量
   • 不要提交到仓库

2. 环境变量配置

   • 确保运行 OpenClaw 的服务环境有正确的 Key
   • daemon/systemd 启动时需要特殊配置

3. 成本控制

   • 使用 search_depth: basic
   • 限制 max_results: 5
   • 定期监控 API 调用次数

---

📝 记录历史

• 2026-03-01 22:00 - 创建实现方案
• 2026-03-01 22:00 - 整理技术细节

---

🎯 预期效果

实现 Tavily Search Skill 后：

1. ✅ OpenClaw 可以稳定搜索网页
2. ✅ 搜索结果结构化，便于模型处理
3. ✅ 成本可控（Tavily 有免费额度）
4. ✅ 可扩展性强（支持更多参数）

---

💡 延伸思考

智能搜索策略

• 根据查询类型选择搜索工具
• 简单查询用 Tavily 复杂查询用多工具组合

搜索结果缓存

• 缓存常见查询结果
• 减少重复 API 调用
• 降低成本

多搜索源

• Tavily + Brave + 其他搜索 API
• 自动选择最优搜索源
• 提高搜索成功率