camofox-browser

# camofox-browser Skill

Camofox is an anti-detection browser automation system built on Camoufox + Playwright with:
- CLI (`camofox`) for operator workflows
- REST API (port `9377` by default) for programmatic control
- OpenClaw plugin integration (`plugin.ts`) with 18 plugin tools

This skill is optimized for bot-evasion workflows where default browser automation gets flagged.

### Camofox vs generic browser skills

Use this skill instead of generic browser tooling when at least one applies:
- You need anti-detection browser identity continuity across sessions.
- You need proxy-aware geolocation behavior and region presets.
- You need OpenClaw plugin compatibility with dedicated camofox tool names.
- You need both CLI and REST API control paths against the same runtime.

Do **not** use this skill if you only need a simple local static page script and anti-detection is irrelevant.

### Fast interface chooser

Use CLI when:
- You are running interactive ops/debugging from terminal.
- You want local encrypted vault prompts for credentials.
- You want quick one-shot command chaining with active tab memory.

Use REST API when:
- You are integrating from another service/agent runtime.
- You need strict request/response control with explicit `userId` and `tabId`.
- You need OpenClaw-compatible route shape (`/tabs/open`, `/act`, `/snapshot`).

## 1) Core Workflow (CLI + API dual interface)

Follow this loop for reliable automation:

1. Create/open tab
2. Snapshot to get fresh `eN` refs
3. Interact using refs
4. Re-snapshot after DOM/navigation changes
5. Keep `userId` stable for session continuity

CLI:
```bash
camofox open https://example.com --user agent1
camofox snapshot --user agent1
camofox click e5 --user agent1
camofox type e7 "hello world" --user agent1
```

API:
```bash
curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","sessionKey":"default","url":"https://example.com"}'

curl "http://localhost:9377/tabs/<tabId>/snapshot?userId=agent1"

curl -X POST http://localhost:9377/tabs/<tabId>/click \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","ref":"e5"}'
```

Dual interface mapping (most common path):

| Intent | CLI | API |
|---|---|---|
| Open tab | `camofox open <url>` | `POST /tabs` |
| Snapshot refs | `camofox snapshot` | `GET /tabs/:tabId/snapshot` |
| Click element | `camofox click <ref>` | `POST /tabs/:tabId/click` |
| Type text | `camofox type <ref> <text>` | `POST /tabs/:tabId/type` |
| Navigate | `camofox navigate <url>` | `POST /tabs/:tabId/navigate` |
| Screenshot | `camofox screenshot` | `GET /tabs/:tabId/screenshot` |

Ref format reminder:
- Camofox refs are `eN` values (example `e1`, `e2`) in normal command usage.
- Some subcommands accept bracketed values in form assignments (`[e1]="value"`).

## 2) Anti-Detection Overview (Camoufox-specific)

Camofox differs from generic browser tools by using Camoufox launch options and per-profile fingerprint persistence:
- Camoufox launch via `camoufox-js` (`launchOptions`)
- Generated fingerprint (`generateFingerprint`) persisted per profile dir
- Humanization enabled (`humanize: true`)
- Proxy-aware geo behavior (`geoip: true` when proxy configured)
- Persistent contexts per user (`~/.camofox/profiles/<user>`) to keep believable identity continuity

Operational anti-detection behaviors:
- Stable identity per `userId`
- Optional proxy credentials from `PROXY_HOST/PORT/USERNAME/PASSWORD`
- Optional headed/virtual display modes with Xvfb fallback on Linux

Execution behavior that helps evade brittle bot checks:
- Persistent profile directories avoid fresh-device fingerprints every run.
- Consistent session reuse lowers abrupt storage/token churn.
- Engine-level spoofing avoids fragile JS-patch race with site updates.

See deep-dive: `references/anti-detection.md`.

## 3) Essential CLI Commands (quick reference)

Core:
```bash
camofox open <url> [--user <user>] [--viewport <WxH>] [--geo <preset>]
camofox close [tabId] [--user <user>]
camofox snapshot [tabId] [--user <user>]
camofox click <ref> [tabId] [--user <user>]
camofox type <ref> <text> [tabId] [--user <user>]
```

Navigation + interaction:
```bash
camofox navigate <url> [tabId] [--user <user>]
camofox screenshot [tabId] [--output <file>] [--full-page] [--user <user>]
camofox fill '[e1]="john" [e2]="john@example.com"' [tabId] [--user <user>]
camofox press Enter [tabId] [--user <user>]
```

Inspection:
```bash
camofox get-text [tabId] [--selector <css>] [--user <user>]
camofox get-links [tabId] [--user <user>]
camofox eval '<js expression>' [tabId] [--user <user>]
camofox wait <selector|navigation|networkidle> [tabId] [--timeout <ms>] [--user <user>]
```

Search:
```bash
camofox search "openclaw plugin" --engine github [tabId] [--user <user>]
```

Full catalog (all 50): `references/cli-commands.md`.

Global flag reminders:
```bash
--user <user>
--port <port>
--format json|text|plain
```

## 4) Essential API Endpoints (quick reference)

API Documentation:
- Interactive docs: `GET /api/docs` (Swagger UI)
- OpenAPI 3.1.0 spec for a representative subset of routes: `GET /openapi.json`

Core tab flow:
```bash
POST   /tabs
GET    /tabs
POST   /tabs/:tabId/navigate
GET    /tabs/:tabId/snapshot
POST   /tabs/:tabId/click
POST   /tabs/:tabId/type
DELETE /tabs/:tabId
```

State + assets:
```bash
POST   /sessions/:userId/cookies
GET    /tabs/:tabId/cookies
GET    /tabs/:tabId/screenshot
GET    /tabs/:tabId/downloads
GET    /users/:userId/downloads
```

Advanced:
```bash
POST   /tabs/:tabId/evaluate
POST   /tabs/:tabId/evaluate-extended
POST   /tabs/:tabId/extract-resources
POST   /tabs/:tabId/batch-download
POST   /tabs/:tabId/resolve-blobs
```

OpenClaw compatibility routes:
```bash
GET    /
POST   /tabs/open
POST   /start
POST   /stop
POST   /navigate
GET    /snapshot
POST   /act
```

Full endpoint map (all 54): `references/api-endpoints.md`.

Compatibility warning:
- The `camofox_youtube_transcript` tool has been re