Skill: goodgoodjm/camoufox (version 1.0.0)

--- name: camoufox version: 1.0.0 description: Anti-detect browser automation using Camoufox (Firefox-based). Use instead of Chrome/Playwright for bot-detection-heavy sites like X/Twitter, Naver, and other protected sites. Provides stealth browsing with OS/browser fingerprint spoofing, humanized mouse movements, and persistent sessions. --- # Camoufox **Use instead of OpenClaw's built-in browser tool for bot-detection sites.** ## Setup (one-time) ```bash bash scripts/setup.sh ``` ## Usage ```bash source ~/.openclaw/workspace/camoufox-env/bin/activate xvfb-run -a --server-args="-screen 0 1920x1080x24" python3 your_script.py ``` ## Required Settings ```python from camoufox.sync_api import Camoufox with Camoufox( headless=False, # MUST be False (True gets detected) os='linux', # MUST match server OS (stack traces leak real OS) humanize=True, persistent_context=True, user_data_dir='~/.openclaw/camoufox-profile' ) as browser: page = browser.new_page() # Use standard Playwright API from here ``` ## Paths - venv: `~/.openclaw/workspace/camoufox-env/` - profile: `~/.openclaw/camoufox-profile/` ## CAPTCHA Handling First visit to protected sites may need manual CAPTCHA: ```bash DISPLAY=:1 python3 scripts/login_session.py https://site.com/login ``` Solve via VNC, session saves to profile for future automation. ## Scripts - `scripts/setup.sh` - Install dependencies - `scripts/browse.py <url> --screenshot out.png` - Quick browse - `scripts/login_session.py <url>` - VNC manual login

path: references/options.md
content: # Camoufox Options Reference

## Camoufox() Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `headless` | bool | True | **Set to False** - headless mode gets detected |
| `os` | str | auto | OS to emulate: `'linux'`, `'macos'`, `'windows'` |
| `humanize` | bool | False | Enable human-like mouse movements |
| `persistent_context` | bool | False | Save browser state between sessions |
| `user_data_dir` | str | None | Directory for profile/cookies |
| `proxy` | str | None | Proxy URL (e.g., `[REDACTED_SECRET]`) |
| `fingerprint` | obj | None | Custom BrowserForge fingerprint (not recommended) |

## OS Matching

**Critical**: The `os` parameter must match your actual server OS. Bot detectors check JavaScript stack traces which reveal the real OS.

```python
# On Linux server
Camoufox(os='linux')  # ✓ Correct

# On macOS
Camoufox(os='macos')  # ✓ Correct

# Wrong: Linux server pretending to be Mac
Camoufox(os='macos')  # ✗ Will be detected
```

## Display Options for Headless Servers

### Xvfb (Virtual Framebuffer)
Best for automated scripts:
```bash
xvfb-run -a --server-args="-screen 0 1920x1080x24" python3 script.py
```

### VNC (for manual intervention)
Best when you need to see/interact with browser:
```bash
# Start VNC server
vncserver :1 -geometry 1920x1080 -depth 24

# Run with VNC display
DISPLAY=:1 python3 script.py
```

## Proxy Configuration

```python
# HTTP proxy
Camoufox(proxy='http://user:[REDACTED_SECRET]:8080')

# SOCKS5 proxy
Camoufox(proxy='socks5://user:[REDACTED_SECRET]:1080')
```

## Common Patterns

### Screenshot with wait
```python
page.goto(url)
time.sleep(3)  # Let dynamic content load
page.wait_for_load_state('networkidle')
page.screenshot(path='output.png')
```

### Handle login forms
```python
page.fill('input[name="username"]', 'myuser')
page.fill('input[name="password"]', 'mypass')
page.click('button[type="submit"]')
page.wait_for_url('**/dashboard**')
```

### Extract text
```python
text = page.inner_text('body')
# or specific element
title = page.inner_text('h1')
```


path: scripts/browse.py
content: #!/usr/bin/env python3
"""
Camoufox Browser Script
Usage: python3 browse.py <url> [--screenshot <path>] [--text] [--wait <seconds>]
"""

import argparse
import os
import sys
import time

def main():
    parser = argparse.ArgumentParser(description='Browse with Camoufox')
    parser.add_argument('url', help='URL to visit')
    parser.add_argument('--screenshot', '-s', help='Save screenshot to path')
    parser.add_argument('--text', '-t', action='store_true', help='Print page text')
    parser.add_argument('--wait', '-w', type=int, default=3, help='Wait seconds after load')
    parser.add_argument('--profile', default=os.path.expanduser('~/.openclaw/camoufox-profile'),
                        help='Profile directory')
    args = parser.parse_args()

    try:
        from camoufox.sync_api import Camoufox
    except ImportError:
        print("ERROR: camoufox not installed. Run setup.sh first.", file=sys.stderr)
        sys.exit(1)

    os.makedirs(args.profile, exist_ok=True)

    print(f"Opening {args.url}...", file=sys.stderr)
    
    with Camoufox(
        headless=False,
        os='linux',
        humanize=True,
        persistent_context=True,
        user_data_dir=args.profile
    ) as browser:
        page = browser.new_page()
        page.set_viewport_size({'width': 1920, 'height': 1080})
        page.goto(args.url, timeout=60000)
        time.sleep(args.wait)
        page.wait_for_load_state('networkidle', timeout=30000)

        title = page.title()
        print(f"Title: {title}", file=sys.stderr)

        if args.text:
            text = page.inner_text('body')
            print(text)

        if args.screenshot:
            page.screenshot(path=args.screenshot)
            print(f"Screenshot saved: {args.screenshot}", file=sys.stderr)

if __name__ == '__main__':
    main()


path: scripts/login_session.py
content: #!/usr/bin/env python3
"""
Open Camoufox for manual login via VNC.
Session will be saved to profile for future automated use.

Usage:
  DISPLAY=:1 python3 login_session.py <url> [--timeout <minutes>]

Requires VNC server running on the display.
"""

import argparse
import os
import sys
import time

def main():
    parser = argparse.ArgumentParser(description='Open browser for manual login')
    parser.add_argument('url', help='URL to open (e.g., https://x.com/login)')
    parser.add_argument('--timeout', '-t', type=int, default=10,
                        help='Minutes to keep browser open (default: 10)')
    parser.add_argument('--profile', default=os.path.expanduser('~/.openclaw/camoufox-profile'),
                        help='Profile directory')
    args = parser.parse_args()

    if not os.environ.get('DISPLAY'):
        print("ERROR: DISPLAY not set. Run with DISPLAY=:1 or use VNC.", file=sys.stderr)
        print("Example: DISPLAY=:1 python3 login_session.py https://x.com/login", file=sys.stderr)
        sys.exit(1)

    try:
        from camoufox.sync_api import Camoufox
    except ImportError:
        print("ERROR: camoufox not installed. Run setup.sh first.", file=sys.stderr)
        sys.exit(1)

    os.makedirs(args.profile, exist_ok=True)

    print(f"Opening {args.url} for manual login...")
    print(f"Browser will stay open for {args.timeout} minutes.")
    print(f"Session will be saved to: {args.profile}")
    print("Close browser or wait for timeout when done.")

    with Camoufox(
        headless=False,
        os='linux',
        humanize=True,
        persistent_context=True,
        user_data_dir=args.profile
    ) as browser:
        page = browser.new_page()
        page.set_viewport_size({'width': 1400, 'height': 900})
        page.goto(args.url, timeout=60000)
        
        print(f"\nBrowser open. Waiting {args.timeout} minutes...")
        try:
            time.sleep(args.timeout * 60)
        except KeyboardInterrupt:
            print("\nInterrupted.")
        
        print("Session saved!")

if __name__ == '__main__':
    main()


path: scripts/setup.sh
content: #!/bin/bash
# Camoufox Setup Script
# Run once to install Camoufox and dependencies

set -e

VENV_DIR="${CAMOUFOX_VENV:-$HOME/.openclaw/workspace/camoufox-env}"
PROFILE_DIR="${CAMOUFOX_PROFILE:-$HOME/.openclaw/camoufox-profile}"

echo "=== Camoufox Setup ==="
echo "venv: $VENV_DIR"
echo "profile: $PROFILE_DIR"

# Check Python
if ! command -v python3 &> /dev/null; then
    echo "ERROR: python3 not found"
    exit 1
fi

# Install python3-venv if needed (Ubuntu/Debian)
if ! python3 -m venv --help &> /dev/null; then
    echo "Installing python3-venv..."
    sudo apt install -y python3-venv python3-full || true
fi

# Create venv
if [ ! -d "$VENV_DIR" ]; then
    echo "Creating virtual environment..."
    python3 -m venv "$VENV_DIR"
fi

# Install camoufox
echo "Installing camoufox..."
source "$VENV_DIR/bin/activate"
pip install --upgrade pip
pip install camoufox

# Create profile directory
mkdir -p "$PROFILE_DIR"

# Install Xvfb if not present (for headless servers)
if ! command -v xvfb-run &> /dev/null; then
    echo "Installing Xvfb..."
    sudo apt install -y xvfb || true
fi

# Test installation
echo "Testing Camoufox..."
python3 -c "from camoufox.sync_api import Camoufox; print('Camoufox OK!')"

echo ""
echo "=== Setup Complete ==="
echo "Activate with: source $VENV_DIR/bin/activate"
echo "Profile stored in: $PROFILE_DIR"


Security scan verdicts — ClawScan: malicious | static analysis: clean | VirusTotal: suspicious | SkillSpector:  ()