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

# Codex CLI 接入

> 将 Codex CLI 通过 router.onetoken.sh 接入自定义 OpenAI 兼容网关。

<Info>
  本文基于 2026 年 3 月 25 日可访问的 Codex CLI 集成文档改写。
</Info>

## 适用场景

如果你希望在以下场景中使用 Codex CLI，可以采用本文方案：

* 在本地终端中通过 `router.onetoken.sh` 使用 Codex CLI
* 通过统一网关管理不同环境中的 Codex 请求
* 将 Codex CLI 指向自定义 OpenAI 兼容接口

## 1. 安装 Codex CLI

按官方方式安装 Codex CLI：

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

安装完成后，可执行以下命令确认版本：

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

## 2. 配置 `config.toml`

Codex CLI 使用 `~/.codex/config.toml` 作为全局配置文件。你可以创建或编辑该文件，并写入以下内容：

```toml theme={null}
model_provider = "onetoken"
model_reasoning_effort = "high"
model = "gpt-5.3-codex"

[model_providers.onetoken]
name = "OneToken"
base_url = "https://router.onetoken.sh/v1"
env_key = "ONETOKEN_API_KEY"
```

上面的示例表示：

* 默认 provider 名称为 `onetoken`
* 默认模型为 `gpt-5.3-codex`
* 接口认证从 `ONETOKEN_API_KEY` 环境变量中读取
* 请求通过 `https://router.onetoken.sh/v1` 发出

<Note>
  这里的 `base_url` 使用的是 OpenAI 兼容接口常见的 `/v1` 路径。这是依据原始 Codex CLI 集成文档中的 OpenAI 兼容写法做出的适配。如果你们的网关在根路径已直接兼容 OpenAI API，请将其改为 `https://router.onetoken.sh`。
</Note>

<Note>
  示例模型名使用 `gpt-5.3-codex`。如果你的网关使用的是其他模型命名规则，请按实际支持的模型 ID 调整。
</Note>

## 3. 设置 API Key

Codex CLI 会从 `env_key` 指定的环境变量中读取令牌。建议将以下变量写入你的 shell 配置文件：

```bash theme={null}
export ONETOKEN_API_KEY="<your-onetoken-token>"
```

### 写入配置文件并持久化

如果你希望每次打开终端时自动生效，可以将上面的变量写入 shell 配置文件。

#### zsh

```bash theme={null}
cat >> ~/.zshrc <<'EOF'
export ONETOKEN_API_KEY="<your-onetoken-token>"
EOF
```

写入后执行：

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

#### bash

```bash theme={null}
cat >> ~/.bashrc <<'EOF'
export ONETOKEN_API_KEY="<your-onetoken-token>"
EOF
```

写入后执行：

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

如果你使用的是其他 shell，请将同样的变量写入对应的启动文件。

## 4. 写入 `config.toml` 并持久化

如果你希望直接用命令写入 `~/.codex/config.toml`，可以使用以下方式：

```bash theme={null}
mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model_provider = "onetoken"
model_reasoning_effort = "high"
model = "gpt-5.3-codex"

[model_providers.onetoken]
name = "OneToken"
base_url = "https://router.onetoken.sh/v1"
env_key = "ONETOKEN_API_KEY"
EOF
```

如果你已经有现有配置，请先手动备份，再根据实际内容合并，避免覆盖其他设置。

## 5. 启动 Codex CLI

进入项目目录后，直接运行：

```bash theme={null}
cd /path/to/your/project
codex
```

配置正确时，Codex CLI 发出的请求会通过 `router.onetoken.sh` 转发。

## 6. 常用配置项

以下是接入时最常用的几个配置项：

* `model_provider`：当前默认 provider 名称
* `model`：默认模型 ID
* `model_reasoning_effort`：推理强度，可选 `low`、`medium`、`high`、`xhigh`
* `env_key`：读取 API Key 的环境变量名
* `base_url`：网关地址

## 7. 项目信任级别

Codex CLI 支持按项目设置不同的信任级别。你可以在 `config.toml` 中增加如下配置：

```toml theme={null}
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

可选值说明：

* `trusted`：允许较高权限的操作，例如执行命令和修改文件
* `untrusted`：采用更保守的访问限制

## 8. 常见问题

### 认证失败

优先检查以下内容：

* `ONETOKEN_API_KEY` 是否已正确设置
* `config.toml` 中的 `env_key` 是否与环境变量名称一致
* `base_url` 是否与实际网关地址一致

### 模型不可用

通常是模型 ID 与网关实际支持的名称不一致。请根据你们当前网关支持的模型列表调整 `model` 字段。

### 修改配置后没有生效

优先检查以下内容：

* 当前终端是否已重新加载环境变量
* `~/.codex/config.toml` 是否已保存
* 是否存在其他 profile 或命令行参数覆盖了默认配置

### 如何确认 Codex CLI 已正常安装

可以执行以下命令：

```bash theme={null}
codex --help
codex -V
```

如果命令可正常返回帮助信息和版本号，说明 CLI 已安装完成。