使用文档问题排查

codex unexpected status 401 unauthorized 排查教程

Codex CLI 返回 unexpected status 401 unauthorized 时，检查 OPENAI_BASE_URL、OPENAI_API_KEY、余额、模型权限和环境变量覆盖。

Codex 401 unauthorized

codex unexpected status 401 unauthorized 表示 Codex CLI 当前请求没有通过认证。先确认 OPENAI_BASE_URL 指向 CoderPlan 的 `/v1` endpoint，OPENAI_API_KEY 是完整的 CoderPlan API Key，再检查账户余额、模型权限和项目 `.env` 是否覆盖了当前 shell。

配置步骤

  1. 1

    确认 OPENAI_BASE_URL 包含 `/v1`

    Codex CLI 使用 OpenAI Compatible 接入时，Base URL 应填写 CoderPlan 的 `/v1` endpoint。

    OPENAI_BASE_URL=https://api.coderplan.ai/v1
  2. 2

    确认 OPENAI_API_KEY

    OPENAI_API_KEY 使用 CoderPlan 控制台生成的完整 `sk-` 密钥。少复制字符、多空格或使用旧密钥都会导致 401。

    OPENAI_API_KEY=sk-your-api-key
  3. 3

    排除旧环境变量覆盖

    检查项目 `.env`、shell profile、IDE 运行配置和系统 keychain，确认 Codex CLI 读取的是当前这组值。

  4. 4

    确认余额和模型权限

    如果认证字段正确，再检查 CoderPlan 余额、API Key 状态和目标模型是否可用。

常见问题

Codex 401 一定是 API Key 错了吗？

API Key 是最常见原因，但余额不可用、模型权限不匹配、OPENAI_BASE_URL 少了 `/v1` 或旧环境变量覆盖，也可能表现为 401。

为什么我已经 export 了新 key，Codex 还是 401？

Codex CLI 可能读取项目 `.env`、IDE 环境或全局配置。建议在同一个终端打印 OPENAI_BASE_URL 和 key 前缀，确认当前进程实际读取的新值。