从安装到上手：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 版本：

👉 nodejs.org

安装完成后验证：

bash 复制代码

node -v
npm -v

如果显示版本号说明安装成功。([Codexc][2])

2 安装 Codex CLI

使用 npm 全局安装：

bash 复制代码

npm install -g @openai/codex

安装完成后验证：

bash 复制代码

codex --version

如果能输出版本号说明安装成功。([Codexc][2])

三、Codex CLI 的两种登录方式

Codex CLI 有两种认证方式：

方式一：ChatGPT 账号登录

直接运行：

复制代码

codex

选择：

csharp 复制代码

Login with ChatGPT

需要 ChatGPT Plus / Team 等订阅。

方式二：API Key（最常见）

通过环境变量设置：

复制代码

OPENAI_API_KEY

四、Windows 环境变量配置（很多人会踩坑）

Windows 下设置 API Key 推荐使用 PowerShell。

设置 API Key

powershell 复制代码

setx OPENAI_API_KEY "sk-xxxx你的key"

注意：

必须加引号
必须重新打开终端

验证是否成功

PowerShell：

powershell 复制代码

echo $env:OPENAI_API_KEY

如果看到 key：

复制代码

sk-xxxxxxxx

说明配置成功。

常见错误

很多人会出现这种情况：

ruby 复制代码

echo $env:OPENAI_API_KEY
$env:OPENAI_API_KEY

这说明：

环境变量没有成功设置。

原因通常是：

在 cmd 里使用 PowerShell 语法
设置变量后没有重新打开终端

五、启动 Codex

进入你的项目目录：

bash 复制代码

cd your-project

然后运行：

复制代码

codex

你会看到类似界面：

vbnet 复制代码

What would you like me to do?
>

这说明 Codex 已经启动。

六、Codex 的基本使用方式

Codex CLI 有两种使用模式。

1 交互模式

直接启动：

复制代码

codex

然后输入任务：

复制代码

为这个项目生成单元测试

2 单次命令模式

可以直接在命令里写任务：

arduino 复制代码

codex "为UserService生成JUnit5测试"

七、真实开发中的使用场景

Codex CLI 在工程里最常见的用途有三个。

1 写单元测试

diff 复制代码

codex "
为 UserService 写 JUnit5 单元测试
要求：
- 使用 Mockito
- 覆盖异常分支
- 测试必须能运行
"

2 修复 Bug

arduino 复制代码

codex "
修复 MyBatis 查询 tenant_id 的问题
只允许修改 mapper.xml
"

3 批量代码重构

arduino 复制代码

codex "
将项目中所有 logger.info
替换为统一日志工具
"

八、CLI 为什么在 AI 工具里这么重要

很多 AI 编程工具都选择 CLI 形式，例如：

Codex CLI
Claude Code
Gemini CLI

原因很简单：

CLI 更适合自动化：

可以读文件
可以执行命令
可以接入 CI
可以批量处理

这也是为什么 AI Agent 工具几乎都走 CLI 路线。

九、使用 Codex 的三个安全原则

1 明确修改范围

一定要说明：

哪些目录能改
哪些不能改

例如：

bash 复制代码

只允许修改 test 目录

2 先看计划再执行

Codex 通常会提示：

bash 复制代码

I will:
1. create test file
2. run mvn test
Proceed?

确认后再执行。

3 随时用 Git 回滚

建议每次任务前：

css 复制代码

git checkout -b codex-work

如果出问题：

css 复制代码

git reset --hard

十、一个真实建议

不要把 Codex 当成：

"自动写代码的机器人"

更好的理解是：

一个高级实习生

你负责：

架构
设计
代码 Review

它负责：

写重复代码
改模板
批量重构
写测试

十一、一句话总结

Codex CLI 本质上是：

可以在你本地代码库工作的 AI Agent

工作模式也很简单：

复制代码

你负责方向
AI 负责体力