wigolo深度介绍：本地优先的AI代理Web智能层，零API密钥、零查询成本

2026-08-10 14:51 👁️ 49 阅读
wigolo 本地优先 AI代理 MCP 开源Web搜索 零API密钥 AGPL-3.0 Firecrawl替代 自托管搜索 Claude Code插件

AI编程助手要"上网"，过去基本只有一条路：接Firecrawl、Exa或Tavily，注册账号、填API密钥、看着账单随查询量线性增长。KnockOutEZ在2026年4月开源的wigolo换了一个思路——把搜索、抓取、爬取、提取、缓存、相似查找、自主调研整套Web能力下沉到本地，核心工具完全不需要API密钥，每次查询成本恒为0，所有数据默认落在你机器的~/.wigolo/目录里。

截至2026年7月，项目在GitHub收获1200+ star，处于Public Beta阶段，AGPL-3.0许可证。

它到底解决了什么问题

AI代理的Web访问有三个老大难：

  1. 按查询计费：Firecrawl、Exa、Tavily每查一次收一次钱，代理一阵阵地发查询，账单就跟着疯涨

  2. 数据外流：查询内容发到第三方服务器，对企业项目和隐私敏感场景是不可接受的风险

  3. 结果不可解释：大多数云API返回一个黑盒分数，代理不知道这条结果为啥排在这里，弱结果和失败也常被粉饰

wigolo的对策很直接——让重活儿在你自己的硬件上跑。18个搜索引擎的直连适配器、重排序模型、嵌入模型、向量索引全部本地化。这么做的前提是接受约1.5GB的磁盘占用（浏览器引擎+本地ML模型），换来的是查询时没有任何计量表在转。

十个工具，一条本地流水线

wigolo通过MCP协议向AI代理暴露十个工具，覆盖Web相关的全部环节：

  • search：18个搜索引擎并行查询，rank fusion合并结果，本地ML模型重排序。传入query数组可一次性扇出多个查询

  • fetch：单页抓取，三层递进策略（HTTP→TLS指纹→无头浏览器），按域名记忆学习

  • crawl：整站爬取，支持BFS/DFS/sitemap，自动去重、限速、遵守robots.txt

  • extract：从页面抽取结构化数据，支持JSON-LD、Schema.org类型或自定义JSON Schema

  • cache：混合检索本地缓存（关键词+向量），支持find_similar和变更检测

  • research：把复杂问题拆成多个子查询，并行获取源，合成带引用的调研摘要

  • agent：自主规划的"搜索→抓取→提取→合成"循环，带步骤日志和时间预算

  • watch：定时轮询目标站点，内容变动通过Webhook推送

  • diff：比对网页历史缓存版本的文字与结构差异

  • skills：11个Agent Skill技能包，教你的编码代理用好每个工具

其中search、fetch、crawl、extract、cache、find_similar这六个核心工具完全不需要API密钥。

真正区别于云API的三个设计

字节级定位的原文摘录

每个搜索结果不只是返回一段摘要，而是带着：

  • 钉在源页面字节偏移量（byte-offset source span）上的逐字摘录

  • 可供代理引用的citation ID

  • 可解释的评分分解：语义分（semantic）、词汇分（lexical）、引擎共识分（engine_consensus）

代理拿到的不是"我觉得相关"的黑盒数字，而是"这段原文在第1284到1571字节之间，语义分0.91、词汇分0.74、5个引擎里有4个返回了它"。

显式失败，不粉饰

Bot拦截标注为blocked_by_challenge，失效引擎直接在结果里报出来，陈旧缓存打上标签，弱结果由它自己的交叉编码器打分器标为junk。代理始终知道"自己站在什么证据上"，而不是被沉默的空结果误导。

本地缓存让重复查询近乎免费

所有抓取内容落在~/.wigolo/：完整文本、关键词索引、本地向量嵌入。同一个问题问第二次，毫秒级返回，断网也能查已缓存的内容。

5分钟接入

wigolo支持多种安装渠道：npm（npx）、PyPI、Docker、Homebrew、MCP官方注册表等。

前置要求：Node ≥ 20，约1.5GB空闲磁盘，macOS/Linux/Windows三平台通用。

第一步：初始化并接入AI助手

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

这条命令无人值守执行（适合脚本和CI），会自动下载浏览器引擎和本地模型、跑健康检查、写入MCP配置。想推迟下载到首次使用，加--no-warmup。

第二步：验证组件健康

npx wigolo doctor

第三步（可选）：让research和agent输出综合答案

这两个工具以及search的format=answer模式需要LLM来写带引用的综合回答。不接LLM也能用，但返回的是原始证据包，体验大打折扣。接一个免费的Gemini密钥是性价比最高的一步：

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=你的密钥

想完全本地化不出境，用Ollama：

export WIGOLO_LLM_PROVIDER=ollama

任何OpenAI兼容的端点都支持，在shell或代理的MCP env块里设置即可。

卸载也很干净：

npx wigolo config --uninstall --yes

不止MCP：三种接入面

wigolo是个单进程Node应用，同一进程同时暴露MCP、REST、SDK三种接入面：

MCP（stdio）：给Claude Code、Cursor、Codex、Gemini CLI、VS Code、Windsurf、Zed、Antigravity等编码代理用

REST API：

wigolo serve
# 127.0.0.1:3333，loopback开放；绑到外网则强制要求bearer token（fail-closed）

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

POST /v1/{tool}覆盖全部十个工具，GET /openapi.json是OpenAPI 3.1契约，/mcp和/sse从同一端口服务远程MCP客户端。n8n、自建助手、任意自托管代理都能直接指过来。

SDK：

// TypeScript：npm install wigolo-sdk（零依赖，支持Node/Bun/Deno/edge）
import { createLocalClient } from 'wigolo-sdk/local';
const { client, close } = await createLocalClient();
const res = await client.search({ query: 'local-first web search', max_results: 5 });
# Python：pip install wigolo（仅标准库，含同步和异步客户端）
import wigolo
result = wigolo.search("local-first web search")

框架集成包也齐全：LangChain、CrewAI、LlamaIndex、Vercel AI SDK都有对应的wrapper。

与Firecrawl/Exa/Tavily的横向对比

以下是项目方公布的对比（功能状态截至2026年7月）：

能力

wigolo

Firecrawl

Exa

Tavily

多引擎Web搜索

✅

✅

✅

✅

抓取与结构化提取

✅

✅

✅

✅

整站爬取与地图

✅

✅

—

✅

字节级定位的原文摘录

✅

—

—

—

可解释的逐条评分分解

✅

—

—

—

持久化本地缓存（离线重查）

✅

—

—

—

查询数据驻留本机

✅

—

—

—

需要API密钥/账户

不需要

必须

必须

必须

单次查询成本

$0

按量

按量

按量

wigolo不是"免费版的将就替代品"——它在结果质量上对标这些付费服务。作者做过一个四方位对比实验：同一个冷查询，在Claude Fable 5会话里同时扇出built-in WebSearch、wigolo、Tavily、Exa四个工具，四个工具都收敛到同一个核心答案和同一个顶级信源；只有wigolo返回了字节钉位的逐字摘录、可解释的评分分解、实时的逐引擎遥测，并且它自己的打分器把两条弱结果标成了junk。

什么场景该用，什么场景不该用

适合

  • 日常高频使用Claude Code、Cursor等编码助手，不想为联网搜索单独承担按量账单

  • 对数据隐私和合规有要求，希望搜索抓取完全在本地闭环

  • 需要稳定批量做网页调研、数据采集，不想被云端速率限制卡脖子

  • 自托管代理（n8n工作流、内部知识机器人、VPS自动化）

要权衡的点

  • Public Beta状态：项目明确说是公开测试版，7600+测试用例兜着稳定性，但"beta"指的是打磨程度而非稳定性

  • 首次安装成本：约1.5GB下载，主要在浏览器引擎和本地模型

  • research/agent的质量依赖LLM：不接LLM也能跑，但返回的是原始证据包，需要代理自己组装答案

  • 最严格的反爬墙：官方明确说明，部分challenge-protected站点会评估IP信誉，数据中心IP可能清不掉某些墙，家庭宽带可以；wigolo的选择是标出失败而不是伪造结果，需要用户主动配置opt-in proxy

  • AGPL-3.0的传染性：个人本地使用、公司内部使用完全自由；但如果你修改了wigolo并作为网络服务运行，必须开源你的修改版本。这一条是AGPL的标准要求，也是项目防止被闭源托管fork的核心保障

架构与性能要点

wigolo采用单进程多协议架构，重型组件全部惰性加载——零密钥安装不会为用不上的功能付出运行时代价：

  • 搜索管道：18个引擎并行 → rank fusion归并 → 本地ML重排序 → 可解释输出（任一个引擎挂掉几乎不影响结果）

  • 分层抓取路由：依据页面信号（challenge body、SPA标记、内容厚度）而非域名白名单决定升级到哪一层；按域名记忆学习

  • 存储层：~/.wigolo/目录下，SQLite（better-sqlite3）存元数据，sqlite-vec做向量索引，本地嵌入模型供语义搜索和重排序

  • 爬虫礼貌性：默认遵守robots.txt，每域名限速，定位在"单代理单机的调研级体量"的礼貌端，不是规模化收割平台

维护与可持续性

wigolo由@KnockOutEZ一人开发维护，作者在项目说明里直言是"一个人对抗三个拿了融资的团队"。项目没有付费档，也承诺永远不会有，靠捐赠和AGPL防止闭源托管来维持开放性。用户在GitHub提的issue作者响应很快，多数当天回复。

如果你想支持，去GitHub点个star是最好的被发现方式，其次是一杯咖啡的捐赠。