Codex 从入门到可交付：新手最容易踩坑的 10 个关键点

最近 Miles Ma 发了一篇《万字长文｜Codex 从入门到精通》，把 Codex 的界面、工作区、权限、Plan、Skills、Plugins、MCP、Automation 等概念系统梳理了一遍。原文很长，适合收藏慢慢读；这篇文章做一次面向新手的二次整理：不追求把每个按钮都讲完，而是先讲清楚怎样把 Codex 用成一个能稳定交付结果的 AI Agent。

原文作者：Miles Ma。原文链接：https://x.com/miles_mazy/status/2091339513134010554

如果你第一次打开 Codex，最容易卡住的往往不是“模型会不会写代码”，而是这些更基础的问题：项目和任务有什么区别？Local、Worktree、Cloud 应该选哪个？权限要给到哪里？Plan 是不是每次都要开？什么时候该用 Skill、Plugin、MCP？

下面按实际使用顺序拆开讲。

1. 先把 Codex 当成“会动手的同事”，不是普通聊天框

普通聊天工具主要产出文字回答；Codex 的关键差异是它能围绕一个工作目录做事：读取文件、修改代码或文档、运行命令、查看 Git 改动、打开网页，并调用已经接入的外部工具。

所以，交给 Codex 的任务最好具备三个条件：

• 有明确材料：比如一个仓库、一个文档目录、一个报错日志；
• 有清楚边界：只改哪个模块、只分析不写入、不要安装依赖；
• 有可验证结果：测试通过、页面恢复、文档结构变清楚、某个文件完成更新。

可以把 Codex 的工作循环记成四步：

Prompt 是你提出要求，Plan 是它准备怎么做，Execute 是实际读写和运行命令，Verify 是检查结果。这里最重要的是最后一步：Codex 说“完成了”，不等于结果已经正确。能不能跑、有没有改错文件、是否符合原需求，都需要验证。

2. 项目和任务不要混用

Codex 里有两个基础概念：Project 和 Thread / Chat。

• 检查这篇文章有没有事实错误；
• 修复登录页按钮点击无响应；
• 给昨天的提交写一份更新说明；
• 把接口文档里的示例改成新版参数。

旧任务里如果已经混入很多无关上下文，新需求又完全不同，直接新建任务更干净。只有在继续修改同一个结果时，才适合留在原任务里。

3. 工作区越小，越不容易出事故

选错工作区，是新手最常见的坑之一：找不到文件、改到别处、读了一堆无关材料，甚至把不该动的目录也纳入上下文。

一个简单标准是：完成这件事所需文件，能否集中在一个最小目录里？能，就只打开这个目录。

几种常见情况可以这样选：

• 只改一个独立项目：打开项目根目录；
• 一个仓库里有多个互不相关的应用：分别添加为多个项目；
• 前后端分成相邻目录：先打开主要目录，需要时再补充另一个；
• 只想分析不想修改：仍然打开正确目录，但把权限设为只读；
• 任务需要远端环境：选择 Cloud，而不是随手扩大本地权限。

边界越小，误操作的影响范围也越小。

4. Local、Worktree、Cloud 的选择逻辑

新建任务时，Codex 通常会让你选择工作模式。不要按“听起来高级”来选，要按任务风险来选。

Local：适合日常小改

Local 会直接在当前目录工作。它适合改文档、修小 Bug、整理文件、跑现有测试。优点是直观，改动马上出现在本地；缺点也明显：如果指令含糊，可能直接把本地文件改乱。

适合 Local 的任务：

• “检查 README 结构，并补充安装步骤”；
• “修复这个函数的边界条件”；
• “运行现有测试，看失败原因”；
• “把这篇文章按小标题重新组织”。

Worktree：适合有风险的实验

Worktree 可以把任务放到隔离分支或独立工作目录里处理。适合大改、重构、批量替换、多个方案并行探索。

当你不确定改动会不会影响主线时，优先用 Worktree。它让你有机会比较方案，而不是把所有实验都堆在当前目录里。

Cloud：适合远端或长任务

Cloud 更适合远端环境、长时间运行、需要独立资源的任务。比如跑较重的构建、处理远端仓库、让任务在本地电脑不用一直开着的情况下继续执行。

如果只是改一段文案或修一个小函数，没有必要为了“高级”而上 Cloud。

5. 权限不是越大越好

很多人一遇到权限提示，就习惯性给最高权限。这个习惯很危险。

更稳妥的原则是：先给最小权限，等任务证明需要更多权限时再升级。

常见权限可以这样理解：

• 只读：适合分析、审稿、排查方向，不允许改文件；
• 工作区可写：适合大多数日常修改；
• 更高权限：涉及安装依赖、访问工作区外目录、操作系统级命令时才考虑。

如果你只是想让它先看代码，指令里可以明确写：

先不要修改。请确认你理解的目标、需要查看的文件和准备执行的步骤，等我确认后再动手。

这句话很朴素，但能显著降低“一上来就乱改”的概率。

6. Plan 的价值不是仪式感，而是提前发现偏差

Plan 不一定每次都必须开。小任务，比如“把错别字改掉”“解释这段报错”，直接做也没问题。

但以下任务建议先让 Codex 出计划：

• 涉及多个文件；
• 可能改变架构或数据结构；
• 你不确定它会改哪里；
• 生产配置、权限、脚本、发布流程相关；
• 需要先调研再动手。

一个好用的提示是：

/plan 先检查当前目录和相关文件，只给出修改计划，不要写文件。

Plan 的作用不是让流程显得专业，而是把风险提前暴露出来。你可以在它动手前发现：它理解错目标了、准备看的文件不对、步骤太激进，或者验证方式不够。

7. Diff 面板是你真正的验收入口

Codex 的回复只能说明它“认为自己做完了”，Diff 才能告诉你它到底改了什么。

每次任务结束，至少要看三件事：

• 有没有改到需求之外的文件；
• 有没有大段重写本来不该动的内容；
• 有没有删除配置、注释、边界处理、错误提示等隐性信息。

如果某一行有问题，直接在那一行留下评论，比在输入框里说“上面那个函数不对”准确得多。评论后再补一句：

处理刚才的 inline 评论，其他部分不要扩大修改。

这类指令越具体，Codex 越容易把修改范围收住。

8. Skills、Plugins、MCP 不要一上来全接

很多新手会被扩展能力吸引：Skills、Plugins、MCP、Automation 看起来都很强。但对初学者来说，最重要的是先把基础闭环跑顺：选对目录、说清任务、控制权限、检查 Diff、做验证。

这些扩展可以这样理解：

• Skills：把重复流程沉淀成可复用做法，比如“发布前检查清单”“代码审查流程”；
• Plugins：把某些应用或服务能力接进来，让 Codex 能操作更多东西；
• MCP：让 Codex 访问结构化外部工具或数据源；
• Automation：把固定任务自动触发，比如定时检查、定时汇总。

建议顺序是：先手动跑顺 3–5 次，再把稳定流程沉淀成 Skill 或自动化。不要还没搞清楚边界，就把一堆外部能力全部打开。

9. 好 Prompt 的核心是“边界 + 验收”

给 Codex 的指令不需要写得很花，但要把边界和验收说清楚。

一个比较稳的任务模板是：

目标：修复登录页点击按钮无反应的问题。
范围：只检查 frontend/src/pages/login 及其直接依赖，除非发现必须扩大范围，否则不要改其他目录。
要求：先说明你准备查看哪些文件，再修改。
限制：不要安装新依赖，不要重写整个页面。
验收：修改后运行现有前端测试或至少执行类型检查，并说明结果。

这里真正关键的是“范围、限制、验收”。只说“帮我修一下登录页”，Codex 也能动手，但它更容易按自己的理解扩大修改。

10. 最后一步永远是验证

无论 Codex 输出多自信，最后都要回到验证。

验证可以分层：

• 文档类：阅读生成结果，检查事实、日期、链接、语气和结构；
• 前端类：跑类型检查、构建、截图或浏览器检查；
• 后端类：跑单测、接口测试、日志检查；
• 配置类：先看 diff，再做最小范围 reload 或 dry-run；
• 内容发布类：发布后打开页面确认标题、排版、封面、链接正常。

真正可靠的 Agent 工作流，不是“AI 一次写对”，而是“AI 能执行，人能用验证把风险关住”。

结语：先把 Codex 用稳，再追求高级功能

Codex 的能力上限很高，但新手最该先掌握的不是某个隐藏按钮，而是这套基本纪律：

• 任务要有明确结果；
• 工作区尽量小；
• 权限逐步给；
• 大改先 Plan；
• 每次看 Diff；
• 完成后验证。

这六件事做稳以后，再去接 Skills、Plugins、MCP 和自动化，才不会变成“功能很多，但风险也很多”。

如果你想把这种 Agent 工作流接到自己的工具、脚本或业务系统里，模型通道和 API 稳定性也很重要。可以从 [api.884819.xyz](https://api.884819.xyz) 注册体验，平台兼容 OpenAI API 格式，新用户注册即送体验 token，适合先用低成本方式把自己的 AI 工作流跑起来。