OpenClaw5.18升级5.22:一次Codex OAuth 授权问题的排查复盘

小龙虾🦞OpenClaw 个人实践 · B-25

5.18 → 5.22 升级 · Codex 路由迁移 · 接 B-24 认证排查

升级到 5.22 之后
openai/gpt-5.5 不是你以为的那条路

信息截至 2026 年 5 月 · 基于 5.18→5.22 升级实录 · 关键结论已对照官方文档核实

先说一个我自己踩到的、很容易把人绕进去的坑。

在 5.18 上，用 Codex 路线对话，短回答还行，一旦是长上下文、详细分析、长文本生成，就经常卡住，最后日志里反复跳这一行：

codex app-server turn idle timed out waiting for completion

它不是没启动，而是 Codex app-server 已经进了处理流程，但 OpenClaw 一直等不到”完成”事件，最后被超时看门狗判了死刑。

我升级到 5.22，又重新踩了一遍认证的坑，最后才搞明白：问题的根子不在网络，也不在缺 API Key，而是 5.22 把 OpenAI Codex 的推荐用法整个换了。这篇就讲清楚换成了什么，以及怎么干净地迁过去。

如果你看过 B-24

OpenClaw 升级5.18后认证失效

B-24 里我建议 OAuth 用户把模型配成openai-codex/gpt-5.5。那是 5.18 时代的正确做法。但 5.22 把这条路降级成了 legacy——继续这么写，反而可能触发本文要讲的报错。这篇就是 B-24 的更新版，看完按新方式来。

一、先纠正一个认知：看到 openai/gpt-5.5 不代表走的是 API Key

这是整篇文章最值钱的一句话，先记住：

在 5.22 里，给 agent 选 openai/gpt-5.5，意思是”用 Codex 跑这个模型”，不是”用 OpenAI 付费 API Key”。

这是经过官方文档确认的：在新版本中，openai/*是 OpenAI 模型的标准写法，agent 的对话默认通过原生 Codex app-server 运行时来执行。普通 OpenAI API Key 只保留给图像、向量、语音这类非 agent 接口。

完整的链路是这样的：

openai/gpt-5.5（模型名）

↓

Codex runtime（运行时）

↓

openai-codex synthetic auth（认证）

↓

Codex app-server（实际执行）

所以模型名只是入口，真正决定它怎么跑的是 runtime 和 auth。看模型名判断路线，是这次最容易掉进去的误区。

二、5.18 → 5.22 到底变了什么

写法	5.22 中的地位
openai/gpt-5.5	✅ 推荐路线。配合 Codex runtime，走 Codex app-server
openai-codex/gpt-5.5	⚠️ Legacy 路线。会被 doctor –fix 自动修正，硬写可能让 lane 走旧 provider 报错
openai-codex:邮箱	这是 auth profile 的 id，不是模型写法。两者别混

关键区别在于：openai-codex现在的定位是provider 和 auth profile 的 id，是认证来源的名字；而它在旧版本里同时被当成模型前缀用，这个双重身份就是混乱的来源。

⚠️ 别浪费时间的地方

如果你在 5.18 上想通过加appServer.turnCompletionIdleTimeoutMs这类超时参数来缓解卡顿，会直接被 schema 拦下来报must NOT have additional properties。5.18 的本地 schema 不认这些字段，在这上面折腾是死路，别在这浪费精力。

三、升级到 5.22 后，为什么还报 No API key

我升级完，最初还是报：

No API key found for provider “openai-codex”

这行报错最坑的地方在于：它看起来像”缺 OpenAI API Key”，但实际根本不是要你去配 API Key。真实原因是——OpenClaw 某个地方还在走旧的 openai-codex provider 路由。

进一步查，发现配置里残留着类似这样的东西：

“openai-codex:你的邮箱”: {

“provider”: “openai-codex”,

“mode”: “oauth”

}

核心误区：手写 OAuth profile 没有用

这段配置看起来像个 OAuth profile，但它只是个声明，不等于真的拿到了 token。auth profile 里有这条记录，不代表授权有效。如果 auth order 还指向这种”有壳没料”的 profile，运行时就会一直报 No API key。手写配置伪装不了登录状态。

四、完整解决步骤

下面这套流程是我实际跑通的顺序。其中第二步有个官方的偷懒办法，比手动清理省事很多。

第一步：保持 5.22 推荐的模型配置

核心是模型名用openai/gpt-5.5，runtime 显式走 codex，不要再把默认模型写成 openai-codex/gpt-5.5。

{

plugins: { entries: { codex: { enabled: true } } },

models: {

providers: {

openai: { agentRuntime: { id: “codex” } }

}

agents: { defaults: { model: “openai/gpt-5.5” } }

}

第二步：清理 legacy 残留（推荐用官方命令）

偷懒办法：官方提供了openclaw doctor --fix，专门把 legacy 的 Codex 模型前缀、旧 auth profile id、旧 auth order 自动迁移到 canonical 的 openai/* 路线，顺带清理 stale session pin。能用这个就别手动 grep 了。

# 一键修复 legacy 路由（推荐先跑这个）

openclaw doctor –fix

如果想自己确认还有没有残留，可以手动搜一遍：

# 搜旧路由残留

grep -RInE ‘openai-codex/|openai-codex:’ \

~/.openclaw/openclaw.json \

~/.openclaw/agents/main/agent 2>/dev/null

重点处理两类残留：

•openai-codex/gpt-5.5这种旧模型前缀 → 迁移成openai/gpt-5.5

• 手写的无效 OAuth profile → 直接删掉，别留着碍事

第三步：重新 OAuth 登录（解决问题的关键）

清理完之后，重新做一次真正的 OAuth 授权。这一步才是让 Codex app-server 的 synthetic auth 真正可用的关键。

# 重新授权

openclaw models auth login –provider openai-codex

# 浏览器回调不方便时，用 device code

openclaw models auth login –provider openai-codex –device-code

补充：官方文档里 OAuth 登录也出现过--provider openai的写法。两种 id 在不同版本下都可能有效，我这边实测openai-codex能登录成功。如果一个不行，换另一个试。

第四步：验证 Runtime auth（别只看模型名）

openclaw models status

重点不是看 Default 那行，而是看 Runtime auth：

Default : openai/gpt-5.5

Runtime auth

– openai via codex uses openai-codex
effective=synthetic:codex-app-server |status=usable

看到openai via codex ... status=usable这行，说明 Codex 路线已经通了。

这时 Default 显示 openai/gpt-5.5 是正常的，不代表它改走了普通 API Key——它依然在走 Codex。这就是第一节那句话的实际验证。

第五步：重启 gateway，新开会话

# 重启

openclaw gateway restart

# 进聊天后，先别复用旧会话

/new

为什么一定要新开会话

旧 session 可能还 pin 着旧的模型路由或旧 auth 状态。结果就是配置明明改对了、授权也重做了，对话却还在报旧错误。这种情况下别怀疑前面的步骤，先/new开个新会话试试。

五、说点实话：5.22 改善了，但没全好

重新授权之后，我那个 No API key 的报错没再出现，Codex 路线恢复正常。5.22 相比 5.18，在 gateway 性能、auth profile 处理、doctor 迁移、compaction 超时、失败会话状态恢复这些方面确实都有改善。

但我得诚实地讲：如果你的场景是极长上下文、超长回复、复杂的多工具调用，长回复超时不一定彻底消失。这种情况下还是要靠分段输出、主动压缩上下文、及时清理旧会话来配合。

换句话说，这次升级解决的是”路由配错导致的认证失效”，不是”所有超时问题”。两者别混为一谈。

一页纸排查清单，收藏备用

① 模型名改回openai/gpt-5.5，runtime 走 codex

② 跑openclaw doctor --fix清理 legacy 残留

③auth login --provider openai-codex重新授权

④models status看 Runtime auth 是否 usable

⑤gateway restart+/new开新会话

一句 No API key，能把人坑半天。

不是因为它难，是因为它在说谎——明明是路由没迁干净，却假装成”缺钥匙”。

升级这种事，看懂 runtime 比看懂模型名重要得多。

你从 5.18 升到 5.22 之后，Codex 路线是顺利通了，还是也卡在某一步？评论区聊聊。