jo-inc/camofox-browser

camofox‑browser – 為 AI 代理人的反檢測瀏覽器伺服器

是什麼 – 一個極小的 Node.js 伺服器，執行經過特殊修補的 Firefox 建構版本（Camoufox），並為 AI 代理人提供 REST API，使其能瀏覽真實網路而不被標記為機器人。瀏覽器的指紋在 C++ 層級被偽造，因此網站看到的是正常的 Firefox，而非無頭或被監控的瀏覽器。

對代理人的意義 – 現代網路爬取工具（Playwright、無頭 Chrome）正越來越多地被 Cloudflare、Google 等機器人檢測服務封鎖。camofox-browser 透過以下方式解決此問題：

• 在任何 JavaScript 執行前，偽造低階屬性（CPU 核心數、WebGL、AudioContext、螢幕尺寸、WebRTC 等）。
• 提供 可存取性快照（頁面的緊湊、螢幕閱讀器友善表示），其大小比原始 HTML 小約 90%，為 LLM 驅動的代理人節省 token 預算。
• 提供穩定的元素引用（e1, e2, …），使代理人能可靠地點擊或輸入，而無需脆弱的 CSS/XPath 選擇器。

主要功能（如 README 所述）

功能	作用
C++ 反檢測	透過在二進位層級修補 Firefox，繞過 Google、Cloudflare 及大多數機器人檢測器。
元素引用	回傳互動元素的穩定短 ID，使代理人的命令具有決定性。
高效 token 快照	發送可存取性樹而非完整 HTML，大幅減少資料封包大小。
低資源佔用	延遲啟動和空閒關閉使記憶體保持在約 40 MiB；可在廉價 VPS 或 Raspberry Pi 上執行。
會話隔離與持久化	每個使用者獨立的 cookie/儲存空間；可選持久化至 ~/.camofox/profiles/。
Cookie 導入	接受 Netscape 格式 cookie 檔案，使代理人可重複使用現有登入（如 LinkedIn、Amazon）。
檔案上傳	允許代理人從設定目錄上傳檔案，無需原生作業系統對話框。
代理 + GeoIP	透過住宅代理路由流量；自動將區域、時區和地理位置與代理 IP 對齊。
YouTube 字幕	透過 yt‑dlp 提取字幕（無需 API 金鑰）。
搜尋巨集	內建快速鍵如 @google_search、@youtube_search、@amazon_search 等。
快照截圖	與可存取性快照一同回傳 base64 編碼的 PNG。
大頁面處理	透過基於偏移的分頁截斷快照，保持回應可管理。
下載捕獲	捕獲瀏覽器下載的檔案，並透過 API 提供（可選內嵌 base64）。
DOM 圖像提取	列出 <img> 的來源/alt 文字，並可回傳 data-URL 版本。
隨處部署	支援 Docker、Fly.io、Railway 或直接 npm start。
VNC 互動式登入	NoVNC UI 允許人類視覺登入；產生的儲存狀態可被代理人重用。
OpenAPI 文件	在 /openapi.json 自動產生規格，在 /docs 提供互動式 Swagger UI。
結構化提取	向 /tabs/:tabId/extract 發送 JSON 模式，將欄位映射到快照引用（x‑ref）。
會話追蹤	可選的 Playwright 追蹤（截圖、DOM、網路）每會話提供，可下載為 zip。
遙測	匿名的當機/卡頓報告會發送至 Cloudflare Worker 並建立 GitHub 問題；可停用。

如何執行

1. 克隆並安裝

   git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
   npm install   # 首次執行時下載 Camoufox 二進位檔（約 300 MiB）
   npm start     # 伺服器監聽 http://localhost:9377
   

2. 可選 – Docker（生產環境推薦）

   make up            # 建構鏡像，下載二進位檔，啟動容器
   # 停止/移除
   make down
   

   Makefile 會自動偵測 CPU 架構（x86_64 或 aarch64），並預先下載 Camoufox + yt‑dlp，使建構快速。
3. 設定 – 多數行為由環境變數控制，例如：
   • CAMOFOX_API_KEY – 用於特權端點（Cookie 導入、VNC 登入）的密鑰。
   • PROXY_HOST, PROXY_PORT, PROXY_USERNAME, PROXY_PASSWORD – 啟用代理路由。
   • CAMOFOX_CRASH_REPORT_ENABLED=false – 禁用遙測。
   • CAMOFOX_EXECUTABLE – 若自行管理，可指向預先下載的 Camoufox 二進位檔。

典型代理工作流程

1. 建立標籤頁 – POST /tabs 傳入 {userId, sessionKey, url}，回傳 tabId。
2. 取得快照 – GET /tabs/:tabId/snapshot 回傳可存取性樹和 base64 PNG。
3. 互動 – 使用 POST /tabs/:tabId/click、.../type、.../scroll 等，透過穩定 ID（e1, e2）引用元素。
4. 提取結構化資料 – 定義 JSON 模式，將所需欄位映射到 x‑ref ID，POST 至 /tabs/:tabId/extract。
5. 關閉 – DELETE /tabs/:tabId（或關閉整個會話）釋放資源，並可選擇性儲存追蹤。

整合點

• OpenClaw 插件 – README 提到 openclaw 插件（@askjo/camofox-browser）將 HTTP 呼叫封裝為便捷的 CLI 命令（camofox_create_tab, camofox_click 等）。對已使用 OpenClaw 代理框架的開發者非常有用。
• 獨立 CLI – npx @askjo/camofox-browser 可在不克隆倉儲的情況下執行伺服器。
• OpenAPI – 生成的規格可用於生成任意語言的客戶端程式庫，便於嵌入自訂 LLM 協調器。

誰開發了它 – 此專案由 Jo 團隊維護，Jo 是一個部分運行在使用者 Mac 上、部分運行在雲端機器上的個人 AI 助手。同一團隊開發了 Camoufox，即底層的指紋偽造 Firefox 分支。

---

TL;DR

• camofox‑browser = 一個輕量級 REST 包裝器，用於指紋偽造的 Firefox（Camoufox）。
• 專為需要在不被阻止的情況下瀏覽開放網路的 AI 代理人設計。
• 提供小型結構化快照、穩定元素 ID、Cookie 導入、代理支援和可選追蹤。
• 使用 npm install && npm start 或透過 Docker/Make 安裝；透過環境變數設定。