# Tavily 配置总结 - 桐哥

**日期:** 2026-03-07  
**状态:** ✅ 已完成

---

## 配置方式确认

**Tavily 通过 Plugin 方式加载**（不是 Skill）

### 为什么是 Plugin 不是 Skill？

| 特性 | Skill | Plugin | Tavily 选择 |
|------|-------|--------|-----------|
| 用途 | 预定义功能（搜索、天气等） | 自定义工具/生命周期钩子 | ✅ Plugin |
| 清单文件 | `skill.json` (Clawhub) | `openclaw.plugin.json` | ✅ 有 |
| 实现文件 | 通常无（内置） | `index.js` | ✅ 有 |
| 加载方式 | `skills.entries` | `plugins.load.paths` + `plugins.entries` | ✅ Plugin |

---

## 正确配置结构

### 1. 文件结构
```
/root/.openclaw/workspace/skills/tavily/
├── openclaw.plugin.json  ✅ 必需（插件清单）
├── index.js              ✅ 必需（工具实现）
├── skill.json            ❌ 可选（Clawhub 元数据）
└── SKILL.md              ✅ 推荐（文档）
```

### 2. 桐哥的配置 (`/root/.openclaw-tongge/openclaw.json`)

```json
{
  "skills": {
    "entries": {
      "find-skills-robin": { "enabled": true },
      "mem0-integration": { "enabled": true },
      "active-learning": { "enabled": true }
      // 注意：tavily 不在 skills.entries 中
    }
  },
  "plugins": {
    "load": {
      "paths": [
        "/root/.openclaw/workspace/skills/mem0-integration",
        "/root/.openclaw/workspace/skills/tavily"  // ← Tavily 在这里
      ]
    },
    "entries": {
      "tavily": { "enabled": true },  // ← 在这里启用
      "mem0-integration": { ... },
      "qwen-portal-auth": { "enabled": true }
    }
  }
}
```

---

## 测试步骤

### 测试 1: 服务启动
```bash
systemctl --user status openclaw-gateway-tongge
# 应该显示 active (running)
```

### 测试 2: 插件加载
```bash
journalctl --user -u openclaw-gateway-tongge -n 30 | grep -i tavily
# 应该看到插件加载成功
```

### 测试 3: Telegram 功能测试

在 Telegram 中对 `@tongge_chat_bot` 发送：

**简单测试:**
> 用 tavily 搜索一下今天的人工智能新闻

**预期回复:**
- 桐哥调用 tavily_search 工具
- 返回搜索结果（标题、URL、摘要）
- 可能包含 AI 生成的总结

**深度测试:**
> 帮我研究一下 2026 年最新的 AI 发展趋势，用 tavily 搜索，要详细一点

**预期回复:**
- 使用 `search_depth: advanced`
- 返回多个来源的结果
- 有综合性的分析总结

---

## 常见问题排查

### 问题 1: 桐哥说没有 Tavily 工具

**原因:** 插件未正确加载

**解决:**
```bash
# 1. 检查 openclaw.plugin.json 是否存在
ls /root/.openclaw/workspace/skills/tavily/openclaw.plugin.json

# 2. 检查 plugins.load.paths 是否包含 tavily
cat /root/.openclaw-tongge/openclaw.json | grep -A 5 '"load"'

# 3. 重启服务
systemctl --user restart openclaw-gateway-tongge

# 4. 查看日志
journalctl --user -u openclaw-gateway-tongge -n 50 | grep -i plugin
```

### 问题 2: Tavily API 错误

**原因:** API Key 无效或网络问题

**解决:**
```bash
# 检查 API Key 配置
cat /root/.openclaw-tongge/openclaw.json | grep TAVILY

# 测试 API Key 是否有效
curl -X POST https://api.tavily.com/search \
  -H "Content-Type: application/json" \
  -d '{"api_key": "tvly-dev-...", "query": "test"}'
```

### 问题 3: 搜索超时

**原因:** 网络问题或 Tavily 服务不可用

**解决:**
- 检查服务器网络连接
- 尝试 `search_depth: basic`（更快）
- 减少 `max_results` 数量

---

## API 参数说明

桐哥使用 Tavily 时可以指定：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | string | 必需 | 搜索关键词 |
| `search_depth` | string | `"basic"` | `basic` (快) 或 `advanced` (详细) |
| `topic` | string | `"general"` | `general` 或 `news` |
| `max_results` | number | `5` | 结果数量 (1-10) |
| `include_answer` | boolean | `true` | 包含 AI 总结 |

---

## 下次新增 Agent 时的检查清单

- [ ] 创建 `openclaw.plugin.json`（不是 `skill.json`）
- [ ] 创建 `index.js` 实现工具逻辑
- [ ] 在 `plugins.load.paths` 中添加插件路径
- [ ] 在 `plugins.entries` 中启用插件
- [ ] **不要**在 `skills.entries` 中重复配置
- [ ] 运行 `openclaw doctor` 验证配置
- [ ] 重启服务并检查日志
- [ ] Telegram 测试功能

---

**最后更新:** 2026-03-07  
**维护者:** Eason (陈医生)