CODEXGUIDE / 任务入口
快速上手
先用 8 篇入门文章建立正确认识，再选择与你当前目标相符的短流程，边做边建立可靠的工作习惯。
按任务开始
3 条短流程基础15 分钟
首次安装、登录并打开项目
用最少的配置完成第一次 Codex 本地启动，确认账号、工作目录和 Git 状态都可用。
- 从 OpenAI Codex 官方入口选择 App、CLI 或 IDE extension，并按当前系统完成安装。
- 使用 ChatGPT 账号或 API Key 登录；不要把 token、auth.json 或 .env 提交到仓库。
- 打开一个范围清楚、可以回退的项目目录，先运行 git status --short --branch。
- 让 Codex 只读 README、依赖文件和测试目录，先回报项目用途、启动命令和未知信息。
验收：你能说明当前项目、当前分支、启动命令和第一项可回滚任务，且工作区没有意外修改。
查看 OpenAI 官方参考 ↗入门实践30 分钟
完成一个可回滚的真实任务
从清晰目标开始，经过读取上下文、最小修改、验证和 diff 审查，走完一次完整闭环。
- 选择一个十几分钟到一小时内能验收的小任务，例如修复可复现的 Bug、补一条测试或更新一段文档。
- 写清 Goal、Context、Constraints 和 Done when，指定允许修改的目录与禁止触碰的内容。
- 让 Codex 先调查并提出计划，再执行最小范围的修改；中途检查 diff，不把多个结果混在一个任务里。
- 运行与任务对应的测试、构建或页面检查，记录成功、失败和无法验证的部分。
- 审查 git diff 与 git status，确认没有敏感文件或无关重构，再提交或回滚。
验收：任务有可复现的完成标准，验证命令有输出，diff 只包含目标改动，并且能在需要时恢复到起点。
查看 OpenAI 官方参考 ↗故障排查20 分钟
排查权限、Git 或验证失败
遇到批准弹窗、工作区冲突、命令失败或测试不稳定时，按证据定位问题，不靠重复重试。
- 先保存失败命令、完整错误、当前路径和 git status，不要先删除缓存或覆盖现有修改。
- 检查请求是否越过工作区、是否需要网络，以及命令会读写哪些文件；高风险操作使用 Ask for approval。
- 确认失败属于环境基线、权限策略、依赖缺失、Git 冲突还是本次代码修改，并逐项隔离。
- 用最小复现重新运行验证；若仍失败，记录已验证的范围和不能验证的原因。
- 检查 diff、依赖锁文件和配置，避免用 Full access 或大范围重构掩盖根因。
验收：你能把失败归类到明确原因，提供一条可复现命令和下一步动作，而不是只报告“Codex 已完成”。
查看 OpenAI 官方参考 ↗