> ## Documentation Index
> Fetch the complete documentation index at: https://obversa.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI Engine

> @obversa/engine-codex-cli: Codex as a seat, one fresh process per call.

`@obversa/engine-codex-cli` runs Codex as an engine: every request is one
fresh `codex` process. Use it to put an OpenAI model in a writing,
verification or review seat, and in particular as the reviewer of a Claude
seat, since a `workflow()` needs the two from different families.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @obversa/engine-codex-cli
  ```

  ```bash pnpm theme={null}
  pnpm add @obversa/engine-codex-cli
  ```
</CodeGroup>

Included in `@obversa/obversa`.

## Requirements

* The Codex CLI installed and signed in. The `codex` command must be on
  your `PATH`, or you pass its path as `cliBinary`.

## Identity

The plugin reports `provider: 'openai'` and model family `gpt`. It runs the
model the request names, or `defaultModel` when the request names none;
with neither set, the CLI runs without a model flag.

## Quickstart

`codex(model)` is the seat helper a `workflow()` role takes:

```ts examples/teams/writer-reviewer-pair.ts (excerpt) {3} theme={null}
    roles: {
      write: engines.claude('claude-sonnet-4-5'),
      review: [engines.codex('gpt-5.6-luna')],
    },
```

The seat runs Codex sandboxed to the workspace with approvals off. Pass
`CodexSeatOptions` (`sandbox`, `approvalPolicy`) to choose otherwise.
`new CodexEngine(options)` is the same engine without the seat identity.
The prompt goes through standard input, and the final message is read from
a temporary file.

## Options

### `sandbox`

Without a workspace mode or a `sandbox` option, Codex runs in its
`read-only` sandbox. The `write` workspace mode or `sandbox:
'workspace-write'` lets it write. `permissionMode: 'bypassPermissions'`
turns the sandbox off.

### `clean`

`true` runs Codex with `--ignore-user-config`. Your own `config.toml` stays
out, with your settings, MCP servers and plugins, and so does the
`AGENTS.md` in your Codex home folder. The repository's instruction files
still apply, and the run keeps your login. With your own settings out,
Codex runs its own default model unless the seat or request names one.
`CodexSeatOptions` takes the same `clean` option.

Its row in the [engines table](/docs/packages/engines#the-engines): runs on your
setup, clean mode available, read-only held in both modes. Your own skills
and command rules still load in clean mode: Codex has no switch that
leaves out your skills, and its switch for rules also leaves out the
repository's.

### The rest

| Field | Type | Default | Description |
| - | - | - | - |
| `defaultModel` | `string` | none | The model when the request names none. |
| `cliBinary` | `string` | `codex` on `PATH` | The executable to run. |
| `cliArgs` | `readonly string[]` | none | Extra arguments for every call. |
| `approvalPolicy` | `'on-request' \| 'never'` | none | Codex's approval policy. |
| `permissionMode` | as Claude's | none | `bypassPermissions` turns the sandbox off. |
| `effort` | `string` | none | Passed as `-c model_reasoning_effort=<level>`, over your own Codex config. Allowed in a workspace mode, unlike `cliArgs`. A request's `effort` wins. Also a `CodexSeatOptions` field. See [Reasoning effort](/docs/packages/engines#reasoning-effort). |
| `clean` | `boolean` | [See the default](/docs/packages/engines#the-default) | On by default: your own setup stays out. `false` runs on your own setup. [`clean`](#clean). |

## Errors

* **`EngineError` of kind `missing-cli`** when the executable can't run.

## API

* **`codex(model, options?)`**: a `TeamSeat` for a workflow role.
  [Quickstart](#quickstart).
* **`CodexEngine`**: the engine class. **`CodexEngineOptions`**,
  **`CodexSeat`**, **`CodexSeatOptions`**: its types.
* **`buildCodexArgs`**: the argument builder, exported for tests.

## Next steps

* [A review panel with a threshold](/docs/patterns/review-panel): a Codex seat
  and an OpenCode seat reviewing a Claude seat.
* [Runtime](/docs/packages/runtime#declare-a-team): the roles a seat fills.


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