OpenAI Codex provider - CtrlNode

Provider id: codex · CtrlNode agent type: CodexSdk Uses @openai/codex-sdk (stdio JSON-RPC to codex app-server). Each agent gets an isolated CODEX_HOME under the workspace.

When to use it

You use OpenAI Codex for autonomous coding on the Bridge host
You want per-agent Codex configuration directories

Prerequisites

Install Codex CLI with optional native deps:

npm install -g @openai/codex
codex --version
which codex   # note path for CODEX_BIN_PATH

Authentication

Option A — API key

CODEX_API_KEY=sk-...

Option B — CLI login

codex auth login

Environment variables

Variable	Default	Description
`CODEX_API_KEY`	—	OpenAI API key
`CODEX_BIN_PATH`	Auto from PATH	Absolute path to `codex` binary
`CODEX_DEFAULT_MODEL`	SDK default	e.g. `gpt-5.4-nano`
`CODEX_TIMEOUT_MINUTES`	`10`	Task timeout
`BASE_PATH`	Home	Workspace root

Example `.env`

PAIRING_TOKEN=...
PROVIDERS=codex
CODEX_API_KEY=sk-...
CODEX_BIN_PATH=/usr/local/bin/codex

CtrlNode setup

Project agent type Codex
Register agents in Team
Ensure agent type is CodexSdk so routing uses codex, not Copilot or Cursor

Troubleshooting

Issue	Fix
`Unable to locate Codex CLI binaries`	Reinstall with optional deps; set `CODEX_BIN_PATH`
Wrong provider executed task	Agent must be `CodexSdk`; check `sync_codex_agents` after reconnect
401	`codex auth login` or refresh `CODEX_API_KEY`

← All providers