Codex启动Hook怎么配置？SessionStart注入目录检查提示与信任核对

每次打开Codex都希望先确认目录、分支和已有改动，可以把短检查提示放进SessionStart Hook。Hook由生命周期事件触发，比在每段聊天里重复粘贴方便，但注入提醒不等于强制阻止操作。本文只做一个输出JSON上下文的最小脚本，不执行安装、外发或自动修改项目。

第一步：选择事件与保存作用域

SessionStart在会话启动、恢复等时机运行，matcher可按source筛选。我们只选startup与resume，不把每次工具调用都触发同一提示。用户级hooks.json影响更多项目，可信项目的.codex/hooks.json更适合练习。先检查是否已有Hook，避免覆盖团队配置。

多个来源的匹配Hook会合并运行，同一事件的多个命令处理器可能并发，不能依赖一个Hook先完成给另一个提供文件。先只新增一项，明确用途和超时。项目未受信任时，项目层Hook可能不加载，用户层仍可能加载，要在实际会话查看来源。

第二步：写只输出上下文的脚本

import json, sys

event = json.load(sys.stdin)
cwd = event.get("cwd", "未提供")
message = ("开始任务前核对当前目录与分支、已有改动。"
           "不要覆盖无关文件，不把旧会话状态当作当前事实。"
           "本次启动事件提供的cwd为：" + str(cwd))
print(json.dumps({"hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": message
}}, ensure_ascii=False))

将脚本保存为练习项目下的.codex/hooks/session_context.py。事件通过标准输入传JSON，标准输出按官方形状返回附加上下文，不把普通调试文字混在JSON前后。需要排错时将必要且脱敏的信息写stderr，避免把完整事件或会话内容转存为日志。

第三步：合并hooks.json定义

{"hooks":{"SessionStart":[{"matcher":"startup|resume","hooks":[{"type":"command","command":"python3 /absolute/path/to/project/.codex/hooks/session_context.py","timeout":5,"statusMessage":"Loading project check reminder"}]}]}}

把绝对路径替换为真实脚本路径，有空格时正确引用；该字符串不是让你保留占位路径运行。绝对路径适合本机练习，共享配置则需按官方建议采用稳妥的仓库根目录解析方式，避免从子目录启动时相对路径找错。先验证JSON语法，再保存。

一个配置层同时用hooks.json与内联TOML会合并并警告，优先选一种表示。不要为测试此Hook关闭所有其他团队Hook，也不使用绕过信任检查的标记来掩盖配置问题。脚本是否可运行、路径是否正确与模型能力无关。

第四步：审阅并信任准确版本

非受管理Hook需在运行前审阅并信任，CLI用/hooks查看来源、新改定义与状态。官方按定义哈希记录信任，修改后可能需要重新审查，不能因为之前点过信任就认定新内容一定执行。由管理员管理的Hook有不同控制边界。

人工验证顺序：先用一份仅含cwd的模拟JSON测试脚本输出；检查输出可解析且没有秘密；进入/hooks核对定义和信任；启动新的练习会话；再恢复一次会话观察对应事件。不要用生产任务测试未经审阅的Hook。

提示被注入后，还需检查Codex实际是否核对当前状态。没有执行相关检查就不能在报告里写“已确认干净分支”。Hook提供上下文，不自动运行Git命令，也不自动替你拒绝后续写入。

第五步：定位不触发与重复触发

不触发时检查事件source、matcher、脚本路径、项目可信状态和hooks功能是否被组织关闭。重复提醒时检查用户、项目与Plugin是否都定义了类似事件，不随意删整个配置文件。对错误保留退出状态和最小输出，不把超时当成模型忽略要求。

完成标准是事件匹配正确、输出结构有效、信任状态明确且提示不含敏感内容。真正必须阻止某类操作时，需要相应权限或支持阻断的机制；不要把一句自然语言提醒宣传成不可绕过的安全策略。

官方资料

资料核对日期：2026年11月9日。

• OpenAI：Hooks