使用手冊

反偵測無頭瀏覽器 · REST API · for AI Agents

讓 AI 代理真的瀏覽得了真實網路。

camofox-browser 是建構在 Camoufox(Firefox fork,C++ 層級指紋偽裝)之上的反偵測無頭瀏覽器伺服器,以 REST API 取代 Puppeteer/Playwright,讓 AI 代理繞過 Cloudflare 與機器人偵測。本手冊整理安裝、API 能力、OpenClaw 外掛工具、實作範例與注意事項。MIT 授權,6.4k stars。依官方 README 整理。

camofox-browser 是一個反偵測的無頭瀏覽器伺服器,核心是 Camoufox——一個在 C++ 層級偽裝指紋的 Firefox fork。它把這顆引擎包成 REST API,作為 Puppeteer/Playwright 的替代品:回傳精簡的 accessibility snapshot 而非臃腫 HTML、用穩定的 element ref 點擊、內建常見網站的搜尋巨集,目標是讓代理繞過 Cloudflare 與機器人偵測。本手冊依官方 README 整理安裝、能力、OpenClaw 外掛工具、實作範例與邊界。

jo-inc/camofox-browser
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
10 分
更新日期
開啟原始報告
GitHub Stars
6.4k
snapshot 比 HTML 更小
~90%
預設埠
9377
開源授權
MIT
本頁章節

01這到底是什麼

一台反偵測的無頭瀏覽器伺服器。

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。

  1. 開 tab

  2. 取 snapshot

  3. 用 ref 點擊/輸入

  4. 擷取結果

  5. 關 session

Playwright gets blocked. Headless Chrome gets fingerprinted. Stealth plugins become the fingerprint.

— camofox-browser README · 為什麼要換引擎

02安裝

三條安裝路徑: npx、原始碼、或 Docker。

最快是直接用 npx 跑起來;要改原始碼就 clone。第一次啟動會下載 Camoufox 二進位檔(約 300MB),之後啟動就快。伺服器預設聽 9377 埠。

bash
# 直接用 npx 啟動(不需 clone)
npx @askjo/camofox-browser

# 或從原始碼;npm start 首次會下載 Camoufox(約 300MB)
git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start                  # -> http://localhost:9377

當成 OpenClaw 外掛

若你的代理用 OpenClaw,直接裝外掛即可,它會註冊一組 camofox_* 工具(見第 04 節)。

bash
openclaw plugins install @askjo/camofox-browser

Docker

內附的 Makefile 會自動偵測 CPU 架構(M1/M2 為 aarch64、Intel 為 x86_64),並在 build 之外預先下載 Camoufox 與 yt-dlp 二進位檔,讓重建快很多(約 30 秒 vs 約 3 分鐘)。

bash
make up                    # 自動偵測架構、build 並啟動
make down                  # 停止並移除容器
make reset                 # 升級版本後強制重建
make fetch                 # 只下載二進位檔

03能力總覽

API 提供的每一項能力。

以下依用途分組,整理 README 列出的核心能力。左區是讓代理「不被擋、看得懂、點得到」的瀏覽基礎;中區是登入與代理路由;右區是資料擷取與可觀測性。每一項都對應 README 中已記載的功能。

隱匿 · 01

C++ Anti-Detection

繞過偵測

在 C++ 實作層偽裝指紋,JavaScript 看到前就改好。README 稱可繞過 Google、Cloudflare 與多數機器人偵測。

互動 · 02

Element Refs

穩定指標

頁面元素以 e1、e2、e3 標記,代理據此點擊與輸入,比 CSS selector 更耐頁面變動。

互動 · 03

A11y Snapshot

精簡快照

回傳 accessibility snapshot 而非整頁 HTML,體積約小 90%。大頁面自動截斷,以 offset 分頁取後續內容。

隱匿 · 04

Search Macros

搜尋巨集

內建 @google_search、@youtube_search、@amazon_search、@reddit_subreddit 等共 14 個常見網站巨集。

登入 · 05

Session Isolation

隔離session

每位使用者的 cookies/storage 各自獨立,並持久化到 ~/.camofox/profiles,瀏覽器重啟後自動還原登入狀態。

登入 · 06

Cookie Import

注入cookie

匯入 Netscape 格式 cookie 檔做已驗證瀏覽,跳過 LinkedIn、Amazon 等網站的互動式登入。需設 API key。

登入 · 07

VNC Login

視覺登入

透過 noVNC 以肉眼登入網站,再匯出 storage state 供代理重用。處理需手動驗證的登入流程。

路由 · 08

Proxy + GeoIP

代理路由

經住宅代理出口,Camoufox GeoIP 自動依出口 IP 設定 locale、timezone 與座標。支援 backconnect 黏性 session。

擷取 · 09

Structured Extract

結構化擷取

POST /tabs/:tabId/extract 帶一份 JSON Schema,以 x-ref 把屬性對應到 snapshot 的 ref,直接抽成結構化資料。

擷取 · 10

YouTube Transcript

抽字幕

經 yt-dlp 抽取任意 YouTube 影片字幕,免 API key。Docker 映像已內含 yt-dlp;本機缺它則退回較慢的瀏覽器路徑。

擷取 · 11

Screenshot

擷圖

在 snapshot 之外一併回傳 base64 PNG 截圖。另可列出頁面 <img> 的 src/alt,並選擇回傳 inline data URL。

觀測 · 12

Session Tracing

追蹤除錯

每個 session 可選開 Playwright trace(截圖+DOM+網路+console),輸出單一 .zip,用 Trace Viewer 開啟。

04工具與實用設定 · 依 README

代理會用到的工具與常見設定。

裝成 OpenClaw 外掛後,代理會拿到一組 camofox_* 工具;下面同時整理幾個 README 記載、上線前值得先設好的設定。每條都對應一段官方文件。

工具集 · 10 個 camofox_* 工具

外掛註冊:create_tab、snapshot、click、type、navigate、scroll、screenshot、close_tab、list_tabs、import_cookies。對應開分頁、取快照、點擊、輸入、導覽、捲動、截圖、關分頁、列分頁與匯入 cookie。

README · Quick Start · OpenClaw Plugin

要匯入 cookie,先設 API key

cookie 匯入預設關閉;沒設 CAMOFOX_API_KEY 時伺服器一律回 403。用 openssl rand -hex 32 產生金鑰,放進 shell profile 或環境變數,別寫進 plaintext 的 openclaw.json。

README · Usage · Cookie Import

已驗證瀏覽:放 cookie 檔再叫代理匯入

把 Netscape 格式 cookie 檔放到 ~/.camofox/cookies/,再對代理說「import my LinkedIn cookies from linkedin.txt」。每次請求上限 500 條 cookie、5MB,且阻擋目錄外的 path traversal。

README · Cookie Import · How it works

輪換 IP 用 backconnect 黏性 session

Decodo、Bright Data、Oxylabs 這類單一 gateway、session 黏性的供應商,設 PROXY_STRATEGY=backconnect。每個瀏覽器 context 拿到獨立黏性 session,不同使用者得到不同 IP,遇錯或被 Google 擋會自動輪換。

README · Proxy + GeoIP · Backconnect

air-gapped:用外部 Camoufox 執行檔

已有 Camoufox bundle 時,設 CAMOUFOX_EXECUTABLE=/path/to/camoufox-bin 跳過內建下載(適用 NixOS 路徑)。否則用 npm install --omit=optional 再手動 npx camoufox-js fetch 對你的 mirror 抓。

README · Standalone · External executable

session 預設持久化,登入一次即可

camofox 預設把每位使用者的 cookies 與 localStorage 存到 ~/.camofox/profiles/,重啟後自動還原。要換目錄設 CAMOFOX_PROFILE_DIR;要關閉就在 camofox.config.json 設 persistence.enabled=false。

README · Session Persistence

除錯:開 trace,用 Trace Viewer 看

開 tab 時帶 trace: true,session 關閉時寫出 .zip。用 npx playwright show-trace session.zip 開啟,可看截圖、DOM、網路與 console。trace 不能在既有 session 上切換,要先 DELETE /sessions/:userId。

README · Session Tracing

缺 yt-dlp 仍可抽字幕,只是較慢

/youtube/transcript 端點優先走 yt-dlp 快路徑(pip install yt-dlp 或 brew install yt-dlp)。Docker 映像已內含;本機沒裝則退回較慢的瀏覽器方法,功能仍在。

README · Optional Dependencies

05實作範例

開分頁、取快照、用 ref 點下去。

以下用 curl 直接打 REST API,走一輪最常見的流程:啟動伺服器 → 開一個帶 session 的分頁 → 取 snapshot 拿到 element ref → 用結構化 extract 抽資料。端點與參數取自 README;回應為示意。

camofox · localhost:9377


# 啟動伺服器(首次會下載 Camoufox 約 300MB)
$ npx @askjo/camofox-browser
  ok: ✓ listening on http://localhost:9377


# 開一個帶 userId / sessionKey 的分頁
$ curl -X POST http://localhost:9377/tabs \
    > -H 'Content-Type: application/json' \
    > -d '{"userId":"agent1","sessionKey":"task1","url":"https://example.com"}'


  { "tabId": "t_8f2a", "title": "Example Domain",
    "snapshot": [
      { "ref": "e1", "role": "heading", "name": "Example Domain" },
      { "ref": "e2", "role": "link", "name": "More information..." } ] }
  # snapshot 比整頁 HTML 小約 90%,元素帶穩定 ref


# 用 ref 點擊(代理只需引用 e2,不必寫 selector)
$ curl -X POST http://localhost:9377/tabs/t_8f2a/click \
    > -H 'Content-Type: application/json' -d '{"ref":"e2"}'
  ok: ✓ navigated · 回傳新頁 snapshot


# 結構化擷取:JSON Schema 以 x-ref 對應到 snapshot
$ curl -X POST http://localhost:9377/tabs/t_8f2a/extract \
    > -H 'Content-Type: application/json' \
    > -d '{"schema":{"type":"object","properties":{
          > "title":{"type":"string","x-ref":"e1"}}}}'
  ok: ✓ { "title": "Example Domain" }


# 收尾:關 session(若開了 trace,此時寫出 .zip)
$ curl -X DELETE http://localhost:9377/sessions/agent1
ok: ✓ session closed

accessibility snapshots instead of bloated HTML, stable element refs for clicking, and search macros for common sites.

— camofox-browser README · 為代理設計的 API

這段流程的重點

差別不在「能不能打開網頁」,而在回給代理的東西:精簡到適合放進 prompt 的 snapshot、用 e1/e2 取代易碎的 selector、以及用 JSON Schema 一次抽成結構化資料。要做已驗證瀏覽,先用第 04 節的 cookie 匯入或 VNC 登入,之後 create_tab 就是登入狀態。

06先看清楚這些

上線前, 知道這些邊界。

07下一步

從 demo 到正式接上代理。

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 規格。

A REST API built for agents: accessibility snapshots, stable element refs, and search macros.

— camofox-browser README