KnockOutEZ/wigolo

GitHub: KnockOutEZ/wigolo

基于 MCP 协议的本地优先网络智能工具，为 AI 编程 agent 提供免密钥、零成本的搜索、抓取、爬虫与研究能力。

Stars: 303 | Forks: 23

基于 MCP 的本地优先网络智能工具 —— **无需密钥，不依赖云服务，无按量计费。** _{兼容 **Claude Code · Cursor · Codex · Gemini CLI · VS Code · Windsurf · Zed · Antigravity**} [![npm](https://img.shields.io/npm/v/wigolo?color=cb3837&logo=npm)](https://www.npmjs.com/package/wigolo) [![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)](https://nodejs.org) [![MCP](https://img.shields.io/badge/MCP-server-7c3aed)](https://modelcontextprotocol.io) [![license](https://img.shields.io/badge/license-AGPL--3.0-2563eb)](#license) [![status](https://img.shields.io/badge/status-public%20beta-b7791f)](#beta--feedback) [快速开始](#quickstart) · [工具](#tools) · [为什么选 wigolo](#why-its-different) · [基准测试](#benchmark) · [架构](#architecture) · [配置](#configuration) · [反馈](#beta--feedback) · [常见问题](#faq) · [可用平台](#available-on) · [贡献](#contributing)

wigolo 在你的机器上作为 MCP 服务器运行，为 AI 编程 agent 提供一个持久的界面，处理所有与网络相关的操作 —— **搜索、抓取、爬虫、提取、缓存、查找相似内容、研究**，以及自动收集循环。核心工具不需要任何 API 密钥，所触及的所有内容都不会离开 `~/.wigolo/` 目录，而且不会随着 agent 思考量的增加而产生高昂的账单。

wigolo demo — Claude Code answering a live web question through wigolo, no API keys

## 快速开始要求 **Node ≥ 20** 以及约 1.5 GB 的可用磁盘空间。支持 macOS、Linux 和 Windows。只需一条命令即可安装本地引擎（搜索、浏览器、on-device 模型），自动将其接入你的 agent，并设置好 MCP 连接： ``` npx wigolo init --non-interactive --agents= ``` - **``** —— 可以是 `claude-code` · `cursor` · `codex` · `gemini-cli` · `vscode` · `windsurf` · `zed` · `antigravity` 中的一个或多个（以逗号分隔）。wigolo 会为你编写 MCP 配置和说明 —— 无需其他设置。 - **使用其他支持 MCP 的 agent？** 省略 `--agents` —— 引擎仍会以无头模式安装，你可以自行将 agent 指向 wigolo 的 MCP 服务器（`npx wigolo mcp`）。这就是全部设置 —— **搜索、抓取、爬虫、提取、缓存和查找相似内容均无需 API 密钥即可工作。** 检查运行状态是否正常： ``` npx wigolo doctor ``` 不适用？使用 `npx wigolo config --uninstall --yes` 即可彻底、干净地移除一切。 ### 手动 MCP 设置（任何其他 agent） `--agents` 标志为上面列出的每个 agent 都提供了内置的安装程序 —— 但它无法覆盖世界上所有的 agent。对于**任何其他工具 —— 你自定义或内部的 agent，或者任何我们尚未实现自动接入的支持 MCP 的客户端** —— 请手动设置 wigolo：它只是一个普通的 MCP 服务器。首先安装引擎，然后进行注册： ``` npx wigolo init --non-interactive # engine only: models, browser, cache — no agent wiring ``` 大多数客户端会在 JSON 配置文件中使用一个 `mcpServers` 块： ``` { "mcpServers": { "wigolo": { "command": "npx", "args": ["-y", "wigolo"] } } } ``` 不带任何子命令直接运行 `wigolo` 即可启动 MCP stdio 服务器（这是默认行为）。如果你进行了全局安装，请改用 `"command": "wigolo", "args": []`。 **文件位置和确切的键名因客户端而异：** | Agent | 配置文件 | 服务器键名 | |-------|-------------|-------------| | Cursor | `~/.cursor/mcp.json` | `mcpServers` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | | Gemini CLI | `~/.gemini/settings.json` | `mcpServers` | | Antigravity | `~/.antigravity/mcp.json` | `mcpServers` | | VS Code | 用户 `mcp.json`（命令面板 → *MCP: Open User Configuration*） | `servers` | | Zed | `~/.config/zed/settings.json` | `context_servers` | | Claude Code | *（无文件）* 运行 `claude mcp add wigolo --scope user -- npx -y wigolo`（`--scope user` = 全局；仅用于项目时请去掉此参数） | — | | Codex | `~/.codex/config.toml`（TOML 格式，不是 JSON） | `[mcp_servers.wigolo]` | | 其他 | 注册 MCP 服务器的对应位置 | 其对应的 MCP 服务器键名 | Codex 使用 TOML 而非 JSON： ``` [mcp_servers.wigolo] command = "npx" args = ["-y", "wigolo"] ``` 要为手动接入的 agent 启用答案合成（见下文），请将提供商和密钥添加到服务器的 `env` 中： ``` { "mcpServers": { "wigolo": { "command": "npx", "args": ["-y", "wigolo"], "env": { "WIGOLO_LLM_PROVIDER": "gemini", "GEMINI_API_KEY": "" } } } } ``` ### 让 AI 为你完成设置设置过程非常简单，完全可以交给 AI 来完成。请求你的编程 agent（Claude Code、Cursor 等）—— 或者任何聊天助手（ChatGPT、Claude、Gemini）—— 代为执行，它们都可以按照上述步骤操作。粘贴类似以下的提示词：该提示词是自包含的，因此即使是无法访问网络的助手也能据此采取行动。如果助手*能够*浏览网络，请将其引导至本 README（上面的**手动 MCP 设置**部分包含了每个客户端的确切配置路径）或项目机器可读的 **`llms.txt`** 文件 —— 两者都包含了完整的操作流程，包括下方可选的 LLM 合成 `env` 设置。 ### 可选 —— 启用答案合成 `research`、`agent` 和 `search format=answer` 会使用 LLM 来*编写*最终答案。通过设置**提供商及其密钥**（在你的 shell 或 agent 的 MCP `env` 块中）来开启它们。`WIGOLO_LLM_PROVIDER` 指定所使用的 LLM —— 与密钥一起设置： ``` export WIGOLO_LLM_PROVIDER=gemini export GEMINI_API_KEY= # free from https://aistudio.google.com/apikey — the free tier is plenty ``` 任何提供商都可以 —— 使用 `anthropic` + `ANTHROPIC_API_KEY`、`openai` + `OPENAI_API_KEY` 或 `groq` + `GROQ_API_KEY`。为了保持完全本地化和无密钥，可以设置 `WIGOLO_LLM_PROVIDER=ollama`（或本地服务器 URL）。推荐使用 Gemini，因为其免费额度对 wigolo 来说绰绰有余。 ### 使用 Docker 运行使用预构建的镜像无需自行安装 Node 即可运行 MCP 服务器。它内置了浏览器引擎和 on-device 模型，默认命令是 stdio MCP 服务器。 ``` docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo ``` `-i` 标志为 MCP 协议保持 stdin 开启，volume 会在多次运行间持久化保存本地缓存和模型（首次运行会下载模型）。将其接入 Claude Code： ``` claude mcp add wigolo --scope user -- docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo ``` 任何 MCP 客户端的工作方式都相同：将 `command` 设置为 `docker`，将 `args` 设置为上面的运行标志。该镜像也在 Docker Hub 上提供，名称为 `towhid69420/wigolo`。 ## 工具 | 工具 | 功能描述 | |------|--------------| | 🔎 `search` | 多引擎网络搜索（18 个直接适配器），具备排名融合、ML 交叉编码器重排序，以及可解释的单项结果评分。传入查询**数组**可实现并行的广度搜索。 | | 📄 `fetch` | 通过分层路由（HTTP → TLS 指纹模拟 → 无头浏览器）加载 URL，遇到反机器人验证或 SPA 外壳时会自动升级策略。输出干净的 markdown + 元数据 + 链接。 | | 🕸️ `crawl` | 多页爬虫 —— 支持 BFS、DFS、sitemap 或仅 map 模式。具备每域名速率限制、robots.txt 尊重及样板内容去重功能。 | | 🧩 `extract` | 从页面提取结构化数据：表格、元数据、JSON-LD、品牌标识、命名 schema（Article / Recipe / Product / ……），或任何自定义 JSON Schema。 | | 💾 `cache` | 查询已见过的所有内容 —— 关键词（BM25）或混合（BM25 + on-device 向量）模式。还提供统计、清理和变更检测功能。 | | 🧲 `find_similar` | 通过关键词 + 语义 + 实时网络的三方融合，查找与某个 URL 或概念相似的页面。 | | 🧠 `research` | 拆解问题 → 扩散子查询 → 抓取来源 → 合成带引用的报告（或由宿主 LLM 生成的结构化摘要）。 | | 🤖 `agent` | 自主收集循环：规划 → 搜索 → 抓取 → 提取 → 合成，具备步骤日志、时间预算和可选的输出 schema。 | | 🔁 `diff` + ⏱️ `watch` | 精确查看自上次访问以来页面发生的变化；按计划重新检查，并将变更推送到 webhook。 | ## 为什么与众不同 wigolo 并不是你在预算批准前勉强使用的免费替代品 —— 它的构建初衷就是为了在该领域与付费服务保持同等水准，并且有事实为证。它的真正独特之处在于： - **专为 agent 打造，而非人类。** 一次 MCP 调用就能在多个引擎上并行扩散多个查询 —— 这是串行的宿主工具循环无法复制的 —— 并且具备透明的单项结果评分和预算感知输出。 - **诚实的输出。** 过期的缓存、失败的抓取、降级的后端和截断的内容都会在结果中如实呈现，绝不会伪装成空但成功的数据。 - **单次查询 $0，重新查询免费。** 默认搜索通过直接适配器与公共引擎通信；重排序器和嵌入模型在本地运行。每个响应都会被缓存，因此再次询问是瞬间完成的，且无需任何成本。 - **默认保护隐私。** 缓存、嵌入、模型和配置都存放在 `~/.wigolo/` 目录下。除非你明确选择加入 LLM 进行合成，否则任何数据都不会传输给第三方。 wigolo 是一个专为单台机器上的单个 agent 打造的专注网络层 —— 它不是托管型 SaaS，不是供其他应用程序查询的向量数据库，也不是浏览器自动化框架。在这个领域内，它在结果质量上与付费服务不相上下 —— 而且完全没有计量表、密钥和数据外发。以下是一个真实结果的剖析 —— 其中包含了失败的引擎和微弱的结果，因为这些也是答案的一部分：

Anatomy of a wigolo result: explainable score decomposition, live engine telemetry, surfaced degradation, self-flagged junk — one real query, captured live

## 基准测试在同一个 **Claude Fable 5** 会话中进行的一次实时冷查询，在同等条件下向四个网络工具扩散 —— 内置的 **WebSearch**、**wigolo**、**Tavily** 和 **Exa** —— 然后由 agent 本身按照一个规则进行汇报：仅根据证据进行评判，不偏袒。查询内容为：`when to choose logical vs streaming replication in Postgres`。核心重点就在报告本身中：**所有四个工具都得出了相同的核心答案。** 与付费工具拥有相同的顶级来源，得出相同的结论 —— 这是事实展示的对等性，而非空口无凭。在此基础上，wigolo 是这四个工具中唯一一个返回**带有字节偏移源位置范围和引用 ID 的逐字引用摘录**，**可解释的每项结果分数分解**（交叉编码器、词法、引擎共识），以及**实时每个引擎的遥测数据**的 —— 而当它的两个结果较弱时，**它自己的评分器直接在屏幕上将它们标记为垃圾内容**。云工具也有其亮点：Exa 完整渲染了官方文档的比较矩阵。两边的优势都由驱动这四个工具的同一个模型直接道出。这是一次诚实的查询，而不是为了制作排行榜 —— 自己运行一次，你就会看到相同的形态：这个无密钥的本地工具与付费服务并肩而立，以 $0 的成本且不泄露任何机器数据的情况下，为你的 agent 提供其他工具无法提供的证据。以下是完整的运行过程：

wigolo vs built-in WebSearch, Tavily, and Exa on one real query, driven by Claude Fable 5

### 相同的较量，不同的物理特性付费工具确实非常出色 —— 这正是对等性令人感兴趣的原因。剩下的一些差异不在于质量，而在于物理特性： | | wigolo | Firecrawl | Exa | Tavily | |---|:---:|:---:|:---:|:---:| | 多引擎网络搜索 | ✅ | ✅ | ✅ | ✅ | | 抓取与结构化提取 | ✅ | ✅ | ✅ | ✅ | | 全站爬取与映射 | ✅ | ✅ | — | ✅ | | 带有字节偏移源位置范围的逐字摘录 | ✅ | — | — | — | | 可解释的单项结果分数分解 | ✅ | — | — | — | | 持久化本地内存 —— 即时重新查询，离线可用 | ✅ | — | — | — | | 查询数据保留在你的机器上 | ✅ | | — | — | | API 密钥 / 账号 | 无 | 必须 | 必须 | 必须 | | 单次查询成本 | $0 | 按量计费 | 按量计费 | 按量计费 | _{功能状态截至 2026 年 7 月 —— 请查看各供应商的文档获取最新状态。} 最后一行才是影响累积成本的关键 —— agent 不会只查询一次，它们会进行突发式查询：

The meter: a metered cloud API's cost climbs with every query while wigolo stays flat at zero dollars — illustrative pricing

## 架构一个使用 MCP（基于 stdio 的 JSON-RPC）通信的单 Node 进程。所有繁重的工作都在本地进行且延迟加载，因此零密钥安装不会为它未使用的部分付出任何代价。 ``` flowchart TD A["🤖 AI coding agent
any MCP client"] A -->|MCP over stdio| B["wigolo
10 tools · dynamic instructions
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
HTTP → TLS-impersonation → headless browser
per-domain learning"] T1 --> S["⚙️ Search
18 engines → RRF fusion → cross-encoder rerank
explainable evidence score"] T2 --> DB[("🗄️ SQLite
url cache · FTS5 keyword · sqlite-vec")] T2 --> ML["🧠 On-device ML
BGE-small embeddings (384d)
MiniLM cross-encoder reranker"] F -.->|optional| LLM["☁️ Cloud LLM
synthesis only · opt-in"] S -.->|optional| SX["🔀 Aggregator backend
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 ``` - **代码胜过模型。** 确定性的工作 —— 规范化、排名融合、去重、schema 匹配、哈希处理 —— 永远不会触及 LLM。模型仅用于判断（可选加入，且按请求设加上限）。由 LLM 填充的字段会与来源进行核对，如果不存在则置空，因此幻觉不会进入你的输出。 - **基于可观测信号的路由。** 抓取阶梯根据它*看到*的内容升级到真实浏览器 —— SPA 标记、挑战主体、单薄内容 —— 而不是猜测域名。它会按域名进行学习，并在某个网站不再需要它时忘记该规则。 - **透明、诚实的结果。** 每个结果都附带分数明细和查询理解块；降级状态总是被如实呈现，绝不隐瞒。

wigolo's fetch escalation ladder: plain HTTP, then TLS-impersonation on challenge signals, then a headless browser on SPA shells — learned and unlearned per domain

## 配置全新安装开箱即用。一些设置可以显著提升输出质量 —— 将它们设为环境变量或放在 agent 的 MCP `env` 块中。 ``` # Synthesis —— 最大的杠杆。research / agent / search-answer 需要一个 LLM # 来编写最终文本。设置 provider 及其 key（仅提供 key 会被忽略）。 export WIGOLO_LLM_PROVIDER=gemini # names the LLM; free tier is plenty (or anthropic/openai/groq) export GEMINI_API_KEY= # that provider's key (ANTHROPIC_API_KEY / OPENAI_API_KEY / …) # ...或者完全本地且无需 key： export WIGOLO_LLM_PROVIDER=ollama （或一个本地 http URL） # 2. 更宽的检索漏斗 export WIGOLO_SEARCH=hybrid # core engines + aggregator fallback export WIGOLO_GITHUB_TOKEN=... # GitHub code search 10 → 30 req/min + org-private # 3. 完成更多 fetch，保持 warm export WIGOLO_TLS_TIER=auto # per-domain TLS-impersonation past Cloudflare/DataDome export WIGOLO_EAGER_WARMUP=1 # pay the ~1s model load up front, not on first search ``` 对于重复的交互式使用，请运行 `wigolo serve`，以便浏览器池、嵌入模型和重排序器在多次调用之间保持驻留。为了保持 100% on-device，一个本地 LLM 端点 + `WIGOLO_TLS_TIER=auto` 是最基本且诚实的配置组合。 **回报丰厚的单次调用习惯：** 使用查询**数组** (`["a","b","c"]`) 获得并行的广度覆盖 · 对于重要的查询使用 `search_depth: "deep"` · 将 `include_domains` 作为查找文档时的硬过滤器。

CLI 命令

| 命令 | 功能描述 | |---------|--------------| | `wigolo` / `wigolo mcp` | 启动 MCP stdio 服务器（默认命令）。 | | `wigolo init` | 设置 wigolo：安装组件，接入检测到的 agent。在 CI 中使用 `--non-interactive --agents= --provider= --search=`。 | | `wigolo setup mcp` | 仅重新编写 MCP 服务器条目，不运行完整的向导。 | | `wigolo doctor` | 冷启动健康检查 —— 不进行网络抓取。 | | `wigolo verify` | 端到端冒烟测试（抓取、爬虫、提取、搜索、重排、嵌入）。 | | `wigolo serve` | HTTP 守护进程 —— 跨多个客户端保持子系统活跃。 | | `wigolo shell` | 交互式 REPL（使用 `--json` 进行管道传输）。 | | `wigolo config` | 设置 TUI；或无头模式 `--set K=V`、`--export`、`--import`、`--cleanup`、`--uninstall --yes`。 | | `wigolo status` | 纯文本状态摘要。 | | `wigolo health` | Ping 正在运行的守护进程的 `/health` 接口。 | | `wigolo backfill` | 为尚无向量的缓存页面生成嵌入（支持 `--batch-size`、`--dry-run`）。 | | `wigolo plugin add\|list\|remove` | 管理自定义提取器 / 搜索引擎插件。 | | `wigolo uninstall` | 从 agent 配置中移除 wigolo（保留你的缓存）。 |

环境变量 —— 搜索与引擎

| 变量 | 默认值 | 作用 | |-----|---------|--------| | `WIGOLO_SEARCH` | `core` | `core`（直接引擎）/ `searxng`（旧版）/ `hybrid`（核心 + 回退）。 | | `BRAVE_API_KEY` | — | 设置后，Brave 将加入引擎池（仅限环境变量，不持久化）。 | | `WIGOLO_GITHUB_TOKEN` | — | 将 GitHub 代码搜索限制从 10 次请求/分钟提升至 30 次；启用组织私有搜索（仅限环境变量）。 | | `SEARXNG_URL` | — | 外部聚合器 URL；设置后，跳过本地引导。 | | `SEARXNG_MODE` | `native` | `native`（Python venv）或 `docker`。 | | `SEARXNG_PORT` | `8888` | 本地聚合器的端口。 | | `SEARXNG_QUERY_TIMEOUT_MS` | `8000` | 对聚合器的每次查询超时时间。 | | `WIGOLO_MULTI_QUERY_CONCURRENCY` | `5` | 最大并行（查询 × 引擎）任务数。 | | `WIGOLO_MULTI_QUERY_MAX` | `10` | 规范化后的最大唯一查询数。 | | `WIGOLO_QUERY_EXPAND_VARIANTS` | `5` | 启发式查询扩展变体数。 | | `SEARCH_NARROW_RENDER_MAX_CANDIDATES` | `3` | 在丰富内容期间，限定于特定域名（`include_domains`）的搜索在浏览器引擎中渲染结果页面的最大候选数 —— 用于从大量依赖 JS 的文档站点恢复真实内容。仅限于少数 URL；广泛搜索永远不会升级。设为 `0` 可禁用。 |

环境变量 —— 抓取、网络与 TLS

| 变量 | 默认值 | 作用 | |-----|---------|--------| | `USER_AGENT` | 轮换的 Chrome UA | 覆盖 User-Agent 标头。 | | `FETCH_TIMEOUT_MS` | `10000` | HTTP 请求超时。 | | `FETCH_MAX_RETRIES` | `2` | 针对 429 / 502 / 503 / 网络错误的重试预算。 | | `MAX_REDIRECTS` | `5` | 手动模式下的重定向上限。 | | `PLAYWRIGHT_LOAD_TIMEOUT_MS` | `15000` | 浏览器 `page.load` 等待时间。 | | `PLAYWRIGHT_NAV_TIMEOUT_MS` | `30000` | 浏览器导航超时。 | | `SEARCH_FETCH_TIMEOUT_MS` | `15000` | 搜索中针对每个结果的水合抓取时间。 | | `SEARCH_TOTAL_TIMEOUT_MS` | `30000` | 总体搜索预算。 | | `USE_PROXY` / `PROXY_URL` | `false` / — | 通过代理路由抓取。 | | `WIGOLO_TLS_TIER` | `off` | `off` / `auto`（按域名学习）/ `on`（始终优先尝试 TLS）。 | | `WIGOLO_TLS_BROWSER` | `chrome_142` | TLS 指纹配置文件（`_`）。 | | `WIGOLO_TLS_SUCCESS_THRESHOLD` | `3` | 域名触发切换到优先 TLS 的成功次数。 |

环境变量 —— 浏览器池与认证

| 变量 | 默认值 | 作用 | |-----|---------|--------| | `MAX_BROWSERS` | `3` | 每种浏览器类型的最大并发上下文。 | | `BROWSER_IDLE_TIMEOUT` | `60000` | 空闲上下文驱逐时间（毫秒）。 | | `BROWSER_FALLBACK_THRESHOLD` | `3` | 强制使用浏览器前某域名的 HTTP 失败次数。 | | `WIGOLO_BROWSER_TYPES` | 自动（全部 3 种） | 要使用的浏览器 CSV 列表（chromium, firefox, webkit）。 | | `WIGOLO_CDP_URL` | — | 用于远程 / 已登录浏览器的 Chrome DevTools 端点。 | | `WIGOLO_AUTH_STATE_PATH` | — | Playwright `storageState.json`（cookies / localStorage）。 | | `WIGOLO_CHROME_PROFILE_PATH` | — | 完整的 Chrome `User Data` 目录（每次使用时复制到临时目录）。 |

环境变量 —— 缓存与爬虫

| 变量 | 默认值 | 作用 | |-----|---------|--------| | `CACHE_TTL_SEARCH` | `86400` | 搜索结果缓存 TTL（秒）。 | | `CACHE_TTL_CONTENT` | `604800` | 页面内容缓存 TTL（7 天）。 | | `WIGOLO_FAST_STALE_MAX_HOURS` | `24` | 在 `cache` 模式下，接受不超过此时长（小时）的条目。 | | `WIGOLO_FAST_TIMEOUT_MS` | `800` | 缓存模式回退抓取的严格超时时间。 | | `CRAWL_CONCURRENCY` | `2` | 每个公共域名的并发抓取数。 | | `CRAWL_DELAY_MS` | `500` | 每个公共域名请求间的延迟。 | | `CRAWL_PRIVATE_CONCURRENCY` | `10` | 每个私有域名的并发数（localhost / RFC1918）。 | | `CRAWL_PRIVATE_DELAY_MS` | `0` | 每个私有域名的延迟。 | | `RESPECT_ROBOTS_TXT` | `true` | 为 false 时，不获取 robots.txt。 | | `VALIDATE_LINKS` | `true` | 为 false 时，跳过断链探测。 | | `WIGOLO_CRAWL_INDEX` | — | `1` → 抓取的页面将排入嵌入队列。 | | `WIGOLO_WAIT_FOR_INDEX` | — | `1` → 嵌入队列按页面同步运行。 |

环境变量 —— 重排序器、嵌入与相关性

| 变量 | 默认值 | 作用 | |-----|---------|--------| | `WIGOLO_RERANKER` | `onnx` | `onnx`（交叉编码器）/ `none`（仅限共识 + 权威性 + 近期度提升）。 | | `WIGOLO_RERANKER_MODEL` | `Xenova/ms-marco-MiniLM-L-6-v2` | 交叉编码器模型 ID。 | | `WIGOLO_RERANKER_IDLE_TIMEOUT_MS` | `300000` | 最后一次使用后将模型保持活跃 5 分钟。 | | `WIGOLO_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` | 嵌入模型（384 维）。 | | `WIGOLO_EMBEDDING_IDLE_TIMEOUT` | `1800000` | 空闲卸载（30 分钟）。 | | `WIGOLO_EMBEDDING_MAX_TEXT_LENGTH` | `8000` | 嵌入前的截断长度。 | | `WIGOLO_RELEVANCE_THRESHOLD` | `0` | agent 抓取后过滤器的最小相关性。 | | `WIGOLO_FIND_SIMILAR_COLD_START_THRESHOLD` | `0.02` | 低于此融合分数时，`find_similar` 会发出 `cold_start`。 |

环境变量 —— LLM 集成（全部可选）

| 变量 | 默认值 | 作用 | |-----|---------|--------| | `WIGOLO_LLM_PROVIDER` | — | `anthropic` / `openai` / `gemini` / `groq` / 自定义 URL（Ollama, vLLM, LM Studio）。 | | `WIGOLO_LLM_MODEL` | — | 通用模型覆盖。 | | `WIGOLO_LLM_MODEL_{ANTHROPIC\|OPENAI\|GEMINI\|GROQ}` | — | 特定于提供商的模型覆盖（优先级最高）。 | | `WIGOLO_LLM_MAX_CALLS_PER_REQUEST` | `1` | 每次工具调用 LLM 次数的硬性上限。 | | `WIGOLO_LLM_CACHE_TTL_DAYS` | `7` | LLM 响应缓存 TTL。 | | `WIGOLO_LOCAL_LLM` | `off` | 可选择加入的无密钥本地语言模型层：`off`（默认）/ `auto`（自动检测本地模型服务器）/ 显式的 `http(s)://` 端点。off 保持无密钥路径不变。 | | `WIGOLO_LOCAL_LLM_MODEL` | — | 本地层的首选模型名称；未设置时自动选取已安装的模型。 | | `IGOLO_LOCAL_LLM_BASE_URL` | `http://localhost:11434` | 当 `WIGOLO_LOCAL_LLM=auto` 时探测的端点（回退到 `WIGOLO_LLM_BASE_URL`，然后是默认的本地服务器）。 | | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | — | 每次调用时读取；从不持久化。 | | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Gemini 提供商密钥（两者皆可；每次调用时读取，从不持久化）。 | | `GROQ_API_KEY` | — | 同上。 | | `WIGOLO_LLM_API_KEY` | — | 用于 `WIGOLO_LLM_PROVIDER` 指定提供商的通用密钥。特定于提供商的变量优先；在自动检测期间被忽略。 | 密钥也可以存放在 OS 钥匙串或经 AES 加密的文件中（`wigolo init` / `wigolo config`）—— 绝不会存放在 `config.json` 中。 |

环境变量 —— 守护进程、预热、路径、日志与杂项

| 变量 | 默认值 | 作用 | |-----|---------|--------| | `WIGOLO_DATA_DIR` | `~/.wigolo` | 缓存、模型、密钥、插件、聚合器 venv 的根目录。 | | `WIGOLO_CONFIG_PATH` | `${DATA_DIR}/config.json` | 持久化配置路径。 | | `WIGOLO_DAEMON_PORT` | `3333` | `wigolo serve` 的监听端口。 | | `WIGOLO_DAEMON_HOST` | `127.0.0.1` | 绑定地址。 | | `WIGOLO_EAGER_WARMUP` | — | `1` → 在启动时预热嵌入 + 重排序器（触发即忘）。 | | `WIGOLO_BOOTSTRAP_MAX_ATTEMPTS` | `3` | 聚合器引导重试限制。 | | `WIGOLO_HEALTH_PROBE_INTERVAL_MS` | `30000` | 后台后端健康探测周期。 | | `WIGOLO_PLUGINS_DIR` | `${DATA_DIR}/plugins` | 插件发现根目录。 | | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error`。 | | `LOG_FORMAT` | `json` | `json` 或对人类友好的 `text`。 | | `WIGOLO_TELEMETRY` | — | `1` → 本地 NDJSON 事件日志（默认关闭，无 PII）。 | | `WIGOLO_TELEMETRY_ENDPOINT` | — | 同时将事件“触发即忘”地 POST 到此 URL。 | | `WIGOLO_TUI_REDUCED_MOTION` | — | `1` → 禁用 TUI 加载动画 / 动画效果。 |

常用的单次调用选项（工具参数）

| 选项 | 适用工具 | 说明 | |--------|-------|-------| | `mode` | fetch, search, crawl, extract, find_similar | `cache`（快速，可接受旧数据）/ `default`（智能路由）/ `stealth`（全功能浏览器，无缓存）。 | | `search_depth` | search | `ultra-fast`（仅缓存）/ `fast` / `balanced`（默认）/ `deep`（证据 + 重排高亮）。 | | `query` | search | `string` 或 `string[]` —— 数组将并行扩散。 | | `include_domains` / `exclude_domains` | search, find_similar, research | 硬性白名单 / 黑名单（主机后缀匹配）。 | | `format` | search | `answer` / `stream_answer` —— 触发带引用的 LLM 合成。 | | `citation_format` | search, crawl, research, agent | `numbered` / `json` / `anthropic_tags`。 | | `time_range` / `from_date` / `to_date` | search | 时间范围边界。 | | `render_js` | fetch | `auto` / `always` / `never`。 | | `use_auth` | fetch, crawl | 通过配置的认证路由（CDP > Chrome 配置文件 > 存储状态）。 | | `actions` | fetch | 连续的浏览器操作（`click`、`type`、`wait`、`wait_for`、`scroll`、`screenshot`）。 | | `section` | fetch | 提取某个标题下的 markdown 子树。 | | `strategy` | crawl | `bfs` / `dfs` / `sitemap` / `auto` / `map`。 | | `mode` (extract) | extract | `selector` / `tables` / `metadata` / `schema` / `structured` / `brand`。 | | `named_schema` | extract | `Article` / `Recipe` / `Product` / `CodeSnippet` / `Paper` / `EventListing`。 | | `depth` | research | `quick` / `standard` / `comprehensive`。 | | `max_pages` / `max_time_ms` | agent | 单次调用的页面上限（默认 3）和实际时间预算。 | | `max_tokens_out` | 大多数 | 总体输出 token 预算（默认 4000）。 | | `include_full_markdown` | fetch, crawl, research, agent | `false` → 返回证据摘录而非完整正文。 |

## Beta 版与反馈 wigolo 目前处于**公测阶段**。这里记录的所有功能均可正常工作，并且经过了 6,000 个测试用例的检验 —— Beta 阶段关注的是打磨程度，而非稳定性。在有足够多的人使用它、给它挑刺、为它点亮 Star，并让 v1 版本的发布变得真正有意义之前，它将一直处于 Beta 阶段。这使得你目前的反馈至关重要。每一份报告都会被阅读，通常会在当天得到处理： - 🐛 **[报告 Bug](https://github.com/KnockOutEZ/wigolo/issues/new?template=bug_report.yml)** —— 崩溃、行为异常、令人意外的情况 - 💡 **[请求功能](https://github.com/KnockOutEZ/wigolo/issues/new?template=feature_request.yml)** —— 期望它具备的新能力 - 💬 **[随意提问](https://github.com/KnockOutEZ/wigolo/discussions)** —— 疑问、配置、展示与交流如果 wigolo 在你的工具链中赢得了一席之地，以下是让它保持活力的方式：一颗 ⭐ **Star**（这是开源项目被发现的方式），一杯 **[☕ 咖啡](https://buymeacoffee.com/knockoutez)**（永远不会有付费层级），或者仅仅是 **[发一封电子邮件](mailto:ktowhid20@gmail.com)** —— 它会直接发送给编写这些代码的唯一一位开发者。 ## 常见问题

免费？有什么附加条件？

设计上没有任何陷阱。那些昂贵的部分 —— 排序、嵌入、浏览器引擎 —— 都在*你的*硬件上运行，因此没有需要收回的单次查询成本，也没有按量计费的理由。依靠捐赠维持；AGPL 许可证在法律上防止了其演变为闭源托管产品的诱饵和掉包行为。

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

运行一次查询自己判断 —— 上面的基准测试部分是一次实时的 4 方对比运行，而不是一张图表。日常的 agent 查询能达到同等水平；付费工具在一些深度提取的边缘情况下仍然占据优势，而爬虫是 wigolo 最强的一面。每个结果都会展示其评分，因此你无需盲信任何人。

公共搜索引擎不会进行封锁或退化吗？

正是为了应对这种情况进行了专门设计：18 个引擎通过排名融合（任何单个引擎失败对结果几乎没有影响），带有按域名学习功能的分层抓取阶梯，以及可选的聚合器回退。降级的后端会*在输出中如实报告*，绝不隐瞒 —— 此外本地缓存意味着所有已经看过的内容无论如何都能继续使用。

这种抓取方式可以接受吗？

wigolo 像浏览器一样阅读公共网络 —— 默认遵守 robots.txt，带有按域名的速率限制，仅针对单台机器上的单个 agent 使用研究级的访问量。它是有意设计为礼貌访问的光谱一端，而不是一个大规模抓取平台。

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

是的，免费、全公司范围皆可使用。该许可证只有在*当你修改了 wigolo 并将其作为网络服务运行时*才会产生约束 —— 届时你必须公开那些修改内容。将其作为本地开发工具使用不承担任何义务。有关商业授权的问题：请联系我们。

为什么需要 1.5 GB 的磁盘空间？

那是 on-device 的大脑：包含一个完整的浏览器引擎，以及云服务在他们那边运行并向你收费的排序和嵌入模型。磁盘很便宜；按量计费的表可不便宜。

## 可用平台在你管理软件包或 MCP 服务器的任何地方获取 wigolo： - **npm** —— [`wigolo`](https://www.npmjs.com/package/wigolo) - **Docker** —— [`ghcr.io/knockoutez/wigolo`](https://github.com/KnockOutEZ/wigolo/pkgs/container/wigolo) · [`towhid69420/wigolo`](https://hub.docker.com/r/towhid69420/wigolo) - **官方 MCP 注册表** —— `io.github.KnockOutEZ/wigolo` - **目录网站** —— [Glama](https://glama.ai/mcp/servers/KnockOutEZ/wigolo) · [Smithery](https://smithery.ai/server/ktowhid20/wigolo) · [mcp.so](https://mcp.so/server/wigolo/KnockOutEZ) · [LobeHub](https://lobehub.com/mcp/knockoutez-wigolo) ## 贡献欢迎提交 Bug 报告、功能请求和 PR —— 参见 **[CONTRIBUTING.md](CONTRIBUTING.md)**。请保持工具处理程序的精简（业务逻辑保留在领域模块中），添加测试，并在开启 PR 前运行测试套件。wigolo 还拥有用于自定义提取器和搜索引擎的插件系统：`wigolo plugin add `。 ## 许可证 **[GNU AGPL-3.0-only](LICENSE).** 可免费使用、修改和自托管 —— 包括在公司内部使用。唯一的义务是：如果你将**修改后**的版本作为网络服务运行，你必须根据相同的许可证公开修改后的源代码。这使得 wigolo 保持开源，同时防止出现闭源的托管分支。报告漏洞请参阅 **[SECURITY.md](SECURITY.md)**，名称使用请参阅 **[TRADEMARK.md](TRADEMARK.md)**。如需商业授权，请联系我们。

wigolo 是免费的，并将一直保持如此 —— 靠维护而非付费墙维持。如果它为你省下了一笔按量计费的搜索账单，一个 ⭐、一个尖锐的问题，或者一杯 **[☕ 咖啡](https://buymeacoffee.com/knockoutez)** 都能帮助它持续发展。 _{由 @KnockOutEZ 构建并维护 · ktowhid20@gmail.com}

标签：AI编程助手, MCP服务器, MITM代理, 暗色界面, 本地搜索引擎, 自动化攻击, 请求拦截