> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# Codex CLI

> Use Codex CLI with JoyToken

## Prerequisites

| Item              | Value                                |
| ----------------- | ------------------------------------ |
| Codex CLI         | Latest version                       |
| Config file       | `~/.codex/config.toml`               |
| Provider id       | `joytoken`                           |
| Model name        | `auto`                               |
| JoyToken Base URL | `https://api.joytokens.ai/openai/v1` |
| Wire API          | OpenAI Responses                     |
| API key env       | `JOY_TOKEN_API_KEY`                  |

## Step 1: Install

```bash
npm install --global @openai/codex@latest
codex --version
```

## Step 2: Set the API key

Replace `sk-xxx` with your JoyToken API key:

```bash
export JOY_TOKEN_API_KEY="sk-xxx"
```

For persistent use, provide the variable through your shell profile or secret manager. Do not store the key in `config.toml`.

## Step 3: Configure the provider

Add the following top-level settings and provider definition to `~/.codex/config.toml`:

```toml
model = "auto"
model_provider = "joytoken"

[model_providers.joytoken]
name = "JoyToken"
base_url = "https://api.joytokens.ai/openai/v1"
env_key = "JOY_TOKEN_API_KEY"
wire_api = "responses"
```

Provider and authentication settings must be in the user-level config. Codex ignores `model_provider` and `model_providers` in project-level `.codex/config.toml` files.

## Step 4: Start

```bash
cd /path/to/your/project
codex
```

## Step 5: Verify

```bash
codex exec "Reply with exactly: pong"
```

A successful response includes `pong`.

## JoyToken Check

| Place | Expected result                                |
| ----- | ---------------------------------------------- |
| Logs  | Request path is `/openai/v1/responses`         |
| Auth  | Bearer authentication uses `JOY_TOKEN_API_KEY` |
| Model | Requested model is `auto`                      |
| Usage | Tokens and credits are recorded                |

## Common Errors

| Error                          | Fix                                                                      |
| ------------------------------ | ------------------------------------------------------------------------ |
| `JOY_TOKEN_API_KEY` is missing | Export the variable in the current shell                                 |
| Codex uses another provider    | Check `model_provider = "joytoken"` in `~/.codex/config.toml`            |
| Provider config is ignored     | Move it from project `.codex/config.toml` to user `~/.codex/config.toml` |
| `401 Unauthorized`             | Check that `JOY_TOKEN_API_KEY` contains a valid JoyToken API key         |

## Resources

* [Codex CLI](https://developers.openai.com/codex/cli/)
* [Codex custom model providers](https://developers.openai.com/codex/config-advanced#custom-model-providers)
* [JoyToken Environments](/user-guide/environments)
* [JoyToken Models](/user-guide/models)