Linux 上的 Claude Code 通知

01Claude Code 內建的行為

當 Claude 完成任務或在等待權限、而你似乎不在電腦前時，Claude Code 會觸發通知事件。根據 Anthropic 的 terminal 指南，Ghostty 和 Kitty 會將它轉成桌面通知；其他 terminal，例如 GNOME Terminal、Konsole 或 VS Code terminal，則什麼都不會顯示。

你也可以改成在任何 terminal 中使用響鈴：

{
  "preferredNotifChannel": "terminal_bell"
}

響鈴的效果取決於 terminal 和桌面環境，可能是嗶一聲、閃爍，或把視窗標記為需要注意。詳見 terminal 響鈴指南。若要真正的通知，請使用 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

如果指令能執行卻沒有任何東西出現，代表你沒有通知 daemon。GNOME、KDE Plasma、Cinnamon 和 Xfce 都有內建；若使用 Sway、i3 或 Hyprland 等 tiling 視窗管理器，就要自行安裝並啟動，例如 mako 或 dunst。Wayland 和 X11 都適用，因為 notify-send 是透過 D-Bus 與 daemon 溝通，而非直接跟顯示伺服器溝通。

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 用來設定 daemon 顯示的 App 名稱。其他實用選項：-u critical 在大多數 daemon 上會讓通知持續顯示到你手動關閉，-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？改用跳脫序列

如果你的 terminal 支援通知用的跳脫序列，hook 可以請 Claude Code 代為送出。Hook 本身沒有自己的 terminal，所以要把序列放在 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 的機器上有 daemon，因此也適用於透過 SSH 連線的遠端伺服器。

07notify-send 在 shell 裡能用，從 Claude Code 執行卻沒反應

notify-send 需要你桌面登入工作階段的 D-Bus session 位址。Hook 會繼承 Claude Code 的環境變數，所以從桌面 terminal 啟動的 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。它會在 ~/.claude/settings.json 中加入自己的 hook 項目，其他設定保持不動，並保留一份備份。之後每當 Claude 完成、需要權限或提出問題時，就會顯示 Linux 桌面通知。這部分不需要網路也不需要手機。每個事件只執行幾毫秒，不會有任何程式常駐背景。

配對 iPhone 或 Android 手機後，同樣的事件會以 push 通知送達，即使機器完全沒有桌面環境也可以。你可以在手機上允許或拒絕權限、選擇 Claude 問題的答案，並在 Claude 完成後送出下一個指示。手機 App 相關資訊請見配對手機、ccn 頁面和價格方案。在 Linux 上，ccn 會將 token 存放在只有你能讀取的檔案中。

如果安裝了 ccn，請移除你自己設定的 notify-send hook，以免收到重複通知。

09常見問題