Claude Code 內建通知：terminal bell 與 preferredNotifChannel

01快速解法

如果 Claude 完成時你什麼都沒聽到，請在 ~/.claude/settings.json 中加入：

{
  "preferredNotifChannel": "terminal_bell"
}

接著確認你的 terminal 會對 bell 做出反應：播放音效、讓 Dock 圖示跳動、閃爍分頁或跳出通知。這項設定位於 terminal 本身，而不是 Claude Code。在 Mac、Windows 和 Linux 上，大多數 terminal 的偏好設定中都有「bell」或「alert」區段。

02preferredNotifChannel 所有值

此設定可放在任何設定檔中：使用者（~/.claude/settings.json）、專案（.claude/settings.json）或本機（.claude/settings.local.json）。舊版本將它存放在 ~/.claude.json，Claude Code 仍會讀取留在那裡的值。

03內建通知的觸發時機

根據 Anthropic 的文件，內建提醒與 Notification hook 的觸發時機相同。在 terminal 工作階段中：

• 權限 prompt：prompt 等待約六秒且沒有任何按鍵輸入後觸發。每按一次鍵都會重新計時。
• 完成：Claude 停止後約 60 秒觸發，且前提是你在這期間沒有輸入，也沒有仍在執行的背景 agent。

因此，內建的「完成」提醒刻意不即時發送。它的設計是在你離開座位時通知你，而不是在你盯著畫面時打擾你。如果你希望每輪結束時立即收到提醒，請改用 Stop hook（請參閱Stop hook 指南）。

04各 terminal 設定

iTerm2（macOS）

iTerm2 預設會收到桌面通知，但必須先允許，iTerm2 才會顯示：

1. 開啟 Settings > Profiles > Terminal。
2. 勾選 Notification Center Alerts。
3. 點選 Filter Alerts，並啟用 Send escape sequence-generated alerts。

另外，請確認已在 System Settings > Notifications 中允許 iTerm2 顯示通知。

Apple Terminal（macOS）

Apple Terminal 不會收到桌面通知。使用 "auto" 時，Claude Code 只有在偵測到最前方視窗的描述檔關閉了 Audible bell 時，才會發送無聲的 bell。若描述檔開啟了 Visual bell 或 Dock 跳動選項，bell 會以視窗閃爍呈現，或在 Terminal 位於背景時讓 Dock 圖示跳動。

有個細節要留意。如果你接受了 Claude Code 首次執行時的 terminal 設定 prompt，它會執行 /terminal-setup，把 Apple Terminal 描述檔的音訊鈴聲關掉。若想聽到聲音，請設定 "terminal_bell"，並在 Settings > Profiles > Advanced 中重新開啟 Audible bell。

Ghostty 與 Kitty（macOS 與 Linux）

兩者都不需設定即可收到桌面通知，並會轉送到作業系統的通知中心。

其他 terminal

Windows Terminal、GNOME Terminal、Konsole、Alacritty、WezTerm、Warp 以及 IDE 內建的 terminal，預設都不會收到任何提醒。請設定 "terminal_bell" 並開啟 terminal 本身的鈴聲處理，或改用 hook。IDE terminal 有各自的特殊狀況，請參考VS Code、Cursor 與 JetBrains 指南。

05透過 SSH 與在 tmux 中使用

桌面通知是一段由你本機 terminal 解讀的 escape sequence，所以即使 Claude Code 是透過 SSH 在遠端伺服器上執行，通知一樣會送到你面前。Ghostty 和 Kitty 不需額外設定就會轉發；iTerm2 則需要完成上述的提醒設定。

在 tmux 中，除非允許 passthrough，否則這段 sequence 會被吃掉。請將以下內容加入 ~/.tmux.conf，然後執行 tmux source-file ~/.tmux.conf：

set -g allow-passthrough on

detached session 則是另一回事：沒有 terminal 連接時，就沒有東西能顯示提醒。請參考tmux 指南與透過 SSH 接收通知。

06同時使用內建提醒與 hook

Notification hook 會與內建提醒同時執行，而不是取代它。Anthropic 的文件明確指出，即使設為 "notifications_disabled"，hook 仍會觸發：這個設定只會改變 Claude Code 提醒你的方式，不影響 hook 是否執行。因此可以清楚分工：

• 在座位上時，保留 "auto" 或 "terminal_bell" 作為提醒。
• 其他需求則加上 hook，例如播放系統音效、在原本收不到通知的 terminal 顯示桌面通知，或透過 ntfy push 到手機。
• 如果 hook 已經會顯示桌面通知，請設定 "notifications_disabled"，以免重複收到兩則。

例如，以下設定會在 Claude 需要你處理時，於 macOS 的任何 terminal 中播放音效：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

Linux 與 Windows 的對應做法請見Linux 指南與Windows 指南。

07內建選項的限制

• 只限於這台電腦。鈴聲或通知來自你螢幕上的 terminal，人一走到廚房就會錯過。
• 取決於 terminal。許多熱門 terminal 在你更改設定前都收不到任何提醒。
• 無法直接回應。它只會告訴你 Claude 在等你，你還是得回到鍵盤前。

Anthropic 的 Remote Control 搭配 Claude 行動 App，是官方接收手機 push 的方式。比較指南中有它與其他選項的對照。

08Claude Code Notifier 的角色

如果你都在座位上工作，內建提醒加上 "terminal_bell" 可能就夠了。Claude Code Notifier 則是為你不在座位上時設計的。它的命令列工具 ccn 以 Claude Code hook 的形式執行，因此在 Mac、Windows 與 Linux 的任何 terminal 都能運作，不論有沒有設定鈴聲。單獨使用時，它會在 Claude 完成工作、需要權限或提出問題時顯示桌面通知。配對手機後，你可以直接在手機上允許或拒絕權限、回答 Claude 的問題並送出下一個指令；如果你在過去 30 秒內有打字，手機上就完全不會出現待處理項目。請見 ccn 頁面。

09常見問題