AI 에이전트를 위한 로컬 우선 (Local-first) 웹 인텔리전스 — 키(key) 없음, 클라우드 없음, 종량제 요금 없음.

Claude Code · Cursor · Codex · Gemini CLI · VS Code · Windsurf · Zed · Antigravity와 함께 작동하며

그 이상도 가능합니다.

LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n 및 셀프 호스팅 (self-hosted) 에이전트 · 모든 MCP 클라이언트 · 일반 REST

Quickstart · 도구 (Tools) · wigolo를 사용하는 이유 · 벤치마크 (Benchmark) · 문서 (Docs) · 예시 (Examples) · 피드백 (Feedback) · FAQ

wigolo는 AI 에이전트에게 웹과 관련된 모든 것을 위한 하나의 지속 가능한 인터페이스를 제공합니다 — 검색 (search), 가져오기 (fetch), 크롤링 (crawl), 추출 (extract), 캐싱 (cache), 유사 항목 찾기 (find-similar), 조사 (research), 그리고 자율적인 수집 루프 (gather loops)를 지원합니다. 에이전트가 실행되는 곳이라면 어디든 실행됩니다: 코딩 에이전트 옆의 MCP 서버로서, 셀프 호스팅 에이전트가 상주하는 장치의 REST/MCP 엔드포인트로서, 또는 자체 앱 내부의 SDK를 통해 임베디드되어 실행됩니다. 핵심 도구들은 API 키가 필요 없으며, 도구가 건드리는 그 어떤 것도 ~/.wigolo/를 벗어나지 않습니다.

또한 에이전트가 얼마나 많이 생각하느냐에 따라 늘어나는 요금도 없습니다.

Node ≥ 20 및 약 1.5 GB의 여유 디스크 공간이 필요합니다. macOS, Linux, Windows 지원.

단 한 번의 명령으로 로컬 엔진을 에이전트에 연결합니다. init 명령은 기본적으로 무인 (unattended) 방식으로 작동하여 — 프롬프트 없이 스크립트 및 CI 환경에서도 안전하며 — **전체 설정 (complete setup)**을 수행합니다: 브라우저 엔진과 온디바이스 모델 (on-device models)을 다운로드하고, 상태 확인 (health check)을 실행하며, 구성 요소별 요약 정보를 출력합니다. 따라서 설정 문제는 에이전트의 첫 호출 시 조용히 발생하는 대신 바로 여기서 드러납니다:

npx wigolo init --agents=<your-agent>

— <your-agent>에는 하나 이상의 다음 값이 들어갈 수 있습니다: claude-code · cursor · codex · gemini-cli · vscode · windsurf · zed · antigravity (쉼표로 구분). wigolo가 당신을 대신해 MCP 설정과 지침을 작성합니다.

다른 MCP 클라이언트를 사용하시나요?
--agents를 생략하고 직접 npx -y wigolo를 등록하세요 — 설치 가이드에 모든 클라이언트를 위한 정확한 설정 블록이 포함되어 있으며, Docker, Homebrew, 단일 파일 바이너리 (single-file-binary) 채널도 제공합니다.

프롬프트를 선호하시나요?
--interactive는 일반 텍스트 흐름을 제공하며, --wizard는 전체 터미널 TUI (Terminal User Interface)를 제공합니다.

다운로드를 건너뛰고 싶으신가요?
--no-warmup

모든 것을 첫 사용 시점까지 미룹니다. 컴포넌트 다운로드에 실패하더라도 설정 자체가 실패하지는 않습니다. 초기화 (init) 과정에서 준비되지 않은 항목이 무엇인지 정확한 해결 방법과 함께 보고하며, 에이전트 (agent) 연결은 그대로 유지합니다.

이것이 전체 설정의 전부입니다 — API 키 없이도 검색 (search), 가져오기 (fetch), 크롤링 (crawl), 추출 (extract), 캐싱 (cache), 유사 항목 찾기 (find-similar) 기능이 작동합니다. 언제든 상태를 확인하세요:

npx wigolo doctor

사용하고 싶지 않으신가요? npx wigolo config --uninstall --yes를 실행하면

모든 것을 깔끔하게 제거합니다. 또한 설치 가이드를 어떤 AI 어시스턴트(AI assistant)에든 붙여넣어 설치를 맡길 수도 있습니다. 가이드 자체가 독립적으로 실행되도록 작성되었습니다.

검색 (search), 가져오기 (fetch), 크롤링 (crawl), 추출 (extract), 캐싱 (cache), 유사 항목 찾기 (find-similar)는 완전한 키리스 (keyless) 방식입니다. 하지만 research, agent, 그리고 search format=answer는

LLM을 사용하여 합성되고 인용된 답변을 작성합니다. LLM이 없다면 에이전트가 조립할 수 있도록 가공되지 않은 요약본과 증거만을 반환하며, 이는 훨씬 빈약한 경험을 제공합니다. 무료 Gemini 키 하나면 충분하며, 이는 여러분이 할 수 있는 가장 큰 품질 업그레이드입니다:

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<free-key> # aistudio.google.com/apikey 에서 받으세요 — 무료 티어로도 충분합니다

어떤 제공자(provider)든 작동하며 (anthropic · openai · groq), 또는 WIGOLO_LLM_PROVIDER=ollama (또는 모든 OpenAI 호환 URL)를 통해 완전히 로컬(local) 상태로 키 없이 유지할 수 있습니다. 셸(shell)이나 에이전트의 MCP env 블록에 설정하세요. 제공자, 모델, 그리고 키리스 로컬 모델 계층에 대한 정보는 다음을 참조하세요: 구성 가이드 (configuration guide).

단순한 스니펫(snippets)이 아닌 증거를 제공합니다. 모든 검색 결과는 소스 내 정확한 위치에 고정된 축자적 발췌문(verbatim excerpt), 에이전트가 인용할 수 있는 인용 ID (citation ID), 그리고 에이전트가 검사할 수 있는 점수 (score)를 포함합니다 (요약된 실제 형태):

{
"results": [{
"title": "Logical replication - PostgreSQL docs",
...

품질이 낮은 결과는 wigolo 자체 스코어러(scorer)에 의해 스팸(junk)으로 분류되고, 실패한 엔진은 보고되며, 오래된 캐시는 라벨이 붙습니다 — 에이전트는 자신이 무엇을 근거로 삼고 있는지 항상 알 수 있습니다. 도구별 전체 응답 규약은 다음을 참조하세요: 도구 참조 (tools reference).

모든 도구는 터미널에서 실행 가능하며 (wigolo search "…" --json), NDJSON 파이핑 (piping)이 가능한 대화형 셸 (wigolo shell)에서 실행 가능하고, REST를 통해, 그리고 SDK를 통해 실행할 수 있습니다 — CLI 참조 (CLI reference).

각 도구는 단순한 한 줄 설명 그 이상의 기능을 수행합니다. 샘플러(Sampler) — 모든 줄은 가이드(guide)로 연결되며, 가이드가 있는 경우 실행 가능한 예제(runnable example)로 연결됩니다:

확산되는 검색 (Search that fans out)— 병렬적인 너비 확장을 위해 쿼리 **배열 (array)**을 전달하고, include_domains로 범위를 지정하며, time_range / 최신성(recency)으로 제한하고, 정확한 문구 일치(exact-phrase match), 깊이 계층(depth tier) 선택, 심지어 이미지 결과까지 지원합니다. → 가이드 · 예제
거의 무엇이든 가져오기 (Fetch almost anything)— JS로 렌더링되는 SPA, PDF, 단일 헤딩 section (섹션)

, 인증된 페이지(브라우저 프로필 또는 원격 브라우저를 통해), 또는 actions(클릭 / 타이핑 / 스크롤 / 스크린샷)로 페이지를 제어합니다. → 가이드사이트 전체 크롤링 (Crawl a whole site)— 사이트맵, BFS, DFS 또는 맵 전용 방식; robots.txt 준수, 도메인별 속도 제한(rate-limited), 불필요한 코드(boilerplate) 중복 제거. → 가이드구조 추출 (Extract structure)— 테이블, JSON-LD, 메타데이터, 브랜드 자산, 명명된 스키마(Article / Recipe / Product / …), 또는 사용자 정의 JSON Schema. → 가이드복리로 쌓이는 메모리 (A memory that compounds)— 모든 페이지가 캐싱됩니다; 키워드나 의미 단위로 즉시 오프라인 재조회 가능; 마지막 방문 이후 변경된 사항 감지. → 가이드 · 예시리서치 및 자율 수집 (Research & autonomous gather)— 질문을 인용된 요약본(brief)으로 분해하거나, agent가 계획 수립 → 가져오기(fetch) → 추출(extract) → JSON Schema 및 시간 예산에 맞춘 종합(synthesize) 과정을 수행하도록 자유롭게 설정합니다. → 가이드 · 예시감시 및 차이 분석 (Watch & diff)— URL을 모니터링하고, 변경 보고서를 생성하여 웹훅(webhook)으로 전달합니다. → 가이드 · 예시원하는 방식으로 제어 (Drive it your way)— 단발성 CLI, 파이프라인용 NDJSON 셸, REST, SDK, 또는 에이전트가 설치할 수 있는 기술(skills)로 제공됩니다. → CLI & 셸 · 예시확장하기 (Extend it)— 약 100줄 내외의 플러그인으로 검색 엔진이나 사이트 추출기를 추가할 수 있습니다. → 플러그인 · 예시튜닝 및 점검 (Tune & inspect)— wigolo tune은 도메인별 학습 내용(가져오기 티어, 챌린지 통과 여부, 백오프(backoff) 등)을 보여주며; doctor / verify는 모든 구성 요소의 상태를 점검합니다. → CLI · 문제 해결

wigolo는 예산이 확보될 때까지 임시로 사용하는 무료 대체재가 아닙니다. 이 분야의 유료 서비스들과 동일한 성능을 유지하도록 구축되었으며, 그 결과로 증명합니다. wigolo를 차별화하는 실제 요소는 다음과 같습니다:

인간이 아닌 에이전트를 위해 구축되었습니다. 하나의 MCP 호출이 여러 엔진에 걸쳐 많은 쿼리를 병렬로 분산시킵니다. 이는 순차적인 호스트 도구 루프(serial host tool-loop)로는 복제할 수 없는 기능이며, 결과별로 투명한 점수 산정(scoring)과 예산을 고려한 출력을 제공합니다.
정직한 출력. 오래된 캐시, 가져오기 실패, 성능 저하된 백엔드, 데이터 잘림(truncation) 등이 결과에 그대로 드러나며, 결코 '성공했지만 비어 있는 데이터'로 위장되지 않습니다. 봇 보호가 적용된 페이지를 읽을 수 없는 경우, blocked_by_challenge라는 라벨이 붙은 결과를 받게 됩니다.

실패 — 콘텐츠로 위장한 챌린지 셸(challenge shell)은 절대 없습니다.쿼리당 $0, 재쿼리는 무료. 기본 검색은 직접 어댑터(adapters)를 통해 공개 엔진과 통신하며, 리랭커(reranker)와 임베딩(embeddings)은 온디바이스(on-device)에서 실행됩니다. 모든 응답은 캐싱(cached)되므로, 다시 질문하면 즉각적이며 비용이 들지 않습니다.**기본적으로 프라이버시 보호.**캐시, 임베딩, 모델 및 설정은 ~/.wigolo/ 아래에 저장됩니다. 합성을 위해 LLM을 명시적으로 선택하지 않는 한, 그 어떤 것도 제3자에게 전달되지 않습니다.

wigolo는 에이전트(agents)를 위한 집중적인 웹 레이어(web layer)입니다. 호스팅되는 SaaS, 다른 앱이 쿼리하는 벡터 데이터베이스(vector database), 또는 대규모 스크래핑(scale-scraping) 플랫폼이 아닙니다. 해당 영역 내에서 wigolo는 결과 품질 면에서 유료 서비스들과 정면 승부를 펼치며, 사용량 측정(meter), 키(key), 데이터 유출(data-egress) 등의 요소는 존재하지 않습니다.

실제 결과 하나가 어떻게 구성되는지 분석해 보겠습니다. 실패한 엔진과 취약한 결과도 포함되어 있는데, 이 또한 답변의 일부이기 때문입니다:

네 가지 도구 모두 동일한 핵심 답변으로 수렴했습니다. 그리고 그중 단 하나만이 답변을 제공하면서 문구 그대로의, 바이트 단위로 고정된(byte-pinned) 증거를 전달했습니다.

단일 Claude Fable 5 세션 내에서 실시간으로 실행되어 네 가지 웹 도구 — 내장된 WebSearch, wigolo, Tavily, Exa — 에 동등한 조건으로 분산된 하나의 콜드 쿼리(cold query)를 수행했습니다. 그 후 에이전트 스스로가 '편견 없이 오직 증거로만 판단하라'는 하나의 규칙에 따라 보고했습니다. 네 가지 도구 모두 동일한 답변과 동일한 최상위 소스로 수렴했으며, 이는 주장이 아닌 동등성(parity)의 입증입니다. 오직 wigolo만이 바이트 오프셋 소스 범위(byte-offset source spans)에 고정된 문구 그대로의 발췌문, 설명 가능한 점수 분해(explainable score decomposition), 그리고 엔진별 실시간 텔레메트리(telemetry)를 반환했습니다. 또한 wigolo의 결과 중 두 개가 취약했을 때, 자체 스코어러(scorer)가 이를 화면에 쓰레기(junk)로 표시했습니다. 클라우드 도구들도 제 역할을 다했습니다. Exa는 공식 문서의 비교 매트릭스를 전체적으로 렌더링했습니다. 이는 리더보드(leaderboard)가 아닌 정직한 쿼리입니다. 직접 실행해 보시면 동일한 양상을 확인하실 수 있습니다.

마지막 행은 문제가 누적되는 부분입니다. 에이전트(agents)는 한 번만 요청하는 것이 아니라, 폭발적으로(in bursts) 요청을 보냅니다.

동일한 10가지 도구가 코딩 에이전트를 위한 MCP, 그 외 모든 것을 위한 REST, 임베딩을 위한 SDK, 바로 적용 가능한 프레임워크 래퍼(framework wrappers) 등 적합한 모든 인터페이스를 통해 모든 종류의 에이전트에게 제공됩니다.

하나의 프로세스가 MCP 전송(transport)과 함께 일반 JSON REST API를 노출합니다. MCP 클라이언트가 필요하지 않으며, 단순히 curl을 사용하면 됩니다:

wigolo serve # 127.0.0.1:3333 — 루프백(loopback)은 열려 있으며, 루프백 이외의 접속에는 토큰이 필요합니다
curl -sX POST http://127.0.0.1:3333/v1/search \
-H 'Content-Type: application/json' \
...

POST /v1/{tool}은

10가지 도구 전체를 커버하며, GET /openapi.json은

OpenAPI 3.1 규약(contract)입니다. 또한 /mcp와 /sse는

동일한 포트에서 원격 MCP 클라이언트에 서비스를 제공합니다. 루프백을 벗어나 바인딩(Bind)할 경우 베어러 토큰(bearer token)이 필수적입니다. 이는 실수로 광범위하게 개방되는 대신, 보안을 위해 기본적으로 차단(fails closed)되도록 설계되었기 때문입니다. n8n, Hermes 스타일의 어시스턴트, 또는 모든 셀프 호스팅 에이전트를 여기에 연결하십시오. → REST API

별도의 serve 단계 없이, 데몬(daemon)을 찾아주거나 직접 시작해주는 로컬 모드가 내장된 가볍고 타입이 지정된(typed) 클라이언트들을 제공합니다.

TypeScript — npm install wigolo-sdk

(의존성 없음(zero-dep); Node / Bun / Deno / edge 지원):

import { createLocalClient } from 'wigolo-sdk/local';
const { client, close } = await createLocalClient(); // 실행 중인 데몬을 재사용하거나 새로 생성합니다
const res = await client.search({ query: 'local-first web search', max_results: 5 });
...

Python — pip install wigolo

(표준 라이브러리만 사용; 동기(sync) + 비동기(async) 지원):

from wigolo import local_client
with local_client() as client: # 정상 작동 중인 데몬을 재사용하거나 새로 생성합니다
    res = client.search(query="local-first web search", max_results=5)
...

wigolo의 도구들을 이미 사용 중인 프레임워크에 바로 적용하십시오. 대부분의 프레임워크 웹 도구들이 제공하지 않는 캐시(cache) / 유사 항목 찾기(find_similar) / 리서치(research) / 에이전트(agent)를 포함하여 10가지 도구 전체를 사용할 수 있습니다.

# stdio MCP — 명령어로 모든 MCP 클라이언트에 연결: docker
docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo
# 원격 / 멀티 클라이언트 사용을 위한 HTTP 서버
...

슬림(slim) 이미지는 볼륨(volume)으로 모델을 지연 로딩(lazy-loads)하며, :full 버전은 브라우저 엔진을 사전 설치합니다. Docker Hub의 towhid69420/wigolo에서도 사용할 수 있습니다. → 설치 및 모든 채널

11종의 스킬 카탈로그(skill catalog)는 코딩 에이전트(coding agent)가 각 도구를 잘 다룰 수 있도록 학습시킵니다 — init으로 설치하며, wigolo skills add|list|remove로 관리합니다. → 스킬 (skills)