记录 Tavily Search Skill 实现方案
This commit is contained in:
267
tavily-search-skill-plan.md
Normal file
267
tavily-search-skill-plan.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# 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. 配置环境变量：
|
||||
```bash
|
||||
export TAVILY_API_KEY="your-api-key"
|
||||
```
|
||||
|
||||
### 2. 创建自定义 Skill
|
||||
|
||||
#### Skill 结构
|
||||
```
|
||||
skills/
|
||||
└── tavily-search/
|
||||
├── SKILL.md # Skill 说明文档
|
||||
└── scripts/
|
||||
└── search.mjs # 搜索脚本
|
||||
```
|
||||
|
||||
#### SKILL.md 内容
|
||||
```markdown
|
||||
# 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 脚本
|
||||
```javascript
|
||||
#!/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
|
||||
|
||||
#### 环境变量
|
||||
```bash
|
||||
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
|
||||
- 自动选择最优搜索源
|
||||
- 提高搜索成功率
|
||||
Reference in New Issue
Block a user