wigolo

为AI coding agent打造的本地优先web智能层，提供搜索、抓取、爬取、提取等10个工具，通过MCP协议与Claude Code、Cursor等主流agent无缝集成。亮点：无需API Key、完全本地运行、零成本每查询，内置18个搜索引擎适配器和on-device重排序，结果附带字节级证据评分和透明调试信息。采用AGPL-3.0许可证，本地使用无限制。

README

面向AI智能体的本地优先网页智能——无需密钥、无需云服务、无计量账单。

可与 Claude Code · Cursor · Codex · Gemini CLI · VS Code · Windsurf · Zed · Antigravity 配合使用
此外还有 LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n 及自托管智能体 · 任何 MCP 客户端 · 原生 REST

快速开始 · 工具 · 为什么不同 · 基准测试 · 文档 · 示例 · 反馈 · 常见问题

wigolo 为 AI 智能体提供了一个统一的网页处理接口——搜索、抓取、爬取、提取、缓存、相似查找、研究，以及自主收集循环。它在你智能体运行的地方运行：作为 MCP 服务器与你的编码智能体并肩运行，作为 REST/MCP 端点部署在你自托管智能体的机器上，或通过 SDK 嵌入到你自己的应用中。核心工具无需 API 密钥，所有操作数据都不会离开 ~/.wigolo/，而且没有随智能体思考而增长的费用。

wigolo 演示——Claude Code 通过 wigolo 回答实时网页问题，无需 API 密钥

快速开始

需要 Node ≥ 20 和约 1.5 GB 可用磁盘空间。支持 macOS、Linux 和 Windows。

一条命令即可将本地引擎连接到你的智能体。init 默认无人值守——无需提示，适用于脚本和 CI——并完成完整设置：下载浏览器引擎和本地模型、运行健康检查、打印各组件摘要，这样任何设置问题都会在此处直接显示，而不会在智能体首次调用时静默失败：

npx wigolo init --agents=<your-agent>

<your-agent> —— 一个或多个（逗号分隔）：claude-code · cursor · codex · gemini-cli · vscode · windsurf · zed · antigravity。wigolo 会为你写入 MCP 配置和说明。
其他 MCP 客户端？ 省略 --agents，自行注册 npx -y wigolo——安装指南提供了每个客户端的精确配置块，以及 Docker、Homebrew 和单文件二进制通道。
偏好提示式交互？ --interactive 是纯文本流程；--wizard 是完整的终端 TUI。
跳过下载？ --no-warmup 将所有操作推迟到首次使用。组件下载失败不会导致设置失败——init 会报告未就绪的内容并提供精确修复，但仍会连接你的智能体。

这就是完整设置——搜索、抓取、爬取、提取、缓存和相似查找无需 API 密钥。 随时检查健康状态：

npx wigolo doctor

不适合你？npx wigolo config --uninstall --yes 将干净地移除所有内容。你也可以将安装指南粘贴到任何 AI 助手中，让它帮你完成设置——该指南是自包含的。

你的智能体会得到什么

不是片段——而是证据。每个搜索结果都带有精确指向原文位置的逐字摘录、智能体可引用的引用 ID，以及可检查的评分（缩写后的真实结构）：

{
  "results": [{
    "title": "逻辑复制 - PostgreSQL 文档",
    "url": "https://www.postgresql.org/docs/current/logical-replication.html",
    "excerpt": "逻辑复制是一种复制数据对象的方法…",
    "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" }
}

弱结果会被 wigolo 自身的评分器标记为垃圾，失败的引擎会被报告，过期的缓存会被标注——智能体始终知道它所依赖的是什么。每个工具的完整响应契约请参考工具参考。

工具

工具	功能
🔎 `search`	多引擎网页搜索（18 个直接适配器），带排序融合、ML 重排序和可解释的逐结果评分。传递查询数组可实现并行广度搜索。
📄 `fetch`	通过分层路由器加载单个 URL——从普通 HTTP 自动升级到无头浏览器引擎，以应对反爬挑战或 SPA 壳。返回干净的 Markdown + 元数据 + 链接。
🕸️ `crawl`	多页面爬取——BFS、DFS、站点地图或仅地图。按域速率限制、尊重 robots.txt、去重样板内容。
🧩 `extract`	从页面中提取结构化数据：表格、元数据、JSON-LD、品牌标识、命名模式（文章/食谱/产品/……），或任何自定义 JSON Schema。
💾 `cache`	查询所有已见过内容——关键字或混合语义。此外还有统计、清除和变更检测功能。
🧲 `find_similar`	通过关键字 + 语义 + 实时网页的三路融合，查找与某 URL 或概念相似的页面。
🧠 `research`	分解问题 → 展开子问题 → 获取来源 → 综合生成带引用的报告（或由宿主 LLM 撰写的结构化摘要）。
🤖 `agent`	自主收集循环：规划 → 搜索 → 获取 → 提取 → 综合，附带步骤日志、时间预算和可选的输出 schema。
🔁 `diff` + ⏱️ `watch`	查看页面自上次访问后的确切变化；按需重新检查并将变化发送到 webhook。

每个工具也都可以从终端运行（wigolo search "…" --json）、从带有 NDJSON 管道的交互式 shell 运行（wigolo shell）、通过 REST 运行，以及通过 SDK 运行——请参考 CLI 参考。

这些工具实际能做什么

每个工具远不止一行描述。以下示例——每行都链接到指南，若有可运行示例也会附带：

展开式搜索——传递查询数组以实现并行广度搜索，通过 include_domains 限定范围，通过 time_range/recency 绑定时效，精确短语匹配，选择深度层级，甚至支持图片结果。→ 指南 · 示例
抓取几乎任何内容——JS 渲染的 SPA、PDF、单个标题部分 section、经过身份验证的页面（通过浏览器配置文件或远程浏览器），或通过 actions 驱动页面（点击/输入/滚动/截图）。→ 指南
爬取整个网站——站点地图、BFS、DFS 或仅地图；尊重 robots.txt、按域速率限制、去重样板内容。→ 指南
提取结构化数据——表格、JSON-LD、元数据、品牌资产、命名模式（文章/食谱/产品/……），或你自己的 JSON Schema。→ 指南
记忆累积——每个页面都被缓存；通过关键字或语义重新查询，即时且离线；检测自上次访问以来的变化。→ 指南 · 示例
研究与自主收集——将问题分解为带引用的摘要，或者让 agent 按 JSON Schema 和时间预算自主规划 → 获取 → 提取 → 综合。→ 指南 · 示例
监控与差异——监控一个 URL，获取变更报告，并将其发送到 webhook。→ 指南 · 示例
按你的方式驱动——单次 CLI、用于管道的 NDJSON shell、REST、SDK，或作为你的智能体可安装的技能。→ CLI 和 shell · 示例
扩展它——用大约 100 行代码添加一个搜索引擎或站点提取器作为插件。→ 插件 · 示例
调优与检查——wigolo tune 显示每个域的学习结果（使用的获取层级、挑战清除、退避策略）；doctor / verify 健康检查每个组件。→ CLI · 故障排除

为什么它不同

wigolo 不是你在预算到位之前暂时忍受的免费替代品——它旨在与这一领域的付费服务保持同等水平，并且有数据支撑。它的真正区别在于：

专为智能体而非人类设计。 一次 MCP 调用即可在多个引擎上并行展开多个查询——这是串行主机工具循环无法复制的——并提供透明的逐结果评分和预算感知输出。
诚实的输出。 过期的缓存、失败的获取、退化的后端以及截断都会在结果中明确显示，绝不会伪装成空但成功的数据。当受机器人保护的页面无法读取时，你会得到一个标记为 blocked_by_challenge 的失败——绝不会收到伪装成内容的挑战壳。
每次查询零费用，免费重复查询。 默认搜索通过直接适配器与公共引擎通信；重排序器和嵌入在本地运行。每个响应都被缓存，因此再次提问是即时的，且无需任何费用。
默认私有。 缓存、嵌入、模型和配置都存放在 ~/.wigolo/ 下。除非你明确选择使用 LLM 进行合成，否则不会触及任何第三方。

wigolo 是为你的智能体提供的专注于网页的层——不是一个托管的 SaaS、一个供其他应用查询的向量数据库，或一个大规模爬取平台。在这一领域，它在结果质量上与付费服务不相上下——而计费器、密钥和数据出口根本不存在。

以下是一个真实结果的详细剖析——包括失败的引擎和弱结果，因为它们也是答案的一部分：

wigolo 结果剖析：可解释的分数分解、实时引擎遥测、暴露的退化、自我标记的垃圾——一个真实查询，实时捕获

基准测试

四种工具都收敛到了相同的核心答案——但只有其中一种在给出答案的同时，还返回了带字节级证据的逐字摘录。

一次冷启动查询，在同一个 Claude Fable 5 会话中实时运行，并平等地扩展到四种网页工具——内置的 WebSearch、wigolo、Tavily 和 Exa——然后由智能体根据一条规则自行报告：仅凭证据评判，不得偏袒。四种工具都收敛到了相同的答案和相同的顶级来源——证明了同等水平，而非宣称。只有 wigolo 返回了带字节偏移源范围的逐字摘录、可解释的分数分解以及实时逐引擎遥测——并且当其中两个结果较弱时，其自身的评分器在屏幕上将其标记为垃圾。云工具也有其价值：Exa 完整呈现了官方文档的比较表格。一次诚实的查询，不是排行榜——你自己运行一下就能看到同样的结果。

wigolo 与内置 WebSearch、Tavily 和 Exa 在同一个真实查询上的对比，由 Claude Fable 5 驱动

相同的战斗，不同的物理规则

	wigolo	Firecrawl	Exa	Tavily
多引擎网页搜索	✅	✅	✅	✅
抓取与结构化提取	✅	✅	✅	✅
全站爬取与地图	✅	✅	—	✅
带字节偏移源范围的逐字摘录	✅	—	—	—
可解释的逐结果分数分解	✅	—	—	—
持久的本地记忆——立即离线重新查询	✅	—	—	—
查询数据留在你的机器上	✅	—	—	—
API 密钥 / 账户	无	必需	必需	必需
每次查询成本	$0	按量计费	按量计费	按量计费

特性状况截至 2026 年 7 月——请检查各供应商文档以了解当前状态。

最后一行是关键——智能体不会只问一次，它们会爆发式地提问：

计费器：计量云 API 的成本随每次查询攀升，而 wigolo 保持为零美元——示意性定价

超出编辑器之外

同样的十个工具服务于各种智能体，通过任意适合的接口——MCP 用于编码智能体，REST 用于其他一切，SDK 用于嵌入，框架封装用于即插即用。

REST API — `wigolo serve`

一个进程在 MCP 传输之外暴露一个纯 JSON 的 REST API。不需要 MCP 客户端——只需 curl：

wigolo serve                          # 127.0.0.1:3333 — 环回开放；非环回需要令牌

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

POST /v1/{tool} 涵盖所有十个工具，GET /openapi.json 是 OpenAPI 3.1 契约，/mcp + /sse 从同一端口为远程 MCP 客户端提供服务。绑定到非环回地址后必须使用 bearer 令牌——服务器默认安全关闭，而非意外开放。指向 n8n、Hermes 风格的助手或任何自托管智能体。→ REST API

SDK — TypeScript 和 Python

精简、带类型的客户端，内置本地模式，可为你查找或启动守护进程——无需单独的 serve 步骤。

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 });
console.log(res.results.map((r) => r.title));
await close();                                          // 仅当此调用启动了守护进程时才停止它

Python — pip install wigolo（仅标准库；同步 + 异步）：

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"])

→ SDK 和嵌入式模式

框架集成

将 wigolo 的工具放入你已使用的框架中——完整的十工具接口，包括大多数框架网页工具未提供的 cache / find_similar / research / agent：

框架	包	获得的功能
LangChain	`wigolo-langchain`	每个工具作为一个 `BaseTool`，外加一个基于 search / find_similar 的 `BaseRetriever`，用于 RAG
CrewAI	`wigolo-crewai`	`wigolo_tools()` → 将工具集交给任何 crew
LlamaIndex	`wigolo-llamaindex`	一个 `BaseReader`，将获取/爬取/搜索的页面作为文档加载
Vercel AI SDK	`wigolo-vercel-ai-sdk`	用于 `generateText` / `streamText` 的工具工厂，友好于边缘环境

→ 框架集成

Docker

# stdio MCP — 将其作为命令: docker 连接到任何 MCP 客户端
docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo

# HTTP 服务器，用于远程/多客户端使用
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

精简镜像会将模型延迟加载到卷中；:full 预装浏览器引擎。也可在 Docker Hub 上作为 towhid69420/wigolo 使用。→ 安装和所有渠道

智能体技能

一个包含 11 个包的技能目录，教导你的编码智能体如何擅长使用每个工具——由 init 安装，通过 wigolo skills add|list|remove 管理。→ 技能

给自托管用户一个诚实的提示：某些受挑战保护的网站会评估 IP 声誉，因此数据中心 IP 可能无法通过普通家庭连接能够通过的障碍。wigolo 会标记这些失败而非伪造它们，自托管指南涵盖了可选的代理解决方案。

Star 历史

实时图表——它会自动更新。如果你读到此时它仍在上升，添加一个 ⭐。

架构

一个单一的 Node 进程，通过 MCP（基于 stdio 的 JSON-RPC）进行通信。所有重组件都是本地且延迟加载的，因此零密钥安装不会为未使用的部分付费。

flowchart TD
    A["🤖 AI 智能体<br/>任何 MCP 客户端 · REST · SDK"]
    A -->|MCP over stdio| B["<b>wigolo</b><br/>10 个工具 · 动态指令<br/>进程内浏览器池 + 缓存 + 模型"]

    B --> C{"工具层"}
    C --> T1["search · fetch · crawl · extract"]
    C --> T2["cache · find_similar · research · agent"]

    T1 --> F["⚙️ 获取路由器<br/>分层升级，按域学习"]
    T1 --> S["⚙️ 搜索<br/>18 个引擎 → 排序融合 → ML 重排序<br/><i>可解释的证据分数</i>"]
    T2 --> DB[("🗄️ 本地缓存<br/>关键字 + 向量索引")]
    T2 --> ML["🧠 本地 ML<br/>嵌入 + 重排序器"]

    F -.->|可选| LLM["☁️ LLM<br/>仅用于合成 · 选择性加入"]
    S -.->|可选| SX["🔀 聚合器后端<br/>可选的传统/混合模式"]

    F --> WEB["🌍 公共网页"]
    S --> WEB

    style B fill:#7c3aed,stroke:#5b21b6,color:#fff
    style WEB fill:#0ea5e9,stroke:#0369a1,color:#fff
    style DB fill:#1e293b,stroke:#334155,color:#fff
    style LLM stroke-dasharray: 5 5
    style SX stroke-dasharray: 5 5

代码胜过模型。 确定性的工作——规范化、排序融合、去重、模式匹配——永远不会触及 LLM。模型仅用于判断、选择性加入，且每次请求有上限；由 LLM 填充的字段会对照来源进行检查，若不存在则置为 null。
基于可观察信号的路径选择。 获取阶梯根据它看到的内容升级到真正的浏览器——SPA 标记、挑战体、内容稀疏——而不是域猜测。它会按域学习，当某个站点不再需要时也会遗忘，wigolo tune list 会精确显示它学到了什么。
像浏览器一样读取页面——并在无法读取时明确告知。 分层获取会等待插页式挑战，并按域重用清除，礼貌地：尊重 robots.txt、按域速率限制、研究级量。当障碍持续存在时，失败会被标记，绝不伪装。

配置

全新安装即可开箱即用。以下三个设置能显著提升输出质量：

# 1. 合成——最大的杠杆（research / agent / search-answer 写出真正的散文）
export WIGOLO_LLM_PROVIDER=gemini                   # 或 anthropic / openai / groq / ollama（免密钥）
export GEMINI_API_KEY=<你的密钥>

# 2. 更广的检索漏斗
export WIGOLO_SEARCH=hybrid                         # 核心引擎 + 聚合器备用
export WIGOLO_GITHUB_TOKEN=...                      # GitHub 代码搜索 10 → 30 req/min

# 3. 获取更多页面，保持热状态
export WIGOLO_TLS_TIER=auto                         # 按域学习的获取强化
export WIGOLO_EAGER_WARMUP=1                        # 提前支付约 1 秒的模型加载时间

值得注意的每次调用习惯： 查询数组 (["a","b","c"]) 用于并行广度 · search_depth: "deep" 用于重要查询 · include_domains 作为文档查找的硬限制。

完整的参考——每个环境变量、配置文件键、搜索后端、缓存 TTL 和服务器限制——位于配置指南中。

文档与示例

docs/ —— 完整手册：入门指南 · 安装与渠道 · 配置 · 工具参考 · CLI 与 Shell · REST API · SDK 与集成 · 自托管 · 智能体技能 · 插件 · 故障排除与 FAQ · 隐私与安全

examples/ —— 可运行示例，每个都带有 README（大多数还带有终端录制）：单次 CLI、NDJSON Shell 管道、通过 curl 的 REST、TypeScript 和 Python SDK、Vercel AI SDK 工具、指向远程 wigolo 的自托管 n8n、带 webhook 的监视功能，以及编写你自己的搜索引擎插件。

文档也呈现在网站上：knockoutez.github.io/wigolo/docs。

Beta 与反馈

wigolo 目前处于公开测试版。这里记录的所有功能都能正常工作，并经过 7,600 项测试套件的验证——beta 阶段关注的是完善程度，而非稳定性。它将保持测试版，直到足够多的人使用、测试和点赞它，使得称之为 v1 具有意义。

这意味着你的反馈就是现在的一切。每份报告都会阅读，通常当天回复：

🐛 报告 Bug —— 出错、行为异常、让你意外
💡 请求功能 —— 它应该能做某事
💬 随便问 —— 问题、设置、展示与分享

如果 wigolo 在你的设置中赢得了位置，你可以通过这些方式支持它的持续发展：一个 ⭐ star（这是开源项目被发现的方式）、一杯 ☕ 咖啡（没有付费层级，永远不会有），或者只是 一封邮件——它会直接到达编写代码的唯一开发者手中。

常见问题

免费？有什么陷阱？

设计上就没有陷阱。昂贵的部分——排序、嵌入、浏览器引擎——在你的硬件上运行，因此没有每次查询的成本需要回收，也没有理由使用计费器。通过捐赠维持；AGPL 许可证在法律上防止了诱骗后转向封闭托管产品的可能。

质量真的能与付费服务相提并论吗？

运行一次查询自己判断——上面的基准测试部分是实时四路运行，而非图表。日常智能体查询达到同等水平；付费工具在某些深度提取的边缘场景上仍然更胜一筹，而爬取是 wigolo 的强项。每个结果都显示其评分，所以你无需相信任何人的话。

公共搜索引擎不会屏蔽或失效吗？

这正是它为之设计的：18 个引擎通过排序融合（任何一个失败几乎不会影响结果）、带有按域学习的分层获取阶梯，以及可选的聚合器备用。后端退化会在输出中报告，永远不会隐藏——而本地缓存意味着所有已见过的内容无论怎样都能正常工作。

这种抓取方式合规吗？

wigolo 以浏览器的方式读取公共网页——默认尊重 robots.txt、按域速率限制、适用于单机单智能体的研究级量。它刻意处于礼貌的一端，而不是一个收割平台。

AGPL——我可以在工作中使用它吗？

可以，自由地在公司范围内使用。许可证只在你修改 wigolo 并将其作为网络服务运行时才会生效——此时你必须发布这些修改。将其用作本地开发工具则没有任何义务。商业许可问题：请联系我们。

为什么需要 1.5 GB 磁盘？

那是本地大脑：完整的浏览器引擎加上云端服务在它们那端运行并向你收费的排序和嵌入模型。磁盘很便宜；计费器不是。

可用渠道

npm —— wigolo （主要渠道——上面的快速开始）
PyPI —— wigolo （Python SDK）
Docker —— ghcr.io/knockoutez/wigolo · towhid69420/wigolo
官方 MCP 注册表 —— io.github.KnockOutEZ/wigolo
目录 —— Glama · Smithery · mcp.so · LobeHub

Homebrew、curl | sh 和单文件二进制文件在安装指南中介绍——每台机器一个渠道；它们共享 ~/.wigolo。

贡献

欢迎提交 Bug 报告、功能请求和 PR——请参阅 CONTRIBUTING.md。保持工具处理程序精简，添加测试，在提交 PR 前运行测试套件。最友好的切入点：wigolo 有一个用于自定义搜索引擎和提取器的插件系统——用大约 100 行代码添加一个搜索引擎，模板在 examples/plugin-search-engine。

许可证

GNU AGPL-3.0-only。 可免费使用、修改和自托管——包括在公司内部。唯一义务：如果你将修改过的版本作为网络服务运行，则必须按照相同许可证发布你的修改源码。这可以在防止封闭托管分支的同时保持 wigolo 的开放性。请参阅 SECURITY.md 报告漏洞，TRADEMARK.md 了解名称的使用。商业许可问题，请联系我们。

wigolo 是免费的，并将保持免费——维护，而非付费墙。如果它为你节省了一份按量计费的搜索账单，一个 ⭐、一个尖锐的 issue，或一杯 ☕ 咖啡 将有助于使其可持续发展。

由 @KnockOutEZ 构建和维护 · ktowhid20@gmail.com

开源项目KnockOutEZ2026-07-18原文

打开互动版

wigolo

README

快速开始

推荐——免费密钥使 `research` 和 `agent` 大放异彩

你的智能体会得到什么

工具

这些工具实际能做什么

为什么它不同

基准测试

相同的战斗，不同的物理规则

超出编辑器之外

REST API — `wigolo serve`

SDK — TypeScript 和 Python

框架集成

Docker

智能体技能

Star 历史

架构

配置

文档与示例

Beta 与反馈

常见问题

可用渠道

贡献

许可证

相关内容

G0DM0D3

kimi-cli

code-review-graph

cwc-workshops

Bonsai-demo

wigolo

README

快速开始

推荐——免费密钥使 research 和 agent 大放异彩

你的智能体会得到什么

工具

这些工具实际能做什么

为什么它不同

基准测试

相同的战斗，不同的物理规则

超出编辑器之外

REST API — wigolo serve

SDK — TypeScript 和 Python

框架集成

Docker

智能体技能

Star 历史

架构

配置

文档与示例

Beta 与反馈

常见问题

可用渠道

贡献

许可证

相关内容

G0DM0D3

kimi-cli

code-review-graph

cwc-workshops

Bonsai-demo

推荐——免费密钥使 `research` 和 `agent` 大放异彩

REST API — `wigolo serve`