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 · api | Wants to run Bash | high |
在 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,然后不必再盯着终端了。