wigolo:基于 MCP 的本地优先 Web 智能代理项目

---

wigolo 为 AI 智能体提供一站式网络相关功能：搜索、获取、爬取、提取、缓存、相似内容查找、研究以及自主收集循环。它可在智能体运行的任何环境中部署 — 作为 MCP 服务器与您的编码智能体协同工作，作为 REST/MCP 端点部署在自托管智能体所在的设备上，或通过 SDK 嵌入到您自己的应用中。核心工具无需 API 密钥，所有数据均存储在 ~/.wigolo/ 目录内，且不会因智能体的使用量而产生费用。

快速入门

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

需要 Node ≥ 20 以及 macOS、Linux 或 Windows 系统上约 1.5 GB 的可用磁盘空间。直接运行 init 即可设置本地引擎：它会下载浏览器引擎和本地模型，运行健康检查，并报告每个组件的状态。添加 --agents 可在同一运行过程中连接指定的代理，因此只需一条命令就能准备好你日常使用的编码代理。

• 支持的代理 — --agents 可接受 claude-code · cursor · codex · gemini-cli · opencode · vscode · windsurf · zed · antigravity 中的任意代理（用逗号分隔）；wigolo 会为每个代理编写 MCP 配置，并在支持的情况下提供相应说明。
• 其他设置方式 — 任何 MCP 客户端、代理框架或自托管代理都可在其自身的 MCP 配置中注册 npx -y wigolo。安装指南 提供了适用于所有客户端的确切配置块，以及 Docker、Homebrew 和单文件二进制等安装渠道。
• 更多功能即将推出 — 支持的代理列表不断增加，欢迎提交 PR 添加你的代理；详见 CONTRIBUTING.md。
• 交互式设置 — --interactive 是纯文本流程；--wizard 是完整的终端 TUI。
• 延迟下载 — --no-warmup 会等待首次使用时才进行下载。组件下载失败不会导致设置过程失败；初始化会报告未准备好的组件、确切的修复方法，并仍能完成设置。

init 默认无人值守，因此可安全用于脚本和 CI 环境，任何设置问题都会在每个组件的报告中直接显示，确保在代理首次调用前解决。搜索、获取、爬取、提取、缓存和相似内容查找功能均无需 API 密钥。 随时检查健康状态：

npx wigolo doctor

要彻底清除所有内容，请运行 npx wigolo config --uninstall --yes。您也可以将安装指南粘贴到任何 AI 助手中，让它完成设置；该指南的编写自成体系。

推荐 — 获取 research 和 agent 的免费密钥

搜索、获取、爬取、提取、缓存和相似内容查找功能完全无需密钥。research、agent 和 search format=answer 需使用 LLM 来生成经过综合且带有引用的答案。若没有 LLM，它们会返回原始摘要和证据，供您的智能体自行整合。免费的 Gemini 密钥可将其转化为完整的最终答案：

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<free-key>      # grab one at aistudio.google.com/apikey — the free tier is plenty

任何提供商均可使用（anthropic·openai·groq），或者通过设置WIGOLO_LLM_PROVIDER=ollama（或任何与 OpenAI 兼容的 URL）保持完全本地化且无需密钥。可在 shell 或智能体的 MCP env 块中进行设置。提供商、模型以及无密钥本地模型层级的相关信息，请参见配置指南。

智能体的返回内容

每一条搜索结果都是智能体可采取行动的依据。它包含一个固定在源文件中确切位置的逐字摘录、一个可供智能体引用的引用 ID，以及一个可供智能体查看的分数（真实结构节选）：

{
  "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 },          // byte-exact provenance
    "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 个直接适配接口），具备排序融合、机器学习重排序以及可解释的单结果评分。传入查询数组以实现并行广度搜索。可按域名和时间范围进行筛选，匹配精确短语，或返回图片结果。
📄 fetch	通过分层路由加载单个 URL，遇到反机器人挑战或单页应用外壳时，会自动从普通 HTTP 升级到无头浏览器引擎。返回干净的 markdown 格式内容、元数据及链接。支持处理 PDF、单标题 section、已认证会话以及页面操作（点击/输入/滚动/截图）。
🕸️ crawl	多页面爬取 — 支持广度优先搜索（BFS）、深度优先搜索（DFS）、站点地图或仅地图模式。具备按域名的速率限制、遵循 robots.txt 协议以及冗余内容去重功能。
🧩 extract	从页面中提取结构化数据：表格、元数据、JSON-LD、品牌标识、命名模式（文章/食谱/产品/…）或任何自定义 JSON 模式。
💾 cache	查询所有已获取的内容 — 支持关键词或混合语义搜索。此外还提供统计、清理和变更检测功能。
🧲 find_similar	通过关键词、语义和实时网络的三方融合，查找与给定 URL 或概念相似的页面。
🧠 research	分解问题 → 展开子查询 → 获取来源 → 综合生成带引用的报告（或主机 LLM 据此编写的结构化摘要）。
🤖 agent	自主收集循环：规划 → 搜索 → 获取 → 提取 → 综合，包含步骤日志、时间预算和可选的输出模式。
🔁 diff + ⏱️ watch	查看页面自上次访问以来的确切变化；按需重新检查并将变更通过 webhook 推送。

所有工具均可通过终端（wigolo search "…" --json）、带有 NDJSON 管道的交互式 shell（wigolo shell）、REST 接口以及 SDK 运行 — CLI 参考文档。包含完整参数集的各工具指南位于 docs/tools.md；可运行示例位于 examples/。

与众不同之处

wigolo 并非付费工具的免费替代品，而是旨在与之媲美。它是为您的智能体打造的专注网络层：一个 MCP 和 REST 接口，供智能体直接调用，其搜索和提取质量可与付费服务相提并论。它的独特之处在于：

• 专为智能体打造：一次 MCP 调用即可并行向多个引擎发起多个查询，这是串行主机工具循环无法实现的。每个结果都带有透明的结果评分，且输出会考虑预算因素。
• 真实输出：结果中会明确显示过时的缓存、失败的抓取、降级的后端服务以及内容截断等情况。当受机器人保护的页面无法读取时，您会得到一个标记为 blocked_by_challenge 的失败结果，而不是将验证页面伪装成内容返回。
• 每次查询零成本，可免费重复查询：默认搜索通过直接适配器与公共引擎交互；重排序器和嵌入模型在本地设备上运行。每个响应都会被缓存，因此再次查询既即时又无需任何成本。
• 默认隐私保护：缓存、嵌入、模型和配置文件均存储在 ~/.wigolo/ 目录下。除非您明确选择使用 LLM 进行内容合成，否则不会有任何数据发送给第三方。

以下是一个真实结果的剖析示例。其中包含了失败的引擎和质量较差的结果，因为这些也是答案的一部分：

基准测试

所有四款工具都得出了相同的核心答案，但其中只有一款在提供答案的同时，还返回了逐字逐句、精确到字节位置的证据。

在一个 Claude Fable 5 会话中实时运行了一个全新查询，该查询平等地分发到四款网络工具（内置的 WebSearch、wigolo、Tavily、Exa），并由智能体仅根据证据进行判断。所有四款工具都收敛到相同的答案和相同的顶级来源，因此屏幕上展示了它们的一致性。只有 wigolo 返回了精确到字节偏移源范围的逐字摘录、可解释的分数分解以及实时的每个引擎遥测数据，并且其自身的评分器将两个质量较差的结果标记为无用信息。云工具也各有其优势：Exa 完整呈现了官方文档的比较矩阵。运行您自己的查询，您会看到类似的结果。

功能对比

	wigolo	Firecrawl	Exa	Tavily
多引擎网络搜索	✅	✅	✅	✅
内容抓取与结构化提取	✅	✅	✅	✅
整站爬取与映射	✅	✅	—	✅
带字节偏移源范围标记的原文摘录	✅	—	—	—
可解释的单结果评分分解	✅	—	—	—
持久化本地存储 — 即时重新查询，支持离线	✅	—	—	—
查询数据仅保留在本地设备	✅	—	—	—
API 密钥 / 账户	无需	需	需	需
每次查询成本	$0	计量收费	计量收费	计量收费

_{功能状态截至 2026 年 7 月 — 具体请以各厂商文档为准。}

最后一行的影响会叠加，因为智能体通常会批量发起查询：

不止于编辑器

这十项工具适用于各类智能体，可通过多种方式集成：为编码智能体提供 MCP 支持，为其他场景提供 REST API，提供可嵌入的 SDK，以及即插即用的框架封装。

REST API — wigolo serve

单个进程可同时提供基于纯 JSON 的 REST API 和 MCP 传输。无需 MCP 客户端，直接使用 curl 即可：

wigolo serve                          # 127.0.0.1:3333 — loopback is open; off-loopback requires a token

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 token，因此服务器默认采用故障关闭模式。可将 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();   // reuse a running daemon, or spawn one
const res = await client.search({ query: 'local-first web search', max_results: 5 });
console.log(res.results.map((r) => r.title));
await close();                                          // stops the daemon only if this call spawned it

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

from wigolo import local_client

with local_client() as client:                          # reuse a healthy daemon, or spawn one
    res = client.search(query="local-first web search", max_results=5)
    for r in res["results"]:
        print(r["title"], r["url"])

→ SDK 与嵌入模式

框架集成

将 wigolo 的工具集成到您已在使用的框架中。您将获得完整的十项工具功能，包括大多数框架网络工具未提供的缓存、相似内容查找、研究和智能体功能：

框架	包	包含内容
LangChain	wigolo-langchain	每个工具均作为 BaseTool，并包含用于 RAG 的基于搜索/相似内容查找的 BaseRetriever
CrewAI	wigolo-crewai	wigolo_tools() → 可将工具集提供给任何智能体团队
LlamaIndex	wigolo-llamaindex	一个 BaseReader，可将获取、爬取、搜索到的页面加载为文档
Vercel AI SDK	wigolo-vercel-ai-sdk	适用于 generateText / streamText 的工具工厂，边缘友好

→ 框架集成

Docker

# stdio MCP — wire it into any MCP client as command: docker
docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo

# HTTP server for remote / multi-client use
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 可能无法突破家庭网络 IP 能够通过的限制。wigolo 会标记这些失败情况，自托管指南 中介绍了可选的代理解决方案。

星标历史

架构

单个 Node 进程支持 MCP（基于标准输入输出的 JSON-RPC）。所有重量级组件均为本地且延迟加载，因此零密钥安装不会为未使用的部分产生任何成本。

flowchart TD
    A["🤖 AI agent<br/>any MCP client · REST · SDK"]
    A -->|MCP over stdio| B["<b>wigolo</b><br/>10 tools · dynamic instructions<br/>in-process browser pool + cache + models"]

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

    T1 --> F["⚙️ Fetch router<br/>tiered escalation, learned per domain"]
    T1 --> S["⚙️ Search<br/>18 engines → rank fusion → ML rerank<br/><i>explainable evidence score</i>"]
    T2 --> DB[("🗄️ Local cache<br/>keyword + vector index")]
    T2 --> ML["🧠 On-device ML<br/>embeddings + reranker"]

    F -.->|optional| LLM["☁️ LLM<br/>synthesis only · opt-in"]
    S -.->|optional| SX["🔀 Aggregator backend<br/>opt-in legacy / hybrid"]

    F --> WEB["🌍 Public 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. Synthesis — the biggest lever (research / agent / search-answer write real prose)
export WIGOLO_LLM_PROVIDER=gemini                   # or anthropic / openai / groq / ollama (keyless)
export GEMINI_API_KEY=<your-key>

# 2. Wider retrieval funnel
export WIGOLO_SEARCH=hybrid                         # core engines + aggregator fallback
export WIGOLO_GITHUB_TOKEN=...                      # GitHub code search 10 → 30 req/min

# 3. Land more fetches, stay warm
export WIGOLO_TLS_TIER=auto                         # per-domain learned fetch hardening
export WIGOLO_EAGER_WARMUP=1                        # pay the ~1s model load up front

立竿见影的单次调用习惯： 查询数组（["a","b","c"]）以实现并行广度搜索 · 对重要查询使用 search_depth: "deep" · 将 include_domains 用作文档查找的硬性筛选条件。完整参考涵盖了所有环境变量、配置文件键、搜索后端、缓存 TTL 和服务限制；详情请参见 configuration guide。

文档与示例

docs/ — 完整手册： getting started · installation & channels · configuration · tools reference · CLI & shell · REST API · SDKs & integrations · self-hosting · agent skills · plugins · troubleshooting & FAQ · privacy & security

examples/ — 可直接运行，每个示例都配有 README（大多数还附有终端操作录制）：一次性 CLI、NDJSON shell 管道、通过 curl 调用 REST API、TypeScript 和 Python SDK、Vercel AI SDK 工具、将自托管 n8n 指向远程 wigolo、带 Webhook 的监控，以及编写您自己的搜索引擎插件。文档也在网站上呈现：knockoutez.github.io/wigolo/docs。

Beta 版与反馈

wigolo 目前处于公开测试阶段。此处记录的所有功能均可正常使用，并通过了 7,600 项测试用例的验证；它是稳定的，测试阶段主要关注完善度。在足够多的用户使用、测试并为其添加星标，使得称之为 v1 版本具有实际意义之前，它将一直保持测试版状态。您的反馈将决定后续发展方向，每一条反馈都会被阅读，通常会在同一天处理：

• 🐛 Report a bug — 程序崩溃、行为异常或让您感到意外
• 💡 Request a feature — 它应该具备的某项功能
• 💬 Ask anything — 问题、设置、展示与分享

如果 wigolo 在您的工作流程中占据了一席之地，以下三件事可以帮助它持续发展：点亮一个 ⭐ star（这是开源项目被发现的方式）、请喝一杯 ☕ coffee（本项目没有也永远不会有付费层级），或者发送**an email** 直接与代码的唯一开发者联系。

故障排除

wigolo doctor 会指出任何损坏的组件以及修复它的确切环境变量或命令；wigolo doctor --fix 可修复常见问题，wigolo verify 则会对每个组件进行健康检查。init 过程中组件失败不会导致 wigolo 无法使用：init 仍会正常退出（返回代码 0），核心的搜索、获取、爬取、提取和缓存功能在没有模型和浏览器的情况下依然可以工作。常见问题快速解决：

• 下载缓慢或失败 — 重新运行 wigolo warmup --all（或 --browser / --embeddings / --reranker）；它们会恢复并重试下载。
• Linux 上浏览器无法启动 — wigolo warmup --browser 会安装所需的操作系统库（或打印确切的安装命令）。
• 原生构建错误 / Node 版本异常 — 使用 LTS 版本：Node 20、22 或 24。
• 位于代理服务器后方 — 设置 USE_PROXY=true + PROXY_URL；对于进行 TLS 检查的代理，需添加 NODE_EXTRA_CA_CERTS。

完整指南涵盖了按症状分类的修复方法、“当 X 失败时哪些功能仍可正常工作”的对应表、平台注意事项（包括 linux-arm64）以及离线安装说明：docs/troubleshooting.md。

常见问题

免费使用？有什么隐藏条件吗？

设计上就没有隐藏条件。那些成本高昂的部分（排序、嵌入、浏览器引擎）都运行在您自己的硬件上，因此不存在按查询次数收费的成本回收问题，也就没有理由设置计量计费。项目通过捐赠维持运营，并且 AGPL 许可证从法律上阻止其转变为闭源的托管产品。

质量真的能与付费服务相媲美吗？

上文的基准测试部分是一个可复现的实时四方对比：日常代理查询的结果达到了同等水平，付费工具在某些深度提取的边缘案例中仍然更胜一筹，而爬取能力则是 wigolo 的强项。每个结果都会显示其评分，因此您无需轻信他人之言。

公共搜索引擎不会屏蔽或限制吗？

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 目录。

贡献指南

欢迎提交错误报告、功能请求和 PR；详情请参见 CONTRIBUTING.md。请保持工具处理程序精简，添加测试，并在提交 PR 前运行测试套件。最友好的入门点是用于自定义搜索引擎和提取器的插件系统：约 100 行代码即可添加一个搜索引擎，examples/plugin-search-engine 目录中提供了模板。

许可协议

GNU AGPL-3.0-only。可免费使用、修改和自托管，包括在公司内部使用。唯一的义务是：如果您将修改后的版本作为网络服务运行，则必须以相同许可协议发布您的修改源代码。这确保了 wigolo 的开源性，同时防止出现闭源的托管分支。有关漏洞报告，请参见 SECURITY.md；有关名称使用规则，请参见 TRADEMARK.md。商业许可相关问题，欢迎联系我们。