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. 配置环境变量：
   ```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
- 自动选择最优搜索源
- 提高搜索成功率