所有指南

用 ntfy 自建 Claude Code 推播通知

更新於 2026年10月31日 · 閱讀時間 6 分鐘

要用 ntfy 接收 Claude Code 推播通知，請在手機安裝 ntfy app，訂閱一個難以猜到名稱的 topic，再新增一個執行 curl -d "message" https://ntfy.sh/your-topic 的 Claude Code hook。Notification hook 會在 Claude 需要權限或正在等你時通知你，Stop hook 則會在每一輪結束時立即通知。完全免費，大約十分鐘就能設定好，支援 Mac、Windows 和 Linux。

01步驟 1：選定 topic 並訂閱

ntfy 不需要註冊。topic 會在第一次有人發布或訂閱時自動建立，任何知道名稱的人都能讀取。ntfy 官方文件也說 topic 基本上就是密碼，所以請取得又長又隨機，例如 claude-7f3k9q2xw4mz。topic 名稱可使用英文字母、數字、底線和連字號，最多 64 個字元。

安裝 ntfy app（App Store、Google Play 或 F-Droid），點 +，然後在 ntfy.sh 上訂閱你的 topic。

在 terminal 測試看看：

curl -H "Title: Test" -d "Hello from my computer" https://ntfy.sh/claude-7f3k9q2xw4mz

手機應該在一兩秒內就會震動。在 Windows 上，Windows 10 和 11 內建 curl.exe，同一行指令也能用。

02步驟 2：hook 腳本（Mac 與 Linux）

Claude Code 會透過標準輸入傳給每個 hook 一個 JSON 物件。兩種事件都有 cwd 和 hook_event_name 等欄位。Notification 另外有 message 和 notification_type，Stop 則有 last_assistant_message，也就是 Claude 最後一則回覆的內容。這個腳本會把兩者都轉成好讀的推播，需要先安裝 jq（brew install jq，Debian 和 Ubuntu 則用 apt install jq）。

存成 ~/.claude/ntfy-notify.sh，再執行 chmod +x ~/.claude/ntfy-notify.sh：

#!/bin/sh
TOPIC_URL="https://ntfy.sh/claude-7f3k9q2xw4mz"

input=$(cat)
event=$(printf '%s' "$input" | jq -r '.hook_event_name')
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")

if [ "$event" = "Stop" ]; then
  title="Claude finished: $project"
  body=$(printf '%s' "$input" | jq -r '(.last_assistant_message // "Done") | .[0:300]')
  priority=3
else
  title="Claude needs you: $project"
  body=$(printf '%s' "$input" | jq -r '.message // "Needs your attention"')
  priority=4
fi

curl -s -H "Title: $title" -H "Priority: $priority" -H "Tags: robot" \
  -d "$body" "$TOPIC_URL" > /dev/null
exit 0

優先順序從 1（最低）到 5（緊急）。Tags 會在通知加上 emoji；robot 會顯示機器人臉。

03步驟 3：寫進 settings.json

把 hook 加到 ~/.claude/settings.json。如果檔案裡已經有 hooks 物件，請把這些事件加進去，不要整個取代。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "~/.claude/ntfy-notify.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.claude/ntfy-notify.sh", "async": true }
        ]
      }
    ]
  }
}

"async": true 讓 Stop hook 在背景傳送，網路慢也不會拖慢 Claude。hook 是在 session 啟動時載入的，所以請開一個新的 Claude Code session。

用 Stop 還是 idle_prompt？

Stop 會在 Claude 完成的當下觸發，就算你人就在鍵盤前也一樣。如果覺得太吵，可以拿掉 Stop 區塊，改用 matcher permission_prompt|idle_prompt。根據 Anthropic 的文件，idle_prompt 會在 Claude 完成約 60 秒後、且你這段期間都沒輸入時才觸發；permission_prompt 則在權限提示等了約六秒都沒有按鍵時觸發。這樣就免費得到一個大致「只在我不在時才通知」的篩選。Notification hook 指南和 Stop hook 指南有每個欄位與觸發時機的完整說明。

04Windows（PowerShell）

在 Windows 上，把這段存成 %USERPROFILE%\.claude\ntfy-notify.ps1，不需要額外安裝任何東西：

$in = [Console]::In.ReadToEnd() | ConvertFrom-Json
$project = Split-Path $in.cwd -Leaf

if ($in.hook_event_name -eq 'Stop') {
  $title = "Claude finished: $project"
  $body = [string]$in.last_assistant_message
  if ($body.Length -gt 300) { $body = $body.Substring(0, 300) }
  $priority = '3'
} else {
  $title = "Claude needs you: $project"
  $body = [string]$in.message
  $priority = '4'
}

Invoke-RestMethod -Method Post -Uri 'https://ntfy.sh/claude-7f3k9q2xw4mz' `
  -Headers @{ Title = $title; Priority = $priority } `
  -Body ([Text.Encoding]::UTF8.GetBytes($body)) | Out-Null

接著用這個 hook 項目取代上面的 command 那幾行：

{
  "type": "command",
  "shell": "powershell",
  "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$HOME\\.claude\\ntfy-notify.ps1\""
}

如果你是在 WSL 裡執行 Claude Code，請改用 Mac 與 Linux 的腳本；對 hook 來說，WSL 就是 Linux。

05保護隱私

推播的所有內容都會經過 ntfy 伺服器，而在 ntfy.sh 上，任何知道 topic 名稱的人都能讀取。上面的 Stop 訊息包含 Claude 回覆的開頭，可能含有程式碼或檔名。有三種方式可以加強保護：

  1. 少傳一點。把 Stop 的內文換成固定字串，例如 "Done"，標題只保留專案名稱。
  2. 使用 access token。ntfy 的任何發布都可以加上 -H "Authorization: Bearer tk_..."。在自架伺服器上，設定 auth-default-access: "deny-all"，用 ntfy user add 建立使用者，再用 ntfy token add 建立 token。
  3. 自架伺服器。ntfy 可以自行架設。若要即時推送到 iPhone app，ntfy 文件建議設定 upstream-base-url: "https://ntfy.sh"，這只會把訊息 ID 和 topic 雜湊轉送到 ntfy.sh 以喚醒手機，app 接著再從你的伺服器取得訊息。

如果 Claude Code 跑在遠端伺服器上，同一個 hook 不用改就能用，因此 ntfy 很適合用來做透過 SSH 的通知。

06Claude Code Notifier 的角色

如果只需要單向提醒，上面的設定就已經完整夠用，我們也不會勸你換掉。不過它只負責通知。當推播說 Claude 需要權限時，session 還是會一直等到你回到鍵盤前。

ntfy 確實支援會發出 HTTP 請求的動作按鈕，所以你可以自己打造回覆流程：用 PermissionRequest hook 發布請求、在第二個 topic 上等待回應，再回傳決定。有些開源專案就是這樣做的（請見比較文章）。

Claude Code Notifier 把這套流程包裝好了。配對手機後，你可以直接在手機上允許一次、在本次 session 內允許或拒絕權限，在 Claude 提問時選擇答案，並在 Claude 完成後送出下一個指示。它也會偵測你是否在場：如果你在過去 30 秒內有輸入，terminal 會照常詢問，不會等手機回應。如果你不在，terminal 會等你回覆，最長到你設定的上限，而且只要你一碰鍵盤就會停止等待。ccn 支援 Mac、Windows 和 Linux；手機 app 請參考 ccn 頁面與價格方案。

07常見問題

用 ntfy 接收 Claude Code 通知是免費的嗎？

在 ntfy.sh 上發布和訂閱都不需要帳號，伺服器對所有人開放。ntfy 也有付費方案，並可自行架設。目前的使用限制請查看 ntfy 官方網站。

為什麼我的 ntfy hook 沒有觸發？

修改 settings.json 後請開新的 Claude Code session，因為 hook 是在啟動時載入的。接著手動執行 curl 測試指令，並把範例 JSON 用 pipe 餵給腳本，例如 echo '{"hook_event_name":"Stop","cwd":"/tmp/x"}' | ~/.claude/ntfy-notify.sh。其他問題請參考疑難排解清單。

可以直接從 ntfy 通知回覆 Claude Code 嗎？

單純發布是做不到的。ntfy 的 HTTP 動作按鈕可以送出請求，但你還需要一個 hook 來等待回應，並把它轉成 Claude Code 看得懂的決定。

每種通知類型都會收到推播嗎？

只有你列出的 matcher 才會。在 Notification 項目中省略 matcher，就能收到所有類型，包括驗證和 MCP 對話框。

Claude Code Notifier Claude Code 完成或需要你處理時，手機會收到 push 通知，並可直接在手機上核准、拒絕或回覆。ccn 命令列工具在 Mac、Windows 和 Linux 上皆可免費使用。
下載 iOS 版 下載 Android 版 安裝 ccn

相關指南