Loading... # 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 Compose - curl、jq 工具 - 至少一个 Grok 账号的 SSO Session Token ### B. 必备 Key - Grok SSO Session Token（从浏览器 Cookie 获取） - Tavily API Key（免费额度 1000 次/月） - FireCrawl API Key（可选，作为网页抓取降级方案） # 二、架构设计 ## 1. 系统组成 系统由以下核心组件构成： | 组件 | 功能 | 端口 | |------|------|------| | grok2api | Grok Token 聚合服务 | 8100 | | TavilyProxyManager | Tavily Key 聚合服务 | 8200 | | FlareSolverr | Cloudflare 自动绕过 | 8191 | ## 2. 工作原理 ```mermaid 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. 服务间交互 ```mermaid 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. 克隆仓库 ```bash git clone https://github.com/你的用户名/UltimateSearchSkill.git cd UltimateSearchSkill # 复制环境变量模板 cp .env.example .env ``` ## 2. 启动服务 ```bash # 创建数据目录 mkdir -p data/grok2api/logs data/tavily-proxy # 拉取镜像并启动 docker compose pull docker compose up -d ``` ## 3. 服务状态验证 ```bash # 查看服务状态 docker compose ps # 查看日志 docker compose logs grok2api docker compose logs tavily-proxy docker compose logs flaresolverr ``` # 四、Key 导入配置 ## 1. 获取 Grok SSO Session Token grok2api 需要的是 Grok 网页版的 SSO Session Token（JWT 格式），而非 API Key。 ### A. 浏览器手动获取 1. 用浏览器登录 https://grok.com 2. 打开开发者工具（F12）→ Application → Cookies → https://grok.com 3. 找到名为 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 Token ### A. 使用 import-keys.sh 脚本（推荐） ```bash # 确保 export_sso.txt 在项目根目录 bash scripts/import-keys.sh ``` 脚本会自动： - 读取 export_sso.txt 中的 Token - 通过 grok2api 管理接口批量导入到 ssoBasic Token Pool - 获取 TavilyProxyManager 的 Master Key 并更新 .env - 导入 .env 中配置的 Tavily/FireCrawl Key ### B. 通过 API 手动导入 ```bash # 单个 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 Key ### A. 配置到 .env 编辑 .env，将 Tavily Key 填入 TAVILY_API_KEYS（多个用逗号分隔）： ``` TAVILY_API_KEYS=tvly-xxx111,tvly-xxx222,tvly-xxx333 ``` 然后运行： ```bash bash scripts/import-keys.sh ``` ### B. 验证导入 ```bash # 测试搜索 bash scripts/tavily-search.sh --query "test" --max-results 1 ``` ## 4. 配置 FireCrawl Key（可选） FireCrawl 作为 web-fetch.sh 的降级方案，当 Tavily Extract 失败时自动切换。 编辑 .env： ``` # 单个 Key（脚本直接使用） FIRECRAWL_API_KEY=fc-你的key # 或批量配置 FIRECRAWL_API_KEYS=fc-key1,fc-key2 ``` ## 5. Cloudflare 绕过配置 grok2api 访问 Grok 官网时会被 Cloudflare 拦截。项目已集成 FlareSolverr 来自动处理： ```mermaid 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 是否获取成功： ```bash docker compose logs grok2api | grep "配置已更新" # 应看到: 配置已更新: cf_cookies (长度 xxxx), 指纹: chromeXXX ``` 如果配置未自动启用，需手动修改： ```bash 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. 加载环境变量 ```bash source .env ``` ## 2. 搜索工具 ### A. Grok AI 搜索 AI 驱动的深度搜索，适合语义理解复杂问题。 ```bash bash scripts/grok-search.sh --query "FastAPI 最新特性" ``` ### B. Tavily 搜索 结构化搜索结果，带评分排序。 ```bash bash scripts/tavily-search.sh --query "Python web frameworks comparison" --depth advanced ``` ### C. 双引擎搜索 并行调用 Grok 和 Tavily，结果交叉验证。 ```bash bash scripts/dual-search.sh --query "Rust vs Go 2026" ``` ```mermaid 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 bash scripts/web-fetch.sh --url "https://docs.python.org/3/whatsnew/3.13.html" ``` ```mermaid graph TD A[web-fetch.sh] --> B[Tavily Extract] B -->|成功| C[返回内容] B -->|失败| D[FireCrawl Scrape] D -->|成功| C D -->|失败| E[报错并返回] ```  ## 4. 站点映射 生成站点结构映射。 ```bash bash scripts/web-map.sh --url "https://docs.tavily.com" --depth 2 ``` # 六、Skill 集成 ## 1. 注册到 OpenClaw / Pi ```bash # 创建 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 ~/.bashrc ``` ## 2. 设为默认搜索方式 在 ~/.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 - 不会提交敏感信息到 Git - TavilyProxyManager 使用随机生成的 Master Key ## 3. 管理面板访问 ```bash # 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/Low ## 3. 引用格式 - 使用 Markdown 格式：[来源标题](URL) - 严禁编造引用 *** ## 参考资料 1. [GitHub - ckckck/UltimateSearchSkill](https://github.com/ckckck/UltimateSearchSkill) 最后修改：2026 年 03 月 02 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏