Codex CLI

Use AIOHub as the model provider in 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