OpenAI Codex CLI

OpenAI 2025 发布的开源命令行 AI 编程工具（@openai/codex）。

区分两个 "Codex"

• 本节说的 Codex CLI = OpenAI 官方 agentic CLI
• 不是 PrimeRouter 里底层的 ChannelTypeCodex 渠道类型

在配置前请先准备好 PrimeRouter API Key（参考 通用准备）。

安装

# 全平台（需 Node 20+）
npm install -g @openai/codex
codex --version

配置文件位置

系统	配置文件路径
macOS	~/.codex/config.toml
Linux	~/.codex/config.toml
Windows	%USERPROFILE%\.codex\config.toml（即 C:\Users\<你>\.codex\config.toml）

编辑配置

macOS / Linux

mkdir -p ~/.codex
vim ~/.codex/config.toml

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

写入（⚠️ 顶层配置必须放在 [model_providers.*] 段之前——TOML 会把段头之后的键全部归入该段，写反顺序 Codex 会静默回落到默认 OpenAI provider）：

推荐方式 · key 写入 Codex 登录凭证（auth.json）

key 存在 Codex 自己的凭证文件里，不依赖任何环境变量——终端、GUI 双击、IDE 扩展都能读到：

# 默认用哪个 provider + model（必须在最前面）
model_provider = "primerouter"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true

# 自定义 provider 指向 PrimeRouter
[model_providers]
[model_providers.primerouter]
name = "PrimeRouter"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://primerouter.ai/v1"

macOS / Linux

printf '%s' "sk-你的primerouter-key" | codex login --with-api-key
codex

Windows PowerShell

"sk-你的primerouter-key" | codex login --with-api-key
codex

⚠️ 与 ChatGPT 账号登录互斥：codex login 只保存一份凭证，之后登录 ChatGPT 账号会顶掉这里的 key（反之亦然）。一键脚本会先把原 auth.json 备份为 auth.json.bak.<时间戳>，需要换回去时 codex login 重新登录即可。

备选方式 · key 走环境变量（env_key）

只在你需要 ChatGPT 账号登录与 PrimeRouter 并存、靠切 model_provider 来回换时才用：

model_provider = "primerouter"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers]
[model_providers.primerouter]
name = "PrimeRouter"
wire_api = "responses"
env_key = "PRIMEROUTER_API_KEY"
base_url = "https://primerouter.ai/v1"

macOS / Linux

export PRIMEROUTER_API_KEY="sk-你的primerouter-key"
codex

macOS GUI 双击启动（额外一步）

# GUI App 不读 shell 配置，需注入 launchd 用户会话
launchctl setenv PRIMEROUTER_API_KEY "sk-你的primerouter-key"

Windows PowerShell

$env:PRIMEROUTER_API_KEY = "sk-你的primerouter-key"
codex

Windows 系统环境变量（永久，GUI 可见）

setx PRIMEROUTER_API_KEY "sk-你的primerouter-key"
:: 重启终端后生效

⚠️ env_key 不是「读不到就回落」：环境变量缺失时 Codex 会直接让请求失败并报 Missing environment variable: PRIMEROUTER_API_KEY。任何没继承到 shell 配置的启动方式（GUI App、IDE 扩展、在写入变量之前就打开的终端）都会踩到。也不能和 requires_openai_auth 一起写——env_key 先被检查、先失败。

从别的服务商迁移：codex resume 里看不到历史会话

Codex 的 resume 列表只显示 model_provider id 与当前配置一致的会话（codex resume --last 同样过滤，--all 只放开目录过滤）。所以把 model_provider 从别家的 id（如 foo-relay）改成 primerouter 之后，旧会话就从列表里消失了。

会话文件一个都没丢，仍在 ~/.codex/sessions/ 下，只是被过滤掉了。三种处理方式：

1. 重跑一键脚本（推荐）。脚本会自动沿用这台机器原有的 provider id，并把它指向 PrimeRouter，历史会话继续可见：

   curl -fsSL https://primerouter.ai/install/codex.sh | bash

2. 临时查看，不改配置：

   codex resume -c model_provider=原来的id

3. 想要干净的 id、接受旧会话不再出现在列表里（文件依然保留）：

   PRIMEROUTER_CODEX_PROVIDER_ID=primerouter curl -fsSL https://primerouter.ai/install/codex.sh | bash

忘了原来的 id？看备份 ~/.codex/config.toml.bak.* 里的 model_provider，或直接从会话文件里取：

grep -ho '"model_provider":"[^"]*"' ~/.codex/sessions/*/*/*/*.jsonl | sort | uniq -c | sort -rn

工具调用兼容性

• Codex CLI 默认走 OpenAI Responses API（/v1/responses）做 agent loop
• PrimeRouter 把 Responses 转译为兼容形态，Claude 系列工具调用全程可用
• wire_api = "chat"（chat completions）已被 codex-cli 0.14x 起移除，配置里写 chat 会直接报错拒绝启动，请使用 "responses"