> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiohub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Use AIOHub as the model provider in Codex CLI.

[Codex CLI](https://github.com/openai/codex) 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:

```bash theme={"system"}
codex --version
codex --help
```

## Setup

### 1. Set the API key

```bash theme={"system"}
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` |

```toml theme={"system"}
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
```

<Note>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.</Note>

### 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`:

```toml theme={"system"}
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
```

<Note>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`.</Note>

## Verify

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

```bash theme={"system"}
test -n "$AIOHUB_API_KEY" && echo "api key configured"
```

Start Codex CLI and send a short prompt:

```bash theme={"system"}
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:

```bash theme={"system"}
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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="Model not available">
    Check that the group assigned to your API key can access the requested model in the console.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="WebSocket or Realtime errors">
    Keep `supports_websockets = false`. Codex CLI will use Responses HTTP/SSE transport and will not require a Responses WebSocket gateway.
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

## Official reference

* [Codex configuration reference](https://www.mintlify.com/openai/codex/configuration/reference)