刘寅生律师在实际的编程工作流里，Codex 代表的是一类变化：从“AI 自动补全代码”变成“AI 在自己的项目里自主完成一段任务”。你给它一个目标，它能读取项目文件、修改代码、运行测试、查看输出，再根据结果调整做法。很多第一次接触 Codex 的人，会把它当成 ChatGPT 的代码版，希望它直接给出一段完整答案；真正用起来之后又会发现，它更像一位需要你提供背景、检查它每一步的实习生。
这篇教程围绕一条学习主线展开：先理解 Codex 是什么，然后完成环境准备、安装登录、跑通第一个任务、掌握进阶用法，最后形成一套可复用的排查和最佳实践清单。文中所有命令和配置都给出最小可运行版本，涉及版本号和字段名的地方，以你实际安装的版本为准。
这里先把结论放在前面：Codex 当前提供的是比较完整的“编码智能体”工作方式。CLI、配置文件和项目指令的配合，决定了它到底是在你的项目里真正干活，还是只在聊天窗口里输出建议。掌握 Codex 的过程，本质上就是掌握“如何给 AI 设定好边界、反馈和验收标准”的过程。
1. 先理解：Codex 是 AI 智能体，不是 AI 补全插件
1.1 Codex 和传统代码补全工具的核心差异
传统代码补全工具的核心动作是“补全”。光标停在一个函数名后面，工具根据上下文预测下一个 token，把代码片段补出来。它处理的是局部问题，很少主动打开多个文件去判断一段改动会不会破坏其他模块。
Codex 的核心动作是“执行任务”。它不是等你逐行写代码，而是接收一个目标描述，比如“把导出功能改成异步执行，并且保留原有的错误提示”，然后自主决定要打开哪些文件、修改哪些位置、运行什么命令来验证。
两者可以这样对比：
| 对比维度 | 传统补全工具 | Codex 这类编码智能体 |
|---|---|---|
| 交互方式 | 跟随光标逐行补全 | 对话式任务描述 |
| 上下文范围 | 当前文件、当前窗口 | 项目目录、多文件、命令行输出 |
| 执行能力 | 只产出代码片段 | 可以修改文件、运行命令、读取结果 |
| 失败处理 | 不断提供候选 | 根据失败信息自我修正再执行 |
| 适用场景 | 写单行逻辑、快速补括号 | 重构、修 bug、写测试、搭建功能 |
这里有一个容易误解的地方：Codex 不会替代你的判断力。它执行任务的速度很快，但它对“任务本身是否正确”没有判断能力。所以使用 Codex 时，最重要的功课不是写提示词，而是定义验收标准。
1.2 Codex 的工作链路：读文件、改代码、跑命令、看结果
Codex 在执行任务时，通常在一条循环里工作：
- 读取任务描述。
- 扫描项目目录，找到相关文件。
- 读取文件内容，理解现有实现。
- 修改代码或创建新文件。
- 运行命令，比如单测、构建脚本、静态检查。
- 读取命令输出，判断是否成功。
- 如果失败，调整方案继续执行，直到满足停止条件。
这个链路与现代 IDE 插件有根本区别。IDE 插件通常把 AI 放在侧边栏，建议你“把这段代码改成下面这样”；Codex 是直接进入你的项目目录，通过 CLI 发起操作。所以项目结构、文件命名、依赖安装状态、测试用例是否存在，都会直接影响它的表现。
理解这条链路之后，你就能明白很多常见问题的根因。比如 Codex 没找到文件，往往不是你提示词不够好，而是你让它在一个错误的目录下执行；比如它改了代码但测试仍然失败，可能是测试本身就不可靠，也可能是它在修改之前没有跑过一次基线测试。
1.3 一天从入门到进阶的学习路径
这篇教程按实际使用顺序组织，建议按顺序执行，不要跳过环境检查：
- 掌握概念：知道 Codex 是智能体，理解它的工作链路。
- 准备环境：装好 Node.js、npm，准备好账号授权。
- 完成安装：安装 CLI，登录，验证版本。
- 跑通第一个任务：在一个最小项目里让它完成一次真实修改。
- 学习进阶用法：项目指令、MCP、IDE 集成、审查流程。
- 建立排查能力：遇到报错时，知道先看日志还是先看配置。
- 形成工程规范：把 Codex 放进团队开发流程而不是个人实验。
一天时间足够完成前六步。最后一步需要你在真实项目里持续使用一段时间后才能固化下来。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：安装前先确认这三件事
2.1 本机环境清单
在安装 Codex CLI 之前，先确认以下基础环境：
| 检查项 | 推荐要求 | 说明 |
|---|---|---|
| 操作系统 | macOS / Linux / Windows | Windows 建议使用 WSL 终端，路径和权限更接近主流开发环境 |
| Node.js | 18 或更高版本 | 版本过低会导致部分命令不可用 |
| npm | 随 Node.js 安装 | 用于从 registry 安装 CLI |
| Git | 任一稳定版本 | Codex 的很多操作依赖 git 仓库识别改动 |
| 终端 | 支持交互式命令 | 建议使用系统终端，不要使用纯文本备忘录环境 |
安装前先跑一遍检查命令：
bash复制node -v
npm -v
git --version
正常输出类似：
text复制v22.14.0
11.3.1
git version 2.43.0
如果 node 或 npm 没有安装，先去对应官方渠道安装运行时，再回到本步骤。这里不建议直接用在线代码编辑器跳过本机环境，因为后续要测试 CLI 访问本地项目目录的能力，没有本机环境会漏掉最重要的验证环节。
2.2 为什么 Node.js 版本会影响 CLI 安装
Codex CLI 依赖 Node.js 运行时来执行。版本过低时，安装过程可能报 engine 相关错误，比如：
text复制npm error EBADENGINE Unsupported engine {
package: '@openai/codex',
required: { node: '>=18.0.0' },
current: { node: '16.14.0' }
}
出现这个错误时，优先升级 Node.js，不要强行在低版本下安装。除了版本要求，还要注意 npm 源是否可用。npm 默认从官方 registry 下载包，如果网络环境不稳定，建议先确认 registry 配置，但不要把 npm 源随意替换成不明来源，否则可能遇到依赖损坏或安全风险。
检查 registry 配置：
bash复制npm config get registry
默认输出通常是 https://registry.npmjs.org/。如果你之前为了加速修改过 registry，在使用 Codex 前确认它能正常拉取 @openai/codex 包即可。
注意：不要因为安装慢就选择来历不明的打包版本。CLI 涉及账号登录和文件操作权限，官方渠道安装是底线要求。
2.3 账号与 API 密钥准备
Codex CLI 需要一个可用的账号授权才能访问语言模型服务。不同入口对账号类型的要求可能有差异，以你实际使用的官方文档为准。
准备账号时可以按下面顺序处理：
- 在官方平台完成注册或登录。
- 创建 API 密钥，或者使用 CLI 提供的登录授权方式。
- 确认账号有可用的额度，CLI 每次调用都会消耗对应资源。
- 把 API 密钥保存在本机安全位置，不要写入项目文件。
密钥保存在代码里是最常见的安全事故。无论项目是私有仓库还是团队仓库，都建议使用环境变量或配置文件管理密钥，并在 .gitignore 中排除密钥文件。
bash复制export OPENAI_API_KEY="your-key-here"
环境变量的好处是：CLI 可以直接从环境读取，不需要你每台机器手动粘贴到代码里，也避免密钥进入 git 历史。
2.4 学习环境和生产环境的差别
学习环境下，你可以随意试验：创建临时目录、让 Codex 写一个脚本、改坏就删除重建。生产环境则要提前想好权限、备份、可回滚性。
| 场景 | 学习环境做法 | 生产环境要求 |
|---|---|---|
| 项目目录 | 使用新建的 demo 目录 | 使用独立工作目录或明确授权范围 |
| 密钥处理 | 使用个人密钥即可 | 使用最小权限凭证，权限满足任务即可 |
| 代码备份 | 可以不备份 | 必须使用 git 或有提交记录 |
| 命令执行权限 | 允许自动执行 | 严格限制自动执行范围，重要操作人工确认 |
| 日志记录 | 看终端输出即可 | 记录调用历史、变更文件和输出结果 |
3. 安装 Codex CLI 并完成首次登录
3.1 用 npm 安装 Codex CLI
Codex CLI 的安装命令在常见文档中统一指向 npm 包 @openai/codex。打开终端执行：
bash复制npm install -g @openai/codex
安装完成后确认版本：
bash复制codex --version
如果输出类似 codex 0.x.x，说明安装成功。如果提示 command not found，先检查全局 npm 包的 bin 目录是否在系统 PATH 中。
查看全局安装路径：
bash复制npm prefix -g
然后把 $(npm prefix -g)/bin 加入 PATH，或者重新打开终端窗口让环境变量生效。
3.2 登录与授权流程
安装成功后执行：
bash复制codex login
登录流程会根据 CLI 版本不同而不同。有些版本会自动打开浏览器完成授权，有些版本会要求你手动输入密钥或访问一个链接。
登录完成后，可以查看当前用户状态：
bash复制codex whoami
如果命令返回账号信息，说明授权链路已经打通。如果报错，优先检查环境变量是否覆盖了登录配置，或者授权 token 是否过期。
注意：CLI 的登录状态通常保存在本机用户目录下，比如
~/.codex/。更换终端、换电脑或清理用户目录时，需要重新登录。
3.3 第一次运行前的配置确认
Codex CLI 的配置通常放在用户目录下，常见位置是 ~/.codex/config.toml。如果你的安装版本生成配置文件，可以先查看默认内容：
bash复制cat ~/.codex/config.toml
典型配置内容类似：
toml复制model = "示例模型"
approval_policy = "on-request"
sandbox_mode = "read-only"
这几个字段的含义是：
| 字段 | 作用 | 配置建议 |
|---|---|---|
model |
指定使用的模型版本 | 以官方文档和你的账号可用范围为准 |
approval_policy |
控制哪些操作需要你手动确认 | 学习阶段用 on-request，自动执行前要仔细阅读规则 |
sandbox_mode |
控制文件系统和命令的受限程度 | 积极性越高风险越大，建议从严格模式开始 |
不同版本的配置字段会变化，直接在终端里用 codex 打开交互界面，它会给出当前版本支持的配置项。不要盲改字段名。
3.4 安装过程中的典型错误
安装阶段最常见的几个错误和对应处理方式如下：
| 错误现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
command not found: codex |
全局 bin 目录不在 PATH | npm prefix -g 查看路径 |
把 bin 目录加入 PATH 后重开终端 |
EBADENGINE |
Node.js 版本过低 | node -v 查看版本 |
升级 Node.js 到 18 以上 |
登录后 whoami 报错 |
环境变量覆盖了登录 token | 检查 OPENAI_API_KEY 等变量 |
清理或修正环境变量后重新登录 |
| 配置文件报错 | 字段名与当前版本不匹配 | 查看 CLI 自动生成的默认配置 | 对照默认配置逐项修改，不要整段复制旧版本 |
4. 跑通第一个 Codex 任务：从零完成一个最小项目
4.1 准备一个最小测试项目
学习 Codex 时，不要一上来就把它放到大型业务项目里。创建一个干净的测试目录，用一个小项目验证基本能力。
在终端执行：
bash复制mkdir codex-demo
cd codex-demo
git init
这个项目最好满足三个条件：
- 目录结构简单，只放几个文件。
- 有明确的任务目标，比如“写一个 Python 脚本统计文本中单词频率”。
- 有验证方式，比如运行后能看到正确输出。
这里建议用 Python 举例，因为 Python 脚本不依赖复杂构建流程。如果本机没有 Python，也可以用 Node.js 写脚本。
4.2 用对话模式让 Codex 完成任务
在 codex-demo 目录下启动 Codex：
bash复制codex
进入交互界面后，输入任务描述：
text复制请在当前目录下创建一个 Python 脚本 word_count.py。
脚本读取 example.txt 中的文本，输出出现频率最高的 10 个单词。
同时创建 example.txt，内容包含至少 4 个句子。
运行脚本并展示结果。
这个任务包含三层信息：
- 明确要创建的文件名。
- 明确输入和输出。
- 明确要求运行验证。
Codex 会读取当前目录、创建文件、安装需要的话会提示你确认，然后运行脚本查看输出。期间你会看到它执行命令的过程，比如：
text复制创建文件 word_count.py
创建文件 example.txt
运行命令 python word_count.py
输出频率最高的单词列表
完成之后，检查目录内容：
bash复制ls -la
cat word_count.py
不要只依赖 Codex 的自我报告。必须自己确认文件存在、内容合理、脚本能独立运行。
4.3 理解交互模式和自动执行模式
Codex 的交互模式适合学习和调试。它会边做边解释，遇到需要执行命令时征求你的确认。
还有一种非交互模式，适合在明确任务时直接执行：
bash复制codex exec "请运行 word_count.py，指出所有潜在问题，并修复后重新运行"
非交互模式的优势是可以批量执行、写进自动化脚本；风险是缺少人工确认。刚开始使用时，建议先交互模式，代码和命令都由你确认后再让 Codex 继续。
4.4 如何判断 Codex 的输出是否可信
判断 AI 智能体的结果，要看三个层面：
| 层面 | 检查内容 | 通过标准 |
|---|---|---|
| 文件层面 | 文件是否创建在正确目录、命名是否规范 | 结构符合项目现有约定 |
| 逻辑层面 | 代码是否实现真实需求，而不是表面相似 | 输入输出符合验收标准 |
| 运行层面 | 脚本能否独立执行，不依赖 Codex 环境 | 你能手动重新运行并得到相同结果 |
只有三层都通过，才算是完成了一个任务。这也是 Codex 使用者和普通 ChatGPT 用户之间最大的区别：ChatGPT 输出文本就结束，而 Codex 的输出必须能被复现和验证。
5. 进阶使用：项目指令、MCP、IDE 集成和审查流程
5.1 用项目指令文件告诉 Codex 你的项目规矩
Codex 在执行任务时，会优先读取项目根目录下的指令文件，常见文件名包括 AGENTS.md 或 CODEX.md。具体文件名以你安装的 Codex 版本为准，但设计思路一致：把项目约定写成文本，让智能体在开始工作前先了解规则。
一个最小示例：
markdown复制# 项目开发约定
- 项目使用 TypeScript，不要新增 JavaScript 文件。
- 所有函数必须写 JSDoc 注释。
- 测试框架使用 Vitest，新增功能必须补充测试。
- 修改代码后必须运行：npm run lint && npm test。
- 禁止直接修改 package-lock.json。
这段文件的作用是把“你每次都要重复交代的背景”固定下来。比如你不想让 Codex 把 TypeScript 项目改成 JS，也不希望它改了代码却不跑测试，把这些规则写在项目指令里，它每次执行就会自动带上这些约束。
指令文件要注意三点：
- 规则要具体，不要太抽象。像“代码质量要高”这种描述没有可执行性。
- 规则要能验证。比如“必须运行某个命令”比“尽量保证不报错”更容易被执行。
- 规则数量不要失控。刚开始控制在五条以内，随着项目复杂度逐步补充。
5.2 用 MCP 扩展 Codex 的工具边界
MCP 是模型上下文协议，可以理解为一种让 AI 智能体接入外部工具的标准化方式。Codex 支持通过 MCP 服务器扩展能力，比如接入文件系统、数据库、HTTP 服务等。
配置 MCP 服务器时，一个常见示例是在配置文件中添加：
toml复制[mcp_servers]
filesystem = { command = "npx", args = ["-y", "@modelcontextprotocol/server-filesystem", "."] }
添加后，Codex 可以在对话过程中调用这个 MCP 工具，获得原先没有的数据访问能力。
使用 MCP 的建议：
- 优先使用官方或社区验证过的 MCP 服务器。
- 每个 MCP 服务器应遵循最小权限，只给它需要访问的目录或接口。
- 不要把所有敏感服务全部通过 MCP 暴露给智能体，尤其是生产环境数据库。
- 新增 MCP 后，先用一个明确的小任务测试，确认它真的能被调用。
MCP 带来的收益是边界扩展，风险也是边界扩展。接入的外部工具越多，越要确认哪些操作是读操作、哪些是写操作。
5.3 把 Codex 接入 IDE 日常开发
除了命令行，Codex 也可以通过对应 IDE 扩展进入日常开发流。你可以在编辑器里选中一段代码，让 Codex 解释、重构、写测试，或者直接把当前打开文件作为上下文请求修改。
IDE 集成适合以下场景：
- 快速解释陌生代码：把一段看不懂的函数交给 Codex。
- 局部重构：选中重复逻辑，让它抽取公共函数。
- 生成单元测试：给它一个现有函数和测试框架要求。
- 代码审查：让它找出潜在 bug、边界问题和可读性问题。
IDE 场景和 CLI 场景的差异在于上下文。CLI 更适合“处理整个项目任务”，IDE 更适合“处理当前文件和当前改动”。两者可以配合使用，不建议只依赖其中一种。
5.4 适合 Codex 的审查工作流
在真实项目里，Codex 的典型工作流不是“说一句话等结果”，而是多轮审查和修订。推荐顺序：
- 需求拆分：把一个大需求拆成多个可验证小任务。
- 让 Codex 实现第一个小任务。
- 你自己查看改动 diff。
- 运行项目已有的测试和检查命令。
- 让 Codex 解释它为什么这样改。
- 发现问题后，把问题描述回传给 Codex，要求修正。
- 全部通过后，让 Codex 提交一个清晰的 commit message，但提交动作最后仍由你完成。
这个流程的重点是你审查，而不是 Codex 自动提交。把它理解成一个高效的协作者，而不是全自动执行器。
6. 常见报错和排查思路：一天里最该提前搞清楚的故障
6.1 鉴权失败：登录成功却无法调用模型
现象：codex login 成功，但发消息时返回鉴权错误。可能原因包括：
- API 密钥环境变量覆盖了登录 token。
- 登录 token 过期。
- 账号额度不足或权限受限。
- 时区或系统时间异常导致 token 校验失败。
排查顺序：
bash复制# 1. 查看登录状态
codex whoami
# 2. 检查是否误设了环境变量
env | grep -i openai
# 3. 重新登录
codex login
处理建议：优先移除不必要的环境变量，再重新登录。如果仍然失败，检查账号后台的额度记录。
6.2 沙箱权限拒绝：文件写入被阻止
现象：Codex 想创建文件或执行命令，但终端提示权限不足或写入失败。这是沙箱机制在起作用。
处理步骤：
- 查看沙箱模式配置，确认当前是
read-only还是其他更严格模式。 - 确认该任务确实需要写文件权限。
- 在交互模式下对对应操作手动授权。
- 不要为了省事直接把沙箱全局关闭。
沙箱设计是保护你本机的最后一道防线。默认严格模式会让你更安全，代价是多几次确认。生产环境建议保留严格模式。
6.3 改动丢失：会话中断后文件回退
现象：Codex 执行了很多修改，中途会话异常退出，一些改动没有生效。根本原因是智能体工作流中的文件写入和会话状态是两回事，断开会话不代表所有写入都会被提交。
处理方式：
- 执行重要任务前先确认 git 工作区是干净的。
- 让 Codex 每完成一个明确阶段，就检查
git diff。 - 关键阶段手动提交一次。
- 会话意外中断后，先用
git status和git diff评估当前状态，再决定是继续还是回滚。
6.4 合适的目录和 git 仓库判断错误
现象：Codex 找不到文件，或者把新文件创建在了错误目录。常见原因是启动 Codex 时的工作目录不是目标项目根目录。
检查方式：
bash复制pwd
git rev-parse --show-toplevel
处理建议：进入项目根目录再启动 Codex。如果项目不是 git 仓库，部分依赖 git 的功能会受限；非 git 场景建议明确告知 Codex 当前工作目录结构。
6.5 任务执行完但没有达到预期结果
这是最隐蔽的问题。Codex 报告“已完成”，但验证后发现结果不符合要求。原因通常是任务描述没有包含验收标准。
对比两种描述：
| 描述 | 问题 | 改进方式 |
|---|---|---|
| “优化这个函数性能” | 没有明确优化目标、没有验证方式 | “重构这个函数，使其在 10 万元素输入下耗时降低 50%，并用现有 benchmark 验证” |
| “写一个用户登录接口” | 没有说明技术栈、字段、异常处理 | “用 FastAPI 实现登录接口，接收用户名和密码，校验失败返回 401，成功后返回 token” |
给 Codex 布置任务时，最好固定一个万能模板：目标 + 输入 + 输出 + 约束 + 验证方式。
6.6 排查清单：遇到 Codex 异常时按顺序检查
按这个顺序排查，能覆盖大多数问题：
- 当前工作目录是否正确。
- 是否在 git 仓库中，改动范围是否清晰。
- Node.js 和 CLI 版本是否符合要求。
- 登录状态是否有效，环境变量是否干扰。
- 沙箱模式是否阻止了必要操作。
- 项目指令文件是否存在冲突规则。
- 任务描述是否有明确验收标准。
- 输出日志中是否有具体报错信息。
- 复现一次最小场景，确认问题是不是配置导致。
- 回到官方文档核对命令和字段。
7. 把 Codex 用进真实项目的实践守则
7.1 场景：什么时候应该用 Codex
Codex 更适合目标明确、验证路径清晰的工程任务：
- 跑通文档示例时有很多小坑，让它边看文档边调整。
- 写单元测试覆盖已有函数。
- 修复一个已知 bug，并且你准备了复现步骤。
- 跨文件重构，改名、移动、替换统一逻辑。
- 解读一段别人写的遗留代码，输出结构说明。
这些场景的共同点是：结果可以通过测试、命令或人工检查来判断。Codex 在“试错型”任务里优势最大。
不适合用 Codex 的场景：
- 需求本身模糊，需要你依赖业务判断来定义目标。
- 涉及大量敏感数据，且无法隔离权限。
- 结论需要人为承担责任，比如法律文书、审计报告。
- 你对现有代码完全不了解，连验收标准都说不清楚。
这时不如先花时间做需求梳理，而不是让智能体替你决定方向。
7.2 思路：把“一次大任务”拆成“多个小任务”
经验不足的 Codex 用户喜欢把整个功能一次性丢过去。实际效果通常不好，因为任务里的隐藏步骤太多，它很容易在某个环节误解。
推荐拆法：
text复制原任务：给订单模块加一个导出 Excel 功能。
拆解：
1. 先定义导出字段和格式。
2. 编写一个只负责数据查询的函数。
3. 编写一个只负责生成 Excel 文件的函数。
4. 编写控制器或入口。
5. 补充单元测试。
6. 用手动请求验证导出文件内容。
每个子任务完成后，都做一次验证。这样就算某一步出错，你也能精确知道是哪一层出了问题。
7.3 成本：控制调用次数和上下文长度
Codex 每次任务都会消耗 token，代码量、文件读取次数、多轮修正都会增加成本。实际项目中可以通过三个手段控制：
| 手段 | 做法 | 效果 |
|---|---|---|
| 限定工作目录 | 不要让它扫描整个 monorepo | 减少无关文件读取 |
| 限制上下文 | 只提交本任务相关的文件路径 | 降低 token 消耗 |
| 阶段验证 | 每步验证后再继续，减少无意义重跑 | 避免反复失败 |
成本控制的核心不是“少用 AI”，而是“减少无效往返”。清晰的项目指令、准确的验收标准、干净的 git 工作区，都能降低失败成本。
7.4 安全：Codex 能碰什么、不能碰什么
把 Codex 当成一个拥有本机权限的自动化助手，所有安全原则都围绕“最小权限”展开：
- 给 Codex 独立工作目录，不要默认使用整个用户主目录。
- 关闭不必要的 MCP 服务。
- 不要把 API 密钥、数据库密码、云凭证写进项目文件。
- 生产环境使用只读模式，重要资源变更由你手动完成。
- 不要允许 Codex 自动推送代码到共享分支。
- 它的输出可能包含不安全代码，执行前必须经过检查。
7.5 团队：如何让 Codex 成为团队的公共工具
个人使用 Codex 和团队使用 Codex 是两回事。团队环境至少要处理三件事：
- 统一项目指令文件，把团队规范写进去，避免每个人给 Codex 讲不同规则。
- 建立共享模板，把“任务描述 + 验收标准 + 测试命令”固定成团队格式。
- 记录真实案例，把成功的任务描述和失败的任务描述沉淀成文档，作为后续参考。
团队规范里也可以约定：
markdown复制- 所有 AI 生成的代码必须经过人工 code review 才能合并。
- 所有 AI 生成的测试必须证明能发现真实缺陷，而不是只提高覆盖率。
- 所有 AI 生成的依赖变更必须验证锁文件 diff。
8. 按这份清单完成你的 Codex 实践闭环
到最后，把这一天的学习内容压缩成可以直接带去项目现场的清单。
8.1 环境清单
- [ ] Node.js 版本大于等于 18
- [ ] npm registry 可用
- [ ] git 已安装
- [ ] Codex CLI 已安装并可输出版本号
- [ ] 登录成功，whoami 能返回账号信息
- [ ] 配置文件路径存在，默认字段可读取
8.2 新手任务练习清单
- [ ] 创建独立 demo 目录并执行 git init
- [ ] 让 Codex 创建一个脚本和一个测试输入文件
- [ ] 让它运行脚本并展示结果
- [ ] 手动复现脚本运行，确认不依赖 Codex 环境
- [ ] 修改脚本中的一个逻辑，验证 diff 可读
- [ ] 新增一个失败任务，观察 Codex 如何处理错误
- [ ] 在项目指令文件里写三条约束，验证 Codex 会遵守
8.3 生产使用前检查清单
- [ ] 工作目录是否是项目根目录
- [ ] git 工作区是否干净，是否有可回滚提交点
- [ ] 沙箱模式是否与任务风险匹配
- [ ] 任务是否有明确验收标准和验证命令
- [ ] 项目指令文件是否描述清楚约束
- [ ] API 密钥是否只存在于安全位置
- [ ] 是否关闭无关 MCP 服务
- [ ] 模型选择是否符合账号权限和预算
- [ ] 是否有日志或执行记录可供事后审查
- [ ] 重要改动是否由人工确认后再提交
8.4 最后一句实践建议
Codex 最值得掌握的用法，不是让它一次性生成最大量的代码，而是把它放进一个你随时可以验证、回滚、审查的工程流程里。先把最小环境跑通，再逐步加上项目指令、MCP 工具和团队规范。真正的分水岭不在安装成功的那一刻，而在你开始给自己设定验收标准的那一刻。