Codex 报「unexpected status 401 Unauthorized」或「Missing environment variable」：原因与修复

两条报错分别是什么意思

在 Codex 的终端界面里，两条报错都显示为红色，开头是 ■。按 openai/codex 源码（rust-v0.166.0，2026-11-02 核对），它们的组成如下，第一行带的是一键安装写入的 env_key_instructions：

■ Missing environment variable: `ROUTER_ONE_API_KEY`. Create an API key at https://router.one/dashboard/api-keys and set the ROUTER_ONE_API_KEY environment variable.
■ unexpected status 401 Unauthorized: <服务端的错误信息>, url: <Codex 请求的地址>, request id: <id>

• 第一行写出 env_key 指定的变量名；provider 块里设了 env_key_instructions 时，后面再接这段说明。Codex 在准备请求时读取这个变量，值为空或只有空白字符也按没设处理，而且不会重试，所以这次请求根本没有发到任何服务器。
• 第二行冒号后面是服务端自己的错误信息：JSON 错误正文里有 error.message 就用它，没有就原样打印正文（最多 1000 字节），正文为空时写 Unknown error。后面依次是 , url: …（Codex 请求的地址）、响应带 cf-ray 头时的 , cf-ray: …、响应带 x-request-id 头（没有时改读 x-oai-request-id）时的 , request id: …，以及响应带 x-openai-authorization-error 头、或 x-error-json 头里带错误码时的 , auth error: … 和 , auth error code: …。

Missing environment variable：设好 Codex 要读的变量

Codex 从 env_key 指定的变量里读取 Key，而 env_key 写在顶层 model_provider 选中的那个 [model_providers.<id>] 块里：按本页的 Router One 配置是 ROUTER_ONE_API_KEY，你自己的配置块写了别的名字，就是那个名字。按 openai/codex 源码（rust-v0.166.0，2026-11-02 核对），Codex 读取启动时继承的环境变量，另外启动时还会加载 ~/.codex/.env（CODEX_HOME 下的 .env 文件），其中的同名变量会覆盖 shell 里的值。之后才设的、或者只在另一个终端里设的变量，它都看不到。先设好变量，再从带着这个变量的 shell 启动 Codex：

# macOS / Linux，当前终端：
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
# 以后新开的终端（zsh；bash 改成 ~/.bashrc，macOS 上的 bash 改成 ~/.bash_profile）：
echo 'export ROUTER_ONE_API_KEY="sk-your-router-one-key"' >> ~/.zshrc
# 检查是否已导出且不是空白（不打印 Key）：
printenv ROUTER_ONE_API_KEY | grep -q '[^[:space:]]' && echo "已导出" || echo "没有导出，或者是空白"
# Windows PowerShell，当前窗口：
$env:ROUTER_ONE_API_KEY = "sk-your-router-one-key"
# 以后新开的窗口（保存为用户环境变量）：
[Environment]::SetEnvironmentVariable("ROUTER_ONE_API_KEY", "sk-your-router-one-key", "User")

• shell 配置文件在终端启动时读取：改完 ~/.zshrc、~/.bashrc 或 ~/.bash_profile，要新开一个终端，或者在当前终端里 source 一下。用 SetEnvironmentVariable 保存的变量只对之后新开的 PowerShell 窗口生效，所以当前窗口还要再用 $env: 设一次。
• IDE 插件：按 Codex 的配置基础文档（2026-11-02 核对），CLI 和 IDE 插件共用同一套配置层，所以编辑器里同样需要这个变量；插件里的 Codex 用的是编辑器启动时的环境。设好变量后，把编辑器完全退出再重新打开。
• ~/.codex/.env 由 Codex 自己读取，不受启动它的 shell 或编辑器影响：在里面写一行 ROUTER_ONE_API_KEY=sk-your-router-one-key，CLI 和编辑器里的 Codex 重新启动后都能读到。如果这个文件里已经有 ROUTER_ONE_API_KEY，Codex 用的就是那一行的 Key，要么保持更新，要么删掉。
• provider 块里没有任何凭据设置时，Codex 根本不带 Key。按 openai/codex 源码（rust-v0.166.0，2026-11-02 核对），没有打开 requires_openai_auth 的自定义 provider 只发送这个块自己配置的凭据：env_key 读到的 Key、experimental_bearer_token（Codex 配置参考不推荐这种写法），或者这个块的 auth、gateway_oauth 设置取得的令牌，不会用 codex login 保存的登录信息。请求不带 Key 时，Router One 返回 401。
• 如果报错里是别的变量名，比如 OPENAI_API_KEY，说明你的会话用的 provider 块就是这么写的。接 Router One 时，给 Key 单独用一个变量，像下面的 Router One 配置那样用 ROUTER_ONE_API_KEY，免得读取 OPENAI_API_KEY 的其他工具把你的 Router One Key 拿去用。

unexpected status 401：先看 url

这一行里的 url 是请求发往的地址，看它就知道是谁返回的 401。按 openai/codex 源码（rust-v0.166.0，2026-11-02 核对），这个地址由当前 provider 的 base_url 加上 /responses 组成；内置的 OpenAI provider 用 API Key 登录时是 https://api.openai.com/v1，用 ChatGPT 登录时是 https://chatgpt.com/backend-api/codex，除非 ~/.codex/config.toml 里的 openai_base_url 给了它别的地址，这时内置 provider 的凭据会发到那个地址，包括 ChatGPT 登录令牌。内置 provider 先走 WebSocket，所以它的 Reconnecting... 和回退提示里，同一个端点可能显示成 wss:// 开头的地址：

Router One 拒绝了 Key 时

url 是 https://api.router.one/v1/responses 的 401，问题出在 Codex 发出的 Key，和模型无关。逐项检查，然后重新启动 Codex：

• Key 是当前有效的：它在控制台 → API 密钥里仍然存在、没有过期，而且变量里存的就是这把 Key，不是后来已经换掉的旧 Key。
• 值里只有 Key 本身：连引号一起粘进去、在前面多写了 Bearer，或者 Key 中间混进空格，都会被拒绝。按 openai/codex 源码（rust-v0.166.0，2026-11-02 核对），Codex 把变量的值原样放在 Bearer 后面；值里带换行时，这个值根本放不进 Authorization 头，请求就会不带 Key 发出去。
• 必须是 Router One 的 Key：变量里放的是其他服务的 Key（比如 OpenAI API Key）时，Router One 同样返回 401；请到控制台 → API 密钥创建一把 Router One 的 Key。
• ~/.codex/.env 里没有旧 Key：按 openai/codex 源码（rust-v0.166.0，2026-11-02 核对），Codex 启动时会加载这个文件，里面的 ROUTER_ONE_API_KEY 会覆盖 shell 里的值，所以旧的那一行要改掉或删掉。
• 会话用的是 Router One 的 provider 块。如果 ~/.codex/config.toml 改用 openai_base_url 把内置的 OpenAI provider 指向 Router One，按 openai/codex 源码（rust-v0.166.0，2026-11-02 核对），Codex 发的是它自己的 OpenAI 登录凭据（通常是 codex login 保存的那份），不是 ROUTER_ONE_API_KEY：改用下面的 provider 块，或者用 codex login --with-api-key 以你当前的 Router One Key 登录，绝不要与 ChatGPT 登录同用。
• 已经在运行的程序还拿着旧值：改变量之前就打开的编辑器或终端，发出的仍是旧 Key。
• Router One 返回的 401 在控制台 → 日志里没有记录，因为网关在调用任何模型之前就拒绝了请求。如果 Key 一直被拒，写邮件给 support@router.one 时附上报错时间和报错行里的 request id（如果有），但不要附上 Key 本身。

不启动 Codex，先检查 Key

Router One 的接口参考里，GET /v1/models 对无效或缺失的 API Key 返回 401，所以用它就能按 Codex 发送 Key 的方式测试这把 Key，而不用调用模型。在启动 Codex 的那个 shell 里运行：它测试的是这个 shell 里的 ROUTER_ONE_API_KEY；如果 ~/.codex/.env 里也设了这个变量，Codex 发的是那里的值。它只会打印 HTTP 状态码：200 表示 Key 被接受，401 表示被拒绝。

curl -s -o /dev/null -w "%{http_code}\n" https://api.router.one/v1/models -H "Authorization: Bearer $ROUTER_ONE_API_KEY"
# Windows PowerShell：
curl.exe -s -o NUL -w "%{http_code}" https://api.router.one/v1/models -H "Authorization: Bearer $env:ROUTER_ONE_API_KEY"

用一键命令把 Codex 接到 Router One

带上你的 Router One Key 运行一键命令。它会在缺少 Codex CLI 时先安装，用 Router One 的配置替换 ~/.codex/config.toml（env_key = ROUTER_ONE_API_KEY，以及对应的 env_key_instructions；原有的文件保留为 config.toml.bak.<time>，需要的其他设置可以从里面复制回来），把 Key 写进 shell 配置文件（zsh 是 ~/.zshrc，bash 是 ~/.bashrc，其他 shell 是 ~/.profile），再发一个测试请求，Key 无效时会报 401。Windows 用 PowerShell 那一行，它会把 Key 存成用户环境变量。之后在新开的终端里，或者在安装之后才启动的编辑器里运行 codex。macOS 上用 bash 时，新开的终端窗口读的是 ~/.bash_profile：除非它已经加载 ~/.bashrc，否则把同一行 export 也加进去。

curl -fsSL https://router.one/install/codex.sh | bash -s -- sk-your-api-key
# Windows PowerShell：
$env:ROUTER_ONE_API_KEY = "sk-your-api-key"; irm https://router.one/install/codex.ps1 | iex

Router One 的 provider 配置

顶层的 model 和 model_provider = "router" 两行写在第一个表头之前，块里的 base_url、env_key、wire_api 三行照下面的样子保留，而且都写在 ~/.codex/config.toml 里：按 Codex 的高级配置文档（2026-11-02 核对），项目里的 .codex/config.toml 写了 model_provider 或 model_providers 会被忽略。这个 provider 不要打开 requires_openai_auth：按 Codex 认证文档（2026-11-02 核对），它会为这个 provider 打开 OpenAI 登录（用 ChatGPT 或 OpenAI API Key 登录），而 Router One 的 provider 用 env_key 读取 Key。一键安装写入的文件指向同一个 provider，另外加了 env_key_instructions，也就是 Codex 在缺少变量的提示后面打印的那段说明。

# ~/.codex/config.toml
model = "gpt-5.6-sol"
model_provider = "router"

[model_providers.router]
name = "router"
base_url = "https://api.router.one/v1"
env_key = "ROUTER_ONE_API_KEY"
wire_api = "responses"

# 在 shell 里：
# export ROUTER_ONE_API_KEY=sk-your-router-one-key

常见问题