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

# Codex App

> Use Codex App with JoyToken

## Prerequisites

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

## Step 1: Set the API key

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

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

Codex reads the variable named by `env_key`. Keep the key out of `config.toml` and start the app from a shell where this variable is available.

## Step 2: Configure the provider

In Codex App, open **Settings > Configuration > Open config.toml**. 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-staging.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 3: Start Codex App

Quit any running Codex App process, then open the project from the shell where `JOY_TOKEN_API_KEY` is set:

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

## Step 4: Verify

Send `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 | Start Codex App from a shell where the variable is exported              |
| 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 App](https://developers.openai.com/codex/app/)
* [Codex custom model providers](https://developers.openai.com/codex/config-advanced#custom-model-providers)
* [JoyToken Environments](/user-guide/environments)
* [JoyToken Models](/user-guide/models)