返回技术博客

CODEX CONFIG

Codex 配置不生效：从配置文件到 Provider 的排查顺序

按程序版本、配置覆盖、项目可信状态、Provider ID 和认证来源排查 Codex 配置不生效，保留已有配置与会话。

最后验证：2026-09-20

改了 config.toml，Codex 却仍在用原来的模型或接入地址，先检查运行环境、配置覆盖和当前会话。重新安装通常不会解决读取了另一份配置的问题。

本文核对于 2026 年 9 月 20 日，面向 Codex CLI 与 IDE 扩展。官方配置规则会随版本变化；以下检查不要求删除聊天记录、清空认证文件或扩大执行权限。首次安装请先看 Codex 接入教程。

先按症状确定检查范围

现象优先检查为什么
只在某个项目里不生效项目 .codex/config.toml、工作目录、项目可信状态项目层可能覆盖用户默认值，也可能因未受信任而被跳过
终端能用，IDE 不能用本地/WSL/SSH 环境、扩展运行位置、进程启动时间两边不一定读取同一用户目录或继承同一环境
模型和地址都还是旧的CLI 启动参数、所选 profile、Provider ID启动覆盖可能高于用户配置
地址已变但返回 401当前认证来源和 Key 所属平台配置被读取与凭据有效是两件事
返回 404 或模型不可用/v1、协议、模型 ID 和令牌权限请求已发出，问题不一定在配置文件加载

第一步：确认检查的是同一个 Codex

在发生问题的终端里运行以下只读命令。macOS、Linux、WSL 可使用：

pwd
command -v codex
codex --version

Windows PowerShell 使用：

Get-Location
(Get-Command codex).Source
codex --version

路径不同或版本不同，就先解决“启动了哪一个程序”。例如 Windows 本机与 WSL 内的 Codex 分属不同环境，修改 Windows 用户目录里的配置，不会自动修改 WSL 的配置。不要为了统一版本先卸载全部工具；记录两边结果再判断。

IDE 扩展可以通过右上角齿轮进入 Codex Settings → Open config.toml，直接打开它使用的配置入口。若只有 IDE 出问题，继续看 VS Code 与终端配置差异。

第二步：沿覆盖顺序找出真正生效的值

截至本文核对时，官方文档给出的优先级由高到低为：

  1. CLI 参数及 --config 覆盖。
  2. 可信项目中的 .codex/config.toml，从项目根目录到当前工作目录，较近的配置优先。
  3. --profile 选中的 profile 文件。
  4. 用户配置 ~/.codex/config.toml。
  5. 已下发的云端托管默认配置。
  6. 系统配置与内置默认值。

当前官方说明将 profile 描述为用户配置目录中的独立 profile-name.config.toml 文件。若你使用旧版客户端，不要直接照搬新版本的 profile 组织方式；先对照本机版本、启动帮助和相应官方文档。

排查时只追踪一个字段，例如 model_provider：启动脚本有没有指定它？项目配置有没有覆盖？profile 是否仍指向旧供应商？依次核对，比同时重写所有文件更容易找出原因。

项目不受信任时，Codex 会跳过项目配置层。仅在理解并信任仓库内容后调整可信状态，不要为了让一个设置生效而绕过安全要求。企业托管约束也不能靠用户配置随意覆盖。

第三步：核对 Provider 的三个连接点

连接点核对方法
model_provider值必须对应 [model_providers.<id>] 中的同一个 ID；显示名称不能代替 ID
base_url 与协议RootFlowAI 的 Codex 入口是 https://api.rootflowai.com/v1；不要重复 /v1，也不要填门户网页地址；具体协议配置沿用接入教程
认证来源分清教程中的本机认证文件方案与自定义 Provider 的 env_key 方案；使用哪一种就核对哪一种，不混放多套冲突设置

如果自定义 Provider 使用 env_key，配置值应该是环境变量名称，而不是密钥本身。该变量还必须存在于启动 Codex 的进程环境里；在另一个终端临时设置变量，不会更新已经运行的客户端。

不要把完整 auth.json、环境变量列表或带 Authorization 的调试日志贴到工单。提供 Provider ID、去除凭据的域名、客户端版本和错误时间就能开始定位。

第四步：用最小改动验证

  1. 保存原配置备份，并记下当前版本和启动方式。
  2. 每次只纠正一个明确的问题，例如 Provider ID 拼写或重复的 /v1。
  3. 保存后退出受影响的客户端进程，再重新启动一个会话确认；保留旧会话记录。
  4. 按 接入教程的模型列表检查核对 Key 和模型可见性。
  5. 模型列表正常后再验证实际工作流。列表查询成功只说明相应读取接口可用，不保证 Responses、工具调用或全部模型权限已经通过验证；模型推理会按实际规则计费。

不要反复发送相同付费任务来验证一个文件路径问题。先完成只读检查，再做必要的最小请求，并在 消费日志中按时间核对。

仍然失败时，提供这份信息

记录操作系统及是否使用 WSL/SSH/容器、CLI 或扩展版本、程序路径、项目路径、配置层级、Provider ID、模型 ID，以及脱敏后的完整错误。说明“哪个入口正常、哪个入口失败”，比只提供一张报错截图更有帮助。

错误已明确为接口返回时，继续查 API 参考；需要重新核对令牌时，查看 获取 API Key。

资料来源

本文为官方资料与本站接入说明的排查整理，不是对所有客户端版本和运行环境的兼容性保证。