codex 403 报错

Codex CLI 或 IDE 插件跑着跑着突然回一个 403，比 401 更让人摸不着头脑：Key 明明是好的，昨天还能用。这篇不讲概念，直接给一套排查顺序——先分清是「没身份」「有身份但不让做」还是「中间那层拦了」，再逐项动手验证，最后说清哪些情况下这套顺序不适用。

Codex 跑着跑着突然回一个 403，比 401 更让人摸不着头脑——Key 明明是好的，昨天还能用，今天就翻脸了。核心区别在于：401 是「你没证明自己是谁」，403 是「认出你了但不让你干」。所以 403 出现，基本可以判定身份已经通过了，问题出在「你的身份被允许做什么」这件事上。

下面这套顺序是从最省事的验证开始，一层层往深处走：先分清错误来源，再查 Key 的权限范围，然后怀疑中转层，最后自检客户端配置。结尾会说清哪些情况下这套顺序不适用，免得你白折腾。

第一步：先把 403 和 401 分开，别混着查

先看响应体里的错误码与 message 字段。有的网关会把上游原始错误透传，关键词能直接指向「模型无权」「地区不支持」「额度组不允许」中的哪一类。如果有 message 内容，优先按里面的关键词定位，比翻文档快得多。

• 记下报错发生的动作：是握手或列表模型阶段就 403，还是发完第一条消息才 403，这两者指向完全不同的层
• 确认客户端有没有打印出完整的响应体，有些工具默认只显示状态码，把 body 藏起来，反而让排查变难
• 如果遇到的是延迟和连通性异常，可以先到 /tools/speed-test 量一遍基线，把网络因素先排除掉

第二步：查 Key 的权限范围和账号档位

这一步的核心问题是：这个 Key 到底有没有权限做你正在做的事。按量计费的 Key 与订阅制额度的调用口径不一样，用订阅身份去调按量接口，或用只读或受限 Key 去调生成接口，都可能被判 403。团队共用 Key 时，管理员改过一次权限就会让所有人同时报错——先问一句「最近动过权限吗」，比什么排查都快。

1. 确认 Key 的绑定范围看这个 Key 是否绑定了模型白名单、项目空间或额度组。具体字段名称和口径到 /official-api 核对当时说明，各家写法不同。
2. 检查账号档位与策略企业账号常见的坑是 SSO 策略或合规开关上线后，老 Key 被静默降权，表现为突然全员 403。判断方法：问同期其他同事是否也报错。
3. 排除地区与组织限制部分接口对调用地区或组织归属有限制，如果近期换过网络出口或账号归属地，这个问题会浮出来。

第三步：怀疑中转层——Base URL 与兼容层的锅别背错

直连和走中转站是两条链路。403 有可能根本没到官方，中转站自己做了模型白名单、分组限制或风控，请求在中间就被拒了。这种情况下把官方文档翻烂也没用，因为错误根本不是官方发的。

确认客户端里请求打到了哪个域名，有没有被环境变量、配置文件、插件设置三处里的某一处覆盖成另一个地址。三处不一致时以哪一处生效要看客户端说明，但排查时至少要先把三处的值列出来对照一次。换源前先到 /ai-nav/category/ai-api 对比一下口径，避免把不同链路的限制混为一谈。

• 把同一个 Key、同一条命令分别对直连地址和当前地址各跑一次，能立刻分清是账号问题还是中间层问题
• 检查中转站的模型映射表，有些中转站把小写模型名映射到另一个上游，原账号权限不覆盖映射后的模型
• 看中转站是否要求额外的鉴权头，少传了头可能以 403 而非 401 返回

第四步：客户端配置与环境变量的自检清单

前三步都排完还没定位，就把注意力收回到本地。这一步最容易出低级的坑，但也最容易被忽略。按下面清单逐项过，基本能覆盖大部分残留问题。

# 排查看当前生效的 base url 与 key 前缀（示意，字段名以客户端文档为准）\nenv | grep -i -E 'OPENAI|CODEX|API_BASE'\n# 再检查项目级配置文件里有没有覆盖同名变量

什么情况下这套顺序不适用

• 错误是间歇性的、同一命令时好时坏：多半是限流或上游抖动，该走并发与重试那条线，别在权限上钻牛角尖
• 整团队同一时间集体 403：先按上游策略变更或账号级封禁处理，个人层面怎么改配置都无效
• 只有某一个模型 403、其他模型正常：直接归到模型白名单或档位限制，不用再查网络和证书
• 刚上线的合规或 SSO 策略之后才开始报：把组织策略当作首要怀疑对象，而不是 Key 本身

判断标准很简单：如果换 Key、换网络、换地址三种组合里至少有一种能恢复正常，那就说明问题在某一个具体链条上，顺着那条链继续查；如果三种全失败，那问题就在账号或组织级别，本地怎么做都无效。

403 不是「你没登录」，而是「登录了，但这件事不归你干」——把这句话记住，排查方向就不会跑偏。