camofox-browser

Camoufox 기반 anti-detection 브라우저를 에이전트용 REST/OpenClaw 도구로 감싼 서버

npx @askjo/camofox-browser

camofox-browser는 Camoufox 기반 stealth 브라우저를 에이전트용 REST API와 OpenClaw plugin으로 감싼 서버입니다. 접근성 snapshot, element ref, 세션 격리, proxy/GeoIP, Docker 배포를 제공합니다.

판단

이럴 때 씁니다

  • Playwright/Headless Chrome이 fingerprinting이나 bot detection에 자주 막히는 agent browsing 작업.
  • 에이전트에게 HTML 전체 대신 token-efficient accessibility snapshot과 element ref를 주고 싶을 때.
  • 인증 세션, proxy/GeoIP, VNC login, Docker 배포까지 포함한 독립 브라우저 서버가 필요할 때.
  • OpenClaw 기반 agent에 브라우저 도구 세트를 빠르게 붙이고 싶을 때.

이럴 땐 쓰지 마세요

  • 사용자의 실제 로컬 Chrome 프로필, 확장, 북마크, 세션을 그대로 써야 한다면 Browser Harness가 더 맞습니다.
  • 단순 E2E 테스트에는 Playwright 자체가 더 작고 표준적입니다.
  • 조직 정책상 stealth/anti-detection 브라우저 사용이 금지되어 있으면 도입하면 안 됩니다.
  • 대용량 binary download나 외부 브라우저 bundle 관리가 어려운 폐쇄망 환경에서는 준비가 필요합니다.

차별점

  • Camoufox가 Firefox C++ 구현 레벨에서 fingerprint surface를 spoof한다는 점을 전면에 둡니다. README는 JS shim 방식 stealth plugin과 차별화합니다.
  • HTML 덤프 대신 accessibility snapshot과 안정적인 element ref를 제공해 에이전트 토큰 사용량과 클릭 안정성을 줄이는 방향입니다.
  • OpenClaw plugin 도구 세트와 standalone REST 서버를 모두 제공합니다. `camofox_create_tab`, `camofox_snapshot`, `camofox_click` 같은 도구명이 명시돼 있습니다.
  • 세션 격리, cookie import, proxy/GeoIP, VNC login, OpenAPI docs, trace capture까지 운영형 브라우저 서버 기능을 넓게 포함합니다.

워크플로

  1. 01`npx @askjo/camofox-browser` 또는 소스 checkout의 `npm start`로 서버를 실행합니다.
  2. 02처음 실행에서 Camoufox binary 다운로드가 끝나는지 확인하고 기본 포트 9377의 `/docs` 또는 `/openapi.json`을 확인합니다.
  3. 03OpenClaw를 쓴다면 `openclaw plugins install @askjo/camofox-browser`로 도구 세트를 붙입니다.
  4. 04로그인 세션이 필요하면 `CAMOFOX_API_KEY`와 cookie directory를 설정한 뒤 cookie import flow를 분리해서 운영합니다.

주요 명령

명령설명
npx @askjo/camofox-browsernpm에서 standalone 서버를 실행합니다
openclaw plugins install @askjo/camofox-browserOpenClaw plugin으로 설치합니다
npm start소스 checkout에서 서버를 시작합니다. 첫 실행 때 Camoufox를 내려받습니다
make upDocker/Makefile 경로로 빌드와 실행을 시작합니다

설정

CAMOFOX_API_KEY=your-generated-key
CAMOFOX_COOKIES_DIR=$HOME/.camofox/cookies

함정

설치 전에 확인하세요

  • 첫 실행이나 npm install 시 Camoufox binary를 내려받습니다. README는 약 300MB 다운로드를 언급합니다.
  • `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`을 그대로 믿으면 안 됩니다. postinstall이 이 값을 정리해 Camoufox fetch를 수행합니다.
  • cookie import는 기본 비활성화이며 `CAMOFOX_API_KEY` 없이는 403으로 막힙니다.
  • Anti-detection은 웹사이트 약관·법적 리스크와 맞물립니다. 내부 테스트나 허가된 자동화 범위로 제한해야 합니다.

직접 써본 메모

camofox-browser는 브라우저 자동화 실패 원인을 정면으로 겨냥합니다. Playwright가 막히고 stealth plugin이 오히려 fingerprint가 되는 상황에서, Camoufox의 구현 레벨 spoofing을 에이전트 서버로 감싼다는 포지션이 선명합니다.

에이전트 관점에서는 accessibility snapshot과 element ref가 중요합니다. 브라우저 HTML을 통째로 던지는 방식보다 클릭 대상과 화면 상태를 작게 전달할 수 있고, OpenAPI와 plugin 도구명도 명시되어 있어 자동화 표면이 비교적 분명합니다.

다만 이 계열은 항상 운영 리스크가 큽니다. 사이트 약관, bot detection 회피 목적, proxy 사용 정책을 먼저 확인해야 하고, Camoufox binary 다운로드와 API key/cookie 보관도 관리 대상입니다. 일반 QA 자동화보다 권한과 격리를 더 엄격히 봐야 합니다.

비교

Browser Harness가 사용자의 실제 Chrome 또는 Browser Use cloud 브라우저에 얇은 CDP harness를 붙이는 방식이라면, camofox-browser는 Camoufox 기반 별도 stealth browser 서버를 띄우는 방식입니다. 실제 로그인된 내 브라우저를 에이전트에게 맡기려면 Browser Harness가 자연스럽고, bot detection이 강한 사이트를 별도 격리 브라우저로 다루려면 camofox-browser가 더 직접적입니다.

최근 변경

v1.13.0에서 중단된 브라우저 컨텍스트 복구, IndexedDB 유지, 세션 저장소 초기화, bind host 설정과 Docker 공유 메모리가 개선됐다.

공식 변경 내역