> ## 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.

# 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.** If `codex` is absent from the image, the harness 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>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>timeout</code></td><td style={{ whiteSpace: 'nowrap' }}>int / null</td><td>unset</td><td>integer ≥ 1 or <code>null</code></td><td>Wall-clock timeout for the complete Codex task.</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>
</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 `results/<benchmark>/<model>/<run>/` (see [Results](/en/user_guide/results)).