Codex Cli 用法实践入门 | Geepair’s Blog

type

Post

status

Published

date

Apr 27, 2026

slug

summary

记录codex的使用技巧，入门实践等等

1、Codex CLI 的介绍、安装和基础使用

1.1 Codex CLI 是什么？

Codex CLI 是 OpenAI 提供的本地命令行 AI 编程代理工具。它可以运行在你的终端中，直接读取、理解、修改、执行你本地项目里的代码。

你可以把它理解为：

一个运行在终端里的 AI Pair Programmer，可以帮你读代码、改代码、写测试、运行命令、修复 Bug、解释架构、生成文档。

与传统 ChatGPT 网页复制粘贴代码不同，Codex CLI 的核心优势在于：

能力	说明
本地项目上下文	可以直接读取当前 Git 仓库中的代码
命令行操作	可以运行测试、构建、格式化、lint 等命令
文件修改	可以直接编辑项目文件
多轮任务执行	可以围绕一个目标持续分析、修改、验证
与 Git 配合	可以基于分支、diff、commit 进行工程化开发
适合后端项目	对 Java、Go、Python、Node.js、Rust 等项目都比较友好

Codex CLI 不是简单的代码补全工具，而更像是一个本地 coding agent。

1.2. Codex CLI 适合什么场景？

Codex CLI 特别适合下面这些程序员日常场景：

阅读和理解老项目（explore）

修复BUG（fixbug）

编写单元测试（unittest）

重构代码（refactor）

生成文档（writedoc）

配合 CI/CD 排查问题（review）

其他…

1.3 Codex CLI 的安装

codex

openai • Updated Apr 28, 2026

官方推荐的安装方式主要有两种：

使用 npm 安装

如果你已经安装了 Node.js，可以使用：

启动：

使用 Homebrew 安装

macOS 用户可以使用：

1.4 Codex CLI 的认证方式

Codex CLI 通常支持两类认证方式：

使用 ChatGPT 账号登录使用 OpenAI API Key

使用 ChatGPT 账号登录

使用 OpenAI API Key

使用 ChatGPT 登录

使用 API Key

如果你希望通过 OpenAI API 调用模型，可以配置环境变量：

为了让它永久生效，可以写入 shell 配置文件：

注意：不要把 API Key 写入项目代码、Git 仓库、README 或共享脚本中。

1.5 Codex CLI 的基础使用

在项目目录中启动

这样 Codex 可以更好地读取项目结构、构建文件和源码。

常用提问方式

分析项目结构

解释某个类

修改代码

编写测试

修复构建失败

生成提交说明

Codex CLI 的常见工作流

小任务工作流

适合修改一个小 Bug 或简单功能。

推荐流程：

让 Codex 先分析问题

要求它给出修改方案

让它修改代码

运行测试

查看 git diff

人工 review

手动commit

中型功能工作流

适合新增接口、服务逻辑、数据库字段等。

例如：

然后要求：

最后：

大型重构工作流

对于大重构，不建议一句话让 Codex 直接动手：

这种提示太宽泛，容易导致不可控修改。

更好的做法：

然后：

再执行：

在 Java 项目中的最佳实践

启动前先保证项目可构建

在让 Codex 修改代码之前，最好先确认项目本身是健康的：

如果项目一开始就有失败测试，建议告诉 Codex：

建议为项目添加 AGENTS.md

很多 AI coding agent 都会读取项目级说明文件，例如 AGENTS.md。你可以在项目根目录添加：

这样 Codex 每次进入项目后都能更好地遵守约定。

明确 Java 版本和框架版本

提示中最好明确：

否则 Codex 可能会生成你当前项目不支持的语法或依赖。

控制修改范围

不要让 Codex 一次性修改太多文件。

不推荐：

2、Codex CLI 结合 oh-my-codex 增强功能

2.1 oh-my-codex 是什么？

oh-my-codex，简称 OMX，是一个围绕 OpenAI Codex CLI 构建的工作流增强层。如果说 Codex CLI 是一个强大的 AI 编程代理，那么 oh-my-codex 就像是给 Codex 加了一套：

工作流规范

项目记忆

任务规划

Agent 角色

技能系统

运行时辅助

多 Agent 协作

项目状态管理

它的定位不是替代 Codex CLI，而是增强 Codex CLI。

可以类比：

oh-my-codex 主要解决的问题是：

问题	Codex CLI 原始体验	oh-my-codex 增强后
任务容易跑偏	依赖提示词质量	引入标准工作流
缺少长期状态	多轮对话容易丢上下文	使用 .omx/ 保存计划、日志、状态
复杂任务拆解困难	需要手工引导	提供 $deep-interview、$ralplan 等技能
多 Agent 协作弱	单 Agent 为主	支持 $team 协同执行
项目规范不稳定	靠临时 prompt	结合 AGENTS.md 和 OMX 配置

2.2 oh-my-codex 的核心能力

更强的 Codex 启动体验

例如：

可以用更激进、更高能力的模式启动 Codex 工作流。

标准化工作流

OMX 常用技能包括：

大致可以理解为：

技能	作用
$deep-interview	深度澄清需求，避免一上来就写代码
$ralplan	制定或审批实现计划
$ralph	持续执行已批准计划直到完成
$team	多 Agent / 多角色协同执行任务

.omx/ 项目状态目录

OMX 会在项目中维护 .omx/ 目录，用于保存：

计划

日志

记忆

模式状态

任务上下文

运行时信息

这对于中大型项目非常有用，因为很多开发任务不是一次会话就能完成的。

与 AGENTS.md 配合

OMX 会更重视项目级指导说明，例如：AGENTS.md

你可以在其中定义：

项目架构

编码规范

测试命令

禁用操作

提交规范

领域术语

2.3 oh-my-codex 的安装

环境要求

推荐环境：

macOS 或 Linux

Node.js 20+

已安装 Codex CLI

Codex CLI 已完成认证

tmux，推荐用于稳定的团队运行时

官方特别强调：oh-my-codex 主要针对 macOS/Linux + Codex CLI 体验优化。Native Windows 和 Codex App 不是默认推荐路径，可能行为不稳定。

安装 Codex CLI 和 oh-my-codex

如果你还没装 Codex CLI：

安装 OMX：

也可以一次安装：

初始化设置

安装后运行：

说明 OMX 可以调用当前环境中的 Codex。

oh-my-codex 的基础使用

在项目中启动 OMX

需求澄清：$deep-interview

当你有一个不够清晰的需求时，先不要让 Codex 直接写代码，而是使用：

它应该会围绕这些方面提问：

优惠券类型

优惠范围

叠加规则

有效期

用户限制

订单金额门槛

退款后优惠券处理

数据库设计

接口设计

测试场景

这一步非常重要，因为 AI 编程中最大的问题往往不是“代码不会写”，而是“需求没有说清楚”。

制定计划：$ralplan

需求澄清后，让 OMX 帮你形成计划：

一个好的计划通常包括：

修改哪些表

新增哪些 Entity / DTO

新增哪些 Controller

新增哪些 Service 方法

需要哪些校验

需要哪些测试

风险点

分阶段执行顺序

执行计划：$ralph

$ralph 更适合单线持续推进任务。

多 Agent 执行：$team

对于较复杂任务，可以使用：

这相当于让多个执行角色协同工作。

适合：

前后端并行

测试和实现并行

文档和代码并行

多模块改造

大型重构

但也要注意，多 Agent 并行修改可能造成冲突，所以建议在清晰计划下使用。

2.4 oh-my-codex 在 Java 项目中的最佳实践

用 OMX 做复杂需求开发

第一步：澄清需求

第二步：制定计划

第三步：人工审查计划

第四步：执行

第五步：验收

然后自己执行或者让codex处理：

OMX + Java 项目的 AGENTS.md 示例

2.5 oh-my-codex 使用建议

小任务不一定需要 OMX

直接用 Codex CLI 就可以。

中大型任务优先使用 OMX

先计划，再执行

OMX 的价值在于流程，不要跳过计划：

多 Agent 慎用

$team 很强，但也可能带来：

建议只在计划明确、模块边界清晰时使用。

3、Codex CLI 结合 Superpowers 插件

3.1 Superpowers 是什么？

Superpowers 是一套面向 AI coding agent 的软件开发方法论和技能系统。它不是单纯的提示词集合，而是试图把 AI 编程过程变成一种更稳定的工程流程。

它的核心理念是：

不要让 AI 一上来就写代码，而是先澄清需求、形成设计、拆分计划、测试驱动、逐步执行、持续 review、最终验证。

Superpowers 为 AI coding agent 提供了一组可组合的技能，例如：

这些技能让 AI 更像一个遵守工程规范的开发团队，而不是一个随机生成代码的聊天机器人。

3.2 Superpowers 解决什么问题？

AI 写代码常见问题包括：

Superpowers 的目标是通过固定工作流减少这些问题。

3.3 Superpowers 的核心工作流

brainstorming

在写代码之前先进行头脑风暴和需求澄清。

理解真实需求

探索替代方案

识别边界条件

确认设计方向

using-git-worktrees

在设计确认后，使用 Git worktree 创建隔离工作区。

避免污染当前工作区

支持并行任务

方便回滚

方便 review

writing-plans

将设计拆分为可执行任务。

一个好的计划应该足够详细，甚至让一个不了解上下文的初级工程师也能执行。

具体文件路径

具体修改内容

测试步骤

验证命令

完成标准

test-driven-development

Superpowers 强调真正的 TDD：

RED：先写失败测试

GREEN：写最少实现让测试通过

REFACTOR：重构并保持测试通过

它不鼓励 AI 先写一堆实现再补测试。

executing-plans / subagent-driven-development

计划确认后，AI 按任务执行。

对于支持子 Agent 的环境，可以让不同 Agent 分别完成：

实现

测试

review

文档

验证

requesting-code-review

执行过程中要求 review。

是否符合设计

是否测试充分

是否有过度设计

是否破坏兼容性

是否存在安全问题

verification-before-completion

完成前必须验证。

AI 不能只说“应该可以”，而必须提供证据。

3.4 Codex CLI 中安装 Superpowers

根据 Superpowers 当前官方说明，Codex CLI 中可以通过插件搜索界面安装：

打开 Codex CLI 的插件搜索界面

搜索 Superpowers

选择 Install Plugin

3.5 Superpowers 的基本使用

Superpowers 的理想状态是：安装后 Agent 会自动检查当前任务是否应该使用对应技能。不过在实际使用中，你可以显式提醒 Codex：

3.6 Java 项目中使用 Superpowers 的完整示例

订单系统新增积分抵扣功能

第一步：brainstorming

期望它澄清：

第二步：形成设计

第三步：writing-plans

第四步：test-driven-development

maven验证：

第五步：code review

第六步：最终验证

验证：

3.7、Superpowers 在项目开发中的最佳实践

适合用 Superpowers 的场景

Superpowers适合：

中大型功能开发

复杂 Bug 修复

需要 TDD 的核心业务逻辑

需要长期执行的任务

团队协作任务

遗留系统改造

多 Agent 开发流程

不太适合：

改一个变量名

修一个简单 typo

生成一段临时代码

一次性脚本

强制“先问清楚再写代码”

建议在项目说明中加入：

把 TDD 规则写进 AGENTS.md

使用 Git worktree 隔离复杂任务

对于大任务，不建议直接在主工作区执行：

主工作区保持干净

多个 AI 任务可以并行

失败后可以直接删除 worktree

不要跳过 review

即使 Superpowers 帮你做了 code review，你仍然需要人工 review：

AI review 是辅助，不是最终质量门。

3.8 Superpowers 与 oh-my-codex 的区别

对比项	oh-my-codex	Superpowers
定位	Codex CLI 的工作流增强层	面向 coding agent 的软件开发方法论和技能系统
核心能力	OMX 运行时、状态、Agent 编排、.omx/	TDD、计划、debug、review、worktree、验证
典型命令	$deep-interview、$ralplan、$ralph、$team	brainstorming、writing-plans、test-driven-development 等技能
适用重点	强化 Codex CLI 使用体验	规范 AI 开发过程
是否偏 Codex	是，围绕 Codex CLI	多平台，支持 Claude Code、Codex、Cursor、Gemini CLI 等
项目状态	.omx/	更多是技能和方法论
多 Agent	$team 等	subagent-driven-development

oh-my-codex 更像 Codex 的增强运行时和编排层；

Superpowers 更像 AI 开发方法论和技能库。

二者可以互补：

用 oh-my-codex 管 Codex 会话、状态和多 Agent；

用 Superpowers 约束需求澄清、计划、TDD 和验证流程。

3.9 Superpowers 与 OpenSpec 的对比

OpenSpec 是什么？

OpenSpec 是一个面向 AI 编程的轻量级规范驱动开发框架。它的核心思想是：

在写代码之前，先把需求、设计、任务以结构化文档形式固定下来。

OpenSpec 通常会在项目中生成类似这样的结构：

Superpowers vs OpenSpec

对比项	Superpowers	OpenSpec
核心定位	AI 软件开发方法论和技能系统	规范驱动开发框架
关注重点	怎么做开发	写代码前先定义清楚要做什么
产物	技能触发、计划、测试、review、验证	proposal.md、design.md、tasks.md、specs
约束方式	工作流和技能	文件化规范和变更管理
TDD	强调 TDD	可结合 TDD，但核心是 Spec
适合场景	实施过程管控	需求和设计固化
对团队协作	强调执行纪律	强调可追溯规范
是否轻量	中等	相对轻量，文档结构清晰
与 Codex	作为插件/技能增强	作为外部规范系统配合 AI

OpenSpec 解决“我们到底要做什么”的问题；

Superpowers 解决“我们应该怎么把它做好”的问题。

两者结合的推荐流程

对于复杂 Java 项目，可以这样组合：

Codex CLI + oh-my-codex + Superpowers + OpenSpec 的整体选型建议

只用 Codex CLI

个人项目

小任务

快速修 Bug

代码解释

简单测试生成

入门必备

Codex CLI + oh-my-codex

日常大量使用 Codex

希望有更强工作流

需要多 Agent 协作

需要项目记忆和状态

中大型任务

Codex 重度用户推荐

Codex CLI + Superpowers

想让 AI 更守工程纪律

强调 TDD

强调 review

强调验证

复杂功能和 Bug 修复

工程质量优先团队推荐

Codex CLI + OpenSpec

需求容易变

多人协作

需要文档沉淀

企业项目

中大型功能

团队项目推荐

全家桶组合

复杂业务系统

企业级 Java 后端

多人团队协作

长期演进项目

AI 深度参与开发流程

4、总结

Codex CLI 是一个非常适合程序员日常使用的本地 AI 编程代理。它的优势在于能直接理解和修改本地项目，尤其适合 Java 后端项目中的代码阅读、测试补齐、Bug 修复和功能开发。

但对于复杂项目，仅靠 Codex CLI 原生能力还不够：

oh-my-codex 适合增强 Codex CLI 的会话能力、项目记忆、任务计划和多 Agent 协作。Superpowers 适合给 AI 加上工程纪律，包括需求澄清、计划、TDD、review 和最终验证。OpenSpec 适合把需求和设计固化为可追踪的规范文档，特别适合团队项目和中大型功能开发。