# Codex App 集成

Codex App 是 OpenAI 的桌面端编程助手。它与 Codex CLI 共用本地 Codex 配置，因此可以通过同一套 TokenFlows Provider 配置来接入模型网关。

## 前置条件

- **Codex App**：从 [OpenAI 官方 Codex App 页面](https://developers.openai.com/codex/app) 下载并安装，确保可打开本地项目。
- **API Key**：在 [TokenFlows 控制台](https://dash.tokenflows.org/) 创建一个 API Key，建议选择 Codex 分组以匹配适用模型和倍率。
- **本地配置权限**：需要能写入当前用户目录下的 `~/.codex/`。

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

推荐使用 [CC Switch](https://github.com/farion1231/cc-switch/releases) 配置 Codex App。Codex App、Codex CLI 和 IDE 扩展会读取同一套 Codex 配置，使用 CC Switch 可以减少手动编辑 TOML/JSON 出错。

1. 下载并安装 [CC Switch](https://github.com/farion1231/cc-switch/releases)。
2. 打开 CC Switch，选择 `Codex`。
3. 新增 TokenFlows Provider：
   - API Base URL：`https://api.tokenflows.org`
   - API Key：填入你的 TokenFlows API Key
   - Model：选择或填写 `gpt-5.3-codex`
4. 点击启用或切换到该 Provider。
5. 重新打开 Codex App，进入项目后新建线程并发送一条测试消息。

> 如果 Codex App 已经打开，切换 Provider 后建议重启 App 或新建线程，确保新配置被读取。

## 方式二：手动配置

### 1. 创建配置目录

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

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

### 2. 写入 Codex 配置

在 `~/.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
```

### 3. 写入 API Key

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

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

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

### 4. 在 Codex App 中使用

1. 退出并重新打开 Codex App。
2. 打开一个本地项目。
3. 新建 Local 或 Worktree 线程。
4. 发送测试消息，确认模型响应正常。

## 常见问题

**Q：Codex App 没有读取新配置？**

先退出并重新打开 Codex App；如果仍无效，检查 `~/.codex/config.toml` 和 `~/.codex/auth.json` 是否位于当前系统用户目录。

**Q：Codex CLI 可用，但 Codex App 返回 401？**

确认 Codex App 使用的是同一个系统用户，并检查 `auth.json` 中的 API Key 是否填写正确。

**Q：能否只给某个项目使用 TokenFlows？**

可以在项目内创建 `.codex/config.toml` 写入项目级配置；但密钥仍建议放在用户级 `~/.codex/auth.json` 中，不要提交到 Git。