Codex CLI 配置指南

OpenAI 推出的命令行 AI 编程助手，基于 GPT 模型，默认沙箱安全运行

难度：●●○中等参考时长：约 10-15min支持：windows · macos · linux

🌐 本指南内容三端通用

按照以下步骤在你的 Windows 系统上安装 Codex CLI。

前置条件：需要 Node.js 22+（推荐）或 18+。Codex CLI 基于 Rust 重写（开源于 github.com/openai/codex ，Apache-2.0 协议），已替代旧的 TypeScript 版本。认证方式有两种：ChatGPT 订阅登录（Plus / Pro / Team / Enterprise / Edu）或 API Key。

网络要求：Codex 需要访问 OpenAI 服务器进行 AI 推理。OpenAI 相关域名（api.openai.com、platform.openai.com）在国内无法直连，需开启科学上网。如无法满足网络条件，可搜索 "OpenAI API 中转" 使用国内中转服务（参见配置指南）。安装步骤本身（npm 下载）在国内可以完成，但使用 Codex 进行对话时需要上述网络条件。

1你要装的是哪一个？先搞清楚

Codex CLI 没有桌面版。OpenAI 的 Codex 只有命令行版本（CLI），所有操作都在终端里完成。它和 ChatGPT 网页版/桌面版是两回事——ChatGPT 桌面版是聊天应用，Codex CLI 是编程工具。本指南只讲 Codex CLI 的安装。

产品	是什么	界面	能写代码吗
Codex CLI（本指南）	OpenAI 的命令行编程工具	终端	✅ 直接读写项目文件
ChatGPT 网页版	OpenAI 的 AI 聊天产品	浏览器	只能给代码建议，不会操作你的文件
ChatGPT 桌面版	ChatGPT 的桌面客户端	桌面应用	和网页版一样，不能操作文件

Codex CLI 的核心特点：

沙箱安全：默认在隔离环境中运行，不能修改系统文件（这是安全设计，不是 Bug）
ChatGPT 订阅直接可用：已有 ChatGPT Plus ($20/月) / Pro ($200/月) 等订阅无需额外付费
开源：代码托管在 GitHub（github.com/openai/codex），Apache-2.0 协议
适用人群：ChatGPT 订阅用户、需要沙箱安全保障的开发者

💡 对比 Claude Code：Codex 的沙箱更安全但不能直接在编辑器里改文件（AI 重新生成而非原地编辑），Claude Code 更灵活但需要手动管理权限。如果你更喜欢图形界面而非命令行，可以考虑 Cursor 或 Windsurf。如果不需要沙箱，Claude Code 的功能更全面。

2安装前置依赖

Codex CLI 的核心依赖只有一个：Node.js。以下是各平台的安装方式：

2.1 安装 WSL2（Windows 用户必须先看）

什么是 WSL2：WSL2（Windows Subsystem for Linux）是 Windows 自带的 Linux 子系统，让你在 Windows 里运行一个完整的 Linux 环境。Codex CLI 在 Windows 原生支持仍为实验性，建议通过 WSL2 使用，否则可能遇到兼容性问题。

安装步骤：

以管理员身份打开 PowerShell：右键开始菜单 → Windows PowerShell（管理员）
运行安装命令：

powershell

# 安装 WSL2（会自动安装 Ubuntu）

wsl --install

这个命令会自动启用虚拟机平台、安装 WSL2 内核、并默认安装 Ubuntu 发行版。整个过程约 5–10 分钟。

重启电脑：安装完成后必须重启，WSL2 才能生效
首次启动 Ubuntu：重启后在开始菜单搜索 "Ubuntu"，打开后会提示创建用户名和密码（这个密码是 Linux 的密码，和 Windows 无关）
WSL2 环境准备完毕。之后的 Node.js 安装和 Codex 安装都在 Ubuntu 终端 中操作

💡 如不熟悉 WSL2，可到 B站搜索 "WSL2 安装教程" 查看视频演示。如想了解 WSL2 原理，搜索 "WSL2 是什么"。

这一步最容易出问题：如果 wsl --install 报错 "请启用虚拟机平台" 或 "WSL2 内核未安装"，说明你的 Windows 版本过旧或缺少组件。解决方案：① 确保 Windows 10 版本 ≥ 2004 或 Windows 11；② 在"启用或关闭 Windows 功能"中勾选 "Hyper-V" 和 "虚拟机平台"；③ 如仍不行，到 B站搜索 "WSL2 安装失败" 查看详细的排查视频。这一步如果没搞好，后面的全部做不了，务必确认 WSL2 正常后再继续。

2.2 在 WSL2 中安装 Node.js

打开 Ubuntu 终端，执行以下命令：

bash

# 更新包列表

sudo apt update

# 安装 Node.js 22.x（推荐版本）

# 方法一：使用 NodeSource 官方源

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

sudo apt install -y nodejs

# 方法二：使用 nvm（版本管理更灵活，推荐）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 关闭终端重新打开，然后：

nvm install 22

nvm use 22

⚠️ raw.githubusercontent.com 在国内可能间歇性无法访问。如遇超时，可到 B站搜索 "nvm 国内安装" 或 "Node.js 国内镜像" 使用国内源。

2.3 验证 Node.js 安装

bash

# 检查 Node.js 版本（应显示 v22.x.x 或更高）

node --version

# 检查 npm 版本

npm --version

如果显示版本号，说明 Node.js 安装成功 ✅。

如果提示 "command not found"：① 关闭终端重新打开再试；② 确认你是在 Ubuntu 终端（WSL2）中操作，不是在 PowerShell 或 CMD 中。仍不行的话，到 B站搜索 "WSL2 安装 Node.js" 查看视频教程。

3安装 Codex CLI

Codex CLI 通过 npm 安装（npm 是 Node.js 自带的包管理器，无需额外安装）：

国内用户注意：npm 官方源（registry.npmjs.org）在国内访问较慢。建议先切换到国内镜像源，下载速度会快很多：

bash

# 先切换 npm 镜像源（国内用户推荐）

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

# 全局安装 Codex CLI

npm install -g @openai/codex

# 如需固定版本（CI/CD 环境）

npm install -g @openai/codex@0.131.0

也可使用 yarn / pnpm：yarn global add @openai/codex 或 pnpm add -g @openai/codex。

如果 npm 安装报错：① 最常见的错误是 EACCES（权限不足）——WSL2 中通常是 npm 全局目录权限问题，可到 B站搜索 "npm EACCES 权限修复" 解决；② 如提示 ETIMEDOUT 或 ESOCKETTIMEDOUT（网络超时），npm 镜像源可能没切成功，重新执行 npm config set registry https://registry.npmmirror.com 再试；③ 如提示 node version 相关错误，检查 node 版本是否 ≥ 18。

4选择认证方式

Codex CLI 提供两种认证方式，任选其一：

方式一：ChatGPT 订阅登录（推荐）

适用于 ChatGPT Plus ($20/月)、Pro ($200/月)、Team、Enterprise、Edu 订阅用户。

在终端输入 codex 并回车
浏览器会自动弹出 OpenAI 登录页面
登录你的 ChatGPT 账号 → 授权 Codex CLI 访问
浏览器显示 "登录成功" 后回到终端，Codex 已就绪

网络要求：OpenAI 登录页面（auth.openai.com）在国内无法直连。浏览器弹窗时需要确保浏览器走了科学上网，否则会出现页面无法加载或登录超时。

如果浏览器没有自动弹出：① 终端会输出一个 URL（以 https://auth.openai.com/ 开头），手动复制到浏览器打开；② 如果浏览器打开了但是一直转圈，检查浏览器代理设置；③ 登录成功后浏览器显示的是 OpenAI 的确认页面，点"授权"即可。如果反复尝试都失败，到 B站搜索 "Codex CLI 登录失败" 查找详细排查步骤。

方式二：API Key

适用于有 OpenAI API Key 的用户（在 platform.openai.com/api-keys 创建，按使用量计费）。

bash

# Bash / Zsh（macOS / Linux / WSL2）：

# 用 read -rs 避免 API Key 记录到 shell 历史

read -rs OPENAI_API_KEY && export OPENAI_API_KEY

# 粘贴你的 API Key，按回车确认

# PowerShell（Windows 原生终端）：

# $env:OPENAI_API_KEY = "sk-你的密钥"

# ⚠️ 绝对不要把 API Key 直接写在 ~/.bashrc 或代码文件里！

国内用户：OpenAI API 需要国外信用卡和科学上网。可使用中转服务（提供兼容 OpenAI 协议的 API 端点），在配置文件 ~/.codex/config.toml 中将 openai_base_url 指向中转地址即可绕过网络限制。如不了解中转服务，可到 B站或其他网络平台搜索 "OpenAI API 中转" 了解具体方案。详见「配置指南」。

5验证安装

bash

# 检查版本号

codex --version

# 进入项目目录，启动 Codex

cd 你的项目目录

codex

看到版本号和欢迎界面即安装成功 ✅。

如果提示 command not found：关闭终端重新打开。确认 npm 全局安装路径在 PATH 环境变量中。运行 npm list -g --depth=0 检查是否已安装成功。 Windows 用户：确认所有操作都在 WSL2 的 Ubuntu 终端中进行，而非 PowerShell 或 CMD。

如果启动后反复显示 "Reconnecting"：这是国内用户最常见的问题，原因是网络无法稳定连接 OpenAI 服务器。① 先在 ~/.codex/config.toml 中添加 supports_websockets = false；② 如仍不行，需要使用中转服务（API 代理），将 openai_base_url 指向中转地址。详见「配置指南」中的网络优化章节；③ 如果对中转服务不熟悉，到 B站搜索 "Codex 国内中转" 或 "OpenAI API 中转" 了解具体方案。

6了解沙箱模式（重要）

Codex CLI 的沙箱是它的核心安全机制——AI 默认在隔离环境中运行，不能修改你的系统文件。三种模式：

模式	权限范围	适合场景
`read-only`	只能读文件，不能写任何东西	代码审查、分析项目
`workspace-write`	可修改项目目录内的文件	日常开发（推荐）
`danger-full-access`	全盘访问，无任何限制	⚠️ 不推荐，有误删风险

重要安全提醒：① 新手建议使用默认的 workspace-write 模式；② 绝对不要让 Codex 执行清理或删除文件夹的操作；③ 操作前用 Git 提交代码；④ danger-full-access 有全盘清空风险，除非你完全清楚后果，否则不要使用。沙箱模式在 ~/.codex/config.toml 中配置（详见「配置指南」）。

💡 如果上述步骤遇到问题，建议到 B站或其他网络平台搜索 "Codex CLI 安装教程"，视频教程通常有更直观的演示。

有疑问？来这里找答案

如果对本站内容有疑问，推荐到视频或其他知识性平台寻求解决方法，也可直接向 AI 提问获得参考性回答（注意分辨 AI 回答的正确性）

视频教程

B站搜索教程

视频演示 + 疑难解答