Codex CLI 完全指南：环境检查、安装配置与常见错误排查

Codex CLI 是 OpenAI 推出的终端编程助手。安装之后，你可以在命令行里让 Codex 根据自然语言指令生成代码、修改文件、执行命令并解释结果。和 ChatGPT 网页版不同，Codex 直接运行在本机，能访问当前项目的文件结构，更适合“先看代码、再改代码、最后跑命令”的工作流。

这篇文章的完整路径是：先搞清楚 Codex 的请求链路，再完成 Node.js 环境检查，然后安装 CLI、登录、配置模型提供方、跑通最小任务，最后处理最常见的一批报错。文章里不会出现无法验证的模型版本和“限时领取额度”之类的说法。凡是涉及模型 ID、API 地址、额度状态的地方，都以官方文档和你的账户页面为准。

1. 先理解 Codex 在本地是怎么工作的

1.1 Codex 是什么，和 ChatGPT 网页版有什么区别

通俗地说，Codex 是一个跑在终端里的 AI 编程助手。它和 ChatGPT 网页版的底层模型能力可能同源，但使用方式完全不同。

ChatGPT 网页版是“对话式问答”，它看不到你本机的文件，回答代码也依赖你手动复制粘贴。Codex 则不同，它默认以当前目录为上下文，可以读取文件内容、创建文件、修改文件、执行命令，再把执行结果反馈给模型。也就是说，它不是一个“只会聊天”的工具，而是一个可以操作本地工程目录的命令行智能体。

在常见工程实践中，Codex 适合这样使用：

• 在某个 Git 仓库根目录运行它，让它理解项目结构。
• 让它实现一个功能、修复一个测试、解释一段日志。
• 让它读取报错信息后给出修改方案。
• 让它直接执行命令，并汇报执行结果。

安装 Codex 后，你会得到一个codex命令。这个命令可以进入交互式聊天界面，也可以使用exec模式执行单次任务。

1.2 一次完整的 Codex 请求会经过哪些环节

理解请求链路对排错非常重要。很多报错并不是 Codex 本身的问题，而是请求还没有到达模型提供方就已经失败了。

一次完整请求大致经过以下环节：

1. 用户在终端输入自然语言指令。
2. Codex 读取当前目录的上下文，可能包括文件内容、目录结构和系统提示。
3. Codex 把指令、上下文和配置一起发送给base_url指定的服务端。
4. 服务端校验 API Key、额度和模型 ID。
5. 模型返回文本、工具调用结果或错误信息。
6. Codex 在本地渲染输出，必要时执行命令并把结果追加进对话。

如果第 3 步的地址配置错、第 4 步的密钥无效、模型 ID 写错，就会出现连接失败、401、403 或模型不支持等报错。安装前先理解这条链路，后面排查时会快很多。

1.3 需要分清 Codex CLI 与 IDE 插件

Codex 相关产品线不少，容易混淆的是 CLI、桌面应用和 VS Code 插件。它们底层都依赖模型端点，但安装方式和配置位置不同。

这篇文章以最常用的 Codex CLI 为例。如果你后续还要使用 IDE 插件，建议先让 CLI 跑通，再把同一份配置思想迁移到插件设置里。

注意：Codex 的本体是客户端工具，真正回答问题的是你配置的模型提供方。客户端安装成功不等于请求一定能成功，关键看网络、密钥、模型 ID 三者是否对齐。

2. 安装前的环境检查：Node.js、npm 与目录权限

2.1 环境要求清单

Codex CLI 通过 npm 分发，这意味着你的机器必须能运行 Node.js。安装之前，先确认环境是否满足基础要求。

如果原始工程环境中存在多套 Node.js，建议先确认当前终端实际使用的版本，避免装到一半发现全局命令路径不对。

2.2 检查 Node.js 和 npm 版本

打开终端，依次执行：

node -v npm -v

正常情况下会输出类似下面的内容：

v20.11.1 10.2.4

如果node命令不存在，说明 Node.js 尚未安装。此时不要继续安装 Codex，先安装 Node.js。安装方式有很多，这里不做唯一推荐：可以下载官方网站的安装包，也可以使用系统自带的包管理器安装。

如果输出版本低于要求，建议升级 Node.js 后再继续。升级后要重新打开终端，确保当前会话加载的是新版本。

2.3 设置 npm 全局安装目录

npm 全局安装包会默认写入系统目录。在 Linux 和 macOS 上，如果当前用户没有写入权限，npm install 会报EACCES错误。

先检查 npm 全局目录：

npm config get prefix

如果这个路径是/usr或/usr/local这类系统目录，而你使用普通用户执行安装，建议改为用户级目录。常见做法是在用户目录下创建.npm-global：

mkdir -p ~/.npm-global npm config set prefix ~/.npm-global

然后把全局 bin 目录加入当前 shell 的 PATH。以 Bash 为例：

export PATH=~/.npm-global/bin:$PATH

如果希望每次打开终端都生效，可以把上面的export写到~/.bashrc、~/.zshrc或对应 shell 配置文件中。Windows PowerShell 用户通常不需要这一步，但要注意全局命令所在的 npm 目录是否在 PATH 中。

3. 安装 Codex CLI 并完成首次登录

3.1 使用 npm 安装 Codex

环境检查通过后，执行：

npm install -g @openai/codex

安装完成后，验证命令：

codex --version

如果输出一个版本号，说明安装成功。例如：

0.1.0

如果提示codex: command not found，大概率是全局 bin 目录不在 PATH 中。先执行npm config get prefix找到全局目录，再把bin子目录加入 PATH，然后重新打开终端。

3.2 登录与 API 密钥两种认证方式

Codex 和模型提供方通信时，需要验证身份。常见认证方式有两种：账号登录和 API 密钥。

账号登录通常执行：

codex login

如果当前版本没有这个命令，可以执行codex --help查看可用的认证子命令。登录成功后，Codex 会把凭据保存在本地配置目录中，后续请求会自动带上认证信息。

API 密钥方式则是通过环境变量传入。官方端点默认读取OPENAI_API_KEY：

export OPENAI_API_KEY="你的密钥"

注意，不要把真实密钥写到示例代码里。密钥应该来自你自己的账户控制台，并且不要提交到 Git 仓库。

对于第三方兼容端点，可以配置成读取其他环境变量。这个部分在第 4 节详细说明。

3.3 验证安装结果

登录或配置好密钥后，运行一个最简单的交互命令：

codex

进入交互界面后，输入一句“你好，请用一句话说明你现在可以帮我做什么”。如果模型正常返回，说明客户端、网络、认证和模型端点全部打通。

如果这一步直接报错，不要急着卸载。绝大多数问题出在网络连通性、模型 ID 或密钥上，核对第 4 节配置后再重试。

注意：不要在无法验证模型 ID 的情况下盲目修改配置。网上流传的很多“新模型版本号”可能并不存在，写进配置后只会得到 model is not supported 的报错。

4. 配置模型提供方：官方端点与第三方兼容端点

4.1 配置文件位置和基础结构

Codex CLI 的配置文件位于用户目录下的.codex目录中。典型路径是：

~/.codex/config.toml

如果文件不存在，可以手动创建。这个文件采用 TOML 格式，里面保存了模型 ID、模型提供方、Base URL 和环境变量读取规则。

最简配置可能长这样：

model = "gpt-5-codex" model_provider = "openai" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY"

配置中有三个关键字段：

• model：请求使用的模型 ID。
• model_provider：使用哪个模型提供方配置块。
• base_url：请求发往的 API 地址。

模型 ID 不要照抄。OpenAI 的模型列表会更新，登录后建议通过官方模型页面确认当前可用的模型 ID。示例中的gpt-5-codex只用于说明 Codex 需要明确指定模型 ID，并不代表它永远有效。

4.2 配置官方 OpenAI 端点

如果使用官方端点，可以这样配置：

model = "gpt-5-codex" model_provider = "openai" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY"

保存后，在终端 export 密钥：

export OPENAI_API_KEY="你的官方密钥"

然后运行：

codex "用 Python 写一个读取 CSV 文件并统计行数的脚本"

如果返回代码，说明官方端点配置成功。

4.3 配置第三方兼容端点（以 DeepSeek 为例）

很多第三方服务商提供与 OpenAI 兼容的 API 格式。只要你把base_url换成服务商提供的地址，并把model换成服务商模型 ID，Codex 就能复用同一套客户端逻辑。

以 DeepSeek 为例，配置如下：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY"

然后设置环境变量：

export DEEPSEEK_API_KEY="你的DeepSeek密钥"

这里有一个容易踩的坑：不同服务商对base_url是否包含/v1要求不同。有的服务商要求完整路径，有的要求不带路径。建议以服务商提供的接入文档为准，不要一刀切。

4.4 用表格看懂配置参数

如果你要接入多个模型提供方，可以用表格整理配置要点：

配置原则是：模型 ID 必须属于你所配置的服务商。不能用第三方服务商去请求 OpenAI 专属模型，也不会合法。

5. 用最小任务跑通 Codex 并验证结果

5.1 交互模式：直接对话

安装和配置完成后，进入测试目录：

mkdir -p ~/codex-test cd ~/codex-test codex

进入交互界面后，输入：

请创建一个 hello.txt 文件，内容为 Hello Codex。

正常情况下，Codex 会给出执行方案，并可能会询问是否允许创建文件。确认后，~/codex-test/hello.txt就会出现。

这一步验证的是 Codex 的文件操作能力，而不只是闲聊能力。如果文件创建成功，说明客户端上下文读取、命令执行链路都是通的。

5.2 执行模式：codex exec

如果不想进入交互界面，可以使用exec模式执行单次任务：

codex exec "解释一下当前目录下所有文件的用途"

exec模式适合脚本调用、CI 集成和批量任务。输出通常更简洁，不会像交互模式那样保留完整会话。

在脚本中使用时，建议加--json或类似参数查看结构化输出。具体支持的参数以codex exec --help的说明为准。

5.3 验证输出和退出码

运行结束后，检查三样内容：

1. 命令是否正常退出。
2. 预期文件是否生成。
3. 生成内容是否符合要求。

如果是多步骤任务，还要检查 Codex 是否执行了额外命令、是否修改了预期之外的文件。第一次使用不要直接让 Codex 在真实项目里自动执行命令，先在测试目录里观察它的行为。

5.4 学习环境与生产环境的使用差异

在个人学习环境里，直接把密钥 export 到终端即可。但在团队或生产环境，这套用法还不够。

生产环境建议把密钥注入和额度监控放在 Codex 之外，而不是依赖使用者自觉。

6. 常见错误排查：连接失败、模型不支持、认证失效

6.1 本地端点转发失败：local endpoint forward failed

这里说的“本地端点转发失败”，常见报错形如：

local endpoint forward failed while handling codex endpoint /responses

这个报错的意思通常是：Codex 把请求发送到了一个本地未监听的地址，或者请求头没有正确携带认证信息。它不是模型能力问题，而是请求链路问题。

先按顺序检查：

1. 检查base_url是否指向了一个正在运行的服务。
2. 如果是本地自定义端点，确认服务已经启动，并且监听在配置的端口上。
3. 检查端口是否拼写正确。
4. 检查环境变量是否已设置，名称是否与env_key一致。
5. 检查配置文件语法，有没有多余冒号或漏掉括号。

排查命令示例：

codex exec "hello"

如果报错里出现localhost:xxxx，可以直接用curl验证该地址是否能访问：

curl http://localhost:xxxx/v1/models

如果curl返回认证失败，说明地址没问题，问题在密钥；如果连接被拒绝，说明服务没有启动或端口写错。

6.2 模型不支持：model is not supported

报错示例：

the 'gpt-5.6-sol' model is not supported when using codex with a ...

这类错误很典型：模型 ID 写错、写成了不存在的版本，或者模型 ID 与当前模型提供方不匹配。

处理方式如下：

• 确认模型 ID 与服务商文档一致。
• 不要把网上流传的版本号直接写进配置。
• 检查model_provider是否指向了包含该模型的提供方。
• 如果切换了服务商，model也要同步切换。

需要明确一点：如果某个模型 ID 在你的服务商模型列表中根本不存在，无论怎么调参数都不会成功。正确做法是去模型提供方的官方文档或控制台确认当前可用列表。

6.3 401 和 403：认证失败或无权访问

401 Unauthorized通常意味着密钥缺失或格式错误。

403 Forbidden通常意味着密钥有效，但当前账号没有权限使用该模型。

排查步骤：

# 确认环境变量是否存在 echo $OPENAI_API_KEY # 有第三方密钥时同样确认 echo $DEEPSEEK_API_KEY

如果环境变量为空，说明当前 shell 没有加载密钥。重新 export 后再试。如果密钥有值但仍报 401，检查密钥前后是否有空格，或是否复制了完整密钥。

403的情况要检查：

• 当前账号是否开通了模型访问权限。
• 密钥是否绑定在正确的项目下。
• 服务商控制台是否显示额度耗尽或权限受限。

不要为了绕过权限限制去购买来路不明的密钥。额度不足就按服务商正规流程充值或申请额度。

6.4 常见错误排查速查表

7. 实际使用中的额度、安全与版本管理

7.1 额度管理：在控制台确认，不要轻信“免费额度”话术

网络信息里经常出现“领取某额度”“白拿多少美元”的表述。这些信息需要谨慎判断。真实可用的额度一定能在服务商控制台里查到，而不是某个第三方网页声称的。

使用 Codex 前，建议先建立额度检查习惯：

1. 登录服务商控制台，查看当前可用余额或额度。
2. 记录当前时间点的用量，方便后续对比。
3. 设置账单提醒或预算限制。
4. 不要把生产环境的密钥试来试去，避免意外消耗。

模型请求是按 token 计费的。同样一个任务，模型复杂度和上下文长度不同，费用会差很多。建议在测试阶段使用较小的上下文，不要一次把整个项目目录塞给模型。

7.2 密钥安全：环境变量优先，配置文件不写密钥

config.toml里可以配置env_key，但不建议直接写明文密钥。密钥一旦写入文件，可能被无意中提交到 Git，造成泄露。

推荐做法：

# 写入 gitignore echo ".env" >> .gitignore # 从 .env 读取 export OPENAI_API_KEY="你的密钥"

如果你必须在一个会话中使用多个密钥，建议在启动 Codex 的 shell 里明确 export 后再运行，而不是写进配置文件。

如果怀疑密钥已经泄露，立即到服务商控制台吊销并重新生成密钥，同时检查账单里是否有异常调用。

7.3 升级与卸载

Codex 仍在快速迭代，升级成本很低：

npm install -g @openai/codex@latest

升级后建议运行一次codex --version，并重新执行最小对话，确认配置没有被破坏。

如果不再需要，可以卸载：

npm uninstall -g @openai/codex

卸载后，用户目录下的~/.codex配置文件还会保留。如果想彻底删除，再手动移除这个目录即可。

7.4 下一步扩展方向

跑通基础安装后，可以继续尝试这些方向：

• 在 VS Code 中使用 Codex 插件，把终端能力带入编辑器。
• 使用exec模式把 Codex 接入本地脚本，实现批量代码审查或测试生成。
• 为不同的项目配置不同的模型提供方，按成本和效果切换。
• 在团队内部统一配置模板，把模型 ID、密钥来源和日志规范写到 README 中。

最后留一个最实用的建议：第一次使用时，先在一个临时目录里把最小任务跑通，再进入真实项目。Codex 能操作文件、执行命令，这意味着它的破坏力也很大。自动执行前，务必先看清楚它准备做什么。