wigolo 使用教程：给 AI Agent 一个本地优先的 Web 层

wigolo 是一个面向 AI Agent 的本地优先 Web 智能层，提供 搜索、抓取、爬取、提取、缓存、相似查找、研究 和自主采集循环等能力。它通过 MCP 协议与 Claude Code、Cursor、Codex、Gemini CLI、OpenCode、VS Code、Windsurf、Zed、Antigravity 等编码 Agent 协作，也支持 LangChain、CrewAI、LlamaIndex、Vercel AI SDK、n8n 等框架，以及任何 MCP 客户端和纯 REST 调用。

核心卖点很直接：不需要 API key，不依赖云服务，没有按量计费。所有数据默认留在 ~/.wigolo/ 目录下。

安装前提

• Node.js ≥ 20（建议使用 LTS 版本 20、22 或 24）
• 约 1.5 GB 可用磁盘空间（macOS、Linux、Windows 均可）
• 网络连接用于首次下载浏览器引擎和本地模型

安装步骤

安装通过 npx 完成，核心命令是 init：

init 会下载浏览器引擎和本地模型，运行健康检查，并逐项报告每个组件的状态。默认是非交互式的，适合在脚本和 CI 中安全执行。

--agents 参数支持逗号分隔的多个 Agent 名称：claude-code、cursor、codex、gemini-cli、opencode、vscode、windsurf、zed、antigravity。wigolo 会为这些 Agent 写入 MCP 配置和必要的指令文件。

其他 MCP 客户端或自托管 Agent 需要在自己的 MCP 配置中注册 npx -y wigolo。官方文档提供了每种客户端的精确配置块，以及 Docker、Homebrew 和单文件二进制等安装渠道。

两个有用的安装选项：

• --interactive：纯文本交互式安装流程
• --wizard：完整的终端 TUI 界面
• --no-warmup：延迟下载模型和浏览器，等到首次使用时再加载

即使某个组件下载失败，init 也会正常完成退出（退出码 0），并在报告中指出哪些组件未就绪及修复方法。核心的搜索、抓取、爬取、提取和缓存功能在无模型、无浏览器的情况下也能工作。

启动与健康检查

安装完成后，随时检查系统状态：

doctor 会指出任何损坏的组件，并给出确切的修复命令或环境变量；wigolo doctor --fix 可以自动修复常见问题；wigolo verify 则对每个组件做健康检查。

彻底卸载：

配置

默认安装即可使用。三个配置项可以显著提升输出质量：

1. 配置 LLM 提供方（最大杠杆）

搜索、抓取、爬取、提取、缓存和相似查找完全不需要 API key。但 research、agent 和 search format=answer 这三个功能需要 LLM 来生成带引用的综合回答。没有 LLM 时，它们会返回原始简报和证据，由宿主 Agent 自行整理。

推荐使用免费的 Gemini key：

也支持 anthropic、openai、groq，或者完全本地无 key 的方案：WIGOLO_LLM_PROVIDER=ollama（或任何 OpenAI 兼容的 URL）。

2. 扩大检索漏斗

3. 提升抓取成功率

典型命令示例

所有工具都可以通过 CLI 直接运行：

启动 REST API 服务：

通过 REST 调用搜索：

POST /v1/{tool} 覆盖全部十个工具，GET /openapi.json 提供 OpenAPI 3.1 契约，/mcp 和 /sse 端点支持远程 MCP 客户端。绑定到非 loopback 地址时必须设置 bearer token，服务默认 fail-closed。

交互式 shell 模式（支持 NDJSON 管道）：

十个核心工具

搜索结果的结构

每次搜索返回的结果都带有可操作的证据信息，包括原文摘录（精确到字节偏移）、可引用的 citation ID 和可检查的评分：

弱结果会被 wigolo 自己的评分器标记为 junk，失败的引擎和过期的缓存也会在输出中标注。

SDK 与框架集成

TypeScript（零依赖，支持 Node / Bun / Deno / edge）：

Python（仅标准库，支持同步和异步）：

框架集成包：

• wigolo-langchain：每个工具作为 BaseTool，另有 BaseRetriever 用于 RAG
• wigolo-crewai：wigolo_tools() 直接交给任意 crew
• wigolo-llamaindex：BaseReader 加载抓取/爬取/搜索到的页面作为文档
• wigolo-vercel-ai-sdk：为 generateText / streamText 提供工具工厂

Docker：

slim 镜像按需加载模型到卷中；:full 标签预装了浏览器引擎。Docker Hub 上也有 towhid69420/wigolo。

注意事项

1. 磁盘占用：1.5 GB 是本地模型和浏览器引擎的体积，这是本地运行的成本。安装后每次查询都免费使用这些资源。

2. 网络环境：如果下载慢或失败，重新运行 wigolo warmup --all（或 --browser / --embeddings / --reranker），支持断点续传和重试。

3. Linux 浏览器启动问题：wigolo warmup --browser 会自动安装所需的系统库，或打印出确切命令。

4. 代理环境：设置 USE_PROXY=true 和 PROXY_URL；如果代理做 TLS 检查，还需要 NODE_EXTRA_CA_CERTS。

5. 自托管注意：部分有反爬保护的网站会评估 IP 信誉，数据中心 IP 可能无法通过家庭网络能通过的验证。wigolo 会标注这类失败，官方自托管指南介绍了可选的代理方案。

6. 许可协议：wigolo 使用 AGPL-3.0 许可。在公司内部使用没有义务；只有当你修改了 wigolo 并作为网络服务运行时，才需要以相同许可发布修改后的源码。

7. 公共搜索引擎的稳定性：wigolo 通过 18 个引擎的排名融合来降低单一引擎失效的影响，可选的聚合器回退和本地缓存进一步保证了可用性。后端降级会在输出中明确报告。

8. 爬取礼仪：默认尊重 robots.txt、按域名限速，面向单机单 Agent 的研究级流量，刻意保持在礼貌的一端。

wigolo 目前处于 public beta，官方称有 7,600 项测试保障稳定性。如果你遇到问题，wigolo doctor 是最快的诊断入口。