Hooks 钩子

18.1 Hooks 是什么

Hooks(钩子)是 Codex 在特定事件发生时自动执行自定义命令的机制。常见用途:

• 任务完成时播放铃声提醒
• 任务失败时发通知
• 提交前自动跑 lint
• 任务结束后自动清理临时文件

18.2 开启 Hooks

Hooks 是实验性功能,需要先在 config.toml 中开启:

[features]
hooks = true

或用 /experimental 命令切换。

18.3 配置写法

Hooks 用 [[hooks.Event.hooks]] 块状写法。来自掘金《我给 codex 装了个彩铃》的实战示例:

[features]
hooks = true

[[hooks.Event.hooks]]
event = "task-complete"
command = ["/absolute/path/to/ring.sh"]

[[hooks.Event.hooks]]
event = "task-failed"
command = ["/absolute/path/to/notify.sh"]

18.4 全局 hook 必须写在 ~/.codex/config.toml

掘金教程强调:项目的 Codex hooks 不能只放在项目 .codex/config.toml 里,要把真实生效配置写到 ~/.codex/config.toml。

原因:全局 hook 调用时不一定在仓库目录下,所以必须用全局配置才能保证 hook 在任何场景都能触发。

18.5 绝对路径要求

全局 hook 调用时不一定在仓库目录下,所以命令必须是绝对路径:

# ❌ 错误:相对路径
command = ["./ring.sh"]

# ✅ 正确:绝对路径
command = ["/Users/yourname/scripts/ring.sh"]

18.6 review/trust 机制(重要!)

掘金教程强调第三条关键点:

每次新增或修改 hook 命令后,必须在 Codex 的 /hooks 界面执行 review/trust,否则 Codex 会跳过 hook,声音脚本不会被调用。

这是安全防线——防止恶意 hook 自动执行。流程:

1. 在 config.toml 写好 hook
2. 在 Codex 中执行 /hooks
3. review 新增的 hook 命令
4. trust 它
5. 之后 hook 才会真正生效

18.7 实战:任务完成铃声提醒

完整步骤(来自掘金《我给 codex 装了个彩铃》):

1. 写铃声脚本

/Users/yourname/scripts/ring.sh

#!/bin/bash
# macOS 用 afplay 播放音效
afplay /System/Library/Sounds/Glass.aiff

加可执行权限:

chmod +x /Users/yourname/scripts/ring.sh

2. 写入全局 config

~/.codex/config.toml

[features]
hooks = true

[[hooks.Event.hooks]]
event = "task-complete"
command = ["/Users/yourname/scripts/ring.sh"]

3. review/trust

在 Codex 中执行 /hooks,review 并 trust 这个 hook。

4. 测试

下次任务完成时,会听到 Glass 音效。

18.8 常见 hook 事件

事件	触发时机
task-complete	任务完成
task-failed	任务失败
其他事件	以官方文档为准,Codex 迭代中持续新增

⚠️ hook 事件类型会随版本扩展,具体事件名以 /hooks 界面和官方文档为准。

资料来源

• 掘金《我给 codex 装了个彩铃,干完活儿终于会吭声了》——三条核心要点(全局配置、绝对路径、review/trust)
• CSDN《Codex 完整指南(五)》——features.hooks = true 与 [[hooks.Event.hooks]] 写法
• 官方文档(实验特性,以 /experimental 和 /hooks 界面为准)