Codex 是 OpenAI 面向软件开发场景的编码智能体，可以在本地仓库中阅读代码、编辑文件、执行命令并协助验证结果。本文用图文方式整理一套实用工作流，帮助你把 Codex 从“问答工具”用成“能闭环交付的小型开发助手”。

1. Codex 适合做什么

Codex 最适合处理有明确目标、能被验证、上下文可以从仓库中读取的任务，例如：

  • 修复构建、测试、类型检查或 lint 报错；
  • 解释陌生模块、梳理调用链、总结目录职责；
  • 新增小功能、补测试、改文档、重构局部代码；
  • 根据错误日志定位问题，并给出可复现的修复步骤；
  • 审查 Git diff，发现潜在回归、边界条件和缺失测试。

不建议一上来就把边界很大的需求直接丢给 Codex，例如“重写整个系统”“优化所有页面”。更好的做法是先让它阅读项目、输出计划，再按任务拆分推进。

Codex 工作闭环

核心原则只有一句：让 Codex 能够验证自己的工作。如果任务最后只能靠“看起来差不多”，它就容易停在猜测；如果你给出测试命令、构建命令、截图要求或清晰验收标准，它就能形成反馈闭环。

2. 安装与启动

通常可以通过 npm 安装 Codex CLI：

npm install -g @openai/codex

进入项目目录后启动：

cd your-project
codex

首次使用时按提示登录 OpenAI 账号或配置 API Key。启动后，Codex 会以当前目录作为工作区，读取仓库文件、执行命令和编辑代码。建议在 Git 工作区干净或至少知道当前 diff 的情况下开始任务，方便后续检查改动。

常用启动方式：

# 交互式使用，适合日常开发
codex

# 一次性执行一个明确任务
codex "阅读 package.json，说明这个项目如何构建"

# 在当前仓库中让 Codex 先给计划，不急着改代码
codex "先分析登录模块，给出修复移动端样式问题的计划，暂时不要修改文件"

3. 第一次任务怎么写

新手最常见的问题不是“Codex 不会做”，而是任务描述太短，导致它缺少判断依据。

Codex 上下文输入结构

推荐把提示词写成下面这种结构：

目标：修复用户列表页搜索按钮在 390px 宽度下被挤出容器的问题。

上下文：
- 相关页面可能在 src/pages/users 或 src/views/user 下。
- 项目使用 Vue 3 和 Element Plus。
- 当前报错或截图现象是：按钮换行后遮挡表格工具栏。

约束：
- 不要改接口字段。
- 不要重做整个页面布局。
- 尽量沿用现有样式变量。

验证：
- 修改后运行 npm run build。
- 如果有浏览器工具，检查 390px 和 1440px 两种宽度。

交付：
- 说明改了哪些文件。
- 说明验证结果。

这个模板看起来比一句“帮我修一下页面”长，但它能显著减少返工。Codex 需要知道的不只是“做什么”，还包括“不要做什么”和“怎样才算完成”。

4. 先探索，再计划，再执行

复杂一点的任务，建议分三步走。

第一步，只让 Codex 读代码：

阅读订单模块相关代码，找出创建订单、更新订单状态、生成出库单分别在哪里实现。
先不要修改文件，只给我调用链和关键文件列表。

第二步，让它给计划：

基于刚才的分析，计划新增“订单取消原因”字段。
说明需要修改哪些后端实体、接口、前端页面和测试。
先不要写代码。

第三步，再让它执行并验证：

按计划实现。改完后运行后端测试和前端构建。
如果命令失败，先分析根因再修复，不要通过删除测试或绕过校验来通过。

这种节奏比“直接开改”慢一点，但更稳。尤其是多文件修改、生产项目、陌生代码库和架构调整，先计划能避免方向错了还改出一大片 diff。

5. 权限、沙箱与高风险命令

Codex 可以执行本地命令，所以必须理解权限边界。

Codex 权限与沙箱

日常开发中，下面这些操作通常风险较低：

  • 读取文件、搜索代码、查看 Git diff；
  • 编辑当前工作区内的代码和文档；
  • 运行项目已有的测试、构建、类型检查、格式化命令。

下面这些操作要谨慎授权：

  • 安装依赖，例如 npm install、pip install、brew install；
  • 访问网络、调用外部接口、下载文件；
  • 删除文件、清理目录、修改系统路径；
  • Git 重置、强制切换分支、覆盖用户未提交改动；
  • 执行数据库迁移、生产脚本或带有凭据的命令。

如果 Codex 请求执行一个你不熟悉的命令，先让它解释三个问题：

这个命令为什么必要？
它会修改哪些文件或外部资源？
有没有更小范围的验证方式？

一个好习惯是：授权前看意图，授权后看结果。Codex 执行完命令后，应该要求它总结关键输出，而不是把几百行日志原样贴出来。

6. 用 AGENTS.md 固化项目规则

如果你经常在同一个仓库中使用 Codex，建议维护 AGENTS.md。它相当于写给 AI 协作者的项目手册，可以把仓库结构、常用命令、代码规范、验证要求和禁区写进去。

AGENTS.md 仓库协作手册

一个最小可用的 AGENTS.md 可以这样写：

# Agent 工作指南

## 项目概览

这是一个 Vue 3 + Vite 项目。

- `src/pages/`: 页面组件
- `src/components/`: 通用组件
- `src/api/`: 接口封装
- `tests/`: 单元测试

## 常用命令

```bash
npm run dev
npm run build
npm run test
```

## 约束

- Vue 文件使用 `<script setup lang="ts">`。
- 不要手动编辑 `dist/`。
- 修改 UI 后需要检查移动端和桌面端。
- 提交前至少运行 `npm run build`。

AGENTS.md 的价值在于减少重复沟通。你不用每次都提醒“不要改 dist”“构建命令是什么”“文章格式是什么”，Codex 进入仓库后就能先读取这些约定。

7. 常用交互技巧

让 Codex 只读分析

只读分析当前仓库的认证流程，列出登录态从接口到前端存储的完整链路。
不要修改任何文件。

适合接手老项目、做重构前调研、审查风险。

让 Codex 以审查者身份看 diff

请按代码审查方式检查当前 git diff。
优先指出 bug、回归风险、缺失测试和安全问题。
不要重写代码，先给 findings。

适合提交前自查。它不会替代人工 review，但能提前发现低级问题。

给失败日志让它闭环修复

npm run build 失败，错误日志如下：
<粘贴关键错误>

请定位根因并修复。修复后重新运行 npm run build。
不要通过关闭类型检查或删除报错代码来绕过问题。

日志不要贴太多，优先贴第一处错误、调用栈和相关文件路径。大段日志可以让 Codex 自己运行命令读取。

明确最终输出格式

完成后请按下面格式汇报：
1. 修改文件
2. 行为变化
3. 验证命令与结果
4. 仍需人工确认的风险

这能让交付结果更稳定，也便于你快速判断任务是否真的完成。

8. 什么时候使用 Plan 模式

当任务满足任意一个条件时，建议先进入计划模式：

  • 需要修改多个模块；
  • 需求还不够清楚；
  • 涉及数据库、权限、支付、登录等高风险逻辑；
  • 你希望先确认方案，再让 Codex 写代码；
  • 你担心它误删、误改或扩大范围。

计划阶段应该要求 Codex 回答：

  • 它理解的目标是什么；
  • 它准备读取哪些文件；
  • 它会修改哪些文件；
  • 每一步如何验证；
  • 哪些地方需要你确认。

计划确认后再进入执行阶段。这个过程看似多一步，实际能减少大量回滚和返工。

9. 一套可复用的日常工作流

下面是一套适合大多数开发任务的流程。

9.1 新功能

先阅读相关模块，给出实现计划。
计划需要包含：数据结构、接口、页面、测试和验证命令。
确认计划前不要修改文件。

确认后：

按计划实现，保持改动聚焦。
实现后运行测试和构建。
最后总结修改文件、验证结果和风险。

9.2 修 Bug

根据这个错误现象定位根因：
<现象或日志>

请先说明最可能的原因、涉及文件和复现方式。
不要急着改代码。

确认后：

修复根因，并补充能覆盖这个问题的测试。
验证失败时继续分析，不要绕过测试。

9.3 写文档

阅读 README、配置文件和相关源码，更新部署文档。
要求内容真实，不要臆测不存在的配置。
更新后检查 Markdown 链接和命令是否与 package.json 一致。

9.4 重构

分析这个模块的重复逻辑，提出最小重构方案。
要求保持外部行为不变，并说明如何证明行为不变。

重构最怕“顺手改需求”，所以一定要强调行为保持和验证方式。

10. 常见错误用法

只给一句话

帮我优化一下项目。

问题是范围无限大。Codex 可能开始改格式、改结构、改依赖，但这些都未必是你要的。

不给验证方式

修好这个 bug。

更好的写法是：

修复这个 bug，并补一个失败前能复现、修复后能通过的测试。
最后运行 npm run test。

一次塞太多目标

顺便升级依赖、重构登录、优化首页、修复构建、补测试。

建议拆成多个任务。Codex 的上下文和注意力也是有限的，任务越杂，越容易遗漏。

盲目授权高风险命令

当命令会删除文件、重置 Git、安装依赖或访问外部系统时，不要只看它“像是对的”。先让 Codex 解释影响范围，再决定是否执行。

11. 写给团队的使用建议

如果团队要把 Codex 纳入日常开发，可以建立几条简单规则：

  1. 仓库根目录维护 AGENTS.md，并让它随项目演进更新；
  2. 新功能先计划，修 Bug 先复现，重构先定义行为不变的验证方式；
  3. 禁止让 AI 绕过测试、关闭类型检查或删除断言来“通过构建”；
  4. 所有 AI 生成代码仍然走正常 review；
  5. 涉及凭据、生产数据、线上操作时，必须人工确认命令和影响范围。

Codex 的优势不是替代工程判断，而是把“查代码、改局部、跑验证、整理结果”这些步骤变快。你给它越清晰的目标、边界和验证方式，它越像一个可靠的协作者。

参考资料