# Cursor 推送通知：智能体完成时手机提醒你

> Cursor 智能体完成、失败或有消息需要告诉你时，手机立即收到推送。每次运行都能触发的 stop 钩子，加上 Pocket Alert MCP 服务器，让智能体自己撰写并发送消息。

*12.10.2026*

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

Cursor 的智能体可以在你泡咖啡时重构一个模块，但对于普通的本地运行，Cursor 只会在电脑上告诉你它完成了：一声提示音，或者你开启过的系统通知。Cursor iOS 应用会在智能体结束一轮对话时推送，但只适用于云端智能体，以及你通过远程控制（Remote Control）交接的会话，并且需要付费套餐和 iPhone。Android 版本尚在计划中。

如果你希望本地智能体运行结束时手机收到推送，Cursor 提供两种发送方式：

- **`stop` 钩子。** 每当智能体循环结束时，Cursor 都会运行你的脚本，无论运行是完成、被中止还是出错。稳定可靠，每次行为一致。
- **MCP 工具。** 添加 Pocket Alert MCP 服务器后，你随时可以让智能体用它自己写的消息给你发推送。

本指南会配置这两种方式，每种只需几分钟。

## 你需要准备

- Cursor 1.7 或更高版本；钩子功能在 1.7 中推出。
- 钩子脚本需要 `jq` 和 `curl`。
- 一个 Pocket Alert 账户，从 [API Keys](/account/apikeys) 获取 API 密钥，并在手机上安装[应用](/get-app)。免费套餐即可满足需求。

从程序坞（Dock）启动的 Cursor 不会读取你的 `.zshrc`，所以你在那里导出的环境变量对它不可见。请把密钥保存在文件中：

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

## 方式一：每次运行都触发的 stop 钩子

### 脚本

Cursor 会通过标准输入（stdin）向钩子传递一个 JSON 对象。对于 `stop`，它包含 `status`（`completed`、`aborted` 或 `error`）以及 `workspace_roots`，即窗口中打开的文件夹。将以下内容保存为 `~/.cursor/hooks/pocketalert.sh`：

```bash
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.workspace_roots[0] // "cursor"' <<<"$payload")")
status=$(jq -r '.status // "completed"' <<<"$payload")

case "$status" in
  completed) title="Cursor finished · $project"; level=default ;;
  error)     title="Cursor hit an error · $project"; level=high ;;
  *)         echo '{}'; exit 0 ;;
esac

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

echo '{}'
```

```bash
chmod +x ~/.cursor/hooks/pocketalert.sh
```

被中止的运行会被有意跳过：如果你按了停止，自然已经知道结果。脚本输出 `{}`，是因为 `stop` 钩子可以返回一个 `followup_message`，Cursor 会把它作为你的下一条提示发回给智能体；空对象表示“无需补充”。

### 或使用 Pocket Alert CLI

安装 [Pocket Alert CLI](/tools/cli) 2.0 或更高版本后，curl 那部分可以精简为一条命令。CLI 会自行转义文本，并从 `pocketalert auth` 读取密钥：

```bash
pocketalert send -t "$title" -m "Agent run $status" -l "$level" -q >/dev/null 2>&1 || true
```

请保留 `-t` 和 `-m`，不要改用位置参数：以短横线开头的内容（比如 Markdown 列表）否则会被当作选项解析。

### 注册钩子

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

```json
{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": "/Users/you/.cursor/hooks/pocketalert.sh", "timeout": 10 }
    ]
  }
}
```

请使用脚本的绝对路径，并将 `/Users/you` 替换为你的主目录。主目录中的这个文件适用于所有项目。如果只想用于某个项目，请把它放在仓库中的 `.cursor/hooks.json`。

文件变化时，Cursor 会自动重新加载 `hooks.json`。给智能体一个小任务，结束时你的手机就会显示 **Cursor finished · your-project**。

### 想在推送中包含智能体的回复？

`stop` 不包含智能体的回复，但 `afterAgentResponse` 会以 `text` 提供。如果你想推送回复的前几行而不只是状态，可以在 `afterAgentResponse` 上注册同类脚本，并从标准输入读取 `.text`。它会在每次回复后触发，因此更嘈杂；大多数人还是保留 `stop`。

## 方式二：MCP 服务器

钩子告诉你一次运行已经结束，MCP 服务器则让智能体告诉你发生了什么。将 Pocket Alert 添加到 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "pocketalert": {
      "url": "https://mcp.pocketalert.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

由于上面提到的程序坞问题，密钥需要直接写入文件。这个文件位于你的主目录，而不是仓库中。如果你从终端启动 Cursor，并且已经导出了密钥，可以改用 `"Bearer ${env:POCKETALERT_API_KEY}"`。

打开 Cursor 设置中的 MCP 部分，确认 `pocketalert` 显示了它的工具，然后发出指令：

```text
> Run the test suite. When it's done, push me the number of failures with Pocket Alert.
```

智能体会调用 `create_message`，并附上它自己写的摘要。它还可以设置 `level`，因此测试失败时可以以 `high` 级别送达；付费套餐还支持附加操作按钮。

如果想把它变成习惯，而不是每次都在提示里说明，可以添加一条项目规则：

```text
When a task takes more than a few minutes, finish by calling the pocketalert
create_message tool with a one-line summary. Use level "high" if anything failed.
```

## 该选哪一种

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th></th><th>Stop 钩子</th><th>MCP 工具</th></tr></thead>
<tbody>
<tr><th>触发时机</th><td>每次运行都会，必定触发</td><td>由智能体自行决定</td></tr>
<tr><th>消息内容</th><td>状态：completed 或 error</td><td>智能体写的任何内容</td></tr>
<tr><th>需要</th><td>一个脚本和 <code>hooks.json</code></td><td><code>mcp.json</code> 中的一段配置</td></tr>
<tr><th>可能静默失败</th><td>仅当网络中断时</td><td>如果模型忘记调用</td></tr>
</tbody>
</table>
</div>

两者结合是不错的默认方案：钩子保证你每次运行都能收到通知，MCP 工具则在关键时刻提供具体内容。

## 审批请求

Cursor 没有“智能体正在等待审批”的钩子。`beforeShellExecution` 和 `preToolUse` 会在每条命令执行前触发，包括 Cursor 无需询问就会运行的命令，因此它们无法告诉你什么时候真正需要你介入。目前，Cursor 自身的桌面通知和它的 iOS 应用可以覆盖这种情况。

如果你希望智能体在执行有风险的步骤前停下来询问，可以给它 MCP 工具，并设置一条规则，让它发送带有“批准”和“拒绝”按钮的推送；[人工介入通知](/blog/human-in-the-loop-notifications)一文介绍了如何让它成为真正的审批关卡，而不只是礼貌的请求。

## 收不到通知怎么办

- **手动运行脚本：** `echo '{"status":"completed","workspace_roots":["/tmp/demo"]}' | ~/.cursor/hooks/pocketalert.sh`。如果没有收到推送，请去掉 `>/dev/null 2>&1`，以查看 curl 的错误信息。
- **重启 Cursor**：如果钩子仍然没有运行。通常文件变化时 Cursor 会自动重新加载 `hooks.json`。
- **检查路径**：确认 `hooks.json` 中的路径是绝对路径，并且脚本具有可执行权限。
- **对于 MCP，检查工具列表。** Cursor MCP 设置中服务器旁边的错误通常表示密钥错误或为空。

## 常见问题

### Cursor 有内置的推送通知吗？

在电脑上有：完成提示音和系统通知。在手机上，Cursor iOS 应用会在云端智能体，或通过远程控制交接的会话结束一轮对话时推送。它需要付费套餐和 iPhone。普通的本地运行仍然只在电脑上提醒，而本指南介绍的正是这部分。

### 这适用于后台和云端智能体吗？

`~/.cursor/hooks.json` 中的钩子只在你的机器上运行，因此它覆盖的是本地运行的智能体。云端智能体运行在 Cursor 的服务器上：它们会执行仓库中 `.cursor/hooks.json` 里的项目钩子，但不会执行用户钩子，而且密钥文件也不在那里。对于这些智能体，如果它已配置该 MCP 服务器，可以使用 MCP 方式；或者使用 Cursor 的 iOS 应用或 Slack 集成。

### 智能体能看到我的 API 密钥吗？

在钩子方案中不能：密钥只保存在脚本读取的文件里。在 MCP 方案中，密钥保存在 Cursor 的配置中，并发送给 MCP 服务器，而不是发送给模型。

### 这是免费的吗？

是的。钩子和 MCP 都是 Cursor 的功能，Pocket Alert 的免费套餐每天可在一台设备上发送 50 条消息。

[获取 API 密钥](/signup)，添加钩子，让 Cursor 在完成时通知你。
