ClawBench Documentation

repository·main·Indexed 19 days ago

https://github.com/tiger-ai-lab/clawbench

An open-source benchmarking framework for evaluating AI browser agents on real-world online tasks across live websites. It features a 5-layer recording pipeline and an agentic evaluator that compares AI trajectories against human reference runs. The framework includes the clawbench-eval package, support for Docker-isolated harnesses or Browserbase runtime, and datasets for V1 (153 tasks) and V2 (130 tasks) corpora.

Tokens
36.4K
Snippets
89
Records
153
Agent score
66%

What's inside ClawBench

  1. Overview of ClawBench Benchmark

    main

    ClawBench is an open-source benchmark designed to evaluate AI browser agents on everyday online tasks (e.g., booking travel, ordering food, applying for jobs, managing email) across live websites.

    Key features include:

    • Task Coverage: V1 contains 153 tasks across 144 websites; V2 contains 130 tasks.
    • Evaluation Methodology: Measures end-to-end task success using a 5-layer recording pipeline and an agentic evaluator that compares agent runs against human references.
    • Environment: Runs on any Chrome browser and utilizes Docker-isolated harnesses for execution.
    • Performance Context: Current top scores are approximately 33.3%.
  2. Overview of ClawBench

    main

    ClawBench is an open-source benchmark designed to evaluate the performance of AI browser agents on everyday online tasks, such as booking hotels, ordering food, submitting resumes, and managing emails across real-world websites.

    Benchmark Versions

    • V1: Located in test-cases/v1/, containing 153 tasks covering 144 websites.
    • V2: Located in test-cases/v2/, containing 130 tasks.

    Evaluation Methodology

    ClawBench measures end-to-end task completion rates using:

    1. A 5-layer recording pipeline.
    2. An agentic evaluator that compares agent actions against human reference trajectories.

    Currently, the highest recorded score is 33.3%.

  3. What the ClawBench Runtime Server does

    main

    The ClawBench Runtime Server is a Python-based instrumentation server (FastAPI) that connects to Chromium via the Chrome DevTools Protocol (CDP). It is used to instrument browser sessions for benchmarking by:

    • Capturing DOM actions: Injected listeners store actions in actions.jsonl format.
    • Capturing screenshots: Saves screenshots via CDP.
    • Logging HTTP requests: Monitors and can block specific requests using the CDP Fetch domain.
    • Recording video: Records the local Xvfb display to recording.mp4 (local mode) or manages remote provider URLs (provider mode).
    • Bridging remote browsers: Provides a credential-free WebSocket bridge and discovery endpoints when using remote browsers (e.g., Browserbase), keeping sensitive credentials out of harness logs and metadata.
  4. Track StructEval promotion pull requests

    main

    The structeval-promotion-pr-tracker.md document maintains a registry of pull requests from various external repositories that have added StructEval (a TMLR 2025 benchmark for structured-output generation and cross-format conversion) to their respective catalogs.

    This tracker is useful for monitoring the adoption of StructEval across different domains such as:

    • LLM Evaluation & Benchmarking: General LLM, MLLM, and VLM evaluation lists.
    • Domain-Specific Catalogs: JSON Schema, XML, YAML, CSV, and Code-specific resource lists.
    • Specialized AI Fields: Generative UI, AI Agents, Prompt Engineering, and Multimodal Reasoning.

    The tracker categorizes submissions by repository, pull request link, fit/rule check details, and current status (Open, Merged, or Closed).

  5. Understand the ClawBench Chrome Extension responsibilities

    main

    The ClawBench Chrome Extension is designed for browser fingerprint hardening during benchmark runs.

    Key Responsibilities:

    • Stealth Injection: Injects stealth.js at document_start in the page's MAIN world to patch window and navigator objects before any page JavaScript executes.
    • Anti-Bot Detection: Applies patches for webdriver, plugins, WebGL, permissions, and other browser fingerprints to reduce detection by systems like reCAPTCHA and Cloudflare Turnstile.

    Important Note on Data Flow:

    • The extension does not send data to the server.
    • Action capture (clicks, keystrokes), screenshot capture, request logging, request interception, and tab activation are handled by the runtime server via the Chrome DevTools Protocol (CDP).
  6. Configure the Evidence Trust Model and Tamper Resistance

    main

    Because EdgeBench submits an agent-controlled archive, the Judge does not automatically trust the intercepted flag in interception.json. Instead, it recomputes Stage-1 verification by matching submitted requests against the task's eval_schema (URL pattern, method, and body/params).

    To prevent an agent from fabricating matching requests (full tamper-resistance), use a shared secret:

    1. Set CLAWBENCH_EVIDENCE_SECRET in both the trusted runtime/entrypoint and the Judge via SFORGE_JUDGE_EXTRA_ENV.
    2. The runtime will sign each intercepted request using HMAC-SHA256(secret, canonical-json(request)).
    3. The Judge will reject any evidence that is unsigned or forged.

    Warning: Never provide CLAWBENCH_EVIDENCE_SECRET to the agent.

  7. Understand ClawBench evaluation metrics

    main

    ClawBench uses a multi-stage evaluation process to grade AI agents on their ability to complete online tasks. The primary metrics used in the V2 (Hermes) leaderboard are:

    • Intercepted: A deterministic Stage 1 metric. It checks if the final HTTP request made by the agent matched the task's target URL and method.
    • Reward (lenient): A Stage 2 metric where a judge LLM (deepseek/deepseek-v4-pro) evaluates if the instruction was fulfilled using a "no contradiction $\rightarrow$ match" rubric.
    • Reward (strict): A Stage 2 metric using the same judge but with a stricter rubric where any ambiguity results in a mismatch.

    In V1 evaluations, the Pass Rate was determined by a Claude Code agentic-eval subagent comparing runs against human reference trajectories.

  8. How ClawBench scoring works

    main

    ClawBench uses a two-stage scoring process to evaluate if an AI agent successfully completed an online task. A task is only considered a success (final_pass: true) if it passes both stages.

    1. Stage 1: Final-request interception: A request interceptor inside the sandbox blocks the final outgoing HTTP request that matches the task's eval_schema (URL pattern and method). This captures the agent's 'commit-intent' (e.g., a POST request to submit a form) before it hits the live web.
      • If the request does not match the schema, intercepted: false and reward = 0.
    2. Stage 2: LLM judge: For intercepted requests, an LLM judge reviews the intercepted request body against the natural-language instruction. The judge returns match: true if the body satisfies the instruction, or match: false otherwise.

    Final Score Logic: final_pass = intercepted AND (judge_match is True)

    Aggregate Metrics:

    • intercepted_rate = sum(intercepted) / N
    • reward_rate = sum(intercepted ∧ judge_match) / N (where N is the total number of tasks in the corpus).
    final_pass = intercepted AND (judge_match is True)
  9. Compare ClawBench to other web benchmarks

    main

    ClawBench is specifically designed to evaluate agents on live consumer websites performing everyday tasks with end-to-end recordings.

    Key differentiators from other benchmarks include:

    • WebArena: Uses synthetic web apps/self-hosted replicas; ClawBench uses live consumer sites.
    • GAIA: Focuss on closed-book text + tools; ClawBench is browser-centric and end-to-end.
    • SWE-bench: Focuses on software engineering/GitHub; ClawBench focuses on non-code consumer workflows.
    • Mind2Web: Uses static traces; ClawBench uses dynamic live websites.
    • WebVoyager: Uses LLM-judge-only; ClawBench uses interception-graded metrics.
    • TheAgentCompany: Focuses on enterprise/office sandboxes; ClawBench focuses on consumer everyday tasks.
  10. Configure the Request Interceptor with eval_schema

    main

    The eval_schema field in task.json allows you to define a request interceptor. When a request matches the specified criteria, the interceptor blocks the request, records it in data/interception.json, and stops the container. This is useful for detecting when an agent attempts an irreversible action (like a POST request to a submission endpoint).

    Fields in eval_schema:

    • url_pattern (Required): A regex string matched against request URLs using re.search().
    • method (Required): The HTTP method to match (e.g., POST, GET).
    • body (Optional): Exact key-value filters for parsed request bodies.
    • params (Optional): Exact key-value filters for URL query parameters.

    Note: If no interception is needed, use "__PLACEHOLDER_WILL_NOT_MATCH__" as the url_pattern to allow the session to run until other stop conditions are met.

  11. How ClawBench integrates with Polar (ProRL)

    main

    The integration uses a "Harness as Environment" model. Instead of ClawBench emitting token IDs, the Polar Rollout Server (:8080) uses a Gateway node to proxy and capture the policy's LLM calls. This creates a token-faithful trajectory (token IDs + logprobs + loss mask) without requiring the agent to perform special logic.

    The integration components include:

    • TaskRequest models (models.py): Typed payloads for Polar submissions.
    • Submission client (submit.py): Manages the lifecycle of a task submission.
    • Shell-harness entry (run-prorl.sh): Routes the policy model via $OPENAI_BASE_URL and $OPENAI_API_KEY while exporting necessary environment variables (BASE_URL, API_KEY, API_TYPE, MODEL_NAME, INSTRUCTION) for the harness runners.
    • Topology template (topology.example.yaml): A fleet configuration for rollout, gateway, and inference nodes.
    • Offline mock (mock_gateway.py): A tool for contract testing the Rollout-Server and harbor-evaluator without requiring GPUs or a browser.
  12. ClawBench Container Architecture

    main

    The ClawBench runtime operates within a container (Docker or Podman) to provide a controlled environment for browser automation. The architecture consists of:

    • Chromium: Running on port :9222 via CDP (Chrome DevTools Protocol) to handle fetch, runtime, and page events.
    • Xvfb: A virtual framebuffer running on port :99 to manage the display.
    • FastAPI Server: Running on port :7878, which interfaces with Chromium and captures video via ffmpeg using x11grab from Xvfb.
    • Data Storage: The /data directory persists the following artifacts:
      • actions.jsonl: Log of agent actions.
      • requests.jsonl: Log of HTTP requests.
      • screenshots/: Directory of captured screenshots.
      • recording.mp4: The full video recording of the session.
    ┌─────────────────────────────────────────────────┐
    │  Container (Docker / Podman)                    │
    │                                                 │
    │  ┌──────────┐  CDP Fetch/Runtime/Page events    │
    │  │ Chromium ├─────────────────────────────┐     │
    │  │ :9222 CDP│                             │     │
    │  └──────────┘                             │     │
    │                                           │     │
    │  ┌──────────┐            ┌────────────────▼─┐   │
    │  │  Xvfb    │◄──ffmpeg──►│  FastAPI Server  │   │
    │  │ :99      │  x11grab   │  :7878           │   │
    │  └──────────┘            └──────────────────┘   │
    │                                  │              │
    │                          ┌───────▼─────────┐    │
    │                          │     /data       │    │
    │                          │  actions.jsonl  │    │
    │                          │  requests.jsonl │    │
    │                          │  screenshots/   │    │
    │                          │  recording.mp4  │    │
    │                          └─────────────────┘    │
    └─────────────────────────────────────────────────┘