KnockOutEZ/wigolo 源码：https://github.com/KnockOutEZ/wigolo

面向 AI 智能体的本地优先网络智能——无需密钥、无需云端、无按量计费。

适用于 Claude Code · Cursor · Codex · Gemini CLI · VS Code · Windsurf · Zed · Antigravity 及其他
以及 LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n 与自托管智能体 · 任何 MCP 客户端 · 纯 REST

npm (https://www.npmjs.com/package/wigolo)
npm 下载量 (https://www.npmjs.com/package/wigolo)
GitHub 星标 (https://github.com/KnockOutEZ/wigolo/stargazers)
CI (https://github.com/KnockOutEZ/wigolo/actions/workflows/ci.yml)
node (https://nodejs.org)
MCP (https://modelcontextprotocol.io)
许可协议
状态
在 X 上关注 (https://x.com/yourtowhid)

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

新功能和更新稳定发布。关注 @yourtowhid（X 平台）获取全部动态和 wigolo 的新用法，也可在那里寻求合作或反馈 · 也可通过 LinkedIn 联系

wigolo 为 AI 智能体提供一个统一界面，涵盖所有网络相关操作：搜索、获取、爬取、提取、缓存、相似查找、研究以及自主收集循环。它在你智能体运行的任何地方运行——作为 MCP 服务器与你的编码智能体并列运行，作为 REST/MCP 端点在你自托管智能体所在的机器上运行，或通过 SDK 嵌入到你自己的应用中。核心工具无需 API 密钥，操作内容不会离开 ~/.wigolo/ 目录，并且不会随智能体的思考量而产生账单。

快速开始

npx wigolo init                    # 设置本地引擎——适用于任何系统
npx wigolo init --agents=claude-code,cursor   # ...或一次性设置并连接你日常使用的智能体

需要 Node ≥ 20 以及 macOS、Linux 或 Windows 上约 1.5 GB 的可用磁盘空间。纯 init 命令设置本地引擎：下载浏览器引擎和本地模型，运行健康检查，并报告每个组件的状态。添加 --agents 可在同一运行中连接指定的智能体，使你日常使用的编码智能体一次命令即可就绪。

• 支持的智能体 —— --agents 可接受以下任意值（逗号分隔）：claude-code · cursor · codex · gemini-cli · vscode · windsurf · zed · antigravity；wigolo 会为每个智能体写入 MCP 配置和指令。
• 任何其他设置 —— 任何 MCP 客户端、智能体框架或自托管智能体将其 MCP 配置注册为 npx -y wigolo。安装指南 提供了每个客户端的精确配置块，以及 Docker、Homebrew 和单文件二进制渠道。
• 更多在途 —— 支持的列表不断增长，欢迎提交 PR 添加你的智能体；参见 CONTRIBUTING.md。
• 交互式设置 —— --interactive 是纯文本流程；--wizard 是完整的终端 TUI。
• 延迟下载 —— --no-warmup 会等到首次使用时才下载。某个组件的下载失败不会导致设置失败；init 会报告哪些组件未就绪并提供精确修复方法，但依然完成设置。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=   # 在 aistudio.google.com/apikey 获取一个——免费额度绰绰有余

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

你的智能体将获得什么

每个搜索结果都是智能体可以采取行动的证据。它包含一段逐字摘录，锁定到其在源中的精确位置、一个智能体可以引用的引用 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 自带的评分器标记为垃圾。失败的引擎会被报告，过时的缓存会被标记，这样智能体始终知道它所依据的信息状态。每个工具的完整响应协议见工具参考。

工具

每个工具也可从终端运行（wigolo search "..." --json）、从支持 NDJSON 管道的交互式 shell（wigolo shell）、通过 REST 以及通过 SDK 运行——参见 CLI 参考。每个工具的完整参数指南见 docs/tools.md；可运行的示例见 examples/。

为什么选择 wigolo

wigolo 并不是付费工具的免费替代品——它被设计为与之匹敌。它是一个专门为你的智能体设计的网络层：智能体可以直接调用的 MCP 和 REST 界面，具备付费服务所收取的搜索和提取质量。其与众不同之处在于：

• 专为智能体构建。 一次 MCP 调用即可在各个引擎上并行展开多个查询，这是串行的宿主工具循环无法复制的。每个结果都带有透明的逐结果评分，输出也考虑预算因素。
• 诚实的输出。 过期的缓存、失败的获取、降级的后端以及截断信息都会在结果中显示。当某个反爬页面无法读取时，你会得到一个标记为 blocked_by_challenge 的失败，而不是作为内容返回一个挑战页面外壳。
• 每次查询 $0，免费重新查询。 默认搜索通过直接适配器与公共引擎通信；重排序器和嵌入模型在本地运行。每个响应都被缓存，因此再次查询是即时的且无需成本。
• 默认隐私。 缓存、嵌入、模型和配置都存放在 ~/.wigolo/ 下。除非你明确选择使用 LLM 进行综合，否则不会将数据发送给第三方。

下面是一个真实结果的解析示例。其中包含失败的引擎和弱结果，因为它们也是答案的一部分：

基准测试

所有四个工具都收敛于相同的核心答案，但只有其中一个在提供逐字、字节精确证据的同时完成了这一点。

一次冷查询在一个 Claude Fable 5 会话中实时运行，向四个网络工具（内置 WebSearch、wigolo、Tavily、Exa）平等展开，并由智能体仅根据证据进行评判。所有四个工具都收敛于相同的答案和相同的顶级来源，因此一致性已在屏幕上展示。wigolo 独自分返回了锁定到字节偏移来源范围的逐字摘录、可解释的分数分解以及实时的每引擎遥测数据，并且其自带的评分器将两个弱结果标记为垃圾。云端工具也有其价值：Exa 完整渲染了官方文档的对比矩阵。运行你自己的查询，你将看到同样的结果。

对比情况

（截至 2026 年 7 月的功能状态——请查看各供应商文档了解当前状态。）

最后一行影响重大，因为智能体是突发性请求的：

超越你的编辑器

同样的十个工具适用于所有类型的智能体，通过适合的表面：MCP 用于编码智能体，REST 用于其他一切，SDK 用于嵌入，以及框架包装器用于直接集成。

REST API — wigolo serve

一个进程在 MCP 传输旁边暴露一个纯 JSON REST API。无需 MCP 客户端，只需 curl：

wigolo serve   # 127.0.0.1:3333 — loopback 开放；非 loopback 需要令牌
curl -sX POST http://127.0.0.1:3333/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"本地优先软件","max_results":5}'

POST /v1/{tool} 覆盖所有十个工具，GET /openapi.json 是 OpenAPI 3.1 合约，/mcp + /sse 从同一端口为远程 MCP 客户端提供服务。绑定到非 loopback 时需要 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: '本地优先网络搜索', 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="本地优先网络搜索", max_results=5)
    for r in res["results"]:
        print(r["title"], r["url"])

→ SDK 与嵌入式模式

框架集成

将 wigolo 的工具放入你已有的框架中。你将获得完整的十个工具表面，包括大多数框架网络工具未提供的 cache / find_similar / research / agent：

→ 框架集成

Docker

# stdio MCP — 将其作为 command: 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 会标记这类失败，并且自托管指南涵盖了可选的代理解决方案。

星标历史

每天从 GitHub API 刷新。如果你觉得 wigolo 有用，请添加一个 ⭐。

架构

单个 Node 进程通过 MCP（基于 JSON-RPC over stdio）进行通信。所有重量级组件都是本地且懒加载的，因此零密钥安装不会为未使用的部分付出任何代价。

flowchart TD
  A["🤖 AI 智能体<br/>任何 MCP 客户端 · REST · SDK"]
  A -->|MCP over stdio| B["wigolo<br/>10 tools · 动态指令<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/>可解释的证据分数"]
  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=...