# Gemini CLI 推送通知：任务完成或等待审批时提醒你

> Gemini CLI 完成一轮对话或请求运行工具时，向手机发送推送通知。在 settings.json 中配置两个 Hook、一个脚本，再加上 Pocket Alert MCP 服务器即可。

*15.10.2026*

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

Gemini CLI 自身可以发出通知，但只能在终端中显示：开启 `general.enableNotifications`，它会在完成任务或需要你处理时发送桌面通知或响铃。当你就在电脑前、终端在另一个标签页时，这很有用。但你不在电脑前时，它就帮不上忙了。

Hook 可以填补这个空缺。自 v0.26 起，Hook 默认开启，其中两个事件正适合用手机推送通知来提醒：

- **AfterAgent**：Gemini 完成了本轮回复。负载中包含回复内容。
- **Notification**：Gemini 请求运行工具的许可。

本指南会通过 Pocket Alert 把这两类事件发送到你的手机上。

## 关于 Gemini CLI 的说明

根据 Google 的文档，自 2026 年 6 月 18 日起，免费套餐和 Google One 套餐的用户将改用 Antigravity CLI，而 Gemini CLI 则继续面向使用付费 Gemini API 密钥、Vertex AI 或企业访问权限的用户。本指南针对的是 Gemini CLI。如果你使用的是 Antigravity CLI，请查阅其文档中关于 Hook 的部分。

## 准备工作

- Gemini CLI v0.26 或更高版本。
- `jq` 和 `curl`。
- 一个 Pocket Alert 账户，一个来自 [API 密钥](/account/apikeys) 页面的 API 密钥，以及手机上的 [应用](/get-app)。免费套餐即可满足需求。

请把密钥保存到文件中。在启用环境变量脱敏或在 GitHub Actions 中运行时，Gemini CLI 可能会在执行 Hook 前移除名称包含 `KEY` 或 `TOKEN` 的环境变量，而从文件读取的密钥不会受影响：

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

## 第 1 步：Hook 脚本

Gemini CLI 会通过标准输入向 Hook 发送一个 JSON 对象，其中包含 `hook_event_name` 和 `cwd`。`AfterAgent` 还会添加 `prompt_response`；`Notification` 还会添加 `notification_type` 和 `message`。将以下内容保存为 `~/.gemini/hooks/pocketalert.sh`：

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

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  AfterAgent)
    title="Gemini finished · $project"
    message=$(jq -r '.prompt_response // "Turn complete"' <<<"$payload")
    level=default ;;
  Notification)
    title="Gemini needs approval · $project"
    message=$(jq -r '.message // "Waiting for tool permission"' <<<"$payload")
    level=high ;;
  *) echo '{}'; 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 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 ~/.gemini/hooks/pocketalert.sh
```

Gemini CLI 会将 Hook 的标准输出解析为 JSON，因此脚本只输出 `{}`，不输出其他内容；curl 的输出则重定向到 `/dev/null`。`AfterAgent` Hook 返回退出码 2 会拒绝该回复并促使 Gemini 重试，所以脚本从不返回该退出码。

### 或使用 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 步：注册 Hook

在 `hooks` 中添加 `~/.gemini/settings.json` 配置块，并与文件中已有的内容合并：

```json
{
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "pocketalert-done",
            "type": "command",
            "command": "/Users/you/.gemini/hooks/pocketalert.sh",
            "timeout": 10000
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "pocketalert-approval",
            "type": "command",
            "command": "/Users/you/.gemini/hooks/pocketalert.sh",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}
```

将 `/Users/you` 替换为你的主目录。这里的 `timeout` 单位是毫秒，与某些其他智能体不同。若只想针对单个项目生效，可将同样的配置块放入代码仓库中的 `.gemini/settings.json`；Gemini CLI 只会在受信任的文件夹中运行项目级 Hook。

## 第 3 步：测试

先用一个模拟事件运行脚本：

```bash
echo '{"hook_event_name":"AfterAgent","cwd":"/tmp/demo","prompt_response":"Hook test"}' \
  | ~/.gemini/hooks/pocketalert.sh
```

然后启动 Gemini CLI，并给它一个最终需要调用工具且需要审批的任务，例如“创建一个名为 notes.txt 的文件”。等待审批时，你会收到 **Gemini 需要审批**；你允许之后、本轮结束时，会收到 **Gemini 已完成**。

## 手机上会收到什么

<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>Gemini 已完成 · api</td><td>回复的前 300 个字符</td><td>default</td></tr>
<tr><th>工具权限</th><td>Gemini 需要审批 · api</td><td>来自 Gemini CLI 的权限提示信息</td><td>high</td></tr>
</tbody>
</table>
</div>

`high` 级别的通知在 iPhone 上会以时效性通知的形式送达，因此审批请求可以穿透专注模式。所有推送都会保留在应用和网页控制台中。

## 或让 Gemini 通过 MCP 发送

使用 [Pocket Alert MCP 服务器](/tools/mcp)，Gemini 就能在你指定的时机自行编写并发送推送。在命令行中添加：

```bash
gemini mcp add --scope user --transport http \
  --header 'Authorization: Bearer $POCKETALERT_API_KEY' \
  pocketalert https://mcp.pocketalert.app/mcp
```

单引号会让 `$POCKETALERT_API_KEY` 在设置文件中保持为变量，而不是把密钥明文写入文件；Gemini CLI 会在连接时展开该变量，因此请在启动 `gemini` 的 Shell 中导出该变量。如果不加 `--scope user`，服务器只会添加到当前项目中。

`~/.gemini/settings.json` 中的结果如下：

```json
{
  "mcpServers": {
    "pocketalert": {
      "url": "https://mcp.pocketalert.app/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $POCKETALERT_API_KEY" }
    }
  }
}
```

在 Gemini CLI 中运行 `/mcp`，即可查看服务器及其工具。之后，像“运行迁移，完成后把行数推送给我”这样的提示会以调用 `create_message` 结束。

## 如果没有收到通知

- **运行测试命令。** 没有推送通常是密钥或网络问题；去掉 `>/dev/null 2>&1`，即可看到 curl 的响应。
- **确认 Hook 已启用。** 它们默认开启，但设置中的 `hooksConfig.enabled: false` 会将其关闭。
- **检查 `command` 中的路径**是否为绝对路径，并且脚本具有可执行权限。
- **检查标准输出。** 标准输出中只要不是 JSON，Gemini CLI 就会忽略该 Hook 的结果。确保脚本中没有其他内容输出到标准输出。

## 常见问题

### 它和 `general.enableNotifications` 有什么区别？

该设置会在 Gemini 需要你或完成任务时，向你的电脑发送终端通知。Hook 可以运行任意命令，因此能够触达你的手机、保留历史记录，并支持优先级级别。

### 我能在手机上批准工具调用吗？

用这个脚本做不到：它只告诉你 Gemini 在等待，批准仍需在终端中完成。`BeforeTool` Hook 可以阻止工具调用，因此借助你的手机调用的端点，可以实现审批关卡；[人在回路通知](/blog/human-in-the-loop-notifications) 一文介绍了这种模式。

### 能在 GitHub Actions 中使用吗？

可以，而且在那里密钥文件的方式尤为重要：在 GitHub Actions 中，Gemini CLI 会从 Hook 的运行环境中移除名称包含 `KEY` 或 `TOKEN` 的变量。请在之前的步骤中，把来自 Secret 的密钥写入一个文件。

### 免费吗？

Hook 是 Gemini CLI 的功能，而 Pocket Alert 免费套餐每天可在一台设备上发送 50 条消息。至于 Gemini 本身，正如上文所述，CLI 需要付费的 API 密钥或企业访问权限。

[获取 API 密钥](/signup)，添加 Hook，让 Gemini 在需要你的时候找到你。
