jo-inc / camofox-browser

查看原文 / View Original 编辑 / Edit

jo-inc / camofox-browser

camofox-browser Anti-detection browser server for AI agents, powered by Camoufox camofox-browser：由 Camoufox 驱动的 AI 智能体反检测浏览器服务器

Standing on the mighty shoulders of Camoufox - a Firefox fork with fingerprint spoofing at the C++ level. Built by the team behind jo, a personal AI agent that runs half on your Mac, half on a dedicated cloud machine just for you — with zero maintenance needed. Available on macOS, Telegram, WhatsApp, and email. 它站在 Camoufox 的巨人之肩上——Camoufox 是一个在 C++ 层面进行指纹伪装的 Firefox 分支。该项目由 jo 团队开发，jo 是一个个人 AI 智能体，一半运行在你的 Mac 上，另一半运行在专属于你的云端机器上，无需任何维护。目前支持 macOS、Telegram、WhatsApp 和电子邮件。

Try the beta free -> 免费试用测试版 -> git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser npm install && npm start # -> http://localhost:9377

Why AI agents need to browse the real web. 为什么 AI 智能体需要浏览真实网页。

Playwright gets blocked. Headless Chrome gets fingerprinted. Stealth plugins become the fingerprint. Camoufox patches Firefox at the C++ implementation level - navigator.hardwareConcurrency, WebGL renderers, AudioContext, screen geometry, WebRTC - all spoofed before JavaScript ever sees them. No shims, no wrappers, no tells. This project wraps that engine in a REST API built for agents: accessibility snapshots instead of bloated HTML, stable element refs for clicking, and search macros for common sites. Playwright 会被拦截，Headless Chrome 会被识别出指纹，而隐身插件本身也成了指纹。Camoufox 在 C++ 实现层面修补了 Firefox——无论是 navigator.hardwareConcurrency、WebGL 渲染器、AudioContext、屏幕几何参数还是 WebRTC，都在 JavaScript 接触到它们之前就完成了伪装。没有垫片（shims），没有包装器，没有破绽。本项目将该引擎封装为专为智能体设计的 REST API：提供辅助功能快照（accessibility snapshots）而非臃肿的 HTML，提供用于点击的稳定元素引用（element refs），以及针对常用网站的搜索宏。

Features (功能特性)

  • C++ Anti-Detection - bypasses Google, Cloudflare, and most bot detection C++ 反检测 - 绕过 Google、Cloudflare 及大多数机器人检测。
  • Element Refs - stable e1, e2, e3 identifiers for reliable interaction 元素引用 - 提供稳定的 e1, e2, e3 标识符，实现可靠的交互。
  • Token-Efficient - accessibility snapshots are ~90% smaller than raw HTML Token 高效 - 辅助功能快照比原始 HTML 小约 90%。
  • Runs on Anything - lazy browser launch + idle shutdown keeps memory at ~40MB when idle. Designed to share a box with the rest of your stack — Raspberry Pi, $5 VPS, shared infra. 运行环境广泛 - 懒加载浏览器 + 空闲自动关闭，使空闲内存占用保持在约 40MB。专为与你的其他技术栈共存而设计——无论是树莓派、5 美元的 VPS 还是共享基础设施。
  • Session Isolation - separate cookies/storage per user 会话隔离 - 每个用户拥有独立的 Cookie/存储空间。
  • Cookie Import - inject Netscape-format cookie files for authenticated browsing Cookie 导入 - 注入 Netscape 格式的 Cookie 文件以进行已认证的浏览。
  • File Upload - attach files from a configured upload directory without a native OS dialog 文件上传 - 从配置的上传目录附加文件，无需原生操作系统对话框。
  • Proxy + GeoIP - route traffic through residential proxies with automatic locale/timezone 代理 + GeoIP - 通过住宅代理路由流量，并自动设置地区/时区。
  • Structured Logging - JSON log lines with request IDs for production observability 结构化日志 - 带有请求 ID 的 JSON 日志行，便于生产环境的可观测性。
  • YouTube Transcripts - extract captions from any YouTube video via yt-dlp, no API key needed YouTube 字幕提取 - 通过 yt-dlp 从任何 YouTube 视频提取字幕，无需 API 密钥。
  • Search Macros - @google_search, @youtube_search, @amazon_search, @reddit_subreddit, and 10 more 搜索宏 - 支持 @google_search, @youtube_search, @amazon_search, @reddit_subreddit 等 10 多种宏。
  • Snapshot Screenshots - include a base64 PNG screenshot alongside the accessibility snapshot 快照截图 - 在辅助功能快照中包含 base64 PNG 格式的截图。
  • Large Page Handling - automatic snapshot truncation with offset-based pagination 大页面处理 - 通过基于偏移量的分页实现自动快照截断。
  • Download Capture - capture browser downloads and fetch them via API (optional inline base64) 下载捕获 - 捕获浏览器下载内容并通过 API 获取（可选内联 base64）。
  • DOM Image Extraction - list src/alt and optionally return inline data URLs DOM 图像提取 - 列出 <img> 的 src/alt，并可选择返回内联数据 URL。
  • Deploy Anywhere - Docker, Fly.io, Railway 随处部署 - 支持 Docker, Fly.io, Railway。
  • VNC Interactive Login - log into sites visually via noVNC, export storage state for agent reuse VNC 交互式登录 - 通过 noVNC 可视化登录网站，并导出存储状态供智能体复用。
  • OpenAPI Docs - auto-generated spec at /openapi.json and interactive docs at /docs OpenAPI 文档 - 自动生成的规范位于 /openapi.json，交互式文档位于 /docs。
  • Structured Extract - POST /tabs/:tabId/extract with a JSON Schema that maps properties to snapshot refs via x-ref 结构化提取 - 通过 POST /tabs/:tabId/extract 使用 JSON Schema，将属性通过 x-ref 映射到快照引用。
  • Session Tracing - opt-in per-session Playwright trace capture (screenshots + DOM snapshots + network) with API endpoints to list, fetch, and delete trace zips 会话追踪 - 可选的按会话 Playwright 追踪捕获（截图 + DOM 快照 + 网络），并提供 API 端点来列出、获取和删除追踪压缩包。
  • Telemetry - automatic anonymized crash/hang telemetry via GitHub Issues. 遥测 - 通过 GitHub Issues 自动进行匿名崩溃/挂起遥测。

Optional Dependencies (可选依赖)

DependencyPurposeInstall
yt-dlpYouTube transcript extraction (fast path)pip install yt-dlp or brew install yt-dlp

The Docker image includes yt-dlp. For local dev, install it for the /youtube/transcript endpoint. Without it, the endpoint falls back to a slower browser-based method. Docker 镜像已包含 yt-dlp。对于本地开发，请安装它以支持 /youtube/transcript 端点。否则，该端点将回退到较慢的基于浏览器的方法。

Quick Start (快速开始)

OpenClaw Plugin OpenClaw 插件 openclaw plugins install @askjo/camofox-browser Tools: camofox_create_tab | camofox_snapshot | camofox_click | camofox_type | camofox_navigate | camofox_scroll | camofox_screenshot | camofox_close_tab | camofox_list_tabs | camofox_import_cookies

Standalone 独立运行 Run from npm: npx @askjo/camofox-browser Or from source: git clone https://github.com/jo-inc/camofox-browser cd camofox-browser npm install npm start # downloads Camofox on first run (~300MB) Default port is 9377. See Environment Variables for all options. 默认端口为 9377。查看环境变量以获取所有选项。

Docker

The included Makefile auto-detects your CPU architecture and pre-downloads Camoufox + yt-dlp binaries outside the Docker build, so rebuilds are fast (~30s vs ~3min). 随附的 Makefile 会自动检测你的 CPU 架构，并在 Docker 构建之外预先下载 Camoufox 和 yt-dlp 二进制文件，因此重新构建速度很快（约 30 秒 vs 约 3 分钟）。

  • make up # Build and start (auto-detects arch: aarch64 on M1/M2, x86_64 on Intel) make up # 构建并启动（自动检测架构：M1/M2 为 aarch64，Intel 为 x86_64）
  • make down # Stop and remove the container make down # 停止并移除容器
  • make reset # Force a clean rebuild (e.g. after upgrading VERSION/RELEASE) make reset # 强制进行干净的重新构建（例如在升级 VERSION/RELEASE 后）
  • make fetch # Just download binaries (without building) make fetch # 仅下载二进制文件（不构建）

Windows

On Windows, make is not available. Use the included build.ps1 PowerShell script instead: 在 Windows 上，无法使用 make。请改用随附的 build.ps1 PowerShell 脚本：

  • .\build.ps1 up # Build and start .\build.ps1 up # 构建并启动
  • .\build.ps1 down # Stop .\build.ps1 down # 停止
← 返回新闻列表 / Back to news list