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 的部分。
准备工作
请把密钥保存到文件中。在启用环境变量脱敏或在 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 在需要你的时候找到你。