camofox-default-browser

Camofox Default Browser

Use Camoufox browser (Firefox fork with advanced fingerprint management) as OpenClaw's browser automation engine. The camofox_* tools handle anti-bot protection that standard Chromium/Playwright automation may trigger, enabling reliable automation for authorized tasks.

When to Use

• Use camofox_* when the built-in browser tool encounters blocking — for external public websites with anti-bot protection
• The built-in browser tool (Playwright/Chromium) may be detected by Google, LinkedIn, Amazon, Cloudflare, and most WAFs. Camoufox manages fingerprints at the C++ implementation level, reducing detection risk.

Reason

Camoufox manages browser fingerprints at the C++ implementation level: navigator.hardwareConcurrency, WebGL renderer, AudioContext, screen geometry, WebRTC — all handled before JavaScript evaluation. This provides more reliable automation compared to standard stealth plugins that can themselves be fingerprinted.

Available Tools

Workflow

1. camofox_create_tab(url="https://example.com") → tabId
2. camofox_snapshot(tabId="") → accessibility tree
3. camofox_click/type(tabId="", ref="e3") → interact
4. camofox_close_tab(tabId="") → cleanup

Resource Management

• Server auto-starts with OpenClaw Gateway (default port 9377)
• Browser engine launches lazily on first tab request
• Idle browser shuts down after configurable timeout (default 5 min)
• ~40MB memory when idle, ~200MB with active browser session
• Session isolation: separate cookies/storage per user
• Health endpoint: GET http://localhost:9377/health
• Crash telemetry: anonymized (no page content, cookies, IPs). Opt out via CAMOFOX_CRASH_REPORT_ENABLED=false

⚠️ Security & Usage Guidelines

• Cookie Import: Session cookies are bearer tokens that grant full account access. Treat imported cookie files as live credentials. Only import cookies you own or have explicit authorization to use.
• Authorized Use Only: This tool is designed for legitimate automation tasks where you have permission to access the target service. Do not use to circumvent access controls on sites where you lack authorization.
• Legal Compliance: Ensure your automation complies with target site Terms of Service, applicable laws, and regulations. Unauthorized scraping or access may violate computer fraud laws.
• Privacy: Do not automate access to accounts or data you do not own or have explicit permission to access.
• Risk Awareness: Imported session cookies may bypass normal login safeguards. Mishandling can lead to unauthorized account actions or session hijacking.

Dependencies & System Requirements

System Dependencies (Linux / Debian-based)

The following packages are required for Camoufox to render pages correctly, handle UI elements, and operate in both headful and headless environments.

All libraries above are available via standard Debian/Ubuntu package repositories (apt). For Alpine Linux, equivalents exist but must be cross-compiled alongside Camoufox since pre-built binaries target glibc distributions.

Node.js Requirements

Camoufox is distributed as a native C++ server — there are no npm dependencies. The only JavaScript requirement is Node.js itself to bootstrap the OpenClaw tool integrations. Both global (npm i -g) and local installation paths work identically since the server communicates via HTTP localhost API.

Browser Engine

The Camoufox binary is downloaded and cached automatically by the camofox_* tool runtime on first use. To force re-download, delete the cache directory before next session start.

Environment Variables

Optional Dependencies

These packages are not strictly required for basic browsing automation but improve compatibility:

• Font packages (fonts-liberation, fonts-noto-color-emoji, fonts-wqy-microhei): Provide proper CJK, emoji, and Western text rendering. Without fonts, PDF exports may show blank boxes and some websites fall back to generic monospace.
• Shared MIME info (shared-mime-info): Enables correct MIME-type detection for downloaded files (PDFs, images, archives).
• Alsa / PulseAudio (libasound2, libpulse0): Audio playback support needed for sites with embedded video/audio that attempt to initialize audio contexts.
• Video codecs (libavcodec-extra, libavformat-extra): H.264/AAC decoding for HTML5 video players. Firefox ships with open formats (VP8/VP9, Ogg Vorbis) by default; proprietary codecs require additional packages.
• Cups (cups-client, libcupsys2): Print-to-PDF functionality. Required if automation involves printing web pages.

---

Dependencies

# System (Linux)
apt-get install -y libgtk-3-0 libgdk-pixbuf2.0-0 libdbus-glib-1-2 \
  libxt6 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
  libatk-bridge2.0-0 libdrm2 libgbm1 xvfb

# Environment
export CAMOUFOX_EXECUTABLE=/root/.cache/camoufox/camoufox