Skip to main content
The Codex adapter lets Orkestral drive the OpenAI Codex CLI as a planning provider. When you hire an agent backed by Codex, that agent uses the codex binary on your machine to reason, plan, and propose work. The premium model plans; the bundled local Forge executes the actual code changes at no API cost. This adapter is recommended and runs entirely against your local codex install. Orkestral never embeds your OpenAI key: it shells out to the CLI you already authenticated.
The internal adapter type is codex_local and it appears as Codex in the onboarding grid. See Adapters overview for how providers and the Forge fit together.

​
Requirements

Codex CLI

The codex binary must be installed and discoverable on your PATH.

Authentication

A logged in Codex session or an OPENAI_API_KEY in your environment.
Install the CLI with: 
npm i -g @openai/codex
Then authenticate using one of: 
codex login
or export a key before launching Orkestral: 
export OPENAI_API_KEY=sk-...
Orkestral reads your Codex configuration from CODEX_HOME when set, otherwise from ~/.codex. The model list is sourced from ~/.codex/models_cache.json, a cache the CLI itself maintains.

​
How Orkestral runs Codex

Orkestral invokes the CLI in headless exec mode. During the environment test it runs a probe equivalent to: 
codex exec --skip-git-repo-check --yolo -
with a short prompt piped on stdin. The reasoning effort and web search options you configure are translated into CLI flags at run time (see Configuration). Orkestral closes stdin automatically and parses the response, so you do not pass these flags yourself.

​
Set up the adapter

1

Install and authenticate the CLI

Confirm the binary works in a terminal before opening Orkestral:
codex --version
If this fails, fix your install or PATH first.
2

Open the Codex adapter in Orkestral

Go to the adapters grid (during onboarding or in settings) and select Codex.
3

Run the environment test

Use Test environment. Orkestral verifies that codex is on the PATH, that --version responds, and that the agent answers a sample prompt. Review the result of each check.
4

Pick a model

Choose a model from the list. Models come from your real Codex cache when available, so the list reflects what your account can actually access.
5

Configure options and save

Set reasoning effort, web search, and an optional command override, then save. The adapter is now available when hiring agents.

​
Configuration

The Codex adapter exposes three options. Set them in the adapter configuration panel.
​
modelReasoningEffort
select
default:"medium"
How hard the model reasons before answering. Passed to the CLI as -c model_reasoning_effort=<value>. Allowed values: minimal, low, medium, high, xhigh. Higher effort can improve plan quality but costs more time and tokens.
​
search
toggle
default:false
Enables web search by adding the --search flag to the Codex invocation. Turn this on when planning needs current external information.
​
command
text
default:"codex"
Override the command or path used to launch the CLI. Leave empty to use codex from your PATH. Set an absolute path here if your binary lives outside the default location.

​
Reasoning effort levels

ValueLabelWhen to use
minimalMinimalFastest, cheapest, lightweight tasks.
lowLowSimple planning with light reasoning.
mediumMediumDefault balance of speed and depth.
highHighHarder problems that need deeper analysis.
xhighVery highMaximum reasoning for the hardest plans.

​
Models

The model selector always includes a Default entry that uses whatever model your Codex CLI is configured to use. Beyond that:
  • If ~/.codex/models_cache.json exists, Orkestral lists the models your account actually has access to. Internal models (those not marked for listing) are filtered out.
  • If no cache is present, Orkestral falls back to a static, newest first list that includes entries such as GPT-5.4, GPT-5.3 Codex, GPT-5, GPT-5 Mini, the OpenAI o-series, and Codex Mini.
To refresh the model list, run any codex command so the CLI updates its cache, then reopen the adapter in Orkestral.

​
Environment test checks

When you run Test environment, Orkestral reports these checks:
CheckMeaning
codex on PATHThe binary was found. A failure here stops the test.
CLI versioncodex --version responded successfully.
Agent responseA headless probe returned an expected answer, or a warning if authentication or the response looks off.
An authentication warning appears when the probe output mentions login, missing key, or unauthorized access. The test still completes, but you should authenticate before relying on the adapter.

​
Capabilities and limits

  • Plans and reasons through the Codex CLI; code execution is handled by the Forge, not by this adapter.
  • Reflects your real account access through the CLI model cache, with a static fallback.
  • Runs locally and uses the credentials already present in your shell or Codex config.
  • Does not store or transmit your OpenAI key through Orkestral; it relies on the CLI.

​
Troubleshooting

Orkestral could not locate the binary. Install it with npm i -g @openai/codex or follow the official guide, then confirm codex --version works in the same shell Orkestral launches from. If you use a version manager, ensure the binary is on the PATH your desktop session inherits, or set an absolute path in the command override.
The probe saw a login, unauthorized, or API key message. Run codex login (or codex auth), or export OPENAI_API_KEY before launching Orkestral, then test again.
codex --version did not respond. The install may be broken or partially upgraded. Reinstall the CLI and verify it runs in a terminal.
The sample prompt did not return in time. This is often transient. Test again. If it persists, check your network and that your Codex account is active.
The list comes from ~/.codex/models_cache.json (or CODEX_HOME). Run any codex command to refresh the cache, then reopen the adapter. If the cache is missing, Orkestral shows its static fallback list instead.
The environment probe runs Codex with --yolo, which skips its interactive approval prompts so the test can run unattended. This is used only for the short headless check.