如何在 Claude Code 完成时收到通知

01Claude Code 自带的通知行为

Claude Code 在判断你不在 terminal 前时，本身就会尝试提醒你。默认情况下，它在 iTerm2、Ghostty 和 Kitty 中发送桌面通知，在 Apple Terminal 中可能会响铃，在其他 terminal 中则什么也不做。另外，iTerm2 还需要先打开提醒设置才会显示通知。

所以如果你用的是 VS Code 内置 terminal、Warp、Windows Terminal 或大多数 Linux terminal，通常什么提醒都收不到。你可以通过 preferredNotifChannel 设置强制使用 terminal 响铃，详见terminal 响铃指南。想在任何 terminal 中都收到真正的桌面通知，就需要用 hook。

02需要的两个 hook

hook 是 Claude Code 在会话中特定时间点执行的命令。这里用到其中两个：

Stop 是最快的，每轮结束时立即执行。Notification 类型则只在你离开时才会触发：每次按键都会推迟它，所以你盯着屏幕时不会被打扰。如果想在 Claude 请求权限的那一刻就收到信号，请改用 PermissionRequest hook，详见PermissionRequest 指南。

关于 hook 的通用机制（事件、matcher、设置文件、退出码），请参阅Claude Code hook 详解。

03macOS 上的可用配置

打开 ~/.claude/settings.json（不存在就新建），加入以下内容。如果文件里已经有 hooks 对象，就把 Stop 和 Notification 作为键加到里面，不要整个替换。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Stop 没有 matcher，所以每轮都会触发。Notification 的 matcher 把它限制在表示“该回来了”的两种类型上。

如果没有任何通知，可能是 macOS 屏蔽了脚本编辑器（Script Editor），而 osascript 正是靠它来显示通知。先在 Terminal 中运行一次 osascript -e 'display notification "test"'，然后打开系统设置 > 通知，找到脚本编辑器，开启允许通知。

04在 Linux 和 Windows 上的相同配置

保持上面的 JSON 结构不变，只替换 command 字符串即可。

Linux（需要桌面通知守护进程，因此无法在 headless 服务器上使用）：

"command": "notify-send 'Claude Code' 'Claude has finished'"

如果没有 notify-send，在 Debian 和 Ubuntu 上安装 libnotify-bin，其他发行版请安装对应的包。SSH 和服务器环境请参阅通过 SSH 接收通知。

Windows（PowerShell）。Anthropic 官方示例弹出的是消息框，而不是角落里的 toast 通知：

"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude has finished', 'Claude Code')\""

消息框可能会出现在 terminal 窗口后面，所以先在 PowerShell 里测试一下命令。在 WSL 下，需要能通过 Windows interop 调用 powershell.exe。更多方案见 Windows 指南。

05验证是否生效

1. 在 Claude Code 中输入 /hooks，应该能在 Stop 和 Notification 下看到你的 hook。
2. 随便问 Claude 一个简短的问题。它回复后，应该会弹出 Stop 通知。
3. 让它做一件需要权限的事，然后切到别的窗口等待。大约六秒后会收到 permission_prompt 通知。

对 settings.json 的修改通常会立即生效。如果 /hooks 里没有显示某个 hook，检查文件是否是合法的 JSON（不能有尾随逗号，也不能有注释）。用 claude --debug 启动 Claude Code，可以看到每个 hook 的执行情况。更多解决办法见故障排查清单。

06在手机上接收提醒

桌面通知只有你坐在电脑前才有用。一旦离开，就需要把提醒发到别处。常见的方式有三种：

• 自建 push 服务，比如 ntfy，在同样的 hook 里用 curl 调用。便宜又灵活。见 ntfy 指南。
• 聊天 webhook，适用于 Telegram、Slack 或 Discord。如果你平时就泡在聊天工具里，这个很合适。见聊天 webhook 指南。
• Claude Code Notifier，帮你配好 hook，还能直接在手机上回复。

如果只想收到一个提醒，自己动手的方案就够用了。它们的局限在于是单向的：你知道 Claude 在等你，但要批准什么操作，还得回到键盘前。

Claude Code Notifier 是一个独立工具（并非 Anthropic 出品），由两部分组成：ccn，一个适用于 Mac、Windows 和 Linux 的免费命令行工具；以及 iPhone 和 Android 应用。一行命令即可安装：

curl -fsSL https://claudecodenotifier.com/install.sh | sh

在 Windows 上，在 PowerShell 中运行 irm https://claudecodenotifier.com/install.ps1 | iex（Windows 支持目前处于 beta 阶段）。其他安装方式，包括 Homebrew、npx @touchtap/ccn 和 Claude Code 插件，见 ccn 页面。

安装时会添加七个 hook 条目，每个都运行 ccn hook，settings.json 的其余内容保持不变，并在同目录下保存一份一次性备份。即使不连手机，ccn 也会在 Claude 完成、需要权限或提问时在电脑上弹出桌面通知。这部分免费，而且无需联网。

用 ccn pair 配对手机后，还能获得：

• 每轮结束时立即收到“Claude 已完成”的 push；
• 权限请求可以选择允许一次、在本次会话中允许或拒绝；
• 在手机上回答 Claude 的选择题；
• Claude 完成后，可在输入框里直接发送下一条指令。

如果你在最近 30 秒内打过字，就不会等待手机，terminal 会照常询问。应用需要订阅或买断，见价格。配对手机里有完整的设置步骤。

07常见问题