Codex 深度指南：从安装到交付项目

普通 ChatGPT 更像顾问：你问它怎么做，它给你解释、方案、代码片段。Codex 更像一个坐在你电脑旁边的程序员：它能进入项目目录，读文件，改文件，跑命令，再把结果给你看。

你可以把 Codex 理解成三件事的组合。第一，它会读项目上下文，不是只看你复制进去的几行代码。第二，它能直接修改本地文件，所以适合做真实项目里的小功能、修 bug、补文档、重构。第三，它会运行命令，比如安装依赖、跑测试、启动构建，但高风险操作应保留人工确认。

适合交给 Codex 的任务包括：解释一个陌生项目、补一个页面、修一个报错、写单元测试、改接口字段、生成 README、检查代码风险、把重复代码抽成组件。不适合一开始就交给 Codex 的任务包括：没有需求说明的大型系统重构、涉及资金或用户数据的生产库操作、你完全看不懂也不准备验收的代码变更。

小白最容易犯的错是把 Codex 当成“许愿机”。正确做法是把任务写成验收标准：要改哪个页面、成功后看到什么、不能破坏什么、怎么测试。Codex 做得越像真实外包，效果越稳定。

第一次不要让 Codex “帮我优化整个项目”。先让它只读不改：

先不要修改任何文件。请阅读当前项目，告诉我：
1. 这个项目是做什么的；
2. 前端、后端、数据文件分别在哪里；
3. 启动命令是什么；
4. 最容易出问题的地方有哪些；
5. 你建议我下一步先改哪 3 个小任务。

这一步的价值是建立共同上下文。Codex 会看目录、配置、脚本、README，然后给你项目地图。你要把它的总结当成“入场检查”，不是最终结论。如果它误解了项目，你要立刻纠正。

第二步再让它做一个很小的改动，例如改按钮文案、补一个 README 段落、修一个明显报错。提示词要写清楚范围：

请只修改首页标题和描述，不要改路由、接口和样式结构。修改后告诉我改了哪些文件，并给出本地检查命令。

验收时看三样：它改了哪些文件；是否超出范围；是否给出可运行的验证命令。小白不要只看“它说完成了”，要看 Git diff。

很多人下载 GitHub 项目后卡住，不知道从哪里开始。Codex 的一个高价值用法就是“项目导游”。把项目拉下来后，进入根目录：

git clone <项目地址>
cd <项目目录>
codex

然后输入：

请用小白能听懂的话解释这个项目。重点说明：
- 项目解决什么问题；
- 主要技术栈；
- 入口文件；
- 配置文件；
- 数据存放位置；
- 本地启动步骤；
- 部署前必须改哪些配置。
先不要修改文件。

如果你要把 GitHub 源码包装成自己的产品，这一步尤其重要。不要急着改 UI，先搞清楚授权、环境变量、数据库、登录、支付、部署方式。否则你会出现“首页能跑，核心功能全挂”的情况。

进阶提示词：

请把这个项目拆成 10 个适合小白理解的模块，每个模块说明：作用、关键文件、能不能删、常见改法、风险等级。输出成 Markdown 表格。

这段内容可以直接变成你网站里的“源码讲解”付费内容。

Codex 能改代码，但你要控制节奏。推荐流程是“一次一个任务、一次一个提交、每次都能回滚”。

标准提示词：

任务：给百科详情页增加一个“相关指南”区域。
范围：只允许修改前端详情页组件和必要的样式文件。
要求：
1. 如果没有相关指南数据，不显示空标题；
2. 不影响原有 relatedWiki；
3. 修改后运行现有构建或检查命令；
4. 最后列出修改文件和测试结果。

不要写：

帮我把项目优化一下。

这个提示太空，Codex 会自己猜，结果可能改路由、改样式、改数据结构，最后你不知道哪里坏了。

每次改完后执行：

git diff
git status

如果你满意，再提交：

git add .
git commit -m "feat: add related guide section"

如果不满意，回滚：

git restore <文件名>
# 或者放弃所有未提交修改
git restore .

付费技巧：要求 Codex 先输出“修改计划”，你确认后再动手。提示词可以写：

先给计划，不要修改文件。计划里必须列出预计修改文件、风险点、验证命令。等我回复“开始改”后再执行。

真正能卖钱的 AI 编程，不是“生成代码”，而是“生成后能跑”。每次让 Codex 修改功能，都要让它跑测试或构建。

常用检查命令：

npm run lint
npm run test
npm run build
npm run dev

如果项目没有这些脚本，让 Codex 先读 `package.json`：

请检查 package.json，告诉我这个项目有哪些可用脚本，哪个用于本地启动，哪个用于构建，哪个用于测试。先不要运行会修改数据的命令。

报错时不要只复制最后一行。给 Codex 完整上下文：执行了什么命令、完整报错、你期望什么、实际发生什么、最近改过哪些文件。

调试提示词：

我执行 npm run build 报错如下。请先判断是语法错误、类型错误、依赖错误、环境变量错误还是构建配置错误。不要直接大改，先指出最可能的 3 个原因和最小修复方案。

<粘贴完整报错>

让 Codex 修 bug 时，要求它解释“为什么这样修”。否则它可能只是把报错隐藏掉，例如用 `any` 跳过类型，或者把失败测试删掉。这种修法短期能过，长期会埋雷。

Codex 改完代码后，可以再开一个审查任务，让它站在审查者角度检查。重点不是让它夸自己，而是让它找风险。

代码审查提示词：

请审查当前未提交改动。重点检查：
1. 有没有超出需求范围；
2. 有没有破坏现有功能；
3. 有没有安全问题；
4. 有没有硬编码、重复代码、错误处理缺失；
5. 有没有需要补测试的地方。
请按“必须修 / 建议修 / 可以不管”分组输出。

如果你在做付费内容或客户项目，建议把“审查报告”作为交付物之一。客户不只要你说“做好了”，还要知道你怎么保证没乱改。

更稳的流程是：ChatGPT 写需求，Codex 改代码，Claude Code 或另一个 Codex 做审查。三者不要混成一个窗口。一个窗口负责需求，一个窗口负责施工，一个窗口负责验收，质量会明显更稳定。

不会 Git，就不要让 AI 大规模改项目。最低要求是会看状态、看差异、提交、回滚。

每次开始前：

git status

如果有未提交改动，先处理掉。不要在一堆脏文件上让 Codex 开始改，否则出了问题很难回退。

推荐分支流程：

git checkout -b ai/add-wiki-guide-links
codex
# 让 Codex 完成任务后
git diff
git add .
git commit -m "feat: add wiki guide links"

如果项目被改坏：

git restore .

如果已经提交但想撤回：

git log --oneline
# 找到上一个安全提交后
# 谨慎使用：会丢弃之后提交
git reset --hard <commit-id>

付费交付建议：每个任务一个分支，每个分支一个明确提交信息。这样你可以把“AI 做了什么”讲清楚，也方便 Codex 或 Claude Code 后续继续接手。

MCP 可以理解成“给 AI 接工具的标准插座”。Codex 支持通过 MCP 连接第三方文档、浏览器、Figma 等工具。不是所有人一开始都需要 MCP，但当你反复让 Codex 查同一类资料、操作同一类工具时，就值得配置。

官方文档说明，Codex 的 MCP 配置默认放在 `~/.codex/config.toml`，也可以在可信项目里放 `.codex/config.toml`。可以通过命令添加 MCP server，例如：

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

进入 Codex 后可用：

/mcp

查看已连接服务。

小白不要一开始就堆十几个 MCP。先问自己三件事：这个工具是不是经常用？它会不会拿到敏感数据？出了错能不能撤回？

推荐优先级：文档类 MCP 优先，设计稿类其次，能操作线上系统的 MCP 最后。凡是能删数据、发消息、改生产配置的工具，都必须加人工确认。

Codex 适合做批量但规则明确的任务，例如：补 50 个页面的 meta description、给 20 个 Markdown 文件统一加目录、把 JSON 字段统一改名、给每个 API 增加错误处理。

批量任务的关键是先做样板。不要直接说“把所有页面都改了”。正确流程是：先改 1 个文件，验收；再改 5 个文件，验收；最后批量改。

提示词：

请先只处理 1 个样板文件，不要批量修改。目标是把指南章节里的“空章节”替换为完整正文。完成后列出你采用的结构，我确认后再处理其余文件。

批量修改前，要求 Codex 输出影响范围：

在修改前，请先列出将被修改的文件清单、每类修改规则、可能风险、回滚方式。不要立即执行。

适合自动化的任务有：格式整理、字段补全、文案统一、测试补齐、文档生成。不适合自动化的任务有：价格策略、合同条款、数据库删除、支付逻辑上线、生产密钥轮换。

最省钱、最稳定的分工是：ChatGPT 做产品经理，Codex 做程序员，Claude Code 做复杂代码协作和长上下文审查。

ChatGPT 适合：需求拆解、商业模式、页面文案、提示词、百科词条、操作手册。它不直接碰项目文件，适合把混乱想法整理成清晰任务。

Codex 适合：在本地项目里按任务改代码、跑测试、解释项目结构、生成补丁。它的强项是“动手”。

Claude Code 适合：长时间理解项目、持续协作、复杂重构、团队式开发流程。它也能动手，但你要给它明确边界。

推荐流水线：

1. ChatGPT：把想法整理成任务单。
2. Codex：按任务单修改项目。
3. Claude Code：审查改动，找遗漏。
4. Codex：按审查意见修复。
5. ChatGPT：把完成情况写成给用户看的更新记录。

这样做的好处是每个 AI 都有角色，不会互相抢活。你作为老板，只负责定目标、验收、决定是否上线。