Codex 中文使用手册

Codex 不只是一个终端命令。它可以在 ChatGPT 桌面 App、CLI、IDE 扩展和 Cloud 环境中理解项目、修改代码、运行命令并审查结果。本手册先帮你选对入口，再完成一条可验证的真实开发流程。

SuperToken 中文整理版 · 核对日期 2026-07-15 · 当前模型 GPT-5.6 · 实测 CLI 0.144.3 · 非 OpenAI 官方译本

阅读边界

产品能力以当前 OpenAI Codex 官方文档 和你的账号界面为准。界面、模型和实验功能可能分批开放；手册不会把未验证能力写成所有账号都能使用。

当前模型基线

当前推荐系列是 GPT-5.6：默认 Power 使用 5.6 Sol，Terra 面向日常工作，Luna 面向清晰、重复和高吞吐任务。ChatGPT 登录场景中的 gpt-5.2 与 gpt-5.3-codex 已弃用；模型选择与迁移细节见 桌面 App 完整操作。

先选对入口

入口	最适合	你会直接接触什么	不适合
ChatGPT 桌面 App 中的 Codex	同时管理多个任务、可视化审查 diff、使用集成终端和 Worktree	项目侧栏、任务、Review、终端、Local / Worktree / Cloud	纯脚本流水线
Codex CLI	终端优先、本地仓库、可复现命令和非交互任务	当前目录、终端会话、sandbox、approval、JSONL 输出	依赖大量鼠标操作的界面工作
IDE 扩展	围绕当前选区、文件和编辑器上下文快速迭代	Codex 侧栏、选中代码、当前文件、编辑器 diff	大量并行后台任务
Cloud	让任务在已配置的远程环境中执行	云端仓库快照、setup、网络策略和远程结果	必须依赖未上传本地文件或本机进程的任务

最简单的选择规则：

• 第一次使用，想看清过程：从 桌面 App + Local 开始。
• 已经习惯终端：从 CLI + workspace-write 开始。
• 问题只涉及当前文件或选区：使用 IDE 扩展。
• 想并行处理独立任务，且远程环境已经配好：使用 Worktree 或 Cloud。

Subagents 是跨入口的并行能力

当前 Codex 在桌面 App、CLI 和 IDE 扩展中都可以运行 subagent workflow。它不是第五个独立入口，而是由主任务把边界清楚的工作分给多个 agent thread，再汇总结果。

• 最适合并行：代码库探索、测试、日志分析、按维度审查和资料汇总。
• 谨慎并行：多个 agent 同时修改相同文件，容易产生覆盖、冲突和额外协调成本。
• 子代理继承父任务当前权限；非交互任务无法弹出新审批时，需要额外权限的动作会失败并回报主任务。
• 每个子代理都会单独使用模型和工具，因此通常比单代理消耗更多 Token。
• CLI 用 /agent 或 /subagents 查看和切换 agent thread；App 与 IDE 在当前界面提供子代理活动入口时，也应逐个检查结果。

10 分钟完成第一次任务

这条最短路径使用一个你熟悉、可以运行测试的 Git 仓库。第一次不要拿生产密钥仓库、个人主目录或尚未备份的项目练习。

1. 确认工作区

在终端进入项目并检查当前状态：

cd /path/to/your-project
git status --short --branch

预期结果：你能说清当前分支和已有未提交修改。已有修改不用清空，但必须知道哪些不是本次任务产生的。

2. 打开 Codex

桌面 App：打开 ChatGPT 桌面 App，在产品下拉框选择 Codex，用 Cmd/Ctrl + O 打开项目，运行位置选择 Local。

CLI：

codex -C /path/to/your-project

预期结果：任务明确绑定到正确目录。若界面显示的项目或 CLI 当前目录不对，先退出并修正，不要靠提示词补救错误工作区。

3. 先做只读调查

输入：

先不要修改文件。请检查这个项目并告诉我：
1. 它解决什么问题，主要入口在哪里；
2. 安装、开发、测试和构建命令分别来自哪个文件；
3. 当前 Git 状态中哪些改动已经存在；
4. 如果只改 README 中的一处错别字，最小验证方法是什么。

不要读取或输出 .env、密钥和账号信息。结论尽量引用具体文件。

预期结果：Codex 只读文件和仓库状态，没有产生 diff；命令来自 package.json、任务文件或项目文档，而不是凭空猜测。

4. 做一个最小修改

确认调查结果无误后再输入：

只修复 README 中刚才指出的那一处错别字。
不要改写段落，不调整格式，不修改其他文件。
完成后显示 diff，并运行最小验证；最后说明实际执行了什么。

审批时只允许与当前任务匹配的文件写入和命令。陌生命令、仓库外路径、网络访问或凭据读取都应先拒绝并追问原因。

5. 用证据验收

至少完成四项检查：

1. Review 面板或 git diff -- README.md 只显示目标改动。
2. git status --short 没有意外文件。
3. Codex 报告的验证命令确实执行成功，而不是只建议你运行。
4. 原有未提交改动没有被覆盖、还原或混入本次结果。

这才算任务完成。模型说“已经修复”本身不是证据。

第一次不要这样做

• 不要从主目录、下载目录或包含多个项目的上级目录启动。
• 不要把 danger-full-access 或危险绕过审批作为默认配置。
• 不要把真实 Key、.env 内容、客户数据或私人会话贴进提示词。
• 不要让 Codex 在没有复现问题时连续试错式修改生产代码。
• 不要在没看 diff、没跑验证时直接提交或推送。
• 不要把 Worktree 当成数据库、端口、云账号或外部服务的隔离层。

手册怎么读

你的目标	阅读
在桌面 App 完成打开项目、修改、Review 和验证	桌面 App 完整操作
掌握交互式 CLI、图片输入、恢复会话和自动化	CLI 使用
在编辑器中工作，或把任务交给 Cloud	IDE 与 Cloud
配置 AGENTS.md、权限、MCP、Skills、Plugins 和 Hooks	项目与团队定制
跟着完整案例练习 Bug、功能、重构、审查和前端验收	项目实战
遇到目录、认证、权限、网络、MCP 或 Worktree 问题	故障排除与速查

一条成熟的日常工作流

1. 定界： 确认仓库、分支、已有修改、数据和权限范围。
2. 调查： 先读入口、相似实现、测试和项目规则。
3. 计划： 写清方案、改动文件、失败状态和验证命令。
4. 实现： 做最小纵向闭环，避免顺手重构和升级依赖。
5. 审查： 检查完整 diff，而不是只看最终回答。
6. 验证： 运行测试、类型检查、lint、构建或人工界面检查。
7. 交付： 列出改动、证据、未验证项和剩余风险。
8. 沉淀： 把稳定约定放进 AGENTS.md、配置或复用流程，不把临时对话当长期规则。

产品边界速记

• Codex 可以操作文件和命令，但实际范围由工作区、sandbox、approval、组织策略和外部系统权限共同决定。
• CLI、IDE 和桌面 App 共享一部分 config.toml 行为；编辑器外观和 chatgpt.* 设置属于 IDE 自己。
• Local 与 Worktree 都在本机运行；Cloud 使用远程环境，不会自动拥有本机未提交文件、进程或凭据。
• Review 面板展示的是 Git 仓库状态，其中可能同时包含你、Codex 和其他工具产生的修改。
• Worktree 隔离 Git 文件和分支，不隔离数据库、端口、缓存、浏览器登录或云资源。
• Subagents 适合并行读和独立验证，不是并行写同一工作区的默认方案；委派前先划分文件所有权和完成标准。

官方资料

• Models
• Codex environments
• Desktop app commands
• CLI options
• IDE settings
• Approvals and security