jo-inc/camofox-browser

camofox-browser – AI 에이전트를 위한 감지 회피 브라우저 서버

개요 – 패치된 Firefox 바이너리 (Camoufox)를 실행하고 REST API를 노출하여 자율 AI 에이전트가 지문 채취나 차단 없이 웹을 탐색할 수 있게 해주는 Node-JS 서비스입니다. 브라우저는 C++ 수준에서 수정되어 JavaScript가 실행되기 전에 하드웨어, WebGL, WebRTC, 화면 크기 등을 위조합니다. 서버는 가벼운 접근성 스냅샷 (페이지 UI 트리의 컴팩트한 표현)과 선택적 스크린샷을 반환하며, 클릭, 입력, 스크롤 등을 안정적으로 수행할 수 있도록 안정적인 요소 참조 (e1, e2 …)를 제공합니다.

AI에게 중요한 이유 – 대규모 언어 모델 에이전트는 종종 웹사이트에서 실제 정보를 가져와야 합니다. 기존의 헤드리스 브라우저 (Playwright, Chrome)는 봇 방지 서비스 (Google, Cloudflare)에 의해 쉽게 감지되고 차단됩니다. camofox-browser는 다음과 같은 방법으로 이를 해결합니다:

• Camoufox의 저수준 지문 위조를 사용하여 세션을 일반 데스크톱 Firefox처럼 보이게 합니다.
• 토큰 효율적인 API를 제공하여 (스냅샷은 원시 HTML보다 약 90 % 작음) LLM의 토큰 사용량을 줄입니다.
• 세션 격리, 쿠키 가져오기, 프록시/GeoIP 처리 및 VNC 기반 수동 로그인을 지원하여 에이전트가 작업 간에 인증된 세션을 유지할 수 있도록 합니다.

주요 기능

• C++ 감지 회피 – 하드웨어 동시성, WebGL, AudioContext, 화면 기하학, WebRTC 등을 JS가 인식하기 전에 위조합니다.
• 요소 참조 – 결정론적 작업을 위한 안정적인 식별자 (e1, e2).
• 접근성 스냅샷 – 컴팩트한 JSON UI 트리; 선택적 base64 PNG 스크린샷.
• 세션 관리 – 사용자별 저장소, 쿠키 가져오기 (Netscape 형식), 영구 프로필, 선택적 IndexedDB 영속성.
• 프록시 & GeoIP – 자동 로케일/시간대 매칭을 지원하는 주거용 프록시 지원.
• 검색 매크로 – Google, YouTube, Amazon, Reddit 등을 위한 내장 바로가기.
• YouTube 자막 – yt-dlp를 통해 (API 키 불필요).
• 대형 페이지 처리 – 스냅샷 페이지 매기기, 다운로드 캡처, 이미지 추출.
• 추적 – 세션당 선택적 Playwright 추적 (스크린샷, DOM, 네트워크), zip으로 다운로드 가능.
• 배포성 – Docker, Fly.io, Railway, Raspberry Pi 지원; 낮은 유휴 메모리 사용량 (~40 MiB).
• 텔레메트리 – 익명화된 충돌/상태 보고서를 Cloudflare Worker로 전송하여 GitHub issue 생성; 옵트아웃 가능.

시작하기

1. 복제 및 설치:

   git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
   npm install   # 최초 실행 시 Camoufox (~300 MiB) 다운로드
   npm start     # 서버가 9377 포트에서 대기
   

2. API 호출 (예: 탭 생성):

   curl -X POST http://localhost:9377/tabs \
        -H 'Content-Type: application/json' \
        -d '{"userId":"agent1","url":"https://example.com"}'
   

   응답에는 tabId와 접근성 스냅샷이 포함됩니다.
3. 제공된 OpenClaw 플러그인 명령 (camofox_click, camofox_type 등) 또는 직접 HTTP 엔드포인트를 사용하여 페이지와 상호 작용합니다.
4. 인증이 필요한 사이트의 경우 쿠키를 가져옵니다:

   export CAMOFOX_API_KEY=$(openssl rand -hex 32)
   # Netscape 형식의 쿠키 파일을 ~/.camofox/cookies/ 에 배치
   camofox_import_cookies linkedin.txt
   

5. 제공된 Makefile/build.ps1을 사용하여 Docker (또는 Fly.io/Railway)로 배포합니다. 스크립트는 빌드 속도를 높이기 위해 바이너리를 미리 다운로드합니다.

일반적인 사용 사례 – LLM 기반 개인 비서 (예: jo)가 *“Reddit에서 2024 Tesla Model Y에 대한 최신 리뷰를 찾아 요약해줘”*라는 요청을 받습니다. 에이전트는 camofox_browser를 호출하여 Reddit을 열고, 검색 매크로를 실행하며, 접근성 스냅샷을 통해 UI 트리를 추출하고, 관련 요소를 파싱한 다음 응답을 작성합니다. 이 모든 과정에서 기본 브라우저는 Reddit의 봇 방지 조치에 감지되지 않습니다.

제한 사항 / 고려 사항

• Camoufox 바이너리 (≈300 MiB)가 필요하며, YouTube 자막에는 선택적으로 yt-dlp가 필요합니다.
• 텔레메트리는 기본적으로 활성화되어 있습니다. 개인 정보 보호가 우려되는 경우 CAMOFOX_CRASH_REPORT_ENABLED=false로 비활성화하십시오.
• 추적은 세션 생성 시에만 활성화할 수 있으며 나중에 전환할 수 없습니다.
• 이 서비스는 Playwright 제어 Firefox의 래퍼이므로 네트워크 수준에서 브라우저를 차단하는 사이트 (예: IP 차단)의 경우 여전히 신뢰할 수 있는 프록시가 필요합니다.

라이선스 – MIT.