Windows下Codex安装详细配置使用指南

Codex 是 OpenAI 推出的 AI 编程助手，集代码生成、解释、调试、重构于一体，支持 CLI（命令行）、IDE 插件等多种使用方式，尤其适合 Windows 开发者提升编码效率。本文基于 2026 年最新版本，手把手教你完成 Codex 在 Windows 系统下的安装、详细配置及日常使用，覆盖从前置准备到常见问题排查的全流程，新手也能轻松上手。

一、前置准备

在安装 Codex 前，需确保系统环境满足要求，提前安装必要依赖，否则会导致安装失败或功能异常。

1.1 系统要求

操作系统：Windows 10 或 Windows 11（64位，32位系统不支持）
内存：最低 4GB，推荐 8GB 及以上（保证运行流畅）
网络：稳定联网（用于下载依赖、验证安装及后续使用）
权限：管理员权限（安装过程中需修改系统环境变量）

1.2 必备依赖安装

Codex CLI 基于 Node.js 开发，必须先安装 Node.js 环境，推荐使用最新 LTS 版本，避免版本过低导致兼容性问题。

下载 Node.js：访问 Node.js 官网，下载 Windows 版本（.msi 格式，64位），建议选择 Node.js 22+ 版本（兼容最新 Codex 版本）。
安装 Node.js：双击安装包，勾选「Add to PATH」（关键步骤，自动配置环境变量），其他选项保持默认，点击「下一步」直至安装完成。
验证安装：以管理员身份打开 CMD 或 PowerShell，输入以下命令，若能正常输出版本号，说明 Node.js 安装成功。
bash 复制代码
```
 node -v # 输出 Node.js 版本，如 v22.2.0 
 npm -v # 输出 npm 版本，如 v10.7.0
```
若国内网络下载 Node.js 速度较慢，可使用淘宝镜像加速，安装完成后执行以下命令配置镜像：

bash 复制代码

npm config set registry https://registry.npmmirror.com

二、Codex 安装步骤

Codex 支持通过 npm 全局安装，确保已完成前置准备后，按以下步骤执行。

2.1 管理员身份启动终端

按下 Win + R，输入 cmd 或 powershell，右键选择「以管理员身份运行」，避免因权限不足导致安装失败。

2.2 全局安装 Codex

在终端中输入以下命令，执行 Codex 安装，国内用户可添加镜像加速（可选）：

bash 复制代码

npm install -g @openai/codex 

# 国内镜像加速安装
npm install -g @openai/codex --registry=https://registry.npmmirror.com

安装过程中，终端会显示下载进度，耐心等待即可，若出现警告信息，无需理会，继续等待安装完成。

2.3 验证安装成功

安装完成后，在终端中输入以下命令，若能正常输出 Codex 版本号，说明安装成功：

bash 复制代码

codex --version # 输出版本号，如 0.42.0 及以上

常见问题：若提示「command not found」，大概率是 Node.js 环境变量配置失败，重启终端后重新尝试，若仍失败，需手动配置环境变量（详见文末常见问题）。

三、Codex 详细配置

Codex 安装完成后，需进行 API 配置或账号授权，才能正常使用。目前支持两种授权方式：ChatGPT Plus 账号登录、国内中转平台 API Key 配置（推荐国内用户使用第二种）。

3.1 授权方式选择

方式一：ChatGPT Plus/Pro/Team 订阅账号（官方授权，无需手动配置 API Key）
方式二：国内中转平台 API Key（无 Plus 账号可用，简单易操作，部分平台提供免费额度）

3.2 方式一：ChatGPT Plus 账号授权

在终端中输入以下命令，启动 Codex 授权流程： codex login
执行命令后，会自动弹出浏览器，跳转至 ChatGPT 登录页面，输入你的 ChatGPT Plus 账号（邮箱+密码）。
登录成功后，点击「授权」按钮，系统会自动将授权 Token 保存至本地（路径：C:\Users\你的用户名\.codex\token），无需手动配置。
授权完成后，关闭浏览器，返回终端，提示「Login successful」即授权成功。

3.3 方式二（推荐）：国内中转平台 API Key 配置

若没有 ChatGPT Plus 账号，可通过国内中转平台获取 API Key，步骤如下（以 api.88api.chat 为例，其他平台操作类似）：

3.3.1 获取 API Key

访问https://api.aigc.bar/register?aff=9Fyu,注册并登录账号。
登录后，点击顶部「控制台」→「API令牌」，进入令牌管理页面。

点击「添加令牌」，填写相关信息：
1. 令牌分组：务必选择「codex专属」
2. 令牌名称：随意填写（如「Codex-Windows」）
3. 额度设置：建议设置为「无限额度」，其他选项保持默认。
点击「创建」，生成 API Key（格式：sk-xxxxxx），复制该密钥，后续会用到。

3.3.2 创建并配置配置文件

打开文件资源管理器，进入用户目录（路径：C:\Users\你的用户名），开启「显示隐藏的项目」（顶部「查看」选项卡勾选），找到 .codex 文件夹（若没有，手动创建）。

在 .codex 文件夹中，手动创建两个文件：auth.json 和 config.toml。
配置 auth.json 文件（存储 API Key）：用记事本或 VS Code 打开 auth.json，粘贴以下内容，将 sk-xxx 替换为你获取到的实际 API Key：
bash 复制代码
```
{ "OPENAI_API_KEY": "sk-xxx" // 替换为你的 API Key }
```

配置 config.toml 文件（配置模型和中转地址）：用记事本或 VS Code 打开 config.toml，粘贴以下内容（直接复制即可，无需修改，model_reasoning_effort 可根据需求调整）：

bash 复制代码

model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.aigc.bar/v1"
wire_api = "responses"
requires_openai_auth = true

保存两个文件，配置完成。

3.4 配置验证

配置完成后，重启终端（关键步骤，否则配置不生效），输入以下命令启动 Codex：

bash 复制代码

codex

若终端显示 Codex 交互式界面，无报错信息，说明配置成功，可以开始使用；若出现报错，检查 API Key 是否正确、配置文件格式是否有误。

四、Codex 常用使用方法

Codex 支持 CLI 交互式使用、IDE 插件使用两种方式。

4.1 CLI 交互式使用

通过终端启动 Codex 后，进入交互式界面，可直接输入指令，实现代码生成、调试、解释等功能，常用场景如下：

4.1.1 修复代码报错

若代码运行报错，可截图报错信息，通过以下命令让 Codex 修复：

bash 复制代码

codex -i error.png "修掉图中报错" # error.png 是报错截图路径

4.1.2 常用 CLI 命令速查

命令	作用	使用场景
codex	启动交互式终端 UI	日常开发，人机协作编码
codex "提示内容"	带初始提示启动 TUI	直接指定任务，省去输入步骤
codex exec "任务"	非交互模式执行任务，输出到 stdout	CI/CD 流水线、批量自动化
codex login status	查看当前认证状态	检查是否已登录/配置成功
codex --model "gpt-5-codex-high"	指定高推理强度模型	复杂代码生成、调试

五、常见问题排查

安装或使用过程中，若出现报错，可对照以下常见问题排查，快速解决问题。

5.1 问题1：安装时提示「权限不足」

解决方案：确保终端是以「管理员身份运行」，关闭其他可能占用权限的软件，重新执行安装命令；若仍失败，可添加 sudo 前缀（仅 PowerShell 支持）：

复制代码

sudo npm install -g @openai/codex

5.2 问题2：验证安装时提示「command not found」

原因：Node.js 环境变量配置失败，系统无法找到 Codex 可执行文件。

解决方案：

重启终端，重新尝试验证命令；
若仍失败，手动配置环境变量：
1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」；
2. 在「系统变量」中找到「Path」，点击「编辑」；
3. 添加 Node.js 安装路径（默认路径：C:\Program Files\nodejs）和 Codex 安装路径（默认路径：C:\Users\你的用户名\AppData\Roaming\npm）；
4. 保存后，重启终端，重新验证。

5.3 问题3：启动 Codex 时提示「No Active Subscription」

原因：API Key 配置错误，或中转平台未开通权限。

解决方案：

检查 auth.json 中的 API Key 是否正确，是否替换了 sk-xxx；
确认中转平台的令牌分组是否选择「codex专属」；
若仍报错，联系中转平台客服开通权限。

5.4 问题4：Codex 生成代码报错，无法运行

解决方案：

切换模型，使用高推理强度模型（codex --model "gpt-5-codex-high"）；
检查是否缺少相关依赖，根据报错信息安装对应依赖（如 pip install requests）。