camofox-browser 是一個反偵測的無頭瀏覽器伺服器,核心是 Camoufox——一個在 C++ 層級偽裝指紋的 Firefox fork。它把這顆引擎包成 REST API,作為 Puppeteer/Playwright 的替代品:回傳精簡的 accessibility snapshot 而非臃腫 HTML、用穩定的 element ref 點擊、內建常見網站的搜尋巨集,目標是讓代理繞過 Cloudflare 與機器人偵測。本手冊依官方 README 整理安裝、能力、OpenClaw 外掛工具、實作範例與邊界。
camofox-browser 解決一個具體問題:AI 代理需要瀏覽真實網路,但 Playwright 會被擋、headless Chrome 會被指紋辨識、stealth 外掛本身又成了新的指紋。它的答案是換引擎——底層用 Camoufox,一個在 C++ 實作層偽裝指紋的 Firefox fork。navigator.hardwareConcurrency、WebGL renderer、AudioContext、螢幕幾何、WebRTC 都在 JavaScript 看到之前就被改掉,沒有 shim、沒有 wrapper、沒有破綻。
這個專案把那顆引擎包成一套為代理設計的 REST API。它不回傳整頁 HTML,而是回傳 accessibility snapshot——體積約比原始 HTML 小 90%,對 token 友善;頁面元素以穩定的 e1、e2、e3 ref 標記,代理據此點擊與輸入;並內建 @google_search 等搜尋巨集處理常見網站。定位是 Puppeteer/Playwright 的 drop-in 替代品。
它由 AI 代理產品「jo」團隊維護,以 MIT 授權釋出,目前約 6.4k stars、638 forks,主要語言 JavaScript。設計上強調輕量:lazy 啟動加上閒置自動關閉,閒置時記憶體約 40MB,可與其他服務共用一台 Raspberry Pi 或 5 美元 VPS。
最快是直接用 npx 跑起來;要改原始碼就 clone。第一次啟動會下載 Camoufox 二進位檔(約 300MB),之後啟動就快。伺服器預設聽 9377 埠。
若你的代理用 OpenClaw,直接裝外掛即可,它會註冊一組 camofox_* 工具(見第 04 節)。
內附的 Makefile 會自動偵測 CPU 架構(M1/M2 為 aarch64、Intel 為 x86_64),並在 build 之外預先下載 Camoufox 與 yt-dlp 二進位檔,讓重建快很多(約 30 秒 vs 約 3 分鐘)。
docker build。Dockerfile 用 bind mount 從 dist/ 取預先下載好的二進位檔,直接 build 會失敗。一律用 make up(或先 make fetch 再 make build)。要部署到 Fly.io / Railway 等遠端 CI,改用會在 build 階段下載二進位的 Dockerfile.ci;repo 已附 railway.toml,會把 Railway 的 PORT 對應到 CAMOFOX_PORT。
以下依用途分組,整理 README 列出的核心能力。左區是讓代理「不被擋、看得懂、點得到」的瀏覽基礎;中區是登入與代理路由;右區是資料擷取與可觀測性。每一項都對應 README 中已記載的功能。
recordVideo 只支援 Chromium。因此除錯改用 trace——它在 Firefox 上可用,且比影片多了網路、DOM 與 console。完整端點規格見 /openapi.json 與互動式文件 /docs。
裝成 OpenClaw 外掛後,代理會拿到一組 camofox_* 工具;下面同時整理幾個 README 記載、上線前值得先設好的設定。每條都對應一段官方文件。
外掛註冊:create_tab、snapshot、click、type、navigate、scroll、screenshot、close_tab、list_tabs、import_cookies。對應開分頁、取快照、點擊、輸入、導覽、捲動、截圖、關分頁、列分頁與匯入 cookie。
cookie 匯入預設關閉;沒設 CAMOFOX_API_KEY 時伺服器一律回 403。用 openssl rand -hex 32 產生金鑰,放進 shell profile 或環境變數,別寫進 plaintext 的 openclaw.json。
把 Netscape 格式 cookie 檔放到 ~/.camofox/cookies/,再對代理說「import my LinkedIn cookies from linkedin.txt」。每次請求上限 500 條 cookie、5MB,且阻擋目錄外的 path traversal。
Decodo、Bright Data、Oxylabs 這類單一 gateway、session 黏性的供應商,設 PROXY_STRATEGY=backconnect。每個瀏覽器 context 拿到獨立黏性 session,不同使用者得到不同 IP,遇錯或被 Google 擋會自動輪換。
已有 Camoufox bundle 時,設 CAMOUFOX_EXECUTABLE=/path/to/camoufox-bin 跳過內建下載(適用 NixOS 路徑)。否則用 npm install --omit=optional 再手動 npx camoufox-js fetch 對你的 mirror 抓。
camofox 預設把每位使用者的 cookies 與 localStorage 存到 ~/.camofox/profiles/,重啟後自動還原。要換目錄設 CAMOFOX_PROFILE_DIR;要關閉就在 camofox.config.json 設 persistence.enabled=false。
開 tab 時帶 trace: true,session 關閉時寫出 .zip。用 npx playwright show-trace session.zip 開啟,可看截圖、DOM、網路與 console。trace 不能在既有 session 上切換,要先 DELETE /sessions/:userId。
/youtube/transcript 端點優先走 yt-dlp 快路徑(pip install yt-dlp 或 brew install yt-dlp)。Docker 映像已內含;本機沒裝則退回較慢的瀏覽器方法,功能仍在。
以下用 curl 直接打 REST API,走一輪最常見的流程:啟動伺服器 → 開一個帶 session 的分頁 → 取 snapshot 拿到 element ref → 用結構化 extract 抽資料。端點與參數取自 README;回應為示意。
差別不在「能不能打開網頁」,而在回給代理的東西:精簡到適合放進 prompt 的 snapshot、用 e1/e2 取代易碎的 selector、以及用 JSON Schema 一次抽成結構化資料。要做已驗證瀏覽,先用第 04 節的 cookie 匯入或 VNC 登入,之後 create_tab 就是登入狀態。
docker build。Dockerfile 用 bind mount 從 dist/ 取預先下載好的二進位檔,直接 build 會失敗。用 make up(或 make fetch 後 make build);遠端 CI 改用 Dockerfile.ci。
npm start 第一次會抓 Camoufox 二進位檔。air-gapped 環境改設 CAMOUFOX_EXECUTABLE 指向既有 bundle,或用 --ignore-scripts / --omit=optional 手動處理。
CAMOFOX_API_KEY 時,所有 cookie 請求回 403。金鑰是機密:放環境變數,別寫進 plaintext 的 openclaw.json。
CAMOFOX_CRASH_REPORT_ENABLED=false。
~/.camofox/profiles/,重啟後自動還原登入。這台機器等同握有那些網站的登入態,務必做磁碟加密與存取控制。
/openapi.json 與 /docs,不要只依賴本手冊的示意。
curl 跑通之後,把它正式接進你的代理。以下依序推進。
1. 讀 OpenAPI 規格。所有端點與參數在 /openapi.json,互動式文件在 /docs。要接哪個動作,先在這裡核對欄位,而非照抄示意。
2. 接成代理工具。用 OpenClaw 就裝外掛拿 camofox_* 工具;其他框架則照 OpenAPI 把端點包成 tool/function call。
3. 處理登入。需要帳號的網站,先用 cookie 匯入或 VNC 登入建立 session,storage 會持久化,之後免再登入。
4. 上代理路由。規模化抓取時設住宅代理;會被 Google 擋的場景用 backconnect 黏性 session 自動輪換 IP。
5. 部署。選 Docker、Fly.io 或 Railway。記得設 CAMOFOX_API_KEY 等機密,並依需要關閉遙測。
① github.com/jo-inc/camofox-browser——原始碼、README 與 issue 追蹤。
② camoufox.com——底層引擎 Camoufox(C++ 層級指紋偽裝的 Firefox fork)。
③ http://localhost:9377/openapi.json 與 /docs——啟動後即可取得的完整 API 規格。