Skip to main content

OpenAI Codex CLI

What is the Codex CLI?​

The Codex CLI is an open-source, agentic terminal tool from OpenAI. It uses OpenAI's models (e.g., gpt-4o, gpt-4.1, o3) to read your codebase, execute shell commands, and iteratively solve tasks — similar to Claude Code but built on the OpenAI SDK.

Because BluesMinds provides a fully OpenAI-compatible API, you can redirect Codex CLI to BluesMinds with two environment variables and gain access to every model in the BluesMinds marketplace — including Claude models — without changing how you invoke the tool.

Why route Codex CLI through BluesMinds?​

BenefitDetail
Cross-provider model accessUse claude-sonnet-4-5 or gemini-pro through the same Codex CLI that normally only speaks OpenAI.
Automatic failoverIf OpenAI is down or rate-limiting, BluesMinds retries through an alternative provider seamlessly.
Cost controlBluesMinds selects the cheapest upstream option for each request.
Single API keyNo need to manage separate OpenAI, Anthropic, and Google credentials.

Prerequisites​

Install the Codex CLI globally via npm:

npm install -g @openai/codex

Confirm the installation:

codex --version

Obtain your BluesMinds API key from the BluesMinds Console.

Environment Variable Configuration​

VariableValue
OPENAI_BASE_URLhttps://api.bluesminds.com/v1
OPENAI_API_KEYYour BluesMinds API key (sk-…)

One-off (inline):​

OPENAI_BASE_URL=https://api.bluesminds.com/v1 \
OPENAI_API_KEY=sk-your-bluesminds-key \
codex "Refactor the main function to use async/await"

Persistent (shell profile):​

Add the following to your ~/.zshrc or ~/.bashrc:

export OPENAI_BASE_URL=https://api.bluesminds.com/v1
export OPENAI_API_KEY=sk-your-bluesminds-key

Then reload:

source ~/.zshrc  # or source ~/.bashrc

Then run Codex normally:

codex "Write unit tests for src/parser.ts"

.env File​

.env
OPENAI_BASE_URL=https://api.bluesminds.com/v1
OPENAI_API_KEY=sk-your-bluesminds-key

Load before running:

export $(cat .env | xargs) && codex "Your task here"

Codex CLI Config File​

The Codex CLI reads ~/.codex/config.json (or $CODEX_HOME/config.json). You can bake the BluesMinds base URL and model into this file so you never need to set environment variables manually:

~/.codex/config.json
{
  "model": "gpt-4o",
  "provider": "openai",
  "providers": {
    "openai": {
      "apiKey": "sk-your-bluesminds-key",
      "baseURL": "https://api.bluesminds.com/v1"
    }
  }
}

Then run normally — no extra environment variables needed:

codex "Refactor this function to use async/await"

Supported Models (OpenAI-compatible)​

BluesMinds supports all standard OpenAI model IDs, plus cross-provider models. Check the BluesMinds Models page for the complete list. Common examples:

Model IDDescription
gpt-4oLatest multimodal GPT-4o
gpt-4.1Enhanced instruction-following
gpt-4o-miniFast and cost-efficient
o3Full reasoning model
o4-miniCompact reasoning model

CLI Usage Examples​

# One-shot task
OPENAI_BASE_URL=https://api.bluesminds.com/v1 \
OPENAI_API_KEY=sk-your-bluesminds-key \
codex "Add JSDoc comments to every exported function in src/"

# Use a specific model
OPENAI_BASE_URL=https://api.bluesminds.com/v1 \
OPENAI_API_KEY=sk-your-bluesminds-key \
codex --model gpt-4.1 "Explain the bug in src/parser.ts"

# Interactive mode (omit the task argument)
OPENAI_BASE_URL=https://api.bluesminds.com/v1 \
OPENAI_API_KEY=sk-your-bluesminds-key \
codex

Quick Reference​

# For Codex CLI and all OpenAI-compatible tools
export OPENAI_API_KEY=sk-your-bluesminds-key
export OPENAI_BASE_URL=https://api.bluesminds.com/v1

BluesMinds implements the full OpenAI REST specification — any tool that works with the OpenAI SDK will work with BluesMinds.

Troubleshooting​

SymptomFix
401 UnauthorizedConfirm OPENAI_API_KEY matches your BluesMinds key and starts with sk-.
404 model not foundVerify the model ID exists on the BluesMinds Models page. Model IDs are case-sensitive.
ECONNREFUSEDConfirm OPENAI_BASE_URL is set. Some library versions default to https://api.openai.com.
Config file ignoredDelete ~/.codex/config.json and recreate it; check for JSON syntax errors with `cat ~/.codex/config.json
Rate limit errorsBluesMinds routes across providers — if one provider is saturated, try a different model variant (e.g., gpt-4o-mini instead of gpt-4o).
Auth errors (401/403)1. Re-copy your key from the BluesMinds Console. 2. Ensure no extra spaces or line breaks. 3. Confirm the key starts with sk-.
Connection timeoutVerify connectivity: curl https://api.bluesminds.com/v1/models -H "Authorization: Bearer sk-your-key"
Tool uses wrong endpointSome tools cache the base URL. Restart the tool — or open a new terminal — after changing env vars.
Responses seem slowTry a lighter model for faster responses (e.g., gpt-4o-mini).
Context window errorsSwitch to a model with a larger context window (e.g., gpt-4.1 supports 1M tokens).

Next Steps​