排障：升级后 Codex OAuth 仍失败？删除旧版 openai-codex Provider 覆盖配置

一句话结论（TL;DR）

如果你在“早期试水 Codex”阶段手动在 openclaw.json 里配置过 models.providers.openai-codex，这个遗留覆盖配置可能会继续生效，从而遮蔽 OpenClaw 新版内置的 Codex OAuth Provider：

• 你明明已经升级到包含修复的版本
• 也重新授权了 OAuth
• 但仍出现 401 / scope（权限范围）相关失败或诡异回退

已验证的解决办法是：

1. 备份配置
2. 删除 models.providers.openai-codex 这段旧覆盖
3. 重启 OpenClaw

然后 openai-codex/gpt-5.4 可能会立刻恢复正常。

为什么“升级了也没好”

近期上游确实合入了 Codex OAuth 相关修复（提升了授权探测与回退行为）：

• PR #37558：移除一个错误的 Codex OAuth 探测逻辑
  • https://github.com/openclaw/openclaw/pull/37558
• PR #38026：在 scope error 场景启用 Chat Completions fallback（包含 gpt-5.4 的常见场景）
  • https://github.com/openclaw/openclaw/pull/38026

但如果你的 openclaw.json 里仍保留着手动的 models.providers.openai-codex，OpenClaw 就可能继续按你“旧时代的 provider 形状”走，而不是走新版内置 Provider 的修复路径。

你是否命中这个坑（快速自检）

符合以下特征，优先试这篇的修复：

• 你曾经手动写过 models.providers.openai-codex（比如显式 baseUrl / api / 手工列 model）
• 你已升级到包含上述 PR 的版本
• Codex OAuth 表面看配置好了，但请求仍失败（401 / scope / 频繁 fallback）

修复步骤（务实版）

改配置前先备份。

1. 打开 openclaw.json
2. 找到类似结构：

{
  "models": {
    "providers": {
      "openai-codex": {
        // ... 旧的手工 provider 配置 ...
      }
    }
  }
}

3. 删除（或在你自己的配置管理工具里禁用）仅 models.providers.openai-codex 这一段
4. 重启 OpenClaw
5. 重试你的目标模型（例如 openai-codex/gpt-5.4）

谁最该检查这项配置

如果你符合下面任意一条，建议优先检查是否还残留了旧版 openai-codex Provider 覆盖：

• 最近刚把 OpenClaw 升级到支持 Codex OAuth 修复的新版本
• 之前为了试用 Codex，手工写过 models.providers.openai-codex
• 现在仍遇到 401、scope、fallback 异常，且看起来不像是单纯授权过期

这类问题的典型特征不是“完全没配置好”，而是新版能力已经到位，但被旧配置继续劫持。如果你已经反复重试授权、仍旧失败，这一项非常值得优先排查。

常见上线判断问题

什么时候该优先怀疑旧 provider 覆盖，而不是继续反复重做 OAuth？

如果重新授权本身能成功，但一跑请求又立刻回到同样的 401、scope 或 fallback 异常，就不要再把它当成单纯的 OAuth 失效问题。此时旧版手工 provider 配置残留，往往比“重新授权一次”更值得先查。

想在接近生产的环境里低风险验证，最稳的做法是什么？

先备份配置，只删除 models.providers.openai-codex 这一段，重启 OpenClaw，再只重试一个已知失败的 Codex 模型。这样既能控制影响面，也能保留清晰的前后对比证据。

为什么明明 token 没问题，看起来却还是像 OAuth 故障？

因为表面症状发生在请求阶段，团队很容易把问题继续归因到 access token、scope 或 OpenAI 上游状态。但如果真正生效的是旧版 models.providers.openai-codex 覆盖配置，OpenClaw 其实根本没有走到新版内置 Codex OAuth 路径。此时你重复浏览器授权，也不会改变实际处理请求的那条代码路径。

哪些环境最该先查这种配置遮蔽？

共享服务器、长期运行的开发机，以及跨多个 OpenClaw 版本连续升级过的主机，最该先查这项问题。这些环境最容易遗留早期手写的 provider 覆盖配置，当年有用，现在却会静默压住已经修好的默认行为。

面向搜索入口的对比判断：旧 provider 覆盖，还是 Codex OAuth 真的挂了

这类问题最容易浪费时间的地方在于，两个故障表象很像，都是“刚升级或刚登录后，Codex 请求还是失败”。更快的判断方式不是继续盲目重登，而是先问最近变化发生在哪一层。

更应优先怀疑旧 provider 覆盖的信号包括：

• OAuth 重新授权能走完，但同一类请求立刻继续失败
• 这台机器跨过多个 OpenClaw 版本升级
• 之前有人手工改过 models.providers.openai-codex

更应优先怀疑真实 OAuth 故障的信号包括：

• 全新机器、没有手写 provider 配置，也出现同样问题
• 浏览器授权流程本身就走不完
• 多个操作员在没有配置漂移的前提下同一时间一起报错

这也是搜索意图层面的关键区别。搜 Codex OAuth 升级后还是 401 的人，很多时候第一需求并不是“再来一遍授权教程”，而是先排查配置优先级是否把新版内置 Provider 压住了。

值班团队怎么快速区分这是旧 provider 覆盖，还是 Codex OAuth 真的挂了

如果浏览器里的 OAuth 授权流程本身能顺利完成，但请求一落到模型调用阶段又回到同样的 401、scope 或 fallback 异常，就不要再默认把它当成纯 OAuth 故障。对值班团队来说，这时更高概率的嫌疑对象，其实是 旧的 models.providers.openai-codex 覆盖配置仍在生效。

更像是 旧 provider 覆盖 的信号包括：

• OAuth 重登能完成，但同类请求马上继续失败
• 机器经历过多次 OpenClaw 升级，历史上有人手改过 provider 配置
• 只对 Codex 这条路径异常，其他整体认证流程看起来还正常

更像是 真实 OAuth 故障 的信号包括：

• 授权流程本身就无法完成
• 新机器、无手写 provider 覆盖，也出现同样问题
• 多个环境在相近时间同时报出一致的授权失败

这个分流的价值很直接，它能阻止团队把时间继续浪费在重复重登授权上，而忽略真正还在接管流量的旧配置。

修好之后，交接里至少留下什么

如果这次故障已经恢复，建议给下一位值班同事留下一条很短但可复用的交接说明，至少写清这四项：

1. 是哪台主机或哪个配置文件删掉了 models.providers.openai-codex
2. 重启前后的 OpenClaw 版本号
3. 哪个失败模型在修复后恢复了，例如 openai-codex/gpt-5.4
4. 现场是否还保留着其他自定义 provider 覆盖

这条交接的价值很直接，它能减少团队在下一次迁移、复盘或交叉排障时，把旧覆盖配置又重新加回去。

删除旧 provider 后，先做 3 个回归验证

不要只看“请求终于成功了一次”。删除 models.providers.openai-codex 后，建议按这 3 步留下可复验结果：

1. 同一模型复测：用变更前失败的同一个模型名复测，例如 openai-codex/gpt-5.4，确认不是换模型后绕过了问题。
2. 重启后复测：重启 OpenClaw 后再跑一次，确认旧 provider 没有被配置管理、脚本或同步工具重新写回。
3. 其他 provider 对照：抽查一个非 Codex provider，确认这次修改只影响 Codex OAuth 路径，没有误删共享 credential 或全局 provider 配置。

这 3 个验证点能把“我删了一段配置”变成可交接的恢复证据，也能帮助团队判断下一步是收口事故，还是继续排查认证链路。

如果你是从 troubleshooting 进来，先分清 OAuth 失败和旧 provider override

GA4 现在把这篇 Codex OAuth 修复页和 setup、runtime 选择流量放在同一组里。读者可能已经完成浏览器登录，但 OpenClaw 里 Codex 仍然 fallback 或启动失败。

不要先重复 OAuth 登录，先把证据拆成三类：

1. OAuth 根本没完成：先确认 OpenAI authorization callback、本地 credential cache，以及 Codex runtime 自己的 auth status，再改 provider config。
2. OAuth 已完成，但旧 openai-codex override 仍然生效：检查 provider ordering、陈旧环境变量 override 和 model routing，避免旧 provider entry 掩盖新的 Codex runtime。
3. Codex 启动了，但实际由其他 runtime 回复：对比 agent order、runtime selection logs 和 provider fallback messages，再判断是不是 token scope 问题。

这能避免高意图 setup 读者反复卡在登录页面，把修复聚焦到移除陈旧 provider override 和确认 runtime 优先级。

3 分钟判断：删旧 override，还是先别动配置

如果你是从 Codex OAuth、setup 或总排障页跳到这里，先不要直接删除配置。用 3 分钟确认改动半径：

1. 历史上手写过 models.providers.openai-codex：先备份配置，再删除这一段做最小验证。
2. 没有任何手写 provider，但 OAuth 流程本身失败：先别动配置，优先查 callback、credential cache 和网络访问。
3. 删除后只在当前进程有效：检查启动脚本、同步工具或环境变量是否又把旧 override 写回。
4. 同机还有其他自定义 provider：只改 Codex 相关块，避免把共享 credential 或全局 provider 一起误删。

这一步把“升级后 Codex 仍失败”的搜索流量分成两类：配置优先级遮蔽走本文；真实 OAuth 或网络失败，先回认证链路排查。

删除旧 override 前，先准备这份回滚卡

如果这是共享机器或生产环境，不要把 models.providers.openai-codex 当成“看到就删”的配置。先准备一张很小的回滚卡，让修复可逆：

1. 备份原配置块：只保存 Codex 相关 provider 块和相邻的 model routing 配置，不要复制整份含 secret 的配置。
2. 记录触发症状：写清删除前失败的是 401、scope、No API key found，还是 fallback 到其他 provider。
3. 限定验证模型：指定一个原本失败的模型名，例如 openai-codex/gpt-5.4，避免修复后用不同模型误判成功。
4. 写清回滚条件：如果非 Codex provider 异常、启动失败或配置管理把块写回，就立刻回滚并转查启动脚本。
5. 确认没有同步源：检查 dotfiles、systemd 环境、容器 env 和配置同步脚本，避免旧 override 在下一次重启后复活。

这张回滚卡能把高意图访客从“盲删配置”带到“最小半径验证”。它也能帮助团队判断流量恢复后，是否真的修到了 Codex OAuth 路径，而不是暂时绕开了另一个配置漂移。

如果旧 override 会自己回来，先查是谁在写配置

有些团队删掉陈旧的 models.providers.openai-codex 块并重启后，下一次启动又遇到同样的 Codex OAuth 失败。这通常说明坏 override 不只存在于当前配置文件里，而是被另一个来源重新生成。

先别新开 OAuth 事故，优先查这些持久化来源：

1. dotfiles 或 bootstrap 脚本：搜索 setup 脚本里的 openai-codex，避免个人初始化脚本把旧 provider 写回。
2. 容器或 systemd 环境：对比运行时 env 和已编辑配置，尤其是服务从模板启动时。
3. 配置同步工具：检查 repo、secret manager 或 host profile，确认是否会在部署后重写 OpenClaw 配置。
4. 同机多个 profile：确认失败 agent 使用的 profile，正是你刚刚编辑的那个 profile。

当这篇文章第一次能解决、但重启后又复发时，这就是正确分支。它能把反复进来的 Codex OAuth 流量导向配置归属排查，而不是继续重复浏览器登录。

从 legacy override 流量转成迁移检查清单

如果你是因为 openai-codex legacy override、Codex OAuth 不生效或模型顺序被旧配置覆盖搜到这里，先不要只删除一行配置。更稳的迁移顺序是先列出当前 agent order、全局 runtime override、环境变量和本地 OAuth 状态，再判断到底是哪一层仍在抢优先级。

最小检查清单包括：旧 override 的来源文件、当前选中的 provider/model、登录后的 token 更新时间、以及一次干净重启后的实际 runtime。只有当旧配置在重启后仍覆盖新 OAuth 路径时，才把它升级为兼容性修复；否则先完成配置清理和凭据刷新。

相关阅读

• OpenClaw 智能体故障排查指南
• OpenClaw 完整安装指南
• OpenClaw macOS 快速安装指南

搜索入口分流：Codex OAuth 仍走 legacy override 先看什么

如果你是从 “Codex OAuth still uses legacy OpenAI override”、“OpenClaw Codex OAuth fallback” 或 “登录了 Codex 还是走旧 OpenAI 配置” 搜到这里，先把问题拆成四层：

1. 确认当前 agent order 生效来源：不要只看 OAuth 登录成功页，要核对运行时实际选择的是 Codex agent、OpenAI agent，还是旧的 override 顺序。
2. 确认 legacy override 是否仍被读取：环境变量、旧配置文件、per-agent order 和默认 provider 顺序可能同时存在，最终以运行时解析结果为准。
3. 确认 OAuth 凭据与 agent 绑定关系：OAuth 成功不等于所有 agent 自动切换；需要确认 token 存放位置、agent id 和 runtime 读取范围一致。
4. 保留最小证据：登录方式、agent order 片段、启动日志里的 provider 选择、实际请求命中的模型，比单独说“还是 fallback”更容易定位。

这类问题不要只重复登录 OAuth。最短路径是同时核对凭据、agent order、legacy override 和运行时 provider 选择日志。

相关阅读

• Codex OAuth 登录后为什么还是 fallback：先看 per-agent order
• OpenClaw Agents 排障指南：任务卡住、工具不回、结果异常时先查什么
• OpenClaw 完整安装指南：从零部署到可用
• sessions_send 超时排障：子代理不返回时先看哪一层

删除 provider 配置前，先走安全 OAuth 清理路径

如果你是搜“Codex OAuth still uses legacy openai-codex provider”或“OpenClaw Codex login keeps falling back after upgrade”来到这里，先把旧 override 当成配置事故处理，不要立刻轮换所有凭据。低风险顺序是：

1. 记录当前 agent order，以及运行时实际选中的 provider；
2. 确认旧 openai-codex override 是在 agent、workspace，还是 global config 层；
3. 先把旧 override 移走，不要直接删除整个 auth 目录；
4. 对目标 Codex provider 重新跑 OAuth，并先用一个只读任务验证，再恢复后台作业；
5. 把修复前后的 provider resolution 输出和升级记录放在一起。

这条路径面向需要快速恢复 Codex 的运维搜索流量，同时保留足够证据去区分旧 provider 优先级、陈旧 OAuth 状态，以及更大的模型路由回归。

来源

• Issue（复现 + 根因 + workaround）：
  • https://github.com/openclaw/openclaw/issues/40066
• 相关修复 PR：
  • https://github.com/openclaw/openclaw/pull/37558
  • https://github.com/openclaw/openclaw/pull/38026