macOS 上的 Claude Code 通知

01Claude Code 內建的行為

當 Claude Code 完成任務或等待權限，而你似乎不在 terminal 前時，它會觸發通知事件。根據 Anthropic 的 terminal 指南，實際看到的效果取決於使用的 terminal：

在 iTerm2 中，開啟 Settings > Profiles > Terminal，勾選 Notification Center Alerts，接著點選 Filter Alerts 並開啟 Send escape sequence-generated alerts。另外也要確認 系統設定 > 通知 中允許 iTerm2 發送通知。

在 Apple Terminal 中，至少可以讓它發出聲音。在 ~/.claude/settings.json 設定 "preferredNotifChannel": "terminal_bell"，並在 設定 > 描述檔 > 進階 中開啟 聲音響鈴。詳細做法請參考 terminal 響鈴指南。

內建提醒有其限制：只有在 Claude Code 判斷你不在時才會觸發，只會告訴你「有事發生」，而且永遠不會傳到電腦以外的地方。

02使用 osascript 的通知 hook

Hook 在任何 terminal 中都能運作，包括 IDE 內建的 terminal。以下是 Anthropic hooks 指南中的 macOS 範例。將它加入 ~/.claude/settings.json，並保留原有的其他設定：

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

在 Claude Code 中輸入 /hooks，確認它出現在 Notification 底下。

工序指令編寫程式（Script Editor）的權限

osascript 是以 Script Editor 的身分發送通知。如果 Script Editor 沒有通知權限，指令會靜默失敗，macOS 也不會跳出詢問。請先在 Terminal 執行一次：

osascript -e 'display notification "test"'

第一次執行時不會出現任何東西。開啟 系統設定 > 通知，找到 工序指令編寫程式，開啟 允許通知。再執行一次指令，就應該會看到測試通知。

觸發時機

空的 matcher 會對所有通知類型觸發。最需要注意的兩種是 permission_prompt（Claude 等待核准約六秒，而你還沒輸入）和 idle_prompt（Claude 約 60 秒前已完成，而你之後都沒有輸入）。所有類型及觸發時機請見 Notification hook 指南。

03在 Claude 完成的當下收到通知

idle_prompt 要等一分鐘。如果想立刻收到通知，請加入 Stop hook，它會在 Claude 結束回合時執行。Stop 不需要 matcher：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

sound name 可以使用 /System/Library/Sounds 中的任何音效，例如 Glass、Ping 或 Hero。如果只想要聲音，可以直接用 afplay /System/Library/Sounds/Glass.aiff 作為指令。更多關於此事件的說明請見 Stop hook 指南。

04顯示實際訊息

Hook 會從標準輸入接收 JSON。Notification 的輸入包含 message 欄位，例如「Claude needs your permission」。用一個小腳本就能把這段文字放進通知。將以下內容存為 ~/.claude/hooks/notify-mac.sh：

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
osascript -e 'on run argv' \
  -e 'display notification (item 1 of argv) with title "Claude Code"' \
  -e 'end run' "$msg"

將文字作為參數傳入，而不是放在 AppleScript 字串裡，這樣訊息中的引號就不會破壞指令。使用 chmod +x ~/.claude/hooks/notify-mac.sh 設為可執行，並將 hook 指令設為 ~/.claude/hooks/notify-mac.sh。此腳本需要 jq（若 jq --version 執行失敗，請執行 brew install jq）。

05terminal-notifier：點一下就回到 terminal

osascript 發出的通知被點擊時會開啟 Script Editor，這通常不是你想去的地方。terminal-notifier 可以讓你指定要切換到前景的 app：

brew install terminal-notifier
terminal-notifier -title "Claude Code" -message "Claude has finished" -sound default -activate com.googlecode.iterm2

Apple Terminal 請用 com.apple.Terminal，或改用你編輯器的 bundle ID。同樣的指令可以放進 hook 的 command 欄位。第一次使用時，請在系統設定中允許 terminal-notifier 發送通知。

06專注模式與勿擾模式

以上這些都是一般的 macOS 通知，因此專注模式可能會把它們隱藏。如果通知在某些時段消失，請檢查 系統設定 > 專注模式，並允許發送通知的 app（Script Editor、terminal-notifier 或你的 terminal）。若想讓通知依照你自訂的時段運作，請參考 安靜時段與勿擾模式。

07Claude Code Notifier 的角色

如果你都坐在 Mac 前、只需要一點提醒，上述 hook 就很夠用了。但當你離開座位時就不夠了，因為 Mac 通知無法在你去廚房時找到你，也無法替你回覆 Claude。

Claude Code Notifier 是一款建立在相同 hook 之上的獨立工具（由 TouchTap 開發，並非 Anthropic 出品）。它的免費命令列工具 ccn 可在 Mac、Windows 和 Linux 上執行。在 Mac 上安裝：

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

或使用 Homebrew：brew trust --formula touch-tap/tap/ccn && brew install touch-tap/tap/ccn。它會在 ~/.claude/settings.json 加入自己的 hook 設定，不會動到檔案其他內容，並保留備份。之後每當 Claude 完成、需要權限或提出問題時，都會顯示 macOS 通知，不需要網路，也不需要手機。

如果配對了 iPhone 或 Android 手機，同樣的事件會以 push 通知送達，你可以直接在手機上允許或拒絕權限、選擇 Claude 問題的答案，或傳送下一個指令。如果你在過去 30 秒內有輸入，terminal 會照常詢問，手機上不會有待處理的請求。請參考 配對手機 和 ccn 頁面。手機 app 需要訂閱或買斷，請見 價格方案。

如果加入了 ccn，請移除你自己設定的 osascript hook，否則每個事件都會收到兩則通知。另外還有一個較舊的 Mac 選單列 app，請勿在同一台 Mac 上與 ccn 同時執行。

08常見問題