Mrbaeksang/deepcloak

local-deep-research와 CloakBrowser를 둘러싼 CLI 및 MCP 래퍼입니다. 브라우저에서 선택된 실패한 페치를 재시도하고 그 결과를 기록합니다. 성공 여부는 소스와 접근 제어에 달려 있습니다.

Quickstart · 작동 방식 · 에이전트 사용 (MCP) · 개발 이유 · 변경 로그

연구 도구에 질문을 합니다. 최고의 출처 중 절반은 봇 월(Bot Wall) 뒤에 놓여 있습니다 — Cloudflare, Datadome, Turnstile, reCAPTCHA 등입니다. 다른 모든 도구는 403 에러를 받고, 해당 페이지들을 조용히 누락시키며 더 얇은 보고서를 제공합니다. 무엇을 놓쳤는지 심지어 알지 못하게 됩니다.

일반적인 페치(fetch)가 봇 월에 부딪히면, DeepCloak은 해당 URL을 **스텔스 페치(Stealth Fetch)**로 강화하고 벽을 우회하여 다른 에이전트들이 포기하는 콘텐츠를 복구합니다. 그런 다음 모든 보고서 하단에 몇 개의 벽을 뚫었는지 정확하게 알려줍니다.

이는 두 가지 훌륭한 프로젝트, 즉 local-deep-research(연구 루프)와 CloakBrowser(스텔스 브라우저) 위에 구축된 가볍고 로컬 우선의 오케스트레이터입니다. 이를 CLI, MCP 서버, 또는 Claude skill로 사용하십시오. MIT 라이선스.

개방형 웹은 조용히 닫히고 있습니다. 최고의 글쓰기 자료 중 더 많은 부분이 이제 봇 확인 뒤에 놓여 있으며, 우리가 점점 더 신뢰하는 AI 연구 에이전트들 — 우리를 대신하여 웹을 읽어주는 도구들 — 은 정확히 그 문 앞에서 눈이 멀게 됩니다. 그렇게 말조차 하지 않으면서요. 모든 벽으로 보호되는 출처를 조용히 건너뛰는 보고서는 중립적이지 않습니다. 그것은 당신이 볼 수 없는 방식으로 틀렸습니다.

DeepCloak의 입장은 간단합니다: 당신의 에이전트는 브라우저를 사용하는 사람이 읽을 수 있는 것을 읽을 수 있어야 하며 — 그리고 어떻게 거기에 도달했는지에 대해 정직해야 합니다. 필요할 때 스텔스 페치를 시도하고 그 결과에 대한 증거 기록(Evidence Record)을 출력합니다. 이 프로세스는 로컬에서 실행됩니다. 검색 엔진은 쿼리를 받고, 출처 웹사이트는 요청을 받고, 구성된 클라우드 LLM은 연구 컨텍스트를 받습니다. 컨텍스트가 기기에 머물러야 할 경우 로컬 LLM을 선택하십시오. 역량과 투명성, MIT 라이선스이며, 종속성이 없습니다.

| 일반 심층 리서치 (Plain deep research) | DeepCloak |
| :---: | :---: | :---: |
| 오픈 웹 읽기 | ✅ | ✅ |
| Cloudflare / Datadome / Turnstile / reCAPTCHA 페이지 읽기 | ❌ 조용히 누락됨 (dropped silently) | ✅ 우회함 (Bypassed) |
| 어떤 출처가 벽으로 막혔는지 알려줌 | ❌ | ✅ 증거 기록 (Evidence Record) |
| 로컬 우선 (API 키 불필요) | ✅ | ✅ |
| 오픈 페이지에서 빠름 | — | ✅ plain-first, 필요할 때만 은신 모드 사용 (stealth only when needed) |

검증된 실시간 작동 — 모의가 아님. 위의 클립은 실제 deepcloak이 로컬 LLM (Qwen) + SearXNG를 대상으로 실행한(API 키 없음) 비편집 화면 녹화(ffmpeg로 캡처, 합성 없음)입니다. 이 과정에서 각 Bot Wall에 대해 에스컬레이션하며 Cloudflare/Turnstile 벽 8개를 한 번의 패스로 우회하고, 인용된 보고서를 작성합니다. 전체 클립: docs/media/demo-real.mp4

또한 원시적인 asciinema 세션이 docs/media/demo.cast에 보관되어 있습니다.

벽 카운트는 오픈 웹의 특성상 실행마다 다릅니다 (8–20).

pip install deepcloak
deepcloak setup # 일회성: 은신 브라우저 다운로드
export OPENAI_API_KEY=... # 또는 ANTHROPIC_API_KEY / GEMINI_API_KEY — 또는 --provider ollama
...

인용된 report.md를 받게 되며, 이 파일은 🛡️ Bypassed N bot-walled sources 섹션으로 끝납니다. 또한 report.md.evidence.json 사이드카(sidecar) 파일을 함께 제공합니다.

search (DuckDuckGo, 설정 불필요) ─▶ 후보 URL들
│
▼ 각 페이지에 대해:
...

은신 모드는 무겁기 때문에 DeepCloak은 먼저 저렴한 일반 가져오기(plain fetch)를 시도하고, 실제로 Bot Wall을 감지했을 때만 은신 브라우저를 실행합니다 (--stealth auto, 기본값). 우회가 발생하는 전체 페이지를 가져오려면 --depth detailed 또는 --report를 사용하세요.

DeepCloak은 deep_research(query, depth, provider, model), quick_summary(query, provider, model), get_evidence(run_id), 그리고 list_models(provider)를 노출하는 표준 입/출력 MCP 서버로 실행됩니다.

Claude Code — 프로젝트의 .mcp.json에 추가하세요 (예시가 이 리포지토리에 포함되어 있습니다):
`{

그리고 봇에 의해 차단된 소스도 직접 읽을 수 있습니다. 슬래시 스타일의 스킬을 선호하십니까? 다음을 ~/.claude/skills/deepcloak/ 디렉터리로 넣으세요.

모델 선택: deepcloak models --provider openrouter로 제공되는 모델 목록을 확인하세요.
(모든 공급자에 적용 가능; --base-url을 통한 로컬 서버도 해당)
그 후, --model <id>를 전달하면 됩니다. 환경에 여러 자격 증명이 있고 실제 터미널에서 DeepCloak은 단순히 질문합니다. 설정은 ~/.config/deepcloak/config.toml에 유지됩니다.( $DEEPCLOAK_CONFIG로 덮어쓸 수 있음); 우선순위: CLI 플래그 > 환경 변수 > 설정 파일.

실행 기록: 완료된 실행은 ~/.local/share/deepcloak/runs/에 저장됩니다.— deepcloak runs로 탐색하고, deepcloak show <id>로 보고서를 다시 재생합니다.(전체 기록을 원하면 --json 사용).

DeepCloak은 봇 감지를 우회합니다. 사용자는 가져오는 모든 내용에 대한 접근 권한이 있음을 책임져야 합니다. robots.txt는 기본적으로 무시됩니다; 이를 준수하려면 --respect-robots를 전달하세요 (ADR-0002). 사이트의 약관이나 법을 위반하는 데 사용하지 마십시오.

• 더 많은 봇 월(Bot Wall) 시그니처 + 더욱 스마트한 에스컬레이션 휴리스틱
• DuckDuckGo / SearXNG 외 더 많은 검색 백엔드
• 실행 간 캐시 우회 페이지
• 풍부해진 증거 기록 내보내기 (HTML / JSON 스키마)

아이디어를 환영합니다 — 토론을 시작하거나 기능 요청을 열어주세요.

local-deep-research
(MIT) + CloakBrowser}<tool_call|>```json</code></p>{

(MIT) 라이선스이며, pip을 통해 설치할 수 있습니다. 외부 종속 코드가 포함되어 있지 않습니다. 도메인 용어집은 CONTEXT.md에, 설계 결정 사항은 docs/adr/에, 기여 가이드는 CONTRIBUTING.md에 명시되어 있습니다.