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

> Codex CLI 完成一轮任务或请求审批时，把手机推送通知发到你的手机。使用 Codex hooks 加 Pocket Alert，旧的 notify 设置作为备选。

*14.10.2026*

<!-- source: https://pocketalert.app/zh/blog/codex-notifications -->

只要你盯着终端，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](/account/apikeys) 获取 API 密钥，并在手机上安装 [应用](/get-app)。免费套餐即可满足需求。

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

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

## 第 1 步：Hook 脚本

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

```bash
#!/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
```

```bash
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](/tools/cli) 2.0 或更高版本后，curl 部分可以缩减为一条命令。CLI 会自行转义文本，并从 `pocketalert auth` 读取密钥，因此不再需要密钥文件：

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

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

## 第 2 步：注册 hooks

创建 `~/.codex/hooks.json`：

```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，并给它一个简短的任务：

```text
> Summarise README.md in one sentence.
```

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

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

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

## 手机上会收到什么

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>事件</th><th>标题</th><th>正文</th><th>级别</th></tr></thead>
<tbody>
<tr><th>任务完成</th><td>Codex finished · api</td><td>最后一条回复的前 300 个字符</td><td>default</td></tr>
<tr><th>需要审批</th><td>Codex needs approval · api</td><td>Wants to run Bash</td><td>high</td></tr>
</tbody>
</table>
</div>

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

## 旧方式：notify

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

```bash
#!/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
```

```toml
# ~/.codex/config.toml
notify = ["/Users/you/.codex/notify-pocketalert.sh"]
```

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

## 或者让 Codex 通过 MCP 发送

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

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

也可以通过命令行添加：

```bash
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 可以返回允许或拒绝的决定，因此你可以在它之上，借助手机调用的接口来实现远程审批。[人在回路中的通知](/blog/human-in-the-loop-notifications) 介绍了这种模式。

### 是免费的吗？

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

[注册并获取 API 密钥](/signup)，添加 hook，然后不必再盯着终端了。
