尧图网页设计 
wigolo 故障排查完全指南从 doctor 诊断到 blocked_by_challenge、平台差异与网络问题修复【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo本篇指南以 wigolo 官方 Troubleshooting 文档docs/troubleshooting.md为主体骨架逐条讲解最常见的故障症状、对应的修复命令、组件下载失败后的真实影响边界以及 Windows / Linux / macOS / ARM 各平台的行为差异。读完你能够熟练使用wigolo doctor与wigolo warmup定位并修复安装问题理解blocked_by_challenge标签背后的抓取层级与 IP 信誉现实并在代理、离线等受限网络环境中完成模型的预下载与迁移。排查的第一步永远是wigolo doctor遇到任何异常第一条命令不是去看日志、不是重装而是运行内置诊断wigolo doctor # 指出哪个组件损坏以及修复它所需的环境变量 / 命令 wigolo doctor --fix # 自动修复已知的失败类别doctor是一个纯本地的快照式体检它检查数据目录可写性、Python 与 Docker仅搜索侧车需要、浏览器引擎是否可启动、TLS 抓取层级、ML reranker 与 embeddings 模型缓存、各 LLM provider 的密钥配置密钥永远只显示掩码、搜索后端模式与各搜索引擎的健康状态。从源码看其核心体检项位于 src/cli/doctor.ts 的runDoctorColdChecks浏览器、embeddings、searxng 侧车、熔断器breaker与数据目录逐一给出ok / failed / skipped状态且全部是存在性快照不会触发任何模型下载或浏览器启动。两点值得注意的细节浏览器检查不是看文件在不在而是真实启动。checkPlaywright复用与 warmup 完全一致的probeBrowser探针做一次无头启动——在裸 Linux 上二进制存在但缺系统库时existsSync会误报健康而真实启动会立刻暴露缺失的库。这正是 src/cli/doctor.ts 里注释强调doctor 不能与 warmup 对浏览器健康判断不一致的原因。--fix只修有明确修复路径的项installBrowser(chromium)、installEmbeddings()、searxng 状态清理、熔断器重置含向运行中 daemon 的/admin/reset-breakers下发。数据目录不可写这类权限问题无法自动修复doctor 会明确报告但保持degraded。退出码契约是0 全部必要组件 OK可选组件缺失不扣分1 任一必要组件降级。诊断输出里还有个隐藏技能wigolo doctor的搜索引擎表格会逐行显示每个引擎的状态——ok、needs-key (set WIGOLO_GITHUB_TOKEN ...)、disabled (set BRAVE_API_KEY ...)并附带熔断器状态与已知的不可修复限制说明src/cli/doctor.ts 的formatEngineHealthLines。所以当搜索结果变薄时先跑 doctor 看是哪个引擎变暗了、它想要什么。症状 → 修复对照表下表完整覆盖官方文档列出的全部症状与修复路径并补充了底层依据症状修复init期间某个组件下载失败wigolo warmup --all重跑全部下载也可用--browser/--reranker/--embeddings只补一个。失败不会阻塞 wigolo 其他部分——组件会在首次使用时惰性重试。Linux 上浏览器引擎无法启动wigolo warmup --browser会安装浏览器引擎所需的操作系统库必要时用 sudo 提权装不了时错误信息会打印出你可以自己执行的精确安装命令执行后再重跑wigolo warmup。wigolo serve退出端口被占用daemon 刻意不做自动换绑。错误信息会给出一个空闲端口供重试例如wigolo serve --port 3334。src/cli/daemon.ts 中明确写着 Not auto-rebinding — retry with a free port——这是设计行为而非缺陷避免守护进程在无人知晓的情况下漂移端口导致既有调用方全部失联。wigolo serve拒绝在非回环主机上启动符合设计fail-closed。设置WIGOLO_API_TOKEN/WIGOLO_API_TOKEN_FILE或显式传--allow-unauthenticated。详见 绑定回环之外。Fetch 结果返回blocked_by_challenge见下文 blocked_by_challenge 专节。搜索结果变薄 / 某个引擎像死了降级引擎是被报告而非被隐藏——检查响应中的engine_warnings、engine_telemetry、engine_pool以及wigolo doctor的逐引擎表格引擎只是缺 key 时它会点名所需环境变量如WIGOLO_GITHUB_TOKEN、BRAVE_API_KEY。熔断器处于 open/half-open 的引擎会以[breaker open — 上游错误摘要]的形式显示在 doctor 表格里让你知道它为何不派发请求。结果陈旧传force_refresh: true适合新闻、价格、changelog或清除指定条目wigolo cache clear --url-pattern*example.com*。缓存寿命可调CACHE_TTL_SEARCH默认 86400 秒/1 天、CACHE_TTL_CONTENT默认 604800 秒/7 天完整配置见 docs/configuration.md。在企业代理后面一切请求都失败设置USE_PROXYtrue和PROXY_URL凭据存入操作系统钥匙串不落盘。见 fetch 与浏览器引擎配置。某个原本正常的域名开始出问题wigolo 会学习每个域名的抓取路由站点改版可能使其学到的路由失效。wigolo tune show domain查看wigolo tune reset domain重新学习。watch 任务从不触发watch 检查只在 daemonwigolo serve或 MCP 会话存活期间运行——一次性 CLI 调用只能注册任务无法调度它们。从 src/watch/scheduler.ts 的结构看调度循环依附于常驻进程的生命周期。浏览器引擎下载缓慢或超时常见于被限速或地域受限的网络。重跑wigolo warmup --browser——它会重试并断点续传。若默认下载 CDN 在你所在地区很慢可在 warmup 前设置PLAYWRIGHT_DOWNLOAD_HOSTmirror-url指向镜像。底层实现里浏览器安装有 300 秒超时和 2 次尝试的预算BROWSER_INSTALL_TIMEOUT_MS 300_000超时被识别为网络受限并给出镜像提示而非无限重试src/cli/warmup.ts。embeddings 模型下载失败TAR_BAD_ARCHIVE/ unrecognized archive截断或损坏的下载。wigolo 现在会自动清除不完整文件并重新下载一次若仍失败wigolo config --cleanup后再跑wigolo warmup --embeddings。排序模型下载失败fetch failed一次瞬时网络抖动。重跑wigolo warmup --reranker——它会带退避重试。下载报self signed certificate in certificate chain你在做 TLS 检查的企业代理后面。把 Node 指向组织 CA 包——NODE_EXTRA_CA_CERTS/path/to/corp-ca.pem——然后重跑 warmup。npm install编译原生依赖失败常见于 Windows你的 Node 版本没有预编译二进制npm 回退到源码编译。请使用有预编译产物的受支持 LTS——Node 20、22 或 24——或在 Windows 上安装 C/C 工具链Visual Studio Build Tools。磁盘空间低导致下载停滞或失败组件需要约 1 GB 空闲。释放空间、把WIGOLO_DATA_DIR指向更大的卷或wigolo config --cleanup回收上次安装的残留。关于wigolo tune域名级路由的查看与重置tune是上述域名曾经正常、现在异常症状的直接工具。它是对缓存库中域名路由投影的一层薄 CLIsrc/cli/tune.ts支持wigolo tune list # 列出所有已学习路由的域名 wigolo tune show domain # 查看单个域名的路由 wigolo tune reset domain # 清除单个域名的已学习路由 wigolo tune reset --all # 清除全部 wigolo tune ... --json # 输出单一 JSON 文档人类可读行走 stderrJSON 走 stdout表格列包含DOMAIN / TLS / BROWSER / TLS_HITS / HTTP_FAILS / BACKOFF / CLEARANCE直接对应 wigolo 自调优的四类行为TLS 模拟层级提升、浏览器引擎升级、已解反爬挑战的 clearance 复用、以及被反复拦截后的礼貌退避窗口。站点改版导致路由失效时reset让 wigolo 重新学习。组件安装失败——wigolo 坏了吗没有。init即使有下载失败也会以退出码 0 结束而且核心功能搜索、HTTP fetch、crawl、extract、cache完全不需要模型和浏览器。失败的组件会优雅降级——具体代价如下哪个组件失败了你失去什么仍然正常工作的浏览器引擎JS 渲染页面回退到纯 HTTP fetch部分 SPA 内容可能缺失搜索、HTTP fetch、crawl、extract、cache、模型embeddings 模型语义发现——find_similar和语义缓存排序回退到关键词匹配搜索、fetch、crawl、extract、关键词缓存排序模型ML 重排环节多引擎 rank fusion 仍然生效其他一切——只是结果排序颗粒度降低没有 LLM keyresearch/agent/search --format answer返回结构化证据而非书面散文所有无 key 工具这正是默认形态任何时候都可以重跑wigolo warmup --all重试下载或干脆让每个组件在首次使用时惰性加载。从源码看这一永不阻塞的契约在 src/cli/init.ts 的runFullSetup中被显式保证warmup 即使抛异常init 也打印修复提示后继续完成 agent 接线与配置持久化并输出逐组件报告✓ ready/○ skipped (lazy)/✗ failed Fix:随后附加 doctor 冷检查摘要。浏览器、embeddings、reranker 的失败都被映射为可修复项对应修复命令各不相同src/cli/init.ts。另一个支撑点warmup 对每个模型都做端到端冒烟测试而非下载完成即成功——reranker 下载后会真正跑一次rerank调用embeddings 会实际embed([warmup])并校验向量维度src/cli/warmup.ts。所以warmup报告ok的组件是可以直接用的。blocked_by_challenge 标签深度解析这个标签意味着目标站点位于一个在挑战窗口内未被清除的反爬挑战之后。wigolo 会逐级升级抓取层级纯 HTTP → TLS 模拟层级 → 完整浏览器引擎像耐心浏览器一样轮询挑战并按域名复用此前解出的 clearance——而当这一切都无效时它会如实告诉你而不是把挑战页面伪装成内容返回。两个诚实的现实用来校准预期IP 信誉是被评分的。在数据中心 IPVPS、CI、云主机上部分受挑战保护的站点无论如何都不会清除——即使从住宅连接发出完全相同的请求就能成功。这是你的运行位置属性而不是 wigolo 漏掉了某个旋钮。可选杠杆是代理其 IP 信誉要与你的合法研究用途匹配——见 数据中心 IP 的现实。凭据存入钥匙串且礼貌机制robots.txt、按域名限速依旧生效。从源码角度这个标签有完整的实现支撑挑战无法清除时路由层会把它归一化为结构化的blocked_by_challenge阶段错误浏览器池对该错误有专门映射src/fetch/browser-pool.tsfetch 路由层保证挑战回退变成blocked_by_challenge绝不把挑战外壳当作内容泄漏出去src/fetch/router.tsREST 错误层把blocked_by_challenge列为标准上游失败原因之一src/daemon/rest/errors.ts。相关可调参数见 docs/configuration.mdWIGOLO_CHALLENGE_COMPLETION_MS默认 15000浏览器层轮询挑战页多久后快速失败、WIGOLO_TLS_TIERoff/auto/on、WIGOLO_STEALTH与WIGOLO_TLS_BROWSER。平台注意事项Node 版本。wigolo 运行在Node 20、22 或 24LTS上。过新或不常见的 Node 构建可能还没有预编译原生二进制会尝试从源码编译需要 C/C 工具链——坚持使用 LTS 即可避免。Windows。支持 Node 20。数据目录是%USERPROFILE%\.wigolo。环境变量用你 shell 的语法设置PowerShell 中$env:WIGOLO_SEARCHhybrid其他一切——命令、flags、端口——与 Unix 文档完全一致。注意npm install编译原生依赖失败在该平台上最常出现解决方案就是上文对照表中的 Node LTS 或 Visual Studio Build Tools。Linux精简镜像 / 容器。浏览器引擎需要若干操作系统库wigolo warmup --browser会安装它们有 sudo 时提权否则打印你需要手动执行的精确命令。Python 不是必需的——它只被可选的搜索引擎侧车使用所以 Python 3 not found 提示在核心使用中可以安全忽略。实际上 warmup 对 searxng 阶段的降级路径设计得很细致无 Python 时报no_python无python3-venv模块时报no_venv并给出 apt 安装提示、回退到内置 core 搜索后端而不是用难懂的 traceback 让整个 warmup 失败src/cli/warmup.ts。macOSApple Silicon / Intel。完全支持——模型和浏览器都包含在内。Linux on ARMarm64。核心搜索、fetch、crawl、extract 和 cache 正常工作。语义功能目前在 linux-arm64 上不可用——embeddings 模型的 tokenizer 还没有预编译 ARM 二进制所以find_similar、embeddings 和语义缓存排序回退到关键词匹配。如果今天就需要 Linux 上的语义功能请运行在 x64 主机上此事已纳入未来版本计划。doctor 的诊断输出会把这一事实如实展示——checkFastembedCache检测模型缓存目录而 src/cli/doctor.ts 的注释明确惰性 ≠ 盲目存在但损坏的目录会在首次使用时暴露。慢速、代理或离线网络慢速或地域受限的链接。模型和浏览器下载是耗时大头重跑时可断点续传。wigolo init --no-warmup跳过全部前置下载——每个组件随后在首次使用时惰性加载。浏览器引擎 CDN 被限速时在 warmup 前设置PLAYWRIGHT_DOWNLOAD_HOST镜像。企业代理。设置USE_PROXYtrue和PROXY_URL凭据进 OS 钥匙串不落盘。在 TLS 检查代理后面还需设置NODE_EXTRA_CA_CERTS指向你的 CA 包使下载校验通过。气隙 / 离线环境。在联网机器上运行wigolo warmup --all然后把它的~/.wigolo复制到目标机器以预置模型和浏览器。注意search 和 fetch 在查询时仍然访问实时网络——只有模型/浏览器的下载可以预置。补充一个磁盘层面的细节数据目录里模型与缓存的体积是可查、可回收的。wigolo config --storage打印按组件划分的存储使用地图wigolo config --cleanup cache|embeddings|models|browser|searxng按组件释放空间src/cli/config.ts 显示释放后输出Cleaned component: freed N MB。wigolo config --cache-stats则给出缓存条目数与体积。日志都在哪里wigolo 把全部日志写到 stderr默认结构化 JSONLOG_FORMATtext给人看LOG_LEVELdebug提高详细度。没有隐藏的日志目录CLI 运行日志出现在终端 stderr用2wigolo.log重定向。MCP 宿主宿主把 server 的 stderr 捕获进它自己的 MCP 日志位置。systemd / Docker 下的wigolo servejournal / 容器日志。wigolo 自己写事件的唯一文件是可选遥测 NDJSON~/.wigolo/telemetry/且仅在WIGOLO_TELEMETRY1时。遥测默认关闭只写到本地文件不发送任何数据只有额外设置WIGOLO_TELEMETRY_ENDPOINT才会 POST 到你自己的端点docs/configuration.md。这个日志只在 stderr的设计是有意为之stdout 被保留给 MCP 协议流量和--json工具输出日志永远不污染它们docs/configuration.md。常见问题FAQ商业模式是什么会开始收费吗wigolo 是免费的开源软件采用 AGPL-3.0 许可。没有托管层级、没有计费 API、没有需要购买的 key——它是本地软件你的机器完成工作。这正是它的意义所在。AGPL 对我意味着什么直白地说把 wigolo 当作工具使用——个人、公司内部、接入你运行的每个 agent——零义务。许可证的分享条款只在你修改 wigolo 本身并以网络服务形式为他人运行修改版时生效那时你需要分享这些修改。构建仅仅调用 wigolo 的产品不属于这种情况。用它做抓取道德吗wigolo 的默认配置围绕做一个礼貌客户端构建默认遵守 robots.txt、按域名限速与抓取延迟、为研究而非批量收割设计的页面预算、以及诚实的失败标注而不是死磕撞墙。这里可靠性工作意味着像真实浏览器那样读页面——它不是伪装工具包文档也不会教你造一个。它有多稳定当前为 0.2.0 公开测试版。文档化的功能面由约 7,600 个自动化测试组成的测试套件守护beta 关乎的是打磨标准和 API 形态的信心而不是已知的不稳定。真正存在的限制都写在文档里而不是留到生产环境才被发现——见上文挑战上限一节。为什么安装包这么大因为智能在本地。下载体积主要来自设备端 embedding 排序模型约 250 MB和 JS 渲染抓取所需的可选浏览器引擎二进制约 0.5–1 GB。这是换取无 key、私有、零按次调用成本运作的代价。init --no-warmup可推迟全部下载wigolo config --cleanup可回收它们。延伸阅读docs/troubleshooting.md —— 本文的官方出处docs/configuration.md —— 上文涉及的全部环境变量的权威表格fetch、缓存寿命、daemon、遥测等docs/self-hosting.md —— 非回环绑定、数据中心 IP 现实、SSRF 网络姿态与反向代理拓扑docs/cli.md ——doctor、warmup、tune、config等命令的完整参考src/cli/doctor.ts 与 src/cli/warmup.ts —— 诊断与下载修复的源码实现【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 wigolo 故障排查完全指南：从 doctor 诊断到 blocked_by_challenge、平台差异与网络问题修复
wigolo 故障排查完全指南从 doctor 诊断到 blocked_by_challenge、平台差异与网络问题修复【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo本篇指南以 wigolo 官方 Troubleshooting 文档docs/troubleshooting.md为主体骨架逐条讲解最常见的故障症状、对应的修复命令、组件下载失败后的真实影响边界以及 Windows / Linux / macOS / ARM 各平台的行为差异。读完你能够熟练使用wigolo doctor与wigolo warmup定位并修复安装问题理解blocked_by_challenge标签背后的抓取层级与 IP 信誉现实并在代理、离线等受限网络环境中完成模型的预下载与迁移。排查的第一步永远是wigolo doctor遇到任何异常第一条命令不是去看日志、不是重装而是运行内置诊断wigolo doctor # 指出哪个组件损坏以及修复它所需的环境变量 / 命令 wigolo doctor --fix # 自动修复已知的失败类别doctor是一个纯本地的快照式体检它检查数据目录可写性、Python 与 Docker仅搜索侧车需要、浏览器引擎是否可启动、TLS 抓取层级、ML reranker 与 embeddings 模型缓存、各 LLM provider 的密钥配置密钥永远只显示掩码、搜索后端模式与各搜索引擎的健康状态。从源码看其核心体检项位于 src/cli/doctor.ts 的runDoctorColdChecks浏览器、embeddings、searxng 侧车、熔断器breaker与数据目录逐一给出ok / failed / skipped状态且全部是存在性快照不会触发任何模型下载或浏览器启动。两点值得注意的细节浏览器检查不是看文件在不在而是真实启动。checkPlaywright复用与 warmup 完全一致的probeBrowser探针做一次无头启动——在裸 Linux 上二进制存在但缺系统库时existsSync会误报健康而真实启动会立刻暴露缺失的库。这正是 src/cli/doctor.ts 里注释强调doctor 不能与 warmup 对浏览器健康判断不一致的原因。--fix只修有明确修复路径的项installBrowser(chromium)、installEmbeddings()、searxng 状态清理、熔断器重置含向运行中 daemon 的/admin/reset-breakers下发。数据目录不可写这类权限问题无法自动修复doctor 会明确报告但保持degraded。退出码契约是0 全部必要组件 OK可选组件缺失不扣分1 任一必要组件降级。诊断输出里还有个隐藏技能wigolo doctor的搜索引擎表格会逐行显示每个引擎的状态——ok、needs-key (set WIGOLO_GITHUB_TOKEN ...)、disabled (set BRAVE_API_KEY ...)并附带熔断器状态与已知的不可修复限制说明src/cli/doctor.ts 的formatEngineHealthLines。所以当搜索结果变薄时先跑 doctor 看是哪个引擎变暗了、它想要什么。症状 → 修复对照表下表完整覆盖官方文档列出的全部症状与修复路径并补充了底层依据症状修复init期间某个组件下载失败wigolo warmup --all重跑全部下载也可用--browser/--reranker/--embeddings只补一个。失败不会阻塞 wigolo 其他部分——组件会在首次使用时惰性重试。Linux 上浏览器引擎无法启动wigolo warmup --browser会安装浏览器引擎所需的操作系统库必要时用 sudo 提权装不了时错误信息会打印出你可以自己执行的精确安装命令执行后再重跑wigolo warmup。wigolo serve退出端口被占用daemon 刻意不做自动换绑。错误信息会给出一个空闲端口供重试例如wigolo serve --port 3334。src/cli/daemon.ts 中明确写着 Not auto-rebinding — retry with a free port——这是设计行为而非缺陷避免守护进程在无人知晓的情况下漂移端口导致既有调用方全部失联。wigolo serve拒绝在非回环主机上启动符合设计fail-closed。设置WIGOLO_API_TOKEN/WIGOLO_API_TOKEN_FILE或显式传--allow-unauthenticated。详见 绑定回环之外。Fetch 结果返回blocked_by_challenge见下文 blocked_by_challenge 专节。搜索结果变薄 / 某个引擎像死了降级引擎是被报告而非被隐藏——检查响应中的engine_warnings、engine_telemetry、engine_pool以及wigolo doctor的逐引擎表格引擎只是缺 key 时它会点名所需环境变量如WIGOLO_GITHUB_TOKEN、BRAVE_API_KEY。熔断器处于 open/half-open 的引擎会以[breaker open — 上游错误摘要]的形式显示在 doctor 表格里让你知道它为何不派发请求。结果陈旧传force_refresh: true适合新闻、价格、changelog或清除指定条目wigolo cache clear --url-pattern*example.com*。缓存寿命可调CACHE_TTL_SEARCH默认 86400 秒/1 天、CACHE_TTL_CONTENT默认 604800 秒/7 天完整配置见 docs/configuration.md。在企业代理后面一切请求都失败设置USE_PROXYtrue和PROXY_URL凭据存入操作系统钥匙串不落盘。见 fetch 与浏览器引擎配置。某个原本正常的域名开始出问题wigolo 会学习每个域名的抓取路由站点改版可能使其学到的路由失效。wigolo tune show domain查看wigolo tune reset domain重新学习。watch 任务从不触发watch 检查只在 daemonwigolo serve或 MCP 会话存活期间运行——一次性 CLI 调用只能注册任务无法调度它们。从 src/watch/scheduler.ts 的结构看调度循环依附于常驻进程的生命周期。浏览器引擎下载缓慢或超时常见于被限速或地域受限的网络。重跑wigolo warmup --browser——它会重试并断点续传。若默认下载 CDN 在你所在地区很慢可在 warmup 前设置PLAYWRIGHT_DOWNLOAD_HOSTmirror-url指向镜像。底层实现里浏览器安装有 300 秒超时和 2 次尝试的预算BROWSER_INSTALL_TIMEOUT_MS 300_000超时被识别为网络受限并给出镜像提示而非无限重试src/cli/warmup.ts。embeddings 模型下载失败TAR_BAD_ARCHIVE/ unrecognized archive截断或损坏的下载。wigolo 现在会自动清除不完整文件并重新下载一次若仍失败wigolo config --cleanup后再跑wigolo warmup --embeddings。排序模型下载失败fetch failed一次瞬时网络抖动。重跑wigolo warmup --reranker——它会带退避重试。下载报self signed certificate in certificate chain你在做 TLS 检查的企业代理后面。把 Node 指向组织 CA 包——NODE_EXTRA_CA_CERTS/path/to/corp-ca.pem——然后重跑 warmup。npm install编译原生依赖失败常见于 Windows你的 Node 版本没有预编译二进制npm 回退到源码编译。请使用有预编译产物的受支持 LTS——Node 20、22 或 24——或在 Windows 上安装 C/C 工具链Visual Studio Build Tools。磁盘空间低导致下载停滞或失败组件需要约 1 GB 空闲。释放空间、把WIGOLO_DATA_DIR指向更大的卷或wigolo config --cleanup回收上次安装的残留。关于wigolo tune域名级路由的查看与重置tune是上述域名曾经正常、现在异常症状的直接工具。它是对缓存库中域名路由投影的一层薄 CLIsrc/cli/tune.ts支持wigolo tune list # 列出所有已学习路由的域名 wigolo tune show domain # 查看单个域名的路由 wigolo tune reset domain # 清除单个域名的已学习路由 wigolo tune reset --all # 清除全部 wigolo tune ... --json # 输出单一 JSON 文档人类可读行走 stderrJSON 走 stdout表格列包含DOMAIN / TLS / BROWSER / TLS_HITS / HTTP_FAILS / BACKOFF / CLEARANCE直接对应 wigolo 自调优的四类行为TLS 模拟层级提升、浏览器引擎升级、已解反爬挑战的 clearance 复用、以及被反复拦截后的礼貌退避窗口。站点改版导致路由失效时reset让 wigolo 重新学习。组件安装失败——wigolo 坏了吗没有。init即使有下载失败也会以退出码 0 结束而且核心功能搜索、HTTP fetch、crawl、extract、cache完全不需要模型和浏览器。失败的组件会优雅降级——具体代价如下哪个组件失败了你失去什么仍然正常工作的浏览器引擎JS 渲染页面回退到纯 HTTP fetch部分 SPA 内容可能缺失搜索、HTTP fetch、crawl、extract、cache、模型embeddings 模型语义发现——find_similar和语义缓存排序回退到关键词匹配搜索、fetch、crawl、extract、关键词缓存排序模型ML 重排环节多引擎 rank fusion 仍然生效其他一切——只是结果排序颗粒度降低没有 LLM keyresearch/agent/search --format answer返回结构化证据而非书面散文所有无 key 工具这正是默认形态任何时候都可以重跑wigolo warmup --all重试下载或干脆让每个组件在首次使用时惰性加载。从源码看这一永不阻塞的契约在 src/cli/init.ts 的runFullSetup中被显式保证warmup 即使抛异常init 也打印修复提示后继续完成 agent 接线与配置持久化并输出逐组件报告✓ ready/○ skipped (lazy)/✗ failed Fix:随后附加 doctor 冷检查摘要。浏览器、embeddings、reranker 的失败都被映射为可修复项对应修复命令各不相同src/cli/init.ts。另一个支撑点warmup 对每个模型都做端到端冒烟测试而非下载完成即成功——reranker 下载后会真正跑一次rerank调用embeddings 会实际embed([warmup])并校验向量维度src/cli/warmup.ts。所以warmup报告ok的组件是可以直接用的。blocked_by_challenge 标签深度解析这个标签意味着目标站点位于一个在挑战窗口内未被清除的反爬挑战之后。wigolo 会逐级升级抓取层级纯 HTTP → TLS 模拟层级 → 完整浏览器引擎像耐心浏览器一样轮询挑战并按域名复用此前解出的 clearance——而当这一切都无效时它会如实告诉你而不是把挑战页面伪装成内容返回。两个诚实的现实用来校准预期IP 信誉是被评分的。在数据中心 IPVPS、CI、云主机上部分受挑战保护的站点无论如何都不会清除——即使从住宅连接发出完全相同的请求就能成功。这是你的运行位置属性而不是 wigolo 漏掉了某个旋钮。可选杠杆是代理其 IP 信誉要与你的合法研究用途匹配——见 数据中心 IP 的现实。凭据存入钥匙串且礼貌机制robots.txt、按域名限速依旧生效。从源码角度这个标签有完整的实现支撑挑战无法清除时路由层会把它归一化为结构化的blocked_by_challenge阶段错误浏览器池对该错误有专门映射src/fetch/browser-pool.tsfetch 路由层保证挑战回退变成blocked_by_challenge绝不把挑战外壳当作内容泄漏出去src/fetch/router.tsREST 错误层把blocked_by_challenge列为标准上游失败原因之一src/daemon/rest/errors.ts。相关可调参数见 docs/configuration.mdWIGOLO_CHALLENGE_COMPLETION_MS默认 15000浏览器层轮询挑战页多久后快速失败、WIGOLO_TLS_TIERoff/auto/on、WIGOLO_STEALTH与WIGOLO_TLS_BROWSER。平台注意事项Node 版本。wigolo 运行在Node 20、22 或 24LTS上。过新或不常见的 Node 构建可能还没有预编译原生二进制会尝试从源码编译需要 C/C 工具链——坚持使用 LTS 即可避免。Windows。支持 Node 20。数据目录是%USERPROFILE%\.wigolo。环境变量用你 shell 的语法设置PowerShell 中$env:WIGOLO_SEARCHhybrid其他一切——命令、flags、端口——与 Unix 文档完全一致。注意npm install编译原生依赖失败在该平台上最常出现解决方案就是上文对照表中的 Node LTS 或 Visual Studio Build Tools。Linux精简镜像 / 容器。浏览器引擎需要若干操作系统库wigolo warmup --browser会安装它们有 sudo 时提权否则打印你需要手动执行的精确命令。Python 不是必需的——它只被可选的搜索引擎侧车使用所以 Python 3 not found 提示在核心使用中可以安全忽略。实际上 warmup 对 searxng 阶段的降级路径设计得很细致无 Python 时报no_python无python3-venv模块时报no_venv并给出 apt 安装提示、回退到内置 core 搜索后端而不是用难懂的 traceback 让整个 warmup 失败src/cli/warmup.ts。macOSApple Silicon / Intel。完全支持——模型和浏览器都包含在内。Linux on ARMarm64。核心搜索、fetch、crawl、extract 和 cache 正常工作。语义功能目前在 linux-arm64 上不可用——embeddings 模型的 tokenizer 还没有预编译 ARM 二进制所以find_similar、embeddings 和语义缓存排序回退到关键词匹配。如果今天就需要 Linux 上的语义功能请运行在 x64 主机上此事已纳入未来版本计划。doctor 的诊断输出会把这一事实如实展示——checkFastembedCache检测模型缓存目录而 src/cli/doctor.ts 的注释明确惰性 ≠ 盲目存在但损坏的目录会在首次使用时暴露。慢速、代理或离线网络慢速或地域受限的链接。模型和浏览器下载是耗时大头重跑时可断点续传。wigolo init --no-warmup跳过全部前置下载——每个组件随后在首次使用时惰性加载。浏览器引擎 CDN 被限速时在 warmup 前设置PLAYWRIGHT_DOWNLOAD_HOST镜像。企业代理。设置USE_PROXYtrue和PROXY_URL凭据进 OS 钥匙串不落盘。在 TLS 检查代理后面还需设置NODE_EXTRA_CA_CERTS指向你的 CA 包使下载校验通过。气隙 / 离线环境。在联网机器上运行wigolo warmup --all然后把它的~/.wigolo复制到目标机器以预置模型和浏览器。注意search 和 fetch 在查询时仍然访问实时网络——只有模型/浏览器的下载可以预置。补充一个磁盘层面的细节数据目录里模型与缓存的体积是可查、可回收的。wigolo config --storage打印按组件划分的存储使用地图wigolo config --cleanup cache|embeddings|models|browser|searxng按组件释放空间src/cli/config.ts 显示释放后输出Cleaned component: freed N MB。wigolo config --cache-stats则给出缓存条目数与体积。日志都在哪里wigolo 把全部日志写到 stderr默认结构化 JSONLOG_FORMATtext给人看LOG_LEVELdebug提高详细度。没有隐藏的日志目录CLI 运行日志出现在终端 stderr用2wigolo.log重定向。MCP 宿主宿主把 server 的 stderr 捕获进它自己的 MCP 日志位置。systemd / Docker 下的wigolo servejournal / 容器日志。wigolo 自己写事件的唯一文件是可选遥测 NDJSON~/.wigolo/telemetry/且仅在WIGOLO_TELEMETRY1时。遥测默认关闭只写到本地文件不发送任何数据只有额外设置WIGOLO_TELEMETRY_ENDPOINT才会 POST 到你自己的端点docs/configuration.md。这个日志只在 stderr的设计是有意为之stdout 被保留给 MCP 协议流量和--json工具输出日志永远不污染它们docs/configuration.md。常见问题FAQ商业模式是什么会开始收费吗wigolo 是免费的开源软件采用 AGPL-3.0 许可。没有托管层级、没有计费 API、没有需要购买的 key——它是本地软件你的机器完成工作。这正是它的意义所在。AGPL 对我意味着什么直白地说把 wigolo 当作工具使用——个人、公司内部、接入你运行的每个 agent——零义务。许可证的分享条款只在你修改 wigolo 本身并以网络服务形式为他人运行修改版时生效那时你需要分享这些修改。构建仅仅调用 wigolo 的产品不属于这种情况。用它做抓取道德吗wigolo 的默认配置围绕做一个礼貌客户端构建默认遵守 robots.txt、按域名限速与抓取延迟、为研究而非批量收割设计的页面预算、以及诚实的失败标注而不是死磕撞墙。这里可靠性工作意味着像真实浏览器那样读页面——它不是伪装工具包文档也不会教你造一个。它有多稳定当前为 0.2.0 公开测试版。文档化的功能面由约 7,600 个自动化测试组成的测试套件守护beta 关乎的是打磨标准和 API 形态的信心而不是已知的不稳定。真正存在的限制都写在文档里而不是留到生产环境才被发现——见上文挑战上限一节。为什么安装包这么大因为智能在本地。下载体积主要来自设备端 embedding 排序模型约 250 MB和 JS 渲染抓取所需的可选浏览器引擎二进制约 0.5–1 GB。这是换取无 key、私有、零按次调用成本运作的代价。init --no-warmup可推迟全部下载wigolo config --cleanup可回收它们。延伸阅读docs/troubleshooting.md —— 本文的官方出处docs/configuration.md —— 上文涉及的全部环境变量的权威表格fetch、缓存寿命、daemon、遥测等docs/self-hosting.md —— 非回环绑定、数据中心 IP 现实、SSRF 网络姿态与反向代理拓扑docs/cli.md ——doctor、warmup、tune、config等命令的完整参考src/cli/doctor.ts 与 src/cli/warmup.ts —— 诊断与下载修复的源码实现【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考