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

# OpenAI Codex CLI

> Configure the OpenAI Codex CLI to use KiosAPI as the backend provider with the Codex model groups.

# OpenAI Codex CLI

[OpenAI Codex CLI](https://github.com/openai/codex) is a command-line coding agent from OpenAI. This guide walks you through configuring it to work with KiosAPI.

## System Requirements

| Requirement | Minimum | Recommended |
| - | - | - |
| **Operating System** | macOS 12+, Ubuntu 20.04+, or Windows 11 (WSL2) | — |
| **RAM** | 4 GB | 8 GB |
| **Node.js** | 22+ | Latest LTS |
| **Disk Space** | 200 MB | 500 MB |

## Get the right API key

Codex models on KiosAPI (gpt-5.5, gpt-5.6, gpt-6 series) are served through the **`Codex-Pro`** and **`Codex-Plus`** groups:

1. Log in to the [KiosAPI Dashboard](https://kiosapi.com).
2. Go to **Console → Tokens** → **Add Token**.
3. Select group **`Codex-Pro`** (0.04×) or **`Codex-Plus`** (0.02×) — check which group covers the exact model you want on the [pricing page](https://kiosapi.com/pricing).
4. Save and copy the key (starts with `sk-`).

> [!WARNING]
>
> A token in the wrong group cannot call the Codex models. `Codex-Pro` and `Codex-Plus` cover slightly different model sets — verify your target model's group on the [pricing page](https://kiosapi.com/pricing) before creating the key. See [Choosing a Token Group](https://docs.kiosapi.com/getting-started/token-groups.md).

## Installation

Install Codex CLI globally via npm:

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew (macOS/Linux):

```bash theme={null}
brew install codex
```

Verify the installation:

```bash theme={null}
codex --version
```

## Current Codex models on KiosAPI

| Model | Group | Best for |
| - | - | - |
| `gpt-6-astra` | `Codex-Pro`, `Codex-Plus` | Most capable agentic coding |
| `gpt-5.6-sol` | `Codex-Pro`, `Codex-Plus` | Daily coding — recommended default |
| `gpt-5.6-terra` | `Codex-Pro`, `Codex-Plus` | Balanced coding |
| `gpt-5.5` | `Codex-Pro` | Lighter tasks |

## Configuration

### 1. Create the config file

Create `~/.codex/config.toml`:

```toml theme={null}
[model_providers.kiosapi]
name = "KiosAPI"
base_url = "https://kiosapi.com/v1"
wire_api = "responses"
env_key = "KIOSAPI_KEY"

[profiles.kiosapi]
model = "gpt-5.6-sol"
model_provider = "kiosapi"
```

> [!NOTE]
>
> The `wire_api = "responses"` setting tells Codex to use OpenAI's Responses API format, which KiosAPI supports at `/v1/responses`.

### 2. Set the environment variable

Set your KiosAPI key as the `KIOSAPI_KEY` environment variable.

**Windows (PowerShell):**

```powershell theme={null}
setx KIOSAPI_KEY "sk-xxx"
```

**macOS / Linux:**

Add to `~/.bashrc` or `~/.zshrc`:

```bash theme={null}
export KIOSAPI_KEY="sk-xxx"
```

Then reload:

```bash theme={null}
source ~/.bashrc  # or ~/.zshrc
```

## Usage

### Interactive mode

```bash theme={null}
codex
```

### Direct question

```bash theme={null}
codex "Explain how async/await works in Python"
```

### Using the KiosAPI profile

```bash theme={null}
codex --profile kiosapi "Write a function to reverse a linked list"
```

## VSCode Plugin

Codex is also available as a [VSCode extension](https://marketplace.visualstudio.com/items?itemName=openai.codex). After installing the extension, configure it to use KiosAPI by setting the same environment variables in your VSCode settings or terminal.

> [!WARNING]
>
> The VSCode extension reads environment variables from your shell. Make sure `KIOSAPI_KEY` is exported in the shell that launches VSCode, or set it in the integrated terminal.

## Advanced Configuration

### Non-Interactive CI Mode

For CI/CD pipelines, run Codex in non-interactive mode:

```bash theme={null}
codex --quiet --auto-approve "Fix the failing test in tests/auth.test.js"
```

| Flag | Description |
| - | - |
| `--quiet` | Suppress interactive prompts |
| `--auto-approve` | Automatically approve file changes |
| `--json` | Output results as JSON |

### MCP Servers

Codex supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers for extended tool access. Add MCP servers in `~/.codex/config.toml`:

```toml theme={null}
[mcp.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

[mcp.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }
```

## Troubleshooting

### Authentication Error (401)

* Verify `KIOSAPI_KEY` is set correctly: `echo $KIOSAPI_KEY`
* Ensure the key starts with `sk-`
* Check the `env_key` in your config matches the environment variable name

### Model Not Found / No Available Channel

* Verify the model name in your profile is a current model ID (old names like `o4-mini` no longer exist)
* Verify your token's group (`Codex-Pro` or `Codex-Plus`) covers that model on the [pricing page](https://kiosapi.com/pricing)

### Connection Error

* Ensure `base_url` is `https://kiosapi.com/v1` (with `/v1`)
* Check your network connection and firewall settings

## Verify Your Setup

```bash theme={null}
codex "Say hello"
```

## Need Help?

* [KiosAPI Dashboard](https://kiosapi.com)
* [Choosing a Token Group](https://docs.kiosapi.com/getting-started/token-groups.md)
* [Available Models](https://kiosapi.com/pricing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.