# Claude Code 推送通知：任务完成即时知晓

> Claude Code 完成任务、等待权限或因错误停止时，手机即时收到推送提醒。一个 hook 脚本，三个事件，无需插件。

*11.10.2026*

<!-- source: https://pocketalert.app/zh/blog/claude-code-push-notifications -->

Claude Code 很乐意自己干上二十分钟。麻烦在于这二十分钟的另一面：你要么盯着终端等，要么走开，回来才发现它从第三分钟起就一直卡在权限确认上。

Hook 能解决这两个问题。Claude Code 会在生命周期的固定节点运行 shell 命令，其中三个节点正是你想在手机上知道的：

- **Stop**：Claude 结束了本轮回复。任务完成，或者它有问题要问你。
- **Notification**：Claude 需要你介入。出现权限确认，或者它空闲等待输入。
- **StopFailure**：本轮因 API 错误结束，例如速率限制或账单问题。

本指南用一个脚本把这三个事件都接入 Pocket Alert。设置大约需要五分钟。

## 准备工作

- Claude Code，任意较新版本。
- `jq` 和 `curl`。大多数 Linux 发行版自带；macOS 上执行 `brew install jq` 安装。
- 一个 Pocket Alert 账户，以及来自 [API Keys](/account/apikeys) 的 API 密钥。免费套餐即可。
- 在你的 [iPhone 或 Android](/get-app) 手机上安装 Pocket Alert 应用并登录。

## 第 1 步：Hook 脚本

Claude Code 会通过 stdin 把一个 JSON 对象传给每个 hook。你需要的字段有：`hook_event_name`、`cwd`，Stop 事件中的 `last_assistant_message`，Notification 事件中的 `message`，以及 StopFailure 事件中的 `error`。脚本把这些转换成一条推送：

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

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Claude finished · $project"
    message=$(jq -r '.last_assistant_message // "Task complete"' <<<"$payload")
    level=default ;;
  Notification)
    title="Claude needs you · $project"
    message=$(jq -r '.message' <<<"$payload")
    level=high ;;
  StopFailure)
    title="Claude stopped · $project"
    message=$(jq -r '"API error: " + (.error // "unknown")' <<<"$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: $POCKETALERT_API_KEY" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null || true

exit 0
```

保存为 `~/.claude/hooks/pocketalert.sh` 并添加执行权限：

```bash
mkdir -p ~/.claude/hooks
chmod +x ~/.claude/hooks/pocketalert.sh
```

脚本里有两行比看上去更重要：

- **`jq -n` 负责构建 JSON。** Claude 的最后一条消息里充满引号、反引号和换行符。如果手动把它粘进 JSON 字符串，遇到第一个引号就会出错；`jq` 会正确转义。
- **结尾的 `exit 0`，以及 curl 后面的 `|| true`。** 对于 Stop hook 来说，退出码 2 表示“不要停止，继续执行”。通知类 hook 绝不能阻塞 Claude，即使你的网络断开也一样。

### 或者使用 Pocket Alert CLI

安装 [Pocket Alert CLI](/tools/cli) 2.0 或更高版本后，curl 那段可以缩减为一条命令。CLI 会自行转义文本，并从 `POCKETALERT_API_KEY` 读取密钥（下方 `env` 配置块会设置它），或从 `pocketalert auth` 读取：

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

请保留 `-t` 和 `-m`，不要改用位置参数：如果回复以破折号开头（比如 Markdown 列表），就会被当作选项解析。

## 第 2 步：注册 Hook

把 hook 添加到 `~/.claude/settings.json`，使其对所有项目生效。如果该文件已有 `hooks` 键，请把这些条目合并进去：

```json
{
  "env": {
    "POCKETALERT_API_KEY": "YOUR_API_KEY"
  },
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
    ],
    "StopFailure": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }]
      }
    ]
  }
}
```

`env` 配置块把 API 密钥传给 hook，同时无需把它写进你的 shell 配置文件。如果你已经在别处导出了 `POCKETALERT_API_KEY`，就不必添加这个配置块。

Notification 上的 `matcher` 按通知类型过滤。`permission_prompt` 在权限确认等待约六秒仍无应答时触发，`idle_prompt` 在 Claude 完成后约一分钟、且你期间没有输入时触发。在终端会话中，两者都只会在你看起来已离开时才触发，因此你盯着屏幕时手机不会震动。Stop 没有 matcher：Claude 每完成一次回复都会触发。

如果只想让 hook 作用于某一个代码仓库，可以把同样的 `hooks` 配置块放进该仓库的 `.claude/settings.json`，或放进 `.claude/settings.local.json` 以避免提交到 git。

## 第 3 步：测试

Claude Code 通常会自动识别设置文件的修改（如果 `/hooks` 还没列出它们，请新开一个会话）。给它一个简单的任务：

```text
> List the files in this directory and stop.
```

Claude 完成后，你的手机会显示 **Claude finished · your-project**，并附上回复的开头部分。如果什么都没收到，在 Claude Code 中运行 `/hooks` 查看已注册的 hook。

要单独测试脚本，可以喂给它一个模拟事件：

```bash
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | POCKETALERT_API_KEY=YOUR_API_KEY ~/.claude/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>Claude finished · api</td><td>Claude 最后一条回复的前 300 个字符</td><td>default</td></tr>
<tr><th>权限确认</th><td>Claude needs you · api</td><td>Claude needs your permission</td><td>high</td></tr>
<tr><th>等待输入</th><td>Claude needs you · api</td><td>Claude is waiting for your input</td><td>high</td></tr>
<tr><th>API 错误</th><td>Claude stopped · api</td><td>API error: rate_limit</td><td>high</td></tr>
</tbody>
</table>
</div>

`high` 级别的推送会在 iPhone 上以时效性通知的形式送达，因此权限确认能穿透专注模式，而常规的“已完成”消息保持安静。每条推送也会保留在应用的历史记录和 [网页控制台](/messages) 中，方便你回看 Claude 通宵做了什么。

## 按自己的需要定制

**只在你离开时发送。** Stop 会在每次回复后触发，包括你正在盯着看的那些简短回复。在脚本开头加一个开关：

```bash
[ -f ~/.claude/away ] || exit 0
```

然后离开座位时执行 `touch ~/.claude/away`，回来时执行 `rm ~/.claude/away`。权限确认无论如何都值得收到，因此你可以只把检查放进 `Stop)` 分支中。

**按项目分组。** 在 Pocket Alert 中为每个项目创建一个应用，并在 JSON 中添加 `application_id`。这样应用就能按项目过滤，你还可以为每个项目设置各自的默认级别。

**完全不阻塞 Claude。** 在 `"async": true` 旁边添加 `"type": "command"`，hook 就会在后台运行。在无头模式（`claude -p`）下请不要使用：后台 hook 会在会话结束时被终止，推送可能根本发不出去。

**从手机上恢复会话。** 在付费套餐中，带有会话 ID 的 `copy` [操作按钮](https://info.pocketalert.app/features/action-buttons.html) 可以让你在手机上复制 `claude --resume <id>`，回到电脑前再粘贴执行。

## 或者让 Claude 通过 MCP 发送

Hook 是确定性的：无论 Claude 记不记得你，它都会触发。另一种方式是给 Claude 一个通知工具，让它自行决定何时使用。添加 [Pocket Alert MCP 服务器](/tools/mcp)：

```bash
claude mcp add --transport http pocketalert https://mcp.pocketalert.app/mcp \
  --scope user --header "Authorization: Bearer YOUR_API_KEY"
```

现在你可以说“运行迁移，完成后把行数推送给我”，Claude 就会调用 `create_message`，并为此专门撰写一条消息。该工具还接受 `level` 和 `actions` 参数，`list_messages` 则允许 Claude 回读它之前发送过的内容。

两者可以结合使用：用 hook 保证“已完成”和“需要你介入”的提醒必达，用 MCP 发送有实际内容的消息。关于在高风险操作前进行审批，请参阅 [人在回路通知](/blog/human-in-the-loop-notifications)。

## 如果没有收到推送

- **检查密钥。** 运行上面的测试命令。curl 返回 `401` 说明 API 密钥有误；去掉 `>/dev/null` 即可看到响应内容。
- **检查 hook 是否已加载。** 运行 `/hooks`。设置文件的修改通常几秒内生效；如果 hook 没有列出，请重启 Claude Code。
- **检查 `jq` 是否在 Claude Code 使用的 PATH 中。** Hook 在 Claude 的环境中运行，而通过图形界面启动的编辑器可能看不到 Homebrew 的 `/opt/homebrew/bin`。
- **检查每日上限。** 免费套餐每天可发送 50 条消息。长时间会话中如果有大量简短回合，很容易用完配额；上面的离开开关可以帮你减少消息数量。

## 常见问题

### 这在 VS Code 和 JetBrains 扩展中能用吗？

可以。这些扩展底层运行的是 Claude Code，并读取相同的 `~/.claude/settings.json`，因此 hook 在那里同样会触发。

### Claude 能看到 API 密钥吗？

在对话中看不到：hook 在对话之外运行，Stop 和 Notification 的输出也不会展示给模型。但 `env` 配置块作用于整个会话，因此 Claude 运行的 Bash 命令有可能读取该变量。如果这一点很重要，可以把密钥保存在只有你能读取的文件中，例如权限为 `~/.config/pocketalert/key` 的 `600`，并在脚本中改用 `-H "Token: $(cat ~/.config/pocketalert/key)"`。

### 这和终端响铃有什么区别？

响铃和桌面通知都需要你在电脑前。推送则能送达你身处任何位置的手机，保留历史记录，并且可以设置为突破专注模式，用于提醒那些阻塞 Claude 的确认请求。

### 能获取完整回复，而不只是 300 个字符吗？

一条推送最多可携带约 3,000 个字符的文本。你可以提高 `0:300` 的上限，但推送的用途是帮你判断是否需要回到电脑前，而不是阅读完整答案。

### 这是免费的吗？

是的。Hook 是 Claude Code 的功能，而 Pocket Alert 的免费套餐在一台设备上每天覆盖 50 条消息。付费套餐提供更多消息、设备和操作按钮。

[获取 API 密钥](/signup)，放入脚本，让 Claude 在轮到你时告诉你。
