OpenAI Codex CLI 安装配置与认证实践

前言

今晚把 OpenAI Codex CLI 真正接进了当前工作环境，目标很明确：后续代码分析、架构梳理、样例工程深挖，都优先交给 Codex 处理。

过程中踩了几个典型坑：

• 本机未安装 codex
• 安装后依然无法使用
• 401 Unauthorized
• Missing bearer or basic authentication in header
• 以及和服务端 server_error 混在一起，容易误判

这篇文章把实际安装、认证和排查流程完整记下来，后面复用会省很多时间。

---

一、问题背景

在代码分析任务中，希望把 OpenAI Codex 作为默认编程助手使用，但最开始执行时直接失败：

codex --version

返回：

Command not found

说明当前机器上还没有安装 Codex CLI。

另外，在后续尝试调用 Codex 时，还出现过：

{
  "type":"error",
  "error":{
    "type":"server_error",
    "code":"server_error",
    "message":"An error occurred while processing your request..."
  }
}

以及：

401 Unauthorized: Missing bearer or basic authentication in header

这两个报错虽然都发生在 Codex 调用过程中，但性质完全不同：

• server_error：OpenAI 服务端临时异常
• 401 Unauthorized：本地 Codex CLI 没有完成认证

---

二、确认运行环境

先检查 Node.js 和 npm：

node -v
npm -v

输出：

v22.22.0
10.9.4

说明安装环境没问题，可以直接通过 npm 安装 Codex CLI。

顺手确认 npm 上的 Codex 包版本：

npm view @openai/codex version

输出：

0.113.0

---

三、安装 Codex CLI

安装命令：

npm install -g @openai/codex

安装完成后验证：

codex --version
which codex

输出：

codex-cli 0.113.0
/usr/bin/codex

到这里，本机安装已经完成。

---

四、查看 Codex 登录方式

为了确认认证方式，先看帮助：

codex login --help

可以看到支持两类登录方式：

1. API Key
2. Device Auth

其中 device auth 更适合有人在旁边、可以网页授权的场景。

---

五、通过 OAuth / Device Auth 认证

启动设备授权：

codex login --device-auth

CLI 会给出：

• 授权网页地址
• 一次性验证码
• 有效时间（通常 15 分钟）

典型流程：

1. 打开 https://auth.openai.com/codex/device
2. 输入一次性验证码
3. 登录 OpenAI 账号并授权

授权完成后检查状态：

codex login status

输出：

Logged in using ChatGPT

这说明 Codex CLI 已经具备可用登录态。

---

六、典型报错与排查思路

6.1 Command not found

原因： 没安装 Codex CLI
处理：

npm install -g @openai/codex

---

6.2 401 Unauthorized

典型报错：

Missing bearer or basic authentication in header

原因：

• 没有 OpenAI 认证信息
• 没完成 codex login --device-auth
• 或未设置 OPENAI_API_KEY

处理：

codex login --device-auth
codex login status

如果是 API Key 模式，也可以走：

printenv OPENAI_API_KEY | codex login --with-api-key

---

6.3 server_error

典型报错：

{
  "type":"server_error",
  "code":"server_error"
}

原因：

这是 OpenAI 服务端错误，不一定是本地配置问题。

建议：

• 先确认本地已登录
• 再重试一次
• 如果是大任务，拆小再跑
• 避免误把服务端临时故障当成本地安装失败

---

七、安装后建议的验证动作

7.1 检查版本

codex --version

7.2 检查登录状态

codex login status

7.3 运行最小测试

codex exec "say hello"

如果这条能正常返回，说明本地安装、网络和认证链路都通了。

---

八、在代码仓里使用 Codex 的建议

如果要在真实代码仓里使用，建议：

1. 在 git 仓库中运行

git rev-parse --is-inside-work-tree

确保当前目录是可信仓库。

2. 大任务拆分

不要一上来就让 Codex：

• 扫完整个大仓库
• 直接输出完整架构 + PPT + 优化方案

更稳妥的方式是拆成：

1. 目录结构与模块识别
2. 主执行链路分析
3. 后端差异分析
4. 架构归纳与 PPT 总结

3. 对需要文件读写的任务，明确工作目录

例如：

codex exec --dangerously-bypass-approvals-and-sandbox 'Analyze repo and write notes.md'

要确保：

• 工作目录明确
• 输出路径可写
• 不要让沙箱挡住读代码能力

---

九、最终结果

本次完成了：

• ✅ 安装 OpenAI Codex CLI
• ✅ 配置 Device Auth / OAuth 登录
• ✅ 验证登录状态正常
• ✅ 成功把 Codex 用于代码库分析任务

后续代码相关工作可以直接默认交给 Codex 处理。

---

十、总结

这次排查里最容易混淆的一点是：

安装问题、认证问题、服务端问题是三回事

现象	根因	处理方式
codex: command not found	未安装 CLI	npm install -g @openai/codex
401 Unauthorized	未登录 / 无认证	codex login --device-auth
server_error	OpenAI 服务端异常	重试 / 拆任务

真正把这三类问题分开后，Codex 的接入就很顺了。

---

参考

• Codex CLI: codex --help
• 登录帮助: codex login --help
• OpenAI 设备授权地址: https://auth.openai.com/codex/device

---

实践日期： 2026-03-10
Codex CLI 版本： 0.113.0