Codex 使用文档

1. Codex 是什么

Codex 是 OpenAI 面向软件开发场景的代码代理。它可以在终端、IDE 扩展或 Codex App 中帮助你完成代码理解、实现功能、修复问题、执行命令、审查变更、生成说明文档等工作。

从使用形态上看，Codex 主要分成几类：

• Codex CLI：在终端里使用，适合本地项目开发
• Codex IDE Extension：在编辑器内使用，适合边写边改
• Codex App / Web：偏任务委托和多项目管理
• MCP / Skills / Subagents：偏进阶扩展能力

---

2. 适合谁用

Codex 比较适合以下场景：

• 需要快速理解陌生代码仓库
• 想把重复性编码、重构、补测试交给代理处理
• 需要在终端里直接让 AI 改代码、跑命令、看结果
• 想在 IDE 里边选中文件边和 AI 协作
• 想给 AI 配置固定工程规则，例如构建命令、代码规范、禁止事项

如果你平时主要在本地仓库里干活，通常建议先从 Codex CLI 开始。

---

3. 快速开始

3.1 安装 Codex CLI

npm 安装

npm i -g @openai/codex

Homebrew 安装

brew install --cask codex

不同文档页面里 Homebrew 写法可能会有差异，实际以官方当前安装页为准。

3.2 启动

codex

首次启动后，一般会提示你登录。常见认证方式：

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

3.3 基本使用流程

一个最常见的本地使用流程是：

1. 进入你的项目目录

2. 先执行一次 Git 提交或至少确认当前改动状态

3. 运行 codex

4. 直接输入任务，例如：

   • 解释这个项目的启动流程
   • 给这个接口补单元测试
   • 修复这个 NPE，但不要改公共接口
   • 把这个模块重构成 service + repository 结构

5. 审查它的改动，再决定是否保留

---

4. Codex CLI 核心概念

4.1 Codex CLI 是什么

Codex CLI 是运行在本地终端中的代码代理。它能读取当前目录代码、修改文件、执行命令，并根据结果继续推理和迭代。

可以把它理解成：

• 不是单纯聊天机器人
• 而是一个会在你的项目目录里实际动手的代理

4.2 它能做什么

常见能力包括：

• 阅读并总结项目结构
• 搜索调用链、定位 bug
• 修改代码
• 运行测试、构建、lint
• 生成文档、变更说明、PR 描述
• 执行 review 类任务
• 接入 MCP 服务扩展外部工具能力

4.3 它和普通聊天窗口的区别

普通聊天窗口偏“给建议”；Codex 更偏“直接执行”。

差异主要在这里：

• 有目录上下文
• 能访问项目文件
• 能执行命令
• 能形成连续代理工作流
• 更适合真实工程任务

---

5. 常见工作模式

5.1 交互式模式

直接运行：

codex

然后持续对话式地下任务。这是最适合日常开发的模式。

5.2 非交互模式

适合脚本、CI、管道式调用。

官方文档里对应的是 codex exec。这类场景适合：

• 预设好输入输出
• 想把结果继续 pipe 给别的工具
• 在自动化流程里调用 Codex

示意：

codex exec "总结最近一次提交的变更风险"

5.3 Review / 专项工作流

Codex 提供了一些专项命令或 slash commands，适合：

• 审查未提交改动
• 检查当前状态
• 切换模型
• 调整权限
• 触发自定义命令

---

6. 常用命令与入口

6.1 最常见命令

codex
codex exec
codex mcp
codex mcp-server

6.2 Slash Commands

在交互界面里，可以通过 / 调出 slash commands。常见用途包括：

• /model：功能：1.切换当前使用的模型 2.查看可用模型列表
• /fast：切换或查看 fast mode
• /permissions：功能 控制 Codex 是否允许：修改文件 执行命令 自动操作
• /status：功能：1.查看当前模型 2.当前目录 3.权限状态 4.MCP 状态
• /agent：切换代理相关行为
• /init：初始化 AGENTS.md 帮助 Codex理解项目结构（只是生成最基础的，想要团队规范还是得自己配置一下 ，想要中文的话输入“把这个 AGENTS.md 转成中文版本，并优化为适合我的项目”
• /mcp：查看 MCP 服务状态（mcp使用见9）

不同客户端里可用命令略有差异，CLI、IDE、App 不一定完全一致。

6.3 命令行参数

Codex 支持通过命令行参数和 -c key=value 方式临时覆盖配置。优先级通常是：

• 当前命令行传参
• 项目级配置
• 用户级配置

---

7. 配置文件

7.1 配置文件位置

Codex 默认使用：

~/.codex/config.toml

项目级配置通常可以放在：

.codex/config.toml

7.2 为什么要配项目级配置

因为很多规则只对当前仓库有效，例如：

• 测试命令是什么
• 默认模型是什么
• 权限策略怎样设
• MCP 服务是否只对某个仓库生效

7.3 配置思路

建议把配置分成两层：

用户级配置

放通用偏好：

• 默认模型
• 全局审批偏好
• 常用工具配置

项目级配置

放工程规则：

• 构建/测试/格式化命令
• 与项目绑定的 MCP 服务
• 项目特定安全限制
• 团队约定

---

8. AGENTS.md（非常重要）

8.1 什么是 AGENTS.md

AGENTS.md 是 Codex 的项目级长期说明文件。Codex 在开始干活前会先读取它。

它的作用不是替代 prompt，而是把每次都应该遵守的工程规则固定下来。

8.2 适合写什么

推荐写这些内容：

• 仓库目录结构说明
• 如何启动、构建、测试
• 代码风格和工程规范
• 哪些目录不能改
• 修改后必须执行什么验证
• PR 说明要求
• “完成”的判断标准

8.3 不适合写什么

不建议塞太多冗长背景、过时说明或大段业务文档。

原则上应该：

• 短
• 准
• 稳定
• 可执行

8.4 快速生成

Codex CLI 提供 /init 可帮助你快速生成一份起始版 AGENTS.md，但生成后最好自己再改一遍。

8.5 一个实用模板

# AGENTS.md

## Project Overview
This is a Spring Boot monorepo for HRMS-related services.

## Important Directories
- `adapter/`: controllers and API entrypoints
- `app/`: application services
- `domain/`: domain models and domain services
- `infrastructure/`: persistence and external integrations

## Commands
- Build: `mvn clean install -DskipTests`
- Test: `mvn test`
- Run: `mvn spring-boot:run`

## Rules
- Do not change public API contracts unless explicitly asked.
- Prefer minimal changes.
- Add tests for bug fixes when feasible.
- Keep SQL compatible with MySQL 8.

## Done Criteria
- Code compiles
- Tests pass
- No unrelated refactors

---

9. MCP Servers

9.1 什么是 MCP

MCP 是 Model Context Protocol，用来让 Codex 连接外部工具或服务。

你可以把它理解成：

• Codex 本体负责推理
• MCP Server 负责提供外部能力
• 两者通过协议连接起来

9.2 MCP 能做什么

常见用途：

• 访问文档服务
• 连接数据库、知识库、浏览器、Issue 系统
• 获取项目外部上下文
• 让 Codex 调用额外工具

9.3 配置方式

有两种常见方式：

方式一：CLI 管理

codex mcp add <server-name> -- <server-command>

例如：

codex mcp add context7 -- npx -y @upstash/context7-mcp

方式二：直接写配置文件

在 ~/.codex/config.toml 或项目级 .codex/config.toml 里配置。

9.4 查看 MCP 状态

在交互界面中可通过：

/mcp

查看当前活动 MCP 服务。

9.5 直接把 Codex 当 MCP Server

Codex 自己也可以作为 MCP Server 启动：

codex mcp-server

这适合把 Codex 接到别的 MCP Client 或代理系统里。

---

10. Subagents（子代理）

10.1 什么是 Subagents

Subagents 是 Codex 的并行子代理能力。主代理可以把复杂任务拆给多个更专门的子代理，然后收拢结果。

10.2 适合哪些场景

很适合：

• 大仓库探索
• 多模块并行排查
• 一边改代码一边补测试一边写文档
• 对不同任务分配不同指令或模型配置

10.3 自定义子代理思路

常见拆法：

• 代码阅读代理：只做项目结构分析
• 实现代理：只做功能开发
• 测试代理：只补测试和验证
• 审查代理：只检查改动质量和边界

这种方式特别适合复杂任务，但前提是你先把任务边界写清楚。

---

11. Skills

11.1 什么是 Skills

Skill 可以理解成 Codex 的可复用能力包。一个 Skill 里可以包含：

• 指令
• 资源
• 脚本
• 约束

作用是让 Codex 在某类任务上更稳定地按固定流程工作。

11.2 什么时候该用 Skill

当你有这些需求时就适合：

• 某项工作反复做
• 每次步骤都差不多
• 想降低 prompt 波动
• 希望团队共享一套 AI 工作流

11.3 典型场景

例如：

• 自动生成 PR 描述
• 固定格式的代码审查
• 前端页面样式检查
• 数据库变更检查
• 发布前 checklist

---

12. IDE 中怎么用 Codex

12.1 IDE 扩展的特点

IDE 扩展比 CLI 更适合这些场景：

• 你想基于当前打开文件、选中代码直接提问
• 你想在编辑器里看 diff 和上下文
• 你需要快速在 Chat / Agent / Full Access 之间切换

12.2 常见能力

• 使用打开文件作为上下文
• 引用选中代码片段
• 使用 @file 形式引用文件
• 切换模型
• 调整 reasoning effort
• 切换审批模式
• 将长任务委托到云端环境

12.3 适合你的选择建议

如果你主要在 IDEA/VS Code 里工作：

• 日常写业务代码：IDE 扩展更顺手
• 批量改代码、跑命令、重构：CLI 更直接
• 复杂任务拆解：CLI + AGENTS.md + MCP 更强

---

13. 推荐使用姿势

13.1 新项目接入建议

建议按这个顺序上手：

1. 安装 Codex CLI
2. 在测试仓库中运行几次
3. 给仓库补一份 AGENTS.md
4. 配置项目级 .codex/config.toml
5. 再逐步接入 MCP
6. 最后尝试 Subagents / Skills

13.2 最稳的工作流

一个比较稳的工程化流程：

1. 先让 Codex 总结项目结构
2. 再让它给出实现计划
3. 确认计划后再让它修改
4. 改完后要求它跑测试/构建
5. 最后让它输出变更摘要与风险点

13.3 Prompt 写法建议

比起一句“帮我改一下”，更推荐这种写法：

请在当前模块中修复用户详情查询的空指针问题。
要求：
1. 不修改对外接口
2. 只做最小改动
3. 如果需要，补充单元测试
4. 修改后执行相关测试并汇报结果
5. 输出变更文件列表和风险点

---

14. 安全与权限建议

Codex 能改代码、跑命令，所以权限控制很重要。

建议你遵循这几个原则：

• 先在测试仓库练手
• 先做 Git checkpoint
• 不要一上来就给过高权限
• 对 shell 命令执行保持审查
• 对数据库、生产配置、密钥文件要特别谨慎
• 项目规则尽量写进 AGENTS.md

---

15. 适合你的几类常见用法

15.1 Java 后端开发

你这种偏 Java / Spring Boot / 微服务开发，Codex 很适合：

• 解释 controller -> app -> domain -> infra 调用链
• 补 DTO / MapStruct / MyBatis 相关代码
• 优化 SQL 或补索引建议
• 给接口补单测/集成测试
• 帮你做局部重构，不大改架构

15.2 读老项目

例如你可以直接让它：

• 解释某个接口从入口到数据库的完整链路
• 列出某个字段在哪些模块被使用
• 总结某个服务的核心职责
• 画出模块关系的 mermaid 图

15.3 故障排查

也很适合：

• 根据异常堆栈定位源码
• 找出某个 401/502 的可能链路
• 排查配置缺失、Bean 注入、线程上下文丢失
• 给出最小修复方案

---

16. 常见问题

16.1 Codex CLI 和 IDE 扩展怎么选？

• 想在终端里直接动项目：选 CLI
• 想结合编辑器上下文：选 IDE 扩展
• 最常见是两者一起用

16.2 AGENTS.md 和普通 prompt 有什么区别？

• prompt 是这次任务的即时要求
• AGENTS.md 是项目长期规则

16.3 MCP 是必须的吗？

不是。初学者完全可以先不用。

先把这三件事用好就够了：

• CLI
• AGENTS.md
• 项目级配置

16.4 Subagents 是不是越多越好？

不是。只有任务边界清楚、并行价值高时才适合。简单任务没必要拆。

---

17. 一份最小上手清单

如果你现在就要开始，照这个做：

第一步：安装

npm i -g @openai/codex

第二步：进入项目

cd your-project

第三步：启动

codex

第四步：先问它

先阅读这个项目，告诉我：
1. 项目结构
2. 启动方式
3. 核心模块
4. 测试怎么跑
5. 你建议我补充什么 AGENTS.md

第五步：初始化项目规则

/init

然后把生成的 AGENTS.md 改成适合你项目的版本。

---

18. 总结

如果只抓重点，Codex 最值得你先掌握的其实只有四个：

1. CLI 基本操作
2. AGENTS.md
3. 项目级配置
4. MCP / Subagents / Skills 的扩展思路

先把这四项用顺，再去折腾更复杂的自动化工作流，效率会高很多。