第一次让 Codex 进入项目，先跑通一个最小任务 - AIPlan

第一次让 Codex 进仓库，别从“帮我重构这个项目”开始。选一个 20 分钟内能验证完的小任务：改一处文案、加一个参数校验、修一个明确报错。跑通这一轮，你才会知道它的读文件范围、命令权限和输出习惯。 第一步是确认它站在哪个目录 Codex CLI 的行为跟当前工作目录绑定。在 ~ 下直接敲 codex，它探索的是一个没有项目的目录，接下来所有输出都是废的。 正确顺序是：cd 到仓库根目录，再运行 codex。判断是不是根目录有个简单办法，看这里有没有 .git、package.json、go.mod 这类标志文件。仓库根目录和子目录的行为差别很大，在子目录启动，它可能读不到上层的配置文件。 桌面版的做法不同：从左上角菜单选 Codex，然后打开本地文件夹或者从 Projects 里选一个项目。审查面板要求项目在 Git 仓库内，项目还没初始化时应用会先提示创建一个。 先让它读，不写 第一句话用官方示例就够：Tell me about this project。它会给你一份结构说明。这份说明的价值不在准确，而在能暴露它读错了什么。 拿到输出后核对三处： • 入口文件对不对。Web 服务看有没有找到 main.go、server.ts 之类。 • 依赖声明读的哪个。有 package-lock.json 和 pnpm-lock.yaml 两个锁文件的项目，它可能选错。 • 测试命令从哪来。读 package.json 的 scripts.test，还是从 README 里抄的。 三处有一处错，就在任务描述里直接指定，别指望它自己纠正。比如“包管理器是 pnpm 10.34.3，不要用 npm 的命令”。 摸清运行方式再动手 判断一个仓库能不能让它改，标准很实际：你能不能自己跑起来。跑不起来的话，它改完你也没法验证。 要确认的三条命令： • 装依赖的命令是什么 • 跑测试的命令是什么 • 起本地服务的命令是什么 把这三条写进你的第一条任务描述。官方在快速上手文档里也建议在任务前后创建 Git 检查点，理由就是改坏了要能退。 Windows 上还有个额外步骤。Codex 在这边提供 codex doctor 用来诊断启动、连接和性能问题。第一次装完先跑一次，比后面出问题再查省事。 一个小任务的具体形状 选任务的标准：改动 1 个文件以内，有明确的成功判据，能自己验证。 三个可用的例子： 把 README 里 "Installation" 一节的 npm 命令改成 pnpm，其他内容不动。 给 /api/v1/orders 的 status 参数加校验，只接受 pending/paid/refunded 三个值， 其他返回 400 并带错误信息。不要改路由，不要改数据库字段。 修复 test/format.test.ts 里那个失败的用例，先告诉我失败原因，等我确认再改。 第三个例子多了一句“等我确认再改”，这是第一次用的时候值得加上的约束。它会先给你诊断，你判断完再放行。 看它改了什么，不看它说了什么 任务结束后不要读它的总结，直接看差异。git status 看动了哪些文件，git diff 看具体行。 第一次用的人常犯的错是相信“已完成”这句话。实际差异里可能多了 3 个文件：一个格式化过的配置、一个自动生成的锁文件、一个它顺手建的测试。前两个通常不该提交。 审查面板在这时候好用。输入 /review 选 Review uncommitted changes，它会按优先级报发现，且不改工作区。默认范围是 Unstaged，切到 Last turn 只看上一轮助手的改动。 权限先停在最保守那档 桌面上权限控制在输入框下方，CLI 里用 /permissions。官方建议大多数工作从 Ask for approval 开始，它让工具在当前工作区内干活，要越界时暂停。 一个容易误解的点：Approve for me 不会扩大沙箱。它保持同样的工作区边界，只是把越界请求交给自动复核。想限制它能碰哪些文件，改的是工作区，不是审批方式。 第一次跑，建议保持 Ask for approval。等你摸清它会在哪些地方尝试越界，再考虑放宽。多数团队在跑了 3 到 5 轮之后才会动这个开关。 工作区边界和密钥处理可以一起配好，具体做法在 Codex 的权限、密钥和命令范围怎么管 里。 会话可以接着上次 codex resume 用来恢复当前仓库的最近对话，也能跨本地会话搜索更早的工作。第一次开完一轮，第二天接着改同一个模块时，恢复会话比重新解释上下文省事。 codex --image 可以带图进第一条提示，传报错截图、架构图、设计稿都行。第一次上手时这个功能挺实用：把界面设计稿丢进去，让它照着改样式，比用文字描述布局准确得多。 codex cloud 在终端里浏览云端任务并把结果应用到本地仓库，codex mcp 用来接本地或远程的 MCP 服务器。这两个先不用急着开，等本地流程顺了再说。 什么时候算摸清了 三件事都做到，就算过了第一关： • 能在 1 次任务里改对 1 个文件，git diff 里只有预期的改动 • 能预判它会不会要求越界，实际和预判一致 • 出问题时知道去哪看：Settings > Usage 看额度，审查面板看差异，codex doctor 看环境 第一关过不了的常见原因是仓库本身没有测试、没有构建脚本、没有 README。这种情况下它只能靠猜，你也只能靠猜。先把项目的基础命令补齐，比换工具更有效。 Astra 需要 Codex CLI 0.153.0 或更新，装完先 codex --version 确认一次。桌面版看不到 Astra 时，从菜单里点 Check for Updates 再重启，自动更新过也可能还差一版。 如果你还没装，安装方式和首次登录的细节在 Codex 是什么，从理解代码到修改和验证。任务描述里那 4 段怎么写更省返工，值得在第二轮之前先理顺。 Plus 的 $20 按 1 美元 ≈ 6.69 元折算约 ¥133.80，一周几次专注编码的量级刚好；菲区官充的 Plus 月卡是 ¥115.50，开出的是同一个 Plus 身份，额度上限没有差别。 挑一个今天就能验证的小改动，跑完这一轮再决定要不要扩大范围。 参考资料资料核对日期：2026-10-17 • Codex CLI • Permissions 延伸阅读• Codex 是什么？从理解代码到修改、运行和验证 • 给 Codex 下任务怎么写？让目标、边界和验收都可检查 • Codex 操作项目时，权限、密钥和命令范围怎样管理？