wigolo：零成本、零 API Key，给 AI 编程助手的本地优先 Web 搜索神器

## wigolo：零成本、零 API Key，给 AI 编程助手的本地优先 Web 搜索神器

如果你平时用 Claude Code、Cursor、VS Code + Copilot 这类 AI 编程工具，大概率遇到过这个痛点：让 AI 查个文档、搜段代码，它要么连搜索引擎都没接，要么消耗付费 API 额度，要么返回的结果没有出处无法验证。

最近在 GitHub Trending 上爆火的 **wigolo** 正是来解决这个问题的——一个完全本地化运行、无需任何 API Key 的 AI Agent Web 智能搜索工具，上线不久就拿了近 2000 星，今天一天涨了 595 颗。

—

### wigolo 是什么？

简单说，wigolo 给你的 AI Agent 提供一整套”上网工具”：**搜索、抓取、爬取、提取、缓存、相似检索、研究报告、自主搜索循环**——总共 10 个工具，全部在本地跑，所有数据留在 `~/.wigolo/` 目录里，一次也不想让你付费。

它通过 **MCP（Model Context Protocol）** 与 AI 编辑器集成，一行命令就能让 Claude Code、Cursor、Codex、Gemini CLI、VS Code、Windsurf、Zed 等工具获得 Web 搜索能力。

—

### 核心亮点

1. **真正零成本**
– 底层搜索对接 18 个公开搜索引擎，本地做 rank fusion 和 ML 重排序
– 嵌入模型（embeddings）和重排模型都跑在本地设备上
– 搜索结果永久缓存，重复查询不花一分钱

2. **诚实的结果输出**
– 每条结果附带引用 ID 和原文逐字摘录，精确到字节偏移量
– 搜索失败或被反爬阻挡时，明确返回失败标记（`blocked_by_challenge`），而不是伪装成空数据
– 带可解释的评分拆解——语义分、词法分、引擎共识数——让你知道为什么返回了这些结果

3. **隐私优先**
– 默认无第三方通信，缓存、模型、配置全在 `~/.wigolo/` 下
– 只有在你主动选择 LLM 合成时（比如 `research` 模式），才向外联网

4. **广泛的工具面**
10 个工具覆盖了 AI Agent 几乎所有 Web 交互需求：

| 工具 | 能力 |
|——|——|
| `search` | 多引擎并行搜索（支持查询数组批处理） |
| `fetch` | URL 内容抓取，自动升级到无头浏览器 |
| `crawl` | 整站爬取（BFS/DFS/Sitemap） |
| `extract` | 结构化数据提取（表格、JSON-LD、自定义 Schema） |
| `cache` | 本地缓存查询与变更检测 |
| `find_similar` | 相似页面发现（关键词+语义+Web 三路融合） |
| `research` | 自动分解问题→收集资料→生成引用报告 |
| `agent` | 自主搜索循环（plan→search→fetch→synthesize） |
| `diff` / `watch` | 页面变更追踪和 Webhook 通知 |

—

### 快速上手

**前置条件**：Node ≥ 20，约 1.5 GB 空闲磁盘

一键初始化（自动下载浏览器引擎和本地模型）：

“`bash
npx wigolo init –agents=claude-code,cursor
“`

`–agents` 参数支持：`claude-code`、`cursor`、`codex`、`gemini-cli`、`vscode`、`windsurf`、`zed`、`antigravity`（逗号分隔）。wigolo 会自动写入 MCP 配置，无需手动编辑。

验证安装：

“`bash
npx wigolo doctor
“`

#### 推荐：加个免费 API Key 让 research 更智能

搜索、抓取、爬取完全零 Key。但 `research`、`agent`、`search` 的回答模式需要 LLM 来合成最终结果——加个免费的 Gemini API Key 就能大幅提升体验：

“`bash
export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=
“`

也支持 Anthropic、OpenAI、Groq，或者用 Ollama 完全离线。

—

### 不只是 MCP：REST API、SDK、Docker

wigolo 的灵活程度远超一般 MCP 工具：

– **REST API**：`wigolo serve` 启一个 HTTP 服务，curl 就能调用所有 10 个工具
– **TypeScript SDK**：`npm install wigolo-sdk`，零依赖
– **Python SDK**：`pip install wigolo`，标准库实现
– **框架集成**：LangChain、CrewAI、LlamaIndex、Vercel AI SDK 都有对应包
– **Docker**：官方提供 slim 和 full 两种镜像

“`python
# Python SDK 示例
from wigolo import local_client

with local_client() as client:
res = client.search(query=”Python async best practices”, max_results=5)
for r in res[“results”]:
print(r[“title”], r[“url”])
“`

—

### 适用场景

– **AI 编程辅助**：让 Claude Code / Cursor 实时查最新文档和 Stack Overflow
– **技术调研**：用 `research` 模式自动收集某个技术话题的引用报告
– **内容监控**：用 `watch` + `diff` 追踪竞品页面变更
– **RAG 数据源**：通过框架集成作为 LangChain/LlamaIndex 的检索器
– **自托管 Agent**：通过 REST API 接入 n8n 或自建 agent 架构
– **离线场景**：所有核心功能不依赖云端，缓存过后完全离线可用

—

### 与付费竞品的对比

| 维度 | wigolo | Firecrawl | Exa | Tavily |
|——|:—:|:—:|:—:|:—:|
| 多引擎搜索 | ✅ | ✅ | ✅ | ✅ |
| 整站爬取 | ✅ | ✅ | — | ✅ |
| 逐字引用（字节偏移） | ✅ | — | — | — |
| 可解释评分拆解 | ✅ | — | — | — |
| 本地持久化缓存 | ✅ | — | — | — |
| 数据本地存储 | ✅ | — | — | — |
| 需要 API Key | ❌ | 需要 | 需要 | 需要 |
| 单次查询费用 | $0 | 计费 | 计费 | 计费 |

—

### 值得注意

– wigolo 目前处于 **public beta**，核心功能稳定（有 7600+ 测试用例保障），主要是在打磨体验
– 采用 **AGPL-3.0** 协议——个人和企业免费使用，修改后作为网络服务需要开源
– 反爬方面：遵守 robots.txt、按域名限速；面对深度反爬保护的站点会明确报告失败而不是伪装成功
– 作者是独立开发者 [@KnockOutEZ](https://github.com/KnockOutEZ)，维护靠社区捐赠

—

### 总结

wigolo 切中了 AI 编程时代一个刚需痛点：**给 Agent 一个靠谱、免费、可验证的 Web 能力层**。它不试图取代浏览器，也不做爬虫平台，就做一件事——让你的 AI 编程助手能真正”上网查东西”，而且不用为这个能力买单。

如果你平时用 AI 写代码，花 5 分钟装上试试，感受一下 Agent 有了搜索引擎之后的工作效率提升。

> GitHub: [github.com/KnockOutEZ/wigolo](https://github.com/KnockOutEZ/wigolo)