# Codex CLI

Source: https://docs.aicentos.com/en/clients/codex-cli

Language: en

> Use aicentos in Codex CLI — manually configure model_providers in config.toml

Codex CLI is OpenAI's official command-line coding agent; model providers are defined in `~/.codex/config.toml`. Point a custom provider at aicentos and the models aicentos offers become usable in the terminal.

If you prefer managing multiple configurations graphically, [CC Switch](https://docs.aicentos.com/en/clients/cc-switch) offers one-click switching; this guide covers manual configuration only.

## Prerequisites

First create a dedicated key for Codex CLI on the console's "API Keys" page (naming it `codex-cli` makes usage easier to track):

* Console: [https://aicentos.com](https://aicentos.com)
* Create a key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Confirm Codex CLI is installed:

```bash
codex --version
```

## Configuration to fill in

| Field                        | Value                                              |
| ---------------------------- | -------------------------------------------------- |
| Provider ID                  | `aicentos`                                         |
| Provider name                | `aicentos`                                         |
| API Key environment variable | `AICENTOS_API_KEY`                                 |
| Base URL                     | `https://aicentos.com/v1`                          |
| Model                        | A model name from the Model Gallery in the console |

## Setup steps

### 1. Set the API Key environment variable

```bash
export AICENTOS_API_KEY="sk-your-API-Key"
```

To persist it, add the line to `~/.zshrc` or `~/.bashrc`, `source` the file, and verify with `echo $AICENTOS_API_KEY`.

### 2. Edit config.toml

Add the following to `~/.codex/config.toml`:

```toml
model = "your-model-name"
model_provider = "aicentos"

[model_providers.aicentos]
name = "aicentos"
base_url = "https://aicentos.com/v1"
env_key = "AICENTOS_API_KEY"
wire_api = "responses"
```

Replace `your-model-name` with a model name listed in the Model Gallery of the console; see [Supported models](https://docs.aicentos.com/en/billing/models-list).

### 3. Start Codex

```bash
codex
```

Send a simple request to confirm the provider works.

## Test

```
codex exec "Answer in one sentence: what is 1+1?"
```

A normal response means the integration works. The response consumes a small amount of quota, which you can check in the console's usage logs.

## Notes

* **Enter the Base URL only up to `/v1`** — do not extend it to the full `/v1/chat/completions` path.
* Fields such as `base_url` and `env_key` only take effect in the user-level `~/.codex/config.toml`. A `.codex/config.toml` inside the project is ignored and may trigger a startup warning.
* Set `wire_api` to `responses`, which corresponds to aicentos' [Responses API](https://docs.aicentos.com/en/api/chat/openai/responses). The official documentation currently only supports this value; if your version reports `unknown variant`, the CLI is too old — upgrade first.
* `openai`, `ollama` and `lmstudio` are reserved provider IDs. You **cannot** repoint the built-in `openai` provider's base\_url at a third-party gateway; you must create a new provider name (`aicentos` in this guide).
* Troubleshooting order: does the model name match the console → is the Base URL only up to `/v1` → are the environment variables visible in **the terminal that launched codex** → is the account balance sufficient.

## Related links

* [Connect Codex (via CC Switch)](https://docs.aicentos.com/en/clients/codex)