1. 项目定位与用途
camofox-browser 是基于 Camoufox 引擎构建的反检测浏览器自动化服务器，专为 AI 代理设计。它通过 REST API 提供浏览器自动化能力，使 AI 代理能够访问通常被阻止的网站。项目同时提供 OpenClaw 插件支持，可直接集成到 AI 代理工具链中。核心定位是解决 AI 自动化在真实网页环境中面临的指纹识别与访问阻断问题。
项目档案应用项目
jo-inc/camofox-browser 是什么？用途、安装与使用指南
jo-inc/camofox-browser：camofox-browser 是基于 Camoufox 引擎的反检测浏览器自动化服务器，专为 AI 代理设计，通过 C++ 级指纹伪装绕过网站本页整理它解决什么问题、适用场景、安装方式和使用方法。
AI 总结
camofox-browser 是基于 Camoufox 引擎的反检测浏览器自动化服务器，专为 AI 代理设计，通过 C++ 级指纹伪装绕过网站检测，提供 REST API 和 OpenClaw 插件支持，具有 token 效率高、内存占用低的特点。
中文项目介绍
camofox-browser 是一个面向 AI 代理的反检测浏览器自动化服务器，底层采用 Camoufox 引擎（Firefox 分支），在 C++ 实现层面进行指纹伪装，而非依赖 JavaScript shim，从而有效绕过 Google、Cloudflare 等平台的 bot 检测系统。
该项目将 Camoufox 封装为 REST API 服务，默认监听 9377 端口，为 AI 代理提供稳定的网页访问能力。核心特性包括：生成轻量的 accessibility 快照（比 HTML 小约 90%）、提供稳定的元素引用标识（e1/e2/e3）、支持会话隔离与 Cookie 导入、内置搜索宏系统、YouTube 视频转录提取（无需 API 密钥）等。
适用场景涵盖：AI 代理访问通常被阻止的网站、需要高稳定性的网页自动化任务、大规模数据采集、视频内容转录分析等。项目支持本地运行、Docker 容器化部署以及 OpenClaw 插件集成，可灵活适配不同基础设施环境。
详细信息与使用说明
2. 解决的问题
传统浏览器自动化方案（如 Playwright、headless Chrome）及 stealth 插件容易被现代网站检测并阻止。camofox-browser 通过 Camoufox 引擎在 C++ 层面修改浏览器实现，对 navigator.hardwareConcurrency、WebGL 渲染器、AudioContext、屏幕几何信息、WebRTC 等指纹特征进行底层伪装，使网站在 JavaScript 层面无法获取真实信息，从而绕过检测。这解决了 AI 代理在网页浏览任务中频繁被拦截的核心痛点。
3. 适用场景
主要适用于：AI 代理需要访问反爬虫严格的网站；需要稳定元素引用进行可靠交互的自动化任务；提取 YouTube 视频转录内容（无需 API 密钥）；使用内置搜索宏（@google_search、@youtube_search 等）高效导航；需要会话隔离和 Cookie 导入的认证浏览场景；通过代理和 GeoIP 路由流量以绕过地域限制；在资源受限环境（如 Raspberry Pi、$5 VPS）运行浏览器自动化。
4. 安装方式
标准安装：克隆仓库后执行 `npm install && npm start`，首次运行会自动下载 Camoufox 引擎（约 300MB）。Docker 安装：使用项目中的 Dockerfile 和 Makefile 构建镜像，支持多架构自动检测。OpenClaw 插件安装：执行 `openclaw plugins install @askjo/camofox-browser`。环境要求：Node.js >= 18。可选依赖：yt-dlp 用于加速 YouTube 转录提取（Docker 镜像已内置）。
5. 使用方式
启动后访问 http://localhost:9377 调用 REST API。主要端点包括：创建标签页、生成快照（返回 accessibility 树和截图）、点击元素、输入文本、导航、滚动、关闭标签页等。OpenClaw 插件提供工具：camofox_create_tab、camofox_snapshot、camofox_click、camofox_type、camofox_navigate、camofox_scroll、camofox_screenshot、camofox_close_tab、camofox_list_tabs、camofox_import_cookies。特殊功能端点：/youtube/transcript 提取视频转录，/search 使用内置宏。
6. 实现特点与补充说明
项目采用模块化架构，核心模块包括：launcher（浏览器生命周期管理）、snapshot（快照与截图生成）、macros（搜索宏系统）、youtube（转录提取）、cookies（Cookie 导入）、proxy（代理与 GeoIP）、downloads（下载捕获）、images（图像处理）。特点：lazy browser launch + idle shutdown 使空闲内存约 40MB；结构化 JSON 日志支持生产环境观测；自动处理大页面截断与分页；支持 Netscape 格式 Cookie 文件导入。仓库中未明确给出所有环境变量列表，需参考 README 相关章节。
思维导图
camofox-browser
核心特性
C++ 级反检测
元素引用系统（e1/e2/e3）
Token 效率优化（快照小 90%）
低内存占用（空闲 ~40MB）
会话隔离
技术架构
Camoufox 引擎（Firefox 分支）
Express REST API 服务器
OpenClaw 插件系统
模块化设计（lib/ 目录）
功能模块
launcher：浏览器生命周期
snapshot：快照与截图
macros：搜索宏（@google_search 等）
youtube：视频转录提取
cookies：Netscape 格式导入
proxy：代理与 GeoIP 路由
downloads：下载捕获
images：图像处理
部署方式
本地运行（npm start）
Docker 容器化
云平台（Fly.io/Railway）
OpenClaw 插件集成
使用场景
AI 代理网页浏览
反爬虫网站访问
稳定元素交互自动化
YouTube 内容转录
资源受限环境部署
常见问题
camofox-browser 与传统浏览器自动化工具（如 Playwright）有何区别？
主要区别在于反检测机制：camofox-browser 基于 Camoufox 引擎在 C++ 层面修改浏览器实现，对硬件并发数、WebGL、AudioContext、屏幕几何等指纹特征进行底层伪装，而非依赖 JavaScript shim 或插件。这使得它能够更有效地绕过现代网站的 bot 检测系统，而传统工具容易被识别和阻止。
如何安装和启动 camofox-browser？
标准安装方式：克隆仓库后执行 `npm install && npm start`，服务默认监听 http://localhost:9377。首次运行会自动下载 Camoufox 引擎（约 300MB）。也支持 Docker 部署（使用项目中的 Dockerfile）和 OpenClaw 插件安装（`openclaw plugins install @askjo/camofox-browser`）。环境要求：Node.js >= 18。
camofox-browser 支持哪些特殊功能？
主要特殊功能包括：稳定元素引用（e1/e2/e3 标识符）确保可靠交互；YouTube 视频转录提取（通过 yt-dlp，无需 API 密钥）；内置搜索宏系统（@google_search、@youtube_search、@amazon_search 等）；会话隔离与 Cookie 导入（支持 Netscape 格式）；代理与 GeoIP 路由；下载捕获；快照截图一体化；大页面自动截断分页。这些功能专为 AI 代理的浏览器自动化需求设计。
部署时需要注意哪些环境要求和依赖？
基础要求：Node.js >= 18 环境。首次运行需下载 Camoufox 引擎（约 300MB）。如需 YouTube 转录的快速路径，建议安装 yt-dlp（`pip install yt-dlp` 或 `brew install yt-dlp`），Docker 镜像已内置。项目设计为低内存占用（空闲约 40MB），适合 Raspberry Pi、低配 VPS 等资源受限环境。可通过环境变量（如 DEBUG_SERVER）配置服务器行为，具体选项需参考 README。
camofox-browser 如何保证元素引用的稳定性？
项目通过生成 accessibility 快照并分配稳定的元素引用标识（如 e1、e2、e3）来保证交互稳定性。这些引用基于 DOM 结构和可访问性信息生成，相比动态变化的 CSS 选择器或 XPath 更可靠。快照机制还提供 ~90% 的 token 效率提升，减少 LLM 处理负担，同时支持截图辅助验证，适合 AI 代理进行精确的网页操作。