Codex 安装与代理 API 配置教程 2026：下载、鉴权和常见报错

更新日期：2026 年 8 月 3 日。 本文面向 Codex CLI，配置示例使用当前 Codex 支持的 Responses API。命令和配置项会随版本变化，操作前建议先更新 Codex。

OpenAI Codex CLI 可以在终端中读取代码、修改文件、运行命令和测试。安装本身很简单，真正容易出错的是“代理”配置：有人需要的是让 Codex 通过本机网络代理访问 OpenAI，也有人需要把请求发送到第三方兼容 API。这是两件不同的事。

需求	应该配置什么	API 地址是否改变
官方 API 无法直连，需要本机代理软件转发流量	HTTP_PROXY、HTTPS_PROXY 等环境变量	不变
使用第三方 OpenAI 兼容 API 或企业网关	~/.codex/config.toml 中的自定义 model_provider	改为服务商地址

本文从安装开始，把两种方案分别讲清楚。想继续学习日常命令和项目实战，也可以阅读站内的 Codex CLI 终端教程。

一、安装前准备

开始前确认以下条件：

• macOS 或 Linux 可以直接安装；Windows 建议使用 WSL2。
• 使用 npm 安装时，需要先安装 Node.js 当前 LTS 版本和 npm。
• 使用官方服务时，需要 ChatGPT 账号或 OpenAI API Key。
• 使用第三方代理 API 时，需要服务商提供的 API Key、API 基础地址和模型名称。

先检查本机环境：

node -v
npm -v

如果还没有 Node.js，可从 Node.js 官网 下载 LTS 版本。macOS 用户也可以使用 Homebrew 安装 Codex，不必单独配置 npm。

二、下载并安装 Codex CLI

方法一：npm 安装，适合 macOS、Linux 和 WSL

npm install -g @openai/codex

安装后验证：

codex --version

如果终端提示 codex: command not found，先关闭并重新打开终端，再检查 npm 的全局可执行目录是否已经加入 PATH：

npm prefix -g

方法二：Homebrew 安装，适合 macOS

brew install --cask codex
codex --version

不需要额外执行 brew tap。以后可以使用下面的命令更新：

brew upgrade --cask codex

方法三：从 GitHub Releases 下载

不想使用包管理器时，可以打开 OpenAI Codex Releases，下载与操作系统和 CPU 架构匹配的发行包。

下载时重点确认两项：

1. 操作系统：macOS 或 Linux。
2. 架构：Apple Silicon/ARM64、Intel/x86_64 等。

解压后将可执行文件重命名为 codex，添加执行权限，并放入已经加入 PATH 的目录。发行包的文件名可能随版本变化，建议以 Releases 页面说明为准。

Windows 推荐使用 WSL2

以管理员身份打开 PowerShell：

wsl --install

重启并进入 Ubuntu 后，在 WSL 内安装 Node.js LTS，再执行：

npm install -g @openai/codex
codex --version

项目最好也放在 WSL 的 Linux 文件系统中，例如 ~/projects/my-app，这样文件权限、Git 和命令行工具的兼容性通常更好。

三、更新和检查 Codex

Codex 自带更新与诊断命令：

codex update
codex doctor --summary

如果当前安装方式不支持 codex update 自动升级，可重新执行对应包管理器的安装命令：

# npm
npm install -g @openai/codex@latest

# Homebrew
brew upgrade --cask codex

codex doctor 会检查安装、配置、鉴权、网络和运行环境。配置代理 API 后，优先运行它，比直接猜测报错原因更有效。

四、使用官方账号或官方 API

方案一：登录 ChatGPT 账号

codex login

按照终端提示在浏览器中完成登录。登录状态可以这样检查：

codex login status

方案二：使用 OpenAI API Key

先在当前终端设置环境变量：

export OPENAI_API_KEY="你的_OpenAI_API_Key"

再通过标准输入登录，避免把密钥直接写进命令历史：

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

ChatGPT 订阅和 OpenAI API 计费是两套体系。拥有 ChatGPT 订阅并不等于拥有 API 余额；使用哪种鉴权方式，应根据自己的账号和计费方式选择。

完成后进入一个代码项目并启动：

cd /path/to/your-project
codex

五、配置本机网络代理

这一方案适合继续使用 OpenAI 官方账号或官方 API，只让 Codex 的网络流量经过本机代理。

macOS、Linux 和 WSL

假设代理软件提供的 HTTP 代理地址是 http://127.0.0.1:7890：

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

部分程序也读取小写变量，可以同时设置：

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"

这些设置只在当前终端窗口生效。确认可用后，再按所用 Shell 写入 ~/.zshrc 或 ~/.bashrc。

Windows PowerShell

如果使用 Windows 原生终端：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

如果 Codex 安装在 WSL 中，应在 WSL 终端设置 Linux 环境变量。注意：WSL 中的 127.0.0.1 能否访问 Windows 代理端口，取决于 WSL 网络模式和代理软件是否允许局域网连接。

验证网络代理

codex doctor --summary

如果仍然连接失败，依次检查：

1. 代理端口是否与代理软件显示的一致。
2. 代理协议是否为 HTTP，而不是误填 SOCKS 端口。
3. 防火墙、公司网络或 WSL 是否阻止本地端口。
4. 终端是否继承了刚设置的环境变量。

可以用下面的命令确认变量，但不要输出 API Key：

env | grep -i proxy

六、配置第三方代理 API

这一方案适合 OpenAI 兼容中转服务、公司统一 AI 网关或自建代理。Codex 的用户配置文件默认位于：

~/.codex/config.toml

如果文件不存在，可以手动创建。下面是一个完整模板：

# 使用代理服务实际支持的模型 ID，不要照抄示例名称
model = "服务商提供的模型ID"
model_provider = "api_proxy"

[model_providers.api_proxy]
name = "My API Proxy"
base_url = "https://api.example.com/v1"
env_key = "CODEX_PROXY_API_KEY"
wire_api = "responses"

逐项说明：

配置项	作用	注意事项
model	实际请求的模型 ID	必须使用服务商明确提供的名称
model_provider	选择下面定义的提供商	必须与 [model_providers.api_proxy] 后缀一致
base_url	代理 API 基础地址	是否包含 /v1 以服务商文档为准
env_key	保存密钥的环境变量名称	这里填变量名，不填真实 Key
wire_api	Codex 使用的请求协议	当前应设置为 responses

然后在终端中设置密钥：

export CODEX_PROXY_API_KEY="你的代理平台_API_Key"

Windows PowerShell 对应写法：

$env:CODEX_PROXY_API_KEY = "你的代理平台_API_Key"

配置后先严格检查字段名：

codex --strict-config doctor --summary

再执行最小测试：

codex exec "只回复 OK"

为什么必须是 Responses API

新版本 Codex 的自定义提供商使用 wire_api = "responses"。仅仅声称“兼容 OpenAI API”还不够：有些代理只实现了 /v1/chat/completions，却没有实现 Responses API 或 Codex 所需的流式事件、工具调用能力，这类服务不能直接用于当前 Codex。

选择服务商前应明确确认：

• 是否支持 Responses API，而不只是 Chat Completions API。
• 是否支持 Codex 使用的模型和工具调用。
• base_url 是否需要包含 /v1。
• 是否支持流式响应，是否有超时限制。
• 模型 ID 是官方名称，还是平台自定义别名。

不要把 wire_api 改成 chat。当前 Codex 已不再支持这种旧配置，通常会直接提示改用 responses。

七、同时使用网络代理和代理 API

两种代理可以同时存在：

export HTTPS_PROXY="http://127.0.0.1:7890"
export CODEX_PROXY_API_KEY="你的代理平台_API_Key"
codex

此时请求流程是：Codex 读取 config.toml 中的第三方 base_url，再通过 HTTPS_PROXY 指定的本机网络代理访问该地址。

只有在第三方 API 本身也无法直连时才需要这样配置。否则只配置自定义 model_provider 即可，减少排查链路。

八、常见报错与解决方法

1. codex: command not found

原因通常是安装失败，或 npm 全局可执行目录没有加入 PATH。

npm list -g @openai/codex
npm prefix -g

重新打开终端后再运行 codex --version。

2. 401 Unauthorized 或 Incorrect API key

检查 env_key 指向的环境变量是否存在：

test -n "$CODEX_PROXY_API_KEY" && echo "API Key 已设置" || echo "API Key 未设置"

还要确认 Key 属于当前 base_url 对应的平台。官方 OpenAI Key 和第三方平台 Key 通常不能混用。

3. 404 Not Found

常见原因是 base_url 多写或少写了 /v1，或者代理没有实现 /responses。不要反复试不同路径，应直接查看服务商的 Codex 或 Responses API 文档。

4. 提示 wire_api = "chat" is no longer supported

把提供商配置改为：

wire_api = "responses"

如果服务商只支持 Chat Completions，则需要服务商升级兼容能力，单改本地字段无法解决。

5. 模型不存在或无权限

把 model 改为服务商控制台中实际可用的模型 ID。模型名称相似并不代表接口别名相同。

6. 请求开始后长时间无响应

依次执行：

codex --version
codex doctor --summary

再检查代理服务是否支持流式 Responses、工具调用和足够长的请求超时。编码任务通常比普通聊天持续时间更长。

7. TOML 配置无法解析

常见问题包括使用中文引号、漏掉引号、表名拼错。用严格模式定位未知字段：

codex --strict-config doctor --summary

九、密钥与代码安全建议

Codex 能读取项目文件并执行命令，代理服务也可能接触发送给模型的代码内容。正式使用前至少完成以下检查：

1. 不要把真实 API Key 写入 config.toml、代码仓库或截图。
2. 为 Codex 单独创建 Key，并设置余额、速率或调用范围限制。
3. 确认代理服务的运营主体、隐私政策、日志保存周期和数据用途。
4. 不要向不可信代理发送商业源代码、客户数据、私钥和生产环境配置。
5. 首次在陌生项目中运行时，先检查 Codex 的沙箱和审批设置，不要为了省事关闭全部安全限制。
6. Key 泄露后立即在服务商控制台撤销并重新生成，不要只删除本地文件。

十、快速配置清单

如果你已经安装了 Codex，只需要代理 API，按下面五步操作：

1. 向服务商确认 Responses API、模型 ID 和 base_url。
2. 在 ~/.codex/config.toml 添加自定义 model_provider。
3. 设置 CODEX_PROXY_API_KEY 环境变量。
4. 运行 codex --strict-config doctor --summary。
5. 运行 codex exec "只回复 OK" 做最小验证，再进入真实项目。

官方参考

• Codex 官方文档
• Codex 配置基础
• Codex 配置参考
• OpenAI Codex GitHub 仓库
• Codex GitHub Releases

配置成功后，建议保留 codex doctor --summary 作为第一排查命令。只要先分清“网络代理”和“API 中转”，大多数安装与连接问题都能很快定位。