← Back to Articles

How to Connect OpenAI Codex CLI to AGNT

Connect your OpenAI Codex CLI to AGNT and use GPT Codex models directly from your desktop. This guide covers installation, authentication, and troubleshooting.

Prerequisites

Before connecting, you need the Codex CLI installed on your machine.

Install Codex CLI

npm install -g @openai/codex

Verify the installation:

codex --version

Note: AGNT auto-discovers the Codex binary from common locations (npm global, nvm, fnm, Homebrew, Volta, asdf). If you installed Codex through any of these, AGNT should find it automatically.

Supported Models

Once connected, AGNT gives you access to these Codex models:

Model Description
gpt-5.2-codex Latest GPT Codex model
gpt-5.1-codex Previous generation GPT Codex model

These models run through OpenAI's Codex Responses API and require OAuth authentication (not a standard API key).

Connecting Codex to AGNT

You can connect from two places in the AGNT UI. Both use the same device authentication flow.

Option A: Connectors Page

  1. Open Connectors from the left sidebar
  2. Go to the Auth Connections section
  3. Find OpenAI Codex and click Connect
  4. Follow the device login flow (see below)

Option B: Integration Health Panel

  1. Open any Chat panel
  2. In the right sidebar, find the Connected Integrations section
  3. Click the connect button next to OpenAI Codex
  4. Follow the device login flow (see below)

Device Login Flow

Codex uses OpenAI's device authorization flow — no passwords are entered in AGNT.

Step 1: Start Device Login

When you click Connect, AGNT starts the device auth process and displays a modal with:

  • A URL (e.g., https://auth.openai.com/codex/device)
  • A one-time code (e.g., ABCD-1234)

Step 2: Authenticate with OpenAI

  1. Open the URL in your browser
  2. Enter the one-time code shown in AGNT
  3. Sign in to your OpenAI account
  4. Authorize the connection

Step 3: Confirm in AGNT

Return to AGNT and click I have logged in. AGNT will verify the connection and show a success message.

That's it — Codex models are now available in your agent chats.

Where Are Credentials Stored?

Codex credentials are stored locally on your machine, shared with the official Codex CLI:

~/.codex/auth.json

This file contains your OAuth tokens (access token, refresh token). AGNT reads from and writes to this file — it never sends your credentials to any third-party server.

Token Auto-Refresh

AGNT automatically refreshes your Codex OAuth token before it expires. OpenAI uses refresh token rotation, meaning each refresh issues a new refresh token. AGNT handles this transparently — you shouldn't need to re-authenticate unless you explicitly disconnect or your refresh token is revoked.

Environment Variables (Optional)

Variable Description Default
CODEX_BIN Explicit path to the codex binary Auto-discovered
CODEX_HOME Override the Codex config directory ~/.codex
CODEX_OAUTH_CLIENT_ID Override the OAuth client ID OpenAI's public client ID

Most users don't need to set any of these.

Troubleshooting

"spawn script ENOENT"

Cause: Older versions of AGNT used a Unix script command to wrap the Codex CLI process. This fails on systems where script is not installed (Docker containers, minimal Linux installs).

Fix: Update AGNT to the latest version. This was fixed in v0.5.0+. As a workaround, you can authenticate directly in your terminal:

codex login --device-auth

Once authenticated, AGNT will pick up the tokens from ~/.codex/auth.json automatically.

"HTTP error! status: 400"

Cause: Your OAuth access token has expired and failed to refresh. This typically happens when:

  • You haven't used Codex in a while and the refresh token was rotated/revoked
  • The token was already used by another client (OpenAI enforces refresh token rotation)

Fix: Disconnect and reconnect:

  1. Click Disconnect on the Codex integration
  2. Click Connect and complete the device login flow again

Or re-authenticate via terminal:

codex login --device-auth

"Codex CLI not found"

Cause: AGNT cannot locate the codex binary on your system.

Fix:

  1. Verify Codex CLI is installed: codex --version
  2. If not installed: npm install -g @openai/codex
  3. If installed but AGNT can't find it, set the path explicitly in your .env:
CODEX_BIN=/path/to/codex

"Device code was not returned yet"

Cause: The Codex CLI is slow to respond or the device auth endpoint is rate-limited.

Fix: Wait a moment and try again. If you see this repeatedly, OpenAI may be rate-limiting device code requests. Wait 1–2 minutes before retrying.

Connection shows "Not Connected" after restart

This is expected if your OAuth token expired while AGNT was closed. AGNT will attempt to auto-refresh on next use. If auto-refresh fails, simply reconnect using the device login flow.

How It Works Under the Hood

┌─────────────┐     device-auth      ┌──────────────┐     OAuth     ┌─────────────┐
│   AGNT UI   │ ──────────────────── │  AGNT Server │ ────────────  │   OpenAI    │
│  (Connect)  │                      │  (Express)   │              │  auth.openai │
└─────────────┘                      └──────────────┘              └─────────────┘
                                           │
                                     spawns codex CLI
                                           │
                                     ┌─────────────┐
                                     │  ~/.codex/   │
                                     │  auth.json   │
                                     └─────────────┘
  1. Frontend triggers device auth via the Vuex store
  2. Backend spawns codex login --device-auth and parses the device URL/code from stdout
  3. User authenticates with OpenAI in their browser
  4. Codex CLI writes OAuth tokens to ~/.codex/auth.json
  5. AGNT reads the tokens and uses them with the Codex Responses API at chatgpt.com/backend-api/codex
  6. Auto-refresh kicks in 5 minutes before token expiry, posting to auth.openai.com/oauth/token with the refresh token

FAQ

Q: Do I need an OpenAI API key?
No. Codex uses OAuth device authentication, not API keys. You sign in with your OpenAI account.

Q: Is my OpenAI account billed for Codex usage?
Codex usage follows your OpenAI account's plan and billing. Check your OpenAI dashboard for details.

Q: Can I use Codex and regular OpenAI at the same time?
Yes. Codex CLI and standard OpenAI are separate providers in AGNT. You can connect both simultaneously — they use independent credentials.

Q: Does AGNT share my credentials with anyone?
No. Credentials are stored locally in ~/.codex/auth.json on your machine. AGNT communicates directly with OpenAI's API — no credentials pass through any third-party server.