Codex CLI 安装教程 |全平台安装 + 认证配置 + 国内网络环境配置

                                             Codex CLI 安装教程

全平台安装 + 认证配置 + 国内网络环境配置

一、Codex 简介与核心概念

Codex CLI 是 OpenAI 推出的开源命令行 AI 编程代理（Agent），基于 Apache 2.0 协议，使用 Rust 语言构建。它在你的终端中本地运行，能够阅读代码、修改文件、执行 Shell 命令、自动修复 Bug，是一个端到端的自主软件工程助手。

与传统的代码补全工具（如 GitHub Copilot）不同，Codex 不仅能生成代码，还能理解整个项目结构、跨文件修改、执行终端命令、运行测试，甚至可以同时处理多项开发任务。你只需要用自然语言描述需求，Codex 就会自动分析项目、编写代码、运行命令、跑测试，你只需审核结果。

1.1 Codex 的核心能力

•项目级代码理解：自动扫描和分析整个代码库的结构与依赖关系

•自动修改与重构：根据自然语言指令跨文件修改代码

•Shell 命令执行：在终端中直接运行构建、测试、部署等命令

•Bug 自动修复：分析报错信息，定位问题并自动修复

•自动化任务编排：将复杂任务拆解为多个步骤自动执行

•本地运行保护隐私：代码不离开本地设备，仅 prompt 和必要上下文发送给模型

1.2 Codex 的使用形态

Codex 提供多种使用方式，适用于不同场景。本教程聚焦于 CLI 版本，因为它功能最完整、最适合处理整个项目。

1.3 Codex 与同类工具对比

二、环境准备

在安装 Codex 之前，需要确保系统满足最低要求并已安装必要的依赖。不同操作系统的准备步骤有所不同。

2.1 系统要求

注意：Windows 用户原生运行也可，但部分高级功能（如 full-auto 模式）在 WSL2 环境下体验更佳。如果仅使用基础功能，可直接在 Windows 终端（PowerShell 或 Git Bash）中运行。

2.2 macOS 环境准备

macOS 用户需要安装 Node.js。推荐使用 Homebrew 安装：

# 安装 Homebrew（如果尚未安装） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# 安装 Node.js brew install node@22# 验证安装 node --version# 应输出 v22.x.x npm --version# 应输出 10.x.x

也可以从 Node.js 官网下载安装包：访问 https://nodejs.org/，下载 LTS 版本的 .pkg 安装包并运行。

2.3 Linux 环境准备

以 Ubuntu / Debian 为例：

# 添加 NodeSource 仓库并安装 Node.js 22 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs# 验证安装 node --version npm --version

CentOS / RHEL 用户可使用：

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - sudo yum install -y nodejs

2.4 Windows 环境准备

Windows 用户有两种方式：原生安装或通过 WSL2 安装。

2.4.1 方式一：原生安装（推荐新手）

使用 winget 安装 Node.js：

# 以管理员身份打开 PowerShell winget install OpenJS.NodeJS.LTS# 验证安装 node --version npm --version

也可以从 Node.js 官网下载 .msi 安装包直接安装。安装完成后需要关闭并重新打开终端窗口使环境变量生效。

2.4.2 方式二：通过 WSL2 安装（适合高级用户）

如果你的项目依赖 Linux 工具链，或者需要 full-auto 模式的完整体验，建议使用 WSL2：

# 以管理员身份打开 PowerShell # 安装 WSL2 wsl --install# 设置默认版本为 WSL2 wsl --set-default-version 2# 安装 Ubuntu 发行版 wsl --install -d Ubuntu

安装完成后重启计算机，打开 Ubuntu 终端完成初始用户设置，然后按照上面 Linux 环境准备的步骤安装 Node.js。

三、安装 Codex CLI

Codex 支持多种安装方式。推荐根据你的操作系统选择最合适的方式。

3.1 方式一：官方一键安装脚本（推荐）

这是最简单的方式，官方脚本会自动检测系统架构并下载对应的二进制文件。

3.1.1 macOS / Linux 安装

curl -fsSL https://chatgpt.com/codex/install.sh | sh

脚本会自动下载 Codex 二进制文件并安装到系统路径。安装完成后可直接运行 codex 命令。

3.1.2 Windows 安装

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

如果默认下载源（releases.openai.com）无法访问，可以强制使用 GitHub Releases 作为下载源：

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false' irm https://chatgpt.com/codex/install.ps1 | iex

3.2 方式二：通过 npm 全局安装

如果你已经安装了 Node.js 和 npm，可以直接通过 npm 全局安装：

npm install -g @openai/codex

国内网络环境下，建议使用淘宝镜像源加速下载：

npm install -g @openai/codex --registry=https://registry.npmmirror.com

验证安装成功：

codex --version

看到版本号输出即表示安装成功。

3.3 方式三：通过 Homebrew 安装（仅 macOS）

brew install --cask codex

3.4 方式四：从 GitHub Releases 下载二进制文件

访问 https://github.com/openai/codex/releases/latest，根据你的平台下载对应的压缩包：

解压后将二进制文件重命名为 codex 并移动到 PATH 路径下：

# 解压 tar -xzf codex-aarch64-apple-darwin.tar.gz# 重命名 mv codex-aarch64-apple-darwin codex# 移动到 PATH 路径 sudo mv codex /usr/local/bin/# 赋予执行权限 chmod +x /usr/local/bin/codex# 验证 codex --version

3.5 Windows 用户环境变量配置（如需）

如果通过 npm 安装后运行 codex 提示找不到命令，需要将 npm 全局安装路径添加到系统 PATH：

# 查看 npm 全局安装路径 npm config get prefix# 将该路径添加到用户 PATH 环境变量 [Environment]::SetEnvironmentVariable("Path",$env:Path + ";D:\tools\codex","User" )

运行后关闭并重新打开终端窗口即可生效。也可以通过图形界面操作：按 Win + S 搜索环境变量 -> 编辑系统环境变量 -> 环境变量 -> 用户变量 Path -> 新建 -> 添加路径。

四、认证配置

Codex 支持两种认证方式：ChatGPT 账号登录和 API Key 认证。推荐使用 ChatGPT 账号登录，可利用你的 Plus / Pro / Business / Edu / Enterprise 订阅额度。

4.1 方式一：ChatGPT 账号登录（推荐）

这是最简单的方式，适合已有 ChatGPT 订阅的用户。运行 codex 后选择 Sign in with ChatGPT，浏览器会自动打开登录页面。

# 启动 Codex codex

首次运行时，你会看到如下交互界面：

Welcome to Codex CLIChoose how to sign in:> Sign in with ChatGPTSign in with API keyUse arrow keys to navigate, Enter to select.

选择 Sign in with ChatGPT 后，浏览器会自动打开 OpenAI 登录页面。完成登录授权后，终端会显示登录成功提示，之后就可以直接使用了。

ChatGPT Plus / Pro / Business / Edu / Enterprise 订阅用户可以直接使用 Codex，无需额外付费。免费用户可使用有限的额度。

4.2 方式二：API Key 认证

如果你没有 ChatGPT 订阅，或者需要按 token 计费使用，可以选择 API Key 方式。

4.2.1 获取 API Key

1.访问 OpenAI API 平台：https://platform.openai.com/api-keys

2.登录你的 OpenAI 账号（如果没有则注册）

3.点击 Create new secret key 创建新的 API Key

4.复制生成的 API Key（以 sk- 开头），妥善保存

4.2.2 配置 API Key

Codex 支持通过环境变量或配置文件设置 API Key。推荐使用环境变量方式。

方法 A：环境变量（推荐）

macOS / Linux：

# 写入 shell 配置文件（永久生效） echo 'export OPENAI_API_KEY="sk-你的API密钥"' >> ~/.zshrc# 立即生效 source ~/.zshrc# 验证 echo $OPENAI_API_KEY

如果你使用的是 Bash 而非 Zsh，将 ~/.zshrc 替换为 ~/.bashrc。

Windows（PowerShell）：

# 设置用户级环境变量（永久生效） [Environment]::SetEnvironmentVariable("OPENAI_API_KEY","sk-你的API密钥","User" )# 关闭并重新打开终端后生效 # 验证 echo $env:OPENAI_API_KEY

Windows（Git Bash）：

# 写入 .bashrc echo 'export OPENAI_API_KEY="sk-你的API密钥"' >> ~/.bashrc source ~/.bashrc

方法 B：auth.json 文件

Codex 的认证信息存储在 ~/.codex/auth.json 文件中（Windows 为 %USERPROFILE%\.codex\auth.json）。你也可以手动创建此文件：

{"api_key": "sk-你的API密钥" }

安全提醒：切勿将 API Key 提交到版本控制系统。建议在 .gitignore 中添加 .codex/ 目录。API Key 是敏感凭据，应像保护密码一样保护它。

五、国内网络环境配置

对于国内开发者，使用 Codex 主要面临两个网络问题：npm 安装慢和 OpenAI API 访问受限。本章提供完整的国内网络解决方案。

5.1 npm 镜像源配置

国内使用 npm 安装包时速度可能很慢，建议配置淘宝镜像源。

5.1.1 临时使用镜像源安装

npm install -g @openai/codex --registry=https://registry.npmmirror.com

5.1.2 永久切换镜像源

# 设置淘宝镜像源为默认 npm config set registry https://registry.npmmirror.com# 验证当前镜像源 npm config get registry # 应输出: https://registry.npmmirror.com/# 如需切回官方源 npm config set registry https://registry.npmjs.org/

5.2 官方安装脚本国内加速

官方一键安装脚本默认从 releases.openai.com 下载，国内可能无法访问。可以强制使用 GitHub Releases 作为下载源：

macOS / Linux：

curl -fsSL https://chatgpt.com/codex/install.sh \| CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

Windows：

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false' irm https://chatgpt.com/codex/install.ps1 | iex

5.3 API 中转 / 代理配置

如果无法直接访问 OpenAI API，可以通过自定义 base_url 指向兼容 OpenAI API 格式的中转服务。Codex 的配置文件位于 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml）。

5.3.1 创建配置文件

# 创建 .codex 目录和配置文件 mkdir -p ~/.codex touch ~/.codex/config.toml

5.3.2 方式一：修改 base_url（最简单）

如果你的中转服务兼容 OpenAI API 格式，只需修改 base_url 即可：

# ~/.codex/config.toml# 指定使用的模型 model = "gpt-4o"# 修改 API 基础地址为中转服务 openai_base_url = "https://你的中转地址/v1"

API Key 仍然通过环境变量 OPENAI_API_KEY 传入，或写入 auth.json。

5.3.3 方式二：自定义 Provider（推荐，更灵活）

如果需要切换不同模型或使用多个 API 服务商，可以定义自定义 Provider：

# ~/.codex/config.toml# 默认使用的模型 model = "gpt-4o"# 默认 Provider model_provider = "myproxy"# 自定义 Provider 配置 [model_providers.myproxy] name = "My API Proxy" base_url = "https://你的中转地址/v1" env_key = "MY_PROXY_API_KEY" wire_api = "responses"

然后设置对应的环境变量：

# macOS / Linux echo 'export MY_PROXY_API_KEY="sk-你的中转API密钥"' >> ~/.zshrc source ~/.zshrc# Windows PowerShell [Environment]::SetEnvironmentVariable("MY_PROXY_API_KEY","sk-你的中转API密钥","User" )

注意：Provider 名称不能使用 openai、ollama、lmstudio 这三个保留名。wire_api 建议设为 responses 以兼容 Codex 的 Responses API 格式。

5.3.4 方式三：使用系统代理

如果你已经有可用的 HTTP/HTTPS 代理，可以直接设置代理环境变量：

# macOS / Linux export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890# Windows PowerShell $env:HTTP_PROXY="http://127.0.0.1:7890" $env:HTTPS_PROXY="http://127.0.0.1:7890"

将 7890 替换为你的代理端口。设置后运行 codex 即可通过代理访问 OpenAI API。

5.3.5 接入国产模型（扩展）

Codex 也支持接入兼容 OpenAI API 格式的国产模型。以 Kimi K3（月之暗面）为例：

# ~/.codex/config.tomlmodel = "kimi-k3" model_provider = "kimi"[model_providers.kimi] name = "Kimi K3 (Moonshot AI)" base_url = "https://api.moonshot.cn/v1" env_key = "MOONSHOT_API_KEY" wire_api = "responses"

# 设置环境变量 export MOONSHOT_API_KEY="你的Kimi API密钥"

其他兼容 OpenAI API 的国产模型（如 DeepSeek、通义千问等）也可以按相同方式配置，只需修改 base_url 和 env_key。

六、安装常见问题排查（FAQ）

6.1 安装问题

Q: 运行 codex 提示 command not found

原因：Codex 未添加到系统 PATH 中。解决方案：

1.确认安装方式：如果通过 npm 安装，检查 npm 全局路径是否在 PATH 中

2.查看 npm 全局路径：npm config get prefix

3.将该路径添加到系统 PATH 环境变量

4.关闭并重新打开终端窗口

Q: npm install 报错或速度很慢

原因：默认 npm 源在国内访问慢。解决方案：使用淘宝镜像源：

npm install -g @openai/codex --registry=https://registry.npmmirror.com

Q: Windows 下 PowerShell 执行策略报错

原因：PowerShell 默认执行策略限制脚本运行。解决方案：修改执行策略：

# 以管理员身份运行 PowerShell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Q: 官方安装脚本下载失败

原因：默认下载源 releases.openai.com 无法访问。解决方案：强制使用 GitHub Releases：

# macOS / Linux curl -fsSL https://chatgpt.com/codex/install.sh \| CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

6.2 认证问题

Q: ChatGPT 登录后仍然提示需要认证

原因：登录凭证可能未正确保存。解决方案：

1.检查 ~/.codex/auth.json 文件是否存在且内容正确

2.尝试删除 ~/.codex/auth.json 后重新运行 codex 登录

3.确保浏览器登录的是正确的 OpenAI 账号

Q: API Key 认证报错 401 Unauthorized

原因：API Key 无效或环境变量未生效。解决方案：

1.检查 API Key 是否以 sk- 开头且完整复制

2.验证环境变量：echo $OPENAI_API_KEY

3.确保环境变量已写入 shell 配置文件并 source 生效

4.在 OpenAI 平台确认 API Key 状态是否为 Active

6.3 网络问题

Q: 连接 OpenAI API 超时

原因：国内网络无法直接访问 OpenAI API。解决方案：

1.设置 HTTP 代理环境变量（见第五章 5.3.4 节）

2.或配置自定义 base_url 指向中转服务（见 5.3.2 节）

3.或接入国产兼容模型（见 5.3.5 节）

Q: 中转服务返回错误

原因：中转服务可能不完全兼容 Responses API。解决方案：

1.确认中转服务的 base_url 末尾包含 /v1

2.确认 wire_api 设置为 responses

3.确认 env_key 指向的环境变量已正确设置

4.联系中转服务提供商确认是否支持 Responses API 格式

七、参考资源

•Codex GitHub 仓库：https://github.com/openai/codex

•Codex 官方文档：https://developers.openai.com/codex

•Codex CLI 文档：https://developers.openai.com/codex/cli

•认证配置文档：https://developers.openai.com/codex/auth

•基础配置文档：https://developers.openai.com/codex/config-basic

•高级配置文档：https://developers.openai.com/codex/config-advanced

•完整配置参考：https://developers.openai.com/codex/config-reference

•最新 Release 下载：https://github.com/openai/codex/releases/latest

•ChatGPT 计划详情：https://help.openai.com/en/articles/11369540-codex-in-chatgpt

•Node.js 官网：https://nodejs.org/

往期回顾：

马斯克要用AI拍整部电影挑战诺兰，结果自家AI先投了反对票

Kimi K3开源了，2.8万亿参数免费用，三种方案实测对比

Kimi K3今天开源了 但你的显卡根本跑不动