Configure Codex CLI with a Custom API Endpoint (2026)

TL;DR

Codex CLI is OpenAI’s command-line AI coding tool. It runs in your terminal, takes natural language instructions, and generates or modifies code directly in your project. Since OfoxAI is fully compatible with the OpenAI protocol, you can integrate seamlessly with just two environment variables. This guide covers installation, configuration with OfoxAI, model selection, and verification.

For the official integration reference, see the OfoxAI Codex integration docs.

What Is Codex CLI

Codex CLI is a command-line tool published by OpenAI for AI-assisted coding. Unlike IDE extensions, it has no graphical interface. You type a natural language instruction in your terminal, and it generates code, modifies files, or performs refactors.

Typical use cases:

• Scaffolding: Generate project structures and configuration files from a description
• Refactoring: Describe the change you want and Codex CLI edits your source files
• Batch operations: Rename, reformat, or apply consistent changes across files
• Code explanation: Point it at unfamiliar code and ask for a walkthrough

Why Use a Custom API Endpoint

Codex CLI connects to OpenAI’s API by default. Routing through a provider like OfoxAI offers practical advantages:

Unified billing. If you use multiple AI tools, adding Codex CLI to the same endpoint means one API key, one invoice, and one usage dashboard.

Model access. An aggregation platform may provide access in regions where direct OpenAI connectivity is unreliable.

Cost management. Consolidating tools under one provider simplifies cost tracking.

Installation

npm install -g @openai/codex

After installation, the codex command should be available in your terminal. If it is not found, verify that npm’s global bin directory is in your $PATH.

Configuration

Codex CLI uses the OpenAI protocol — just configure two environment variables.

Step 1: Edit Your Shell Configuration

Add these lines to ~/.zshrc (or ~/.bashrc on Linux):

export OPENAI_API_KEY=<your OFOXAI_API_KEY>
export OPENAI_BASE_URL=https://api.ofox.run/v1

Key points:

• OPENAI_API_KEY is the key from your OfoxAI dashboard, not an OpenAI key
• OPENAI_BASE_URL must include the /v1 path
• No spaces around the = sign

Step 2: Reload the Configuration

source ~/.zshrc

Or open a new terminal window.

Step 3: Verify

Run a simple test:

codex "Create a Hello World Python script"

If Codex CLI generates code without errors, the configuration is working.

Model Selection

You can specify the model using command-line arguments:

# Everyday coding
codex --model openai/gpt-5.1-codex-mini "Refactor this function"

# Complex, multi-file work
codex --model openai/gpt-5.3-codex "Fix this bug"

Recommended Models

Rates read from the live /v1/models endpoint on 5 September 2026. For most day-to-day work gpt-5.1-codex-mini is the practical choice — lower cost, faster responses. Reach for gpt-5.3-codex when the model has to reason across multiple files.

A note if you are following an older guide: openai/gpt-5.4-mini-codex no longer exists in the catalog and returns model_not_found. Check GET https://api.ofox.run/v1/models rather than copying a model string from any page, including this one.

Using GPT-6 Astra in Codex CLI

GPT-6 Astra landed in the catalog on 5 September 2026 as openai/gpt-6-astra. It needs no separate provider block — it is the same OpenAI-compatible endpoint you configured above:

codex --model openai/gpt-6-astra "Migrate this module off the deprecated client"

Three things are worth knowing before you make it your default.

It is priced for agents, not for chat. $10.00 input and $50.00 output per million, against $5.00 / $30.00 for openai/gpt-5.6-sol. On short prompts you are paying 2.5x per token for a model whose general-intelligence score did not move. On long agent runs the arithmetic flips: Artificial Analysis measured Astra using roughly one third of GPT-5.6 Sol’s tokens in the Codex harness, so a full task can cost about the same while scoring higher.

Set the effort level explicitly. Astra exposes five (low, medium, high, xhigh, max). The step from high to max bought one index point and roughly doubled the cost in third-party testing, so high is the sensible default until you have measured otherwise.

Reasoning tokens are thinner. OpenAI’s system card documents a substantial decrease in chain-of-thought monitorability on this model. If your workflow reads reasoning output to debug a failed run, expect less to read. Our full review covers what that means in practice, and the pricing breakdown has the per-task numbers.

If you want Astra alongside other agents — DeepSeek Harness, Cline, Cursor — the harness setup guide has a working config block for each.

Practical Examples

Project scaffolding

codex "Create an Express.js project with TypeScript, ESLint, and a health check endpoint"

File conversion

codex --model openai/gpt-5.1-codex-max "Convert all JavaScript files in src/utils/ to TypeScript"

Test generation

codex "Write comprehensive Jest tests for src/services/auth.ts"

Troubleshooting

”Invalid API Key” error

Confirm that OPENAI_API_KEY in your shell profile is the key from your OfoxAI dashboard. Check for trailing spaces or line breaks in the copied value.

Connection timeout

Verify that OPENAI_BASE_URL is set to https://api.ofox.run/v1. The protocol must be https and the path must include /v1.

Environment variables not loaded

Run echo $OPENAI_BASE_URL in your terminal. If the output is empty, run source ~/.zshrc again or open a new terminal.

Model not found

When using a custom provider, model IDs include a prefix. Use openai/gpt-5.4-mini-codex, not gpt-5.4-mini-codex.

A Note on Versioning

Codex CLI configuration options may change with version updates. See the Codex CLI official documentation for the latest information.

Summary

Configuring Codex CLI with a custom API endpoint takes two environment variables and under five minutes. Install the npm package, set OPENAI_API_KEY and OPENAI_BASE_URL in your shell profile, reload, and you are coding from the terminal with AI assistance.

Once setup is done, the next question is what to actually do with it day-to-day. See the Codex CLI real-world coding workflow for the AGENTS.md, plan-mode, and worktree loop senior devs use. And if you outgrow the two-env-var setup — multiple providers, profiles, rotating tokens — the Codex CLI custom model providers guide covers the ~/.codex/config.toml path. And if the reason you are wiring a custom endpoint at all is a drained plan, the drop-in API that caps Codex spend has the wire_api = "responses" line you need.

For full integration documentation, see the OfoxAI Codex integration guide.

If the endpoint is set and calls still fail, the Codex error index covers the failures that follow a custom endpoint.