Codex 实战使用手册

简体中文版本。本手册根据 OpenAI 官方文档中与 Codex 使用有关的链接页面重新编写，并按真实任务流程组织。内容不是逐页复制，而是加入可直接调整和使用的命令、配置、提示词、审查及排错示例。

Codex 任务流程：检查、规划、实施、验证 — 适合代码仓库任务重复使用的四阶段工作流。

1. 选择合适的 Codex 使用界面

界面	适合工作	开始方式
ChatGPT 桌面应用	规划、审阅修改、并行对话、浏览器测试、长时间任务	打开项目或文件夹，再创建 Codex 对话
Codex CLI	终端优先的代码工作、本地检查及自动化	`codex`
IDE 扩展	利用已打开文件和选区进行精确修改	在编辑器中打开 Codex 面板
Codex 云端	在隔离的托管环境委派任务	连接代码仓库并配置环境

2. 快速开始

打开真正的代码仓库，不要选择范围过大的上级目录。
先让 Codex 检查现状，再进行修改。
说明期望结果，以及完成时必须提供的验证证据。
最后检查差异并运行相关测试。

CLI 示例

# 安装后进入项目并启动
npm install -g @openai/codex
cd ~/projects/example-app
codex

# 常用交互命令
/init
/status
/permissions
/model
/review

3. 编写能够完成的提示词

稳定的任务说明应包含四部分：目标、相关背景、限制条件和可验证的完成标准。路径、错误日志、截图、复现步骤或失败测试都能减少误解。

过于含糊

修复设置页面。

可执行版本

目标：修复个人资料表单，让已保存的显示名称在页面刷新后仍然保留。

背景：
- 界面：src/pages/Profile.tsx
- API：src/api/profile.ts
- 复现：保存名称后刷新，旧名称再次出现

限制：
- 保持现有 API 契约
- 不增加状态管理依赖
- 不覆盖与本任务无关的修改

完成标准：
- 复现步骤不再失败
- 相关测试通过
- 说明根本原因和已修改文件

只要求规划

检查登录流程并提出简短实施方案。现在不要修改文件。
列出假设、风险、可能涉及的数据迁移，以及证明结果所需的测试。
等我确认后再开始实施。

4. 采用“检查 → 规划 → 实施 → 验证”

检查：找到入口、现有约定、测试和未提交修改。
规划：把高风险或跨文件工作拆成可验证步骤。
实施：完成最小而完整的修改，同时保留其他人的工作。
验证：运行针对性测试、查看真实页面或输出，并审阅差异。

先运行最小范围的相关测试；通过后再运行更完整的测试套件。
界面修改必须打开实际流程，检查可见内容和交互，不能只确认 HTTP 200。
若有测试无法执行，请说明原因。

5. 使用 AGENTS.md 保存仓库规则

AGENTS.md 适合保存需要长期重复遵守的指引，例如构建和测试命令、目录职责、格式要求及交付标准。内容应简短、明确并可执行；子目录可以用更具体的文件细化上层规则。

# 代码仓库指引

## 命令
- 安装：npm ci
- 单元测试：npm test
- 界面测试：npm run test:e2e
- 代码检查：npm run lint

## 工作规则
- 保留请求范围之外的用户修改。
- 沿用 src/styles/tokens.css 中的设计变量。
- 每个错误修复都要增加或更新回归测试。
- 交付时列出修改文件和实际运行过的命令。

6. 模型、审批和沙箱配置

Codex 只能在当前会话允许的范围内读取、编辑和运行命令。优先采用能完成任务的最小权限；只有在安装依赖、访问外部服务等具体需要下才扩大权限。

# .codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

审批请求示例

需要联网下载此项目锁定的依赖包。
允许命令：npm ci
范围：仅限这个代码仓库
完成后：运行单元测试并报告结果。

7. Skills、插件和 MCP

扩展方式	使用时机	典型内容
Skill	把工作流变成可复用的专业能力	`SKILL.md`、参考资料、脚本、素材
插件	把多项能力组合成可安装的软件包	Skills、工具、命令、MCP、应用
MCP	需要经过授权的实时数据或外部操作	服务器连接和工具定义

最小 Skill 示例

release-check/
└── SKILL.md

---
name: release-check
description: 部署前验证网站版本。
---

# 版本检查
1. 运行单元和集成测试。
2. 构建生产版本。
3. 使用浏览器检查主要用户流程。
4. 报告阻塞项；未收到明确要求时不得部署。

MCP 配置示例

[mcp_servers.docs]
command = "npx"
args = ["-y", "@example/docs-mcp"]

[mcp_servers.docs.env]
DOCS_SPACE = "engineering"

8. CLI 和非交互模式

一次性任务

codex exec "检查失败的结账测试，修复最小根本原因，运行相关测试并总结差异。"

可供 CI 读取的输出

codex exec --json \
  "审阅当前修改的正确性和安全风险；不要编辑文件。" \
  > codex-review.jsonl

恢复最近会话

codex resume --last

自动化任务必须明确工作目录、允许的动作、输出格式和失败处理；不要假设无人值守任务可以获得宽泛权限。

9. IDE、桌面端、浏览器和云端示例

IDE 精确修改

根据当前选中的函数和相关测试，移除重复网络请求。
保持公开函数签名；修改调用方之前先展示建议差异。

浏览器验证

打开本地管理页面，使用开发账号登录，再进入工具编辑器。
确认四张富文本卡片都已加载，并检查标题、可编辑内容、图片控件及控制台错误。
HTTP 200 不能证明页面已经正确工作。

云端委派

在隔离的云端环境中更新依赖并运行完整测试。
不要发布或合并；返回补丁、兼容性说明和测试证据。

10. 把代码审查作为独立任务

审阅相对于 main 的修改。
优先检查正确性、安全、数据丢失和回归风险。
每项发现包括严重程度、文件与行号、失败场景和简短修复方向。
如果没有发现问题，也要列出尚未覆盖的测试风险。

11. Worktree、并行对话和长时间任务

Git worktree 让每项并行工作拥有独立的代码副本，同时共享 Git 元数据。当两项任务可能修改相同文件或需要独立分支时使用 worktree；如果必须立即看到本地未提交修改，则使用本地对话。

Worktree A	Worktree B	本地目录
升级 API 客户端及测试	改进界面错误状态	整合、处理冲突并运行端到端测试

目标：分三个检查点迁移测试套件。
检查点 1：盘点范围和风险。
检查点 2：迁移一个代表模块并验证。
检查点 3：完成其他模块并运行完整测试。
每个检查点后报告进度和阻塞；不要部署。

12. 远程和定时任务

远程功能适合离开原电脑后继续工作；定时任务适合可重复、可观察的周期性检查。两者都不会自动扩大授权范围。

每个工作日上午 09:00 检查此代码仓库的依赖警报。
生成简短报告，包含软件包、严重程度、受影响版本和建议行动。
不要安装软件包、创建拉取请求或向外部用户发送消息。

13. 排错清单

确认当前项目和工作目录。
查看页面错误、终端输出及相关日志。
运行 /status，检查模型、审批和沙箱状态。
分别验证登录、账号／工作区权限和 API 密钥。
插件或 MCP 故障时，检查安装、启用、授权、配置、重启要求和工作区策略。
界面卡住时检查实际页面和浏览器控制台，不能只看状态码。
先用最小任务复现，再考虑扩大权限或修改全局配置。

只进行诊断，不要修改文件。
复现问题、记录准确的失败步骤、检查最近的日志和配置，
并用证据指出最可能的根本原因。明确区分已确认事实和假设。

14. 官方资料来源

本手册使用了 OpenAI 官方的完整文档索引，并逐页整理最佳实践、CLI、IDE、桌面应用、云端、审批与安全、AGENTS.md、Skills、插件、MCP、代码审查、Worktree、非交互模式、浏览器、定时任务和排错等页面。

编辑日期：2026 年 8 月 11 日。对版本敏感的命令、模型名称、可用范围或政策，使用前应重新核对官方页面。