【AI 大模型】Codex CLI 基本用法 ① ( 安装 Codex CLI | 安装 Node.js 运行时环境 | 配置 npm 镜像与缓存 | 设置安装目录 | 设置 CODEX_HOME )

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

文章目录

• 前言
• 安装总结
• 一、Codex CLI 简介
• • 1、概念简介
  • 2、核心特点
  • 3、使用形态
  • 4、安装前置条件检查
• 二、安装 Node.js 运行时环境
• • 1、下载与解压
  • 2、写入环境变量
  • 3、作用原理
• 三、安装 Codex CLI
• • 1、配置 npm 镜像与缓存
  • 2、设置全局安装目录并安装
  • 3、加入 PATH 并验证
  • 4、作用原理
  • 5、备选方案 : GitHub Releases 二进制直装
• 四、设置 CODEX_HOME
• • 1、设置环境变量并初始化
  • 2、作用原理
• 五、安装验证与卸载方法
• • 1、安装验证
  • 2、完全卸载
• 六、注意事项与避坑指南
• 总结

前言

本文主要介绍 Codex CLI 本体的安装环节 , 给出详细的安装流程 ;

全程采用绿色安装思路 , 运行时 , 全局包 , 下载缓存 , 配置文件 , 会话历史 五类数据全部落在 D:\\001_Develop\\000_Codex , C 盘零残留 ;

大模型接入与 config.toml 配置在下一篇博客讲解 ;

目录规划 : 安装前先明确五类数据的落点 ;

• nodejs : Node.js 运行时环境 , Codex 的启动载体 ;
• npm-global : npm 全局包安装位置 , Codex CLI 本体在这里 ;
• npm-cache : npm 下载缓存 , 防止日积月累塞满 C 盘 ;
• .codex : Codex 配置 , 会话历史与日志 , 即 CODEX_HOME ;
• 目标结构 : 四个目录全部并列挂在 D:\\001_Develop\\000_Codex 目录中 , 卸载时删一个目录即可 ;

安装总结

Codex CLI 安装总结 : 将下面的代码复制到本地 , 将 " D:\\001_Develop\\000_Codex " 替换为 自己要安装 Codex 的目录 , 按照步骤操作即可 ;

# ============================================================
# Codex CLI 绿色安装全流程总结 ( 目标 : C 盘零残留 , 全部落 D 盘 )
# 目录规划 : D:\\001_Develop\\000_Codex\\ 下并列四个目录
# nodejs ( 运行时 ) | npm–global ( 全局包 ) | npm–cache ( 缓存 ) | .codex ( 配置/会话 )
# ============================================================

# ——————————————————————————————
# 1、安装 Node.js 运行时环境
# ——————————————————————————————
# 1.1 从 nodejs.org 官网下载 Windows 独立 zip 版 ( x64 ) ,
# 解压到 D:\\001_Develop\\000_Codex\\node–v24.21.0–win–x64
# 注意 : 若 zip 内带一层子目录 , 需把内容整体上提一层 ,
# 确保 node.exe 直接位于该目录根下
# 1.2 在该目录打开 Powershell , 将 Node 加入用户级 PATH :
$nodeHome = "D:\\001_Develop\\000_Codex\\node-v24.21.0-win-x64"
$oldPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$nodeHome;" + $oldPath, "User")

# 1.3 重开终端验证 :
node –v # 应输出 v24.21.0
npm –v # 应输出 11.19.0

# ——————————————————————————————
# 2、配置 npm 并安装 Codex CLI ( 顺序不能反 , prefix 必须先于 install )
# ——————————————————————————————
npm config set registry https://registry.npmmirror.com # 国内镜像加速
npm config set cache "D:\\001_Develop\\000_Codex\\npm-cache" # 缓存迁到 D 盘
npm config set prefix "D:\\001_Develop\\000_Codex\\npm-global" # 全局包位置指到 D 盘 ( 关键 )
npm install –g @openai/codex # 安装 Codex CLI

# 2.1 将 npm–global 加入用户级 PATH ( codex.cmd shim 在该目录根下 ) :
$oldPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "D:\\001_Develop\\000_Codex\\npm-global;" + $oldPath, "User")

# 2.2 重开终端验证 :
codex —version # 应输出 codex–cli 0.x

# 备选方案 ( npm 超时/内网受限 ) : 从 github.com/openai/codex Releases 下载
# codex–x86_64–pc–windows–msvc zip , 解压重命名为 codex.exe
# 放入 D:\\001_Develop\\000_Codex\\npm–global 即可 ( 自包含 , 不依赖 Node )

# ——————————————————————————————
# 3、设置 CODEX_HOME ( 配置/会话/日志整体重定向到 D 盘 )
# ——————————————————————————————
[Environment]::SetEnvironmentVariable("CODEX_HOME", "D:\\001_Develop\\000_Codex\\.codex", "User")
New–Item –ItemType Directory –Force "D:\\001_Develop\\000_Codex\\.codex"

# ——————————————————————————————
# 4、最终验证 ( 重开终端逐条执行 )
# ——————————————————————————————
node –v # Node 运行时就位
npm –v # npm 就位
codex —version # Codex 本体就位
echo $env:CODEX_HOME # 应输出 D:\\001_Develop\\000_Codex\\.codex
# 进入任意项目目录执行 codex , 首次启动自动初始化配置并进入交互界面

# ——————————————————————————————
# 5、完全卸载 ( 三步干净退出 , C 盘无残留 )
# ——————————————————————————————
# 5.1 删除 D:\\001_Develop\\000_Codex 整个目录
# 5.2 从用户级 PATH 移除 nodejs 与 npm–global 两项 , 删除 CODEX_HOME 环境变量
# 5.3 重开终端确认 node 与 codex 均不可识别

# ——————————————————————————————
# 避坑要点 :
# – PATH 改完必须重开终端才生效
# – prefix 必须在 npm install 之前设置 , 否则全局包装进 C 盘
# – zip 解压后确认 node.exe 位于 PATH 所指目录根下
# – 网络超时切 npmmirror 镜像或改用二进制直装
# – codex.exe 被杀软拦截时加入信任区/白名单
# ——————————————————————————————

一、Codex CLI 简介

1、概念简介

Codex CLI 是 OpenAI 开源的终端 AI 编程 Agent , 2025 年开源 ( 仓库 github.com/openai/codex , Apache 2.0 协议 ) , 用 Rust 编写 , 跑在命令行里 ;

可以把它理解为 " 住在你终端里的程序员同事 " : 用自然语言下任务 , Codex CLI 自己读代码、改文件、跑命令、看报错、再修正 , 直到任务完成 ;

Codex CLI 的 最大价值在于 不绑定 OpenAI 账号也能完整使用 , 任何支持 OpenAI 格式的 大模型纯 API Key 即可驱动 Agent 应用 执行任务 ;

2、核心特点

核心特点 :

• Agentic 工作流 : 不是 一问一答 的 补全工具 , 而是 多步自主执行 — 规划、编辑多文件、执行构建/测试、根据结果迭代 ;
• 本地沙箱 : 文件读写 和 命令执行 默认在 沙箱 内进行 , 配合 三档审批策略 ( 只读 / 自动 / 完全放开 ) 平衡 效率 与 安全 ;
• 原生二进制 : Rust 实现无运行时依赖 , 单文件分发 , Windows/macOS/Linux 全平台 , 启动快、资源占用低 ;
• 模型可替换 : 通过 config.toml 的 model_providers 可 对接任何 OpenAI 兼容大模型 , 如 : 火山方舟、智谱、DeepSeek 等 ;
• AGENTS.md : 用 项目 根目录 的 说明书 文件给 Agent 灌项目约定 , 多处环境的官方通用标准 ;

3、使用形态

使用形态 :

• 终端 CLI : 交互式 TUI 界面 , 自然语言对话式开发 ;
• IDE 扩展 : VS Code 扩展与 CLI 共享同一份配置 ;
• 非交互执行 : codex " 任务 " 用于 脚本 和 CI 自动化 ;

4、安装前置条件检查

开始前确认三点 : 条件不满足时先补齐再继续 ;

• 系统 : Windows 10 或 Windows 11 , 64 位 ;
• 磁盘 : D 盘剩余空间不少于 2 GB ;
• 网络 : 能访问 nodejs.org 与 npmmirror.com , 后者是本文使用的 npm 国内镜像 ;

二、安装 Node.js 运行时环境

1、下载与解压

操作步骤 : 选则下载 zip 而不是 msi ;

• 第一步 : 访问 nodejs 官网 https://nodejs.org/zh-cn , 在下载页 https://nodejs.org/zh-cn/download 选择 " Windows 独立文件 ( .zip ) " 的 x64 版本 ;

• 第二步 : 将 zip 解压到 D:\\001_Develop\\000_Codex\\nodejs ;

• 第三步 : 检查解压结果 , 确认 node.exe 直接位于 nodejs 根目录下面 " D:\\001_Develop\\000_Codex\\node-v24.21.0-win-x64 " ; 部分 zip 内部带一层 node-v22.x-win-x64 子目录 , 需要把子目录内容整体上提一层 , 否则后续 PATH 会指向空目录 ;

2、写入环境变量

在 " D:\\001_Develop\\000_Codex\\node-v24.21.0-win-x64 " 目录 空白处 , 点击右键 , 在弹出的下拉菜单中选择 " 在此处打开 Powershell 窗口 " 选项 ,

在 Powershell 命令行中 , 执行下面三个命令 , 把 Node 运行时目录 " D:\\001_Develop\\000_Codex\\node-v24.21.0-win-x64 " 加入 用户级 PATH ;

# 将 Node 运行时目录写入用户级 PATH ( 永久生效 , 无需管理员权限 )
$nodeHome = "D:\\001_Develop\\000_Codex\\node-v24.21.0-win-x64"
$oldPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$nodeHome;" + $oldPath, "User")

在 " 设置 | 高级系统设置 | 高级 | 环境变量 | 用户变量 | Path " 下查看 " D:\\001_Develop\\000_Codex\\node-v24.21.0-win-x64 " 目录是否设置到其中 ;

验证 : 重开终端后执行以下命令 , 两条都有正常输出即通过 ;

node –v # 应输出 v24.21.0
npm –v # 应输出 11.19.0

3、作用原理

Node.js 是 Codex CLI 的运行载体 — npm 分发的 @openai/codex 包本质上是一个启动器 , 由 Node 解释执行后再拉起随包分发的 Rust 原生二进制 ;

选择 zip 版而不是 msi 安装器 , 是因为 msi 会写入注册表并向系统目录复制文件 , 而 zip 只做纯解压 , 卸载时删目录即干净退出 ;

PATH 环境变量是操作系统的可执行文件查找清单 , 终端按 PATH 从前到后逐个目录寻找 node.exe , 把目录写进去命令才能被识别 ;

写入用户级 PATH 只影响当前账号 , 不需要管理员权限 , 也不会污染其他用户的环境 ;

三、安装 Codex CLI

1、配置 npm 镜像与缓存

操作步骤 : 安装之前先把 npm 的三个行为参数改到 D 盘 ;

# 国内镜像加速 , 只改下载源 , 不改包内容
npm config set registry https://registry.npmmirror.com

# 下载缓存也迁到 D 盘 , 避免日积月累塞满 C 盘
npm config set cache "D:\\001_Develop\\000_Codex\\npm-cache"

2、设置全局安装目录并安装

操作步骤 : prefix 必须在安装之前设置 , 顺序不能反 ;

# 全局包安装位置指到 D 盘 ( 关键 , 必须先于 install 执行 )
npm config set prefix "D:\\001_Develop\\000_Codex\\npm-global"

# 安装 Codex CLI
npm install –g @openai/codex

3、加入 PATH 并验证

将 " D:\\001_Develop\\000_Codex\\npm-global " 目录加入到环境变量中 , 目的是为了在命令行中可以调用 " D:\\001_Develop\\000_Codex\\npm-global\\codex.cmd " 指令 ;

在 Powershell 中 执行如下命令 , npm 全局目录默认不在 PATH 中 , 需要手动加入 ;

# 把 npm-global 加入用户级 PATH ( shim 就放在该目录根下 )
$oldPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "D:\\001_Develop\\000_Codex\\npm-global;" + $oldPath, "User")

去 环境变量 里看一眼 ;

验证 : 重开终端后执行 , 输出版本号即安装成功 ;

codex —version # 应输出 codex-cli 0.x

4、作用原理

npm 有项目本地与全局两套目录体系 , -g 参数把包装进 prefix 指定的全局目录 , 同时在该目录根下生成可执行 shim ( codex.cmd 与 codex.ps1 ) , 终端敲 codex 时实际执行的就是这些 shim , 这也是必须把 npm-global 加入 PATH 的原因 ;

npm 默认 prefix 在 C 盘用户目录或 Node 安装目录下 , 不改就必然污染 C 盘 ;

@openai/codex 的主体是 Rust 编译的原生程序 , 包内通过 optionalDependencies 按平台分发对应架构的二进制 , npmmirror 镜像同步了这些二进制文件 , 大陆直连即可获得可接受的下载速度 ;

缓存目录 npm-cache 是 npm 的下载中转站 , 同样默认在 C 盘 , 迁移后重装包时不再反复写入 C 盘 ;

5、备选方案 : GitHub Releases 二进制直装

适用场景 : npm 反复超时或企业内网受限时使用 ;

• 第一步 : 访问 github.com/openai/codex 的 Releases 页面 , 下载 codex-x86_64-pc-windows-msvc 对应的 zip ;
• 第二步 : 解压得到 exe 文件 , 重命名为 codex.exe , 放入 D:\\001_Develop\\000_Codex\\npm-global ;
• 第三步 : 确认该目录已在 PATH 中 ( 上一步已配置 ) , 重开终端执行 codex –version 验证 ;

作用原理 : 该二进制是自包含的 Rust 原生程序 , 不依赖 Node.js 与 npm , 下载解压即可运行 ; 它绕过了整个 npm 工具链 , 是网络受限环境下最短路径的安装方式 ;

四、设置 CODEX_HOME

1、设置环境变量并初始化

在 Powershell 中 , 执行 两行命令完成重定向与预创建 ;

# 配置与会话目录整体重定向到 D 盘
[Environment]::SetEnvironmentVariable("CODEX_HOME", "D:\\001_Develop\\000_Codex\\.codex", "User")

# 预创建目录 ( 不创建也可以 , Codex 首次启动会自动建 )
New-Item –ItemType Directory –Force "D:\\001_Develop\\000_Codex\\.codex"

2、作用原理

Codex 默认把配置文件 , 会话历史 , 日志与登录凭据硬编码写到用户主目录下 , 即 C:\\Users\\用户名\\.codex ;

启动时它会优先解析 CODEX_HOME 环境变量 , 变量存在则整体替换默认值 , 此后所有读写都发生在新目录中 — 这是官方支持的唯一位置重定向手段 , 不需要符号链接 , 也不需要改动任何配置文件内容 ;

会话历史按登录方式分组存储 , 重定向后旧会话不会丢失 , 只是留在原位置 ;

把这一步放在最后验证 , 是因为只有 Codex 本体装好后 CODEX_HOME 才有意义 ;

五、安装验证与卸载方法

1、安装验证

验证清单 : 重开终端后逐条执行 ;

node –v # Node 运行时就位
npm –v # npm 就位
codex —version # Codex 本体就位
echo $env:CODEX_HOME # 应输出 D:\\001_Develop\\000_Codex\\.codex

首次启动 : 进入任意项目目录执行 codex , 首次启动会自动初始化 .codex 目录内的基础文件并进入交互界面 , 界面正常出现即整个安装流程完成 ;

2、完全卸载

卸载清单 : 三步干净退出 , C 盘无残留 ;

• 第一步 : 删除 D:\\001_Develop\\000_Codex 整个目录 ;
• 第二步 : 从用户级 PATH 中移除 nodejs 与 npm-global 两项 , 删除 CODEX_HOME 环境变量 ;
• 第三步 : 重开终端确认 node 与 codex 均已不可识别 ;

六、注意事项与避坑指南

总结

本文把 Codex CLI 的安装拆成四个关键动作 :

• zip 版 Node 解压入 D 盘并写入 PATH ,
• npm 三参数 ( registry , cache , prefix ) 提前改向再安装 ,
• npm-global 加入 PATH 让 shim 可被识别 ,
• CODEX_HOME 环境变量把配置与会话整体迁往 D 盘 ;

理解了 shim , prefix , PATH 查找与环境变量优先级这四个机制 , 后续升级 ( npm update -g @openai/codex ) , 换目录 , 排查命令找不到等问题都能自行定位 ;

安装完成后即可进入模型接入配置环节 ;