Camofox Browser — антидетект-браузер для AI-агентов на базе Camoufox

Camofox Browser — антидетект-браузерный сервер для AI-агентов на базе Camoufox — Firefox-форка с подменой цифрового отпечатка на уровне C++. Проект от команды jo, MIT-лицензия, ~9.3k звёзд на GitHub.

Проблема простая: агентам нужно ходить в настоящий веб, но Playwright блокируют, headless Chrome вычисляют по отпечатку, а stealth-плагины сами становятся отпечатком. Camoufox патчит Firefox на уровне реализации на C++ — navigator.hardwareConcurrency, рендеры WebGL, AudioContext, геометрию экрана, WebRTC — всё подменяется до того, как JavaScript это увидит. Без шимов, без обёрток, без следов.

Проект оборачивает этот движок в REST API, заточенный под агентов: accessibility-снапшоты вместо раздутого HTML, стабильные element refs для кликов и поисковые макросы для популярных сайтов.

Возможности

• C++ антидетект — обходит Google, Cloudflare и большинство систем бот-детекции
• Element Refs — стабильные идентификаторы e1, e2, e3 для надёжного взаимодействия
• Токен-эффективность — accessibility-снапшоты примерно на 90% меньше сырого HTML
• Работает где угодно — ленивый запуск браузера и idle-выключение держат память на ~40MB в простое. Рассчитан на Raspberry Pi, VPS за $5 и общую инфраструктуру
• Изоляция сессий — отдельные cookies и хранилище на пользователя
• Импорт cookies — инъекция Netscape-файлов cookies для аутентифицированного браузинга
• Загрузка файлов — прикрепление файлов из настроенной директории без нативного OS-диалога
• Proxy + GeoIP — маршрутизация через резидентные прокси с автоматической локалью и таймзоной
• Структурные логи — JSON-строки с request ID для наблюдаемости в проде
• YouTube-транскрипты — субтитры любого видео через yt-dlp, без API-ключа
• Поисковые макросы — @google_search, @youtube_search, @amazon_search, @reddit_subreddit и ещё 10+
• Скриншоты снапшотов — base64 PNG вместе со снапшотом доступности
• Большие страницы — автоматическая обрезка снапшота с offset-пагинацией
• Захват загрузок — перехват скачиваний браузера и получение через API (опционально inline base64)
• Извлечение DOM-картинок — список <img> src/alt, опционально inline data URLs
• Деплой где угодно — Docker, Fly.io, Railway
• VNC-логин — визуальный вход в сайты через noVNC и экспорт storage state для переиспользования агентом
• OpenAPI-документация — автоспека на /openapi.json и интерактивная на /docs
• Structured Extract — POST /tabs/:tabId/extract с JSON Schema, мапящей свойства на snapshot refs через x-ref
• Сессионные трейсы — опциональный захват Playwright-трейсов (скриншоты + DOM-снапшоты + сеть) с эндпоинтами для листинга и скачивания
• Телеметрия — анонимизированный сбор падений и зависаний через GitHub Issues. Приватные домены HMAC-хэшируются, пути и параметры вырезаются, токены и IP редактируются. Отключается через CAMOFOX_CRASH_REPORT_ENABLED=false

Быстрый старт

Как плагин OpenClaw:

openclaw plugins install @askjo/camofox-browser

Инструменты: camofox_create_tab, camofox_snapshot, camofox_click, camofox_type, camofox_navigate, camofox_scroll, camofox_screenshot, camofox_close_tab, camofox_list_tabs, camofox_import_cookies.

Отдельно, из npm или исходников:

npx @askjo/camofox-browser

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start  # при первом запуске скачает Camoufox (~300MB)

Порт по умолчанию — 9377. Библиотека camoufox-js скачивает движок (~300MB) при npm install с официальных GitHub releases с проверкой целостности.

Базовый браузинг

# Создать вкладку
curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "sessionKey": "task1", "url": "https://example.com"}'

# Снапшот доступности с element refs
curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1"
# -> { S3: S4, ... }

# Клик по ref
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/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "macro": "@google_search", "query": "best coffee beans"}'

Импорт cookies

Чтобы пропустить интерактивный вход в LinkedIn, Amazon и т.п.:

openssl rand -hex 32  # сгенерировать ключ
export CAMOFOX_API_KEY="your-generated-key"

Экспортируйте cookies браузера в Netscape-формат (расширение «cookies.txt») и положите файл в директорию:

mkdir -p ~/.camofox/cookies
cp ~/Downloads/linkedin_cookies.txt ~/.camofox/cookies/linkedin.txt

Дальше просто попросите агента импортировать их — он вызовет camofox_import_cookies, сервер с Bearer-токеном валидирует и инжектит cookies в сессию.

Важные детали: импорт cookies отключён по умолчанию — без CAMOFOX_API_KEY сервер отвечает 403. Путь к файлу резолвится относительно директории cookies, выход за её пределы блокируется. Максимум 500 cookies за запрос, лимит файла 5MB.

Сессионная персистентность

По умолчанию camofox сохраняет cookies и localStorage каждого пользователя в ~/.camofox/profiles/. Сессии переживают перезапуск браузера — вошли один раз (cookies или VNC), и последующие сессии восстанавливают аутентифицированное состояние автоматически.

~/.camofox/
|-- cookies/          # Bootstrap cookie files (Netscape format)
\-- profiles/         # Persisted session state (auto-managed)
    \-- <hashed-userId>/
        \-- storage_state.json

По умолчанию хранятся только cookies и localStorage; для IndexedDB включите "indexedDB": true в конфиге persistence-плагина.

Сессионные трейсы

Опциональный захват Playwright-трейса каждой операции: скриншоты страницы, DOM-снапшоты, сетевые запросы и вывод консоли. Результат — .zip, который открывается во встроенном Trace Viewer Playwright:

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

curl -X DELETE http://localhost:9377/sessions/agent1   # закрыть сессию и сбросить трейс
curl http://localhost:9377/sessions/agent1/traces      # список трейсов

npx playwright show-trace session.zip                  # просмотр

Почему трейсы, а не видео: Camoufox на Firefox, а recordVideo в Playwright — Chromium-only. Трейсы работают на Firefox и дают больше, чем видео (сеть + DOM + консоль + скриншоты). По умолчанию хранятся 24 часа, максимум 50MB на трейс.

Прокси и GeoIP

Вся трафика идёт через прокси с автоматическим определением локали, таймзоны и геолокации по IP прокси через встроенный GeoIP Camoufox:

export PROXY_HOST=166.88.179.132
export PROXY_PORT=46040
export PROXY_USERNAME=myuser
export PROXY_PASSWORD=mypass
npm start

Для backconnect-провайдеров (Decodo, Bright Data, Oxylabs) с одним gateway-эндпоинтом и sticky-сессиями:

export PROXY_STRATEGY=backconnect
export PROXY_BACKCONNECT_HOST=gate.provider.com
export PROXY_BACKCONNECT_PORT=7000

Каждый browser context получает уникальную sticky-сессию — разные пользователи видят разные IP. Сессии ротируются автоматически при ошибках прокси или блокировках Google. Цифровой отпечаток (язык, таймзона, координаты) согласован с локацией прокси.

Архитектура

Browser Instance (Camoufox)
\-- User Session (BrowserContext) - isolated cookies/storage
    |-- Tab Group (sessionKey: "conv1")
    |   |-- Tab (google.com)
    |   \-- Tab (github.com)
    \-- Tab Group (sessionKey: "conv2")
        \-- Tab (amazon.com)

Сессии автоистекают через 30 минут бездействия. Браузер сам выключается через 5 минут без активных сессий и перезапускается по следующему запросу. При достижении лимита вкладок самая старая/наименее используемая вкладка автоматически переиспользуется вместо ошибки — длинные сессии агентов не упираются в тупик.

Безопасность

• Изоляция кода — все чтения process.env централизованы в lib/config.js, весь child_process — в lib/launcher.js. Ни один файл не совмещает доступ к креденшелам с сетевыми отправками
• Нет встроенных секретов — все ключи задаются через переменные окружения (CAMOFOX_API_KEY, CAMOFOX_ACCESS_KEY)
• Импорт cookies выключен по умолчанию — за забором CAMOFOX_API_KEY, с защитой от path traversal
• Доступ — CAMOFOX_ACCESS_KEY включает Bearer-аутентификацию для всех маршрутов (кроме /health). Рекомендуется для деплоя за пределами localhost
• Телеметрия аудируема — эндпоинт Cloudflare Worker отдаёт через GET /source хэш коммита и sha256 развёрнутого кода; можно сравнить с исходником в репозитории. Анонимизация параноидальная: приватные домены HMAC-хэшируются, пути превращаются в */*/*, значения параметров — в счётчики. Ни контент страниц, ни cookies, ни пользовательские данные не отправляются
• Subprocess — только два: движок Camoufox и опциональный yt-dlp для YouTube-транскриптов

Docker

Makefile сам определяет архитектуру CPU и предзагружает бинарники Camoufox и yt-dlp вне Docker-сборки, поэтому пересборки быстрые (~30с против ~3мин):

make up      # сборка и запуск (aarch64 на M1/M2, x86_64 на Intel)
make down    # остановка
make reset   # чистая пересборка
make fetch   # только скачать бинарники

На Windows вместо make используется build.ps1. Внимание: не запускайте docker build напрямую — Dockerfile использует bind mounts из dist/; всегда через make up.

Итог

Camofox Browser — это готовый слой «браузер для агента»: антидетект на уровне C++, токен-эффективные снапшоты, стабильные ссылки на элементы, поисковые макросы, персистентные сессии и аутентификация через cookies или VNC. Разворачивается на любом железе, от Raspberry Pi до облака, и отдаёт всё через один REST API с OpenAPI-спекой. Примечание из репозитория: «Camofox» — не криптопроект, и никакие токены с этим именем к нему отношения не имеют.