OpenClaw配置Tavily 搜索 Skill 完整指南教程

优先级 1：Tavily       → 高质量结构化结果，1000 次/月，日常主力
优先级 2：SearXNG + Jina → 免费无限次，兜底 / 批量搜索场景
优先级 3：Bocha         → 600+ 次余额，应急备用

npm_config_registry=https://registry.npmjs.org npx clawhub@latest search tavily

openclaw-tavily-search  Tavily 搜索  (3.707)
tavily-tool             Tavily       (3.603)
liang-tavily-search     Tavily Search (3.522)
tavily-web-search-for-openclaw  Tavily Web Search Skill for OpenClaw 🦀  (3.505)

npm_config_registry=https://registry.npmjs.org npx clawhub@latest install openclaw-tavily-search

openclaw skills list | grep -i tavily
# 预期输出：
# ✓ ready │ 📦 tavily-search │ Web search via Tavily API (alternative to Brave)...

mkdir -p ~/.openclaw/skills/tavily-search/scripts
# 从 GitHub 下载（如果你的服务器能访问 GitHub）
curl -sL <https://raw.githubusercontent.com/openclaw/skills/main/skills/arun-8687/tavily-search/SKILL.md> \\
  -o ~/.openclaw/skills/tavily-search/SKILL.md
# 确认下载成功
cat ~/.openclaw/skills/tavily-search/SKILL.md | head -20

cat > ~/.openclaw/skills/tavily-search/SKILL.md << 'EOF'
---
name: tavily
description: AI-optimized web search via Tavily API. Returns concise, relevant results for AI agents.
homepage: <https://tavily.com>
metadata: {"clawdbot":{"emoji":"🔍","requires":{"bins":["node"],"env":["TAVILY_API_KEY"]},"primaryEnv":"TAVILY_API_KEY"}}
---
# Tavily Search
AI-optimized web search using Tavily API. Designed for AI agents - returns clean, relevant content.
## Search
`bash
node {baseDir}/scripts/search.mjs "query"
node {baseDir}/scripts/search.mjs "query" -n 10
node {baseDir}/scripts/search.mjs "query" --deep
node {baseDir}/scripts/search.mjs "query" --topic news
`
EOF

cat > ~/.openclaw/skills/tavily-search/scripts/search.mjs << 'EOF'
#!/usr/bin/env node
import https from "https";
const API_KEY = process.env.TAVILY_API_KEY;
if (!API_KEY) {
  console.error("Error: TAVILY_API_KEY environment variable is not set.");
  process.exit(1);
}
const args = process.argv.slice(2);
let query = "";
let maxResults = 5;
let searchDepth = "basic";
let topic = "general";
for (let i = 0; i < args.length; i++) {
  if (args[i] === "-n" && args[i + 1]) { maxResults = parseInt(args[i + 1]); i++; }
  else if (args[i] === "--deep") { searchDepth = "advanced"; }
  else if (args[i] === "--topic" && args[i + 1]) { topic = args[i + 1]; i++; }
  else if (!args[i].startsWith("-")) { query = args[i]; }
}
if (!query) {
  console.error("Usage: node search.mjs \\"query\\" [-n count] [--deep] [--topic news|general|finance]");
  process.exit(1);
}
const payload = JSON.stringify({
  api_key: API_KEY,
  query,
  max_results: maxResults,
  search_depth: searchDepth,
  topic,
  include_answer: true
});
const req = https.request("<https://api.tavily.com/search>", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) }
}, (res) => {
  let data = "";
  res.on("data", (chunk) => data += chunk);
  res.on("end", () => {
    try {
      const result = JSON.parse(data);
      if (result.answer) {
        console.log("## Answer\\n");
        console.log(result.answer + "\\n");
      }
      if (result.results && result.results.length > 0) {
        console.log("## Sources\\n");
        result.results.forEach((r, i) => {
          console.log(`${i + 1}. **${r.title}**`);
          console.log(`   URL: ${r.url}`);
          if (r.content) console.log(`   ${r.content.slice(0, 200)}...`);
          console.log();
        });
      }
    } catch (e) {
      console.error("Failed to parse response:", data);
    }
  });
});
req.on("error", (e) => console.error("Request failed:", e.message));
req.write(payload);
req.end();
EOF

# 检查目录结构（应有 2 个文件）
find ~/.openclaw/skills/tavily-search/ -type f
# 预期输出：
# /root/.openclaw/skills/tavily-search/SKILL.md
# /root/.openclaw/skills/tavily-search/scripts/search.mjs
# 用 openclaw 内置命令确认 Skill 已识别
openclaw skills list | grep -i tavily
# 预期输出包含：✓ ready │ 📦 tavily

# 方法一：用 Python 脚本安全写入（推荐）
python3 << 'PATCH'
import json, shutil
API_KEY = "tvly-你的实际Key"  # ← 替换为你的 Tavily API Key
filepath = "/root/.openclaw/openclaw.json"
# 备份
shutil.copy2(filepath, filepath + ".bak.pre-tavily")
print(f"已备份到 {filepath}.bak.pre-tavily")
with open(filepath, "r", encoding="utf-8") as f:
    config = json.load(f)
if "env" not in config:
    config["env"] = {}
if "TAVILY_API_KEY" in config["env"]:
    print("TAVILY_API_KEY 已存在，跳过")
else:
    config["env"]["TAVILY_API_KEY"] = API_KEY
    with open(filepath, "w", encoding="utf-8") as f:
        json.dump(config, f, ensure_ascii=False, indent=2)
    print("✅ 已将 TAVILY_API_KEY 写入 openclaw.json")
print("\\n当前 env 节的 key 列表：")
for key in config["env"]:
    print(f"  - {key}")
PATCH

# 同步到 systemd（必须！否则新配置不生效）
openclaw gateway install --force
# 重启 Gateway
openclaw gateway restart
# 等待启动后验证
sleep 5
cat /proc/$(pgrep -f openclaw-gateway)/environ | tr '\\0' '\\n' | grep -i tavily | sed 's/=.*/=******/'

TAVILY_API_KEY=******

python3 << 'PATCH'
filepath = "/root/.openclaw/workspace/AGENTS.md"
with open(filepath, "r", encoding="utf-8") as f:
    content = f.read()
old_block = """## 搜索工具
- ✅ 优先使用 **SearXNG**（<http://localhost:8080>）进行网络搜索，免费无限额
- ✅ 网页全文阅读使用 **Jina Reader**（r.jina.ai）
- ❌ **禁止使用 bocha-web-search**（已弃用，额度有限）
- 搜索失败时，尝试使用 Jina Reader 直接读取目标网站
- 搜索结果要标注来源 URL 和时间"""
new_block = """## 搜索工具与降级策略
### 搜索优先级
- ✅ **首选 Tavily**（tavily_search）：AI 优化的结构化搜索结果，每月 1000 次免费额度
- ✅ **备用 SearXNG**（<http://localhost:8080>）：免费无限额，Tavily 不可用时自动切换
- ✅ 网页全文阅读使用 **Jina Reader**（r.jina.ai）
- ⚠️ **Bocha**（bocha-web-search）：仅在 Tavily 和 SearXNG 都失败时作为最后手段
- 搜索结果要标注来源 URL 和时间
### 自动降级规则（重要！必须严格遵守）
1. 搜索时**优先调用 tavily_search**
2. 如果 Tavily 返回错误（429 额度耗尽、超时、网络错误等），**立即改用 SearXNG 重新搜索同一 query**，不要停下来告诉用户搜索失败
3. 如果 SearXNG 也失败，尝试用 Jina Reader 直接读取目标 URL
4. 如果 Bocha 可用且前面的都失败了，使用 Bocha 作为最后手段
5. **只有所有搜索方式都失败时，才告知用户搜索遇到问题**
6. 降级时在回复末尾简要注明实际使用的搜索工具（如"数据来源：Tavily"或"数据来源：SearXNG（Tavily 暂不可用）"）"""
if old_block in content:
    content = content.replace(old_block, new_block)
    with open(filepath, "w", encoding="utf-8") as f:
        f.write(content)
    print("✅ 搜索工具段落已替换（含降级策略）")
else:
    print("❌ 未找到匹配的旧内容，可能已修改过")
PATCH

python3 << 'PATCH2'
filepath = "/root/.openclaw/workspace/AGENTS.md"
with open(filepath, "r", encoding="utf-8") as f:
    content = f.read()
changes = 0
# 修改 researcher 描述
old = "（使用 SearXNG + Jina Reader）"
new = "（优先 Tavily，备用 SearXNG + Jina Reader）"
if old in content:
    content = content.replace(old, new)
    changes += 1
# 修改 trader 描述
old = "（使用 TuShare + SearXNG）"
new = "（使用 TuShare + Tavily，备用 SearXNG）"
if old in content:
    content = content.replace(old, new)
    changes += 1
# 修改子 Agent 搜索规则
old = "- 所有子 Agent 搜索时必须使用 **SearXNG**（<http://localhost:8080>）"
new = "- 所有子 Agent 搜索时优先使用 **Tavily**（tavily_search），不可用时降级到 **SearXNG**（<http://localhost:8080>）"
if old in content:
    content = content.replace(old, new)
    changes += 1
with open(filepath, "w", encoding="utf-8") as f:
    f.write(content)
print(f"✅ 完成 {changes} 处修改")
PATCH2

openclaw gateway restart

tail -100 /tmp/openclaw/openclaw-2026-03-15.log | grep -i "web_search\\|tavily\\|error\\|failed"

[tools] web_search failed: fetch failed
[tools] browser failed: timed out

用户说“帮我搜一下...”
    ↓
Agent 调用内置 web_search 工具（Brave 后端）
    ↓
Brave Search 在国内被墙 → fetch failed
    ↓
Agent 降级到 SearXNG Skill  ✅ 成功
    ↓
返回结果，标注“数据来源：SearXNG（Tavily 暂不可用）”
❗ Tavily Skill 在整个过程中从未被调用

当前（OpenClaw 2026.3.8）          未来（支持 MCP 后）
──────────────────────          ───────────────────────
内置 web_search (Brave) ❌       openclaw mcp add tavily
SearXNG Skill ✅ (降级生效)     Tavily 注册为原生搜索工具
Tavily Skill ✓ ready 但不被调用  Agent 直接调用 tavily_search
                               + tavily_extract / crawl / research

openclaw mcp add <https://mcp.tavily.com/mcp?tavilyApiKey=$TAVILY_API_KEY>
openclaw gateway restart

用 Tavily 搜索一下今天的 A 股市场新闻

用 Tavily 搜索：2026年3月A股市场走势分析

用 SearXNG 搜索：2026年3月A股市场走势分析

搜索最近一周的半导体行业动态，找到最相关的文章后阅读全文给我总结

# 直接测试 Tavily API 是否可用
curl -s <https://api.tavily.com/search> \\
  -H "Content-Type: application/json" \\
  -d '{
    "api_key": "'$TAVILY_API_KEY'",
    "query": "A股今日行情",
    "max_results": 3
  }' | python3 -m json.tool | head -30

用户在飞书发消息：“帮我搜一下...”
    ↓
Agent（kimi-k2.5 / sonnet4.6）分析意图
    ↓
内置 web_search（Brave） ❌ fetch failed（国内被墙）
    ↓ 自动降级
┌──────────────┬──────────────┬──────────────┬──────────────┐
│ SearXNG ⭐主力 │ Jina Reader  │ TuShare      │ Bocha 应急   │
│ 搜索兜底       │ 网页阅读     │ 股票/行情    │ 最后手段     │
│ Docker 本地   │ 云端 API     │ Python API   │ 600+次余额  │
├──────────────┼──────────────┼──────────────┼──────────────┤
│ localhost    │ r.jina.ai    │ api.waditu   │ api.bocha    │
│ :8080/search │              │ .com         │ .ai          │
├──────────────┼──────────────┼──────────────┼──────────────┤
│ 免费无限次   │ Markdown     │ 股票数据      │ 有限额度      │
│ 质量良好      │ 需指定 URL   │ 需指定代码    │ 仅应急使用    │
└──────────────┴──────────────┴──────────────┴──────────────┘
    ↓
Agent 整理信息，回复用户
⭐ Tavily Skill 已安装且 API Key 已配置，但因内置工具优先级问题未被 Agent 调用
⭐ 等 OpenClaw 支持 MCP 后可一键升级
定时推送（crontab）独立通道：
crontab → a-stock-daily-push.py → Bocha + 财联社 → AI 总结 → 飞书