> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

The `codex` harness runs the [OpenAI Codex CLI](https://github.com/openai/codex) non-interactively in a benchmark-prepared workspace.

## How it works

* **Prepare Codex CLI.** An optional Runtime Capsule supplies Node/npm first; if `codex` is absent, the harness then applies `install_strategy` and `install_command`.
* **Configure and run.** The harness writes a session-scoped Codex provider configuration and invokes the CLI non-interactively in the task workspace. Recipes may place this configuration outside the repository so it cannot enter a generated patch.
* **Collect results.** Codex JSON events are normalized into the trajectory, final answer, and execution status in a `RunResult`.

## Parameters

Pass harness options with `--harness-params '{...}'`. The table exposes the installation, provider, and execution behavior that normally needs tuning; path and upload details use built-in defaults.

### Parameter reference

<div style={{ overflowX: 'auto' }}>
  <table style={{ minWidth: '1040px', width: '100%' }}>
    <thead>
      <tr><th style={{ whiteSpace: 'nowrap' }}>Parameter</th><th style={{ whiteSpace: 'nowrap' }}>Type</th><th style={{ whiteSpace: 'nowrap' }}>Default</th><th style={{ whiteSpace: 'nowrap' }}>Choices / values</th><th>Description</th></tr>
    </thead>

    <tbody>
      <tr><td style={{ whiteSpace: 'nowrap' }}><code>install\_strategy</code></td><td style={{ whiteSpace: 'nowrap' }}>string</td><td><code>install\_if\_missing</code></td><td><code>preinstalled</code> / <code>install\_if\_missing</code> / <code>upload</code></td><td>How to prepare Codex.</td></tr>
      <tr><td style={{ whiteSpace: 'nowrap' }}><code>install\_command</code></td><td style={{ whiteSpace: 'nowrap' }}>string</td><td><code>npm install -g @openai/codex</code></td><td>shell command</td><td>Command used when Codex is missing.</td></tr>
      <tr><td style={{ whiteSpace: 'nowrap' }}><code>setup\_capsule\_tag</code></td><td style={{ whiteSpace: 'nowrap' }}>string</td><td>unset</td><td><code>node24-v1</code></td><td>Optional predefined Node toolchain Capsule injected before Codex installation.</td></tr>
      <tr><td style={{ whiteSpace: 'nowrap' }}><code>sandbox</code></td><td style={{ whiteSpace: 'nowrap' }}>string</td><td><code>workspace-write</code></td><td><code>read-only</code> / <code>workspace-write</code> / <code>danger-full-access</code></td><td>Codex sandbox policy.</td></tr>
      <tr><td style={{ whiteSpace: 'nowrap' }}><code>reasoning\_effort</code></td><td style={{ whiteSpace: 'nowrap' }}>string</td><td>unset</td><td>provider-supported effort</td><td>Value written to Codex as <code>model\_reasoning\_effort</code>.</td></tr>
      <tr><td style={{ whiteSpace: 'nowrap' }}><code>dangerously\_bypass\_approvals\_and\_sandbox</code></td><td style={{ whiteSpace: 'nowrap' }}>bool</td><td><code>true</code></td><td><code>true</code> / <code>false</code></td><td>Whether to pass <code>--dangerously-bypass-approvals-and-sandbox</code>. Set it to <code>false</code> only when the Codex approval and sandbox flow must be retained.</td></tr>
    </tbody>
  </table>
</div>

### Model API

Codex requires an OpenAI-compatible `--model-base-url` and `--model-api-key`. `--model-api-protocol openai-responses` selects the Responses API and `openai-chat` selects Chat Completions; the CLI protocol takes precedence over the harness's internal `wire_api` fallback. The harness appends `/v1` when it is absent from the base URL.

## Run examples

<Tabs>
  <Tab title="Default">
    Run with the default installation and workspace-write policy.

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

  <Tab title="Custom params">
    Use the Chat Completions endpoint and adjust the sandbox.

    ```bash theme={"system"}
    agentcompass run \
      swebench_verified \
      codex \
      "$MODEL_NAME" \
      --env docker \
      --harness-params '{"sandbox":"workspace-write"}' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>

  <Tab title="Runtime Capsule">
    Use a `node24` Capsule in an Environment without compatible Node, npm, or glibc.

    ```bash theme={"system"}
    agentcompass run \
      swebench_verified \
      codex \
      "$MODEL_NAME" \
      --env docker \
      --harness-params '{
        "install_strategy": "install_if_missing",
        "install_command": "npm install -g @openai/codex@<version>",
        "setup_capsule_tag": "node24-v1"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-responses
    ```
  </Tab>
</Tabs>

## Output

The harness returns a `RunResult` per task: trajectory, final answer, and execution status. Per-task details and aggregate metrics are written by the benchmark under the [run directory](/en/user_guide/other_features/results/overview#directory-layout) (see [Results](/en/user_guide/other_features/results/overview)).

Set the task execution deadline through `--execution-params` with `run_timeout_seconds` and `run_timeout_multiplier`. See [phase timeouts](/en/user_guide/using_agentcompass/timeouts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.