Knightdreams'Blog

Appearance

Codex CLI 入门指南：从安装、AGENTS.md 到 Plan 模式 ​

最近 AI 编程工具越来越多：

text
GitHub Copilot
Cursor
Claude Code
Codex
...

但 Codex 和传统的“AI 代码补全”有一个很明显的区别。

传统 AI 编程工具更像：

text
你写代码
   ↓
AI 帮你补几行

而 Codex 更接近：

text
你告诉它要做什么
        ↓
Codex 阅读整个项目
        ↓
分析代码结构
        ↓
制定修改方案
        ↓
修改多个文件
        ↓
执行命令
        ↓
运行测试
        ↓
检查修改结果

也就是说，它不是单纯的：

Code Completion

而更接近一个：

Coding Agent。

OpenAI 对 Codex 的定位也是用于编写、审查和交付代码的编程 Agent，并且现在可以在 ChatGPT、IDE、终端等多个环境中使用。(OpenAI)

本文主要介绍开发者最常使用的一种方式：

text
Codex CLI

也就是直接在终端里使用 Codex。

1. Codex 到底是什么？ ​

假设现在有这样一个 Java 项目：

text
xxx-server
├── xxx-api
├── xxx-business
├── xxx-common
├── xxx-framework
└── pom.xml

以前我们使用 ChatGPT 时，可能会这样：

text
复制代码
    ↓
粘贴给 ChatGPT
    ↓
问它哪里有问题
    ↓
复制修改后的代码
    ↓
手动改回项目

如果涉及十几个文件，这套流程会非常麻烦。

Codex CLI 的思路不同。

你直接进入项目：

bash
cd xxx-server

启动：

bash
codex

然后告诉它：

text
帮我分析用户登录流程，找出 token 刷新逻辑在哪里，
先不要修改代码。

Codex 可以自己读取：

text
Controller
Service
Mapper
Entity
Configuration
pom.xml
application.yml

然后沿着调用链分析。

如果你继续说：

text
现在帮我增加 refresh token 过期时间配置，
修改完成后执行相关测试。

它就可以直接在项目中修改文件。

因此更准确地说：

text
ChatGPT
≈ 你把代码拿给 AI

Codex CLI
≈ AI 进入你的代码仓库工作

2. Codex CLI 能做什么？ ​

一个比较完整的 Codex 工作流程可能是：

text
需求
 ↓
阅读项目
 ↓
搜索代码
 ↓
分析依赖
 ↓
制定方案
 ↓
修改代码
 ↓
执行 Maven / Gradle / npm
 ↓
运行测试
 ↓
查看 Git Diff
 ↓
继续修复

例如可以直接告诉它：

text
分析这个项目的支付模块。

或者：

text
找出所有调用 UserBalanceService.opsBalance 的地方，
解释每个调用场景。

甚至：

text
把这个接口从同步处理改成异步处理，
不要改变现有 API，
修改完成后运行相关单元测试。

对于复杂任务，Codex 的价值并不是：

帮你生成一段代码。

而是：

帮你完成一整个代码修改任务。

3. 安装 Codex CLI ​

安装之后可以先执行：

bash
codex

进入交互模式。

第一次使用时通常需要进行账户登录或相关授权。

Codex 目前可以与 ChatGPT 账户配合使用，不同 ChatGPT 套餐对应的 Codex 使用额度可能不同。(OpenAI Help Center)

4. 一定要在项目目录启动 Codex ​

这是新手非常容易忽略的一点。

假设你的项目位于：

text
~/IdeaProjects/xxx

最好：

bash
cd ~/IdeaProjects/xxx
codex

而不是直接在：

bash
~

运行：

bash
codex

为什么？

因为 Codex 的工作目录决定了：

text
它主要从哪里开始读取项目
它可以看到什么代码
它会在哪里寻找项目规则
它修改哪些文件

启动 Codex 后，可以使用：

text
/status

查看当前 Session 状态。

例如可能看到类似：

text
Model:           gpt-5.6-sol
Directory:       ~/IdeaProjects/xxx
Permissions:     Workspace
Agents.md:       AGENTS.md
Collaboration:   Default

这里最值得关注的是：

text
Model
Directory
Permissions
Agents.md
Collaboration mode

其中：

text
Directory

最好就是你的项目根目录。

5. 第一次进入项目，不要急着让 Codex 改代码 ​

很多人第一次使用 Coding Agent 时会这样：

text
帮我重构整个订单模块。

然后就开始让模型修改。

这通常不是一个好习惯。

更推荐先让 Codex：

text
阅读项目

例如：

text
阅读这个项目，分析整体技术栈和目录结构，
先不要修改任何文件。

或者：

text
分析这个 Spring Boot 项目。

重点说明：

1. 模块划分
2. Controller / Service / Mapper 结构
3. 数据库访问方式
4. Redis 使用方式
5. MQ 使用方式
6. 定时任务
7. 外部服务调用

先不要修改代码。

这样做有两个好处。

第一：

text
让 Codex 建立项目上下文

第二：

text
你可以检查 Codex 对项目的理解是否正确

如果连项目结构都理解错了，就不应该马上让它进行大范围修改。

6. Codex 最重要的文件之一：AGENTS.md ​

如果你长期使用 Codex，强烈建议了解：

text
AGENTS.md

它可以简单理解为：

给 Coding Agent 阅读的项目开发说明。

OpenAI 官方也建议使用 AGENTS.md 为 Codex 提供持久的项目上下文，例如命名规范、业务规则、项目特殊约束以及测试方式。(OpenAI)

例如：

text
xxx/
├── AGENTS.md
├── pom.xml
├── xxx-api
├── xxx-business
└── xxx-common

你可以在里面写：

markdown
# Project Instructions

## Technology

- Java 17
- Spring Boot
- MyBatis-Plus
- MySQL
- Redis
- RabbitMQ

## Coding Style

- Service 接口统一放在 service 包
- ServiceImpl 必须放在 service.impl
- Entity 不允许直接返回给 Controller
- Controller 统一返回 AjaxResult
- 禁止新增 Lombok @Data

## Database

修改数据库结构时：

- 必须提供 migration SQL
- 不允许直接删除已有字段
- 金额统一使用 BigDecimal

## Testing

修改完成后优先执行：

```bash
mvn test

如果只修改单模块：

bash
mvn -pl module-name test

未经明确要求：

  • 不要提交 Git Commit
  • 不要修改生产环境配置
  • 不要删除数据库 migration
这样以后你不用每次告诉 Codex：

```text
我们项目是 Java17。
我们使用 MyBatis-Plus。
金额必须 BigDecimal。
Controller 不允许直接返回 Entity。

因为这些长期规则已经写进：

text
AGENTS.md

7. 如何生成 AGENTS.md？ ​

Codex 提供了初始化工作流。

可以在项目中尝试：

text
/init

OpenAI 官方说明中，/init 可以为当前项目生成 AGENTS.md 的初始结构。(OpenAI Help Center)

第一次进入一个成熟项目时，可以先运行：

text
/init

然后再人工检查生成结果。

注意：

不建议完全依赖自动生成的 AGENTS.md。

因为 Codex 可以从代码里推断：

text
Java 版本
Spring Boot 版本
Maven 模块
目录结构

但很多真正重要的东西它无法从代码中准确推断。

例如：

text
这张表禁止直接更新
这个接口必须保持兼容
线上使用的是哪个配置中心
测试环境有什么特殊规则
金额统一保留几位
哪些模块不允许重构
Git 提交规范是什么

这些应该由开发者自己补充。

8. AGENTS.md 是怎么生效的？ ​

AGENTS.md 并不只是一个普通 README。

它主要是：

text
开发者
   ↓
告诉 Codex
   ↓
在这个目录下工作时必须遵守什么规则

例如：

text
project/
├── AGENTS.md
├── backend/
│   ├── src/
│   └── pom.xml
└── frontend/
    ├── AGENTS.md
    └── src/

可以理解为：

text
project/AGENTS.md

控制整个项目。

而：

text
frontend/AGENTS.md

可以针对前端目录提供更具体的规则。

更深层目录中的 AGENTS.md 可以提供更局部、更具体的说明。OpenAI 关于 AGENTS.md 的说明也强调，其规则通常按照所在目录向下作用，较深层的文件可以覆盖更上层的规则。(OpenAI)

这对于 Monorepo 特别有用：

text
project
├── backend
│   └── Java
│
├── admin-web
│   └── Vue
│
└── app
    └── Flutter

三个项目可以拥有不同规则。

9. README.md 和 AGENTS.md 有什么区别？ ​

很多人第一次看到 AGENTS.md 会问：

text
那 README.md 不就够了吗？

并不完全一样。

README 更偏向：

text
给人看

例如：

text
项目介绍
安装教程
启动方法
功能说明
API 使用方法

而 AGENTS.md 更偏向：

text
给 Coding Agent 看

例如：

text
修改代码必须遵守什么
哪些目录不能动
测试怎么执行
命名规则是什么
数据库修改有什么约束
提交代码前做哪些检查

可以简单理解：

text
README.md
→ 这个项目是什么

AGENTS.md
→ 在这个项目里应该怎么干活

当然两者可以有部分内容重叠。

10. Codex 的 Plan 模式是什么？ ​

这是 Codex 非常重要的一种使用思路。

对于简单修改：

text
把 UserService 里的一个变量名改掉

一般不需要复杂规划。

但如果任务变成：

text
把目前的余额更新机制改成基于流水账本，
同时保证原有充值、提现、奖励逻辑兼容。

就不应该马上开始写代码。

更适合：

text
先 Plan
再执行

Plan 模式的核心思想是：

先理解问题并形成实施方案，而不是直接修改代码。

新版 Codex 中存在面向规划的协作方式，具体可用命令和入口会随着 Codex CLI 版本变化；当前版本应以 /help 显示的能力为准。Codex 社区和官方产品演进中也已经提供了专门的规划工作方式。(OpenAI Developers)

即使当前版本没有直接暴露某个固定的 /plan 命令，也完全可以通过 Prompt 实现同样的工作流：

text
先进入规划阶段。

阅读相关代码并分析实现方案。

要求：

1. 不修改任何文件
2. 找出涉及的模块和类
3. 说明当前实现
4. 给出修改方案
5. 分析风险
6. 给出测试方案

等方案确认以后再修改代码。

这实际上就是：

text
Plan First

11. 为什么复杂任务一定要先 Plan？ ​

假设需求是：

text
增加用户余额冻结功能。

如果直接告诉 Codex：

text
帮我实现。

它可能马上：

text
新增字段
修改 Entity
修改 Mapper
修改 Service
增加 SQL

但真正的问题可能是：

text
冻结余额是否单独建表？
冻结后 available_balance 怎么计算？
旧数据怎么迁移？
提现逻辑是否受影响？
并发扣款如何处理？
是否需要流水？
解冻是否幂等？

如果先 Plan：

text
需求
 ↓
搜索相关代码
 ↓
理解当前架构
 ↓
分析影响范围
 ↓
设计方案
 ↓
确认
 ↓
实现

错误率通常会明显降低。

因此对于下面这些任务，非常建议先规划：

text
架构调整
数据库修改
大规模重构
支付逻辑
钱包逻辑
权限系统
登录认证
接口迁移
并发问题
性能优化
跨模块修改

12. 一个比较好的 Plan Prompt ​

实际可以这样告诉 Codex：

text
分析用户充值确认流程。

先不要修改代码。

请完成：

1. 找到充值扫描入口
2. 找到充值确认逻辑
3. 找到余额入账逻辑
4. 画出完整调用链
5. 分析幂等机制
6. 分析可能存在的并发问题
7. 给出改进方案
8. 列出需要修改的文件

完成分析以后停止，不要执行修改。

这个 Prompt 的重点并不是写得很长。

而是明确：

text
当前阶段只分析
不要实施

等方案确认后再说：

text
按方案实施。

要求：

1. 只修改刚才列出的文件
2. 不改变现有接口
3. 保持向后兼容
4. 修改完成后运行相关测试
5. 最后总结所有修改

这时候 Codex 才开始执行。

13. Codex 的 Permission 是什么？ ​

Coding Agent 和普通聊天 AI 最大的区别之一是：

text
它真的可以执行操作。

例如：

text
读取文件
修改文件
运行 Maven
运行 npm
执行 Git
执行 shell 命令

因此 Codex 存在权限控制。

在：

text
/status

中可能看到：

text
Permissions: Workspace

可以简单理解为：

Codex 当前拥有什么范围的操作权限。

实际权限策略会根据客户端、版本、配置和运行环境不同而变化。

Codex 的设计原则之一就是区分：

text
安全的本地操作

和：

text
高风险 / 外部 / 破坏性操作

例如 OpenAI 的模型指导中建议，可以允许 Agent 主动进行读取文件、修改范围内代码、执行非破坏性测试等本地操作，而对于外部写入、破坏性操作、付费操作或明显扩大任务范围的行为要求确认。(OpenAI Developers)

这也是使用 Coding Agent 时非常重要的安全边界。

14. 不要一上来就给最高权限 ​

虽然更高权限意味着：

text
少确认
执行更快

但同时意味着：

text
Agent 可以做更多事情

对于第一次接触 Codex 的开发者，更建议：

text
先保持比较保守的权限

观察它通常会执行哪些操作。

例如修改 Java 项目，它可能执行：

bash
grep
find
git diff
mvn test

这些通常问题不大。

但如果涉及：

bash
rm
git reset
docker
kubectl
ssh
mysql
psql
curl 生产接口

风险就完全不同了。

因此最好明确告诉 Codex：

text
未经确认不要：

1. 删除文件
2. 执行 git reset
3. 执行 git push
4. 修改生产配置
5. 连接生产数据库
6. 执行 kubectl 修改命令
7. 调用生产环境写接口

甚至可以直接写入：

text
AGENTS.md

15. /status 是非常实用的命令 ​

平时使用 Codex，可以经常查看：

text
/status

它可以帮助确认当前会话状态。

尤其需要注意：

text
Model
Directory
Permissions
Agents.md
Collaboration mode
Usage

例如：

text
Directory: ~

如果你本来打算修改：

text
~/IdeaProjects/xxx

那就说明当前目录可能不对。

如果：

text
Agents.md: <none>

说明当前没有检测到项目级 AGENTS.md。

如果使用量比较高，也可以通过 /status 查看当前 Codex 额度相关状态。OpenAI 的帮助文档也明确提到，可以在活跃 CLI Session 中通过 /status 查看使用情况。(OpenAI Help Center)

16. /help 应该是第一个记住的命令 ​

Codex 还在快速更新。

因此网上看到的命令：

text
可能已经新增
可能已经改名
可能只存在于某个客户端
可能只存在于某个版本

所以最可靠的方法其实是：

text
/help

查看：

当前安装版本真正支持哪些命令。

特别是：

text
Plan
Collaboration Mode
Model
Permission
Review
Context

这一类功能变化相对快。

不要完全依赖几个月以前的博客。

17. 不需要把所有命令都背下来 ​

刚开始使用 Codex，其实记住几个概念就够了：

功能用途
/help查看当前版本支持的命令
/status查看当前 Session 状态
/init初始化项目 Agent 指令
Model 相关命令切换或查看模型
Review 相关能力审查代码修改
Plan / Collaboration控制 Agent 的工作方式

具体命令应该以：

text
/help

输出为准。

因为 Codex CLI 的版本迭代速度非常快。

18. Codex 不只是“问问题” ​

普通聊天 AI 的使用方式通常是：

text
Q → A

但 Codex 更适合：

text
Task → Action

例如不要只问：

text
这个 Bug 怎么修？

而可以说：

text
分析这个 Bug。

找到根因以后直接修复，
运行相关测试，
最后告诉我：

1. 根因是什么
2. 修改了哪些文件
3. 为什么这样修改
4. 测试结果

这样 Codex 就从：

text
顾问

变成：

text
执行者

这才是 Coding Agent 更大的价值。

19. 给 Codex 的 Prompt 应该怎么写？ ​

很多人以为 Coding Agent Prompt 越长越好。

其实并不是。

一个好的 Codex Prompt 更重要的是明确四件事：

text
目标
范围
约束
验证

例如：

text
修复订单重复支付问题。

范围：

只分析 payment 和 order 模块。

约束：

1. 不改变现有 API
2. 不修改数据库结构
3. 保持现有返回格式
4. 不提交 Git

验证：

修改完成后运行相关 Maven 测试，
并检查 git diff。

这比：

text
帮我看看支付代码有没有问题然后优化一下

有效得多。

20. 一个通用 Codex Prompt 模板 ​

可以长期保存一个模板：

text
任务：

<我要完成什么>

范围：

<允许修改哪些模块 / 文件>

要求：

1. <要求1>
2. <要求2>
3. <要求3>

禁止：

1. <不要做什么>
2. <不要修改什么>

验证：

1. 执行相关测试
2. 检查编译
3. 检查 git diff

完成后输出：

1. 问题原因
2. 实现方案
3. 修改文件
4. 测试结果
5. 潜在风险

对于复杂需求，可以再加一句：

text
先分析并制定计划，不要立即修改代码。

21. Codex 最适合做哪些事情？ ​

个人比较推荐 Codex 用在下面几类任务。

21.1 阅读陌生项目 ​

例如：

text
分析这个项目的登录流程。
这个项目的 MQ 消息是怎么流转的？
解释这个项目的数据库结构。

这种任务特别适合 Codex。

因为它可以直接搜索整个 Repository。

21.2 查调用链 ​

例如：

text
找出 UserBalanceService.opsBalance 的所有调用方，
按照业务类型分类。

相比手动 IDE：

text
Find Usages

Codex 还可以进一步解释：

text
为什么调用
业务含义
上下游关系
风险

21.3 修 Bug ​

例如：

text
用户关闭 SSE 页面后后端出现 Broken pipe。

分析异常产生的位置，
判断是否需要处理，
如果需要则修改异常处理逻辑。

Codex 可以：

text
搜索异常
↓
找到 Controller
↓
找到 GlobalExceptionHandler
↓
分析 Tomcat
↓
修改代码
↓
跑测试

21.4 重构 ​

例如：

text
把重复的链上 RPC 请求逻辑提取成统一 RpcClient，
保持现有业务行为不变。

这种涉及多个文件的修改比单纯复制代码给聊天模型更适合 Codex。

21.5 写测试 ​

例如：

text
给 RewardService 增加单元测试。

覆盖：

1. level = 1
2. level = 8
3. null amount
4. amount = 0
5. 多级奖励

Codex 可以先分析现有测试框架，然后按照项目风格添加测试。

21.6 Code Review ​

例如：

text
检查当前 Git Diff。

重点关注：

1. 空指针
2. 并发问题
3. 数据一致性
4. BigDecimal 精度
5. SQL 性能
6. 向后兼容

不要修改代码，只输出 Review。

这也是非常推荐的一种用法。

22. 不要让 Codex 无限制修改整个项目 ​

例如下面这个 Prompt 风险很高：

text
优化整个项目。

因为：

text
优化

本身几乎没有边界。

Codex 可能认为：

text
改目录是优化
改类名是优化
升级依赖是优化
重写 Service 是优化
修改 SQL 是优化
删除代码也是优化

更好的写法：

text
优化 UserRewardService 的可读性。

只允许修改：

UserRewardService.java
UserRewardServiceImpl.java

要求：

1. 不改变任何业务逻辑
2. 不修改 public API
3. 不修改数据库
4. 不增加依赖
5. 完成后运行相关测试

Agent 的能力越强：

任务边界反而越重要。

23. Git 是使用 Codex 最重要的安全网 ​

使用 Coding Agent 之前，非常推荐确保项目已经进入 Git 管理。

开始任务之前：

bash
git status

确保当前代码状态清楚。

Codex 修改之后：

bash
git diff

检查修改。

最好保持：

text
一个任务
=
一组清晰 Diff

而不是让 Codex连续修改十几个不同需求。

推荐流程：

text
任务 A
 ↓
Codex 修改
 ↓
Review Diff
 ↓
测试
 ↓
Commit

任务 B
 ↓
Codex 修改
 ↓
Review Diff
 ↓
测试
 ↓
Commit

这样出了问题非常容易回滚。

24. 一个推荐的 Codex 实际开发流程 ​

如果是一个成熟项目，我比较推荐：

text
① cd 项目目录
        ↓
② codex
        ↓
③ /status
        ↓
④ 检查 AGENTS.md
        ↓
⑤ 让 Codex 阅读相关模块
        ↓
⑥ 复杂任务先 Plan
        ↓
⑦ 确认方案
        ↓
⑧ 开始修改
        ↓
⑨ Codex 执行测试
        ↓
⑩ Review Git Diff
        ↓
⑪ 人工检查
        ↓
⑫ Git Commit

不要变成：

text
需求
 ↓
AI
 ↓
直接上线

正确思路应该是：

text
Developer
    ↓
定义目标和边界
    ↓
Codex
    ↓
分析 + 实现 + 测试
    ↓
Developer
    ↓
Review
    ↓
上线

Codex 是：

工程能力放大器。

而不是：

生产环境自动驾驶。

25. 新手最值得养成的几个习惯 ​

如果刚开始使用 Codex，只建议先养成下面这些习惯：

text
进入正确项目目录再启动 Codex

复杂任务先分析，不要直接改

维护好 AGENTS.md

Prompt 明确范围和禁止事项

让 Codex 自己运行测试

修改完成一定检查 git diff

高风险操作不要随便授权

这些习惯比背几十个 Codex 命令更重要。

26. Codex、ChatGPT 和 IDE AI 应该怎么分工？ ​

可以简单这样理解。

ChatGPT ​

适合：

text
学习知识
理解概念
架构讨论
技术选型
独立代码示例

IDE AI ​

适合：

text
代码补全
当前文件修改
快速生成小函数

Codex ​

适合：

text
整个 Repository
多文件修改
跨模块分析
自动执行测试
重构
Bug 修复
Code Review
复杂工程任务

不是谁替代谁。

而是：

text
ChatGPT
→ 思考和讨论

IDE
→ 写代码时辅助

Codex
→ 把一个工程任务交给 Agent 执行

27. 最后怎么理解 Codex？ ​

如果只记住一句话：

text
Codex 不是一个更聪明的代码补全工具。

Codex 是一个可以进入你的项目、
读取代码、执行命令、修改文件并验证结果的 Coding Agent。

然后记住三个核心概念：

text
AGENTS.md
→ 告诉 Codex 在这个项目里应该怎么工作

Plan
→ 复杂任务先想清楚，再开始修改

Permissions
→ 决定 Codex 可以做到什么程度

最后再记住一个最实用的开发流程：

text
Read
 ↓
Plan
 ↓
Implement
 ↓
Test
 ↓
Review

也就是：

text
先读懂
再规划
再实现
再测试
最后人工 Review

当你开始按照这种方式使用 Codex，就会发现：

以前使用 AI 编程更多是在问：

text
这段代码应该怎么写？

而使用 Coding Agent 以后，问题会逐渐变成：

text
这个任务应该怎么完成？

这也是 AI 编程从：

text
Code Generation

走向：

text
Agentic Software Engineering

最明显的变化。