jo-inc/camofox-browser 詳細教學

對 jo-inc/camofox-browser 從「定位」→「跑起來」→「整合進 AI agent」的完整 onboarding。 補充 inbox/2026-05-23-github-jo-inc-camofox-browser.md（gh-save metadata），請搭配閱讀。

1. 專案定位

camofox-browser 是 Jo Inc（推出 personal AI agent askjo.ai 的團隊）開源的 stealth headless browser (反偵測無頭瀏覽器) REST API server，目標是讓 AI agent 能像真人一樣瀏覽 web，不被 Cloudflare / Google / bot detection 擋下。

核心理念

• Playwright 會被擋；headless Chrome 會被指紋識別；stealth plugin 反而成為 fingerprint — 套常見頭痛
• 上游 Camoufox 採用「在 C++ 層級對 Firefox 做 fingerprint 偽裝」的設計：navigator.hardwareConcurrency、WebGL renderer、AudioContext、screen geometry、WebRTC 全在 JS 看到前就被替換 — 沒有 shim、wrapper、tell
• 本專案在 Camoufox 之上加上：REST API server、AI-friendly 介面（accessibility snapshot + element refs e1 e2 e3）、session 隔離、cookie import、proxy + GeoIP、VNC 互動登入、search macros、OpenAPI docs

對比表

適用場景

• AI agent 跨網站自動瀏覽（包含 Cloudflare / 強保護站點）
• LLM 上下文「我要看這個網頁」→ snapshot + refs → action
• 跨站 cookie / session persistence（一次登入，多次重用）
• 中型 scraping pipeline（多 session 隔離 + proxy 輪換）
• YouTube 字幕擷取（內建 yt-dlp 整合）
• 部署到輕量機器（Raspberry Pi / $5 VPS）

不適用場景

• 對 Chrome DevTools Protocol 深度依賴的應用（本專案是 Firefox base）
• 需要 video recording（Playwright recordVideo 是 Chromium-only；本專案用 trace 取代）
• 完全 client-side rendering 且需要 JS 模擬瀏覽器物件深層 hook 的特殊測試

2. 安裝指南

2.1 環境需求

2.2 三種安裝方式

A. NPM standalone（最快）

1git clone https://github.com/jo-inc/camofox-browser
2cd camofox-browser
3npm install      # 自動下載 Camoufox 二進位 ~300MB
4npm start        # 預設 http://localhost:9377

重要：postinstall script 會主動 unset PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD，避免你已有 Playwright 設定造成 Camoufox 沒下載。

B. OpenClaw plugin

1openclaw plugins install @askjo/camofox-browser
2export CAMOFOX_API_KEY="$(openssl rand -hex 32)"
3openclaw start

提供 10+ tool 給 OpenClaw agent 用：camofox_create_tab / camofox_snapshot / camofox_click / camofox_type / camofox_navigate / camofox_scroll / camofox_screenshot / camofox_close_tab / camofox_list_tabs / camofox_import_cookies。

C. Docker / Cloud（production）

 1# Docker 本機
 2make up              # 自動偵測 arch、下載 binary、build 並起 container
 3make down
 4
 5# Fly.io
 6fly secrets set CAMOFOX_API_KEY="$(openssl rand -hex 32)"
 7fly deploy
 8
 9# Railway
10railway link
11railway variables set CAMOFOX_API_KEY="$(openssl rand -hex 32)"
12railway up

⚠️ 不要直接 docker build — 用 make up（用 bind mount 取 dist/ 內預下載的 binary，rebuild ~30 s vs ~3 min）。

2.3 air-gapped / 自管 binary

1# 用既有 Camoufox bundle
2export CAMOUFOX_EXECUTABLE=/nix/store/.../camoufox-bin
3npm install --ignore-scripts  # 跳過 postinstall
4npm start

bundle 須含 properties.json / version.json / fontconfig/。

2.4 Optional dep

裝法：pip install yt-dlp 或 brew install yt-dlp（Docker image 已含）

2.5 Mermaid：安裝流程

flowchart TD
    Start([git clone camofox-browser]) --> Pick{部署目標?}
    Pick -->|本機 / dev| NpmInstall[npm install
+ 自動下載 Camoufox 300MB]
    Pick -->|Docker / production| Make[make up
auto-detect arch]
    Pick -->|OpenClaw agent| Oc[openclaw plugins install]
    Pick -->|air-gapped| Air[export CAMOUFOX_EXECUTABLE
npm install --ignore-scripts]

    NpmInstall --> StartServer[npm start
:9377]
    Make --> StartServer
    Oc --> SetKey[export CAMOFOX_API_KEY
= openssl rand -hex 32]
    SetKey --> StartServer
    Air --> StartServer

    StartServer --> Check[curl :9377/health]
    Check --> Done([OK！可用 REST API])

3. 核心架構解析

3.1 Repo 結構

 1camofox-browser/
 2├── server.js                  # 單檔 Express server（~212 KB / 5,800+ 行 / 35+ endpoint）
 3├── lib/                       # 核心工具模組
 4│   ├── auth.js               # Bearer token + access key middleware
 5│   ├── launcher.js           # 包裝 child_process spawn Camoufox 子進程
 6│   ├── camoufox-executable.js # binary 解析（含 air-gapped path）
 7│   ├── snapshot.js           # accessibility snapshot 生成 + element refs
 8│   ├── extract.js            # 結構化 JSON Schema → ref-based extraction
 9│   ├── macros.js             # @google_search / @youtube_search 等
10│   ├── cookies.js            # Netscape format parser + sanitization
11│   ├── proxy.js              # residential proxy + GeoIP
12│   ├── persistence.js        # storage_state.json 持久化
13│   ├── tracing.js            # Playwright trace zip 管理
14│   ├── downloads.js          # 下載 capture
15│   ├── images.js             # DOM image 列舉
16│   ├── openapi.js            # /openapi.json + /docs 路由
17│   ├── metrics.js            # /metrics（prometheus 風格）
18│   ├── inflight.js           # 並發控制
19│   ├── tmp-cleanup.js        # /tmp/playwright-* 清理
20│   └── reporter.js           # JSON 結構化 logging（含 request ID）
21├── plugins/
22│   ├── persistence/          # 預設啟用：每 user storage_state 持久化
23│   ├── vnc/                  # 互動式登入（noVNC + 內建 spawn）
24│   └── youtube/              # yt-dlp 整合
25├── workers/
26│   └── crash-reporter/       # crash 報告 worker
27├── scripts/
28│   ├── postinstall.js        # 安裝完自動 fetch Camoufox binary
29│   ├── generate-openapi.js   # 從程式碼生 openapi.json
30│   ├── exec.js               # child_process re-export（隔離設計）
31│   ├── plugin.js / .test.js  # plugin runtime + 測試
32│   └── sync-version.js       # version 跨檔同步
33├── plugin.ts / plugin.js     # OpenClaw plugin 入口
34├── camofox.config.json       # 預設設定
35├── openclaw.plugin.json      # OpenClaw manifest（11 KB）
36├── openapi.json              # 自動生成的 OpenAPI 3.0 spec（76 KB）
37├── Dockerfile / Dockerfile.ci
38├── Makefile                  # 跨 arch 自動偵測
39├── railway.toml
40└── tests/{unit,e2e,live}/    # Jest + e2e + live web tests

3.2 系統架構圖

flowchart LR
    subgraph Client["AI Agent / Client"]
        Agent[LLM Agent
e.g. Claude / GPT]
        Cli[REST client
curl / fetch]
    end

    subgraph Server["camofox-browser server (Node 22, :9377)"]
        Express[Express app
server.js 5800+ 行]
        Auth[auth.js
Bearer + access key]
        Snap[snapshot.js
accessibility tree
+ element refs e1/e2/e3]
        Macro[macros.js
@google_search
@youtube_search ...]
        Persist[persistence.js
storage_state.json]
        Proxy[proxy.js + GeoIP]
        Trace[tracing.js
Playwright trace.zip]
    end

    subgraph Engine["Camoufox subprocess (child_process)"]
        Launcher[launcher.js
spawn camoufox-bin]
        Cmofx[Camoufox
Firefox fork + C++
fingerprint spoofing]
    end

    subgraph Storage["Disk"]
        Profiles[(~/.camofox/profiles/)]
        Cookies[(~/.camofox/cookies/)]
        Traces[(~/.camofox/traces/)]
    end

    Agent -->|REST| Cli
    Cli -->|HTTP+Bearer| Express
    Express --> Auth
    Auth --> Snap
    Auth --> Macro
    Express --> Persist
    Express --> Proxy
    Express --> Trace
    Snap -->|control| Launcher
    Macro -->|control| Launcher
    Launcher -->|spawn| Cmofx
    Cmofx -->|browse| WWW((real web))
    Persist <-->|read/write| Profiles
    Persist <-->|read| Cookies
    Trace <-->|write/read| Traces

    classDef core fill:#fff3e0,stroke:#f57c00
    classDef storage fill:#e3f2fd,stroke:#1976d2
    class Cmofx,Launcher core
    class Profiles,Cookies,Traces storage

3.3 三個關鍵設計

A. Accessibility Snapshot + Element Refs

不是回傳整份 raw HTML，而是 a11y tree 加上 stable refs：

1- button "Login" e1
2- textbox "Email" e2
3- textbox "Password" e3
4- link "Forgot password?" e4

Agent 看到 e1 就可以 POST /tabs/:tabId/click {"ref": "e1"}。比 raw HTML 省 ~90 % token。

B. C++ Fingerprint Spoofing

不是用 JS shim，而是改 Firefox 原始碼 → 重編。所有偵測 API（navigator.*、WebGL、AudioContext、WebRTC…）在 JS 拿到前就已經是「正確的真人值」。

C. Lazy Launch + Idle Shutdown

server 啟動時不 spawn Camoufox；第一個 POST /tabs 才開；長時間無流量自動關閉。idle 時整個 server ~ 40 MB RAM。適合與其他服務共享機器。

4. Helper Scripts 詳細用法

4.1 開一個 tab 並 snapshot

 1# 1. 開 tab
 2curl -X POST http://localhost:9377/tabs \
 3  -H 'Content-Type: application/json' \
 4  -d '{
 5    "userId": "agent1",
 6    "sessionKey": "task1",
 7    "url": "https://example.com"
 8  }'
 9# → {"tabId":"tab-abc", ...}
10
11# 2. snapshot（拿 element refs）
12curl http://localhost:9377/tabs/tab-abc/snapshot
13# → accessibility tree with e1, e2, e3...

4.2 Click / Type / Scroll

 1# Click
 2curl -X POST http://localhost:9377/tabs/tab-abc/click \
 3  -d '{"ref": "e1"}'
 4
 5# Type
 6curl -X POST http://localhost:9377/tabs/tab-abc/type \
 7  -d '{"ref": "e2", "text": "user@example.com"}'
 8
 9# Scroll
10curl -X POST http://localhost:9377/tabs/tab-abc/scroll \
11  -d '{"direction": "down", "amount": 500}'

4.3 Search Macros

1curl -X POST http://localhost:9377/tabs \
2  -d '{"userId":"agent1","sessionKey":"search","url":"@google_search:diffusion model"}'
3
4# 其他 macros：
5# @youtube_search   @amazon_search   @reddit_subreddit   ...（共 ~14 個）

4.4 結構化 extract

把 a11y snapshot ref 對應到 JSON Schema property（x-ref）：

 1curl -X POST http://localhost:9377/tabs/tab-abc/extract \
 2  -d '{
 3    "schema": {
 4      "type": "object",
 5      "properties": {
 6        "title": {"type":"string","x-ref":"e3"},
 7        "price": {"type":"number","x-ref":"e7"}
 8      }
 9    }
10  }'
11# → {"title":"iPhone 15", "price":999}

4.5 Cookie import（須 Bearer token）

1export CAMOFOX_API_KEY=$(openssl rand -hex 32)
2mkdir -p ~/.camofox/cookies
3# 從瀏覽器 export Netscape 格式 cookie file
4cp ~/Downloads/linkedin_cookies.txt ~/.camofox/cookies/linkedin.txt
5
6# 透過 API import（plugin 自動呼叫）
7curl -X POST http://localhost:9377/sessions/agent1/cookies \
8  -H "Authorization: Bearer $CAMOFOX_API_KEY" \
9  -d '{"cookiesPath": "linkedin.txt"}'

限制：max 500 cookies / 5 MB / path traversal 被擋。

4.6 Session tracing（Playwright trace）

 1# 開 tab 時 opt-in
 2curl -X POST :9377/tabs -d '{"userId":"a1","sessionKey":"t1","url":"...","trace":true}'
 3
 4# 關 session 觸發 flush
 5curl -X DELETE :9377/sessions/a1
 6
 7# 列 trace
 8curl :9377/sessions/a1/traces -H "Authorization: Bearer $CAMOFOX_API_KEY"
 9
10# 下載
11curl -O :9377/sessions/a1/traces/trace-2026-04-18-abc.zip -H "Authorization: Bearer $CAMOFOX_API_KEY"
12
13# Playwright 看 trace
14npx playwright show-trace trace-2026-04-18-abc.zip

4.7 Proxy + GeoIP

1curl -X POST :9377/tabs -d '{
2  "userId":"a1","sessionKey":"t1","url":"https://...",
3  "proxy":{
4    "server":"http://residential-proxy.example.com:8000",
5    "username":"user","password":"$PROXY_PASSWORD"
6  }
7}'
8# Camoufox 自動 derive locale / timezone / geolocation from proxy IP

4.8 VNC 互動登入

1# 啟用 VNC plugin（camofox.config.json）
2{"vnc": {"enabled": true, "password": "myvncpw"}}
3
4# server 起來後：
5# - 連 vnc://localhost:5900（用 noVNC client 或 vnc://）
6# - 手動完成 OAuth / captcha / SMS 驗證
7# - 完成後 storage_state 自動 persist → 之後 agent 用該 sessionKey 自動帶身分

4.9 OpenAPI 互動 docs

啟動後直接打：

• http://localhost:9377/openapi.json — full OpenAPI 3.0 spec
• http://localhost:9377/docs — interactive Swagger UI

對接 LLM tool 描述非常方便（直接吐給 LLM 當 system prompt）。

5. 應用場景

6. 資安掃描報告

對 lib/ scripts/ plugins/ server.js plugin.js plugin.ts 跑 grep -nE 'eval|new Function|child_process|spawn|exec|secret|api_key|password|token'：

🔴 高風險

無。沒有發現 eval() / new Function() 在主路徑使用；也沒有 hard-coded secret。

🟡 中風險 / 須留意

🟢 低風險（良好設計）

• Bearer token 用 timing-safe compare（lib/auth.js:67）— 防 timing attack
• API key 只能從 env var 讀，不從設定檔（避免明文寫入 config）
• Cookie import 有 path traversal 防禦 + 500 cookies + 5 MB limit + allowlist sanitization
• Loopback 例外只在 non-production 生效（config.nodeEnv !== 'production' && isLoopbackAddress）
• child_process 使用集中在 4 個明確檔（design rule，README/AGENTS.md 明示）
• Trace zip 有 TTL + size cap + 自動清理
• 預設 ESM-only + Node 22+ → 較新 supply-chain hygiene
• OpenAPI 自動生成（spec 與 code 不漂移）

結論

🟡 中風險偏低，安全意識遠優於同類專案平均。主要建議：

1. production deploy 必設 CAMOFOX_API_KEY 與 CAMOFOX_ACCESS_KEY（前者 gate 敏感 endpoint，後者 gate 全部）
2. VNC plugin 預設關閉，要啟用務必設強密碼
3. ~/.camofox/profiles/ 視同機密（含 session cookies）— production encrypted disk
4. npm install 在 CI 環境用 --ignore-scripts 並驗證 Camoufox binary SHA

7. FAQ

Q1: Camoufox 與一般 Playwright stealth plugin 差別？ A: Stealth plugin 只能在 JS 層 patch（Object.defineProperty(navigator, ...)），detection 工具看到「有 patch 痕跡」反而當成 fingerprint。Camoufox 是改 Firefox 原始碼 / 重編，所有偵測點在 C++ 層就已經是「真人值」。

Q2: 為什麼用 Firefox 不用 Chromium？ A: Chrome 的 Web Authentication / DRM / 多種 telemetry 與 Google 服務深度耦合，patch 風險高。Firefox 開源、結構單純、Mozilla 對 fingerprint 防護本來就有研究底子。

Q3: 我已經有 Playwright 程式碼，怎麼遷移？ A: 兩條路：(a) 用 camoufox-js 套件（npm）替換 playwright，code 改動 < 10 行；(b) 用 camofox-browser REST API 完全外包瀏覽器層，agent 改用 HTTP call。後者比較適合 LLM agent。

Q4: API key 在 plugin config（openclaw.json）裡放安全嗎？ A: ❌ 不安全 — README 明示「plugin config 是明文」，必須走 export CAMOFOX_API_KEY=... 在 shell / systemd / Docker env / Fly.io secrets 設定。

Q5: 我可以用在 web scraping 商業產品嗎？ A: License 是 MIT，code 沒問題。但：(a) 上游 Camoufox 可能有自己 license（須查 camoufox.com）；(b) 對特定網站的 scraping 受該網站 ToS 與當地法律規範（GDPR / CCPA / CFAA），技術可行 ≠ 法律可行。

Q6: idle 真的只 40 MB？什麼時候會炸？ A: server 本身 ~40 MB；每個 active tab ~ 200-400 MB（Firefox 渲染）。idle shutdown 是「沒人開 tab 一段時間後關掉子進程」，不是完全沒 RAM。同時 10 個 active tab → 你的機器要 ~3-4 GB。

Q7: 為什麼 element refs 是 e1 / e2 不是 CSS selector？ A: CSS selector 對動態 DOM 很脆弱；a11y tree refs 跨 page reload / DOM 重排相對穩定，更適合 LLM agent。spec：accessibility role + name 為主，refs 為 stable index。

Q8: 跟 browserless / browserbase 比？ A: 那兩家是商業 hosted；camofox-browser 是 self-hosted 開源 + 更強反偵測（C++ 層）+ 對 AI agent 更友善的 API。但商業 hosted 在「不想自己管 infra」這條贏。

8. 進階技巧

8.1 多用戶 session 隔離

1# user1 與 user2 完全隔離（不同 profile dir / 不同 cookies）
2curl -X POST :9377/tabs -d '{"userId":"user1","sessionKey":"a","url":"..."}'
3curl -X POST :9377/tabs -d '{"userId":"user2","sessionKey":"a","url":"..."}'

profile dir：~/.camofox/profiles/<sha256(userId)[:16]>/storage_state.json

8.2 自定 search macro

lib/macros.js 可以加新的 @my_site_search：

1export const macros = {
2  '@my_internal_search': (q) => `https://intra.company.com/?q=${encodeURIComponent(q)}`,
3  // ...既有的 @google_search 等
4};

agent 直接打 url: "@my_internal_search:keyword"。

8.3 OpenAPI → LLM tool 描述

把 /openapi.json 餵給 LLM 作 tool schema：

1curl :9377/openapi.json | jq '.paths' > tools-for-llm.json
2# 接到 LLM system prompt：「以下是你可用的工具 ...」

8.4 結構化 extract 對 JSON Schema 強制

 1{
 2  "schema": {
 3    "type": "object",
 4    "required": ["title", "price"],
 5    "properties": {
 6      "title": {"type": "string", "x-ref": "e3"},
 7      "price": {"type": "number", "x-ref": "e7", "minimum": 0},
 8      "in_stock": {"type": "boolean", "x-ref": "e9"}
 9    }
10  }
11}

x-ref 對應 a11y ref；schema 驗證失敗會回 422。

8.5 Crash reporter worker

workers/crash-reporter/ 是獨立 worker，server 偵測 Camoufox 子進程 crash 時把 stack + last action 寫到 ~/.camofox/crashes/。production 接 sentry / log aggregator 用。

8.6 plugin 自開發

1plugins/my-plugin/
2├── index.js         # export { name, init(server, config) }
3├── AGENTS.md        # 約束（child_process 隔離等）
4└── package.json

在 camofox.config.json 加 {"plugins":{"my-plugin":{"enabled":true,...}}}。

8.7 Persistent storage state 匯出

1# 從 VNC 手動登入後
2curl :9377/sessions/agent1/storage_state \
3  -H "Authorization: Bearer $CAMOFOX_API_KEY" \
4  > storage_state.json
5
6# 之後注入到另一台機器的 session
7curl -X POST :9377/sessions/agent2/storage_state \
8  -H "Authorization: Bearer $CAMOFOX_API_KEY" \
9  -d @storage_state.json

9. 整合進其他工作流

9.1 Claude Code / 大型 LLM agent

1# Python 範例：把 camofox 包成 tool
2def browse(url: str, action: str | None = None) -> str:
3    tab = requests.post('http://localhost:9377/tabs', json={
4        'userId': 'claude', 'sessionKey': 'main', 'url': url
5    }).json()
6    snap = requests.get(f'http://localhost:9377/tabs/{tab["tabId"]}/snapshot').text
7    return snap  # 給 LLM 看 a11y tree + refs

Claude / GPT 看到 e1 e2 e3 refs，後續呼叫 click / type tool。

9.2 OpenClaw agent

直接：

1openclaw plugins install @askjo/camofox-browser

10+ tool 自動註冊到 OpenClaw runtime。

9.3 LangChain / LlamaIndex Tool

1from langchain.tools import Tool
2camofox_browse = Tool(
3    name="camofox_browse",
4    description="Browse a URL through stealth headless browser. Returns accessibility snapshot.",
5    func=browse,
6)

9.4 N8N / Zapier 自動化

server /openapi.json → 餵給 N8N 的「HTTP Request」node template generator → 立刻有 35+ trigger。

9.5 prometheus monitoring

1# prometheus.yml
2scrape_configs:
3  - job_name: 'camofox'
4    static_configs:
5      - targets: ['localhost:9377']
6    metrics_path: '/metrics'

主要 metric：active tab count / per-tab RAM / request latency / error rate。

9.6 自家研究 pipeline 整合 checklist

1. 生產 / staging 設不同 API key（不要共用）
2. CAMOFOX_ACCESS_KEY 設成 superkey，gate 全 endpoint
3. proxy password 走 secrets manager（Vault / AWS Secrets Manager / Fly secrets）
4. ~/.camofox/profiles/ 掛 encrypted volume
5. 限速：在前面加 nginx / Caddy rate-limit，camofox-browser 本身 idle 設計，但若每秒 100 個 new tab 一樣會炸
6. trace 收集只在 incident 時打開（trace zip 累積快、IO 重）

10. 重點摘要 Checklist

• Node ≥ 22 ESM
• 三種安裝：npm standalone / OpenClaw plugin / Docker
• 首次 install 自動下載 Camoufox ~300 MB
• 預設 port 9377；OpenAPI docs 在 /docs
• production 必設 CAMOFOX_API_KEY 與 CAMOFOX_ACCESS_KEY
• cookie import 走 Bearer token；path traversal 已擋
• session 用 userId + sessionKey 隔離
• element refs (e1 e2) 是穩定識別，不要用 CSS selector
• structured extract 走 x-ref 對應 JSON Schema property
• proxy + GeoIP 自動帶 locale/timezone
• VNC plugin 預設關閉，啟用務必設強密碼
• trace 取代 video（Firefox 沒 recordVideo）
• idle 時 ~40 MB，可與其他服務共享機器
• license MIT，但 scraping 受該網站 ToS 與當地法律約束

11. 進一步閱讀

Generated 2026-05-23 by gh-tutorial-qd skill — paired with inbox/2026-05-23-github-jo-inc-camofox-browser.md.