# Codex CLI 集成

Codex CLI 是 OpenAI 的终端编程助手。通过 TokenFlows 网关，你可以在 Codex CLI 中使用 TokenFlows 提供的模型和计费策略。

## 前置条件

- **Node.js 环境**：建议安装 Node.js 18+，并可在终端中运行 `node --version`。
- **API Key**：在 [TokenFlows 控制台](https://dash.tokenflows.org/) 创建一个 API Key，建议选择 Codex 分组以匹配适用模型和倍率。
- **Codex CLI**：如未安装，可先执行 `npm install -g @openai/codex@latest`。

## 方式一：CC Switch 可视化配置（推荐）

推荐使用 [CC Switch](https://github.com/farion1231/cc-switch/releases) 管理 Codex CLI 配置。它会自动写入 Codex 所需的 `config.toml` 和 `auth.json`，适合需要经常切换模型、密钥或服务商的场景。

1. 下载并安装 [CC Switch](https://github.com/farion1231/cc-switch/releases)。
2. 打开 CC Switch，选择 `Codex` 或 `Codex CLI`。
3. 新增 TokenFlows Provider：
   - API Base URL：`https://api.tokenflows.org`
   - API Key：填入你的 TokenFlows API Key
   - Model：选择或填写 `gpt-5.3-codex`
4. 点击启用或切换到该 Provider。
5. 在项目目录运行 `codex`，确认 Codex CLI 已使用 TokenFlows 配置。

> 如需切换模型分组，在 TokenFlows 控制台创建新密钥后，通过 CC Switch 更新 Provider 即可。

## 方式二：手动配置

### 1. 安装 Codex CLI

```bash
npm install -g @openai/codex@latest
```

macOS / Linux 遇到权限问题时可加 `sudo`：

```bash
sudo npm install -g @openai/codex@latest
```

验证安装：

```bash
codex --version
```

### 2. 创建配置目录

```bash
# macOS / Linux
mkdir -p ~/.codex
```

```powershell
# Windows PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
```

### 3. 配置模型网关

在 `~/.codex/config.toml` 中写入：

```toml
model_provider = "tokenflows"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.tokenflows]
name = "TokenFlows"
base_url = "https://api.tokenflows.org"
wire_api = "responses"
requires_openai_auth = true
```

### 4. 配置 API Key

在 `~/.codex/auth.json` 中写入：

```json
{
  "OPENAI_API_KEY": "YOUR_API_KEY"
}
```

将 `YOUR_API_KEY` 替换为你在 TokenFlows 控制台创建的密钥。

### 5. 启动 Codex CLI

进入任意项目目录，运行：

```bash
codex
```

如果只想临时指定模型，也可以运行：

```bash
codex --model gpt-5.3-codex
```

## 常见问题

**Q：`codex --version` 提示命令不存在？**

确认 npm 全局目录已加入系统 PATH，运行 `npm bin -g` 查看路径。

**Q：连接失败或返回 401？**

检查 `base_url` 是否为 `https://api.tokenflows.org`，并确认 `auth.json` 中的 API Key 有效且未过期。

**Q：如何切换模型或密钥？**

推荐在 CC Switch 中维护多个 Provider；手动配置时，修改 `model` 或 `auth.json` 后重新启动 Codex CLI。