Linux 上的 Claude Code 通知

01Claude Code 自带的通知行为

当 Claude 完成任务或等待授权、而你看起来不在电脑前时，Claude Code 会触发一个通知事件。根据 Anthropic 的终端配置指南，Ghostty 和 Kitty 会把它变成桌面通知；其他终端，比如 GNOME Terminal、Konsole 或 VS Code 终端，则什么都不显示。

你也可以在任何终端里改用响铃：

{
  "preferredNotifChannel": "terminal_bell"
}

响铃的效果取决于终端和桌面环境，可能是蜂鸣、闪烁，或把窗口标记为紧急。详见终端响铃指南。想要真正的通知，就用 hook。

02安装 notify-send

先检查是否已安装：

notify-send 'Claude Code' 'test'

如果提示找不到命令，就安装它：

sudo apt install libnotify-bin   # Debian, Ubuntu, Mint
sudo dnf install libnotify       # Fedora, RHEL
sudo pacman -S libnotify         # Arch

如果命令能运行但什么都没弹出，说明没有通知守护进程。GNOME、KDE Plasma、Cinnamon 和 Xfce 都自带一个。如果用的是 Sway、i3 或 Hyprland 这类平铺窗口管理器，需要自己安装并启动一个，比如 mako 或 dunst。Wayland 和 X11 都没问题，因为 notify-send 是通过 D-Bus 和守护进程通信的，不直接和显示服务打交道。

03Notification hook

这是 Anthropic hooks 指南里的 Linux 示例。把它加到 ~/.claude/settings.json 里，和已有的配置项并列：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

在 Claude Code 里输入 /hooks，就能在 Notification 下看到它。matcher 留空表示对所有通知类型都触发。主要有两种：permission_prompt，在授权请求等待约六秒且你没有输入后触发；idle_prompt，在 Claude 完成约 60 秒后触发。完整列表见 Notification hook 指南。

04在 Claude 完成时立即得知

idle_prompt 会晚一分钟才来。Stop hook 则在 Claude 结束本轮时立即运行，不需要 matcher：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send -a 'Claude Code' 'Claude Code' 'Claude has finished'"
          }
        ]
      }
    ]
  }
}

-a 设置守护进程显示的应用名。其他实用选项：-u critical 在大多数守护进程上会让通知一直留在屏幕上，直到你手动关闭；-i dialog-information 可以加个图标。关于这个事件的更多内容，见 Stop hook 指南。

05显示真实消息并播放提示音

hook 会从标准输入收到 JSON，Notification 的输入里有一个 message 字段。用脚本就能显示这段文字并播放提示音。把下面内容保存为 ~/.claude/hooks/notify-linux.sh：

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
notify-send -a 'Claude Code' 'Claude Code' "$msg"
paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true

用 chmod +x ~/.claude/hooks/notify-linux.sh 加上可执行权限，然后把 ~/.claude/hooks/notify-linux.sh 作为 hook 命令。各发行版的软件源里都有 jq。paplay 支持 PulseAudio 以及 PipeWire 的 PulseAudio 兼容层，音效文件来自 freedesktop 声音主题（Debian 和 Ubuntu 上的包名是 sound-theme-freedesktop）。也可以换成任意 .oga 或 .wav 文件。

06没有 notify-send？用转义序列

如果你的终端支持通知转义序列，hook 可以让 Claude Code 帮忙发送。hook 本身没有终端，所以要把序列放在 terminalSequence 字段里返回，由 Claude Code 写入终端。Anthropic 的参考文档列出：Ghostty、urxvt 和 Warp 用 OSC 777，Kitty 用 OSC 99。例如：

#!/bin/bash
body=$(jq -r '.message // "Needs your attention"')
seq=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

这种方式不需要 Claude Code 所在机器上有守护进程，所以也适用于通过 SSH 连接的远程服务器。

07notify-send 在 shell 里能用，从 Claude Code 里却不行

notify-send 需要你桌面登录会话的 D-Bus 地址。hook 继承 Claude Code 的环境变量，所以从桌面终端启动的 Claude Code 没问题。而通过 SSH、systemd 服务、容器，或在最初由 SSH 启动的 tmux server 里启动的 Claude Code，可能拿不到这个地址，通知也就无处可去。在启动 claude 的同一个 shell 里运行 echo $DBUS_SESSION_BUS_ADDRESS；如果输出为空，这个会话就发不出桌面通知。这些场景可以参考 tmux 指南和 SSH 指南。

08Claude Code Notifier 的定位

人在电脑前时，上面这些 hook 就够用了。但离开座位后它们就通知不到你，而且桌面通知也没法回复 Claude。

Claude Code Notifier 是一个基于 Claude Code hook 的独立工具（由 TouchTap 开发，并非 Anthropic 出品）。它的免费命令行工具 ccn 支持 Mac、Windows 和 Linux。在 Linux 上：

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

装了 Node.js 的话也可以用 npx @touchtap/ccn。它会把自己的 hook 配置加到 ~/.claude/settings.json，其他内容保持不动，并留一份备份。之后每当 Claude 完成任务、需要授权或提出问题时，都会弹出 Linux 桌面通知。这部分不需要联网，也不需要手机。每个事件只运行几毫秒，不会有常驻后台的进程。

配对一台 iPhone 或 Android 手机后，同样的事件会以 push 通知的形式发到手机上，即使机器根本没有桌面环境也可以。在手机上可以批准或拒绝授权、选择 Claude 所提问题的答案，并在 Claude 完成后发送下一条指令。手机 App 的相关信息见配对手机、ccn 页面和价格。在 Linux 上，ccn 会把 token 存放在只有你能读取的文件里。

如果装了 ccn，记得删掉自己配置的 notify-send hook，免得收到重复通知。

09常见问题