Codex 连接报错排查

先看错误正文，再处理重连

“正在重新连接 5/5”只是客户端重试状态。下面三类错误分别涉及鉴权、请求格式和登录凭证，重复点击重试通常不能解决。本文依据用户反馈中的错误文本分析；截图不能单独证明是哪一个配置文件或哪条上游线路出了问题。

问题一：401 Unauthorized，提示 API Key 不正确

如果你使用的是 OmniGateway 创建的 API Key，而客户端实际连接 api.openai.com，地址与密钥不配套是首先要检查的原因。OmniGateway Key 不能直接当作 OpenAI 官方 Key 使用。报错中附带的 OpenAI 密钥页面也不代表你必须去官方重新购买或申请密钥。

仅凭这一行 URL，仍不能排除代理转发了上游错误的情况。需要结合客户端实际连接地址和 OmniGateway 请求记录判断：是客户端发错地址，还是网关已接收请求后上游鉴权失败。

1. 在 OmniGateway 控制台确认使用的是 API 密钥；兑换码、充值码、网页登录密码都不能作为 API Key。
2. 检查当前生效配置：model_provider 应指向 omnigateway，且与 [model_providers.omnigateway] 的名称一致；base_url 应为 https://www.omnigateway.org/v1。
3. 如果使用 CC Switch，确认选中的是 Codex，并已保存、启用 OmniGateway 配置。只添加配置但未启用，不会切换当前连接。界面名称可能随工具版本不同。
4. 完全退出并重新启动对应客户端，再开一个新会话测试。若仍访问 api.openai.com，继续检查 CODEX_HOME、项目 .codex/config.toml、启动参数、profile 和配置工具是否覆盖了用户配置。
5. 若实际请求已到 OmniGateway，但仍返回 401，检查 Key 是否复制完整、有无空格或换行、是否已撤销或过期，以及客户端是否还在用旧 Key。
6. 若网关确认已接受你的 Key，之后才出现上游 401，将时间、模型 ID 和请求标识交给客服排查上游凭证。此时反复更换用户 Key 未必有效。

1unexpected status 401 Unauthorized: Incorrect API key provided: [REDACTED]2url: https://api.openai.com/v1/responses

问题二：unknown variant developer，消息格式不兼容

这说明请求已到达一个解析 JSON 的服务，但它的消息角色列表不支持 developer。developer 是 OpenAI 接口中的合法指令角色；用户正常输入一句话，也可能由客户端自动附带这类消息。

常见原因是旧版兼容适配器、仅支持部分 Chat Completions 的上游，或 Responses 到其他格式的转换不完整。messages[1] 只说明出错的是解析后的第二条消息，不能据此确定是用户写错了 JSON，也不能仅凭 latest_reminder 判断具体服务商。

1. 确认 Codex 使用 wire_api = "responses"，Base URL 只写到 /v1；不要填完整的 /chat/completions 或 /responses 路径。
2. 在控制台确认准确模型 ID、密钥分组和线路支持 Responses。模型能在普通聊天软件里回复，并不能证明它兼容 Codex 的流式输出、工具调用和多轮上下文。
3. 记录客户端及配置工具版本；升级到各自支持的稳定版本后，重新启用配置并在新会话中测试。
4. 用后文包含 developer 消息的最小 Responses 请求复现。若最小请求也报错，向客服提交模型、分组、时间和 request ID，让服务端检查协议转换及上游能力。
5. 若最小请求成功而 Codex 仍失败，继续检查流式传输、工具调用、多轮历史，以及中间代理是否改写请求；也可用已确认兼容的另一模型做对照。

1Failed to deserialize the JSON body into the target type:2messages[1].role: unknown variant 'developer',3expected one of 'system', 'user', 'assistant', 'tool', 'latest_reminder'

问题三：refresh_token 是空字符串

这里的 token 指登录流程中的刷新凭证，不是模型的计费 token，也不是 OmniGateway API Key。错误明确表示客户端尝试刷新登录，但提交的 refresh_token 为空。常见诱因包括不完整的登录缓存、迁移配置遗漏、配置工具写入空字段，或切换认证方式后仍使用旧状态；截图本身不能确定是哪一种。

• API Key 不能填入 refresh_token、access_token 或 id_token；也不要给这些字段填空字符串来绕过登录。
• 认证缓存可能位于 CODEX_HOME 下的 auth.json，也可能在系统凭证管理器里。删除某个 auth.json 不一定能清除当前登录状态。
• 优先使用客户端退出登录和重新配置功能。若需人工处理缓存，先确认实际目录并保留本地备份，只处理对应凭证；不要删除整个 .codex 目录。
• 若 API 请求已经走 OmniGateway，而其他账号功能仍提示刷新失败，应单独修复该功能的 ChatGPT 登录，不要把两个问题混为一谈。

1Failed to refresh token: 400 Bad Request:2Invalid 'refresh_token': empty string.3Expected a string with minimum length 1, but got an empty string instead.

一份便于排查的最小配置

下面选择“自定义 provider + 环境变量 API Key”这一种方式，适合用 CLI 隔离配置问题。修改前备份现有 config.toml，将相关字段合并到正确位置，保留原有 MCP 等设置，不要整文件覆盖，也不要重复添加同名 TOML 表。

默认用户配置在 macOS/Linux 的 ~/.codex/config.toml，Windows 为 %USERPROFILE%\.codex\config.toml。若设置了 CODEX_HOME，应检查该目录下的 config.toml。model 和 model_provider 是顶层字段，应放在第一个 [表名] 之前。

• 从控制台选择当前分组可用且支持 Responses 的模型 ID，不要直接照抄桌面端的显示名称。
• 这个示例用 env_key 读取独立环境变量，并明确关闭 requires_openai_auth。官方文档说明，requires_openai_auth = true 时会忽略 env_key；不要把两种认证方案混用。
• 旧教程或配置工具可能使用 OpenAI 认证存储方式。若继续使用那一方式，应由工具正确配置 API Key 登录；不要同时套用本文的环境变量方式。
• Base URL 中只保留一个 /v1；正常拼接后的生成接口是 https://www.omnigateway.org/v1/responses。

1# 将模型占位符替换为控制台中支持 Responses 的准确模型 ID2model = "REPLACE_WITH_YOUR_MODEL_ID"3model_provider = "omnigateway"4 5[model_providers.omnigateway]6name = "OmniGateway"7base_url = "https://www.omnigateway.org/v1"8wire_api = "responses"9env_key = "OMNIGATEWAY_API_KEY"10requires_openai_auth = false

把密钥交给实际运行的客户端

下面的命令在本地隐藏输入 Key，只为当前终端会话设置环境变量。随后在同一终端启动 Codex CLI，可以先验证密钥、地址和线路是否正确。

1$secureKey = Read-Host "输入 OmniGateway API Key" -AsSecureString2$env:OMNIGATEWAY_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password3# 在同一终端启动 CLI；不要打印密钥4codex

1printf '输入 OmniGateway API Key: '2read -r -s OMNIGATEWAY_API_KEY3printf '\n'4export OMNIGATEWAY_API_KEY5# 在同一终端启动 CLI6codex

第一步验证：密钥能否读取模型列表

在已经设置 OMNIGATEWAY_API_KEY 的终端执行。这个请求只读取模型列表，不触发模型生成；不要额外粘贴真实 Key 到命令或截图中。

1$headers = @{ Authorization = "Bearer $env:OMNIGATEWAY_API_KEY" }2$result = Invoke-RestMethod -Uri "https://www.omnigateway.org/v1/models" -Headers $headers3$result.data | Select-Object id

1curl -sS "https://www.omnigateway.org/v1/models" \2  -H "Authorization: Bearer $OMNIGATEWAY_API_KEY" \3  -w "\nHTTP %{http_code}\n"

第二步验证：最小 Responses 请求

选择一个已确认支持 Responses 的准确模型 ID，替换下方占位符。这次会产生一次真实模型调用，可能计费；手动测试一次即可。请求包含 developer 消息，可帮助定位第二类报错，不自动重复重试。

1. 确认返回的是正常模型响应，output 中有回答，而不是仅看到 HTTP 200 就认为成功。
2. 在控制台查本次请求的时间、模型和状态。成功后再用 Codex 新会话发“只回复 OK”。
3. 最后确认 Codex 请求也走同一 OmniGateway 路由。最小请求成功但客户端失败时，收集流式或工具调用错误，交给客服进一步复现。

1$headers = @{ Authorization = "Bearer $env:OMNIGATEWAY_API_KEY" }2$body = @{3  model = "REPLACE_WITH_YOUR_MODEL_ID"4  input = @(5    @{ role = "developer"; content = "Reply with OK only." }6    @{ role = "user"; content = "Connection test." }7  )8} | ConvertTo-Json -Depth 69$result = Invoke-RestMethod -Method Post -Uri "https://www.omnigateway.org/v1/responses" -Headers $headers -ContentType "application/json" -Body $body10$result | ConvertTo-Json -Depth 12

1curl -sS "https://www.omnigateway.org/v1/responses" \2  -H "Authorization: Bearer $OMNIGATEWAY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model":"REPLACE_WITH_YOUR_MODEL_ID","input":[{"role":"developer","content":"Reply with OK only."},{"role":"user","content":"Connection test."}]}' \5  -w "\nHTTP %{http_code}\n"

如果是其他状态，按这一表继续查

仍未解决：把这些信息交给客服

• 操作系统、Codex 客户端类型和版本，是否使用 CC Switch 或本地代理，以及工具版本。
• 发生时间和时区、准确模型 ID、密钥分组、实际 Base URL。
• 完整错误正文中的状态码和 request ID（如有）；先遮盖 Key、Authorization、access_token、refresh_token、id_token。
• 仅提供已脱敏的 provider 配置字段，以及 CODEX_HOME 是否自定义。不要发送完整 auth.json 或完整环境变量列表。
• 模型列表、最小 Responses、新会话测试分别是否成功；控制台是否找到对应记录。部分失败可能未进入消费日志，没有记录本身不能证明请求未到网关。