jo-inc/camofox-browser 딥다이브
— 봇 탐지를 뚫는 AI 에이전트 전용 브라우저 서버

1한 줄 정체

camofox-browser는 "봇 탐지에 걸리지 않는 브라우저를 HTTP API 하나로 조종하게 해주는 서버"다. 개발자가 직접 쓰라고 만든 게 아니라, AI 에이전트(LLM)가 도구로 호출하도록 설계됐다. 에이전트가 POST /tabs로 탭을 열고, GET /snapshot으로 페이지의 "읽을 수 있는 요약"을 받고, POST /click으로 버튼을 누른다. 이 모든 게 사람 눈에는 평범한 Firefox 사용자로 보인다.

결과물은 단일 바이너리 CLI(npx @askjo/camofox-browser)이자, Docker 이미지이자, OpenClaw 플러그인이다. 실행하면 기본 9377 포트에서 REST 서버가 뜨고, OpenAPI 문서(/docs)까지 자동 생성된다.

2왜 주목받는가 — 봇 탐지 군비경쟁의 최전선

2025~2026년 "AI 에이전트가 웹을 쓴다"가 폭발하면서, 역설적으로 "에이전트가 웹에서 차단당한다"는 문제가 동시에 커졌다. camofox-browser가 뜨는 이유는 이 정확한 통증을 건드리기 때문이다.

① "스텔스 플러그인이 곧 지문이 된다"는 근본 문제를 다르게 푼다

기존 접근(예: puppeteer-extra-plugin-stealth)은 JavaScript로 탐지 신호를 덮어쓴다. 문제는 그 덮어쓰는 행위 자체가 새로운 신호가 된다는 것. 예를 들어 navigator.webdriver를 지우면, 지워졌다는 사실이 오히려 자동화의 증거가 된다. Camoufox는 이걸 C++ 소스 레벨에서 바꾼다 — JS가 값을 읽을 때는 이미 위조된 값이 "진짜 그 브라우저의 원래 값"처럼 존재한다. 덮어쓴 흔적(getter 함수 변조 등)이 남지 않는다.

② 에이전트가 실제로 쓰기 편하게 만들었다 (이게 진짜 차별점)

Camoufox 엔진 자체는 이 프로젝트의 것이 아니다("mighty shoulders of Camoufox"라고 README가 명시). camofox-browser의 독창성은 엔진을 LLM 에이전트용으로 감싼 방식에 있다:

• 접근성 스냅샷 — 페이지를 원시 HTML(수십만 자) 대신, 스크린리더가 읽는 것 같은 구조화된 YAML 목록으로 준다. README 기준 ~90% 작다. LLM은 토큰 예산이 한정돼 있어서, 이게 사실상 "쓸 수 있냐/없냐"를 가른다.
• 엘리먼트 ref — 각 요소에 e1, e2 같은 안정적 ID를 붙인다. 에이전트는 "복잡한 CSS 셀렉터"를 만들 필요 없이 click e5라고만 하면 된다.
• 검색 매크로 — @google_search, @youtube_search 등 14개 사이트의 검색 URL을 미리 만들어 둔다. 에이전트가 URL 구조를 몰라도 된다.

③ "$5 VPS·라즈베리파이에서도 돈다"는 운영 현실성

README가 반복 강조하는 포인트: 유휴 시 메모리 ~40MB. 브라우저를 요청이 올 때만 지연 실행(lazy launch)하고, 놀면 자동 종료(idle shutdown)한다. 에이전트 인프라는 24시간 떠 있어야 하는데, 브라우저는 무거우니까 "필요할 때만 깨우는" 전략이 비용을 좌우한다. 이 운영 감각이 별점 급상승의 실질 이유 중 하나다.

경쟁 구도 한눈에

3기술 스택 전체 지도

런타임 & 언어

Node.js ≥22 위에서 도는 순수 ESM(ECMAScript Module) 프로젝트다("type": "module"). 서버 본체는 JavaScript(server.js + lib/*.js)로 쓰였고, OpenClaw 플러그인 진입점만 TypeScript(plugin.ts)로 작성돼 빌드 시 dist/plugin.js로 컴파일된다.

백엔드 — 요청을 받는 층

• Express 4 — REST API 라우팅. /tabs, /snapshot, /click 같은 엔드포인트를 정의한다. 가장 검증된 Node 웹 프레임워크라 안정성을 택한 것.
• swagger-jsdoc — 코드 주석에서 OpenAPI 스펙을 자동 생성. /openapi.json과 /docs 대화형 문서가 여기서 나온다.
• prom-client — Prometheus 메트릭. 운영 관측성(observability)을 위해 요청 수·지연·메모리를 /metrics로 노출한다.

브라우저 제어 층 — 핵심

• camoufox-js 0.10.2 — Camoufox(위조된 Firefox) 바이너리를 내려받고 실행하는 Node 래퍼. 첫 실행 시 ~300MB를 다운로드한다. VirtualDisplay(가상 디스플레이) 헬퍼도 여기서 온다.
• playwright-core 1.58 — 실제 브라우저 조종은 Playwright의 firefox 드라이버로 한다. camoufox-js가 Playwright와 호환되는 브라우저를 띄우고, 서버는 Playwright API(page.click, page.accessibility, tracing 등)로 조작한다. "core"만 쓴다 — 즉 Playwright의 자체 브라우저 다운로드는 끄고, Camoufox 바이너리만 쓴다는 게 설치 스크립트의 핵심 트릭이다.

선택적 의존성 & 플러그인 층

• yt-dlp (외부 파이썬 도구) — YouTube 자막 추출의 빠른 경로. 없으면 브라우저 기반 느린 경로로 폴백. Docker 이미지에는 포함돼 있다.
• noVNC / Xvfb (vnc 플러그인) — 사람이 브라우저로 직접 로그인(예: 2FA)한 뒤 세션 상태를 에이전트에게 넘겨주는 "VNC 인터랙티브 로그인" 기능.
• Cloudflare Workers (workers/crash-reporter) — 익명화된 크래시 리포트를 GitHub 이슈로 모으는 서버리스 함수. TypeScript + wrangler.toml.

인프라 & 배포

• Docker — Makefile이 CPU 아키텍처(M1/M2의 aarch64, Intel의 x86_64)를 자동 감지해 바이너리를 빌드 밖에서 미리 받아둔다(재빌드 ~30초). Windows용 build.ps1 PowerShell 스크립트도 별도 제공.
• Fly.io / Railway — railway.toml과 Dockerfile.ci로 원격 CI에서 빌드 타임에 바이너리를 받는 별도 경로.
• Jest — 단위·E2E·플러그인·라이브 테스트로 나뉜 테스트 스위트. tests/ + 각 플러그인 옆 *.test.js.
• Sentry (선택) — 에러 추적. lib/sentry.js로 표현식만 감싸 넣어 미설정 시 무해하게 통과.

스택 요약표

4아키텍처 심화 — 스냅샷·ref·세션 격리

전체 시스템 구조도

핵심 설계 패턴 ① — 접근성 스냅샷 "윈도잉"

거대한 페이지(예: 무한 스크롤 피드)의 접근성 트리는 수십만 자가 될 수 있다. LLM에 통째로 넣으면 토큰이 폭발한다. lib/snapshot.js는 이걸 페이지네이션 가능한 창(window)으로 자른다. 실제 로직:

// lib/snapshot.js — 큰 스냅샷을 자르되, 꼬리(페이지네이션 링크)는 항상 보존
const MAX_SNAPSHOT_CHARS = 80000;  // 약 20K 토큰
const SNAPSHOT_TAIL_CHARS = 5000;  // 마지막 5K는 '다음 페이지' 링크용

function windowSnapshot(yaml, offset = 0) {
  const total = yaml.length;
  // 작으면 그대로 반환
  if (total <= MAX_SNAPSHOT_CHARS)
    return { text: yaml, truncated: false, ... };

  const tail  = yaml.slice(-SNAPSHOT_TAIL_CHARS);   // 꼬리 확보
  const chunk = yaml.slice(offset, offset + budget); // 본문 조각
  // "offset=NNNN 로 다시 부르면 더 보여줌" 마커 + 꼬리를 붙여 반환
  return { text: chunk + marker + tail, hasMore, nextOffset };
}

핵심 설계 패턴 ② — 사용자별 세션 격리

서버는 sessions라는 Map을 중심에 둔다. 구조는 Map<userId, { tabGroups: Map<sessionKey, Set<tab>>, cookies, storage }>. 즉 사용자(userId) → 세션(sessionKey) → 탭의 3단 계층이다. 에이전트 A와 에이전트 B가 같은 서버를 써도 쿠키·로그인 상태가 절대 섞이지 않는다. 멀티테넌트(여러 고객이 한 인스턴스 공유) 운영을 전제로 한 설계다.

핵심 설계 패턴 ③ — 방어적 복구 (production hardening)

lib/를 보면 "브라우저는 언제든 죽는다"는 전제로 짠 흔적이 가득하다. 이게 이 레포에서 가장 배울 게 많은 부분이다:

요청 한 건의 생애 (Google 검색 예시)

1. POST /tabs {userId, sessionKey, macro:"@google_search", query:"날씨"}
   └ auth.js: API 키/루프백 검사
   └ macros.js: @google_search → https://google.com/search?q=날씨
   └ 세션에 브라우저 없으면 지연 실행(lazy launch) → Camoufox 기동
   └ new-page-recovery: 컨텍스트 죽으면 재생성
   → { tabId, url, title }

2. GET /tabs/:id/snapshot?userId=...
   └ Playwright 접근성 트리 추출 → YAML 직렬화
   └ snapshot.js: 80K자 넘으면 윈도잉
   → { snapshot: "…e1 link 날씨…e5 heading…", refs }

3. POST /tabs/:id/click {ref:"e5"}
   └ ref → 실제 엘리먼트 핸들 매핑 → page.click()
   → { ok:true, newSnapshot? }

5디렉토리 구조 해부

구조에서 읽히는 설계 철학

• server.js는 얇고, lib는 두껍다 — 진입점은 30여 모듈을 import해 배선만 한다. 각 관심사(인증·프록시·스냅샷·복구)가 독립 파일이라 테스트·교체가 쉽다. 전형적인 "조립기(composition root)" 패턴.
• 플러그인은 옵션 — youtube·vnc·persistence는 plugins/로 분리돼, 없어도 코어가 돈다. 각 플러그인에 AGENTS.md(에이전트용 설명서)와 *.test.js가 함께 있다.
• 배포 경로가 이중화 — 로컬은 bind mount로 빠르게, CI는 빌드타임 fetch로. Dockerfile을 둘로 나눈 이유가 README에 명시돼 있다.
• reporter.js가 1,101줄로 가장 크다는 사실이 이 프로젝트의 성격을 말해준다 — 기능보다 안정성·관측성에 코드를 더 썼다.

6학습 포인트 — 기술별 배울 것

① 브라우저 핑거프린팅의 원리 (방어자 관점)

camofox-browser를 이해하려면 "애초에 어떻게 봇이 탐지되는가"를 알아야 한다. 이건 웹 보안·프라이버시의 핵심 주제다. 배울 것: navigator 속성, WebGL/Canvas 지문, AudioContext 지문, TLS/HTTP2 지문, 마우스 동선·타이핑 리듬 같은 행위 지문. Camoufox가 어떤 값들을 위조하는지 역추적하면, 반대로 탐지 시스템이 무엇을 보는지가 보인다.

② LLM 에이전트 도구 설계 (토큰 경제학)

이 레포의 진짜 교훈은 "브라우저 자동화"가 아니라 "LLM에게 세계를 어떻게 압축해서 보여줄 것인가"다. 접근성 스냅샷(HTML 대신), ref 시스템(셀렉터 대신), 윈도잉(무한 페이지 대신)은 모두 토큰 예산이라는 제약에서 나온 설계다. 자신만의 LLM 도구를 만들 때 그대로 응용할 수 있는 패턴이다.

③ 프로덕션급 Node 서버 하드닝

new-page-recovery, inflight, browser-errors, reporter의 워치독 — 이 조합은 "외부 프로세스(브라우저)에 의존하는 서버를 어떻게 죽지 않게 만드나"의 교과서다. 크래시 분류, 재시도 판정, 중복 요청 병합, 고아 프로세스 정리는 어떤 백엔드에서도 통용되는 기술이다.

④ 프록시 추상화 설계

lib/proxy.js(277줄)는 "provider 인터페이스"라는 깔끔한 추상을 보여준다. Decodo·BrightData·generic 같은 프록시 업체마다 다른 인증 방식·세션 회전 규칙을 공통 인터페이스 뒤로 숨긴다. 여러 외부 서비스를 갈아끼워야 하는 코드를 짤 때 참고할 만한 전략 패턴(Strategy Pattern)이다.

// lib/proxy.js — provider 추상화 (주석에 인터페이스가 문서화돼 있음)
{
  name:              'decodo',   // 업체 이름
  canRotateSessions: true,       // 세션별 회전 지원?
  buildSessionUsername(base, opts),  // country/city/session을 username에 인코딩
  buildProxyUrl(proxy, config),      // 최종 프록시 URL 조립
}

⑤ 배포 이식성 (Docker 아키텍처 감지)

Makefile이 uname -m으로 CPU를 감지해 aarch64/x86_64 바이너리를 나눠 받고, Docker 빌드 밖에서 미리 다운로드해 재빌드를 30초로 줄인 트릭은 실전 CI/CD 최적화의 좋은 예다.

7하드웨어 / 시스템 요구사항

README가 강조하는 배포 타깃은 라즈베리파이·$5 VPS·공유 인프라다. 즉 "전용 고사양 서버가 필요 없다"가 세일즈 포인트. 다만 동시에 많은 탭을 열면 Firefox 프로세스 메모리가 실제 병목이 된다 — 유휴 40MB는 "브라우저가 자고 있을 때" 이야기다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

1주차 — 브라우저 자동화 & 접근성 기초

• Playwright 공식 문서: 브라우저·컨텍스트·페이지 개념, page.accessibility.snapshot()과 ARIA 스냅샷
• 접근성 트리(Accessibility Tree)와 ARIA role — 크롬 DevTools의 Accessibility 패널로 실제 트리 관찰
• 실습: Playwright로 아무 사이트나 접근성 스냅샷을 뽑아 HTML과 크기 비교

2주차 — 봇 탐지 & 핑거프린팅 (보안/프라이버시)

• Canvas·WebGL·AudioContext 지문의 원리, navigator 신호들
• Camoufox·Camoufox의 상위 개념: Firefox 소스 패치가 왜 JS 패치보다 은밀한가
• 방어자 시각: Cloudflare Bot Management, reCAPTCHA v3의 행위 점수화가 무엇을 보는가
• 실습: 지문 테스트 사이트로 "탐지 신호 체크리스트" 작성

3주차 — LLM 에이전트 도구 설계

• MCP(Model Context Protocol)·OpenClaw 플러그인 구조: 도구를 어떻게 노출하나
• 토큰 경제학: 관찰(observation)을 압축하는 패턴(스냅샷·ref·윈도잉·구조화 추출)
• 에이전트 루프: 관찰 → 추론 → 행동 → 재관찰(ReAct 패턴)
• 실습: camofox-browser를 도구로 붙여 간단한 "웹 리서치 에이전트" 만들기

4주차 — 프로덕션 Node 서버 하드닝

• 외부 프로세스 관리: 지연 실행, 유휴 종료, 소유권 추적, 고아 정리
• 에러 분류·재시도·요청 병합(idempotency/coalescing), 워치독 패턴
• 관측성: Prometheus 메트릭, 구조화 로깅(request ID), 익명 크래시 리포트 윤리
• 실습: reporter.js를 읽고 워치독이 감지하는 이상 상황 5가지 정리

10핵심 키워드 사전

11참고 링크

• 이 레포 — github.com/jo-inc/camofox-browser (README·AGENTS.md·lib 소스가 학습의 출발점)
• npm 패키지 — @askjo/camofox-browser (npx @askjo/camofox-browser로 즉시 실행)
• Camoufox (엔진) — camoufox.com · 지문 위조 원리와 지원 항목
• Playwright — playwright.dev · 접근성 스냅샷·트레이싱 문서
• yt-dlp — github.com/yt-dlp/yt-dlp · YouTube 자막 추출
• 제작사 — askjo.ai · "jo" 개인 AI 에이전트 팀