游手好闲地学习，并不比学习游手好闲好。——约翰·贝勒斯

https://github.com/KnockOutEZ/wigolo

wigolo：把“上网这件事”重新交还给你的 AI 编码代理

给 AI 编码代理接入互联网，听起来像一件早该被解决的事，可真正做起来，往往不是卡在搜索质量，就是卡在抓取能力；不是被 API key 绊住脚，就是被云端计费追着跑。更现实一点说，很多时候你只是想让代理去查资料、抓页面、做点研究，结果先要注册、配置、付费、限额、再祈祷别超预算。

wigolo 对这件事的态度很直接：no keys, no cloud, $0/query。

它把自己描述为：The go-to web for your AI coding agent — local-first search, fetch, crawl & research over MCP. 这句话挺有劲，像是在说：如果你的代理需要“上网”，那就别再东拼西凑了，给它一个统一的本地入口，让搜索、抓取、爬取、提取和研究都在同一个表面上发生。

项目地址：https://github.com/KnockOutEZ/wigolo

它不是单一搜索工具，而是一个统一的 Web intelligence surface

README 很早就把定位说透了：wigolo 给 AI agent 提供了一个统一的 web surface，用来处理所有与网络相关的事情，包括：

  • search
  • fetch
  • crawl
  • extract
  • cache
  • find-similar
  • research
  • autonomous gather loops

这份列表的意思很明确：它并不想只做“搜一下网页”的替代品，而是试图让代理在网络层上的工作有一个统一接口。代理不需要分别接不同的搜索、提取、研究和缓存组件，而是通过同一套工具面去完成这些动作。

这会让人很自然地想到一个画面：以前代理上网像背着一堆零散工具出门，现在 wigolo 像是给它装了一辆功能齐整的小车，查资料、抓页面、翻站点、抽结构化数据、回看缓存、做相似发现，统统可以从驾驶位直接操作。

它的核心气质：local-first，而且是真本地

wigolo 最醒目的特点之一，就是它对 local-first 的坚持。README 反复强调几件事：

  • 它运行在代理所在的地方
  • 缓存、embedding、模型和配置保存在 ~/.wigolo/
  • 默认情况下不会把东西发到第三方
  • 除非你显式选择使用 LLM 做 synthesis，否则很多核心能力都可以保持 keyless

这种设计有一种很明显的脾气：它不是把代理对网络的需求再交给另一个云端黑盒，而是尽量把重心放回本机。你用自己的机器跑搜索逻辑、跑 reranker、跑 embeddings、跑浏览器引擎，代价是占一些磁盘，但换来的是更低的查询成本和更强的控制感。

快速开始的入口非常短，像是在说“别想太多，先跑起来”

README 的 Quickstart 只有两条主命令：

1
2
npx wigolo init                              # set up the local engine — any system
npx wigolo init --agents=claude-code,cursor  # …or set up + wire your day-to-day agents in one command

这两行命令基本把使用路径讲清楚了。

第一种是单纯初始化本地引擎。第二种更进一步，会在初始化的同时，把你日常使用的代理也一起接好线。README 还补充说明，init 会下载浏览器引擎和 on-device models、执行 health check，并完成必要配置。

它还给出了运行条件：

  • Node ≥ 20
  • macOS / Linux / Windows
  • 约 1.5 GB 可用磁盘空间

这个 1.5 GB 看起来不小，但 README 在 FAQ 里其实已经给了一个很明确的解释：这里装进去的是完整浏览器引擎以及 ranking / embedding 模型，而这些恰恰是云服务通常在另一端替你跑、再按查询计费的部分。

支持的 Agent 很多，而且不是只说“理论兼容”

README 明确给出了 --agents 支持的目标：

  • claude-code
  • cursor
  • codex
  • gemini-cli
  • vscode
  • windsurf
  • zed
  • antigravity

而且仓库首页一开始还专门点名它能与：

  • Claude Code
  • Cursor
  • Codex
  • Gemini CLI
  • VS Code
  • Windsurf
  • Zed
  • Antigravity

协同工作。

除了这些，它还提到在更广的层面上，也可以对接：

  • LangChain
  • CrewAI
  • LlamaIndex
  • Vercel AI SDK
  • n8n 与自托管 agents
  • any MCP client
  • plain REST

这让 wigolo 的形象变得很清晰：它不是专门给某一个编辑器生态定制的小插件，而是一层相对通用的网络能力底座。

“免费”不是口号，它把费用逻辑解释得很清楚

README 一再强调的一件事是：$0 per query。但它并不是简单喊口号，而是解释了背后的原因。

项目默认通过 direct adapters 对接公共搜索引擎；reranker 和 embeddings 在本机执行；查询结果会被缓存。因此再次查询时既快，也不会继续消耗额外查询成本。换句话说，这个“免费”不是靠补贴，而是靠架构选择：把原本会被云服务计费的执行成本挪回本机。

这也解释了为什么 README 会反复提到 “no keys, no cloud, no metered bill”。它不是要做付费服务的“阉割免费版”，而是试图直接换一种成本结构。

但它也很诚实：有些能力如果想要合成答案，推荐接一个 LLM

README 有一段写得很坦白：以下能力默认可以 keyless 使用：

  • search
  • fetch
  • crawl
  • extract
  • cache
  • find-similar

而：

  • research
  • agent
  • search format=answer

如果希望输出综合后的、带引用的自然语言答案，就推荐配置一个 LLM。它甚至给了一个“推荐使用免费 key”的示例，使用 Gemini：

1
2
export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<free-key>

同时它也说明，可以选择：

  • anthropic
  • openai
  • groq

或者完全本地、继续 keyless 地使用：

  • WIGOLO_LLM_PROVIDER=ollama
  • 或任意 OpenAI-compatible URL

这段信息很重要，因为它说明 wigolo 的边界并不是“绝不碰 LLM”，而是“把 LLM 留给真正需要生成综合答案的那一步”。能用确定性逻辑做的，就尽量不用模型；要让答案写成像样的报告，再由模型接手。

返回结果这件事，它做得很“证据导向”

README 专门有一节叫 What your agent gets back。这部分非常关键，因为它展示了 wigolo 不只是把网页结果甩给代理，而是尽量把每条结果都包装成可追溯证据。

返回结果中包含：

  • title
  • url
  • excerpt
  • citation_id
  • source_span
  • evidence_score
  • freshness_signal

示例结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "results": [{
    "title": "Logical replication - PostgreSQL docs",
    "url": "https://www.postgresql.org/docs/current/logical-replication.html",
    "excerpt": "Logical replication is a method of replicating data objects…",
    "citation_id": "src-1",
    "source_span": { "start": 1042, "end": 1305 },
    "evidence_score": { "final": 0.86, "semantic": 0.91, "lexical": 0.78, "engine_consensus": 3 }
  }],
  "citations": [{ "id": "src-1", "url": "…" }],
  "freshness_signal": { "published": "2026-05-12", "confidence": "high" }
}

这里最有意思的，是它把“证据”而不是“答案”当成结果的基本单位。excerpt 有定位，citation 有标识，source span 有字节级区间，score 也被拆解成多个维度。这很像在对代理说：别只拿到一条模糊结论，请带着证据去工作。

它不掩盖失败，相反，它会把失败也写进结果里

README 多次强调一个词：honest output。

它明确说，以下情况不会被偷偷藏起来：

  • stale cache
  • failed fetches
  • degraded backends
  • truncation
  • failed engines
  • blocked_by_challenge

如果某个被 bot 保护的页面读不到，你得到的不会是假装成功的空结果，而是被明确标记为 blocked_by_challenge 的失败状态。

这种设计特别适合 Agent 场景，因为代理最怕的不是失败，而是“看起来成功但其实信息已经坏掉”的假象。wigolo 在这里选择的是尽量透明：弱结果会被自家 scorer 标记为 junk，失败引擎会被报告，陈旧缓存会被标注。它让代理知道自己站在什么地面上。

十个核心工具，把网络层的活几乎包圆了

README 的 Tools 表列出了 wigolo 的核心十个工具：

  • search
  • fetch
  • crawl
  • extract
  • cache
  • find_similar
  • research
  • agent
  • diff
  • watch

这十个名字很直观，但如果稍微读细一点，会发现每个工具后面都带着明确的定位。

多引擎 web search，支持 18 direct adapters，带 rank fusion、ML reranking，以及 explainable 的逐结果评分。还支持传入 query 数组并行扩展检索范围，也支持 domain、recency 等约束。

fetch

按层级升级的抓取路由器。能从普通 HTTP 抓取一路升级到 headless browser，以应对 anti-bot challenge 或 SPA shell，最后输出 clean markdown、metadata 和 links。

crawl

多页面 crawl，支持：

  • BFS
  • DFS
  • sitemap
  • map-only

并带有 per-domain rate limits、robots.txt respect、boilerplate dedup。

extract

从页面中提取结构化数据，包括：

  • tables
  • metadata
  • JSON-LD
  • brand identity
  • 命名 schema
  • 自定义 JSON Schema

cache

对已见内容进行检索，支持 keyword 或 hybrid semantic 查询，并提供 stats、clear 与 change detection。

find_similar

查找与某个 URL 或概念相似的页面，通过 keyword、semantic 和 live web 的三路融合完成。

research

把一个问题拆解成子查询，拉取来源，最后合成为带引用的报告，或者生成一个供宿主 LLM 编写的 structured brief。

agent

一个 autonomous gather loop：plan → search → fetch → extract → synthesize，并带 step log、time budget 和可选输出 schema。

diff + watch

查看页面与上次访问相比发生了什么变化，也可以按需重查，并把变化发送到 webhook。

这一整组工具看下来，会很容易感觉到：wigolo 真不是只把“搜网页”包装得更花一点，它是想把 Agent 在 Web 上的操作链条尽量补齐。

它主张“Code beats model”

在 Architecture 一节中，README 有一句非常能代表项目气质的话：Code beats model.

它解释得也很清楚：像 canonicalization、rank fusion、dedup、schema matching 这些确定性工作，尽量不交给 LLM；模型只保留给 judgment、而且是 opt-in，并按请求设上限。

这是一种相当清醒的工程取向。它不迷信模型，也不把所有工作塞给生成系统，而是尽量让能被规则与程序解决的部分继续由代码负责。LLM 在这里不是总导演，更像一位被谨慎安排出场时机的高级写手。

抓取路由是“信号驱动”的，而不是靠拍脑袋猜域名

README 中还有一段对 fetch ladder 的描述也很有味道：它会根据可观察信号决定是否升级到真实浏览器，比如：

  • SPA markers
  • challenge bodies
  • thin content

而不是先对域名贴标签、做静态猜测。它甚至还会按域名学习，再在条件变化时“unlearn”。

这种设计让它的抓取逻辑显得不像死规则，而更像一个会根据现象调整动作的执行层。项目还特别强调：

  • 会等待 interstitial challenge
  • 会复用每个域名的 clearance
  • 默认尊重 robots.txt
  • 有 per-domain rate limits

这说明它对“怎样读网页”这件事想得很细，不只是追求抓下来，而是想尽量像浏览器一样、又相对克制地读下来。

为什么它觉得自己和那些付费工具不一样

README 有一个 “Why it’s different” 小节，里面浓缩了项目最想表达的差异点。

为 Agent 而建

它强调，一次 MCP 调用可以并行展开多个 query，覆盖多个引擎，这是串行 host tool-loop 无法复制的。并且每个结果自带透明评分和引用结构，适合代理进一步推理或写答复。

输出诚实

降级、失败、陈旧、截断都不会被藏起来。代理拿到的是带着状态说明的结果，而不是被粉饰过的“看起来正常”。

查询成本为零，可自由重查

默认走公开引擎，本机运行 reranker 与 embeddings，所有结果都有缓存，因此反复追问也不会被账单追上来。

隐私默认更强

缓存、模型、embedding 和配置都在本地，除非显式启用 LLM synthesis，否则没有额外第三方流出。

这四点放在一起，基本就是 wigolo 的人格画像：它不是以“更炫 API”取胜，而是想在 Agent 场景里提供更便宜、更可控、更透明的 Web layer。

Benchmark 一节很有攻击性，但它的重点其实是“证据形式”

README 中的 Benchmark 部分写得非常醒目，尤其有一句总结：

All four tools converged on the same core answer, and only one of them handed back verbatim, byte-pinned evidence while doing it.

它说明一次冷启动查询在单个 Claude Fable 5 会话中，对四个工具进行了同台比较：

  • built-in WebSearch
  • wigolo
  • Tavily
  • Exa

后面给出了一张对比表。表中强调的差异包括：

  • 是否支持 multi-engine web search
  • 是否支持 fetch & structured extraction
  • 是否支持 whole-site crawl & map
  • 是否支持 verbatim excerpts pinned to byte-offset source spans
  • 是否支持 explainable per-result score decomposition
  • 是否支持 persistent local memory
  • 是否保证 query data stays on your machine
  • 是否需要 API key / account
  • 是否按 query 计费

在这张表里，wigolo 最突出的几项是：

  • byte-offset source spans
  • explainable score decomposition
  • persistent local memory
  • query data stays on your machine
  • API key: none
  • cost per query: $0

这组特征拼起来，和它前面“证据导向”“透明输出”“本地优先”的主线是完全一致的。

它不只活在编辑器里，也能跑 REST、SDK、Docker 和框架集成

wigolo 很明白一件事：代理不一定只住在编辑器里。所以 README 专门做了一个 Beyond your editor 部分。

REST API：wigolo serve

它可以开启一个本地 HTTP 服务：

1
wigolo serve

并用 curl 直接调用：

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

README 说明：

  • POST /v1/{tool} 覆盖全部十个工具
  • GET /openapi.json 提供 OpenAPI 3.1 contract
  • /mcp 和 /sse 用于 remote MCP clients
  • 如果绑定到 loopback 之外，就需要 bearer token

这意味着 wigolo 不只是一个本地 CLI，也是一套可以被其他系统直接消费的 API 层。

TypeScript SDK

README 给了 TypeScript SDK 的示例：

1
2
3
4
5
6
import { createLocalClient } from 'wigolo-sdk/local';

const { client, close } = await createLocalClient();
const res = await client.search({ query: 'local-first web search', max_results: 5 });
console.log(res.results.map((r) => r.title));
await close();

Python SDK

也给出了 Python 版本：

1
2
3
4
5
6
from wigolo import local_client

with local_client() as client:
    res = client.search(query="local-first web search", max_results=5)
    for r in res["results"]:
        print(r["title"], r["url"])

这两段示例都很有代表性：本地客户端会自动复用或拉起 daemon，使用门槛并不高。

Framework integrations

README 还列出了框架适配：

  • wigolo-langchain
  • wigolo-crewai
  • wigolo-llamaindex
  • wigolo-vercel-ai-sdk

它不是在说“理论上你可以集成”，而是已经把面向常见 agent framework 的入口包准备好了。

Docker

Docker 方式也被单独列了出来。既可以 stdio MCP 模式运行，也可以作为 HTTP server 暴露：

1
docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo

或：

1
2
3
docker run -p 3333:3333 -v wigolo-data:/data \
  -e WIGOLO_API_TOKEN=a-long-random-secret \
  ghcr.io/knockoutez/wigolo serve --host 0.0.0.0

这让它在本地开发、自托管代理、远程客户端等场景下都有了较明确的落点。

Agent skills 这一层，也说明它不只是给工具，还想教会代理怎么用

README 里提到一个 11-pack skill catalog，由 init 自动安装，也可以通过：

  • wigolo skills add
  • wigolo skills list
  • wigolo skills remove

进行管理。

这很能体现项目的产品意识。很多工具只把能力暴露出来，至于代理会不会用、会不会用得好，就留给使用者自己摸索。wigolo 则显然在试图进一步降低使用摩擦：不只给工具，还给方法。

配置部分很有层次感：默认可用，但有几个杠杆特别重要

README 说得很直白：干净安装后开箱即用，但有三组设置能明显抬高输出质量。

1. Synthesis

1
2
export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<your-key>

这是写出自然语言研究结论和答案的最大杠杆。

2. Wider retrieval funnel

1
2
export WIGOLO_SEARCH=hybrid
export WIGOLO_GITHUB_TOKEN=...

一个扩大检索漏斗，一个提升 GitHub code search 的速率上限。

3. 更强 fetch 与预热

1
2
export WIGOLO_TLS_TIER=auto
export WIGOLO_EAGER_WARMUP=1

一个决定抓取加固策略，一个让模型与组件提前热身。

这套配置很像给汽车调驾驶模式：默认可以开，但如果你愿意多拧几下旋钮，表现会更好。

文档与示例组织得也很完整

docs/README.md 说明文档覆盖了：

  • getting started
  • installation
  • configuration
  • tools
  • cli
  • rest api
  • sdks
  • self-hosting
  • skills
  • plugins
  • troubleshooting
  • privacy & security

而 examples/README.md 列出的示例包括：

  • quickstart-claude-code
  • one-shot-cli
  • shell-ndjson-pipeline
  • rest-curl
  • sdk-typescript-research
  • sdk-python-agent
  • vercel-ai-sdk-tools
  • n8n-remote-mcp
  • watch-changelog-webhook
  • plugin-search-engine

这说明 wigolo 不是只写了一个好看的首页 README，后面还配了相对完整的文档和样例路径。

它承认自己还在 public beta，但同时强调已经有大规模测试兜底

README 在 Beta & feedback 中说明：wigolo 目前是 public beta。不过它也补了一句很关键的话：文档中描述的内容是可工作的，并且由 7,600-test suite 维持稳定，beta 更多是 polish bar 的问题。

这让“beta”两个字的意味不太一样。不是“功能还没成形”，而更像“核心已经能跑，只是在打磨边角”。

这个项目最迷人的地方，是它试图把“上网”变成 Agent 的基础能力，而不是昂贵特权

读完 README，很容易发现 wigolo 的野心其实并不小。它不是想变成另一个“更便宜的搜索 API”，也不只是想做个抓网页的小工具。它更像是在重新设计这样一件事：

如果 AI 代理真的需要稳定、持续、低成本地使用 Web，它应当拥有怎样的一层本地能力栈？

于是你会看到它在几个方向上同时发力：

  • 把 search / fetch / crawl / extract 放进统一工具面
  • 用本地缓存、embedding 和 reranking 降低查询成本
  • 用透明评分、字节级证据定位和失败标记提升结果可信度
  • 用 MCP、REST、SDK、Docker 和框架集成把入口铺平
  • 在必要时才引入 LLM synthesis，而不是凡事都交给模型

这种思路很有力量，因为它把“让代理联网”从一种昂贵、分裂、易失真的附加能力，重新变成了一层相对扎实的本地基础设施。

如果把它拟人化，它像一个既会查、又会记、还很坦白的网络助手

它会去搜，而且不只搜一个引擎；
它会去抓，而且遇到障碍会换更强的抓取方式；
它会做爬取、提取、研究和相似查找；
它会把看过的东西缓存下来，下次不再白跑；
它会告诉你哪些结果可靠，哪些结果很弱，哪些页面压根没读成；
它甚至会承认自己受阻，而不是给你一份看起来体面的错误答案。

这份“坦白”其实很难得。因为在 Agent 世界里，真正危险的从来不是工具说“不行”，而是工具装作“可以”。

而 wigolo 最让人记住的地方，也许正是这一点：它不只是让代理能上网，更努力让代理知道，自己到底在网络上看到了什么、没看到什么，以及这些信息值不值得信。