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

# OpenAI Codex provider

> Bridge provider codex — OpenAI Codex SDK and CLI

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:

```bash theme={null}
npm install -g @openai/codex
codex --version
which codex   # note path for CODEX_BIN_PATH
```

## Authentication

**Option A — API key**

```env theme={null}
CODEX_API_KEY=sk-...
```

**Option B — CLI login**

```bash theme={null}
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`

```env theme={null}
PAIRING_TOKEN=...
PROVIDERS=codex
CODEX_API_KEY=sk-...
CODEX_BIN_PATH=/usr/local/bin/codex
```

## CtrlNode setup

1. Project agent type **Codex**
2. Register agents in **Team**
3. 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](/bridge/providers)