从安装到上手：Codex CLI 实战指南（Windows + Node + AI Agent）
大家好，我是G探险者！
随着 AI 编程工具的兴起，越来越多开发者开始使用 OpenAI Codex CLI。
它是一种可以在终端运行的 AI 编程助手，可以读取项目代码、修改文件、执行命令，甚至帮你自动写测试和修 Bug。([Aiberm][1])
相比传统聊天式 AI，Codex CLI 更像一个 本地 AI Agent，可以直接参与工程开发流程。
本文记录一次完整的实践过程：
从安装 Codex CLI → 配置环境 → 解决常见坑 → 第一次使用。
一、什么是 Codex CLI
Codex CLI 是 OpenAI 推出的 命令行 AI 编程助手，主要特点：
- 在终端运行
- 能读取当前项目代码
- 可以修改文件
- 可以执行命令（如测试、构建）
- 支持自动化代码任务
例如你可以直接输入：
codex 然后说：
为这个 service 写单元测试 它就会：
- 阅读代码
- 生成 test
- 运行测试
- 修复失败
二、安装 Codex CLI
Codex CLI 依赖 Node.js，因此第一步需要安装 Node。
1 安装 Node.js
去官网下载 LTS 版本：
安装完成后验证：
node -v npm -v 如果显示版本号说明安装成功。([Codexc][2])
2 安装 Codex CLI
使用 npm 全局安装：
npm install -g @openai/codex 安装完成后验证：
codex --version 如果能输出版本号说明安装成功。([Codexc][2])
三、Codex CLI 的两种登录方式
Codex CLI 有两种认证方式：
方式一：ChatGPT 账号登录
直接运行：
codex 选择：
Login with ChatGPT 需要 ChatGPT Plus / Team 等订阅。
方式二：API Key（最常见）
通过环境变量设置：
OPENAI_API_KEY 四、Windows 环境变量配置（很多人会踩坑）
Windows 下设置 API Key 推荐使用 PowerShell。
设置 API Key
setx OPENAI_API_KEY "sk-xxxx你的key" 注意：
- 必须加引号
- 必须重新打开终端
验证是否成功
PowerShell：
echo $env:OPENAI_API_KEY 如果看到 key：
sk-xxxxxxxx 说明配置成功。
常见错误
很多人会出现这种情况：
echo $env:OPENAI_API_KEY $env:OPENAI_API_KEY 这说明：
环境变量没有成功设置。
原因通常是：
- 在 cmd 里使用 PowerShell 语法
- 设置变量后没有重新打开终端
五、启动 Codex
进入你的项目目录：
cd your-project 然后运行：
codex 你会看到类似界面：
What would you like me to do? > 这说明 Codex 已经启动。
六、Codex 的基本使用方式
Codex CLI 有两种使用模式。
1 交互模式
直接启动：
codex 然后输入任务：
为这个项目生成单元测试 2 单次命令模式
可以直接在命令里写任务：
codex "为UserService生成JUnit5测试" 七、真实开发中的使用场景
Codex CLI 在工程里最常见的用途有三个。
1 写单元测试
codex " 为 UserService 写 JUnit5 单元测试 要求： - 使用 Mockito - 覆盖异常分支 - 测试必须能运行 " 2 修复 Bug
codex " 修复 MyBatis 查询 tenant_id 的问题 只允许修改 mapper.xml " 3 批量代码重构
codex " 将项目中所有 logger.info 替换为统一日志工具 " 八、CLI 为什么在 AI 工具里这么重要
很多 AI 编程工具都选择 CLI 形式，例如：
- Codex CLI
- Claude Code
- Gemini CLI
原因很简单：
CLI 更适合自动化：
- 可以读文件
- 可以执行命令
- 可以接入 CI
- 可以批量处理
这也是为什么 AI Agent 工具几乎都走 CLI 路线。
九、使用 Codex 的三个安全原则
1 明确修改范围
一定要说明：
- 哪些目录能改
- 哪些不能改
例如：
只允许修改 test 目录 2 先看计划再执行
Codex 通常会提示：
I will: 1. create test file 2. run mvn test Proceed? 确认后再执行。
3 随时用 Git 回滚
建议每次任务前：
git checkout -b codex-work 如果出问题：
git reset --hard 十、一个真实建议
不要把 Codex 当成：
“自动写代码的机器人”
更好的理解是：
一个高级实习生
你负责：
- 架构
- 设计
- 代码 Review
它负责：
- 写重复代码
- 改模板
- 批量重构
- 写测试
十一、一句话总结
Codex CLI 本质上是：
可以在你本地代码库工作的 AI Agent
工作模式也很简单：
你负责方向 AI 负责体力
