不登录 ChatGPT，把第三方 API 接进 Codex

先分清：ChatGPT 登录 vs API Key

同一时刻只有一套生效凭据。CLI 与客户端共用；一边 logout，另一边也要重新登录。

看当前生效哪一套：终端跑 codex login status。清空用 codex logout。

三种接到 Key 的方式

官方 Platform Key、兼容网关 Key 都可以。使用自定义 API 时，端点需要能被 Codex 以 Responses 协议访问（2026 年 2 月后 wire_api 仅支持 responses）。

export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

{
  "OPENAI_API_KEY": "sk-your-key"
}

CLI：从登录到确认

建议顺序：export → 管道 login → status → 再开 codex。CI 里用 secrets 管道进 login，不要把 Key 打进日志。

export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status
codex

只设置 OPENAI_API_KEY 不等于已经登录。使用内置 openai provider 时，显式 --with-api-key（或写好自定义 provider 的 env_key）才是稳妥做法。

凭据存在哪：file / keyring / auto

在用户级 ~/.codex/config.toml 用 cli_auth_credentials_store 控制。换机器或排查「明明 login 了却读不到」时，先看这个。

cli_auth_credentials_store = "file"

auth.json 里是明文级敏感信息。权限尽量仅本人可读；不要放进 iCloud/网盘同步的明文目录。

客户端：和 CLI 共用登录缓存

桌面客户端 / 应用客户端读的是同一套用户级缓存。一边登出，另一边也会失效。改完配置要「完全退出」再开，只关窗口常常不够。

1. 1

   先确认用户级目录

   默认 ~/.codex。可用环境变量 CODEX_HOME 改根目录——改了就要保证 CLI 与客户端看的是同一路径。

2. 2

   用 CLI 登录或写好 provider

   客户端很少单独再走一遍管道登录；多数情况是共用 CLI 已经写好的 auth / config。

3. 3

   完全退出客户端再打开

   让进程重新加载 auth.json 与 config.toml。若仍在使用旧 API，对照下面「用户级 vs 项目级」。

用户级 vs 项目级：provider 只能写在用户级

这是社区里最高频的「改了不生效」原因之一。项目目录里的 .codex/config.toml 在信任项目后会加载，但 provider 与 API 地址相关的键会被忽略。

config.toml：自定义兼容网关

自定义 provider 不能占用保留 id：openai、ollama、lmstudio。model_provider 的值必须与 [model_providers.xxx] 的 xxx 一致。

1. 1

   只编辑用户级文件

   路径：~/.codex/config.toml（或 $CODEX_HOME/config.toml）。

2. 2

   env_key 填变量名，不填密钥本身

   例如 env_key = "OPENAI_API_KEY"，然后在 shell 里 export 真正的值。写错成明文密钥字符串会导致鉴权失败。

3. 3

   base_url 按网关文档写

   常见兼容网关带 /v1，末尾不要多余斜杠。Azure 形态另有 /openai 或 /openai/v1 差异，以你拿到的说明为准。

4. 4

   重启会话验证

   新开终端再跑 codex；客户端完全退出重开。也可用工具箱里的 CC Switch 写入后同样重启。

model_provider = "codexfree"
model = "gpt-5"

[model_providers.codexfree]
name = "CodexFree"
base_url = "https://YOUR-GATEWAY-HOST/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
env_key_instructions = "export OPENAI_API_KEY before starting Codex"
requires_openai_auth = false
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

字段速查

若旧教程让你写 wire_api = "chat"：那是过时做法。Codex 已移除 Chat Completions 支持，只接受 Responses。网关若只有 /chat/completions，需要网关侧提供 Responses，或用本地路由转换协议（见工具箱）。

更轻的写法：只改 openai_base_url

如果只是把内置 openai provider 指到代理 / 路由器，不必新建 model_providers —— 在用户级 config 设 openai_base_url 即可。真正的多供应商、不同 Key、不同协议细节，仍用完整 model_providers。

openai_base_url = "https://YOUR-PROXY-HOST/v1"

踩坑对照表

现象 → 优先检查什么。

最后别靠感觉：用四步确认请求真的走对

保存文件只说明语法可能写进去了。身份、配置位置、进程和供应商日志都对得上，才算接入完成。

codex login status
printenv CODEX_HOME
cat ${CODEX_HOME:-$HOME/.codex}/config.toml
codex

1. 第 1 项

   确认当前身份

   login status 应与你选择的 ChatGPT 或 API Key 方式一致；不一致先 logout，再只重做一条路径。

2. 第 2 项

   确认读的是哪份文件

   检查 CODEX_HOME。provider 必须出现在用户级 config.toml，不是在项目里的 .codex。

3. 第 3 项

   彻底重启两个入口

   CLI 新开终端；客户端完全退出再打开。窗口关闭不一定等于进程退出。

4. 第 4 项

   发送短任务并看上游

   问一句短问题，再看供应商日志或余额。401 查 Key，404 查 Base URL / Responses，没记录就查旧进程和 model_provider。

FAQ