返回博客

Codex CLI 通知:任务完成时收到手机推送

Codex CLI 通知:任务完成时收到手机推送

只要你盯着终端,Codex CLI 完成任务时就会告诉你。它内置的通知是终端转义码:如果终端支持,就显示桌面横幅;不支持就响一声铃。这些都跟不上你离开工位去厨房的步伐。

Codex 还能在生命周期的特定节点运行你自己的命令,而手机推送正需要这个。本指南会在 Codex 完成一轮任务时发送一条推送,在它停下来请求审批时再发一条。

Codex 运行你命令的两种方式

  • Hooks,当前推荐的机制。在 hooks.json 中配置,默认启用,支持 Stop、PermissionRequest、PreToolUse、SessionEnd 等事件。命令通过标准输入(stdin)以 JSON 形式接收事件。
  • notify,config.toml 中较早的设置。它只针对一个事件 agent-turn-complete 触发,并把 JSON 作为最后一个命令行参数传入。它仍然可用,但 Codex 源码已将其标记为旧版功能。

建议使用 hooks。notify 方案放在文末,供旧版配置参考。

你需要准备

  • Codex CLI,需要支持 hooks 的较新版本。
  • jq 和 curl。
  • 一个 Pocket Alert 账号,在 API Keys 获取 API 密钥,并在手机上安装 应用。免费套餐即可满足需求。

把 API 密钥放进只有你能读取的文件中,这样它就不会出现在 shell 历史或环境变量里:

mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key

第 1 步:Hook 脚本

将以下内容保存为 ~/.codex/hooks/pocketalert.sh:

#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Codex finished · $project"
    message=$(jq -r '.last_assistant_message // "Turn complete"' <<<"$payload")
    level=default ;;
  PermissionRequest)
    title="Codex needs approval · $project"
    message=$(jq -r '"Wants to run " + (.tool_name // "a tool")' <<<"$payload")
    level=high ;;
  *) exit 0 ;;
esac

jq -n --arg t "$title" --arg m "${message:0:300}" --arg l "$level" \
  '{title: $t, message: $m, level: $l}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true

exit 0
chmod +x ~/.codex/hooks/pocketalert.sh

Codex 对 hook 的输出要求很严格。对于 Stop,它要么期望没有输出,要么期望标准输出中是 JSON;退出码 2 则会让它继续运行而不是停止。因此脚本中 curl 的所有输出都重定向到 /dev/null,并且脚本始终以 exit 0 结束。

PermissionRequest hook 本身也可以代替你批准或拒绝操作。这个脚本两者都不做:它不输出任何内容,Codex 会显示正常的审批提示,而你会收到一条说明它正在等待的推送。

或者使用 Pocket Alert CLI

安装 Pocket Alert CLI 2.0 或更高版本后,curl 部分可以缩减为一条命令。CLI 会自行转义文本,并从 pocketalert auth 读取密钥,因此不再需要密钥文件:

pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true

请保留 -t 和 -m,不要改用位置参数:如果回复以短横线开头(比如 Markdown 列表),就会被误读为选项。

第 2 步:注册 hooks

创建 ~/.codex/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

主目录中的文件对所有项目生效。仓库内的 .codex/hooks.json 只对该项目生效,而且需要先将该项目标记为受信任。

Hooks 默认开启。如果你之前关闭过,请从 hooks = false 的 [features] 表中删除 ~/.codex/config.toml。

Codex 只运行你审查并信任过的 hooks。下次启动时,它会提示新 hooks 需要审查:打开 /hooks,检查这两个条目并信任它们。如果之后修改了它们,Codex 会跳过这些 hooks,直到你重新信任。

第 3 步:测试

在任意项目中启动 Codex,并给它一个简短的任务:

> Summarise README.md in one sentence.

一轮任务结束后,你的手机会显示 Codex finished · your-project 以及摘要。接着让它运行一条需要审批的命令,第二条推送 Codex needs approval 会以高优先级到达。

如果想在不启动 Codex 的情况下测试脚本:

echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | ~/.codex/hooks/pocketalert.sh

手机上会收到什么

事件标题正文级别
任务完成Codex finished · api最后一条回复的前 300 个字符default
需要审批Codex needs approval · apiWants to run Bashhigh

在 iPhone 上,high 会作为时效性通知投递,因此审批推送即使在专注模式下也能送达,而日常的"完成"推送则保持安静。两类推送都会保留在应用的历史记录和网页控制台中。

旧方式:notify

如果你的 Codex 版本早于 hooks,或者你已经在使用 notify,它也能用,只需做几处修改。Codex 会把事件作为最后一个参数传入,而不是通过 stdin;键名使用 kebab-case;并且只报告任务完成的情况:

#!/usr/bin/env bash
event="${@: -1}"
[ "$(jq -r '.type' <<<"$event")" = "agent-turn-complete" ] || exit 0

jq -n --arg m "$(jq -r '."last-assistant-message" // "Turn complete"' <<<"$event" | cut -c1-300)" \
  '{title: "Codex finished", message: $m}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true
# ~/.codex/config.toml
notify = ["/Users/you/.codex/notify-pocketalert.sh"]

notify 没有审批事件,所以如果你想知道 Codex 何时被卡住,请使用 hooks。

或者让 Codex 通过 MCP 发送

Hooks 只会在固定事件上触发。如果想让 Codex 自己判断该告诉你什么,可以在 ~/.codex/config.toml 中添加 Pocket Alert MCP 服务器:

[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"

也可以通过命令行添加:

codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
  --bearer-token-env-var POCKETALERT_API_KEY

在启动 Codex 的 shell 中导出 POCKETALERT_API_KEY。之后只要发出类似"运行测试套件,把失败的部分推送给我"的指令,Codex 就会调用 create_message,附上它自己写的摘要。该工具同样支持 level 和 actions 参数。

如果没有收到推送

  • 运行测试命令。 如果在这里能正常工作,问题出在 hook 注册上;如果不行,去掉 >/dev/null 2>&1,查看 curl 的报错。401 表示密钥错误。
  • 检查 hooks 是否已被信任。 在 Codex 中打开 /hooks;未信任或已修改的 hooks 会被跳过。
  • 检查项目是否已被信任。 如果你把 hooks.json 放在仓库中,请确认该项目已受信任。
  • 检查 Codex 能否在 PATH 中找到 jq。 Hook 命令在 Codex 的环境和会话的工作目录中运行。
  • 检查每日上限。 免费套餐每天可发送 50 条消息,而 Stop 会在每一轮任务结束后触发。

常见问题

[tui] notifications 呢?

那是 Codex 内置的终端通知。它默认开启,可以同时覆盖任务完成和审批请求,但它只会在电脑上通过终端显示。手机推送则能送达你的手机,并保留历史记录。

这个方法适用于 Codex IDE 扩展吗?

扩展会在你的机器上使用同样的 ~/.codex 配置运行 Codex 代理,因此请先在 CLI 中设置并信任 hooks。Codex 云端任务运行在 OpenAI 的服务器上,不会执行你本地的 hooks。

能在手机上批准操作吗?

这个脚本做不到:它只会告诉你 Codex 正在等待。PermissionRequest hook 可以返回允许或拒绝的决定,因此你可以在它之上,借助手机调用的接口来实现远程审批。人在回路中的通知 介绍了这种模式。

是免费的吗?

是的。Hooks 内置于 Codex 中,Pocket Alert 的免费套餐可在一台设备上每天发送 50 条消息。

注册并获取 API 密钥,添加 hook,然后不必再盯着终端了。

分享这篇文章