Codex CLI 安装指南

从零开始安装工具

难度：●●○中等参考时长：约 10-15min

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

前置条件

需要 Node.js 22+（推荐）或 18+。Codex CLI 基于 Rust 开发（开源于 github.com/openai/codex ），通过 npm 分发。认证方式有两种：ChatGPT 订阅登录（Plus / Pro / Team / Enterprise / Edu）或 API Key。

网络要求

Codex 需要访问 OpenAI 服务器进行 AI 推理。OpenAI 相关域名（api.openai.com、platform.openai.com）在国内无法直连，需开启科学上网。安装步骤本身（npm 下载）在国内可以完成。国内 API 接入方案（CC Switch / CCX / 中转站 / 手动配置）见配置指南 → §4 国内 API 接入。

1工具简介

Codex CLI 的核心特点：

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

与其他工具的横向对比见工具对比表。

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 终端 中操作

wsl --install 常见报错：如果提示 "请启用虚拟机平台" 或 "WSL2 内核未安装"，说明 Windows 版本过旧或缺少组件。这一步如果没搞好，后面全部做不了。

查看解决方案

确保 Windows 10 版本 ≥ 2004 或 Windows 11
在"启用或关闭 Windows 功能"中勾选 "Hyper-V" 和 "虚拟机平台"
参考微软 WSL 官方排查文档

2.2 在 WSL2 中安装 Node.js

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

bash

# 更新包列表

sudo apt update

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

# 先清理可能残留的旧版 libnode-dev（否则 dpkg 会冲突）

sudo apt purge -y libnode-dev nodejs nodejs-dev 2>/dev/null

# 方法一：使用 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 在国内可能间歇性无法访问。如遇超时，可通过代理访问，或改用方法一（NodeSource 官方源）安装 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 中。。

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 / 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/Pro/Team/Enterprise/Edu 订阅用户。

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

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

登录遇到问题？查看故障排查

方式二：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 或代码文件里！

国内用户 — API Key 中转

OpenAI API 需要国外信用卡和科学上网。国内可使用中转服务（提供兼容 OpenAI 协议的 API 端点），将 openai_base_url 指向中转地址即可绕过网络限制。四种接入方案详见配置指南 → §4 国内 API 接入。

5验证安装

bash

# 检查版本号

codex --version

# 进入项目目录，启动 Codex

cd 你的项目目录

codex

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

如遇报错，查看故障排查

6了解沙箱模式（重要）

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

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

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

时效性说明

⚠️ 以上信息可能已过时，请以各平台官方网站的最新公告和定价页面为准。以上安装步骤涉及的版本号（Node.js 22+、Codex CLI v0.131.0）和 npm 镜像源验证于 2026-06-17。工具版本迭代频繁，建议以各项目官方文档为准。

有疑问？来这里找答案

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

视频教程

B站搜索教程

视频演示 + 疑难解答

Codex CLI 安装指南

从零开始安装工具

难度：●●○中等参考时长：约 10-15min

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

前置条件

网络要求

1工具简介

Codex CLI 的核心特点：

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

与其他工具的横向对比见工具对比表。

2安装前置依赖

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

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

什么是 WSL2

安装步骤：

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

powershell

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

wsl --install

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

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

wsl --install 常见报错：如果提示 "请启用虚拟机平台" 或 "WSL2 内核未安装"，说明 Windows 版本过旧或缺少组件。这一步如果没搞好，后面全部做不了。

查看解决方案

确保 Windows 10 版本 ≥ 2004 或 Windows 11
在"启用或关闭 Windows 功能"中勾选 "Hyper-V" 和 "虚拟机平台"
参考微软 WSL 官方排查文档

2.2 在 WSL2 中安装 Node.js

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

bash

# 更新包列表

sudo apt update

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

# 先清理可能残留的旧版 libnode-dev（否则 dpkg 会冲突）

sudo apt purge -y libnode-dev nodejs nodejs-dev 2>/dev/null

# 方法一：使用 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 在国内可能间歇性无法访问。如遇超时，可通过代理访问，或改用方法一（NodeSource 官方源）安装 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 中。。

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 / pnpm：yarn global add @openai/codex 或 pnpm add -g @openai/codex。

如果 npm 安装报错

4选择认证方式

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

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

适用于 ChatGPT Plus/Pro/Team/Enterprise/Edu 订阅用户。

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

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

登录遇到问题？查看故障排查

方式二：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 或代码文件里！

国内用户 — API Key 中转

5验证安装

bash

# 检查版本号

codex --version

# 进入项目目录，启动 Codex

cd 你的项目目录

codex

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

如遇报错，查看故障排查

6了解沙箱模式（重要）

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

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

时效性说明

有疑问？来这里找答案

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

视频教程

B站搜索教程

视频演示 + 疑难解答