UltimateSearchSkill 双引擎网络搜索 Skill一、概述1. 简介A. 是什么UltimateSearchSkill 是为 OpenClaw / Pi agent 打造的双引擎网络搜索 Skill，整合了 Grok AI 联网搜索和 Tavily 结构化搜索两种能力，提供并行搜索、网页抓取、站点映射等功能。B. 核心特性双引擎搜索：Grok AI 驱动的语义搜索与 Tavily 结构化数据检索互补协作多账户聚合：通过 grok2api 和 TavilyProxyManager 实现多账号负载均衡自动降级：web-fetch 采用 Tavily Extract → FireCrawl Scrape → 报错的三级降级策略Cloudflare 自动绕过：集成 FlareSolverr 自动获取并刷新 cf_clearance零 MCP 依赖：纯 Shell 脚本实现，agent 通过 Bash 原生调用2. 前置条件A. 系统要求Docker 和 Docker Composecurl、jq 工具至少一个 Grok 账号的 SSO Session TokenB. 必备 KeyGrok SSO Session Token（从浏览器 Cookie 获取）Tavily API Key（免费额度 1000 次/月）FireCrawl API Key（可选，作为网页抓取降级方案）二、架构设计1. 系统组成系统由以下核心组件构成：组件功能端口grok2apiGrok Token 聚合服务8100TavilyProxyManagerTavily Key 聚合服务8200FlareSolverrCloudflare 自动绕过81912. 工作原理graph TD A[用户提问] --> B[Agent] B --> C{搜索工具选择} C -->|Grok AI 搜索| D[grok-search.sh] C -->|Tavily 搜索| E[tavily-search.sh] C -->|双引擎并行| F[dual-search.sh] C -->|网页抓取| G[web-fetch.sh] C -->|站点映射| H[web-map.sh] D --> I[grok2api] I --> J[Grok 联网搜索 API] E --> K[TavilyProxyManager] K --> L[Tavily 搜索 API] F --> I F --> K F --> M[结果交叉验证] G --> N[Tavily Extract] N -->|失败| O[FireCrawl Scrape] O -->|失败| P[报错] H --> K K --> Q[Tavily Map API]3. 服务间交互sequenceDiagram participant A as Agent participant G as grok-search.sh participant T as tavily-search.sh participant G2 as grok2api participant TP as TavilyProxyManager participant FS as FlareSolverr A->>G: grok-search.sh --query G->>G2: GET /v1/search G2->>FS: 获取 cf_clearance FS-->>G2: 返回 Cookie G2->>G2: 选择可用 Token G2->>G2: 调用 Grok API G2-->>G: 返回搜索结果 G-->>A: JSON 输出 A->>T: tavily-search.sh --query T->>TP: POST /api/search TP->>TP: 负载均衡选择 Key TP->>TP: 调用 Tavily API TP-->>T: 返回搜索结果 T-->>A: JSON 输出三、安装部署1. 克隆仓库git clone https://github.com/你的用户名/UltimateSearchSkill.git cd UltimateSearchSkill # 复制环境变量模板 cp .env.example .env2. 启动服务# 创建数据目录 mkdir -p data/grok2api/logs data/tavily-proxy # 拉取镜像并启动 docker compose pull docker compose up -d3. 服务状态验证# 查看服务状态 docker compose ps # 查看日志 docker compose logs grok2api docker compose logs tavily-proxy docker compose logs flaresolverr四、Key 导入配置1. 获取 Grok SSO Session Tokengrok2api 需要的是 Grok 网页版的 SSO Session Token（JWT 格式），而非 API Key。A. 浏览器手动获取用浏览器登录 https://grok.com打开开发者工具（F12）→ Application → Cookies → https://grok.com找到名为 sso 的 Cookie，复制其值（以 eyJ 开头的长字符串）B. 批量导出将多个 Grok 账号的 SSO Cookie 保存到 export_sso.txt 文件中，每行一个 Token：eyJhbGciOiJIUzI1NiJ9.xxx...（第1个账号） eyJhbGciOiJIUzI1NiJ9.yyy...（第2个账号） eyJhbGciOiJIUzI1NiJ9.zzz...（第3个账号）C. Token 额度说明账号类型额度刷新周期Basic（免费）80 次每 20 小时Super（付费）140 次每 2 小时2. 导入 Grok TokenA. 使用 import-keys.sh 脚本（推荐）# 确保 export_sso.txt 在项目根目录 bash scripts/import-keys.sh脚本会自动：读取 export_sso.txt 中的 Token通过 grok2api 管理接口批量导入到 ssoBasic Token Pool获取 TavilyProxyManager 的 Master Key 并更新 .env导入 .env 中配置的 Tavily/FireCrawl KeyB. 通过 API 手动导入# 单个 Token curl -X POST http://127.0.0.1:8100/v1/admin/tokens \ -H "Authorization: Bearer grok2api" \ -H "Content-Type: application/json" \ -d '{"ssoBasic": ["eyJhbGci...你的Token"]}'3. 导入 Tavily API KeyA. 配置到 .env编辑 .env，将 Tavily Key 填入 TAVILY_API_KEYS（多个用逗号分隔）：TAVILY_API_KEYS=tvly-xxx111,tvly-xxx222,tvly-xxx333然后运行：bash scripts/import-keys.shB. 验证导入# 测试搜索 bash scripts/tavily-search.sh --query "test" --max-results 14. 配置 FireCrawl Key（可选）FireCrawl 作为 web-fetch.sh 的降级方案，当 Tavily Extract 失败时自动切换。编辑 .env：# 单个 Key（脚本直接使用） FIRECRAWL_API_KEY=fc-你的key # 或批量配置 FIRECRAWL_API_KEYS=fc-key1,fc-key25. Cloudflare 绕过配置grok2api 访问 Grok 官网时会被 Cloudflare 拦截。项目已集成 FlareSolverr 来自动处理：graph LR A[grok2api] -->|需要访问 Grok| B[检查 cf_clearance] B -->|已过期/不存在| C[FlareSolverr] C -->|无头 Chrome| D[Grok 首页] D -->|通过 Challenge| E[返回 cf_clearance] E --> A B -->|有效| F[直接请求] F --> G[Grok API]首次启动时，验证 cf_clearance 是否获取成功：docker compose logs grok2api | grep "配置已更新" # 应看到: 配置已更新: cf_cookies (长度 xxxx), 指纹: chromeXXX如果配置未自动启用，需手动修改：sudo sed -i 's|^enabled = false|enabled = true|' data/grok2api/config.toml sudo sed -i 's|^flaresolverr_url = ""|flaresolverr_url = "http://ultimate-search-flaresolverr:8191"|' data/grok2api/config.toml docker compose restart grok2api五、使用指南1. 加载环境变量source .env2. 搜索工具A. Grok AI 搜索AI 驱动的深度搜索，适合语义理解复杂问题。bash scripts/grok-search.sh --query "FastAPI 最新特性"B. Tavily 搜索结构化搜索结果，带评分排序。bash scripts/tavily-search.sh --query "Python web frameworks comparison" --depth advancedC. 双引擎搜索并行调用 Grok 和 Tavily，结果交叉验证。bash scripts/dual-search.sh --query "Rust vs Go 2026"graph TD A[用户查询] --> B[dual-search.sh] B --> C[Grok 搜索] B --> D[Tavily 搜索] C --> E[Grok 结果] D --> F[Tavily 结果] E --> G[结果合并与交叉验证] F --> G G --> H[最终输出]3. 网页抓取采用三级降级策略：Tavily Extract → FireCrawl Scrape → 报错。bash scripts/web-fetch.sh --url "https://docs.python.org/3/whatsnew/3.13.html"graph TD A[web-fetch.sh] --> B[Tavily Extract] B -->|成功| C[返回内容] B -->|失败| D[FireCrawl Scrape] D -->|成功| C D -->|失败| E[报错并返回]4. 站点映射生成站点结构映射。bash scripts/web-map.sh --url "https://docs.tavily.com" --depth 2六、Skill 集成1. 注册到 OpenClaw / Pi# 创建 skill 目录并软链接 SKILL.md mkdir -p ~/.openclaw/workspace/skills/ultimate-search ln -sf $(pwd)/SKILL.md ~/.openclaw/workspace/skills/ultimate-search/SKILL.md # 将脚本加入 PATH grep -q 'UltimateSearchSkill/scripts' ~/.bashrc || \ echo 'export PATH="$HOME/UltimateSearchSkill/scripts:$PATH"' >> ~/.bashrc # 加载环境变量 grep -q 'UltimateSearchSkill/.env' ~/.bashrc || \ echo '[ -f ~/UltimateSearchSkill/.env ] && source ~/UltimateSearchSkill/.env' >> ~/.bashrc source ~/.bashrc2. 设为默认搜索方式在 ~/.openclaw/workspace/AGENTS.md 的 Tools 部分添加路由规则：### 搜索工具 **默认搜索方式是 ultimate-search skill。** 任何需要网络搜索的场景，先加载 ultimate-search skill 并按其指引操作。支持以下能力： - grok-search.sh — AI 驱动的深度搜索（Grok 联网） - tavily-search.sh — 结构化搜索结果（带评分排序） - dual-search.sh — 双引擎并行搜索（交叉验证） - web-fetch.sh — 网页内容抓取（Tavily → FireCrawl 降级） - web-map.sh — 站点结构映射七、安全说明1. 网络安全所有端口绑定到 127.0.0.1，外部无法直接访问远程管理通过 SSH 隧道访问grok2api 使用 API 认证2. 数据安全export_sso.txt、.env、data/ 已加入 .gitignore不会提交敏感信息到 GitTavilyProxyManager 使用随机生成的 Master Key3. 管理面板访问# SSH 隧道（远程服务器） ssh -L 8100:127.0.0.1:8100 你的服务器 ssh -L 8200:127.0.0.1:8200 你的服务器 # 浏览器打开管理面板 http://localhost:8100/admin # grok2api http://localhost:8200 # TavilyProxyManager八、搜索方法论SKILL.md 内置了 GrokSearch MCP 的搜索规划框架和证据标准：1. 搜索决策流程明确查询意图：事实查询 vs 解释性查询 vs 探索性查询选择合适的搜索工具：Grok（语义理解）vs Tavily（结构化）确定搜索深度：基础结果 vs 深度挖掘2. 证据标准严格区分内部知识与外部知识关键事实需大于等于 2 个独立来源支持来源冲突时展示双方证据并评估可信度标注置信度：High/Medium/Low3. 引用格式使用 Markdown 格式：来源标题严禁编造引用参考资料GitHub - ckckck/UltimateSearchSkill