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

# 接入 Codex

> 给 OpenAI Codex CLI 配置一个 TokenHub 模型提供方，用 API 密钥调用。

Codex 走 OpenAI 的 Responses 接口。你需要一把绑定在面向 Codex 分组上的 API 密钥，然后在 Codex 的配置里把 TokenHub 加成一个模型提供方。

## 开始之前

* 已安装 Codex CLI（终端里能运行 `codex`）
* 密钥所属的个人或团队有可用余额

> [!NOTE]
>
> Claude Code 和 Codex 用的是不同协议的分组。给 Claude Code 用的密钥不能直接拿来跑 Codex，反过来也一样。分组的名称或说明里一般会注明用途，拿不准可以问平台管理员。

## 配置步骤

**1. 创建密钥**

在控制台 **账户 → 密钥设置** 点 **新增密钥**，分组选面向 Codex 的那个。复制生成的 `tk_live_` 密钥，它只显示一次。

**2. 查看分组里的模型**

```bash theme={null}
curl https://aitokenhub.vip/v1/models \
  -H "Authorization: Bearer <your-api-key>"
```

返回的 `data` 里每一项的 `id` 就是可用的模型 ID。如果返回里有 `"object": "list"`，说明这是 OpenAI 协议的分组，可以给 Codex 用。这个接口不收费。

**3. 编辑 Codex 配置**

打开 `~/.codex/config.toml`（Windows 是 `%USERPROFILE%\.codex\config.toml`，没有就新建），加入：

```toml theme={null}
model_provider = "tokenhub"
model = "<上一步查到的模型 ID>"

[model_providers.tokenhub]
name = "TokenHub"
base_url = "https://aitokenhub.vip/v1"
env_key = "TOKENHUB_API_KEY"
wire_api = "responses"
```

注意这里的 `base_url` 要带 `/v1`。

**4. 设置密钥并启动**

**macOS / Linux**

```bash theme={null}
export TOKENHUB_API_KEY="<your-api-key>"
codex
```

想长期生效，把 `export` 那一行加到 `~/.zshrc` 或 `~/.bashrc`。

**Windows PowerShell**

```powershell theme={null}
$env:TOKENHUB_API_KEY = "<your-api-key>"
codex
```

想长期生效，执行 `setx TOKENHUB_API_KEY "<your-api-key>"`，然后新开一个窗口。

发一条消息后，到控制台 **控制台 → 用量统计** 确认能看到这条请求。

## 常见问题

> **报错 401**
>
> 检查 `TOKENHUB_API_KEY` 是否在启动 `codex` 的那个终端里生效（`echo $TOKENHUB_API_KEY` 看一下），以及密钥是否已被吊销。

> **报错 404**
>
> 通常是 `base_url` 少了 `/v1`，或者 `wire_api` 没有设为 `responses`。

> **提示模型不可用**
>
> `model` 填的不在分组的模型列表里。用上面的 `curl` 重新查一遍，按返回的 `id` 原样填写。

其他错误见 [错误码](https://docs.aitokenhub.vip/reference/errors.md)。


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