Codex CLI

Codex CLI uses the OpenAI Responses API. For AIOHub, configure a separate aiohub provider and let Codex CLI read the API key from an environment variable.

Prerequisites

Codex CLI installed
An AIOHub sk- API key
A group assigned to the API key that can access the Codex / GPT model you want to use
A positive account balance

You can first confirm Codex CLI is installed:

codex --version
codex --help

Setup

1. Set the API key

export AIOHUB_API_KEY="sk-your-api-key"

Add this line to ~/.zshrc, ~/.bashrc, or your shell profile if you want it to persist.

2. Configure the provider

Edit ~/.codex/config.toml. Use a separate aiohub provider instead of overriding Codex CLI’s built-in openai provider. Configuration file locations:

System	Path
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`

model_provider = "aiohub"
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
model_verbosity = "high"
disable_response_storage = true

[model_providers.aiohub]
name = "AIOHub"
base_url = "https://api.aiohub.org/v1"
env_key = "AIOHUB_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Set base_url to the /v1 root, not /v1/responses. supports_websockets = false keeps Codex using Responses over HTTP/SSE, which matches the current AIOHub gateway setup.

Optional: sync Codex App sessions

If you want Codex App sessions to sync between your phone and computer, let the AIOHub provider depend on your official OpenAI account login. The key setting is requires_openai_auth = true. Sign in to the same ChatGPT account in Codex App on both your phone and computer, then use this configuration in ~/.codex/config.toml:

model_provider = "aiohub"

[model_providers.aiohub]
name = "OpenAI"
base_url = "https://api.aiohub.org/v1"
experimental_bearer_token = "sk-your-api-key"
wire_api = "responses"
requires_openai_auth = true

This configuration is for Codex App workflows that need OpenAI account session sync. If you only use AIOHub in Codex CLI, keep using the env_key setup above with requires_openai_auth = false.

Verify

Check that the environment variable exists without printing the API key:

test -n "$AIOHUB_API_KEY" && echo "api key configured"

Start Codex CLI and send a short prompt:

codex

Common commands:

Command	Use
`codex`	Start interactive mode
`codex "explain this project"`	Start interactive mode with an initial prompt
`codex exec "count files in this directory"`	Run one non-interactive task

You can also verify the gateway with the Responses API:

curl https://api.aiohub.org/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "input": "Reply with one short sentence."
  }'

Configuration notes

Setting	Meaning
`model_provider`	Selects the custom provider
`base_url`	AIOHub OpenAI-compatible root, including `/v1`
`env_key`	Environment variable where Codex CLI reads the AIOHub API key
`experimental_bearer_token`	Writes the AIOHub API key directly in the config file; use only when you need Codex App session sync
`wire_api`	Codex CLI uses `responses`
`requires_openai_auth`	Use `false` for independent CLI API-key auth; use `true` when Codex App should sync sessions through the same ChatGPT account
`supports_websockets`	`false` uses HTTP/SSE Responses transport
`model`	Change this to a model available to the group assigned to your API key
`model_reasoning_effort`	Reasoning effort: `low`, `medium`, `high`, or `xhigh`
`disable_response_storage`	Requests upstream response-storage opt-out when supported

Troubleshooting

Codex CLI cannot connect

Confirm base_url is https://api.aiohub.org/v1, AIOHUB_API_KEY is set, and your network can reach api.aiohub.org.

Model not available

Check that the group assigned to your API key can access the requested model in the console.

Requests go to the official OpenAI account

Confirm model_provider = "aiohub" and keep AIOHub out of the built-in openai provider. With requires_openai_auth = false, Codex CLI uses the API key from the variable named by env_key.

WebSocket or Realtime errors

Keep supports_websockets = false. Codex CLI will use Responses HTTP/SSE transport and will not require a Responses WebSocket gateway.

Responses Compact errors

/v1/responses/compact is only for models or routes that support compact. A normal Codex CLI session should keep wire_api = "responses" and must not set base_url to /v1/responses/compact.

Official reference

Codex configuration reference

Choose a client

Developer tools

OpenAI-compatible apps

Image clients

Chat clients

Prerequisites

Setup

1. Set the API key

2. Configure the provider

Optional: sync Codex App sessions

Verify

Configuration notes

Troubleshooting

Official reference

​Prerequisites

​Setup

​1. Set the API key

​2. Configure the provider

​Optional: sync Codex App sessions

​Verify

​Configuration notes

​Troubleshooting

​Official reference

Prerequisites

Setup

1. Set the API key

2. Configure the provider

Optional: sync Codex App sessions

Verify

Configuration notes

Troubleshooting

Official reference