camofox-cloaked-browser

# Camofox Cloaked Browser ## When to use Use this skill only when the task needs Camofox/Camoufox specifically: - user names Camofox, Camoufox, anti-detection browsing, cloaked browser, browser fingerprint spoofing, or stealth browsing - a site is likely to block normal Playwright/Chrome automation - the task needs stable accessibility refs from a Camofox browser server - OpenClaw has the `camofox-browser` plugin/tools available Do **not** use it for ordinary web search, simple page fetches, static text extraction, or normal browser automation. Use the cheaper default stack unless cloaking is actually load-bearing. If the user names another browser target explicitly — Browserbase, Selkies, a tailnet browser, normal Hermes browser, Chrome DevTools, etc. — stop and use that target/skill instead. Do not silently route through Camofox. ## Default target Default local server: ```text http://127.0.0.1:9377 ``` Equivalent localhost URL is usually fine: ```text http://localhost:9377 ``` Prefer `127.0.0.1` in examples to avoid IPv6/localhost oddities. There is no container target in this skill. Do not mention or rely on container names; this skill is about the npm server and OpenClaw plugin/API. ## Operating model Camofox Browser is a Node server and OpenClaw plugin wrapper around Camoufox, a Firefox-based anti-detection browser. Primary local startup: ```bash npx -y @askjo/camofox-browser # serves http://127.0.0.1:9377 by default ``` Alternative cloned-repo startup: ```bash git clone https://github.com/jo-inc/camofox-browser cd camofox-browser npm install npm start ``` Alternative global install: ```bash npm install -g @askjo/camofox-browser camofox-browser ``` `npm install` / `npx` downloads the Camoufox browser binary on first run via the package postinstall unless `CAMOUFOX_EXECUTABLE` points to an existing compatible Camoufox bundle. Expect roughly a few hundred MB for the browser payload. ## OpenClaw plugin mode If OpenClaw has the upstream plugin installed, prefer the plugin tools over raw `curl` because they auto-manage `userId` from `ctx.agentId`, use `sessionKey`, and can auto-start the server. Install shape: ```bash openclaw plugins install @askjo/camofox-browser # or whatever ClawHub install command the registry page currently shows ``` Useful OpenClaw CLI commands from the plugin: ```bash openclaw camofox status openclaw camofox start openclaw camofox stop openclaw camofox tabs openclaw camofox configure ``` Plugin config shape shown by upstream: ```yaml plugins: entries: camofox-browser: enabled: true config: port: 9377 autoStart: true maxSessions: 5 maxTabsPerSession: 3 sessionTimeoutMs: 600000 browserIdleTimeoutMs: 300000 maxOldSpaceSize: 128 ``` The upstream plugin exposes these core tools: - `camofox_create_tab` — create tab; returns `tabId` - `camofox_snapshot` — accessibility snapshot with refs and screenshot; primary observation tool - `camofox_click` — click by ref or CSS selector - `camofox_type` — type by ref or selector; optional `pressEnter` - `camofox_navigate` — navigate by URL or search macro - `camofox_scroll` — scroll page - `camofox_screenshot` — screenshot only - `camofox_close_tab` — close a tab - `camofox_evaluate` — execute JS; gated by server auth middleware - `camofox_list_tabs` — list tabs for the current user - `camofox_import_cookies` — import Netscape cookies; use `CAMOFOX_API_KEY` for this sensitive endpoint ## Hard workflow rules Always follow these rules when using Camofox: 1. Check `/health` before doing browser work. 2. Always send `userId` in raw REST calls. 3. Prefer `sessionKey` when creating tabs so task tabs group together. 4. Open or reuse a tab intentionally; do not spray new tabs. 5. Snapshot before selecting refs. 6. Re-snapshot after every state-changing action: click, type with submit, press, scroll, navigation, back, forward, refresh, JS evaluate that mutates state. 7. Element refs reset after navigation and may become stale after DOM changes. 8. Prefer refs from the latest snapshot over CSS selectors. Use selectors only when refs are unavailable or unstable. 9. Close tabs when done unless preserving the session is explicitly useful. 10. Do not claim Camofox is in use until both the server is healthy and the actual agent/client is pointed at it. ## REST API quick commands Set base variables: ```bash BASE="${CAMOFOX_BASE_URL:-http://127.0.0.1:9377}" USER_ID="${CAMOFOX_USER_ID:-agent1}" SESSION_KEY="${CAMOFOX_SESSION_KEY:-task1}" ``` If `CAMOFOX_ACCESS_KEY` or `CAMOFOX_API_KEY` is set, include auth where required: ```bash AUTH_HEADER=() if [ -n "${CAMOFOX_ACCESS_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer ${CAMOFOX_ACCESS_KEY}") elif [ -n "${CAMOFOX_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer ${CAMOFOX_API_KEY}") fi ``` ### Health ```bash curl -fsS "$BASE/health" ``` ### Create tab ```bash TAB_ID="$(curl -fsS -X POST "$BASE/tabs" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"sessionKey\":\"$SESSION_KEY\",\"url\":\"https://example.com\"}" \ | python3 -c 'import json,sys; print(json.load(sys.stdin)["tabId"])')" printf 'TAB_ID=%s\n' "$TAB_ID" ``` ### Navigate ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/navigate" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"url\":\"https://example.com\"}" ``` Search macro example: ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/navigate" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"macro\":\"@google_search\",\"query\":\"site:example.com pricing\"}" ``` Known macros include: - `@google_search` - `@youtube_search` - `@amazon_search` - `@reddit_search` - `@wikipedia_search` - `@twitter_search` - `@yelp_search` - `@spotify_search` - `@netflix_search` - `@linkedin_search` - `@instagram_search` - `@tiktok_search` - `@twitch_search` ### Snapshot ```bash curl -fsS "$BASE/tabs/$TAB_ID/snapshot?userId=$USER_ID" ``` With screenshot and pagination offset: ```bash curl -fsS "$BASE/tabs/$TAB_ID/snapshot?userId=$USER_ID&includeScreenshot=true&offset=0" ``` ### Click ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/click" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"ref\":\"e1\"}" ``` Selector fallback: ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/click" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"selector\":\"button[type=submit]\"}" ``` ### Type ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/type" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"ref\":\"e2\",\"text\":\"hello world\"}" ``` Type and submit: ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/type" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"ref\":\"e2\",\"text\":\"query\",\"pressEnter\":true}" ``` ### Press key ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/press" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"key\":\"Enter\"}" ``` ### Wait ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/wait" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"timeout\":3000}" ``` ### Scroll ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/scroll" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"direction\":\"down\",\"amount\":700}" ``` ### Back / forward / refresh ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/back" -H 'Content-Type: application/json' "${AUTH_HEADER[@]}" -d "{\"userId\":\"$USER_ID\"}" curl -fsS -X POST "$BASE/tabs/$TAB_ID/forward" -H 'Content-Type: application/json' "${AUTH_HEADER[@]}" -d "{\"userId\":\"$USER_ID\"}" curl -fsS -X POST "$BASE/tabs/$TAB_ID/refresh" -H 'Content-Type: application/json' "${AUTH_HEADER[@]}" -d "{\"userId\":\"$USER_ID\"}" ``` ### Links / images / screenshot ```bash curl -fsS "$BASE/tabs/$TAB_ID/links?userId=$USER_ID&limit=50" curl -fsS "$BASE/tabs/$TAB_ID/images?userId=$USER_ID&limit=50" curl -fsS "$BASE/tabs/$TAB_ID/screenshot?userId=$USER_ID" --output screenshot.png ``` ### Evaluate JavaScript This endpoint is auth-gated by the server middleware. Use only when needed. ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/evaluate" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"expression\":\"document.title\"}" ``` ### Structured extract ```bash curl -fsS -X POST "$BASE/tabs/$TAB_ID/extract" \ -H 'Content-Type: application/json' \ "${AUTH_HEADER[@]}" \ -d "{\"userId\":\"$USER_ID\",\"schema\":{\"type\":\"object\",\"properties\":{\"title\":{\"type\":\"string\"}}}}" ``` ### List and close tabs ```bash curl -fsS "$BASE/tabs?userId=$USER_ID" curl -fsS -X DELETE "$BASE/tabs/$TAB_ID?userId=$USER_ID" "${AUTH_HEADER[@]}" ``` ### Delete session data This endpoint is auth-gated. ```bash