Coding 工具 · 03

Codex 客户端

为 Codex 的本机 Local 与 Worktree 任务配置 Stop Hook。脚本只读取会话、轮次和工作目录，不把 prompt 或回复正文交给 bluebell。

先确认任务位置

只适用于在这台 Mac 上运行的任务

Codex 环境能否调用本机 bluebellctl
Local可以；任务直接在当前项目目录运行。
Worktree可以；任务在这台 Mac 的隔离工作树运行。
Cloud不可以直接使用本教程；远端环境看不到 Mac App 内的 CLI。

当前官方生命周期

主线程停止时触发 Stop

Codex 的 Stop Hook 会在主线程的一轮响应停止时执行，并通过 stdin 传入 JSON。当前字段包含 session_id、turn_id、cwd 和最新回复文本；本教程只使用前三项。

步骤 1

创建 Stop 适配脚本

codex-app-bluebell.py
#!/usr/bin/env python3
import json, os, subprocess, sys

CLI = "/Applications/bluebellMac.app/Contents/Helpers/bluebellctl"

try:
    payload = json.load(sys.stdin)
except Exception:
    sys.exit(0)

if payload.get("hook_event_name") != "Stop":
    sys.exit(0)

session_id = str(payload.get("session_id") or "")
turn_id = str(payload.get("turn_id") or "")
cwd = str(payload.get("cwd") or "")
if not session_id or not turn_id:
    sys.exit(0)

try:
    subprocess.run([
        CLI, "emit",
        "--source", "Codex 客户端",
        "--workspace-name", os.path.basename(cwd) or "Codex",
        "--session-id", session_id,
        "--turn-id", turn_id,
        "--dedupe-key", f"codex-app:{session_id}:{turn_id}",
        "--local",
    ], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=3, check=False)
except (OSError, subprocess.SubprocessError):
    pass

把 CLI 替换为 bluebell Mac 首页复制出的真实路径。session_id + turn_id 组成稳定去重身份；同一 Hook 重试不会产生第二条逻辑提醒。

步骤 2

把 Hook 加入 Codex 配置层

对所有本机项目生效时，将下面内容合并进 ~/.codex/hooks.json；只对一个项目生效时可使用 <repo>/.codex/hooks.json。项目级配置还需要信任该项目。

~/.codex/hooks.json
{
  "description": "Send Codex Stop events to bluebell",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"/absolute/path/codex-app-bluebell.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

替换脚本的绝对路径。若文件已有其他 Hook，请只把新的 Stop 项合并进去，不要覆盖整个文件，也不要同时在同一配置层重复写入 hooks.json 和 config.toml Hook。

步骤 3

审查 Hook，再完成一轮本机任务

  1. 保存配置后新建一个 Local 或 Worktree 任务，按 Codex 提示审查并信任这条命令 Hook。
  2. 完成一轮短任务，确认 bluebell Mac 最近提醒只有一条“Codex 客户端”本机事件。
  3. 在同一任务继续一轮，确认新的 turn_id 会生成一条新事件。
  4. 若 Codex 提示 Hook 未信任，可在 Codex CLI 使用 /hooks 查看来源和信任状态。
  5. 验证后从脚本删除 --local，再检查 Mac 总推送、发送队列和真实 Watch。

来源

OpenAI 官方资料