> 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 App

> 使用 Codex App 接入 JoyToken

## 前提条件

| 项目                | 值                                    |
| ----------------- | ------------------------------------ |
| Codex App         | 最新版本                                 |
| 配置文件              | `~/.codex/config.toml`               |
| Provider id       | `joytoken`                           |
| 模型名称              | `auto`                               |
| JoyToken Base URL | `https://api.joytokens.ai/openai/v1` |
| 接口协议              | OpenAI Responses                     |
| API Key 环境变量      | `JOY_TOKEN_API_KEY`                  |

## 第一步：设置 API Key

把 `sk-xxx` 替换成你的 JoyToken API Key：

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

Codex 会读取 `env_key` 指定的环境变量。不要把 API Key 写进 `config.toml`，并从能够读取该变量的终端启动 App。

## 第二步：配置 Provider

在 Codex App 中打开 **Settings > Configuration > Open config.toml**，把以下顶层配置和 Provider 定义加入 `~/.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 和认证配置必须放在用户级配置中。Codex 会忽略项目级 `.codex/config.toml` 里的 `model_provider` 和 `model_providers`。

## 第三步：启动 Codex App

完全退出正在运行的 Codex App，然后从已设置 `JOY_TOKEN_API_KEY` 的终端打开项目：

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

## 第四步：验证

发送 `Reply with exactly: pong`。成功响应中会包含 `pong`。

## JoyToken 检查

| 位置 | 预期结果                                |
| -- | ----------------------------------- |
| 日志 | 请求路径是 `/openai/v1/responses`        |
| 认证 | 使用 `JOY_TOKEN_API_KEY` 进行 Bearer 认证 |
| 模型 | 请求的模型是 `auto`                       |
| 用量 | 正常记录 token 和 Credits                |

## 常见错误

| 错误                     | 处理方式                                                       |
| ---------------------- | ---------------------------------------------------------- |
| 缺少 `JOY_TOKEN_API_KEY` | 从已导出该变量的终端启动 Codex App                                     |
| Codex 使用了其他 Provider   | 检查 `~/.codex/config.toml` 中的 `model_provider = "joytoken"` |
| Provider 配置未生效         | 把配置从项目 `.codex/config.toml` 移到用户级 `~/.codex/config.toml`   |
| `401 Unauthorized`     | 检查 `JOY_TOKEN_API_KEY` 是否为有效的 JoyToken API Key             |

## 相关资源

* [Codex App](https://developers.openai.com/codex/app/)
* [Codex 自定义模型 Provider](https://developers.openai.com/codex/config-advanced#custom-model-providers)
* [JoyToken 环境](/zh/user-guide/environments)
* [JoyToken 模型](/zh/user-guide/models)