Tool Finder 🦞

统一搜索 ClawHub skills 和 Smithery MCP servers 的工具发现引擎。

🎯 自动触发规则（AI 必读）

安装本技能后，AI 会自动在以下场景使用 tool-finder：

触发关键词

为什么不直接用 clawhub 命令？

结论：tool-finder 是 clawhub 的智能封装，搜索结果更精准！

🎯 何时使用（AI 必读）

看到以下关键词 → 立即调用 tool-finder：

⚡ 快速命令参考

# 搜索（默认搜索全部来源，显示评分和推荐）
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "<query>"

# 只搜索 skill（按评分降序排列）
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "<query>" --type skill

# 只搜索 MCP
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "<query>" --type mcp

# 限制数量
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "<query>" --limit 5

# 精确搜索（知道技能名时）
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "agent-orchestrator" --exact

# 显示详细错误信息
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "<query>" --verbose

# 显示所有结果（包括低评分 < 2.0）
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "<query>" --all

# 安装
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh install <name> --type skill
~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh install <name> --type mcp

📋 激活条件详解

✅ 必须触发的场景

1. 用户明确要找工具

   • "帮我找个能搜索 web 的 skill"
   • "有什么 MCP 可以连接 GitHub？"
   • "推荐一个数据库工具"

2. 用户提到工具市场

   • "ClawHub 上有什么好工具？"
   • "Smithery 上有搜索 MCP 吗？"

3. 用户要安装/卸载

   • "安装 tavily-search"
   • "帮我装个 GitHub MCP"

4. 当前技能不足

   • 用户需要的功能当前没有合适 skill/MCP
   • 你需要推荐替代方案

❌ 不要触发的场景

1. 工具已存在，只是不会用

   • "怎么用 weather skill？" → 直接教用法，别搜索

2. 通用问题

   • "今天天气怎么样" → 直接用 weather 工具

3. 闲聊

   • "你觉得哪个工具好用" → 先搜索再回答

📝 使用示例（完整对话）

配置自动触发（让 AI 默认使用 tool-finder）

在 AGENTS.md 中添加以下内容：

### 🔍 Tool Discovery — Use `tool-finder` First!

**When user asks to find/search/install skills or MCPs:**

1. **ALWAYS use `tool-finder` skill first**
2. **DO NOT use `clawhub search` directly**
3. **Search command:**
   ```bash
   ~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh search "<query>" --type skill

4. Install command:

   ~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh install <name> --type skill
   

Why tool-finder?

• ✅ Name matching priority (relevant skills appear first)
• ✅ Rating-based filtering (hides irrelevant low-quality results)
• ✅ Clear recommendation levels (⭐⭐⭐⭐⭐ to ❌)
• ✅ Rate limit handling with fallback
• ✅ Shows source (ClawHub vs Smithery)

**效果：** AI 会自动在找 skill/MCP 时使用 tool-finder，无需每次指定！

---

### 示例 1：找 skill

用户：帮我找个能搜索 web 的 skill

AI：[执行 tool-finder search "web search" --type skill]

AI：找到以下 web 搜索 skill：

• tavily-search: Tavily Web Search
• baidu-search: baidu web search
• multi-search-engine: Multi Search Engine

推荐 tavily-search，需要安装吗？

### 示例 2：找 MCP

用户：有什么 MCP 可以连接 GitHub？

AI：[执行 tool-finder search "github" --type mcp]

AI：找到 GitHub 相关 MCP：

• GitHub: GitHub is a code hosting platform for version control...

需要我帮你安装吗？

### 示例 3：直接安装

用户：安装 tavily-search

AI：[执行 tool-finder install tavily-search --type skill]

AI：正在安装 tavily-search... [输出安装结果]

---

## 🔧 实现细节

### 路径

```bash
TOOL_FINDER="~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh"

ClawHub 搜索

npx clawhub@latest search "<query>"

Smithery 搜索

# MCPs
npx @smithery/cli@latest mcp search "<query>" --json

# Skills
npx @smithery/cli@latest skill search "<query>" --json

⚠️ 注意事项

0. 自动触发配置 ✅ 新增

让 AI 默认使用 tool-finder：

在 AGENTS.md 中添加：

### 🔍 Tool Discovery — Use `tool-finder` First!

**When user asks to find/search/install skills or MCPs:**
1. ALWAYS use `tool-finder` skill first
2. DO NOT use `clawhub search` directly

效果： AI 会自动使用 tool-finder，无需每次指定！

分享配置： 将 AGENTS.md 和 TOOLS.md 分享给其他人，他们也能享受同样的智能搜索体验。

1. 搜索策略 ✅ v1.3.0 优化

优先原词搜索：先用原词搜索，保证基础结果；如果结果不足，再用同义词扩展补充。

搜索流程：

1. 原词搜索 → 返回 N 条结果
2. 如果 N < limit 且未限流 → 扩展搜索（补充结果）
3. 合并去重 → 按评分降序排列

优势：

• ✅ 原词结果优先，避免扩展词污染
• ✅ 限流时保证有结果
• ✅ 结果不足时自动补充

2. 推荐规则 ✅ v1.2.0 新增

评分排序：结果按 ClawHub 评分降序排列，高评分技能优先显示。

推荐等级：

过滤规则：

• 默认隐藏评分 < 1.0 的技能（几乎无关）
• 使用 --all 显示所有结果（包括 < 1.0）
• 说明：模糊搜索分数通常较低（1.0-2.0），这是正常的

2. 错误透明化 ✅ 新增

改进：遇到 API 限流或搜索失败时，会显示明确的警告信息，而不是内部消化。

示例输出：

⚠️  ClawHub API 限流 (Rate limit exceeded)
   建议：等待几分钟后重试，或登录 clawhub login

══════════════════════════════════════════════════════════════
⚠️  搜索警告
══════════════════════════════════════════════════════════════
• ClawHub: 2 次错误/限流

提示：结果可能不完整，建议:
  1. 等待几分钟后重试（限流情况）
  2. 使用精确模式：--exact（知道技能名时）
  3. 直接访问 https://clawhub.ai 搜索验证
  4. 使用 --verbose 查看详细错误

3. 结果可验证性 ✅ 新增

问题：搜索结果可能与 ClawHub 网页搜索有差异（向量搜索 vs 文本搜索）。

解决方案：

• 使用 --verbose 查看详细错误信息
• 重要技能建议访问 https://clawhub.ai 验证
• 使用 clawhub inspect <skill-name> 获取详细信息
• 对比多次搜索结果，确保没有遗漏

4. ClawHub 搜索限制

问题：ClawHub 使用向量搜索，有时搜功能词（如"RAG"）找不到名字包含该词的 skill（如 clawrag）。

解决方案：

• 知道名字 → 用 --exact 模式：tool-finder search "clawrag" --exact
• 不知道名字 → 多试几个关键词："rag", "memory", "retrieval"
• 使用 clawhub search 直接搜索作为补充

5. ClawHub Rate Limit

未登录时可能遇到速率限制（60 次/小时）。

解决：

• 等待几分钟后重试
• npx clawhub login 登录后提高限制
• 使用 --verbose 确认是否限流

6. MCP 安装需要客户端

Smithery MCP 安装需指定客户端（claude-code/cursor/vscode 等）。

解决：输出指引让用户手动安装。

7. 搜索关键词

• 优先用英文（工具名多为英文）
• 中文可试，但效果可能较差
• 使用连字符的技能名要精确搜索（如 agent-orchestrator）

8. 路径问题

• 使用绝对路径：~/.openclaw/workspace/skills/tool-finder/scripts/tool-finder.sh
• 或确保 PATH 包含 scripts 目录

📦 依赖

• Node.js + npx
• curl
• jq

🦞 总结

一句话：用户找工具 → 用 tool-finder search → 返回结果 → 问要不要安装