Codex CLI 配置

Codex CLI 可通过 OpenAI-compatible provider 接入 pragma。

第一次配置前，先完成：

• 注册与登录
• 创建 API Key

如果你还不确定该选哪个客户端，先看 客户端配置总览。

开始前准备

你需要准备：

• 一个可用的 pragma 账号。
• 一个你自己创建的 API Key。
• 已安装的 Codex CLI。
• 当前终端能访问 Pragma 主站。

建议先在 创建 API Key 页面完成 /v1/models 最小验证。验证成功后再配置 Codex CLI，可以更快区分是 Key 问题、网络问题还是 Codex 配置问题。

Base URL 应该填哪个

Codex CLI 走 OpenAI-compatible 协议：

Codex CLI 环境变量

从同一个终端启动 Codex，确认环境变量被当前进程读取。

OPENAI_API_KEYsk-your-key

OPENAI_BASE_URLhttps://pragma.academic-ruc.cc/v1

备选变量OPENAI_API_BASE=https://pragma.academic-ruc.cc/v1

验证任务请只回复 OK

https://pragma.academic-ruc.cc/v1

不要漏掉末尾的 /v1。Claude Code 直连才使用不带 /v1 的地址。

基本配置

配置项	值
Provider 类型	OpenAI Compatible
Base URL	https://pragma.academic-ruc.cc/v1
API Key	你在 pragma 创建的 sk-...

环境变量方式

不同 Codex 版本支持的变量名可能略有差异。常见写法：

$env:OPENAI_API_KEY = "sk-your-key"
$env:OPENAI_BASE_URL = "https://pragma.academic-ruc.cc/v1"

如果你的客户端使用 OPENAI_API_BASE，则写：

$env:OPENAI_API_BASE = "https://pragma.academic-ruc.cc/v1"

macOS / Linux（bash / zsh）用 export：

export OPENAI_API_KEY="sk-your-key"
export OPENAI_BASE_URL="https://pragma.academic-ruc.cc/v1"

设置后关闭旧的 Codex 进程，再从同一个终端重新启动 Codex CLI。

配置文件方式

配置文件通常在：

• Windows：C:\Users\<用户名>\.codex\config.toml
• macOS / Linux：~/.codex/config.toml

在其中选择自定义 provider，并设置默认模型。例如：

model_provider = "custom"
model = "gpt-5.5"

具体字段名以你安装的 Codex 版本为准。关键是 Base URL 使用：

https://pragma.academic-ruc.cc/v1

/model 只显示 5 个模型是正常的

Codex CLI 的 /model 交互列表默认只展示少数几个内置模型，这是 Codex 客户端自身的行为，不是中转站的限制。如果你要用的模型（例如 gpt-5.4-mini）不在列表里，直接在配置文件的 model 字段写模型名，或用命令行参数指定即可，不必受列表约束。

模型选择建议

场景	建议
日常代码解释和修改	gpt-5.4 或 gpt-5.5
轻量任务	gpt-5.4-mini
长上下文或复杂 agent 任务	控制上下文长度，必要时新开会话

配置后验证

配置后验收先短测，再长任务

1. 环境变量

   从设置变量的同一个终端启动 Codex。

2. 短任务

   先跑“请只回复 OK”。

3. 复杂任务

   短任务通过后再跑长上下文。

先发一个短任务，例如：

请只回复 OK

短任务可用后，再尝试读取文件、执行命令或修改代码。不要一开始就把大量日志和长上下文塞进同一个请求。

表现	先检查
401	API Key 是否复制完整
403	Key 是否有目标模型权限
404	Base URL 是否漏写或多写路径
首 Token 很慢	上下文长度、reasoning / effort、并发 agent 数量

延迟建议

Codex agent 请求常走 /v1/responses，长上下文和高 reasoning 会显著增加首 Token 时间。

如果感觉越来越慢：

1. 新开会话或清理上下文。
2. 降低 reasoning / effort。
3. 减少一次性粘贴的大段日志。
4. 先看 故障排查。

下一步

我想做什么	下一页
确认其他客户端怎么填	客户端配置总览
排查 401 / 403 / 404	故障排查
判断是不是服务故障	服务状态
配 Claude Code	Claude Code
配 RTK 省 token	RTK 省 token 配置
在 OAuth、API、RTK、Headroom 之间选择	省 token 决策中心