从安装到上手:Codex CLI 实战指南(Windows + Node + AI Agent)

大家好，我是G探险者！

随着 AI 编程工具的兴起，越来越多开发者开始使用OpenAI Codex CLI。

它是一种可以在终端运行的 AI 编程助手，可以读取项目代码、修改文件、执行命令，甚至帮你自动写测试和修 Bug。()

相比传统聊天式 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

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

2 安装 Codex CLI

使用 npm 全局安装：

npm install -g @openai/codex

安装完成后验证：

codex --version

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

三、Codex CLI 的两种登录方式

Codex CLI 有两种认证方式：

方式一：ChatGPT 账号登录

直接运行：

codex

选择：

需要 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 负责体力