Codex 使用教程：从首次任务到修改代码、测试与交付（2026）

Codex 使用教程应从一个能验收的小任务开始：打开正确的项目，让它先理解代码，再限定范围修改，最后检查差异并运行测试。安装成功只是起点，能说明改了什么、为什么改、怎样验证，才算完成一次开发任务。本文提供一条新手阅读路线，不要求你一开始就掌握 API、MCP 或自动化。

整理需求和解释公开代码时，可以使用 AIMirror GPT 中文站，也可通过 AICNBox 中文 AI 入口 比较表达。这些是第三方网页服务，不等于 Codex 官方客户端，也不自动具备本地仓库权限；真正改文件和跑测试，需要在具备相应工具的项目环境中完成。

更新日期：2026 年 10 月 24 日。本文命令用本机 Codex CLI 帮助核对，版本为 0.163.0-alpha.11，不代表所有稳定版。官方文档本次访问受限，套餐、模型和界面入口以账号及官方实时页面为准；下文案例是练习方案，不是性能评测。¹

一、Codex 使用教程的正确阅读顺序

初学者先完成一次“读项目—小修改—验收”，再决定是否深入配置。把安装、模型选择、工具连接和业务开发同时推进，出错时很难分清是哪一层的问题。已经装好的人可以直接从第三节开始，不必重新安装。

这些页面各自解决一个问题。总教程负责帮助你走完开发流程，不把每种安装命令和配置字段都抄一遍；遇到具体问题再进入专题，返回后继续当前任务。

二、先选工作位置，而不是先追模型名称

桌面入口适合集中管理项目和对话，IDE 扩展适合边读代码边修改，CLI 适合终端操作与脚本化任务。云端任务还涉及远程仓库、运行环境和依赖，不应默认能看到你电脑上尚未提交的文件。具体客户端支持范围需要分别核对。

选择时看你每天在哪里工作，以及工具能否访问任务所需的材料。不要为了试新入口反复移动同一个项目；先在一个入口跑通练习，再比较是否需要换。聊天模型显示出相同名称，也不能证明文件访问、测试执行和授权机制完全一致。

没有编程基础也能从解释项目和整理文档开始，但应理解文件、目录、命令和版本控制的基本含义。暂时看不懂差异时，先让工具解释，不要直接同意发布；涉及数据库、登录、支付或生产配置的任务应交给有经验的人复核。

三、准备一个边界清楚的练习项目

优先选自己可公开的练习仓库，确认能手动启动它。先读 README 和已有脚本，记录正确的构建、测试与启动命令；这些命令来自项目，不应凭语言名称猜测。依赖装不上时，先解决环境问题，不要要求模型通过删除测试来“修好”。

在 Git 仓库中，可以先执行以下只读检查。它们不会替你提交文件，目的只是确认所在目录和已有差异；看到陌生修改时，应先辨认归属，避免把别人的工作覆盖掉。

git status --short
git branch --show-current
git diff --stat

按团队约定建立任务分支或保存检查点。不要把“先清理工作区”理解为删除所有未提交内容；测试素材也可能属于用户。项目文件夹不应包含私钥、生产环境变量或客户数据，演示用占位内容足够验证流程。

四、第一条任务先只读，确认它理解的是同一个项目

初次打开仓库，先要求 Codex 解释入口、依赖和测试位置，而不是立刻重构。看它能否指出具体文件，以及是否区分“从文件中读到”与“推测”；这种检查能尽早发现打开错目录、依赖缺失和上下文不完整。

先只读分析当前项目，不修改文件，不安装依赖。
请说明项目用途、主要入口、已有测试和启动方式。
每个判断注明对应文件；没有证据的地方标为待确认。
最后建议一个适合新手的小任务，并说明验收办法。

核对它引用的文件是否存在，再打开其中一两个位置检查。回答很长却没有路径、把不存在的命令写成现成脚本，说明还不能开始实施。用具体纠正补齐信息即可，不必让它重新“全面理解”整个代码库。

五、把需求写成目标、范围、限制与验收

适合入门的任务包括修复一处文案、补一个输入边界测试、调整一个按钮状态。任务越清楚，越容易判断改动是否必要；“优化整个网站”没有范围，也没有停止条件，通常不适合作为第一步。

下面是一个示例需求，实际文件名和命令要从自己的项目中取得。先让 Codex 提出最小方案，确认涉及的组件后再执行；没有确认的额外改造留到下一次任务。

目标：表单提交时，对空白用户名显示明确错误提示。
范围：只修改用户名校验及相关测试。
限制：不新增依赖，不改变其他字段，不修改接口协议。
验收：空字符串和纯空格会报错，合法输入仍可提交。
先说明计划与受影响文件，确认后再修改。
完成后列出测试命令、结果和未验证项。

别把诊断请求和修改请求混在一起。只想知道原因时，写明“解释但不实施”；确实要修复时，再授权修改。提交、推送、部署也应单独表达，防止工具把本地完成误当成可以发布。

六、执行期间用差异判断进展

Codex 开始改动后，关注文件范围是否扩张，是否引入新依赖，以及是否顺手改了无关格式。一个按钮问题导致整个组件库被重写，需要停下来问清必要性；修复应能对应到具体原因，而不是单纯增加代码量。

每完成一个阶段，检查 git diff --stat，再阅读 git diff。未跟踪的新文件不会直接显示在普通差异中，因此还要查看 git status --short；测试、资源和配置是否被意外新增，都在这一层确认。

反馈应指向可观察问题，例如“只保留空格校验，不改按钮颜色”。不要同时要求改排版、换框架和优化性能，否则难以区分哪项变化导致回归。需要回退时优先撤销本次明确的改动，保留原本已有的用户修改。

七、测试通过与任务完成不是同一句话

先跑最相关的测试，再运行项目约定的构建或检查。对于界面变化，还需实际打开页面，检查桌面与手机的可读性，以及必要的明暗主题。编译成功不能证明交互正确，截图看起来正常也不能证明提交逻辑正确。

让 Codex 按“命令、结果、覆盖范围、未验证项”汇报。测试没有执行、因网络失败、或者执行后有错误，必须分别标注；不能把它们合并成一句“应该没问题”。没有现成测试时，至少给出可重复的手工步骤与预期结果。

发现失败先判断是否由本次修改引起。项目原来就有的错误应保留记录，不能为让检查全绿而删除断言或跳过失败模块；必要时缩小任务，先交付能证明正确的部分，再单独处理历史问题。

八、Git 提交与上线前的最后一道检查

验收也要包含没有变化的部分。例如只修改用户名校验，就应再确认密码、提交按钮和原有接口仍然正常；只补文档，就核对命令能在指定目录执行。这样做不是扩大开发范围，而是证明修复没有破坏相邻行为。发现额外问题时，单独记录影响和复现步骤，交给下一次任务处理，不要顺手把当前补丁扩成一次全面整顿。

准备交付时再次检查状态，按具体路径选择要提交的文件。不要习惯性使用全量暂存，把临时日志、凭证或他人的修改带进同一提交；提交说明应能回答这次做了什么，而不是只写“更新”。

推送前核对分支、远程地址和团队流程。上线需要额外确认构建产物、部署状态与真实页面；推送成功只说明代码到了远程仓库，不说明自动部署已经成功。用户要求线上链接时，应打开实际地址验证，而不是仅拼接预期路径。

交付记录保留目标、改动摘要、测试结果、提交标识和已知限制。下一次遇到同类任务，可以沿用记录格式，而不是复制整个聊天历史；这比反复粘贴长提示词更容易审计。

九、新手常见问题

保留一份脱敏的验收记录，下一次复核时即可对照。

Codex 和普通代码问答有什么区别？

区别主要在工作环境和工具权限。普通问答常给出代码建议，具备仓库工具的 Codex 环境可以在授权范围内读取文件、实施修改并运行命令；能力仍受客户端、环境和审批约束，不代表可以随意操作整台电脑。

为什么同一句提示词，换个项目结果就不同？

依赖、规则、目录结构和已有代码都会影响结果。复用提示词时，应重新确认文件范围和验收标准；不要把另一个项目的测试命令、框架约定和发布地址直接带过来。

要先学 API、Skills 和 MCP 吗？

不必。先用当前工具完成小任务，明确哪种重复工作值得复用；长期项目规则放进 AGENTS.md，多步骤流程再考虑 Skills，外部工具连接另行评估。每增加一个工具，都应知道它读什么数据、具有什么权限。

十、下一步按问题深入，不重复安装

先完成一个小任务，再阅读 CLI 实操 或 VS Code 协作。经常重复约束时，继续看 项目规则与提示词教程；需要第三方路由时，再看 API 接入专题。

需求草稿也可先在 AIMirror GPT 中文站 中整理，随后回到真实项目验收。Codex 使用教程最值得记住的是工作顺序：先确认上下文，再控制改动，最后用证据交付。