KnockOutEZ/wigolo · 上手攻略

• 仓库：KnockOutEZ/wigolo
• 链接：https://github.com/KnockOutEZ/wigolo
• 分类：AI Agent · Web Intelligence · MCP
• 作者：Tom
• 更新：2026-07-20

一、是什么

wigolo 是一个本地优先的 AI Agent 网页智能服务器，为 AI 编程 Agent 提供一站式网页能力：搜索、抓取、爬取、提取、缓存、相似页面查找和自主研究。所有数据默认存储在本地 ~/.wigolo/，核心搜索/抓取功能无需任何 API Key，完全免费。

它的定位是替代需要付费的网页搜索 API（如 Google SerpAPI、Bing Search API），让 AI Agent 在本地就能完成所有 web 相关的推理工作，不产生按查询计费的账单。

核心特点

二、解决什么问题

给 AI Agent 装备网页能力，一直存在三个痛点：

1. 费用问题：每千次搜索约 $5-25 的商业 API 账单随 Agent 思考量线性增长，开发和测试阶段尤为昂贵。
2. 数据隐私：Agent 的查询内容、访问记录经过第三方平台，存在信息泄露风险。
3. 集成摩擦：每个 Agent 框架有各自的插件体系，手动配置繁琐，容易在反爬虫机制面前失败。

wigolo 的设计思路是：在开发者自己的机器上运行一个本地 web 智能层，MCP 协议作为标准接口，所有主流 Agent 和框架都能以相同方式接入，同时通过本地浏览器引擎处理 JavaScript 渲染和反爬虫页面。

三、快速安装

环境要求

• Node.js ≥ 20
• 约 1.5 GB 可用磁盘空间（macOS / Linux / Windows 均支持）

方式一：npm 一键安装（推荐）

# 最简安装
npx wigolo init

# 安装并自动配置指定 Agent（逗号分隔多选）
npx wigolo init --agents=claude-code,cursor

支持的 Agent 标识符：claude-code · cursor · codex · gemini-cli · vscode · windsurf · zed · antigravity

安装时会下载浏览器引擎和本地模型（约 1.5 GB），完成后输出各组件健康状态。--no-warmup 可跳过首次下载，稍后按需拉取。

交互式安装（纯文本引导）:

npx wigolo init --interactive

TUI 全屏向导:

npx wigolo init --wizard

方式二：Docker

docker run -v ~/.wigolo:/root/.wigolo -p 3000:3000 ghcr.io/knockoutez/wigolo serve

方式三：Homebrew（Linux/macOS）

brew install knockoutez/tap/wigolo

验证安装

npx wigolo doctor

正常输出各组件状态，确认本地引擎健康后即可使用。

卸载

npx wigolo config --uninstall --yes

四、核心用法

4.1 MCP 工具调用（Claude Code / Cursor 等本地 Agent）

安装时使用 --agents=claude-code 等参数，会自动写入 MCP 配置文件并配置 Agent 指令。无需手动配置即可在对话中直接调用以下工具：

search — 多引擎网页搜索

{
  "query": ["rust async traits", "rust trait async fn stabilization"],
  "category": "docs",
  "include_domains": ["doc.rust-lang.org", "blog.rust-lang.org"],
  "max_results": 5
}

fetch — 获取单页内容

{
  "url": "https://nextjs.org/docs/app/building-your-application/caching",
  "section": "Data Cache",
  "max_content_chars": 4000
}

crawl — 多页爬取（BFS / DFS / sitemap 模式）

{
  "url": "https://example.com",
  "strategy": "BFS",
  "max_pages": 20
}

extract — 结构化数据提取（支持 Article / Recipe / Product / JSON Schema）

{
  "url": "https://news.ycombinator.com/item?id=123",
  "schema": "Article"
}

research — 自主研究循环（分解问题 → 并行搜索 → 抓取来源 → 综合报告）

{
  "query": "2026年 AI Agent 技术栈演进",
  "output_format": "cited_report"
}

4.2 REST API（远程 / 自托管 Agent）

启动 REST 服务端：

npx wigolo serve --port 3000

常用端点（curl 示例）：

# 搜索
curl -X POST http://localhost:3000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "wigolo AI agent MCP", "max_results": 5}'

# 抓取
curl -X POST http://localhost:3000/api/fetch \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/KnockOutEZ/wigolo"}'

4.3 CLI 交互

# 一次性搜索
wigolo search "rust async" --json

# 交互式 Shell（NDJSON 流式）
wigolo shell

# 检查健康状态
wigolo doctor

完整 CLI 参考见 docs/cli.md。

4.4 LLM 综合能力（可选配置）

search --format=answer 和 research 工具默认输出带引用的原始材料包。如需 LLM 综合回答，可配置免费 Gemini Key：

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<your-free-key>  # https://aistudio.google.com/apikey 免费获取

支持 provider：gemini · anthropic · openai · groq · ollama（本地模型，无需 Key）。

五、典型适用场景

场景 1：本地开发时 AI 编程 Agent 需要实时网页信息

Claude Code / Cursor 在处理前沿技术问题时（如某个库的最新版 API），需要查询官方文档。使用 wigolo 可以直接在终端完成搜索和文档抓取，无需配置 SerpAPI 等付费服务。

# Claude Code 中直接调用
wigolo search "pydantic v2 field validator" --category docs --json

场景 2：隐私敏感的代码审查场景

Agent 需要分析某公司技术博客、竞品文档，但不能暴露查询意图。使用 wigolo 的本地缓存，所有请求记录留在本机 ~/.wigolo/。

场景 3：自主研究 Agent（n8n / CrewAI / 自建系统）

通过 REST API 将 wigolo 接入 n8n 工作流或自研 Agent，实现"提出问题 → 自动搜索 → 抓取 → 提取 → 汇总报告"的全自动研究管道。

场景 4：持续监控页面变化

diff + watch 工具组合适合监控竞品发布动态、技术文档更新，每次变化推送到 webhook。

{
  "url": "https://docs.example.com/changelog",
  "watch_interval": "1h",
  "webhook": "https://your-endpoint.com/notify"
}

六、坑与注意

1. 首次安装磁盘空间：下载浏览器引擎和本地模型约需 1.5 GB，确保磁盘充足。
2. 搜索质量依赖搜索引擎：无 Key 时使用免费搜索入口，极端并发或部分引擎降级时可能影响召回率。engine_telemetry 会诚实报告每个引擎的状态。
3. SPA / 反爬虫页面：wigolo 具备自动升级到浏览器引擎的能力，但并非 100% 成功。遇到 blocked_by_challenge 标签时，该页面被标记为诚实失败，不返回垃圾内容。
4. research 工具需要 LLM：不配置 LLM Provider 时，research 返回原始证据包而非综合报告，需要调用方自行处理。
5. Node.js 版本：明确要求 ≥ 20，老版本 Node 可能出现兼容问题。
6. MCP stdio 模式：仅适用于本地 Agent；远程 Agent（n8n、Docker 部署等）需使用 REST MCP HTTP 端点或 REST API。
7. Windows 支持：文档提及支持，但部分平台细节（如路径处理）建议参考 docs/troubleshooting.md。

七、与同类对比

wigolo 的核心差异：唯一在完全免费 + 本地运行 + 完整工具集三方面同时满足的方案。适合不想管理 API Key、关注数据隐私、或在开发/测试阶段不想产生账单的场景。

八、一句话结论

wigolo 是 AI Agent 的本地网页瑞士军刀——零 Key 开箱即用、MCP 无缝接入，让编程 Agent 真正拥有免费、隐私友好的网页感知能力。

来源

• GitHub README：https://github.com/KnockOutEZ/wigolo
• 官方文档：https://github.com/KnockOutEZ/wigolo/blob/main/docs/README.md
• 工具参考：https://github.com/KnockOutEZ/wigolo/blob/main/docs/tools.md
• Tavily / Vellum 搜索 MCP 生态对比（2026）