> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

The `openclaw` harness runs an [OpenClaw](https://openclaw.ai) agent inside a prepared environment's container, driving the model-under-test through tasks one at a time — commonly used for OpenClaw-style productivity / agentic-coding benchmarks (such as [PinchBench](/en/user_guide/modules/benchmarks/pinchbench) and [SkillsBench](/en/user_guide/modules/benchmarks/skillsbench)).

You only need to provide the model's access credentials; the harness handles the rest: it installs `openclaw` in the container, onboards your model to OpenClaw as a callable custom model, then runs the tasks one by one and collects the results. Credentials are passed on the command line via `--model-base-url` / `--model-api-key`, and both the `openai-chat` and `openai-responses` `--model-api-protocol` protocols are supported.

## Parameters

Pass a chunk of JSON via `--harness-params '{...}'`, or write it into the `harness.params` block of the YAML given to `--config`; on shared keys the command line wins (deep-merge override). For merge and precedence, see the [Harnesses overview](/en/user_guide/modules/harnesses/overview).

### Parameter reference

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'1080px', width:'100%', tableLayout:'fixed'}}>
    <thead>
      <tr><th style={{width:'22%', whiteSpace:'nowrap'}}>Parameter</th><th style={{width:'12%', whiteSpace:'nowrap'}}>Type</th><th style={{width:'20%', whiteSpace:'nowrap'}}>Default</th><th style={{width:'12%'}}>Choices / values</th><th style={{width:'34%'}}>Description</th></tr>
    </thead>

    <tbody>
      <tr><td style={{whiteSpace:'nowrap'}}><code>binary</code></td><td>string</td><td><code>openclaw</code></td><td>—</td><td>Name or full path of the <code>openclaw</code> executable; usually no need to change.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_strategy</code></td><td>string</td><td><code>auto</code></td><td>5 options</td><td>How to prepare <code>openclaw</code> in the container; 5 in total (see <a href="#install-strategy">Install strategy</a> below).</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>openclaw\_version</code></td><td>string</td><td><code>2026.3.22</code></td><td>—</td><td>The <code>openclaw</code> version used when auto-installing; only takes effect when <code>install\_strategy</code> triggers an install.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_command</code></td><td>string</td><td><code>""</code></td><td>—</td><td>Custom install command. When empty, it is auto-assembled from <code>openclaw\_version</code> as <code>npm install -g openclaw@\<version></code>.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>upload\_src</code></td><td>string</td><td><code>""</code></td><td>—</td><td>Only used when <code>install\_strategy</code> is the <a href="#install-strategy"><code>upload</code> strategy</a>: the path to the <code>openclaw</code> executable on the local machine (the one running AgentCompass) to upload; required under that strategy.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>upload\_dst</code></td><td>string</td><td><code>/usr/local/bin/openclaw</code></td><td>—</td><td>Only used when <code>install\_strategy</code> is the <a href="#install-strategy"><code>upload</code> strategy</a>: the destination path inside the container, which is also the <code>openclaw</code> path actually used at runtime.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>provider\_id</code></td><td>string</td><td><code>vllm</code></td><td>—</td><td>The name your model is registered under in OpenClaw; keep the default unless you need to align with a name in existing config.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>gateway\_port</code></td><td>int</td><td><code>18789</code></td><td>≥ 1</td><td>The local port OpenClaw uses to reach your model; change it only if it conflicts with another service.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>gateway\_bind</code></td><td>string</td><td><code>loopback</code></td><td>—</td><td>The gateway's listen scope; defaults to <code>loopback</code> (localhost only).</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>openclaw\_local</code></td><td>bool</td><td><code>true</code></td><td><code>true</code> / <code>false</code></td><td>Whether to run OpenClaw in local mode (<code>--local</code>); on by default.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>brave\_api\_key</code></td><td>string</td><td><code>{"${BRAVE_API_KEY}"}</code></td><td>—</td><td>Injects a Brave Search API key into OpenClaw; when provided, OpenClaw can use Brave for <code>web\_search</code>. When not explicitly provided, <code>web\_search</code> may be limited or unavailable. See the <a href="https://docs.openclaw.ai/tools/web">OpenClaw Web Search documentation</a>.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_message\_chars</code></td><td>int</td><td><code>131072</code></td><td>≥ 1</td><td>Maximum characters in a single message sent to the model; longer messages are automatically split into several sent in sequence.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_tokens</code></td><td>int</td><td><code>0</code></td><td>≥ 0</td><td>Max output tokens for a single model reply; <code>0</code> means unset, using the model's own default. See <a href="#context-and-token-limits">Context and token limits</a> below.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>context\_window</code></td><td>int</td><td><code>250000</code></td><td>≥ 0</td><td>Tells OpenClaw how long a context your model accepts; <code>0</code> means unset. For custom models, set the real value; see <a href="#context-and-token-limits">Context and token limits</a> below.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>timeout</code></td><td>int / null</td><td><code>9600</code></td><td>≥ 1</td><td>Total time limit for a single task from start to finish (seconds); aborted on timeout. <code>null</code> means no limit.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>provider\_timeout\_seconds</code></td><td>int</td><td><code>3600</code></td><td>—</td><td>How long the model service can stay idle before being reclaimed (seconds).</td></tr>
    </tbody>
  </table>
</div>

### Install strategy

`install_strategy` decides how `openclaw` lands in the container:

* `auto` — applies an environment default (not a probing auto-install): [`host_process`](/en/user_guide/modules/environments/overview) uses `install_if_missing`, [other environments like docker](/en/user_guide/modules/environments/overview) use `preinstalled`. If `openclaw` isn't preinstalled on the image in docker and similar environments, `auto` errors out — switch it to `install_if_missing` or `upload` manually.
* `preinstalled` — uses what's already installed on the image; errors if absent.
* `install_if_missing` — installs only when `openclaw` is not present in the container.
* `install_always` — reinstalls on every run (some benchmarks pin `install_if_missing`, in which case the benchmark's setting takes precedence).
* `upload` — instead of installing from npm, uploads an existing `openclaw` executable from your local machine (the one running AgentCompass) into the container: it uploads from `upload_src` to `upload_dst`, adds the executable bit, and uses that file at runtime (`binary` automatically points to `upload_dst`, no need to set it separately). Suited to containers that can't reach npm, or when you want a self-compiled / pinned binary; `upload_src` is required in this case.

Setting `openclaw_version` is enough — `install_command` is auto-derived as `npm install -g openclaw@<version>`. Set `install_command` explicitly only when you need to point at an internal registry or a non-npm source.

### Context and token limits

`context_window` and `max_tokens` are written into `openclaw.json` only when **set greater than 0**, and are independent of each other.

* **`context_window`** — the model's total context length (corresponds to [vLLM](https://docs.vllm.ai/)'s `--max-model-len`). Setting it explicitly stops OpenClaw from falling back to an over-small default window when it can't recognize the model-under-test, which would trigger context compaction prematurely. When the value is `0`, AgentCompass does not write the field into `openclaw.json` and the window is left to OpenClaw: if OpenClaw has a built-in context window for the model, it uses that built-in value; if it's an unrecognized custom model, it falls back to a smaller default window and may compact the context before it has actually exceeded the limit, losing information and hurting long-task performance. Passing the model-under-test's real context length explicitly during evaluation is therefore recommended.
* **`max_tokens`** — the per-turn completion budget; it should be noticeably smaller than `context_window` so that "input tokens + `max_tokens`" doesn't exceed the served context length. When the value is `0` it is likewise not written into `openclaw.json`, and the model / server's own default output limit applies.

## Run examples

`openclaw` is passed as the second positional argument to `agentcompass run <benchmark> openclaw <model>`; harness config is passed via `--harness-params`.

<Tabs>
  <Tab title="Default configuration">
    OpenClaw is already installed on the image — run with the default parameters.

    ```bash theme={"system"}
    agentcompass run \
      pinchbench \
      openclaw \
      "$MODEL_NAME" \
      --env docker \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>

  <Tab title="Install a pinned version">
    When the container isn't preinstalled (or you want to switch versions), let the harness install a pinned version and give it a generous wall-clock timeout.

    ```bash theme={"system"}
    agentcompass run \
      gdpval_ac \
      openclaw \
      "$MODEL_NAME" \
      --env docker \
      --harness-params '{
        "install_strategy": "install_if_missing",
        "openclaw_version": "2026.5.7",
        "timeout": 14400
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>

  <Tab title="Custom provider and limits">
    Write the context window and per-turn token budget for a custom model, and pin the provider id.

    ```bash theme={"system"}
    agentcompass run \
      wildclawbench \
      openclaw \
      "$MODEL_NAME" \
      --env docker \
      --harness-params '{
        "provider_id": "vllm",
        "context_window": 262144,
        "max_tokens": 32768
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>
</Tabs>