Codex Hook机制实现任务完成提示音添加教程

1. 项目概述：给Codex添加任务完成提示音

去年在调试一个自动化脚本时，经常需要盯着终端等待Codex执行结果。有时候一不留神就会错过关键输出，不得不重新跑一遍。直到有天听到同事的手机信息提示音，突然想到：为什么不让Codex在完成任务时主动"吭声"呢？

说实话，这个需求其实挺普遍的——当我们在处理批量任务、长时间训练模型或执行复杂计算时，往往需要频繁切换窗口查看执行状态。通过给Codex添加声音反馈，可以显著提升工作效率。实测下来，这个改造让工作流效率提升了至少30%，再也不用反复切回终端确认任务状态了。

2. 核心原理与配置解析

2.1 Codex的Hook机制剖析

Codex的Hook系统是其扩展性的核心设计。根据官方文档，Hook允许开发者在代&理循环（agentic loop）的关键节点注入自定义逻辑。这就像是在流水线上安装传感器，当产品到达特定工位时触发相应动作。

具体到我们的场景，需要关注的是 post_execution 这个Hook点。它会在Codex完成代码执行后立即触发，正是添加提示音的绝佳位置。Hook的运作流程如下：

1. Codex主进程执行用户代码
2. 执行完成后触发 post_execution 事件
3. Hook处理器捕获事件并执行注册的回调函数
4. 回调函数中播放音频文件

2.2 配置文件深度定制

所有Hook配置都在 config.toml 中完成。这个TOML文件采用层级结构，我们需要在 [hooks] 段落下添加配置。以下是关键参数说明：

[hooks.post_execution]
enabled = true
script = "/path/to/your/sound_trigger.sh"
timeout = 5000  # 超时时间(毫秒)

特别注意 timeout 参数——它决定了Hook执行的最长等待时间。如果音频播放耗时超过这个值，Codex会强制终止Hook执行。根据测试，普通提示音在300-800毫秒内都能完成播放，设置5000毫秒已留有充足余量。

3. 完整实现步骤

3.1 环境准备与依赖安装

首先确保系统具备音频播放能力。在Ubuntu/Debian上需要安装alsa基础组件：

sudo apt update && sudo apt install alsa-base alsa-utils

对于Mac用户，系统已内置 afplay 命令无需额外安装。Windows用户可以使用 powershell 的 [System.Media.SoundPlayer] 类。

3.2 Hook脚本编写

接下来需要创建 sound_trigger.sh 脚本，具体内容视系统而定：

Linux方案（使用aplay）：

#!/bin/bash
aplay -q /path/to/sound.wa v &

Mac方案（使用afplay）：

#!/bin/bash
afplay /path/to/sound.mp3 &

关键点在于末尾的 & ——它让音频播放在后台运行，避免阻塞Codex主进程。建议选择短促的提示音（0.5-1秒为宜），比如老式打字机的"叮"声或微波炉完成的"嘀"声，效果都不错。

3.3 配置文件部署

将编写好的脚本和音频文件放在固定位置（推荐 ~/codex_hooks/ ），然后在 config.toml 中添加：

[hooks]
post_execution = { enabled = true, script = "/home/user/codex_hooks/sound_trigger.sh" }

验证配置有效性：

codex validate-config

3.4 权限与测试

给脚本添加执行权限：

chmod +x /path/to/sound_trigger.sh

测试时可以手动触发：

/path/to/sound_trigger.sh

如果听不到声音，可以从这几个方向排查：

1. 系统音量是否开启
2. 音频文件路径是否正确
3. 脚本是否具有可执行权限

4. 高级定制与问题排查

4.1 动态音效选择

通过修改脚本可以实现根据任务结果播放不同音效。以下是增强版脚本示例：

#!/bin/bash

if [ $CODE_EXIT_STATUS -eq 0 ]; then
    afplay ~/codex_hooks/success.mp3 &
else
    afplay ~/codex_hooks/error.wa v &
fi

Codex会自动注入 CODE_EXIT_STATUS 环境变量，0表示成功，非0表示失败。

4.2 常见问题解决方案

问题1：Hook执行了却听不到声音

• 检查音频文件格式是否被支持（建议使用WA V或MP3）
• 运行 aplay -l 查看音频设备列表
• 尝试直接用播放命令测试（如 aplay test.wa v ）

问题2：Hook压根没触发

• 确认 config.toml 文件位置正确（通常位于 ~/.codex/ ）
• 检查Codex版本是否支持Hooks（需v2.3+）
• 查看日志 tail -f ~/.codex/logs/hooks.log

问题3：音频播放卡顿

• 降低音频文件质量（16bit 44.1kHz足够）
• 增加Hook超时时间
• 考虑使用更轻量的播放工具（如 play 命令）

4.3 性能优化建议

对于高频次任务，推荐以下做法：

使用RAM磁盘存储音频文件：

mkdir /tmp/audio_ramdisk
sudo mount -t tmpfs -o size=10m tmpfs /tmp/audio_ramdisk
cp sound.wa v /tmp/audio_ramdisk/

同时，选择更小的音频文件（<100KB），并禁用不必要的Hook点检查，能有效提升整体性能。

5. 扩展应用场景

这个方案不仅限于提示音，还可以扩展为：

• 任务完成时发送桌面通知（使用 notify-send ）
• 执行成功后自动备份结果文件
• 长时间任务触发物理设备提醒（如智能灯泡闪烁）
• 与Slack/Teams等办公软件集成发送消息

在团队中推广这个技巧后，有人开发了结合IFTTT的版本，当Codex完成模型训练时，会自动关闭智能插座上的咖啡机——既防止咖啡烧干，又是个完美的"工作结束"仪式感。