camofox-browser: AI 에이전트를 위한, 스텔스 헤드리스 브라우저 (feat. Camoufox)

읽을거리&정보공유
, , , , , ,
1

camofox-browser: AI 에이전트를 위한, 스텔스 헤드리스 브라우저 (feat. Camoufox)
camofox-browser: AI 에이전트를 위한, 스텔스 헤드리스 브라우저 (feat. Camoufox)989×465 46 KB

camofox-browser 소개

camofox-browser는 AI 에이전트(Agent)가 실제 웹을 자유롭게 탐색할 수 있도록 만든 안티 디텍션(Anti-detection) 브라우저 서버입니다. 일반적인 헤드리스(Headless) 환경에서 Playwright나 Puppeteer를 그대로 사용하면 Google·Cloudflare·각종 봇 차단 시스템이 손쉽게 자동화를 식별해 차단해버립니다. 자동화 우회를 목적으로 만든 스텔스 플러그인(Stealth plugin)을 얹어도, 그 플러그인 자체가 또 하나의 지문(Fingerprint)이 되어 탐지의 근거가 되는 일이 흔합니다. camofox-browser는 이 문제를 정면으로 다루기 위해 Camoufox 엔진을 REST API로 감싸 에이전트에게 곧장 노출하고, 브라우저 자체의 동작을 C++ 레벨에서 손봐 자동화 신호 자체를 제거합니다.

기반이 되는 Camoufox는 Firefox의 포크(Fork)로, navigator.hardwareConcurrency, WebGL 렌더러, AudioContext, 화면 기하 정보, WebRTC와 같은 핵심 지문 항목을 JavaScript가 접근하기 전에 C++ 구현 레벨에서 모두 위조합니다. 즉 페이지가 실행하는 어떤 자바스크립트 코드도 이미 위장된 값만 볼 수 있고, 별도의 심(Shim)이나 래퍼(Wrapper)가 끼어들지 않으므로 탐지 코드 입장에서는 단서가 거의 남지 않습니다. camofox-browser는 이 강력한 엔진을 그대로 두고, AI 에이전트가 실제로 필요로 하는 API를 위에 얹는 역할을 합니다.

특히 LLM 기반 에이전트가 효율적으로 페이지를 다룰 수 있도록 설계되었다는 점이 인상적입니다. 페이지의 원본 HTML을 그대로 토큰으로 흘려보내면 비용과 지연이 급증하기 때문에, camofox-browser는 접근성 트리(Accessibility tree) 기반 스냅샷에 e1, e2, e3와 같은 안정적인 요소 참조(Element ref)를 부여하여 에이전트가 짧은 키만으로 클릭·입력·스크롤을 수행할 수 있도록 만들어 둡니다. 공식 README에 따르면 이 접근법은 원본 HTML 대비 약 90% 작은 크기의 스냅샷을 만들어 LLM 호출의 토큰 사용량을 크게 줄여 줍니다.

camofox-browser의 핵심 기능

camofox-browser는 단순한 브라우저 래퍼가 아니라, 에이전트 운영에 필요한 거의 모든 도구를 묶어둔 서버입니다. 주요 기능을 정리하면 다음과 같습니다.

  • C++ 레벨 안티 디텍션: Camoufox 엔진을 통해 Google·Cloudflare를 포함한 대부분의 봇 탐지 시스템을 우회하며, 자바스크립트가 접근하기 전 단계에서 지문을 위조합니다.

  • 요소 참조(Element Ref): 페이지 요소마다 e1, e2와 같은 안정적인 키를 부여하여 에이전트가 셀렉터(Selector)를 직접 다루지 않고도 신뢰 가능한 상호작용을 할 수 있게 합니다.

  • 토큰 효율적 스냅샷: 접근성 기반 스냅샷이 원본 HTML 대비 약 90% 더 작아, LLM 호출 비용과 지연을 큰 폭으로 낮춥니다.

  • 저자원 환경 친화적 설계: 지연 브라우저 시작(Lazy launch)과 유휴 자동 종료(Idle shutdown)를 적용하여 유휴 시 약 40MB의 메모리만 점유하며, Raspberry Pi나 5달러 VPS와 같은 환경에서도 무리 없이 함께 떠 있을 수 있습니다.

  • 세션 격리(Session Isolation): 사용자별로 쿠키와 스토리지를 격리하여 다중 사용자/에이전트 운영에 적합합니다.

  • Netscape 쿠키 임포트: 브라우저에서 추출한 Netscape 형식 쿠키 파일을 주입해 LinkedIn·Amazon 같은 사이트에 즉시 인증된 상태로 진입할 수 있습니다.

  • 프록시 + GeoIP 자동 정렬: 주거용 프록시(Residential proxy) 사용 시 Camoufox의 GeoIP가 자동으로 locale, timezone, geolocation을 프록시 출구 IP에 맞춰 정렬합니다.

  • 검색 매크로(Search Macro): @google_search, @youtube_search, @amazon_search, @reddit_subreddit 등 14개의 매크로로 자주 쓰는 사이트의 검색 흐름을 한 번의 호출로 처리합니다.

  • YouTube 자막 추출: yt-dlp를 활용해 API 키 없이도 임의의 YouTube 영상에서 자막을 추출하고, 미설치 시에는 브라우저 기반 폴백을 사용합니다.

  • 구조화된 JSON 로깅과 세션 트레이스(Session Trace): 모든 로그가 JSON 한 줄 형태로 정리되며, 옵션으로 페이지 스크린샷·DOM 스냅샷·네트워크·콘솔을 묶은 Playwright 트레이스 zip 파일을 생성합니다.

  • 다양한 배포 옵션: Docker·Fly.io·Railway 배포 템플릿이 포함되어 있으며, noVNC 기반 인터랙티브 로그인 기능으로 시각적으로 로그인한 뒤 상태를 저장해 에이전트에 재사용시킬 수 있습니다.

camofox-browser의 아키텍처와 동작 흐름

전체 흐름은 OpenClaw 플러그인이나 일반 HTTP 클라이언트에서 시작되는 작업이 camofox-browser 서버를 통과해 Camoufox 브라우저로 전달되는 직선 구조입니다. 쿠키 임포트와 같이 보안이 중요한 작업은 Bearer 토큰을 통해 인증을 거치며, 서버는 도메인 필터링·경로 우회 차단·필드 화이트리스트 검사 등 다단계 방어를 적용한 뒤에야 Playwright의 context.addCookies()로 쿠키를 주입합니다. README의 설명을 기준으로 인증된 쿠키 임포트 흐름은 다음과 같이 정리됩니다.

~/.camofox/cookies/linkedin.txt          (Netscape 형식 쿠키 파일)
        |
        v
camofox_import_cookies tool              (파일을 읽어 도메인 기준 필터링)
        |
        v  POST /sessions/:userId/cookies
        |  Authorization: Bearer <CAMOFOX_API_KEY>
        |  Body: { cookies: [Playwright cookie objects] }
        v
camofox 서버                              (검증, 정제, 주입)
        |
        v  context.addCookies(...)
        |
Camoufox 브라우저 세션                    (인증된 상태로 탐색)

세션 영속성(Session persistence)을 켜 두면 각 사용자 단위로 쿠키와 localStorage가 ~/.camofox/profiles/<hashed-userId>/storage_state.json에 저장되어, 브라우저 재시작 후에도 인증 상태가 자동으로 복원됩니다. 사용자별 식별자는 해시되어 디스크에 기록되므로 운영 환경에서도 원본 ID가 그대로 노출되지 않습니다. 더 강한 디버깅이 필요할 때는 세션 단위로 Playwright 트레이스를 옵트인(Opt-in)할 수 있고, 트레이스는 세션이 닫힐 때 zip으로 플러시되어 playwright show-trace로 곧장 열어볼 수 있습니다.

운영 환경을 염두에 둔 텔레메트리(Telemetry) 설계도 흥미롭습니다. 자동화 실패는 Cloudflare 챌린지·사이트 리뉴얼·리다이렉트 루프·렌더러 크래시처럼 다양하게 발생하기 때문에, camofox-browser는 처리되지 않은 예외, 5초 이상 정체된 이벤트 루프, 같은 탭에서 3회 연속 발생한 실패 패턴이 감지되면 별도의 Cloudflare Worker 엔드포인트로 익명화된 보고를 보내고 GitHub Issue를 자동 생성합니다. URL은 공개 도메인만 그대로 노출되고 비공개 도메인은 HMAC 해시로 치환되며, 토큰·IP·이메일·경로는 모두 마스킹됩니다. 보고가 부담스럽다면 CAMOFOX_CRASH_REPORT_ENABLED=false로 비활성화하거나 CAMOFOX_CRASH_REPORT_URL로 자체 호스팅 엔드포인트를 가리킬 수 있습니다.

camofox-browser의 설치 및 사용법

가장 빠르게 띄우는 방법은 저장소를 클론한 뒤 npm으로 실행하는 것입니다. 최초 실행 시 약 300MB 크기의 Camoufox 바이너리가 자동으로 내려받아지고, 기본 포트는 9377입니다.

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start  # 최초 실행 시 Camoufox 바이너리 다운로드 (~300MB)
# 서버: http://localhost:9377

OpenClaw 환경을 사용하는 경우에는 별도의 플러그인으로 설치하여 camofox_create_tab, camofox_snapshot, camofox_click, camofox_type과 같은 도구를 곧장 호출할 수 있습니다.

openclaw plugins install @askjo/camofox-browser

기본적인 브라우징은 모두 REST API 위에서 이루어집니다. 탭을 열고, 접근성 스냅샷을 받아 본 뒤, 요소 참조를 그대로 사용해 클릭·입력·스크롤·검색을 수행하는 식입니다.

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

# 접근성 스냅샷 (요소 참조 포함)
curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1"
# -> { "snapshot": "[button e1] Submit  [link e2] Learn more", ... }

# 요소 참조로 클릭
curl -X POST http://localhost:9377/tabs/TAB_ID/click \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "ref": "e1"}'

# 입력 후 엔터
curl -X POST http://localhost:9377/tabs/TAB_ID/type \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "ref": "e2", "text": "hello", "pressEnter": true}'

# 검색 매크로로 이동
curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "macro": "@google_search", "query": "best coffee beans"}'

Docker로 배포할 때는 Makefile이 아키텍처를 자동 감지해 Camoufox와 yt-dlp 바이너리를 빌드 외부에서 미리 받아두므로 재빌드가 빠릅니다. 다만 README에서 강조하듯 docker build를 직접 호출하지 말고 반드시 make up을 사용해야 바인드 마운트로 바이너리가 들어옵니다. Fly.io나 Railway의 경우 빌드 시점에 바이너리를 받는 Dockerfile.ci가 제공되며, railway.toml에서 PORT 환경변수를 CAMOFOX_PORT로 자동 매핑하도록 설정되어 있습니다.

라이선스

camofox-browser는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용·수정·재배포할 수 있습니다. 다만 내부적으로 사용하는 Camoufox 엔진은 자체 라이선스를 따르므로, 자동화 대상 사이트의 이용 약관과 함께 Camoufox 측 라이선스를 별도로 확인해 두는 편이 안전합니다.

:house: Camoufox 엔진 공식 사이트

:github: camofox-browser 프로젝트 GitHub 저장소

더 읽어보기



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck: