OpenAI Codex三大概念：新手何时用Skills、Subagents、Hooks

如果你是刚完成 OpenAI Codex 的安装，在文档和社区里频繁撞见 Skills、Subagents、Hooks 这三个词，却一直没搞懂它们到底有什么区别——这篇文章就是为你准备的。 先给出结论：它们不是三个选项，而是三个不同维度的能力扩充。 Skills 是“可复用的工作流模板”，Subagents 是“让多个 AI 并行干活的执行架构”，Hooks 是“在 Codex 干活的关键节点自动插脚本做检查的治理机制”。把这三句记住，剩下细节就好理解了。 ## 决策树：什么时候该用 Skills、Subagents、Hooks 整篇文章的骨架，就是下面这张决策树。三者不是三选一的竞争关系，而是回答三个不同问题的工具。判断的起点不是“我想学哪个”，而是“我现在卡在哪个问题上”。顺着问题往下走，每条路径自然只通向一个工具——这才是“三选一”的正确姿势：一次只解决一个问题。 ```mermaid flowchart TD A[你现在遇到的问题是？] --> B{同一套流程
反复对Codex解释？} B -->|是| C[上 Skills
把流程写成 SKILL.md 复用] B -->|否| D{一个任务能拆成
几块互不依赖、可并行的子任务？} D -->|是| E[上 Subagents
多袋里并行，但更费 token] D -->|否| F{有条规则必须强制执行
不能靠 AI 每次自觉？} F -->|是| G[上 Hooks
用代码在关键节点卡死] F -->|否| H[三个都先别碰
继续用 Codex 攒手感] C --> I{封装好的流程
还要并行拆块？} I -->|是| E I -->|否| J{流程里有
必须强制的红线？} J -->|是| G J -->|否| K[一个 Skill 就够] ``` 把这张图压缩成三句判断，随手就能用： - “同样的话我已经重复解释好几遍了” → 上 Skills，把流程沉淀成模板。 - “这个活可以切成几块同时干，不用互相等” → 上 Subagents，多袋里并行。 - “这条规则必须每次都守住，不能指望 AI 自觉” → 上 Hooks，用代码强制卡死。 后面的章节，就是把每条分支讲透：先用一个比喻把三者的维度拉开，再分别讲每个工具“解决什么问题、什么时候该上”，最后讲它们怎么搭配使用、有哪些坑。你可以随时回到这张图，对照自己当前卡在哪一层。 ## 一、用一个比喻讲清楚 Skills、Subagents、Hooks 的分工 文档里每个词单独看都认识，一放一起就糊涂——因为三个概念处在完全不同的维度，硬放在一条线上比当然乱。用一个贯穿全文的类比把维度拉开：把 Codex 想象成一个帮你干活的助手，那么—— - **Skills（技能）** = 一本标准作业流程手册。你把“做某类任务时该按哪个流程走”写成一份说明书，需要时助手翻出来照着做。它管的是“怎么做这件事”。 - **Subagents（子袋里）** = 一群能同时上工的专业同事。一个大活拆成几块，派给几个各有专长的同事同时干，最后汇总给你。它管的是“谁来做、能不能并行做”。 - **Hooks（钩子）** = 装在工位门口的自动检查门。助手每次伸手拿工具（跑命令、改文件）之前或之后，门会自动拦一道、查一道。它管的是“做之前和做之后，必须卡住哪些规则”。 这个类比锚后面每一节都会用到。只要你心里清楚现在讲的是“剧本、班组、还是质检关”，就不会被术语带偏。  ## 二、Skills（技能）是什么：把重复流程写成一份说明书 Skills 是 Codex 的“可复用工作流模板”。按官方文档的定义，一个 Skill 就是一个文件夹，里面放一份 `SKILL.md` 说明书，外加可选的 `scripts/`（脚本）、`references/`（参考资料）、`assets/`（模板素材）。`SKILL.md` 必须包含两个字段：`name`（精确的名字）和 `description`（描述——它决定了 Codex 在什么时候会触发这个 Skill）。 最简单的 `SKILL.md` 长这样： ``` --- name: skill-name description: 准确说明这个技能什么时候该触发、什么时候不该触发。 --- 给 Codex 照着走的具体步骤。 ``` 它解决的痛点很具体：同一套流程，你在对话里翻来覆去解释。比如“做 PR 评审时先看测试覆盖、再看安全、最后看命名规范”，这套话说一次是教学，说十次就是浪费时间。把它写进一个 Skill，下次只要任务匹配，Codex 自己就调出来照做。 Codex 调用 Skill 有两种方式： - **显式调用**：在提示词里直接点名。在命令行界面或集成开发环境里输入 `/skills` 或打 `$` 提及某个技能。 - **隐式调用**：Codex 根据你任务的内容，匹配某个 Skill 的 `description` 自动选用。 正因为隐式匹配靠的是 `description`，官方建议把关键场景词和边界条件写进描述里——比如“PR 评审专用，不用于普通 code review”——这样即使描述被压缩，Codex 也还能正确匹配。 新手的第一份 Skill 怎么起步？最快的路径是用 Codex 内置的 `$skill-creator`（它本身就是一个系统级的 Skill）。在命令行里输入 `$skill-creator`，它会反向访谈你：这个技能干什么、什么时候触发、要不要带脚本（默认只带说明、不带脚本），然后生成 `SKILL.md` 草稿，你修订即可。第一个 Skill 控制在几十行、跑顺了再迭代，别一上来就写大而全的流程。 ## 三、Subagents（子袋里）是什么：让几个 AI 并行干活 Subagents 是 Codex 的“多袋里执行架构”。按官方文档，Codex 可以同时派出多个专门的子袋里并行干活，再把它们的结果汇总成一个回复。它特别适合那种“能拆开、能并行”的复杂任务——典型场景是探索陌生代码库，或者按一份多步计划同时推进多块内容。 这里有两个新手必须先记住的硬事实： - 子袋里只在你明确要求时才会启动。Codex 不会自作主张开子袋里——你得在提示词里说清楚“派一个袋里查安全、派一个查性能……”它才会动。 - 子袋里消耗的令牌（token）比单袋里多得多。官方明确说过：因为每个子袋里都要自己跑模型、自己调工具，子袋里工作流的总消耗显著高于单袋里。这是成本，不是免费的并行。 Codex 内置了三个开箱即用的子袋里： | 内置子袋里 | 定位 | |---|---| | `default` | 通用兜底袋里 | | `worker` | 执行型：负责实现和修改代码 | | `explorer` | 读取型：负责只读地探索代码库 | 你也可以定义自己的子袋里：在 `~/.codex/agents/`（个人）或 `.codex/agents/`（项目）下放 TOML 配置文件，每个文件定义一个袋里，必须写 `name`、`description`、`developer_instructions` 三个字段，还能可选地指定 `model`（模型）、`sandbox_mode`（沙箱模式）等。官方给的 PR 评审范式就是三个自定义袋里分工：`pr_explorer` 摸清代码、`reviewer` 找正确性和安全问题、`docs_researcher` 通过文档服务器核对接口。 子袋里有两个全局参数，新手务必知道但通常不用动，都在配置里的 `[agents]` 段： - `max_threads`（最大并发线程）：主袋里最多同时开几个子袋里。默认是 6。 - `max_depth`（最大嵌套深度）：子袋里还能不能再开下一层。默认是 1，意思就是允许子袋里再开一层，但禁止更深。 官方对 `max_depth` 有一句明确警告：调高这个值会增加令牌消耗、延迟和本机资源占用。 ## 四、Hooks（钩子）是什么：在关键节点自动插一道检查 Hooks 是 Codex 的“生命周期治理机制”。按官方文档，它是一套扩展框架，让你把自己的脚本插进 Codex 干活的循环里，在关键节点自动执行——比如把对话发给日志系统、扫描提示词防止误粘 API 密钥、在某次操作前拦下危险命令、在对话结束时自动总结存档。 Hooks 默认是开启的。它和 Skills、Subagents 最大的区别是：Skills 和 Subagents 是“让 AI 更会做”，Hooks 是“不靠 AI 自觉、用代码强制卡住”。这就是为什么治理类的事一定要用 Hooks，而不是写进 Skill 里指望 AI 每次都照做——确定性检查交给代码，推理判断才交给模型。 Codex Hooks 支持的生命周期事件远不止社区早期文章说的那几个。按官方文档，当前支持这些事件： | 事件 | 触发时机 | 典型用途 | |---|---|---| | `SessionStart` | 会话开始 | 注入初始上下文、加载工作区约定 | | `UserPromptSubmit` | 用户提交提示词时 | 校验、改写、拦截提示词 | | `PreToolUse` | 工具调用前 | 拦危险命令、注入额外上下文、改写命令 | | `PermissionRequest` | Codex 即将请求授权时 | 自动批准/拒绝/让正常审批流继续 | | `PostToolUse` | 工具调用后 | 捕获输出、自动 lint、把反馈回灌给模型 | | `PreCompact` / `PostCompact` | 对话压缩前/后 | 压缩前后的处理 | | `SubagentStart` / `SubagentStop` | 子袋里启动/结束 | 给子袋里注入上下文、子袋里收尾 | | `Stop` | 对话回合结束 | 清理、总结、判断要不要再跑一轮 |  新手真正要记住的只有两个事件：`PreToolUse`（命令执行前拦截，比如发现命令里有 `rm -rf /` 就拦下）和 `PostToolUse`（命令执行后校验，比如自动跑一遍 lint、检查提交信息格式）。“该不该上 Hooks”的判断到这里就够了——剩下的“具体怎么配”是另一个话题，本文先不展开。 但有一个原理新手必须先建立，因为它直接影响“Hooks 能不能解决你的问题”： ## 五、4 类身份对号入座：你现在该上哪一个 讲清三个概念之后，回到最实际的问题——以你现在的状态，三个里先碰哪个？对号入座。 ① **刚装好 Codex 的纯新手**：三个都先别碰。你现在最该做的是用 Codex 干真实的活，建立手感。等你某个流程重复解释到烦了，再把它写成第一个 `SKILL.md`。理解这三个概念有意义，但动手顺序是“先用、后封装、再治理”。 ② **用了几周的个人开发者**：从 Skills 入手。把你重复最多的那套流程（PR 评审 SOP、新项目脚手架、bug 修复套路）封装成 Skill。如果你开始要啃一个陌生的大型代码库，可以试试让几个 `explorer` 子袋里并行扫不同模块——这是 Subagents 对个人开发者最实在的用途。Hooks 这阶段一般还用不上。 ③ **团队/项目维护者**：直接上 Hooks。团队场景的核心诉求是“强制规则”——不能靠每个人、每个 AI 自觉。用 `PreToolUse` 拦危险命令、用 `PostToolUse` 强制 lint 和提交规范，配合信任审查机制，把治理变成代码而不是口头约定。 ④ **想搭复杂多袋里流程的进阶者**：三件套组合。但有顺序——先用 Skill 把完整流程定义清楚，再用自定义 Subagents 把流程拆成并行的专业袋里，最后用 Hooks 给每个袋里跑工具时兜底。关键是别一上来三个全开，学习曲线太陡，先单独把一种用顺。 这四类身份其实就是开头那张决策树的四个出口：纯新手停在“先别碰”，个人开发者落在“Skills”（顺带试 explorer），团队维护者落在“Hooks”，进阶者把三条路径串起来。拿不准自己是哪一类时，回到决策树问自己那三个问题就行——它认的是你卡在哪个问题，不是你自封哪个段位。 ## 六、Skills 和 AGENTS.md 有什么区别：判断“该不该用 Skills”的关键边界 新手最常问的一个问题：既然有了 `AGENTS.md`（项目指令文件），为什么还要 Skills？两者都是“告诉 AI 该怎么做”，区别在加载方式和职责： | 维度 | AGENTS.md | Skills | |---|---|---| | 加载方式 | 每次对话自动加载 | 按需加载，只在被调用时读完整内容 | | 职责 | 项目级铁律、持续约束 | 可复用的特定工作流 | | 写什么 | “永不”“必做”“项目背景” | “干 PR 评审时按这套流程”“修 bug 时按这个套路” | | 适合 | 所有任务都要遵守的内容 | 不总是需要、但需要时要完整流程的场景 | 判断很简单：高频、每次都要遵守的内容进 AGENTS.md；低频、特定任务才用的完整流程进 Skill。 这背后有一个实测佐证：Vercel 团队做过一组对比评测，把同一份框架文档分别放进每次自动加载的 `AGENTS.md` 和靠 AI 自己决定要不要读的 Skill，结果嵌入式上下文（AGENTS.md）的通过率是 100%，而按需检索的 Skill 在不加额外提示时只有 53%——和“完全没文档”的基线一样，因为有 56% 的情况 AI 根本没去调用那个 Skill。换句话说，你真正高频依赖的内容应该放进 AGENTS.md，而不是指望 AI 每次都正确地选中那个 Skill。 这条分工的本质是“确定性对灵活性”：AGENTS.md 是确定的、强制的、每次都在的；Skill 是灵活的、按需的、靠匹配触发的。所以判断“该不该用 Skills”就一句话——必须每次遵守的写进 AGENTS.md（交给确定性），不固定、只在特定任务才需要的完整流程才写进 Skill（交给灵活匹配）。把强制规则塞进 Skill，等于把确定性的事交给不确定的匹配机制，迟早会漏；把一次性流程塞进 AGENTS.md，又会撑大每次对话的上下文。各归各位。 ## 七、三者能不能搭配使用：能，而且经常这么用 三件套不是三选一，恰恰相反——成熟的工作流经常三个一起上，因为处在不同维度。两个典型组合： **组合一：PR 自动评审。** 先用一个 Skill 定义“PR 评审完整流程”，再用 Subagents 把流程拆成 `reviewer`（查正确性和安全）、`docs_researcher`（核对接口文档）、`pr_explorer`（摸清代码）三个子袋里并行跑，最后用 `PreToolUse` Hook 在每个子袋里跑命令前拦危险操作。 **组合二：bug 修复标准流程。** Skill 定义“修 bug 的标准套路”，先用 `explorer` 子袋里扫清代码，主袋里用 `worker` 改代码，改完用 `PostToolUse` Hook 自动跑 lint 校验。 ## 八、Skills 装多了有副作用吗：会，别囤 这是个真实存在的坑。Codex 用一种叫渐进式披露的机制管理上下文：它先把每个 Skill 的 `name`、`description` 和文件路径放进上下文供选择，不是一上来就塞完整内容。但这份“初始技能列表”有预算上限——大约是模型上下文窗口的 2%，上下文窗口未知时是 8000 字符。 Skill 装太多、超出预算时，Codex 会按这个顺序退让：先缩短 `description`（影响触发准确度），再干脆省略掉一部分 Skill（你以为装了、其实没进选择列表），并显示警告。 社区里的经验共识大致是：起步 5-10 个覆盖最高频工作流，多数团队 10-30 个有价值，超过这个量级可见性就成了瓶颈、需要专门治理。 ## 九、拿一个真实任务走一遍决策树 抽象的判断说再多，不如拿一个具体任务过一遍。假设你要做的是“给团队仓库做 PR 自动评审”，顺着开头那张决策树往下走，看每一步该上哪个工具——这也是检验你是否真听懂“三选一”的最好方式。 1. “这套评审流程是不是会反复用？” 是。每个 PR 都要走一遍同样的步骤（看测试覆盖、查安全、核接口、读改动）。→ 第一步上 Skills，把这套流程写成一个 `SKILL.md`，下次匹配到 PR 评审任务就自动调出来。 2. “这套流程能不能拆成几块同时干？” 能。查安全、核接口文档、摸代码这三件事互不依赖，可以并行。→ 第二步上 Subagents，按官方范式拆成 `reviewer`（查正确性和安全）、`docs_researcher`（核对接口文档）、`pr_explorer`（摸清代码）三个子袋里并行跑。 3. “这里面有没有必须强制、不能靠 AI 自觉的红线？” 有。比如“评审过程绝不允许跑写操作命令”。→ 第三步上 Hooks，在 `PreToolUse` 上挂一个拦截，子袋里一旦想跑危险命令就 `deny`。 同一个任务，三个工具各解决一段问题，顺序由决策树自然推出来，不是凭感觉排的。 反过来，如果任务是“在一个文件里连续改十几处”——走第一问可能值得封个 Skill，但走到第二问“能不能拆成并行几块”就卡住了：这些修改前后依赖、必须串着改，硬上子袋里只会徒增 token 消耗和协调成本，更慢更贵。这时就该在决策树这一步降级——停在 Skills，不碰 Subagents。 ## 十、5 个新手常见坑 1. **一上来三个全开。** 学习曲线陡到劝退。正确做法：先用 Codex 攒手感，需求倒逼着上工具。 2. **把必须每次遵守的规则写进 Skill。** Skill 是按需匹配的，不保证每次命中。强制规则进 `AGENTS.md`，不进 Skill。 3. **囤 Skill。** 渐进式披露有预算上限，装太多会被缩描述、被省略。起步一两个，按真实痛点增。 4. **乱调 `max_depth`。** 默认 1 不要动，深层嵌套 token 指数级涨。要复杂流程就横向拆、串行跑。 5. **指望 `PostToolUse` Hook 撤销已跑的命令。** 它撤不了，只能跑完再纠正。要“不让跑”得用 `PreToolUse` 在执行前拦。 ## 十一、进阶路径：跑两周后下一步 - **第 1 天：** 用 Codex 干一个真实小任务，不碰任何进阶概念，建立基础手感。 - **第 1 周：** 发现某套流程重复解释了好几遍，把它写成第一个 `SKILL.md`（用 `$skill-creator` 起步），跑顺。 - **第 1 个月：** 如果在团队里，给项目加上 `PreToolUse` / `PostToolUse` Hook 做基础治理；如果常啃大代码库，试一次 `explorer` 子袋里并行探索。 - **更进一步：** 把成熟流程做成“Skill 定流程 + 自定义 Subagents 并行 + Hooks 兜底”的组合，但每次只加一个能力、加完验证。 ## 十二、自检清单 读完这篇，下面几条你应该能答上来——答不上来说明对应章节要回看： - [ ] 能复述决策树的三个判断问题：流程反复解释？任务可并行？规则要强制？分别对应哪个工具。 - [ ] 能一句话说清 Skills、Subagents、Hooks 各管哪个维度（剧本/班组/质检关）。 - [ ] 知道什么内容进 `AGENTS.md`、什么进 Skill（确定性进前者，按需流程进后者）。 - [ ] 知道 Subagents 只在你明确要求时启动、且更费 token，判断硬标准是“能不能真正拆成可并行的子任务”。 - [ ] 知道 Hooks 是用代码强制、不靠 AI 自觉，且 `PostToolUse` 撤不了已跑的命令、要拦得用 `PreToolUse`。 - [ ] 拿一个自己手头的真实任务，能顺着决策树走到该上的那一个工具。 ## 一句话收官 回到开头那张决策树：Skills、Subagents、Hooks 不是要一起学的“高级功能套餐”，而是回答三个不同问题的工具——流程反复解释就上 Skills，任务能真正并行就上 Subagents，规则必须强制就上 Hooks。新手最该做的不是把三个都配好，而是看清自己现在卡在哪个问题上，只上真正需要的那一个。需求倒逼工具，永远比工具找需求稳。 **同系列下一步：** - openai-codex-complete-overview - openai-codex-cli-app-ide-cloud - openai-codex-prompt-to-task - openai-codex-context-engineering **跨系列参考：** - claude-code-claude-md-guide - claude-code-hooks-guide（Hooks 怎么配的逐字段拆解） **外部参考：** - https://developers.openai.com/codex/skills - https://developers.openai.com/codex/subagents - https://developers.openai.com/codex/hooks - https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals（AGENTS.md 对 Skills 的评测数据来源）

来源：互联网