API Codex

Appearance

Codex 报 401 Unauthorized 怎么解决 ​

Codex 报 401 Unauthorized，通常不是代码逻辑错误，而是服务端没有接受当前认证信息。常见原因包括 API Key 无效、环境变量没有加载、auth.json 状态过期、Base URL 配错，或者 Provider 读取了另一套配置。

最有效的排查方法是按层验证，不要一上来反复卸载、重装或更换模型。先确认错误发生在哪一层，再修复对应配置。

先记录错误上下文 ​

保留以下信息，但不要分享完整密钥：

  • Codex CLI 版本：codex --version
  • Node.js 和 npm 版本
  • 操作系统和终端类型
  • 错误状态码和首条错误消息
  • 使用的 Provider 名称和模型 ID
  • 请求是否通过 curl 成功

把 API Key 截断成前几位和后两位即可，例如 sk-abcd...9x。不要把完整 Authorization Header 放进 issue、截图或聊天记录。

第一步：确认 Key 仍然有效 ​

登录服务商控制台，确认 Key 没有被撤销、过期或超出额度。检查项目、组织和模型权限，确认这把 Key 属于当前环境。

如果你不确定 Key 是否泄露，直接撤销旧 Key 并创建新 Key。轮换后先单独验证 API，再回到 Codex 配置，不要在同一时间修改多个变量。

第二步：确认当前终端读到了变量 ​

macOS 和 Linux 可以运行：test -n "$CLAWSOCKET_API_KEY" && echo "API key is set"。

PowerShell 可以运行：if ($env:CLAWSOCKET_API_KEY) { "API key is set" }。

这里只检查是否存在，不要使用 echo $CLAWSOCKET_API_KEY 打印完整密钥。确认变量名和配置文件中的引用完全一致，大小写、下划线都不能错。

如果你刚刚修改了 shell 配置或系统环境变量，关闭当前终端并重新打开。已经启动的进程不会自动获得后来新增的环境变量。

第三步：用 curl 分离问题 ​

使用服务商给出的 Base URL 和 endpoint 发出最小请求。例如：

curl https://api.clawsocket.com/v1/responses -H "Authorization: Bearer $CLAWSOCKET_API_KEY" -H "Content-Type: application/json" -d '{"model":"codex","input":"只返回 OK"}'

如果 curl 也返回 401，问题通常在 Key、Header、Base URL 或账号权限。

如果 curl 成功但 Codex 返回 401，问题更可能在 Codex 的 Provider 映射、环境变量引用、配置覆盖或认证文件。

第四步：检查 auth.json ​

部分 Codex CLI 登录方式会在用户目录的 .codex 文件夹中保存认证状态，常见文件名是 auth.json。文件位置和字段会随版本变化，不要假设所有教程都适用。

排查时可以：

  1. 备份当前认证文件，不要上传备份。
  2. 退出 Codex，重新完成官方登录流程。
  3. 确认文件权限只允许当前用户读取。
  4. 检查文件中是否有旧 Provider、错误 Token 或损坏的 JSON。

不要从陌生网站下载 auth.json，也不要把自己的认证文件交给别人“帮忙修复”。它可能包含可直接调用服务的凭据。

第五步：检查 config.toml 和配置覆盖 ​

config.toml 往往负责默认模型、Provider 和 Base URL。401 常见配置错误包括：

  • env_key 指向了不存在的变量
  • Provider 名称和当前选择不一致
  • Base URL 使用了错误的版本路径
  • 项目级配置覆盖了用户级配置
  • 模型名来自控制台展示名称，而不是 API 模型 ID

先用最小配置验证，再逐项加回自定义设置。不要同时替换模型、Base URL 和认证方式，否则错误来源会变得不清楚。

第六步：确认 Base URL 没有重复路径 ​

服务商可能提供 Base URL 和完整 endpoint 两种地址。Base URL 通常类似 https://api.example.com/v1，客户端会在它后面拼接具体路径。

如果你把完整的 /responses 地址也填进 Base URL，客户端可能最终请求到 /v1/responses/responses，得到的通常是 404；如果路径经过网关转发，也可能表现为认证失败。始终以当前 API 文档的 URL 结构为准。

不同状态码的含义 ​

401 ​

认证信息无效、缺失、过期或格式不正确。优先检查 Key、Header、变量名和认证文件。

403 ​

认证可能有效，但当前账号、项目或模型没有权限。检查组织、额度、模型访问范围和来源限制。

404 ​

Base URL、版本路径或 endpoint 不匹配。对照服务商文档检查最终请求 URL。

429 ​

触发速率限制、并发上限或额度限制。降低并发，加入有上限的指数退避，不要无限重试。

常见“无效修复” ​

反复重新安装 Codex ​

如果 codex --version 能正常返回，重新安装通常不能解决凭据和 Base URL 问题。先定位配置层。

只换模型名 ​

模型名错误更常见的结果是 404 或模型不可用。401 仍然应该先检查认证信息。

把 Key 发给别人排查 ​

这是高风险做法。让对方根据状态码、脱敏后的配置和变量名帮助判断，不要共享真实密钥。

删除所有配置文件 ​

删除前先备份并确认文件职责。盲目删除可能丢失登录状态，也会让后续排查缺少证据。

修复后的验证顺序 ​

  1. 用新 Key 或确认过的 Key 发出最小 curl 请求。
  2. 重启终端，确认环境变量重新加载。
  3. 运行 codex --version，确认使用的是预期版本。
  4. 让 Codex 只读读取一个项目文件。
  5. 再执行一个可以通过 diff 和测试验证的小修改。

如果第五步失败，问题可能已经从认证层进入工具调用、模型能力或项目环境，不要继续用 401 的思路排查。

FAQ ​

为什么登录成功后还是 401？ ​

登录状态和 API Provider 可能是两套认证。确认当前任务是否切换到了自定义 Provider，以及它读取的变量和 Base URL 是否正确。

为什么 curl 成功但 Codex 失败？ ​

最常见原因是 Codex 没有读取同一个环境变量，或 config.toml 覆盖了 curl 使用的地址。逐项对比 Provider、变量、URL 和模型名。

Windows 上 401 特别常见吗？ ​

Windows 更容易遇到多个 Node、npm、PowerShell 和 WSL 环境并存的问题。用 Get-Command node、Get-Command npm 和 Get-Command codex 确认它们来自同一环境。

换一个 API Key 后应该做什么？ ​

先验证新 Key，再撤销旧 Key。确认日志和代码中没有旧 Key，最后重新启动使用 Codex 的终端或服务。

继续阅读 ​

专注 Codex 使用方法与 API 工程实践

Copyright © 2026 API Codex