Codex中文官网

Hooks 是 Codex 的生命周期扩展。它允许你在固定时机运行一段外部脚本，比如提示词提交之前，工具调用完之后，或者一次对话即将结束的时候。 它做的是确定性的检查，不替 Codex 推理。脚本怎么写就怎么执行，它的价值在这里，风险也在这里。这是相当进阶的用法，一般建议先从社区里找现成的 Hook 用，或者让 Codex 帮你写一份。 它常被用来做这几件事 把对话或者工具调用的记录送到团队日志系统检查用户提示词里有没有误贴 API key 或者 token在会话开始时加载本地说明和项目约定在工具调用之前拦下高风险命令，比如删除文件，发布和部署在工具调用之后检查输出，提醒 Codex 继续验证在对话停止之前要求它再跑一次测试，或者补一份交付说明 这些事情的共同点是判断标准明确。该拦就拦，该记就记。 默认就开着 Codex 默认启用 Hooks。想在本机关掉，在 config.toml 里把 features 表下的 hooks 设为 false 就行。官方推荐的 feature key 是 hooks，旧的 codex_hooks 还能用，但已经标记为弃用。 团队或者企业管理员可以通过 requirements.toml 统一管理这个开关。个人用户一般只需要管好本机和项目里的两份配置。 配置放在哪四个位置 Codex 会在当前激活的配置层旁边找 Hooks，常见的位置有四个。 位置说明用户目录下的 .codex/hooks.json用户级，单独写一份 Hook 配置文件用户目录下的 .codex/config.toml用户级，写在 hooks 表里仓库下的 .codex/hooks.json项目级，跟着仓库走仓库下的 .codex/config.toml项目级，写在 hooks 表里 多处都配上时 Codex 会全部加载。为了不混，同一层里建议只选一种写法，要么用 hooks.json，要么写在 config.toml 里。 项目内的 Hook 只有在这个项目的 .codex 配置层被信任之后才会加载。没信任的项目里，用户级和系统级的 Hook 照常生效。 一次对话里，它们按什么顺序出现 Hook 绑在固定的生命周期节点上，不是随机触发的。会话启动触发 SessionStart。用户提交提示词触发 UserPromptSubmit。Codex 准备调用工具时是 PreToolUse，如果这个工具需要额外权限，接着来一次 PermissionRequest。工具执行完走 PostToolUse。当前这一轮准备收尾的时候是 Stop。 中途如果发生上下文压缩，会触发 PreCompact 和 PostCompact。启动了子代理，则有 SubagentStart 和 SubagentStop。 常用事件各自能干什么 事件触发时机常见用途SessionStart会话启动，恢复或者压缩后重新开始加载本地上下文，提示项目约定UserPromptSubmit用户提示词即将提交检查敏感信息，提示补充复现步骤PreToolUseCodex 调用工具之前拦截危险命令PermissionRequest准备请求权限时放行低风险请求，拒绝高风险请求PostToolUse工具调用完成之后检查命令输出，要求继续验证PreCompact 和 PostCompact上下文压缩前后保存摘要，补充压缩后的上下文SubagentStart 和 SubagentStop子代理开始或停止给子代理补充规则Stop当前一轮即将结束要求再跑测试，补总结 不同事件的权限不一样 事件能不能改变后续行为PreToolUse可以拒绝部分工具调用，也可以给 Codex 补充上下文PermissionRequest可以放行或者拒绝权限请求PostToolUse工具已经跑完，副作用撤不回来，只能改它接下来看到的反馈UserPromptSubmit可以阻止提示词提交，或者补充上下文Stop可以要求 Codex 继续一轮SessionStart主要用来补充会话开始时的上下文 所以想拦危险命令，得挂在 PreToolUse。想审查执行结果，用 PostToolUse。怕它结束得太早，就靠 Stop。挂错事件点，效果会完全不一样。 作用范围分三种 官方把事件按作用范围分了层。围绕一轮用户请求触发的叫 turn scope，比如 PreToolUse，PostToolUse，UserPromptSubmit 和 Stop。围绕会话启动的是 thread scope，SessionStart 属于这一类。围绕子代理起停的是 subagent scope，对应 SubagentStart 和 SubagentStop。 入门先掌握 turn scope 就够了。检查提示词，拦工具调用，看工具输出，这些最常用的都在这层里。结束前补一次验证也属于它。