返回博客

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

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

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 密钥 页面的 API 密钥,以及手机上的 应用。免费套餐即可满足需求。

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

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:

#!/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 '{}'
chmod +x ~/.gemini/hooks/pocketalert.sh

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

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

在 hooks 中添加 ~/.gemini/settings.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 步:测试

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

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

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

手机上会收到什么

事件标题正文级别
本轮完成Gemini 已完成 · api回复的前 300 个字符default
工具权限Gemini 需要审批 · api来自 Gemini CLI 的权限提示信息high

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

或让 Gemini 通过 MCP 发送

使用 Pocket Alert MCP 服务器,Gemini 就能在你指定的时机自行编写并发送推送。在命令行中添加:

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 中的结果如下:

{
  "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 可以阻止工具调用,因此借助你的手机调用的端点,可以实现审批关卡;人在回路通知 一文介绍了这种模式。

能在 GitHub Actions 中使用吗?

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

免费吗?

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

获取 API 密钥,添加 Hook,让 Gemini 在需要你的时候找到你。

分享这篇文章