SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Claude Code Hooks 設定、事件與 exit code 2

了解 Claude Code Hooks 的設定位置與觸發事件,以及 exit code 2 如何在工具呼叫前取消操作,並查看 stderr 回傳原因與安全性代價。

Claude Code hook 是什麼

Claude Code hook 是 Claude Code 在自身生命週期的固定節點自動執行的 shell 命令。這就是 hook 與規則檔的全部差異。CLAUDE.md 中的指示是建議,模型會將其與 context 中的其他內容一併權衡。hook 是程式碼,不論模型是否同意都會執行。如果 agent 一再略過你已經提醒兩次的 formatter,就不需要更強硬的指示,而是需要 hook。

這項機制很簡單。你在設定檔中以事件名稱註冊命令。事件觸發時,Claude Code 會執行該命令,並以 JSON(JavaScript object notation)格式將事件資料寫入其標準輸入(stdin)。你的命令讀取這些資料、執行工作,然後以結束狀態回應。PreToolUse hook 回傳 exit 2 時,會在工具呼叫執行前取消該呼叫;除非 hook 同時輸出包含阻擋決策的 JSON,否則你的 script 寫入標準錯誤(stderr)的內容會傳回模型,作為取消原因。若輸出包含阻擋決策,其原因優先採用。

此處的事件名稱與欄位名稱來自 Claude Code hooks reference,資料確認日期為 November 12, 2026。這個介面變動很快,因此在從任何 blog post(包括本文)複製 JSON 前,請先查看自己版本的 reference。使用 claude --version 列印目前版本。

Hook 設定的位置

Hook 是設定檔中的 JSON 區塊。共有 6 個位置可以放置 hook,而設定檔的適用範圍就是 hook 的適用範圍。

  • ~/.claude/settings.json:適用於您電腦上的所有專案,但不會套用到其他人的電腦。
  • .claude/settings.json:適用於單一專案,並提交至 repository,因此所有 clone 該專案的人都會取得此 hook。
  • .claude/settings.local.json:適用於單一專案,但僅在您的電腦上生效。
  • Managed policy settings:適用於整個組織,由管理員設定。
  • Plugin 內的 hooks/hooks.json:在該 plugin 啟用期間生效。
  • Skill 或 subagent 的 frontmatter。Skill 一旦被呼叫,其 hook 會在本次 session 的剩餘期間持續生效;subagent 的 hook 則會在該 subagent 執行期間生效。

這些檔案中的 hook 項目會彼此合併,而不是互相覆寫。專案設定檔會將其中的 hook 加入 user settings 中的 hook,而不是取代它們。因此,同一事件可以包含來自多個檔案的多個 hook。設定 "disableAllHooks": true 會停用這些 hook,但有一個例外:來自 managed policy settings 的 hook 仍會繼續執行,除非也在 managed settings 中套用該設定。

在 session 中執行 /hooks,即可依事件列出目前已註冊的所有 hook,並顯示每個 hook 的來源檔案與 matcher。此選單為唯讀,因此必須編輯設定檔來修改 hook。檔案監看程式通常會自動偵測變更,無須重新啟動。

Claude Code 有哪些 hook 事件

hooks 參考文件列出 33 個事件,範圍從 SessionStart 到 SessionEnd,涵蓋壓縮、子代理程式、worktree 與設定檔。伺服器管理通常只會用到其中幾個。

  • PreToolUse:工具呼叫執行前觸發,但 EndConversation 除外。這是唯一可以阻止執行的事件。
  • PostToolUse:工具呼叫成功後觸發,但 EndConversation 除外。工具呼叫失敗時則觸發 PostToolUseFailure。因此,必須掌握所有結果的 hook 需要同時處理這兩個事件。
  • PermissionRequest:工具呼叫需要權限判定時觸發,也就是即將顯示核准提示的時刻。
  • UserPromptSubmit:提交 prompt 時觸發,在 Claude 處理前執行。成功 hook 的純文字 stdout 會加入模型的內容。
  • SessionStart 與 SessionEnd:分別在工作階段開始與結束時觸發。壓縮完成後也會觸發 SessionStart,其 matcher 值為 compact。
  • Stop:Claude 完成回應時觸發。這是每個回合觸發一次,不是每個完成的工作觸發一次。

支援 matcher 的事件可在群組中設定 matcher,用來決定哪些事件會執行 hook。對工具事件而言,matcher 會依工具名稱篩選,因此 "Edit|Write" 只會在編輯檔案時觸發,其他情況不會觸發。Matcher 區分大小寫。空白 matcher 會在每次事件發生時觸發。來自 MCP(model context protocol)伺服器的工具名稱格式為 mcp__<server>__<tool>,因此使用 "mcp__github__.*" 作為 matcher,可只比對其中一台伺服器的工具,不會比對其他伺服器。

Stop hooks 有一個陷阱,撰寫前必須先了解。會阻止執行的 Stop hook 會讓模型返回繼續工作;根據預設,Claude Code 會在連續 8 次繼續後覆寫下一次阻止結果,而每當 Claude 呼叫工具時,計數就會重設。請讀取 hook 輸入中的 stop_hook_active 欄位,若其值為 true,便結束並傳回 0,否則 hook 可能會持續讓 Claude 返回工作狀態。

Hook 從 stdin 接收的內容

當 Claude 即將執行 npm test 時,Bash 上的 PreToolUse hook 會從 stdin 讀取以下內容:

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

常見的輸入欄位包含 session_id、cwd、transcript_path 與 hook_event_name;permission_mode 並非在每個事件中都會發送。工具事件會增加 tool_name、tool_input 與 tool_use_id。其他事件則攜帶各自的欄位:UserPromptSubmit 會取得 prompt 文字,而 SessionStart 會取得包含 startup、resume、clear、compact 或 fork 的 source。

jq 是在 shell script 中讀取此內容的常用方式,但最小化伺服器映像檔通常不包含此工具。請先在 Ubuntu 與 Debian 上使用 sudo apt install -y jq 進行安裝。

結束狀態碼對執行中工具呼叫的影響

共有三種結果。

  • Exit 0 代表成功,任何有效的 JSON 決策欄位依然適用,包含阻擋或拒絕。在 PreToolUse 上,若 Exit 0 且未包含決策,並不代表核准,系統仍會執行正常的權限流程。在 UserPromptSubmit、UserPromptExpansion、SessionStart 與 PostModelSwitch 上,純文字 stdout 會被加入模型的 context。在大多數其他事件中,stdout 僅會輸出至除錯日誌。
  • Exit 2 會在可阻擋的事件(包含 PreToolUse)上阻擋該動作,且 stderr 會成為阻擋訊息,除非 JSON 輸出包含阻擋決策(此時以 JSON 的理由為優先)。誰會讀取該訊息取決於事件類型。在 PreToolUse 與 Stop 上,模型會將其視為理由。在 UserPromptSubmit 與 PreModelSwitch 上,訊息會顯示給您看,且不會加入模型的 context。在無法阻擋的 PostToolUse 與 PostToolUseFailure 上,阻擋動作會被忽略,但 stderr 仍會作為回饋傳送給模型。在大多數其他無法阻擋的事件中,stderr 僅顯示給您或被忽略。在 Stop、SubagentStop、TaskCompleted 以及外掛程式的 UserPromptSubmit hook 上,若 Exit 2 且 stdout 為空,且 stderr 顯示檔案遺失錯誤,則視為非阻擋性錯誤。
  • 任何其他結束代碼若伴隨純文字或空的 stdout,通常視為非阻擋性錯誤。紀錄檔會顯示 hook 錯誤通知,並在 Failed with non-blocking status code: 文字後附上 stderr 的第一行。有效的 JSON 仍可在 PreToolUse 等事件上決定結果,除非該 hook 的失敗導致動作被阻擋。WorktreeCreate 在任何非零結束代碼下皆會失敗,而 WorktreeRemove 若在結束後目錄依然存在,則會在非零結束代碼下失敗。

若要執行阻擋或靜默以外的操作,請改用 Exit 0 並將 JSON 物件列印至 stdout。PreToolUse hook 可透過 permissionDecision 進行決策:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

在權限規則與工具核准要求允許的情況下,"allow" 會跳過互動式提示,"deny" 會取消呼叫並將理由傳送給模型,而 "ask" 則會要求確認。每個 hook 請選擇一種風格。若混用 Exit 2 與 stdout 上的 JSON 決策,即使 JSON 內容為 "allow",阻擋狀態仍會維持。

當多個 hook 符合同一個事件時,它們會並行執行,其中提示與代理 hook 最多同時執行 12 個。來自其中一個 hook 的 deny 不會停止其他並行的 hook,因此即使 guardrail hook 拒絕了該呼叫,logging hook 仍會寫入其日誌行。對於 PreToolUse,Claude Code 會合併所有答案並保留最嚴格的結果,優先順序為:拒絕 (deny)、延後 (defer)、詢問 (ask)、允許 (allow)。

範例 1:在執行前阻擋破壞性指令

將此內容儲存為專案中的 .claude/hooks/block-destructive.sh:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

使其具備執行權限,並在 .claude/settings.json 中將其註冊於 PreToolUse:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

在信任該腳本前請先手動測試,因為若 Hook 因自身輸入而崩潰,在 onFailure 未設定時通常會預設放行。在沒有 Git Bash 的 Windows 環境下,失敗的 shell 格式 PreToolUse 或 PermissionRequest 指令 Hook 可能會直接阻擋工具呼叫:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

您應會在 stderr 看到 Blocked by policy: 行,且結束代碼為 2。輸入如 ls -la 等無害指令,則應無任何輸出,且結束代碼為 0。在工作階段中,被拒絕的呼叫會連同您設定的拒絕原因顯示在紀錄中,模型會讀取該訊息並進行調整。

此做法的價值在於:PreToolUse Hook 會在權限模式檢查前觸發,且適用於所有權限模式,因此即使在 bypassPermissions 下,拒絕規則依然有效。這使得 Hook 在搭配 Claude Code 自動模式及其權限設定 使用時特別有用,即便提示詞被調低,Hook 仍會持續運作。

請務必認清此機制的本質。針對指令字串進行模式匹配僅能作為防止代理程式粗心大意的防護欄,並非防止代理程式惡意操作的邊界,因為同一指令可以透過您的 grep 無法識別的格式撰寫。嚴格的規則應實作於權限系統以及執行該處理程序的帳號層級中。

範例 2:每次編輯後進行格式化與檢查

PostToolUse 搭配 Edit|Write 比對器會在上述任一檔案編輯工具執行成功後觸發。請將此儲存為 .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

請 Claude 在 Python 檔案中加入一個縮排錯誤的函式,然後開啟該檔案。檔案會自動完成格式化。這代表 Hook 已成功執行,因為若 Hook 執行成功,對話中不會顯示任何訊息。

此處的 exit 2 不會撤銷任何變更。PostToolUse 是在工具執行完成後才觸發,因此編輯內容無論如何都已寫入磁碟。使用 exit 2 的目的是讓 ruff check 的輸出結果作為回饋傳送給模型,使其能修正剛才引入的錯誤,而非直接繼續執行。這就是提交時才發現 Lint 錯誤,與代理程式在同一回合內自動修復之間的差異。

此處有兩個比對器限制需要注意。Edit|Write 無法偵測由 Shell 指令所變更的檔案,而 Claude 經常透過 Bash 寫入檔案,這會導致偵測缺口。若要達到每次呼叫的覆蓋率,請同時比對 Bash,並讓指令碼透過 git status --porcelain 列出變更後的檔案。若要達到每回合一次的覆蓋率,請將掃描作業放入 Stop Hook 中。

範例 3:記錄每次工具呼叫以供稽核

PostToolUse 上的空白比對條件會在每次工具呼叫成功時觸發,但 EndConversation 除外。將記錄送至 system journal,而不是寫入家目錄中的檔案,並不會讓 agent 自己的 shell 無法存取這些記錄:能否存取取決於帳戶權限。使用者可以讀取自己的私人 per-user journal,而 root 以及 systemd-journal、adm 或 wheel 的成員可以讀取所有 journal 檔案:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

使用 journalctl -t claude-code -o cat | tail -n 5 讀取記錄。若具備讀取記錄的權限,應會看到每次成功工具呼叫各有一行 JSON;EndConversation 除外,且最新記錄位於最後一行。若沒有任何輸出,請同時檢查 journal 存取權限以及 hook 是否執行;下方的疑難排解章節會說明 hook 的相關問題。

在 PostToolUseFailure 下方加入相同區塊,以擷取失敗的呼叫,因為 PostToolUse 只會在成功時觸發,而失敗的命令通常才是需要關注的對象。使用 logger 而不是將內容附加到家目錄中的檔案,原因在於擁有權:hook 會以與 agent 的 shell 相同的使用者身分執行,因此該使用者能附加內容的任何檔案,也能將其截斷。journal 由 systemd-journald 寫入;但要防止記錄遭刪除,仍取決於 agent 帳戶的權限。

Hook 可執行的最長時間

圖表Default hook timeout in seconds, by hook type and event
此圖表背後的資料
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

命令 hook 預設可執行 600 秒,也就是 10 分鐘。部分事件會大幅縮短這段時間。SessionEnd hook 會共用 1.5 秒的總預算,因此工作階段結束時的清理作業必須快速完成。不過,在設定檔中為 hook 設定較長的 timeout,即可將共用預算提高到相同的時間上限,最多 60 秒。

同步命令、HTTP 或 MCP 工具 hook 如果達到逾時,系統會取消該 hook,通常不會產生任何決策;在 PreModelSwitch 上,逾時會阻止切換。對於 PreToolUse guardrail,逾時通常會讓工具呼叫繼續進入一般權限流程;但在 onFailure 未設定時,Windows 會套用上述例外。因此,guardrail 腳本應保持精簡。自 release 2.1.295 起,您可以在 command 或 http hook 上使用 "onFailure": "block" 反轉這項預設行為,將逾時、當機或非預期的結束代碼視為阻止;但這對 Stop、SubagentStop、TaskCompleted、TeammateIdle 或背景命令 hook 沒有作用。對於無人等待的緩慢工作,例如將日誌傳送到其他位置,請設定 "async": true,讓 hook 在背景執行,不會延遲工具呼叫。

Hooks、rules 檔案、skills 與 MCP servers

這 4 種機制都會改變 agent 的行為,因此經常彼此混淆。但只有其中 1 種不會停留在建議層級。

rules 檔案(CLAUDE.md,或 .claude/rules/ 下的檔案)是載入 model context 的文字。它會塑造行為,但不會強制執行。在長對話、大型 diff 與新的使用者請求中,rules 檔案的其中一行可能被忽略。這就是 agent 忽略你寫下的指示 的一般原因。

skill 是由指示與 script 組成的資料夾。model 判定某項 skill 相關時,才會載入它。這項判定正是 skill 的用途,也是它的限制:仍由 model 做決定。以 Ponytail,它會引導 agent 採用能運作的最小變更 為例,你可以看到 skill 的兩面。它能以 hook 無法做到的方式,塑造整項工作的處理方式,但只會在 model 選擇載入它時生效。

MCP(model context protocol)server 會提供 model 可呼叫的新工具。它能擴大 agent 可存取的範圍,但不會讓 agent 主動使用任何工具。此外,MCP server 是必須自行維運的獨立程序,這本身就是一項工作:請參閱 在 VPS 上執行 MCP servers。

Hook 是 4 種機制中唯一不需要 model 選擇就會執行的機制。偏好設定使用 rules 檔案;model 在適用時應遵循的程序使用 skill。每次都必須執行的步驟,或絕對不允許發生的事項,則使用 hook。更深入的比較,包括 skill 何時優於 rules 檔案,請參閱 skills、MCP 與 rules 檔案的比較。

Plugin 是封裝方式,不是第 5 種機制。它會將 hooks 與 skills 封裝成一個可安裝的單位。團隊可藉此將相同的防護措施部署到每台機器:請參閱 Claude Code plugins 的運作方式。

共用 VPS 上的安全性決策

hook 是由 agent 觸發的程式碼,並會以啟動 Claude Code 的使用者身分執行。它會繼承該使用者的檔案權限與環境。在 laptop 上,這是工作流程問題。在 agent 無人值守執行的 VPS 上,這是包含四個實務面向的安全性問題。

repository 中的 hook 可能是你未撰寫的程式碼。 .claude/settings.json 會提交至 repository,因此 clone repository 並在其中啟動 session,可能會註冊 repository 隨附的 hook。在互動式 session 中,Claude Code 會透過該資料夾的 workspace trust 對話方塊控管 project hook;這表示接受信任的時刻,就是你決定執行這些 hook 的時刻。請先閱讀 hooks 區塊。claude -p 或 SDK session 通常用於執行無人值守的 agent,不會顯示該對話方塊,並會將資料夾視為可信任,因此 repository 的 hook 會直接執行。以 script 操作該 repository 前,請先檢查其中的 .claude/ 檔案,或使用 --settings '{"disableAllHooks": true}' 執行。

hook 可以看見完整的工具輸入。 記錄 tool_input 的 audit hook 會將每個命令的所有引數寫入 log,包括命令列中恰好出現的任何 token。該 log 之後需要與 secret 相同的保護,這也是讓 secret 遠離 AI agent 可接觸範圍這項更廣泛問題的一部分。

hook 可以寫入模型的 context。 成功的 SessionStart 或 UserPromptSubmit hook 所輸出的純文字 stdout 會加入對話。若 hook 將外部來源、 issue tracker 或 log file 中的文字傳入,就等同於把不受信任的文字交給模型,效果如同你親自輸入一樣。將同一 VPS 上另一個 Claude Code session的訊息轉送過來,作用也相同;某個 agent 的輸出並不比 issue tracker 的內容更值得信任。請將這些 stdout 視為輸入,而不是輸出。

權限才是真正的控制手段。 請以專用的非特權使用者執行 agent,並只授予它需要的 sudo 規則。設定 PreToolUse deny 仍然有價值,而且這項機制本來就只提供 best effort:reference 對 if filter 也有相同說明,並要求需要硬性 deny 時使用 permission system。真正能在高壓情境下維持作用的是 permission rules,以及執行該程序的使用者帳號。

每種 permission mode 都具備一項相同的特性。PreToolUse hook 在每種 permission mode 中都會於 permission-mode check 前觸發,因此回傳 deny 的 hook 即使在 bypassPermissions 下也會阻擋工具。hook 可以收緊 permission rules 所允許的範圍,但不能放寬。例外是 mod。在沒有 managed settings 和 managed-mcp.json file 的機器上,如果 session 不是透過 /login 登入 Team 或 Enterprise plan,處理 tool.check 的已安裝 mod 可以核准原本被 PreToolUse hook 阻擋的呼叫。若存在 managed settings、managed-mcp.json file,或 session 使用 Team 或 Enterprise /login 作為 credential,則由 PreToolUse hook 阻擋的呼叫,預設仍會持續被阻擋,不受 hook 所在設定檔的影響。透過 API key 或長效 CLAUDE_CODE_OAUTH_TOKEN 執行的 session,也就是許多 server 的執行方式,會被視為未登入,即使系統已儲存 login 資訊。將 mod 安裝到 server 前,請先確認Claude Code mod 可以變更哪些內容。

為什麼我的 hook 沒有觸發?

請依序檢查下列步驟。每個步驟都對應到您實際會看到的徵狀。

  • 執行 /hooks 並確認該 hook 是否出現在您預期的事件之下。若選單中缺少 hook,通常代表設定檔有 JSON 語法錯誤(不允許結尾逗號與註解),或是檔案未放置在上述六個位置之一。
  • 將比對器(matcher)與工具名稱進行精確比對。比對器區分大小寫,因此 "bash" 無法匹配 Bash 工具。
  • 如同上述範例 1,手動執行該指令碼並輸入範例資料。若出現非預期的結束代碼,代表您的指令碼有誤;請同時檢查其 stdout,因為有效的 JSON 仍可能針對如 PreToolUse 等事件提供決策。
  • 若出現 jq: command not found 的通知,代表該機器缺少 jq。若您的指令碼出現 command not found,代表路徑無法解析,請使用 ${CLAUDE_PROJECT_DIR} 或絕對路徑。若指令碼完全沒有執行,通常是因為沒有執行權限。
  • Hook 印出了有效的 JSON 但沒有反應。在 macOS 與 Linux 上,shell 形式的 hook 會透過 sh -c 在非互動式 shell 中執行,但某些設定仍會載入您的 profile(例如 BASH_ENV 指向 ~/.bashrc)。若該 profile 印出橫幅訊息,該訊息會被附加在 JSON 之前。此時 stdout 不再以 { 開頭,導致 Claude Code 將整段內容視為純文字並忽略決策。由於 hook 正常結束(代碼 0),紀錄檔中不會顯示錯誤。對於大多數事件,該文字僅會進入除錯紀錄檔;但在 UserPromptSubmit、UserPromptExpansion、SessionStart 與 PostModelSwitch 事件中,該文字(包含橫幅)會被加入模型的上下文。請將 profile 中的任何 echo 進行封裝,確保其僅在互動式 shell 中執行。
  • 若仍無法解決:請使用 claude --debug-file /tmp/claude.log 啟動工作階段,並在第二個終端機執行 tail -f /tmp/claude.log。除錯紀錄檔會記錄哪些 hook 匹配成功、每個 hook 回傳的結束代碼,以及它們寫入 stdout 與 stderr 的所有內容。

FAQ

Claude Code 的 hook 與 CLAUDE.md 指令有何不同?

CLAUDE.md 指令是模型上下文中的文字,因此會與對話內容及當前請求競爭注意力,模型可能會權衡其重要性。Hook 則是 Claude Code 在生命週期固定點執行的 Shell 指令,無論模型如何判斷,只要事件發生就會執行。請將指令用於偏好設定,將 hook 用於必須執行或絕對禁止的步驟。

如何阻止 Claude Code 執行特定的 Shell 指令?

註冊一個 PreToolUse hook 並搭配 Bash 比對器,從 .tool_input.command 讀取指令,將原因寫入 stderr 並以狀態碼 2 退出。Claude Code 會取消該呼叫並向模型顯示您的理由;此過程發生在權限模式檢查之前,因此即使在 bypassPermissions 模式下,該拒絕規則依然有效。針對指令字串進行模式比對屬於防護措施而非安全邊界,因為相同的指令可以透過比對器無法識別的形式撰寫,因此請務必輔以權限規則並使用無特權帳號執行。

我的 hook 輸出了有效的 JSON 但沒有反應,為什麼?

請檢查您的 Shell 設定檔中是否有在 JSON 之前輸出的文字。在 macOS 與 Linux 上,若 hook 未設定 args 欄位,會透過 sh -c 執行;在仍會載入設定檔的環境中(例如 BASH_ENV 指向 ~/.bashrc),若設定檔會輸出橫幅訊息,該訊息會出現在 JSON 之前的 stdout 中。由於輸出不再以 { 開頭,Claude Code 會將其視為純文字並忽略該決策,且因為 hook 以狀態碼 0 退出,記錄檔中不會顯示錯誤。請在設定檔中加入互動式 Shell 測試來保護 echo,隨後透過讀取 claude --debug-file /tmp/claude.log 的除錯記錄檔來確認修正是否生效。

在共用伺服器上執行 Claude Code hooks 安全嗎?

Hook 會以啟動 Claude Code 的使用者身分執行,並繼承該使用者的檔案權限,因此 hook 可以執行該帳號具備的所有操作。以下兩個習慣可涵蓋大部分風險:以具備嚴格 sudo 政策的專用無特權帳號執行代理程式;在接受儲存庫的工作區信任對話框或執行 claude -p 之前,請先閱讀該儲存庫的 hooks 區塊,因為專案 hook 包含在 .claude/settings.json 中,且 -p 模式不會顯示該對話框。在設定檔中設定 "disableAllHooks": true 可停用 hook(受管理的 hook 除外,該設定需在管理層級要求);專案層級的 false 設定可以覆寫使用者層級的 true 設定。

這篇文章對您有幫助嗎?