更新时间：2026-03-28

验证环境：

• codex-cli 0.117.0

• OpenAI 官方 Codex 文档

• 本机 codex --help / codex exec --help / codex review --help / codex mcp --help

本文档面向团队内部成员，定位是“平时可以直接查阅的正式手册”。它不是培训讲稿，也不是速查单页，而是一份能支撑新成员入门、老成员复查、高频任务落地的长期文档。

建议按你的角色选择阅读路线，而不是强行从头读到尾：

• 第一次接触 Codex：第 1、3、4、5、6、9、15 章

• 日常开发成员：第 4、5、6、7、8、9、14 章

• 负责团队规范与配置的人：第 9、10、11、13、15 章

• 负责自动化、工具接入或平台能力的人：第 7、9、10、11、13、15 章

---

1. Codex 是什么，适合做什么

把 Codex 理解成一个可执行的编码代理，而不是一个只能聊天的问答框。这里的“代理”可以先简单理解成：它不只会回答问题，还会在你的授权范围内读文件、改文件、跑命令、调用工具来完成任务。

1.1 Codex 和普通 AI 对话工具的区别

很多人第一次接触 Codex 时，会把它和“会写代码的聊天助手”混在一起。这个理解不完全错，但不够准确。

普通对话型 AI 的工作模式通常是：

1. 你输入问题

2. 它基于当前上下文生成回答

3. 工作到此结束

Codex 的工作模式更像一个可以执行任务的工程代理：

1. 你输入任务

2. 它读取上下文

3. 它决定是否需要看文件、跑命令、调用工具

4. 它基于执行结果继续推进

5. 最终给出修改、解释、审查结果或交付物

这也是为什么同样一句“帮我修一下这个 bug”，在普通聊天工具里可能只得到一段建议，而在 Codex 里有机会真正变成一套“读取代码 -> 定位问题 -> 修改 -> 验证 -> 汇报”的工作链路。

1.2 构成 Codex 的几个关键概念

后面的章节会频繁出现这些词，先把它们的关系看清：

• model：底层大模型，负责理解输入和生成输出

• agent：把模型、工具、上下文和执行流程组织起来的工作单元

• tool：Codex 可调用的具体能力，例如读文件、跑命令、访问 MCP server

• thread：一次连续工作会话，保存历史消息、上下文和中间结果

• prompt：你交给 Codex 的任务说明

• context：Codex 当前能看到的信息集合

你可以把它们想象成这层关系：

• model 提供智能

• agent 负责组织工作

• tool 负责执行动作

• thread 负责保存任务现场

• prompt 决定任务目标

• context 决定 Codex 看到什么

1.3 一个任务在 Codex 里是怎么跑起来的

从使用者角度，可以把一次典型任务理解成下面这条链路：

1. 你给 Codex 一个 prompt，说明目标、上下文、限制和完成标准。

2. 当前 agent 读取这段任务说明，以及当前线程里已有的上下文。

3. 如果任务只需要理解和总结，Codex 可能直接回答。

4. 如果任务需要读文件、运行命令、访问外部工具，Codex 会调用对应工具。

5. 工具返回结果后，Codex 再基于这些结果继续推进。

6. 当它认为任务完成，或者被权限、上下文、环境限制挡住时，再给出最终答复。

这个过程里，最常见的错误不是“模型不够强”，而是下面三种：

• 目标不清楚，导致执行方向错误

• 上下文不完整，导致判断依据不足

• 完成标准没写，导致结果看似完成但无法验证

1.4 Codex 适合什么任务

它最适合这些任务：

• 阅读和解释现有代码

• 在约束明确时修改代码

• 运行本地命令、补测试、修 bug

• 审查当前改动

• 结合配置、MCP、skills、subagents 做更稳定的协作

如果你对后面几个词还不熟，可以先这样记：

• MCP：让 Codex 连接外部文档、系统或工具的接口

• skill：把高频工作流封装成可复用能力

• subagent：由主代理分出来并行处理子任务的辅助代理

1.5 Codex 不适合什么任务

它不适合这些用法：

• 目标不清楚，却要求“一次性大改”

• 不给验证方式，却要求“保证没问题”

• 两个线程同时改同一批文件

• 在高风险环境里长期开最高权限

• 把它当成自动背锅器，自己不看 diff、不做验证、不做最终判断

如果只记住一个原则，就记住这句：

Codex 的效果，更多取决于你给它的目标、上下文、约束和验证方式，而不是某句神奇提示词。

---

2. 安装与登录

这一章的目标不是“把命令抄一遍”，而是让你在第一次上手时知道要验证哪些东西，避免装完就直接进入任务、结果连环境有没有准备好都不清楚。

2.1 常见安装方式

官方常见安装方式：

npm install -g @openai/codex

或：

brew install --cask codex

对团队成员来说，选择哪种安装方式通常不是关键问题。关键在于：

• 团队有没有统一要求

• 你是否能稳定升级到一致版本

• 当前环境里 codex 命令是否可用

2.2 安装后第一件事：确认 CLI 真的可用

不要安装完就直接开任务，先跑这几个最小检查：

codex --version

codex --help

codex exec --help

codex review --help

codex mcp --help

这样做的目的不是“背命令”，而是确认当前环境里这些能力确实存在，避免后面把不存在的命令、参数或功能写进团队文档。

2.3 首次启动和登录

启动交互式会话：

codex

首次启动会提示登录。团队内部如果对登录方式有统一要求，以组织规范为准。

当前版本下，至少建议知道这几条和账号状态有关的命令：

codex login status

printenv OPENAI_API_KEY | codex login --with-api-key

codex logout

怎么理解：

• codex login status：查看当前是不是已经登录

• codex login --with-api-key：从标准输入读取 API key，适合脚本或受控环境

• codex logout：清除本机保存的认证状态

如果团队没有统一规定，第一次使用时至少先确认两件事：

• 你准备用哪种身份方式登录

• 当前机器是不是已经残留了旧登录状态

实际使用里，登录相关问题最常见的不是“不会登录”，而是这三类：

• 终端环境和浏览器环境不是同一个账号体系

• 团队对使用 ChatGPT 账号还是 API key 有额外约束

• 本机已经登录过旧环境，但你以为当前会话是新登录

2.4 第一次真实任务前的检查清单

在你把 Codex 用到真实仓库前，至少确认这些事：

1. 版本能看见

2. 帮助命令能打开

3. 登录流程可完成

4. 你知道自己当前在哪个目录启动

5. 你知道当前是只读还是可写模式

如果这 5 件事里有任何一件说不清，先别急着做复杂任务。

---

3. 第一次使用：推荐默认方式

这一章的重点不是“给一条启动命令”，而是帮你建立一套默认启动策略。你以后遇到不同任务时，应该先判断自己要哪种启动方式，而不是每次都盲目开最高权限。

3.1 三种推荐默认方式

对团队成员，最实用的是把默认方式分成三层：

新手默认：先只读理解

codex --sandbox read-only --ask-for-approval on-request

适合：

• 第一次接触 Codex

• 第一次接触当前仓库

• 先理解代码流，不打算立即修改

这组参数的目标是“先理解，再决定要不要改”。它会显著降低误改和误执行的风险。

日常默认：工作区可写

codex --sandbox workspace-write --ask-for-approval on-request

适合：

• 日常开发任务

• 明确知道自己要修改当前工作区文件

• 可以做最小验证

这是本手册推荐的常态默认值。它在可用性和安全性之间通常最平衡。

自动化默认：先最小权限，再逐步放开

如果你准备写脚本或 CI，不要直接照抄交互式习惯。对自动化，应该先从只读和非交互开始，再根据需要放宽。

例如：

codex exec "summarize the repository structure"

自动化场景的详细规则放在第 11.4 节，这里先记住一件事：

自动化比人工交互更需要保守默认值，因为一旦错了，通常会更快、更批量地错。

3.2 sandbox 和 approval policy 到底在控制什么

这组参数最容易让新人混淆，所以先把关系讲清：

• sandbox：执行边界，规定 Codex 能在什么范围内读写和运行命令

• approval policy：审批规则，决定什么时候需要你点确认

可以把它们理解成两层门：

• 第一层门：技术上允许做到哪里

• 第二层门：做到某一步前要不要先问你

如果你只记一句区分：

• sandbox 回答“能不能做”

• approval policy 回答“做之前要不要先确认”

3.3 常见参数怎么理解

对大多数成员，最常见的一组命令是：

codex --sandbox workspace-write --ask-for-approval on-request

这组参数里每个词的实际含义是：

• workspace-write：允许在当前工作区内读写，适合日常开发任务

• on-request：需要越界时再申请审批，避免直接高风险执行

当前版本里，--full-auto 是这组组合的快捷方式：

codex --full-auto

这不代表“完全不受控”，而是“在工作区沙箱内以较低摩擦运行”。

3.4 第一次成功使用应该长什么样

第一次上手，不要直接拿它去做大改。更稳的做法是完成一个最小闭环任务：

1. 启动 Codex

2. 让它解释一段代码

3. 让它给一个最小修改方案

4. 看它给出的 diff 或建议

5. 最后让它说明怎么验证

一个适合第一次成功体验的任务是：

阅读 src/auth.ts 和 src/session.ts。

先不要改代码，解释登录请求从入口到权限校验的完整路径。

请输出：

1. 调用顺序

2. 关键数据结构

3. 两个最容易引入回归的点

这个任务的好处是：

• 不需要写权限

• 不要求你立刻相信它能改对

• 能帮你快速判断它对当前仓库的理解能力

3.5 附加图片和初始上下文

如果任务一开始就需要图片作为上下文，例如 UI 草图、界面截图，可以在启动时附图：

codex -i ./mockups/page.png

这适合做视觉对齐类任务，但仍然要配合文字约束。图片只能提供视觉线索，不能替代你对技术栈、交付范围和验证方式的说明。

---

4. 先建立正确使用心智

很多人不是不会用 Codex，而是没有建立正确的工作方式。Codex 不是“随时问一句”的工具，它更像一位在你边界约束下工作的工程代理。

4.1 把一个线程当成一个任务

一个 thread 可以理解成一次连续工作会话，里面会保留你和 Codex 的上下文、文件引用和任务推进过程。一个 thread 最好只承载一个连续任务，不要把“修 bug、写文档、改首页样式、查另一个问题”都塞进同一个长线程里。

为什么这件事重要：

• 线程越长，上下文越容易脏

• 目标越混，Codex 越容易把旧任务残留带进新任务

• 你自己也会更难判断当前输出到底是对哪个问题的回答

更稳的做法：

• 一个线程做一个主题

• 跑偏了先 /status

• 方案分叉时用 /fork

• 中断后用 /resume

• 任务完全换主题时，优先 /new 或重新开会话

4.2 先解释，再计划，再修改

新成员最常见错误是上来就让 Codex 直接改。更可靠的顺序是：

1. 先让它解释现状

2. 再让它给计划

3. 确认约束

4. 再实施修改

5. 最后要求验证与 review（也就是审查改动）

这个顺序背后的原因是：

• 解释阶段检验理解

• 计划阶段暴露方案风险

• 实施阶段才真正动代码

• 验证阶段避免“看上去对了”

• review 阶段做第二次风险扫描

4.3 验证要求必须写进任务

不要只说“修掉这个问题”，要说“修完后如何证明修对了”。

好的写法：

先复现问题，再提出最小修复方案。修复后运行最小相关测试集，并把执行命令和结果告诉我。

差的写法：

帮我看看这个问题。

两者的区别不在措辞礼貌，而在于：

• 好写法让 Codex 知道什么算完成

• 差写法只是在请求“展开想法”，而不是执行任务

4.4 什么时候该分叉，什么时候该重开

新手经常把 /fork、/resume、/new 混在一起。

可以这样理解：

• /fork：保留当前上下文，试第二种方案

• /resume：回到旧线程继续做

• /new：从空白聊天开始一个新任务

如果你只是想在同一问题上试两条路，用 /fork。如果你已经彻底换题，不要在旧线程里继续追问，直接 /new 更干净。

---

5. 一条好 prompt 的基本结构

这里的 prompt 不只是“问一句话”，而是你给 Codex 的任务说明。写得越像一张清楚的工单，Codex 的结果通常越稳。

5.1 为什么结构化 prompt 更稳定

Codex 并不是因为“看见英文关键词”才工作更好，而是因为结构化 prompt 能减少歧义。它把 4 件最关键的事提前说清：

• 你到底要做什么

• Codex 应该看哪些信息

• 它不能越过哪些边界

• 什么结果才算完成

5.2 最稳定的四段式结构

稳定好用的结构：

• Goal：你要它做什么

• Context：哪些文件、路径、报错、复现步骤相关

• Constraints：不能改什么、必须遵守什么

• Done when：什么结果算完成

这四个英文词只是帮助你记住结构，不是必须逐字照抄。重点是把任务目标、上下文、限制条件和完成标准说清楚。

通用模板：

目标：

我要完成什么



上下文：

相关文件 / 目录 / 错误信息 / 复现步骤



约束：

不能改什么；必须遵守什么；风险边界



完成标准：

需要生成哪些结果；跑哪些检查；如何验证

5.3 每一段都应该写到什么程度

Goal

不要写抽象目标，例如“优化一下”。应写成可执行目标，例如：

• 解释登录流程

• 修复设置页保存失效问题

• 为某函数补测试

• 审查当前未提交改动

Context

能写出文件路径，就不要只说“那个模块”；能写出复现步骤，就不要只说“偶尔有问题”。

好的上下文通常包括：

• 文件路径

• 错误现象

• 复现步骤

• 相关文档或截图

• 你已经怀疑的范围

Constraints

这是限制 Codex 不要乱扩张任务的关键部分。常见限制包括：

• 不修改公开 API

• 优先最小改动

• 不要无关重构

• 保持现有测试风格

• 不要新增依赖

Done when

完成标准最好是可验证的，而不是情绪性的。例如：

• 相关测试通过

• 某复现步骤不再出现错误

• 输出某份文档

• 明确给出 diff、验证步骤和结果

5.4 好 prompt 和坏 prompt 的差别

差的写法：

帮我优化这个页面。

更好的写法：

目标：

优化设置页保存逻辑



上下文：

问题是点击 Save 后偶尔显示成功，但刷新后没有保存。

相关文件：src/settings.tsx、src/api/settings.ts



约束：

不要改 API 结构。

尽量做最小修复。

如果可以，补一个回归测试。



完成标准：

先复现问题，再修复，再重新执行复现步骤，并告诉我验证结果。

5.5 Prompt 失败最常见的原因

如果 Codex 输出看起来跑偏，通常不是因为“它突然变笨了”，而是你的 prompt 存在这些问题：

1. 目标太宽

2. 上下文太少

3. 限制没写

4. 没说什么算完成

5. 把多个任务混在一起

5.6 每次发任务前的最小检查

在发送 prompt 之前，快速自问这 5 件事：

1. 它知道我要解决哪一个具体问题吗？

2. 它知道该看哪些文件吗？

3. 它知道哪些东西不能乱改吗？

4. 它知道怎么验证结果吗？

5. 这个任务是否应该拆成两步？

只要其中有 2 个问题答不上来，先别发。

---

6. 日常高频工作流

这一章不是“给几个 prompt 例子”，而是总结日常最常见的 5 类任务应该怎么交给 Codex。每种工作流都按同一逻辑理解：

• 适合什么时候用

• 推荐怎么下任务

• 如何判断结果是不是可接受

• 最容易犯什么错

6.1 理解代码

适合场景

• 新接手模块

• 改动前先摸清调用链

• review 前快速理解上下文

• 排查问题前先建立代码心智模型

推荐下任务方式

阅读 src/auth.ts 和 src/session.ts。

先不要改代码，解释登录请求从入口到权限校验的完整路径。

请输出：

1. 调用顺序

2. 关键数据结构

3. 两个最容易引入回归的点

验收标准

你至少要看这三件事：

• 它有没有说对关键调用链

• 它有没有提到真正相关的文件

• 它指出的风险点是否与代码实际结构相符

常见误区

• 不给文件路径，让它在大仓库里盲扫

• 一上来就让它给方案，还没确认它理解对不对

• 它解释完以后，你不回到代码里做交叉确认

6.2 修一个可复现的 bug

适合场景

• 错误可以稳定复现

• 你知道大概受影响的页面、接口或模块

• 你希望 Codex 先缩小范围，再实施最小修复

推荐下任务方式

Bug：设置页点击 Save 后偶尔显示成功，但刷新后配置没有保存。



复现步骤：

1. npm run dev

2. 打开 /settings

3. 打开 Enable alerts

4. 点击 Save

5. 刷新页面，状态恢复



约束：

- 不修改 API 结构

- 修复尽量小

- 如果可行，加一个回归测试



先复现，再提出最小修复方案，等我确认后再改代码。

验收标准

• 它先复现或至少解释了复现路径

• 它先给了方案，而不是直接大改

• 修复后的验证方式与你给的复现步骤一致

• 如果改动引入了新行为，应该补测试或解释为什么不补

常见误区

• 只说“偶尔有 bug”，不给复现步骤

• 不限制改动范围，导致它顺手重构一大片

• 不要求先方案后实施

6.3 补测试

适合场景

• 某函数或模块已有实现，但缺少测试

• 刚修完 bug，想补回归测试

• 你希望 Codex 贴合现有测试风格，而不是凭空发明一套

推荐下任务方式

为 src/utils/transform.ts 中的 invertList 函数补一个单元测试。

要求覆盖正常路径和边界情况。

请遵循仓库中已有测试风格，并运行最小相关测试集。

验收标准

• 测试覆盖正常路径和边界条件

• 风格与现有测试一致

• 改动范围集中在相关测试文件

• 最后有运行结果或最小验证说明

常见误区

• 不指出函数或文件，导致它补错位置

• 不说“遵循现有风格”，导致测试写法和仓库习惯不一致

• 不要求跑测试，只看它生成了文件就结束

6.4 改文档

适合场景

• 更新说明文档

• 增加故障排查、示例或术语章节

• 统一语言风格或补齐缺失章节

推荐下任务方式

更新 docs/codex-user-guide.md。

补充“认证故障排查”小节。

要求：

- 语言风格保持一致

- 补充常见错误场景

- 校验文中的链接是否仍然有效

验收标准

• 新增内容与原文风格一致

• 链接、路径、命令没有明显失效

• 没把旧信息和新信息写冲突

常见误区

• 只说“补一段文档”，不说补在哪、补什么

• 不限制风格，导致新旧文档像两个人写的

• 不核查命令和链接

6.5 做本地 review

这里的 review 是“审查改动”，目标是帮你发现风险、遗漏和回归点，不等于自动修复，也不应该替代人工最终判断。

什么时候用

• 任务做完后

• 提交前

• 想快速扫一遍风险点时

交互式写法

/review

更聚焦一点：

/review 重点关注边界条件、安全问题和潜在回归

非交互写法

codex review --uncommitted

codex review --base main

验收标准

• 它指出的风险与你当前 diff 真正相关

• 它区分了“高风险问题”和“一般建议”

• 你会回到代码和 diff 本身确认，而不是只看文字总结

常见误区

• 把 review 当成自动修复

• 把 review 输出当成唯一合并依据

• review 发现问题后，不回看代码就直接相信结论

---

7. 最常用的 CLI 命令

这一章只讲“你还在 shell 层时该怎么选入口”。如果你已经进入 Codex 会话，下一章再看 slash commands。把这两层分开，能明显减少新人把 shell 命令和会话命令混用的问题。

7.1 交互式会话

这里的 CLI 是命令行界面，也就是你在终端里直接和 Codex 交互的方式。

最常见的交互式启动方式：

codex

codex --sandbox workspace-write --ask-for-approval on-request

codex --profile <你已配置的 profile 名称>

codex -i ./mockups/page.png

codex --search

这些命令各自适合：

• codex：最普通的进入方式

• --sandbox ... --ask-for-approval ...：明确控制权限边界

• --profile ...：快速加载一套已配置的默认参数

• -i：在初始 prompt 里附图

• --search：为当前会话启用 web search 工具；不加这个参数时，代理默认并不能直接使用该工具

注意：--profile 只有在你已经在 config.toml 中定义对应 profile 时才可直接使用。profile 不是模型名本身，而是你给一组配置起的别名。

7.1.1 几个值得尽早知道的启动参数

除了最常见的启动命令，下面这几类参数也很实用：

codex -C ~/work/my-repo

codex --add-dir ../shared-package

codex --no-alt-screen

codex --oss --local-provider ollama

分别怎么理解：

• -C / --cd：先把 Codex 的主工作根切到指定目录，再进入会话。它适合你当前 shell 不在目标仓库里，或者想从脚本、快捷命令里直接切到指定项目。

• --add-dir：在主工作区之外，再额外开放一个可写目录。它常见于 monorepo、兄弟包联调、生成物落在仓库外侧目录等场景。

• --no-alt-screen：不用终端备用屏幕，而是以内联方式运行 TUI，保留终端滚动历史。对 tmux、zellij 等环境尤其有用。

• --oss / --local-provider：把模型提供方切到本地开源模型服务。当前 help 里可见的本地 provider 是 lmstudio 和 ollama。

这里最容易搞混的是：

• -C 改的是工作根，不是审批策略

• --add-dir 扩的是可写范围，不是“全盘可写”

• --oss 改的是模型提供方，不是 sandbox 或 MCP

7.2 什么情况下优先用交互式会话

交互式会话最适合：

• 任务还在探索阶段

• 你需要和 Codex 来回几轮澄清

• 你希望边看边调 prompt

• 你不确定第一版方案是否可接受

它不太适合：

• 明确、一次性、可脚本化的任务

• 需要机器可读输出的流程

• 批量自动执行

7.3 非交互执行

codex exec "summarize the repository structure"

codex exec --ephemeral "triage this repository and suggest next steps"

codex exec --json "summarize the repo structure"

注意：codex exec 默认要求你在受信任的 Git 仓库里运行；如果是在非 Git 目录或当前目录未被信任的环境里执行，需要显式加 --skip-git-repo-check。

适合：

• 脚本化任务

• CI

• 一次性分析

• 机器可读输出

和交互式会话的区别不是“能不能聊天”，而是：

• 交互式会话适合迭代

• codex exec 适合一次性交付

7.4 会话续接与分叉

codex resume --last

codex fork --last

codex resume <session-id>

codex fork <session-id>

这组命令解决的是“从 shell 层恢复或分叉会话”，适合：

• 昨天做到一半，今天继续

• 想从历史会话分一条新路线

• 你还没进入 TUI，就想先选定旧线程

它们和会话内的 /resume、/fork 解决的是同一类问题，但入口不同：

• codex resume / codex fork：在 shell 层选旧会话

• /resume / /fork：已经进入会话后再操作当前或历史线程

7.5 审查与环境诊断

codex review --uncommitted

codex review --base main

codex mcp list

codex features list

codex sandbox --help

这组命令的定位是：

• codex review：独立跑审查任务

• codex mcp list：确认外部工具接入状态

• codex features list：确认当前能力开关状态

• codex sandbox --help：确认本机支持的沙箱后端和平台差异

7.6 一个实用的命令选择方法

如果你不确定应该用哪条命令，可以按这个判断：

1. 需要多轮来回讨论，用 codex

2. 需要一次性结果，用 codex exec

3. 需要专门审查改动，用 codex review

4. 需要恢复或分叉旧会话，用 codex resume / codex fork

5. 需要确认工具接入或环境状态，用 codex mcp ... / codex features ...

对大多数团队成员来说，这个判断已经足够覆盖 80% 以上的日常使用场景。

---

8. 常用 slash commands

slash commands 是在 Codex 会话里直接输入的快捷命令，通常以 / 开头，例如 /plan、/review。它们不是 shell 命令，所以不要拿去终端普通提示符里单独执行。

OpenAI 官方文档把 slash commands 定义成“用键盘快速控制 Codex 会话”的方式。可以把它们理解成：你不是在给业务任务下指令，而是在控制这次会话本身怎么工作。

这一章不追求把所有 slash commands 背下来，而是先把最高频、最容易影响任务质量的那一批用熟。

8.1 先分清两类输入

在交互式会话里，你输入的内容其实分两类：

• 普通消息：推动业务任务，例如“修这个 bug”“解释这段代码”

• slash commands：改变会话状态，例如切模型、看 diff、切线程、收紧权限

如果把两者混在一起，就会出现典型误用：

• 想看当前权限，却继续追问业务问题

• 想换线程，却在旧线程里不断补充新任务

• 想清空上下文，却只做了终端清屏

8.2 团队最该掌握的高频命令

下面这些命令不是全部内建命令，但已经覆盖团队绝大多数真实工作流。

进入执行前先校准：/status、/mention、/plan

• /status：看当前模型、审批策略、可写目录、token 使用和剩余上下文容量。任务一旦跑偏，先看它，再怀疑模型。

• /mention：把具体文件或目录显式挂进当前会话。它解决的是“让 Codex 看到哪里”，不是“让 Codex 自己到处猜”。

• /plan：进入 plan mode，让 Codex 先给计划再动手。高风险任务、跨模块任务、需求还没敲定时，优先先走这一步。

这组三个命令解决的是同一个阶段问题：在真正修改前，把目标、上下文和运行状态校准好。

做完修改后先看什么：/diff、/review

• /diff：展示当前 Git diff，包括未跟踪文件。只要 Codex 动过文件，你就应该先看 /diff，再决定是否继续。

• /review：让 Codex 审查当前工作区改动，重点找行为风险、边界条件和测试遗漏。它适合做第二轮扫描，不等于自动修复。

常见误区不是不会用，而是顺序反了：很多人先看总结，再看 diff；更稳的顺序应该是先 /diff，再验证，再 /review。

会话边界怎么切：/new、/clear、/fork、/resume

• /new：在同一个 CLI 会话里开启一段新的对话，旧终端内容仍保留。

• /clear：清空终端可见内容，并同时开始一段新对话。它不是简单的清屏，和 Ctrl+L 不一样。

• /fork：从当前对话分叉出一条新线程，保留原上下文去尝试另一条方案。

• /resume：从会话列表里恢复旧线程，适合跨天续做或回到中断任务。

这四个命令都在处理“上下文边界”问题，但目的不同：

• 换题用 /new

• 想要干净屏幕且顺便换题，用 /clear

• 同题分支试方案，用 /fork

• 回到旧任务，用 /resume

运行时怎么临时改：/permissions、/model、/personality

• /permissions：中途调整审批/权限策略。官方 slash commands 页面当前以 /permissions 暴露，/approvals 仍是兼容别名。

• /model：切换当前会话使用的模型。你不需要退出 CLI 再重开一个会话。

• /personality：调整回复风格，例如更简洁或更解释型。它影响表达方式，不替代你对任务目标和约束的说明。

这组命令解决的是“任务做到一半，运行方式要不要变”。它们改的是会话行为，而不是业务目标本身。

长会话和多代理场景：/compact、/agent、/mcp、/init

• /compact：把长会话压缩成摘要，释放上下文窗口。出现重复、遗忘前文、输出开始漂的时候，用它而不是继续硬聊。

• /agent：切换当前活动 agent 线程。只有在使用 subagents 时它才真正高频，但一旦出现并行代理，这个命令就非常关键。

• /mcp：列出当前会话可用的 MCP servers 和工具。遇到“为什么它没调用那个外部工具”时，先用它看是否真的接上。

• /init：在当前目录生成一份 AGENTS.md 骨架，适合首次把仓库规则沉淀下来。

8.3 一条最稳的操作链

对绝大多数编码任务，最稳的链路是：

/status -> /mention -> /plan -> 修改 -> /diff -> 验证 -> /review

这条链路解决了 6 个高频错误：

1. 一上来就动手，没先确认运行状态

2. 没显式给文件上下文

3. 方案没定就直接改

4. 改完不看实际 diff

5. 没有验证步骤

6. 不做风险扫描

8.4 三个容易混淆的点

1. /new 和 /clear 都会开始新对话，但 /clear 会先清空终端可见内容，/new 不会。

2. /permissions 改的是当前会话运行边界，不会替你补充任务说明。

3. /compact 是上下文治理手段，不是“让模型重新理解任务”的万能重置键。

---

9. 权限、沙箱与安全边界

9.1 两层控制：sandbox 与 approval policy

OpenAI 官方文档把 Codex 的安全控制拆成两层：

• sandbox mode：技术边界，决定 Codex 客观上能做什么

• approval policy：交互边界，决定 Codex 什么时候必须停下来征求你同意

这两层要分开理解：

• sandbox 解决的是“允许做到哪里”

• approval policy 解决的是“做之前要不要先问你”

9.2 常见沙箱模式

read-only

适合只读理解、排查、总结、代码审查。它的典型用途是“先看清楚，再决定要不要改”。

workspace-write

适合大多数本地开发任务。它允许 Codex 在当前工作区内编辑文件和执行常规命令，但默认网络是关闭的。

danger-full-access

不建议作为常态默认值。它适合隔离容器、受控 CI runner 或明确知道风险的自动化流程，不适合日常开发环境。

9.3 workspace-write 的几个关键细节

官方文档明确指出，默认 workspace-write 仍然保留一些受保护路径为只读，例如：

• <writable_root>/.git

• <writable_root>/.agents

• <writable_root>/.codex

也就是说，“可写工作区”不等于“工作区里所有内容都可写”。这对团队很重要，因为它能降低误改 Git 元数据、本地代理配置和技能目录的风险。

9.4 常见审批策略

本机 codex --help 当前可见：

• untrusted

• on-failure（已废弃）

• on-request

• never

怎么理解它们：

• untrusted：可信读操作自动放行，不可信或有副作用的命令要你确认

• on-failure：先直接执行，失败后再申请越权；当前已废弃，交互式更建议用 on-request，非交互更建议用 never

• on-request：Codex 自己判断什么时候该申请审批

• never：不弹审批，失败直接返回给代理

9.5 官方推荐的常见组合

官方文档列出的常见组合里，最值得团队默认采用的是：

• 日常开发：workspace-write + on-request

• 只读学习：read-only + on-request

• 非交互只读：read-only + never

--full-auto 是 workspace-write + on-request 的快捷方式。

9.6 网络访问与风险

官方文档说明，本地 workspace-write 默认网络关闭。需要时可在配置里显式打开：

[sandbox_workspace_write]

network_access = true

默认建议：

• 没必要就不要开网络

• 开网络前先想清楚是否真的需要 live 信息

• 任何外部网页内容都应视为不可信输入

9.7 什么时候该收紧权限

这些情况建议保守一点：

• 你还没理解仓库

• 任务本身定义不清

• 可能接触生产配置或敏感文件

• 你无法快速验证结果

• 你准备使用外部网络或 MCP 工具，但还没明确边界

9.8 什么时候不要用高风险组合

不要把 danger-full-access + never 当成“高手模式”。它只是风险更高、摩擦更低，不代表更适合日常。

只有在这几种场景里才值得考虑：

• 隔离容器

• 临时测试环境

• 明确可回滚的自动化任务

• 你已经把 prompt、验证和边界写得非常具体

9.9 受信任目录与 Git 仓库检查

除了 sandbox 和 approval policy，当前 CLI 还有一层容易被忽略的边界：目录信任和 Git 仓库检查。

这层边界主要影响两类事情：

• 项目级 .codex/config.toml 是否生效

• codex exec 之类的非交互任务能不能在当前目录直接运行

当前版本里，一个常见现象是：

• 你明明会用 codex exec

• 命令本身也没写错

• 但在某些目录下仍然直接失败

其背后往往不是模型问题，而是当前目录不被视为受信任工作区，或者它根本不是 Git 仓库。

实务上这样理解最稳：

• 日常项目目录：默认应该是受信任 Git 仓库

• 临时目录、下载目录、随手建的测试目录：不要假设它天然受信任

• 如果你确实要在非 Git 目录里运行 codex exec，当前 CLI 提供了 --skip-git-repo-check

不要把 --skip-git-repo-check 理解成“推荐默认值”。它更像一个明确知道自己在做什么时才用的越过检查开关。

9.10 不要把 --dangerously-bypass-approvals-and-sandbox 当捷径

当前 codex --help 明确把这个参数标成：

• 跳过全部确认提示

• 不使用 sandbox 直接执行命令

• EXTREMELY DANGEROUS

它不是“更高效的专家模式”，而是：

• 直接绕过审批

• 直接绕过沙箱

• 把风险控制责任完全交还给运行环境本身

只有在这类场景里，它才可能有讨论价值：

• 你运行在外部已经严格隔离的容器或 runner 里

• 你明确知道该环境本身已经提供了足够强的边界

• 你接受一旦 prompt 或命令判断出错，后果会直接落到真实环境

对团队成员的默认建议很简单：

• 日常开发机不要把它当默认参数

• 不要因为嫌审批麻烦就开启它

• 只要还能用 workspace-write、on-request、never 等常规组合解决，就不要碰它

---

10. 把高频要求沉淀下来

10.1 AGENTS.md

AGENTS.md 可以理解成“写给代理看的项目协作说明书”。它告诉 Codex：这个仓库怎么跑、哪些规则必须遵守、什么结果才算完成。

如果你发现自己每次都要重复说这些话：

• 优先做最小改动

• 不要无关重构

• 新增行为优先补测试

• 最后要告诉我怎么验证

那这些要求就不该继续写在每轮 prompt 里，而该进入 AGENTS.md。

10.1.1 AGENTS.md 解决什么问题

它解决的不是“文档缺不缺”，而是“Codex 每次会不会重复犯同样的错误”。一份好的 AGENTS.md 可以把高频规则固化成环境默认值。

10.1.2 作用域与优先级

按当前 Codex 行为，AGENTS.md 是按目录树生效的：

• 仓库根目录的 AGENTS.md 作用于整个仓库

• 更深层目录里的 AGENTS.md 可以覆盖更局部的规则

• 离当前工作目录更近的规则优先级更高

因此，团队真正依赖的规则应该放在仓库根目录，而不是只放在个人环境里。

10.1.3 一份好的 AGENTS.md 至少包含什么

• 仓库结构和关键目录

• build / test / lint 命令

• 工程约定

• 禁区或限制

• 完成标准

• 如果出错，优先怎么验证

10.1.4 什么时候该写进 AGENTS.md

适合写进 AGENTS.md 的内容：

• 稳定不变的工程规则

• 全团队默认都适用的要求

• 需要反复提醒代理的验证流程

不适合写进去的内容：

• 一次性任务

• 某个临时 bug 的修复方案

• 和当前仓库无关的个人偏好

10.1.5 最小模板

# AGENTS.md



## Commands

- 安装依赖：npm install

- 启动开发：npm run dev

- 单测：npm test

- lint：npm run lint



## Rules

- 优先最小改动

- 不要无关重构

- 新增行为优先补测试



## Done when

- 相关测试通过

- lint 通过

- 回复包含验证结果

10.2 .codex/config.toml

config.toml 是 Codex 的配置文件，负责保存默认模型、权限、profiles、MCP 等会跨会话复用的设置。

10.2.1 配置文件在哪里

官方文档当前说明：

• 用户级：~/.codex/config.toml

• 项目级：.codex/config.toml

项目级配置只有在该项目被信任时才会生效。

10.2.2 配置优先级

官方文档给出的优先级，从高到低是：

1. CLI flags 与 --config

2. --profile <name>

3. 项目级 .codex/config.toml

4. 用户级 ~/.codex/config.toml

5. 系统级配置

6. 内建默认值

这条优先级非常重要，因为它决定了“为什么我改了配置却没生效”。

10.2.3 什么适合放进配置

适合放进配置里的内容：

• 默认模型

• 默认审批策略

• 默认沙箱模式

• 常用 profiles

• MCP servers

• feature flags

• agents 全局设置

10.2.4 profile 到底是什么

profile 是一组预设配置的名字，不是模型名本身。你可以把它理解成“把一套常用默认值打包后起个名字”。

适合做成 profile 的场景：

• 日常开发

• 深度 review

• 只读探索

• 自动化执行

10.2.5 一个稳妥的起点

model = "<当前默认模型>"

approval_policy = "on-request"

sandbox_mode = "workspace-write"



[profiles.deep-review]

model = "<当前深度审查模型>"

model_reasoning_effort = "high"

approval_policy = "on-request"

sandbox_mode = "workspace-write"

10.2.6 高价值提醒

• 模型名是版本敏感信息，不要在团队模板里永久写死

• --config 的值按 TOML 解析，不是 JSON

• --enable <feature> / --disable <feature> 本质上是一次性 feature flag 覆盖，等价于当前运行上临时设置 features.<name>=true/false

• 使用 --profile 前要先在配置文件里定义对应 profile

• 如果项目未被信任，项目级 .codex/config.toml 会被跳过

---

11. 深度使用技巧

11.1 MCP

MCP 是 Model Context Protocol。对团队成员来说，最重要的理解不是协议名，而是它解决的问题：让 Codex 能安全、结构化地访问仓库之外的工具和上下文。

11.1.1 MCP 解决什么问题

当你需要的信息不在仓库里，而且变化快时，单靠复制粘贴很容易过期或遗漏。MCP 适合这些场景：

• 文档中心

• 设计系统

• issue / ticket 系统

• 数据库只读查询

• 浏览器或设计工具

• 内部知识库

11.1.2 MCP 与 agent 是怎么协作的

从使用者角度，可以把 Codex 与 MCP 的协作过程理解成下面这 6 步：

1. 你在 config.toml 或 CLI 中配置一个或多个 MCP server。

2. Codex 启动后读取这些 server 的工具定义。

3. 当前 agent 在做任务时，会看到这些可用工具的名字、说明和参数结构。

4. 如果它判断某个工具有帮助，就发起一次结构化工具调用。

5. MCP server 代表 Codex 去和外部系统交互，并把结果返回。

6. Codex 再基于这些结果继续推理、修改或回答。

对团队成员最关键的一点是：

agent 不是在“用自然语言和 MCP server 聊天”，而是在读取 MCP 暴露的工具定义后，按结构化参数发起工具调用。

11.1.3 把 MCP 看成“受约束的工具总线”

MCP 在工程上更接近“受约束的工具总线”，而不是“外部聊天接口”。

你可以把一次 MCP 调用拆成 4 层来看：

1. server 暴露工具名、说明、参数结构和可选认证方式。

2. agent 基于当前任务，判断是否值得调用某个工具。

3. Codex 按结构化参数发起调用，而不是把自然语言整段转发出去。

4. 返回结果进入当前线程上下文，再被 agent 用来继续推理、修改或回答。

这意味着：

• 工具描述写得越清楚，agent 越容易选对工具

• 工具面暴露得越宽，agent 越容易误选或多选

• MCP 返回的是“任务输入”，不是“最终答案”

• 你仍然要检查返回结果是否足以支撑后续修改或决策

11.1.4 CLI 和 IDE 如何共享 MCP

官方文档说明，CLI 和 IDE extension 共享同一套 MCP 配置。这意味着你在一个地方配好后，切换客户端通常不需要重新配置。

11.1.5 Codex 支持哪些 MCP server

当前官方文档列出两大类：

• STDIO servers：本地进程启动的 server

• Streamable HTTP servers：通过 URL 访问的 server

HTTP servers 还支持：

• bearer token

• OAuth 登录

11.1.6 如何配置 MCP

最常见两种方式：

1. 用 CLI：

codex mcp add <server-name> -- <stdio-server-command>

codex mcp add <server-name> --url <url>

codex mcp list

codex mcp get <server-name>

codex mcp login <server-name>

2. 直接改配置文件：

[mcp_servers.context7]

command = "npx"

args = ["-y", "@upstash/context7-mcp"]



[mcp_servers.figma]

url = "https://mcp.figma.com/mcp"

bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

11.1.7 配置项里最重要的几个字段

对实际使用最重要的有：

• command / args：启动本地 server

• url：连接 HTTP server

• bearer_token_env_var：从环境变量读 token

• startup_timeout_sec：启动超时

• tool_timeout_sec：单次工具调用超时

• enabled：临时禁用某个 server

• required：启用后必须成功初始化，否则直接报错

• enabled_tools / disabled_tools：限制该 server 暴露给 Codex 的工具集合

11.1.8 团队接 MCP 的推荐顺序

不要一开始就把所有外部系统都接给 Codex。更稳的落地顺序是：

1. 先接只读、价值高、结果容易验证的 server，例如官方文档或内部知识库

2. 再接浏览器、设计系统之类的辅助型工具

3. 最后才考虑会写入外部系统的 server，例如工单状态变更、数据库写操作

这背后的原则很简单：

• 先让 agent 看见更多上下文

• 再让 agent 拥有更多动作

• 写权限永远比读权限更晚开放

11.1.9 MCP 与安全边界

MCP 很强，但也因此需要约束：

• 能不用就不要接太多 server

• 先接 1 到 2 个高价值工具

• 对高权限 server 做工具白名单

• 把密钥放环境变量，不要写进文档和提交内容

• 明确哪些 server 允许写，哪些 server 只允许读

11.1.10 MCP 什么时候不该用

这些情况不建议急着上 MCP：

• 只是一次性查询

• 外部信息完全可以人工贴进 prompt

• 团队还没想清楚权限边界

• 你并不清楚这个外部工具会暴露哪些操作

11.2 Skills

skill 是把某类高频任务整理成可复用工作流。它的价值不在于“多一个说明文件”，而在于把反复出现的任务做成稳定模板，让 Codex 少走弯路、少重复问、少依赖临时 prompt。

11.2.1 Skills 最适合解决什么问题

适合做成 skill 的工作，通常满足 3 个条件：

1. 任务高频重复出现

2. 执行顺序比较稳定

3. 需要附带脚本、参考资料或检查清单

典型例子：

• 日志排查

• PR 风险清单审查

• 发布说明生成

• 标准化 debugging

• 迁移计划分解

如果某项工作每次都要重复说“先看哪里、再跑什么、最后按什么格式输出”，它就开始有 skill 的价值了。

11.2.2 Skills、AGENTS.md、prompt、MCP 分别管什么

很多团队第一次引入 skills 时，最容易和其他机制混用。可以这样分：

• AGENTS.md：当前仓库长期有效的规则，例如命令、约束、完成标准

• prompt：这一次任务的目标、上下文和边界

• skill：某一类任务的标准流程模板

• MCP：让 Codex 接入仓库外部工具和上下文

简单说：

• 仓库默认规则，写进 AGENTS.md

• 单次任务目标，写进 prompt

• 可复用套路，做成 skill

• 外部能力接入，用 MCP

如果把“项目规则”塞进 skill，或者把“某次临时任务”塞进 AGENTS.md，最后都会变得难维护。

11.2.3 Skills 是怎么被匹配和加载的

官方文档说明，skills 采用 progressive disclosure：

• Codex 先只看 skill 的元数据，例如 name、description

• 只有当它判断当前任务匹配时，才会继续加载完整的 SKILL.md

这意味着 skill 成败往往不取决于正文写得多长，而取决于前两件事：

• description 是否把触发条件写清楚

• skill 的职责是否足够单一

常见失败不是“skill 没生效”，而是：

• description 太泛，任何任务都像能匹配

• skill 范围太大，一个 skill 试图包办 4 种不同工作

• SKILL.md 讲流程很多，但没讲输入、输出和停止条件

11.2.4 一个 skill 的推荐结构

my-skill/

SKILL.md

scripts/

references/

assets/

agents/openai.yaml

其中：

• SKILL.md 必需

• scripts/ 可放自动化辅助脚本

• references/ 可放规范、样例、接口说明

• assets/ 可放固定资源

• agents/openai.yaml 可选，用来补 UI 元数据和策略

结构本身不重要，重要的是让 skill 在“说明、工具、参考资料”之间有清晰分工。

11.2.5 Skills 放在哪里，以及怎么规划作用域

官方文档说明，Codex 会从这些位置发现 skills：

• 仓库内：从当前工作目录开始，向上扫描每一级目录下的 .agents/skills

• 用户级：~/.codex/skills

• 管理级：/etc/codex/skills

• 系统内置：Codex 自带 skills

团队落地时，推荐这样规划：

• 团队共享 skill：放仓库根目录 .agents/skills/

• 某个子模块专用 skill：放模块目录附近，缩小作用域

• 个人实验 skill：先放 ~/.codex/skills/，不要急着进仓库

这样做的好处是：

• 公共技能不会和私人实验混在一起

• 模块技能不会污染整个仓库

• 团队更容易判断“为什么这个 skill 会在这里被发现”

11.2.6 设计一个好 skill 的方法

设计 skill 时，按下面 5 步走最稳：

1. 先定义触发条件

2. 再定义输入和输出

3. 再写执行顺序

4. 再补脚本和参考资料

5. 最后写不该使用的边界

一个好的 skill，至少要让 Codex 知道：

• 什么时候该用它

• 输入通常长什么样

• 它要先看哪些资料

• 它要执行哪些步骤

• 什么结果算完成

• 什么情况下应该停止并回到主线程

11.2.7 一个完整案例

下面是一个适合团队共享的 log-triage skill 的思路：

适用场景：

• 成员给出一段错误日志，希望先判断问题类型，再给最小排查路径

建议在 description 里明确写：

当用户要求分析应用日志、定位报错来源、判断是否需要继续查看代码或配置时使用。

不要直接给修复结论；先做分类、提取关键信息、列出下一步排查建议。

SKILL.md 的核心流程可以写成：

1. 先识别日志来源和时间范围

2. 抽取错误关键词、堆栈入口和重复模式

3. 判断是配置问题、代码问题、权限问题还是外部依赖问题

4. 输出最小排查路径

5. 如果需要进一步查看仓库文件，再明确告诉主线程应该看哪些路径

这个案例的关键不是日志本身，而是它把 skill 的边界卡得很清楚：

• 它负责“分类和排查建议”

• 它不直接替代真正的修复任务

11.2.8 什么时候不要做成 skill

这些情况不建议急着做 skill：

• 一次性任务

• 描述仍然频繁变化

• 任务边界模糊，连你自己都还没想清楚

• 实际上只是项目规则，应该进 AGENTS.md

• 实际上只是工具接入问题，应该用 MCP

11.2.9 本节记住这三点

• skill 解决的是“流程复用”，不是“项目规则”

• description 决定 skill 是否容易被正确触发

• 第一版 skill 只解决一类代表性任务，不要追求大而全

11.3 Subagents

subagent 是由当前主代理分出去的辅助代理。它最核心的价值不是“更像多人协作”，而是让同一任务里的可并行部分独立推进，再由主代理统一收口。

11.3.1 Subagents 最适合解决什么问题

官方文档给出的典型场景包括：

• 大仓库探索

• 多维度并行 review

• 多步骤计划拆分

• 主线程做实现，子线程做验证或查文档

这些场景有一个共同点：子任务边界清楚，而且主线程可以在等待时继续做别的事。

11.3.2 主代理和子代理怎么分工

可以把它理解成一个很简单的结构：

• 主代理：负责定目标、拆任务、汇总结果、做最后决策

• 子代理：负责执行一个边界清楚的子任务

真正容易失败的地方，不是“子代理能力不够”，而是主代理派工不清楚。主线程如果只说“你去看看”，子线程往往会把范围越做越大。

11.3.3 什么任务适合并行，什么任务不适合

适合并行：

• 一个线程读文档，一个线程读代码

• 一个线程做实现，一个线程做只读验证

• 多个线程分别 review 不同风险维度

不适合并行：

• 多个代理同时改同一批文件

• 需要一步结果才能决定下一步方向的任务

• 你自己都还没拆清输入、输出和责任边界的任务

一个简单判断法：

如果两个子任务的产出可以独立成立，再由主线程汇总，它们才适合并行。

11.3.4 Subagents 和普通线程、/fork 的区别

三者经常被混淆：

• 普通线程：你手动开的独立会话，彼此没有自动汇总关系

• /fork：从现有上下文分一条新路，适合试方案分支

• subagent：由主代理统一派工、等待和汇总的子任务线程

所以：

• 想自己切到另一条思路，用 /fork

• 想让 Codex 帮你并行拆活，用 subagents

• 想跨天回到旧任务，用 /resume

11.3.5 一个好子任务应该怎么写

派给子代理的任务说明，至少要有这 4 项：

• Goal：这个子代理只负责什么

• Ownership：它能读什么、能改什么

• Constraints：不能越界做什么

• Done when：输出长什么样就算完成

一个比“去看一下登录问题”更稳的派工是：

子代理只负责阅读 auth 相关代码，不修改文件。

请输出：

1. 登录入口调用链

2. 可能导致会话失效的两个点

3. 需要主线程进一步验证的文件路径

这种写法的好处是，子代理不会误以为自己也该去改代码或做最终结论。

11.3.6 官方工作方式中的关键点

根据官方文档：

• Codex 只会在你明确要求时开子代理

• 子代理默认并行运行

• 主代理负责等待、汇总和关闭线程

• 子代理会消耗额外 token

这几点决定了一个现实结论：

• subagents 不是“默认更高级的模式”

• 它是成本更高、但在任务切得好时更有效的模式

11.3.7 内建 agent 类型和自定义 agents

官方文档当前列出 3 个内建 agent：

• default：通用默认代理

• worker：偏执行和实现

• explorer：偏探索和阅读

如果团队想长期复用某种分工，也可以定义 custom agents：

• 用户级：~/.codex/agents/

• 项目级：.codex/agents/

每个 agent 是独立 TOML 文件，至少包含：

• name

• description

• developer_instructions

还可以附加：

• model

• model_reasoning_effort

• sandbox_mode

• mcp_servers

• skills.config

11.3.8 并发和权限怎么理解

除了单个 custom agent 文件外，官方文档还支持在 [agents] 下配置全局限制，例如：

[agents]

max_threads = 6

max_depth = 1

这两个配置控制的是：

• max_threads：最多允许多少个 agent 线程同时存在

• max_depth：子代理还能不能继续再开子代理

权限方面，官方文档明确说明：

• 子代理继承当前 sandbox policy

• 在交互式会话里，审批请求可能来自非当前可见线程

• 在非交互流程里，如果子代理需要新的审批但无法弹窗，该动作会失败并回传给父线程

这意味着你给主线程多大的边界，子线程基本也只能在这个边界里工作。

11.3.9 一个实战拆法

以“修复登录后偶发掉线问题”为例，更稳的拆法是：

1. 主线程：先定计划，明确本轮只做最小修复

2. 子代理 A：只读分析认证和 session 调用链

3. 子代理 B：只读检查最近相关测试和回归风险

4. 主线程：基于 A、B 的结果决定是否修改

5. 如果要改代码，由主线程统一实施，再做验证和 review

这类拆法的重点是：

• 子代理主要负责收集和压缩信息

• 真正改代码的责任尽量集中在主线程

11.3.10 什么时候不要用 subagents

这些情况不适合：

• 小任务

• 强耦合、必须串行推进的工作

• 多个代理会改同一批文件

• 你自己都还没拆清子任务边界

11.3.11 本节记住这三点

• subagents 的价值在“并行且可汇总”，不是“默认更强”

• 子任务边界不清，subagents 只会把混乱放大

• 主线程最好负责最后的整合、修改和交付

11.4 codex exec

codex exec 是非交互执行模式。它适合把一条任务写清楚，然后让 Codex 一次性执行并输出结果，而不是在终端里来回多轮交互。

11.4.1 什么样的任务适合 codex exec

官方文档给出的典型场景：

• CI

• 定时任务

• 预合并检查

• 需要可管道消费的输出

• 希望显式固定权限和沙箱的自动化任务

从任务形状上看，更适合 exec 的任务通常有这几个特点：

• 输入固定

• 不依赖你中途澄清

• 完成标准明确

• 最终结果可以一次性交付

11.4.2 什么样的任务不适合 codex exec

这些情况更适合交互式会话：

• 目标本身还在探索

• 你预期会来回澄清需求

• 你要边看 diff 边改变方向

• 你需要中途频繁手动授权和决策

一个简单判断法：

如果任务更像“工单执行”，优先 codex exec；如果更像“边探索边决策”，优先交互式会话。

11.4.3 输出通道怎么理解

官方文档说明：

• 进度流写到 stderr

• 最终 agent message 输出到 stdout

这决定了你在脚本或管道里不能把两者混为一谈。一个常见误区是把滚动进度当成最终结果去解析。

例如：

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

这里真正进入管道的是最终消息，不是中间进度。

11.4.4 常用参数与输出控制

codex exec "summarize the repository structure"

codex exec --ephemeral "triage this repository and suggest next steps"

codex exec --json "summarize the repo structure"

codex exec -o ./last-message.txt "summarize the changes"

这些参数各自解决：

• --ephemeral：不要把 session rollout 落盘

• --json：输出 JSONL 事件流，给脚本消费

• -o / --output-last-message：把最终消息额外写入文件

11.4.5 三种常见接入方式

本地脚本：

• 适合批量摘要、文档生成、日志整理

CI 检查：

• 适合预合并检查、变更总结、附加风险扫描

平台任务：

• 适合被上层系统调用，并记录执行轨迹

无论哪种方式，核心都一样：任务必须写成一次性可执行说明，而不是依赖多轮澄清。

11.4.6 权限建议

官方文档说明：

• codex exec 默认在 read-only 沙箱运行

• 允许编辑可用 --full-auto

• 更宽权限可用 --sandbox danger-full-access

默认建议：

• 自动化先从最小权限开始

• 需要写权限时，优先 workspace-write

• 只有在隔离环境中才考虑 danger-full-access

11.4.7 机器可读输出和 MCP 影响

--json 会把 stdout 变成 JSONL 事件流，适合：

• 脚本后处理

• 任务审计

• 平台侧记录 agent 执行轨迹

官方文档还说明：如果某个启用的 MCP server 被标记为 required = true，而它初始化失败，那么 codex exec 会直接报错，而不是默默跳过。

这对自动化很重要，因为它能避免“少了关键工具还继续跑，结果输出看似正常但其实少信息”。

11.4.8 本节记住这三点

• codex exec 适合一次性交付，不适合边聊边改

• 要把 stderr 进度和 stdout 最终结果分开理解

• 自动化默认先用最小权限，再逐步放开

11.5 codex review

codex review 是把“审查改动”独立成一个命令。它的价值不是代替人做最后裁决，而是强制你对当前 diff 做一次系统化风险扫描。

11.5.1 codex review、/review、人工 review 的分工

• /review：当前交互式线程里的即时审查，适合任务结束后马上扫一遍

• codex review：独立起一个非交互审查任务，适合脚本、自检、批量场景

• 人工 review：负责业务语义、架构取舍、上线风险和最终合并判断

这三者不是替代关系，而是不同层级的审查手段。

11.5.2 当前本机可用参数

本机 codex review --help 已验证当前支持：

• --uncommitted

• --base <branch>

• --commit <sha>

• --title <title>

11.5.3 典型用法

codex review --uncommitted

codex review --base main

codex review --commit HEAD~1

这三种方式分别对应：

• 看当前未提交改动

• 看相对某分支的变更

• 看某个提交本身带来的差异

11.5.4 怎么读 review 输出

无论输出是问题列表、摘要还是自然语言评论，先看 4 件事：

1. 它指出的风险是否对应真实 diff

2. 它有没有明确指出文件位置或行为位置

3. 它解释的是“为什么有风险”，还是只给模糊建议

4. 它有没有指出测试、回归或边界条件缺口

如果这 4 件事里有两件说不清，就不要直接把 review 结论当真。

11.5.5 什么时候要给 review 加额外指令

这些场景建议补一条聚焦说明：

• 希望重点看安全问题

• 希望重点看边界条件

• 希望重点看性能或回归风险

• 只想看某个模块的差异

比起泛泛说“帮我 review”，更好的写法是：

重点关注登录态边界条件、错误回滚路径和潜在回归。

11.5.6 codex review 最容易被误用的地方

常见误用包括：

• 把它当成自动修复工具

• 把它当成唯一合并依据

• 它指出问题后，不回看 diff 就直接接受

• 它没指出问题，就误以为改动绝对安全

11.5.7 本节记住这三点

• review 的输入是 diff，判断必须回到 diff 本身

• codex review 适合独立自检，不替代人工 code review

• 好的 review 输出一定能说清“风险在哪里，为什么危险”

11.6 会话持久化、resume、fork 与跨设备

这一节解决的是很多成员迟早会遇到的问题：会话到底保不保存、保存在哪里、能不能继续、能不能换电脑继续。

11.6.1 当前版本里会话是怎么保存的

从本机当前版本行为看，交互式会话默认会被记录下来，因此你才能使用：

codex resume --last

codex fork --last

当前本机可见的本地记录目录是：

~/.codex/sessions

这里最重要的结论不是路径本身，而是：

• 当前版本默认有本地持久化

• resume 依赖的是本机已记录的会话

• 它不是“账号级自动同步聊天记录”

11.6.2 resume、fork 和普通新会话分别解决什么问题

• codex resume：继续一个已经存在的本地会话

• codex fork：基于一个旧会话分出一条新分支

• 重新运行 codex：从空白会话重新开始

可以这样理解：

• 想接着昨天做到一半的任务，用 resume

• 想保留旧思路，再试另一条路，用 fork

• 想彻底换题，不要污染旧上下文，重新开会话

当前 help 里，resume 还支持：

• --last

• --all

• --include-non-interactive

这意味着它不只是“恢复最近一次 TUI”，而是可以在更大的本地记录范围里挑选。

11.6.3 --ephemeral 会影响什么

在 codex exec 里，--ephemeral 的含义是：

• 这次非交互执行不要把 session rollout 落盘

因此不要把它理解成“更快”或“更轻量”的同义词。它真正影响的是：

• 之后还能不能把这次非交互记录纳入本机历史

• 你是否还能在本机记录中继续追踪这次执行

11.6.4 跨设备应该怎么理解

当前版本最容易被误解的一点是：本地 session 持久化，不等于跨电脑自动同步。

更准确地说：

• 本地 resume 解决的是“这台机器上的会话延续”

• 它不是“我在电脑 A 开的 thread，电脑 B 自动接着用”

当前没有看到官方提供的“导入另一台电脑本地 session 继续聊”的标准入口。因此：

• 不要把 resume 当成跨设备同步能力

• 不要把本地 ~/.codex/sessions 当成稳定的跨机交换格式

• 如果只是要延续工作，优先同步代码、diff、文档和任务摘要，而不是指望会话原样迁移

11.6.5 什么时候会对会话机制产生误判

常见误判包括：

• 以为“本地保存”就等于“云端同步”

• 以为把某个 session 文件拷到另一台机器就一定能 resume

• 以为 fork 和重新开新会话没有区别

更稳的工作方式是：

• 代码状态靠 Git

• 项目规则靠 AGENTS.md

• 任务上下文靠 prompt、diff 和必要摘要

• 本地会话只作为当前机器上的便利能力

11.6.6 本节记住这三点

• 当前版本默认会保存本地会话

• resume / fork 主要解决本机会话延续，不是跨设备同步

• --ephemeral 会让非交互执行不落盘

11.7 codex cloud

codex cloud 是当前 CLI 里的实验性能力。它不是“本地对话的云同步版”，而是“把任务提交到 Codex Cloud，再查看状态、看 diff、把结果应用回本地”。

11.7.1 codex cloud 解决什么问题

从当前 help 看，它的核心能力是：

• 提交云端任务

• 查看云端任务状态

• 列出任务

• 查看某个任务的 diff

• 把某个任务的 diff 应用回本地

也就是说，它更像“远程任务执行流”，而不是“跨设备恢复聊天现场”。

11.7.2 当前可见命令

codex cloud exec --env <ENV_ID> "your task"

codex cloud list

codex cloud status <TASK_ID>

codex cloud diff <TASK_ID>

codex cloud apply <TASK_ID>

这些命令分别对应：

• exec：提交一个新云任务

• list：查看任务列表

• status：看某个任务当前状态

• diff：看某个任务产出的统一 diff

• apply：把该 diff 应用到本地工作树

11.7.3 它和本地会话的区别

这是最关键的区分：

• 本地会话：以 thread 和本机记录为核心

• codex cloud：以 task、status、diff、apply 为核心

因此，不要把 cloud 理解成：

• “我本地聊天会自动同步到云”

• “我换台电脑就能从本地 thread 接着聊”

更准确的理解是：

• cloud 适合管理远程任务产出

• resume 适合继续本地会话

11.7.4 什么时候适合用 cloud

• 你需要把任务提交到云端环境

• 你更关心任务状态和 diff，而不是保留完整本地对话流

• 你最终只需要把产出差异拿回本地应用

11.7.5 什么时候不要把它当默认方案

• 你只是想继续当前机器上的本地 thread

• 你只是想跨电脑复用上下文，而不是运行云任务

• 团队还没想清楚环境、权限和 task ID 的管理方式

11.7.6 本节记住这三点

• codex cloud 是实验性能力

• 它管理的是云任务，不是本地 thread 同步

• 它的核心工作流是 exec -> status/list -> diff -> apply

11.8 其他重要 CLI 能力

这一节收纳的是不一定每天都用，但在团队内迟早会碰到的能力。它们不一定值得单独成章，但不应该在总指南里缺席。

11.8.1 登录与账号状态：login、logout、login status

当前 help 可见：

• codex login

• codex login status

• codex logout

当前 codex login 还提供：

• --with-api-key

• --device-auth

对大多数成员，最重要的是：

• 会看当前是否已登录

• 知道如何清理旧登录状态

• 不把“终端当前可用”误当成“账号状态一定正确”

11.8.2 功能开关：features

当前可见子命令：

• codex features list

• codex features enable

• codex features disable

它解决的是“某个功能开没开”，而不是“这个功能该不该长期默认开启”。团队使用时应把它看作：

• 能力开关检查入口

• 某些实验性或渐进发布能力的控制面

不要把 feature flag 写成永久真理，因为它天然是版本敏感和阶段敏感的。

11.8.3 Shell 补全：completion

codex completion zsh

codex completion bash

它的作用很单纯：

• 为 shell 生成补全脚本

这不是核心工作流能力，但对高频 CLI 用户是有价值的效率增强。

11.8.4 补丁应用：apply

当前 help 显示：

codex apply <TASK_ID>

它的作用是：

• 把某个 Codex agent 产出的 diff 以 git apply 的方式应用到本地工作树

它不是日常最常用入口，但对“任务产出 diff，再回到本地落地”这类流程很重要。

11.8.5 桌面端与平台命令：app、app-server、mcp-server、debug

这些命令更偏平台接入或高级使用：

• codex app：启动桌面端

• codex app-server：实验性 app server 相关工具

• codex mcp-server：把 Codex 本身作为 MCP server 启动

• codex debug：调试相关工具

对普通团队成员来说：

• 知道这些命令存在就够了

• 日常开发一般不需要把它们当主入口

对平台、插件、IDE 或集成能力维护者来说，这些命令才值得深入研究。

11.8.6 工作根与附加可写目录：-C / --cd、--add-dir

这两个参数看起来不像“能力”，但它们实际会影响会话对仓库的理解边界。

• -C / --cd <DIR>：告诉 Codex 以指定目录作为主工作根

• --add-dir <DIR>：在主工作根之外，再追加一个可写目录

最适合的场景：

• 你在任意目录下启动，但目标仓库在别处

• 你要同时改主仓库和相邻 package

• 代码生成或构建输出恰好落在主工作区之外

最容易踩的坑：

• 把 shell 当前目录误当成 Codex 的实际工作根

• 用 --add-dir 一路把可写范围放到过大，最后失去边界感

更稳的原则是：

• 主工作根尽量只指向当前任务真正所在仓库

• --add-dir 只加这次任务确实需要写入的目录

11.8.7 本地开源模型入口：--oss、--local-provider

当前 codex --help 对这两个参数的含义说得很明确：

• --oss：把模型提供方切到本地开源模型服务，并验证本地 LM Studio 或 Ollama 服务可用

• --local-provider：显式指定本地 provider；当前 help 中可见值是 lmstudio、ollama

这组参数解决的是：

• 你想接本地模型服务

• 你想在不同 provider 间切换

• 团队需要评估“本地 provider 是否满足当前任务”

不要把它们理解成：

• “开启后就等于离线工作流完全成立”

• “开启后 sandbox、审批、MCP 行为也一起切换”

• “本地 provider 和官方托管模型一定具备相同能力边界”

更准确的理解是：

• 这改的是模型来源

• 不改任务目标

• 不自动改安全边界

11.8.8 远程 App Server 接入：--remote、--remote-auth-token-env

当前 help 说明：

• --remote <ADDR>：把 app-server-backed TUI 连接到远程 app server 的 websocket 地址

• --remote-auth-token-env <ENV_VAR>：从指定环境变量里读取 bearer token，用于该远程连接

这组参数很容易和其他概念混淆。要分清：

• --remote：是“把当前 TUI 连到一个远程 app server”

• codex cloud：是“管理云任务和 diff/apply 流程”

• resume：是“继续当前机器上的本地会话”

所以，不要把 --remote 理解成：

• 跨设备自动同步 thread

• cloud 的别名

• 任何远程执行能力的总开关

对大多数普通成员，这组参数知道存在即可。真正需要深入的是维护远程接入、平台适配或内部托管环境的人。

11.8.9 终端显示模式：--no-alt-screen

当前 help 解释得很直接：它会禁用 alternate screen，让 TUI 以内联方式运行，并保留终端 scrollback。

这解决的不是 agent 能力问题，而是终端体验问题：

• 你想保留完整滚动历史

• 你在严格遵守 xterm 语义的终端复用器里工作

• 你希望会话输出更容易被回看、复制或录屏

因此，遇到“Codex 一启动我就看不到之前终端内容”这类问题时，优先想到的是 --no-alt-screen，而不是误判成会话丢失。

11.8.10 顶层 feature flag 快捷覆盖：--enable、--disable

除了 codex features enable/disable 和配置文件，当前 CLI 还提供了顶层快捷参数：

• --enable <FEATURE>

• --disable <FEATURE>

help 已经说明，它们等价于：

• -c features.<name>=true

• -c features.<name>=false

这意味着它们最适合：

• 对单次运行临时开关某个 feature

• 验证某项实验能力在当前任务里是否值得开启

• 不想立刻改动长期配置文件时做一次性覆盖

团队层面不要把这种临时参数当成长期规范。长期默认值仍然应回到配置文件或团队约定里管理。

11.8.11 本节记住这三点

• CLI 里还有一批低频但重要的能力，不应被总指南遗漏

• features、app-server、cloud、--remote、--oss 这类能力都带有明显版本或环境依赖属性

• 团队手册应至少说明这些命令和参数是什么、谁该关心、谁可以先忽略

---

12. 成员最容易踩的坑

12.1 任务定义问题

• 上来就让 Codex 大改，自己也没讲清楚目标

• 不写完成标准，只看最后总结

• 一个线程里混多个主题，最后谁都没讲清楚

12.2 权限与会话问题

• 不存在的 profile 直接拿来执行

• 还没建立规范就长期开高权限

• 多个线程同时改同一组文件

12.3 验证与版本问题

• 不看 /diff，只看回复

• 长期规则不进入 AGENTS.md

• 把版本敏感信息写成永久真理，例如固定模型名、固定功能状态

---

13. 排错建议

这一章按统一结构组织：先看症状，再看原因类别，再按顺序排查。不要一出问题就直接怀疑“模型不行”，多数问题都能落回配置、权限、上下文或任务描述。

13.1 profile not found

症状

• 执行 codex --profile <name> 后直接报找不到 profile

高频原因

• 你还没在 config.toml 中定义这个 profile

• profile 名拼错

• 你改的是项目级配置，但该项目配置没有生效

检查顺序

1. 打开当前生效的 config.toml

2. 确认 [profiles.<name>] 是否存在

3. 确认名字是否完全一致

4. 如果改的是项目级配置，确认该项目是否被信任

修复动作

• 先定义 profile，再使用 --profile

• 团队文档里不要把未定义 profile 当成开箱即用命令

13.2 命令能解释，不能修改

症状

• Codex 能读文件、解释代码，但始终不动文件

高频原因

• 当前是 read-only

• 当前审批策略过于保守

• 你没有明确说允许修改什么

• 你给的是分析型 prompt，不是执行型 prompt

检查顺序

1. 看 /status 或启动参数，确认当前 sandbox

2. 看审批策略是否限制过严

3. 回看 prompt，确认有没有写目标、范围、完成标准

4. 确认是不是你自己要求了“先不要改”

修复动作

• 切到合适的写权限

• 把“要改哪里、改到什么程度、怎么验证”写清楚

• 如果你只想先分析，就接受它不会修改这一事实

13.3 改动过大

症状

• 本来想做最小修复，结果改了一大片无关代码

高频原因

• prompt 没写“最小改动”

• 没限制文件范围

• 没先 /plan

• 让它顺手“优化一下”或“顺便整理一下”

检查顺序

1. 回看原始 prompt 有没有写清边界

2. 看 /diff 到底扩散到哪些文件

3. 判断扩散是任务要求导致，还是 Codex 自行扩展

修复动作

• 重开一个更干净的线程

• 明确限制文件范围和禁止无关重构

• 先让它解释方案，再决定要不要继续修改

13.4 结果看起来对，但你不放心

症状

• 回复说得很像对的，但你不敢直接采纳

高频原因

• 缺少验证

• 缺少 diff 复核

• 任务本身存在隐含边界条件

• 你把“表达得像对”误当成“已经被证明正确”

检查顺序

1. 先看 /diff

2. 再看验证命令和验证结果

3. 再看 /review 输出

4. 必要时回到关键文件手动复核

修复动作

• 不要继续追问“你确定吗”

• 改成要它给验证命令、依据和风险点

• 高风险改动补最小相关测试

13.5 MCP server 没连上

症状

• 会话里看不到某个外部工具

• 调用了相关任务，但 Codex 没有使用 MCP

• codex exec 因 required MCP 初始化失败而直接中断

高频原因

• URL 写错

• token 环境变量没设置

• 本地 stdio server 启动命令不存在

• 超时太短

• 工具白名单或权限范围没配清楚

检查顺序

1. codex mcp list 看 server 是否存在、是否启用

2. codex mcp get <name> 看配置详情

3. 如果是 HTTP server，检查 URL 和 token 环境变量

4. 如果是 OAuth / login 型 server，确认是否已完成 codex mcp login <name>

5. 如果启用了 required = true，确认它是不是直接阻断了整次任务

修复动作

• 先让配置能稳定初始化，再让业务任务依赖它

• 对高权限 server 先做白名单，再扩大能力

13.6 子代理结果很乱

症状

• 多个子代理给出互相打架的结论

• 结果很多，但主线程无法汇总

• 子代理越做越偏，甚至改到不该改的地方

高频原因

• 子任务切得不够清楚

• 多个代理在改同一批文件

• 父线程给的目标太模糊

• 把本应串行的工作强行并行化

检查顺序

1. 回看主线程派工是否写清 Goal / Ownership / Done when

2. 看不同子代理是否存在写入冲突

3. 判断这些任务是否真的能独立成立

修复动作

• 让主线程先定计划

• 子代理只做边界清楚的子任务

• 把最终整合、修改和交付收回主线程

13.7 codex exec 在自动化里表现异常

症状

• 脚本拿不到想要的结果

• 输出格式不稳定

• 任务在自动化里失败，但交互式会话里能跑

高频原因

• 默认落在 read-only

• 把 stderr 进度误当成最终输出

• 下游没有按 JSONL 读取 --json

• required = true 的 MCP 初始化失败

检查顺序

1. 确认当前 sandbox 和 approval 组合

2. 确认脚本读的是 stdout 还是 stderr

3. 如果用了 --json，确认下游按 JSONL 读取

4. 检查 required MCP 是否初始化成功

修复动作

• 先在本地用最小样例跑通

• 明确输出通道和输出格式

• 不要把交互式心智直接搬进自动化

13.8 登录状态看起来不对

症状

• 你以为自己已经登录，但某些命令仍然提示认证问题

• 换了账号或环境后，CLI 行为和预期不一致

高频原因

• 本机残留旧登录状态

• 你以为当前是浏览器登录，实际正在用 API key

• 终端和组织要求的账号体系不一致

检查顺序

1. 先看 codex login status

2. 回看当前机器是不是残留了旧认证

3. 确认团队要求的是哪种登录方式

修复动作

• 状态不清时，优先先确认再继续跑任务

• 必要时用 codex logout 清掉本机旧认证后重新登录

13.9 codex exec 提示目录不受信任或不是 Git 仓库

症状

• 在某些目录里执行 codex exec ... 会直接失败

• 报错中提到 trusted directory 或 --skip-git-repo-check

高频原因

• 当前目录不是 Git 仓库

• 当前目录没有被视为受信任工作区

• 你把临时目录当成了正式项目目录使用

检查顺序

1. 确认当前目录是不是项目仓库

2. 判断这个目录是不是团队正式工作区

3. 再决定是否真的需要 --skip-git-repo-check

修复动作

• 优先回到真正的项目目录运行

• 只有明确知道自己在做什么时，才用 --skip-git-repo-check

13.10 resume 找不到你以为存在的旧会话

症状

• 你记得之前做过任务，但 codex resume 里没看到想要的记录

高频原因

• 你记错了机器

• 你当时跑的是非交互任务

• 你当时用了 --ephemeral

• 当前筛选范围里没显示全部记录

检查顺序

1. 先确认是不是同一台机器

2. 判断当时是交互式还是非交互式执行

3. 回想是否用了 --ephemeral

4. 必要时看 resume 的其他筛选选项，例如 --all、--include-non-interactive

修复动作

• 不要把“我记得做过”直接等同于“本地一定能 resume”

• 对重要任务，除了本地会话外，还要保留代码状态和任务摘要

13.11 换电脑后找不到之前的本地会话

症状

• 你在电脑 A 上做过任务，换到电脑 B 后找不到同一个本地 thread

高频原因

• 本地会话默认是按机器保存，不是自动跨设备同步

• 你把 resume 当成了账号级云同步能力

检查顺序

1. 先确认你找的是不是本地会话

2. 再确认你是否其实需要的是代码状态而不是聊天记录本身

3. 判断这个场景更适合本地 resume，还是 codex cloud

修复动作

• 代码同步靠 Git

• 上下文迁移靠 prompt、diff、文档和摘要

• 不要把本地 session 当成跨设备工作流核心

13.12 cloud 有结果，但本地没变化

症状

• 你在 codex cloud 里看到了任务、状态或 diff，但本地代码没有变化

高频原因

• 你只看了 status 或 diff

• 你还没有执行 codex cloud apply <TASK_ID>

• 你把 cloud 当成了自动回写本地的能力

检查顺序

1. 确认任务是不是已经完成

2. 看有没有可用 diff

3. 判断你是不是还没执行 apply

修复动作

• 把 cloud 理解成 task/diff/apply 流程，而不是“自动同步到本地”

• 如果目标只是继续本地 thread，不要误用 cloud

---

14. 推荐给每个成员的最小工作流

这一章给的是“够用且稳定”的最小工作流。你不需要一开始把所有高级机制都用上，但至少要把自己的那一条链路用熟。

14.1 第一次上手的成员

适用场景：

• 第一次接触 Codex

• 第一次进入一个陌生仓库

标准操作链：

1. read-only 启动

2. 让 Codex 先解释一个真实模块

3. 要它指出风险点和调用链

4. 看代码交叉确认

5. 再决定要不要进入修改任务

完成标准：

• 你能说清入口文件、关键调用链和两个主要风险点

• 你知道当前会话为什么还不该直接改代码

不要这样做：

• 一上来就让它修复杂 bug

• 还没确认权限边界就开高权限

14.2 日常开发成员

适用场景：

• 已经知道要修什么

• 需要最小改动完成任务

标准操作链：

1. 用结构化 prompt 说明目标、上下文、约束、完成标准

2. /status

3. /mention

4. /plan

5. 修改

6. /diff

7. 验证

8. /review

完成标准：

• 你看过实际 diff，而不是只看总结

• 你做过最小相关验证

• 你知道本轮修改的边界和剩余风险

不要这样做：

• 只给一句“帮我修一下”

• 改完只看总结，不看 diff

14.3 提交前自检的成员

适用场景：

• 代码已经改完

• 希望在提交前再扫一遍风险

标准操作链：

1. 自己先看一遍 diff

2. 跑最小相关验证

3. codex review --uncommitted

4. 对 review 发现的问题回到 diff 和代码里复核

5. 再决定是否提交

完成标准：

• 你能说明当前改动的主要风险点

• 你知道哪些问题已修、哪些只是建议未采纳

不要这样做：

• 让 review 代替你自己看 diff

• 它没报问题就直接认为可以上线

14.4 文档和规范维护者

适用场景：

• 更新团队手册

• 调整 AGENTS.md、skills、配置模板

标准操作链：

1. 先确认哪些规则是长期有效的

2. 把仓库规则放进 AGENTS.md

3. 把可复用流程放进 skill

4. 把单次任务留在 prompt

5. 最后核查命令、路径和版本敏感项

完成标准：

• 规则、流程、单次任务三者没有混写

• 文档里的命令、路径和版本表述都能落地

不要这样做：

• 把一次性经验写成永久规则

• 把未验证命令写进团队文档

14.5 每个成员都应该练熟的一条基础链路

先解释 -> /plan -> 修改 -> /diff -> 验证 -> /review

如果你还在入门阶段，先把这条链路练熟，再去使用 skill、MCP、subagents 或自动化接入。

---

15. 术语解释

这一章不是词典，而是帮助新成员建立不会混淆的基本心智。每个术语都按同一格式说明：定义、为什么重要、最常见误解。

15.1 model

• 定义：底层大模型本身，负责理解输入和生成输出。

• 为什么重要：你选择的模型会影响推理深度、速度和成本。

• 常见误解：把 model 当成完整代理；实际上 agent 还包含工具、上下文和执行流程。

15.2 context

• 定义：Codex 当前能看到的信息集合，包括 prompt、历史对话、文件、命令输出和工具结果。

• 为什么重要：上下文决定 Codex 是在“猜”，还是在“基于证据判断”。

• 常见误解：以为说一句“你自己去看”就等于给了足够上下文。

15.3 tool

• 定义：Codex 可调用的具体能力，例如读文件、跑命令、访问 MCP server。

• 为什么重要：很多任务之所以能落地，不是因为模型会说，而是因为 agent 能调用工具。

• 常见误解：把 tool 理解成插件商店；实际上 tool 更像“可执行动作接口”。

15.4 agent

• 定义：能理解任务、读取上下文、调用工具并持续推进工作的 AI 代理。

• 为什么重要：理解 agent，才能明白 Codex 为什么不只是“会聊天的模型”。

• 常见误解：把 agent 和 model 画等号；model 提供智能，agent 负责组织工作。

15.5 thread

• 定义：一次连续工作会话的上下文容器，保存消息、计划、文件引用和中间结果。

• 为什么重要：线程管理决定上下文会不会脏、任务会不会串。

• 常见误解：把 thread 当成一条消息，或者当成一个 shell 命令。

15.6 prompt

• 定义：你交给 Codex 的任务说明。

• 为什么重要：prompt 决定目标、范围、约束和完成标准是否清楚。

• 常见误解：把 prompt 理解成“提示词技巧”；真正关键的是任务规格是否完整。

15.7 slash commands

• 定义：在 Codex 会话里输入的快捷命令，以 / 开头。

• 为什么重要：它们控制的是会话状态，而不是业务任务本身。

• 常见误解：把 /review、/plan 这类命令拿到普通终端里执行。

15.8 sandbox

• 定义：Codex 执行命令和访问文件时的边界控制。

• 为什么重要：它决定 Codex 客观上能做到哪里。

• 常见误解：把 sandbox 当成审批策略；它解决的是“能不能做”，不是“做之前要不要问”。

15.9 approval policy

• 定义：审批规则，决定某类命令是否需要你手动确认。

• 为什么重要：它决定交互摩擦和风险控制方式。

• 常见误解：以为开了 never 就等于权限更大；真正的边界仍然由 sandbox 决定。

15.10 profile

• 定义：一组可复用配置的名字，通常包含模型、审批策略和沙箱模式。

• 为什么重要：它能让团队用统一入口启动常见工作模式。

• 常见误解：把 profile 当成模型名，或者把未定义 profile 当成内建能力。

15.11 diff

• 定义：修改前后差异对比。

• 为什么重要：它是判断 Codex 实际改了什么的第一入口。

• 常见误解：只看总结不看 diff，以为“说得对”就等于“改得对”。

15.12 review

• 定义：对改动做风险扫描，重点找边界条件、回归点和遗漏。

• 为什么重要：它能把“看起来没问题”的改动再过一遍系统化检查。

• 常见误解：把 review 当成自动修复器或最终裁决者。

15.13 AGENTS.md

• 定义：写给 Codex 这类代理看的仓库协作说明文件。

• 为什么重要：它承载长期稳定的项目规则，而不是让你每次重复说同样的话。

• 常见误解：把临时任务说明、个人偏好或一次性方案塞进去。

15.14 config.toml

• 定义：Codex 的配置文件，用来保存会跨会话复用的默认设置。

• 为什么重要：模型、权限、profiles、MCP 等长期配置都依赖它。

• 常见误解：以为 CLI 参数和配置文件没有优先级差异。

15.15 MCP

• 定义：让 Codex 连接外部系统、资料源或工具的标准接口。

• 为什么重要：它把仓库外的上下文和动作带进 agent 的工作流。

• 常见误解：把 MCP 理解成“外部聊天对象”；实际上 agent 是按结构化工具调用和它交互。

15.16 skill

• 定义：被整理成模板的可复用工作流。

• 为什么重要：它让高频任务少依赖临时 prompt，更稳定地执行。

• 常见误解：把 skill 当成项目规则文件，或者把什么都想做成 skill。

15.17 subagent

• 定义：由主代理派生出去处理子任务的辅助代理。

• 为什么重要：它适合让可并行、可汇总的子任务独立推进。

• 常见误解：把 subagent 当成“多开几个线程”或“默认更强模式”。

15.18 codex exec

• 定义：Codex 的非交互运行模式，适合脚本、CI 和批处理任务。

• 为什么重要：它能把任务变成一次性交付结果或事件流。

• 常见误解：把交互式会话的心智原样搬到 exec，期待中途来回澄清。

15.19 codex review

• 定义：用 Codex 执行审查任务的命令。

• 为什么重要：它适合对未提交改动、某个提交或相对某分支的变化做独立自检。

• 常见误解：把它当成最终 code review 结论，而不是辅助判断。

15.20 session

• 定义：当前版本下会被本机记录下来的一次会话执行记录。

• 为什么重要：理解 session，才能正确理解 resume、fork、--ephemeral 和本地持久化。

• 常见误解：把 session 等同于可跨设备同步的云会话。

15.21 trusted directory

• 定义：被 Codex 视为可信工作区的目录范围。

• 为什么重要：它会影响项目级配置生效，以及某些非交互命令能否在当前目录直接运行。

• 常见误解：把 trusted directory 当成 sandbox 权限的一部分；它更接近工作区信任前置条件。

15.22 cloud task

• 定义：提交到 codex cloud 的远程任务对象。

• 为什么重要：cloud 的核心是 task、status、diff、apply，而不是本地聊天延续。

• 常见误解：把 cloud task 当成本地 thread 的云同步形态。

15.23 feature flag

• 定义：控制某项能力是否启用的配置开关。

• 为什么重要：它常用于实验性能力、灰度功能或受控发布能力。

• 常见误解：把当前 feature flag 状态当成永久稳定接口。

15.24 personality

• 定义：Codex 当前输出风格和沟通方式的配置维度。

• 为什么重要：它会影响回答风格、详略和交互方式，但不改变任务目标本身。

• 常见误解：把 personality 当成模型能力或权限配置。

15.25 codex apply

• 定义：把某个 Codex agent 产出的 diff 应用到本地工作树的命令。

• 为什么重要：它承接的是“任务产出 diff，再落回本地”的工作流。

• 常见误解：把它当成日常交互式编码的主入口。

15.26 local provider

• 定义：Codex 连接的本地模型服务提供方，例如当前 help 中可见的 lmstudio、ollama。

• 为什么重要：它决定 --oss 实际接到哪类本地推理服务。

• 常见误解：把 local provider 当成 sandbox、MCP 或会话存储机制。

15.27 remote app server

• 定义：由 --remote 连接的远程 app server websocket 端点。

• 为什么重要：它描述的是 TUI 到远程服务的接入方式，不等于 codex cloud 或本地 thread 同步。

• 常见误解：把 remote app server 当成 cloud task 或跨设备会话恢复。

15.28 alternate screen

• 定义：终端的备用屏幕缓冲区，很多 TUI 程序会用它接管全屏显示。

• 为什么重要：理解它，才能知道 --no-alt-screen 为什么会保留滚动历史。

• 常见误解：把 alt screen 导致的显示切换误判成会话内容丢失。

15.29 working root

• 定义：Codex 当前视为主工作区的根目录。

• 为什么重要：它会影响路径解析、项目级配置加载和可写范围的基线。

• 常见误解：把 shell 当前目录和 agent 实际工作根永远视为同一个概念；-C 可以让两者不同。

---

16. 按角色使用这份手册

16.1 第一次接触 Codex 的成员

优先读：

• 第 1 章：知道 Codex 到底是什么

• 第 3 章：知道如何安全启动

• 第 4、5、6 章：知道怎么下任务、怎么做最小闭环

• 第 9 章：知道权限和风险边界

• 第 15 章：随时查术语

16.2 日常开发成员

优先读：

• 第 4、5、6 章：建立稳定工作流

• 第 7、8 章：分清 CLI 命令和会话命令

• 第 9 章：知道什么时候该收紧权限

• 第 14 章：照着最小工作流执行

16.3 维护规范和配置的人

优先读：

• 第 9 章：权限与安全边界

• 第 10 章：AGENTS.md 与配置沉淀

• 第 11 章：skills、MCP、subagents、session、cloud、exec/review 的组织方式

• 第 13 章：高频故障排查路径

16.4 负责自动化或平台接入的人

优先读：

• 第 7 章：CLI 入口选择

• 第 9 章：权限和沙箱

• 第 11 章：codex exec、cloud、remote app server、MCP、subagents 与其他 CLI 能力

• 第 13 章：自动化、会话和工具接入相关排错

如果你只记住一句话，就记住这句：

先把目标、上下文、边界和验证说清楚，再考虑模型、skill、MCP 或 subagents。后者是放大器，不是替代品。