Claude Code Hooks 在遠端 Mac 不執行怎麼辦？2026 排查指南

判斷框｜適合：Claude Code 官方文件將 Hook 退出碼 0 定義為成功、2 定義為阻擋錯誤；因此，Claude Code Hooks 遠端 Mac 不執行時，先核對事件與 matcher，再檢查腳本權限、SSH 環境變數和工作目錄，最後判讀退出狀態與輸出。不要先重裝，也不要關閉權限控制。參考官方 Hook 參考中的退出碼說明。

適合透過 SSH 在遠端 Mac 使用 Claude Code、需要定位 Hook 未觸發或執行異常的開發者。
也適合維護共用 Hook 設定的工程師，以及需要在 macOS 執行建置、格式化或測試的 CI 工程師。

Claude Code Hooks 遠端 Mac 不執行：先分辨故障在哪一層

「沒有反應」不是單一故障。事件可能根本沒有發生、matcher 沒有匹配、命令未能啟動，也可能腳本已執行，只是結果沒有按預期傳回。先記錄 Claude Code 版本、啟動方式、會話類型和可重現的操作；每次只改一項設定，才能把原因和修復對上。

觀察到的現象	優先檢查	能判斷什麼
操作後完全沒有 Hook 記錄	事件名稱、操作是否會觸發該事件、設定檔範圍	事件未觸發或設定未載入
有 Hook 記錄，但命令未啟動	matcher、命令路徑、shebang、執行權限	配置匹配了，但腳本啟動條件不成立
腳本已執行，結果不符合預期	工作目錄、PATH、標準輸出、錯誤輸出與退出碼	問題在腳本本身或 Hook 結果處理

Claude Code 的 Hook 會依特定事件執行；事件與設定格式應以官方 Hook 參考為準。若你把使用者層級設定和專案層級設定混在一起，還要確認目前會話實際讀取的是哪個範圍，而不是只看本機曾經成功的設定。官方設定文件說明了設定檔的用途與層級。

Claude Code Hooks 為什麼沒有觸發？

先看選用的事件是否對應你做的操作，再確認 matcher 是否符合該事件提供的工具或條件。不要只因為設定中有一段 Hook JSON，就認定它已經載入並匹配。

把問題縮成一個可觀察的測試：暫時使用不改動專案內容的命令，例如只輸出固定標記，然後執行一次確定會觸發目標事件的操作。如果日誌沒有出現標記，繼續查事件、matcher 和設定範圍；如果有標記，故障點就不在「完全未觸發」這一層。

對照項目	核查方式	修正方向
事件	查官方事件定義，確認該操作是否對應所選事件	改用符合操作的事件，或調整測試操作
Matcher	對照事件所提供的工具名稱或匹配條件	暫時縮小條件，避免測試時加入不必要的匹配規則
設定範圍	檢查使用者設定與專案設定中實際載入的內容	先在單一位置驗證，再決定是否複製到共用設定

事件和 matcher 的實際作用受當前 Claude Code 版本及設定內容影響；不要把其他版本的範例直接當成目前會話的觸發保證。配置格式可再對照官方 Hook 指南。

腳本沒有啟動時，先檢查路徑與執行條件

Hook 命令是在遠端主機上執行，不會自動沿用你本機電腦的檔案路徑。從 SSH 連線後，在同一個遠端帳號和專案目錄下，逐項確認命令是否存在、腳本是否可讀取，以及啟動方式是否正確。

pwd
ls -l ./scripts/check.sh
head -n 1 ./scripts/check.sh
command -v bash

結果要能回答幾件事：目前目錄是否為預期專案；設定中的相對路徑是否從這裡解析；shebang 指向的解譯器是否找得到；檔案是否具備預期的執行權限。若設定命令直接執行腳本，確認檔案可執行；若改由解譯器呼叫，則要確認解譯器路徑與腳本路徑都正確。官方範例與設定格式可參照Hook 指南及設定說明。

避免一開始就對整個專案遞迴開放權限。先檢查目標檔案的權限，再用最小範圍修正；Hook 只應取得完成該項任務所需的命令能力。

SSH 連線後 Hook 找不到命令怎麼辦？

互動式終端和 Hook 啟動時的環境可能不同。你在 SSH 終端輸入 brew 或專案命令能成功，不代表 Hook 執行時使用相同 PATH、環境變數或工作目錄。遠端 Mac 開發環境的排障，應以 Hook 實際啟動時可見的環境為準。

可以暫時在診斷腳本中輸出必要資訊，將結果寫到你有權限檢查的日誌位置：

printf 'PWD=%s\nPATH=%s\n' "$PWD" "$PATH"
command -v brew || true
command -v xcodebuild || true

若命令找不到，先在遠端主機確認它的實際位置，再選擇明確指定可執行檔路徑，或在 Hook 設定中提供必要環境。不要直接複製本機終端的 PATH，因為其中可能含有只在本機成立的目錄或敏感設定。Claude Code 提供的環境變數及相關說明，應以官方環境變數參考為準。

排查時只輸出診斷所需的變數。避免把存取憑證、私鑰內容或完整環境傾印到一般日誌；Hook 的安全邊界仍由你的專案設定與團隊流程負責。

如果 Hook 要執行專案內的腳本，另外核對工作目錄是否正確；相對路徑依執行時目錄解析，不能單憑設定檔所在位置推定。必要時將工作目錄或腳本路徑改成明確值，然後以同一個 SSH 會話重測。

腳本已執行，為什麼看不到預期結果？

將「腳本有沒有啟動」和「Claude Code 如何處理 Hook 結果」分開查。先檢查標準輸出、標準錯誤輸出與退出碼，再確認該事件的輸出是用來阻擋操作、回傳資訊，還是只供診斷。Hook 退出碼 0 與 2 的意義不同，不能把任何非零結果都當成同一類故障；詳細規則以官方 Hook 文件為準。

啟動診斷時，可在終端使用官方配置除錯方式查看載入與執行線索：

claude --debug

也可以在 Claude Code 會話中使用 /hooks 檢視已設定的 Hook。官方配置除錯說明提供了進一步的診斷方向。閱讀輸出時，標記 Hook 對應的事件和命令，再比較腳本自身的錯誤與 Claude Code 對結果的處理；如果記錄顯示腳本已完成，卻沒有預期的對話效果，就不要繼續改檔案權限。

修復後如何驗收 macOS 工具鏈與安全邊界？

先用不會更動檔案的命令確認 Hook 觸發與輸出，再逐步換成專案中的實際工作負載。每次測試都在同一遠端帳號、相同啟動方式及相同設定範圍下進行，否則你無法確認修復是否適用於原本出錯的會話。

驗收時依序核對：

重新執行可重現操作，確認預期事件和 matcher 有記錄。
確認命令在遠端 Mac 上找到正確的解譯器、腳本及工具鏈。
查看腳本標準輸出、錯誤輸出和退出狀態，確認結果符合事件預期。
以專案的格式化、測試或建置任務驗證，而不是只以空命令作為最終驗收。
檢查失敗時會不會刪除重要檔案、輸出憑證，或以超出任務需要的權限執行。

如果 Hook 涉及允許或阻擋命令，請同時閱讀官方權限說明與安全文件。不建議用停用權限檢查的方式讓測試通過：那會改變安全條件，並沒有解決事件、路徑或腳本本身的錯誤。

若你正在比較本機 Mac、Linux 主機與遠端主機，也可以參考遠端 Mac 方案比較，把需要 macOS 工具鏈的工作和一般伺服器任務分開評估。

對於偶爾執行、需要存取特定實體介面的工作，或長期高負載且希望自行控制硬體的工作，租用遠端主機未必是合適選擇；自購 Mac 或本機執行可能更符合要求。反過來說，如果你目前以 Windows 或 Linux 為主，卻因 Xcode 或其他 macOS 工具鏈而必須維護一台 Mac，現有做法可能帶來硬體閒置、維護責任及環境不一致等成本。此時，OakVM 的遠端 Mac 租用可讓你在需要時使用真實 macOS 工具鏈；先依本文排查 Hook，再按遠端 Mac 開發環境配置與接入需求洽詢，確認它是否適合你的工作負載。