wigolo

仍在为 Claude Code、Cursor 等 AI 编码助手配置各种搜索 API？每月看着 Tavily、Exa、Firecrawl 的账单心疼？数据还要出境、还得管理一堆 Key？wigolo 给了开发者一个完全不同的答案。

一句话定位：wigolo 是一个本地优先（local-first） 的 Web 情报工具，为 AI Agent 提供搜索、抓取、爬取、研究等全套联网能力——无需 API Key、无需云端、每次查询零成本。

截至 2026 年 8 月，wigolo 在 GitHub 上已获得 4,500+ Stars，处于公开测试阶段，由作者一人维护，背后有 7000 多个测试用例在跑。

为什么 wigolo 值得关注？

在 wigolo 出现之前，AI Agent 要联网搜索，主流选择是 Tavily、Exa、Firecrawl 这类云端服务。它们的问题是：按查询计费、数据出境、需要注册账号。

wigolo 的底层逻辑很直接——搜索引擎的原始数据是公开的，排序和提取算法可以本地跑，为什么每次搜索都要付费、都要走云端？

于是它把搜索、抓取、爬虫、缓存、提取、研究整套联网能力全部搬到本地，所有数据留在 ~/.wigolo/ 目录里，不离开你的机器。

核心功能：10 个工具，覆盖所有联网需求

wigolo 以 MCP Server 形式暴露 10 个 Web 工具，AI Agent 通过标准 MCP 协议即可调用。

search：18 个引擎并行，每条结果都"讲证据"

search 工具同时向 18 个公开搜索引擎发起查询，然后用排序融合（rank fusion） 合并去重，最后用本地 ML 模型重排序。

关键在于返回格式——不是一串裸链接，而是带可解释评分拆解的结果：

{
  "excerpt": "Logical replication replicates data…",
  "score": 0.87,
  "breakdown": {
    "semantic": 0.91,
    "lexical": 0.74,
    "engine_consensus": "4/5 engines"
  },
  "source_span": { "start": 1284, "end": 1571 },
  "citation_id": "f38b44c100e4"
}

每条结果都附有原文摘录、字节级来源定位（byte-pinned evidence）、引用 ID 和详细打分。质量差的结果会被标记，哪个引擎没响应也会写明——全程透明。

fetch：智能降级，反爬不再是障碍

fetch 采用分层路由（tiered router） ，不靠域名猜测，而是根据实际响应内容判断：

1. Plain HTTP —— 大多数页面在这里就能解析
2. TLS 指纹伪装 —— 遇到反爬墙时自动升级
3. 无头浏览器引擎 —— 遇到 SPA 空壳或验证页面时完整渲染

它会按域名积累经验：某个域名被标记为需要浏览器后，下次直接走浏览器通道；后续发现不需要了，自动降级。实在过不去的验证墙，返回 blocked_by_challenge 标签，不会把验证页面伪装成正文。

此外 fetch 还能读 PDF、支持登录态会话、支持页面交互（点击/输入/滚动/截图）。

cache：查过的内容永不丢失

所有抓过的页面存储在 ~/.wigolo/ 下，同时建立关键词索引和向量索引。同一个问题问第二次，直接从缓存返回，零延迟、零费用、断网也能用。

快速上手：3 步从零到运行

前置要求

• Node.js ≥ 20
• 约 1.5 GB 可用磁盘空间（存放浏览器引擎和本地 ML 模型）
• 支持 macOS、Linux、Windows

第 1 步：安装与初始化

一条命令搞定全部：

npx wigolo init

这条命令会自动下载浏览器引擎、本地嵌入模型和重排序模型，运行健康检查。

如果想同时配置好常用 AI 编码助手，加上 --agents 参数：

npx wigolo init --agents=claude-code,cursor,codex,gemini-cli

支持的 Agent 包括：Claude Code、Cursor、Codex、Gemini CLI、OpenCode、VS Code、Windsurf、Zed、Antigravity 等。

第 2 步：检查是否一切正常

npx wigolo doctor

第 3 步：开始使用

配置完成后，在你的 AI 编码助手中直接提问即可——wigolo 会自动响应联网搜索需求。

如果不使用 MCP，也可以通过 REST API 调用：

wigolo serve
curl -X POST http://127.0.0.1:3333/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"local-first software","max_results":5}'

也可以通过 TypeScript SDK：

import { createLocalClient } from 'wigolo-sdk/local';
const { client, close } = await createLocalClient();
const res = await client.search({ query: 'local-first web search', max_results: 5 });
await close();

或 Python SDK：

from wigolo import local_client
with local_client() as client:
    res = client.search(query="local-first web search", max_results=5)

进阶配置：三组设置大幅提升质量

干净安装后开箱即用，但以下三组配置能显著提高输出质量：

1. 开启 Synthesis（合成回答）

research 和 agent 工具需要 LLM 来写最终报告。推荐配置免费的 Gemini API Key（从 aistudio.google.com 免费获取）：

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<你的免费 Key>

如果追求完全本地、数据不出境，可以用 Ollama：

export WIGOLO_LLM_PROVIDER=ollama

2. 扩大检索范围

export WIGOLO_SEARCH=hybrid
export WIGOLO_GITHUB_TOKEN=<你的 GitHub Token>

hybrid 模式在核心引擎之外增加聚合回退，GitHub Token 可提升代码搜索的速率限制和私有仓库索引能力。

3. 更强抓取与预热

export WIGOLO_TLS_TIER=auto

这个设置决定抓取加固策略，auto 模式让 wigolo 自动选择最优的 TLS 指纹方案。

与其他工具对比：wigolo 的独特优势

在一次 Claude 会话的对比测试中，四个工具（内置 WebSearch、wigolo、Tavily、Exa）对同一个问题的核心答案一致，但只有 wigolo 返回了带字节级定位的原文证据。

适用场景与建议

✅ 最适合的场景

• AI 编码助手重度用户：Claude Code、Cursor、Codex、Windsurf 等日常重度使用搜索的开发者
• 追求数据隐私：所有数据留在本地，不经过任何第三方服务器
• 预算敏感：不想为每次搜索付费，希望零成本无限次使用
• 批量抓取与离线缓存：需要大量抓取页面并建立本地知识库
• 自托管 Agent 系统：在自己服务器上跑 Agent，需要稳定的联网能力

⚠️ 注意事项

1. 首次冷启动：浏览器引擎首次启动大约需要 2-3 秒
2. 磁盘空间：约 1.5 GB，确保有足够空间
3. Windows 路径：~/.wigolo/ 在 Git Bash 和 PowerShell 中解析方式不同，建议用绝对路径或直接在 WSL 里运行
4. 公开测试阶段：虽然已有 7000+ 测试用例，但仍在快速迭代中

总结

wigolo 不是简单的"又一款搜索工具"，它代表了一种范式转变——把 AI Agent 的联网能力从"云服务按次付费"变成"本地运行零成本"。

它的核心价值可以概括为三点：

• 💰 零成本：没有 API Key，没有按次计费，Agent 想查多少次就查多少次
• 🔒 隐私优先：缓存、模型、配置全在本地，数据不离开你的机器
• 📊 透明可信：每条结果都有可解释评分、原文摘录和字节级来源定位

如果你正在使用 AI 编码助手，或者正在搭建自托管的 Agent 系统，wigolo 值得花 5 分钟安装试用——一条命令，终身免费。