Codex

codex_local runs OpenAI's Codex CLI on the same machine as Paperclip. Use it when you want a local coding agent with persistent session state, managed CODEX_HOME, and Paperclip skills injected into the Codex skills directory.

When To Use

• You already use the Codex CLI on the host machine.
• You want session continuity across heartbeats.
• You want Paperclip to manage a per-company Codex home when possible.
• You want repo instructions, Paperclip instructions, and Codex's own runtime behavior to work together.

When Not To Use

• The runtime lives behind a webhook or remote API. Use HTTP.
• You only need a shell command or script. Use Process.
• Codex CLI is not installed or cannot be executed from the Paperclip host.

Common Fields

Note: Codex sends the prompt through stdin and uses codex exec --json. The adapter's environment test checks both the command and the auth path before you try to run a real heartbeat.

Permissions

Codex agents run in full-auto mode by default. If you leave dangerouslyBypassApprovalsAndSandbox unset, Paperclip passes --dangerously-bypass-approvals-and-sandbox, so Codex works through a task without pausing for approvals that no one is around to give.

You stay in control when you say otherwise. Paperclip skips the bypass — keeping Codex in its writable workspace sandbox, or in the mode you picked — when any of these is true (the last three only count while dangerouslyBypassApprovalsAndSandbox is unset):

• You set dangerouslyBypassApprovalsAndSandbox to false.
• Your extraArgs pick a sandbox mode or profile yourself — for example --sandbox, --profile, --full-auto, or a sandbox_mode= config override.
• Your extraArgs set an approval_policy= override, or switch network access off with sandbox_workspace_write.network_access=false.
• The execution target denies network access.

This bypass applies to the classic Codex CLI lane (engine: "cli"). The ACP engine keeps Codex in its writable workspace sandbox, with network access switched on for each turn.

Heads-up: Earlier versions kept Codex in the workspace sandbox unless you opted in to the bypass. If you relied on that, set dangerouslyBypassApprovalsAndSandbox to false explicitly.

ACP Engine

Codex can run through one of two engines — ACP or the classic Codex CLI — selected by the engine field:

• auto (default) — ACP. Paperclip runs Codex through the Agent Client Protocol (ACP). If the host doesn't meet the ACP prerequisites, the run fails with a setup error explaining why — Paperclip never switches engines on its own.
• acp — always ACP. Force the Agent Client Protocol path.
• cli — always the Codex CLI. Force the classic CLI wrapper and skip ACP entirely.

ACP gives you a richer, structured live transcript: session identity, status with context-window usage, assistant and thinking token deltas, and tool-call updates that fold into a single card as they progress. That extra detail is most useful when you're watching a sandbox run stream in.

When the engine resolves to ACP (auto or acp), these extra fields apply:

Heads-up: ACP is where the old standalone acpx_local adapter's capabilities now live. That adapter has been retired — pick codex_local (or claude_local / gemini_local) and leave engine on auto to get ACP by default.

ACP in sandbox environments

You can keep engine on auto when this agent runs in a Paperclip sandbox environment. If that sandbox provides Paperclip's bidirectional process session, Paperclip keeps the ACP engine and its structured live transcript; you do not add a separate bridge setting to the adapter config.

An environment that only runs one-shot commands cannot host an ACP session, so an auto run there fails with a setup error rather than switching to the Codex CLI. Set engine: "cli" when you want the CLI lane — for example on such environments.

Models

Pick any of the known Codex model ids in the model field. The picker lists them the way the ChatGPT app orders Codex models — newest model version first, most capable first within each version, and older models at the end:

• gpt-6.1-sol
• gpt-6-astra
• gpt-6-sol
• gpt-6-luna
• gpt-5.6-sol (the adapter default)
• gpt-5.6-terra
• gpt-5.6-luna
• gpt-5.5
• gpt-5.4
• gpt-5.4-mini
• gpt-5
• gpt-5-mini
• gpt-5-nano
• o3
• o4-mini
• o3-mini
• codex-mini-latest

This is a curated list. Even when an OpenAI API key is available, the picker doesn't fill itself from OpenAI's model catalog, because that catalog also includes image, audio, and embedding models Codex can't run. If you need extra models in the dropdown — say, ones served through your own gateway — declare them with PAPERCLIP_ADAPTER_MODELS.

You can also type a model id that is not in this list. Anything Paperclip does not recognize is treated as a manual model id and passed straight through to the Codex CLI.

Heads-up: The default is now the concrete gpt-5.6-sol slug. The bare gpt-5.6 alias has no OpenAI-published metadata, so Paperclip rewrites gpt-5.6 to gpt-5.6-sol automatically — an agent still configured with the old alias keeps working and stops triggering the CLI's "model metadata not found" warning.

Tip: Leave model empty to let Codex choose. When no model is set, the adapter omits the --model flag entirely so the Codex CLI falls back to its own default model.

Reasoning Effort

The modelReasoningEffort choices follow the model you pick:

If you switch to a model that doesn't support the effort you had selected, the agent form clears the effort so it falls back to Auto.

Model Profiles

A model profile is a named alternative to the agent's main model settings, so you can run the same agent on a different lane without rewriting its adapter config. Codex ships one profile, and it comes from the adapter itself (source: "adapter_default"), so every codex_local agent has it available:

The important part is explicitly configured: the cheap profile ships with an empty adapterConfig, so it does not choose a model for you. Enabling it changes nothing until you fill in what the cheap lane should use — normally a model, and optionally an override such as modelReasoningEffort. You decide which model counts as cheap for this agent, and the primary model in your adapter config stays exactly as it is.

Heads-up: cheap used to hard-code a specific Codex model and reasoning effort for you. It no longer does. If you were relying on that, set the model you want on the profile yourself.

New Codex agents start with this profile switched off. When an agent is created and its runtime config does not already mention cheap, Paperclip records modelProfiles.cheap = { enabled: false } — the profile is present but dormant, waiting for you to configure it and turn it on.

Session Persistence

Codex preserves the previous_response_id chain so heartbeats can continue the same conversation instead of starting fresh each time.

The session codec also preserves these location hints when present:

• cwd
• workspaceId
• repoUrl
• repoRef

If the working directory changes, the adapter starts a fresh session instead of reusing the old response chain.

Native Codex on Paperclip Runner

Codex can also run natively through Paperclip Runner (paperclip_runner with provider: "codex") rather than through codex_local. A few behaviors are specific to that native path:

• Restarts don't cost you the conversation. If a server restart kills a native Codex turn mid-flight, Paperclip first makes sure the old process is really gone. Then it resumes the request once, in the same conversation and workspace, and asks the agent to check any unfinished commands or outside actions before carrying on. It doesn't resend the task. The run log records the interrupted turn with provider_turn_lost_on_restore. Anything that can't be reconciled still stops for a person.
• Codex keeps its own base prompt. Paperclip sends its task context as additive developerInstructions when a thread starts or resumes, so Codex's stock base instructions stay in place. Conversations created before this change keep their saved prompt when resumed; reset those sessions if you want the stock base instructions back.
• A model your ChatGPT account can't use says so. When Codex rejects the selected model for a ChatGPT sign-in, the task shows Model unavailable. with "The selected model is not supported by the current ChatGPT connection. Choose a supported model or a compatible AI connection." Paperclip doesn't retry that request automatically. Choose a supported model or clear the task's model override, then retry.
• A busy model retries on its own. When the selected model is at capacity, Paperclip shows Model at capacity and retries after one minute, then after two. See When a run needs attention.

Skills Injection

Codex injects Paperclip skills into the effective CODEX_HOME/skills directory.

In the default managed-home mode, Paperclip uses a per-company Codex home under the active Paperclip instance and seeds it from the shared Codex home for auth continuity.

When Paperclip runs inside a managed worktree instance, that Codex home is worktree-isolated so sessions, logs, and skills do not leak across checkouts.

For manual local CLI use outside Paperclip, run:

pnpm paperclipai agent local-cli codexcoder --company-id <company-id>

That command installs missing skills, creates an agent API key, and prints shell exports you can use to run Codex as that agent.

Instructions File

If you set instructionsFilePath, Paperclip reads that file and prepends it to the stdin prompt sent to codex exec on every run.

That is separate from Codex's own repo instruction discovery. If the working directory contains an AGENTS.md, Codex can still load it as part of its normal behavior.

Tip: Use instructionsFilePath for Paperclip-managed instructions. Use repo-local instruction files when you want Codex to pick them up naturally from the workspace.

Authentication And Per-Agent Homes

Each codex_local agent runs against its own managed Codex home, so one agent can never spend against another agent's login or share its Codex state. Because that home starts empty, Paperclip seeds credentials into it for you before launching Codex:

• You inherit the host Codex login by default. If you are already signed in to Codex on the Paperclip host (a ChatGPT-subscription login), Paperclip links that login into the agent's managed home automatically. You do not have to log in again per company or per agent.
• A per-agent API key wins when you set one. If the agent's env carries an OPENAI_API_KEY, Paperclip writes that key into the managed home as API-key auth instead of borrowing the host login. On the ACP engine, CODEX_API_KEY works the same way as an alternative name for that key.
• Your own CODEX_HOME is left alone. If you point the adapter at a CODEX_HOME outside Paperclip's managed company tree, Paperclip treats it as self-managed and never seeds or overwrites it.
• No silent credential-less runs. If a managed home ends up with no usable login and no configured API key, the run fails fast with a clear adapter error instead of starting Codex and hitting a 401 from the provider.

Signing in inside a sandbox

When an agent runs in a Paperclip sandbox environment that has no ready Codex login, the environment test reports that authentication is missing and Paperclip can start an interactive device login for you. Complete the login in your browser and Paperclip promotes the resulting subscription credential into the company scope so later heartbeats reuse it.

Paperclip also keeps a company-scoped, identity-keyed cache of subscription credentials (one usable credential per account), so a fresher login recovered from a sandbox run can refresh an account the host already holds. The cache never seeds an empty host and never switches which account an agent uses. It is on by default; set PAPERCLIP_CODEX_AUTH_CACHE to a falsy value (0, false, no, or off) on the Paperclip host to turn it off.

CODEX_HOME sync into a sandbox

When this agent runs in a Paperclip sandbox, the adapter does not copy your whole Codex home into the sandbox. Instead it stages an explicit allowlist, so only the material a run actually needs crosses the boundary and none of your host-local runtime state comes along for the ride. The synced entries are:

• config.json
• config.toml
• instructions.md
• auth.json
• skills

Everything the stock codex binary writes at runtime — session databases (*.sqlite, *-wal), plugins/, cache/, sessions/, shell_snapshots/, and the like — stays on the host and is intentionally left out. This allowlist only applies to sandboxed execution; local and SSH targets read the managed home in place.

Environment Test

The Test Environment button checks:

• Codex CLI is installed and executable.
• The working directory is absolute and usable.
• Authentication is ready through OPENAI_API_KEY or Codex's own login state.
• The hello probe can run codex exec --json - with the prompt Respond with hello.

If the probe fails, fix the command or auth path before saving the adapter.

Custom Providers And Gateways

Codex has no CLI flag or env var for pointing at a custom OpenAI-compatible endpoint. Custom endpoints live as [model_providers.<id>] tables in $CODEX_HOME/config.toml. To route Codex at your own gateway or provider without hand-editing that file, set the PAPERCLIP_CODEX_PROVIDERS environment variable on the Paperclip host.

PAPERCLIP_CODEX_PROVIDERS is a JSON object that maps onto Codex's config.toml schema:

{
  "providers": {
    "my-gateway": {
      "name": "My gateway",
      "base_url": "https://gateway.example.com/v1",
      "env_key": "OPENAI_API_KEY",
      "wire_api": "responses"
    }
  },
  "model_provider": "my-gateway"
}

• Each key under providers becomes a [model_providers.<id>] table. Common fields are name (optional display name), base_url (the OpenAI-compatible endpoint), env_key (the env var Codex reads the bearer key from at request time), and wire_api (the protocol Codex speaks to the provider). Any other field Codex supports is passed through too, including query_params, http_headers, env_http_headers, and request_max_retries.
• model_provider is optional. When set, it selects the top-level provider and must match one of your providers entries. The model field then picks the model within that provider.
• String values may use {env:VAR} placeholders. Paperclip expands them server-side against the run env and process.env, which is handy for fields that must carry a literal value such as http_headers. Prefer Codex's own env_key indirection for the bearer key. Unresolvable placeholders are left intact.

Paperclip writes these definitions into a managed region of the per-company managed Codex home's config.toml, delimited by # >>> paperclip codex providers ... managed, do not edit >>> marker comments. Your existing config is preserved, conflicting definitions are excised so the managed ones win, and the original file is restored after the run.

Note: This merge only happens for the managed Codex home. If your adapter config explicitly sets env.CODEX_HOME, Paperclip leaves that user-managed home untouched and surfaces a note instead of merging.

Example

{
  "adapterType": "codex_local",
  "adapterConfig": {
    "cwd": "/Users/me/projects/paperclip-workspace",
    "model": "gpt-5.6-sol",
    "instructionsFilePath": "/Users/me/projects/paperclip-workspace/INSTRUCTIONS.md",
    "modelReasoningEffort": "medium",
    "search": false,
    "dangerouslyBypassApprovalsAndSandbox": true,
    "env": {
      "OPENAI_API_KEY": {
        "type": "secret_ref",
        "secretId": "secret-id",
        "version": "latest"
      }
    },
    "timeoutSec": 300,
    "graceSec": 15
  }
}

Next Steps

• Creating an Adapter
• Adapter UI Parser Contract
• External Adapters