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

# Codex

> Run agents on Codex: models, capabilities, tools, and how it differs from Claude Code.

Codex is the strongest harness on OpenAI models. paddock runs the real Codex CLI, unmodified, at the version it pins (currently **0.162.1**), through its `codex app-server` protocol, in each agent's sandbox.

```yaml theme={null}
spec:
  harness: codex
  model: gpt-5.5
```

## Models

Codex runs OpenAI models over the Responses API:

* The platform model `gpt-5.5`.
* Project models of an `openai` or `openai-compatible` provider, named `provider/model`. An `openai-compatible` endpoint must serve the Responses API. See [Models](https://docs.paddock.build/guides/models.md).

Codex chooses the tools it offers, among them `apply_patch` for editing files, from what it knows about the model name. A model it does not know runs without `apply_patch`, so the agent edits files through the shell. A project model whose ID Codex knows, such as `acme/gpt-5.5`, runs with the same tools as `gpt-5.5`.

Codex has one model setting; `small_model` is Claude Code only and is rejected on Codex.

## Capabilities

| Capability | Supported |
| - | - |
| MCP servers, remote and local | Yes |
| Marketplaces and plugins | Yes. Codex reads marketplaces in Claude Code's format and its own. A plugin's subagents are ignored and reported as a warning in `config.applied` and the harness status |
| Skills | Yes, from plugins: Codex lists skills in the model's context, and the model reads a skill's files with its ordinary tools, so there is no `skill` tool call |
| Workflows | No. `agent.workflows` is `422 unsupported`, and the harness status has no Workflows section |
| Memory | Yes |

Plugins are installed with `codex plugin` commands and MCP servers with `codex mcp`, then taken up by the running app-server without reloading the conversation. Changes apply between turns; see [Capabilities](https://docs.paddock.build/guides/capabilities.md).

## Configuration

| Setting | On Codex |
| - | - |
| System prompt | Codex's developer instructions, kept for the conversation's whole life |
| Permissions | Written as given to a Codex rules file. Codex runs with no approval prompts and full access to its sandbox, so test that your rules have the effect you expect |
| Environment | Set for every command Codex runs |
| Memory | Rendered into the session's `AGENTS.md`, which Codex reads at every model request |

## Tools

| paddock tool | Codex item |
| - | - |
| `shell` | `commandExecution` |
| `file_patch` | `fileChange`, with each changed path, its kind (`add`, `delete`, or `update`), and its diff |
| `web_search` | `webSearch` |
| `mcp` | `mcpToolCall` |
| `subagent` | A subagent activity: the spawn call and its result; the subagent's own items carry the call's ID as `parentToolUseId` |
| `unknown` | Any other tool item, such as `imageView` |

Codex edits files with patches, so its file changes are `file_patch` calls rather than `file_write` and `file_edit`. Its reasoning arrives as summaries in `reasoning` messages. Items paddock does not map, such as a plan or a context compaction, are `unknown` messages with their raw JSON.

## Harness status

Codex reports Context, Plugins, Skills, MCP, and Subagents; see [Harness status](https://docs.paddock.build/guides/harness-status.md). Its Context section has what Codex reports: the model, the usable window (95% of the model's window) beside the model's own, the auto-compact threshold, the tokens in use, the last request's input, cached, output, and reasoning tokens, the conversation's total, and the instruction files it loaded. Usage by category is not reported.

## Background work

Codex keeps background terminals and subagent threads running after a turn ends, and may continue a goal with a turn of its own: paddock records it as a **harness turn**, which consumes no message. Stopping a session ends the current turn and terminates that turn's own commands; background work started earlier keeps running.


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