Claude Code Hooks 進階之 HTTP Hooks 與 Prompt Hooks:除 Shell 腳本外怎麼用模型判斷攔截不安全操作

除了本地 command 腳本鉤子,Claude Code 還支持發送 POST 請求的 HTTP Hooks(type: http)與單輪大模型語義判定的 Prompt Hooks(type: prompt)。本文講清三類鉤子選型、settings.json 配置與攔截規則。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 Pro 帳號

結論先說

  1. Hooks 不只有本地 Shell 腳本:在 settings.json 中,鉤子處理器除了傳統的 "type": "command",還原生支持 "type": "http" 與 "type": "prompt"(需要讀倉庫文件核實時還有多輪 "type": "agent")。
  2. 語義把關選 Prompt Hooks:由快速模型對工具入參或結束狀態做單輪判斷,返回 {"ok": true} 放行、返回 {"ok": false, "reason": "..."} 則攔截並把原因喂回主模型重做。
  3. 集中審計選 HTTP Hooks:無需本地裝腳本依賴,直接向指定 URL 發送 JSON POST 請求;請求頭裏的鑑權變量必須列入 allowedEnvVars 才會展開。
  4. 每次觸發 prompt 鉤子都會產生一次輕量模型調用:務必配好 matcher(如只盯 Bash 或 Stop),不要無差別掛載到每次讀文件事件上。
  5. 開通與配額升級入口:開啟模型判定鉤子會增加高頻交互的額度消耗;國內用戶可通過本站 Claude Code 訂閱專頁 或免密兌換的 Claude Pro iOS 卡密 開通,重度防禦配置建議選 5 倍額度的 Claude Max 升級服務。

三類 Claude Code Hooks 機制對比

圖:本站根據 Claude Code 官方文檔:Automate workflows with hooks 整理的示意圖

本文根據 Claude Code 官方文檔《Automate workflows with hooks》與《Claude Code settings》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。

適用於誰

  • 寫過本地 Shell 鉤子,但發現正則很難兜住花式變形的高危命令或半途而廢的敷衍收尾,想引入語義判斷的人;
  • 團隊跨 Windows 與 macOS 辦公,不想在每個人電腦裝一套 Python 與 jq 腳本,希望統一連內網審計網關的負責人;
  • 想理清 command、http、prompt 三類鉤子配置字段與成本邊界的開發者。

一、command、http 與 prompt 三種鉤子怎麼選

如果你還沒配過基礎 Shell 鉤子,可先看 Claude Code Hooks 基礎入門示例。當規則變複雜後,三種類型的優劣分工非常清晰:

鉤子類型執行方式延遲與額度消耗最適合攔截或處理的場景
command本機跑 Shell 腳本看退出碼毫秒級,零模型消耗固定格式化、提交前跑測試(退出碼 2 攔截)
http向遠程或本地服務發 HTTP POST取決於接口延遲,零模型消耗團隊統一安全網關審批、集中寫審計日誌
prompt調用輕量模型做單輪語義判斷秒級,每次觸發耗少量配額識別變形危險命令、在 Stop 檢查是否真做完任務

確定性規則(比如提交前必須跑過單測)永遠優先用零成本的 command,具體寫法見 PreToolUse 提交前自動跑測試實戰;只有正則寫不出來的模糊語義邊界,才交給 prompt。

二、Prompt Hooks 配置實戰:攔截變相刪庫與敷衍收尾

type: "prompt" 會把當前事件上下文傳給判定模型,模型只需按官方內置約定返回 ok 布爾值與攔截理由。下面是在 .claude/settings.json 中同時防範高危 Shell 命令與提前收工的配置模板:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "審查即將執行的命令參數:$ARGUMENTS。若涉及刪除生產目錄、導出環境變量密鑰或強推主分支則判定不安全並說明原因,常規開發測試命令放行。",
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "檢查 Claude 是否已完成用戶要求的全部修改並運行了驗證命令,若只給口頭建議未落地驗證則返回不通過。"
          }
        ]
      }
    ]
  }
}

當 Stop 事件裏的 prompt 鉤子判定未完成時,主會話不會停下,而是收到 reason 提示自動補齊遺漏步驟。關於配置文件的作用域層級見 Claude Code settings.json 詳解。

Prompt Hooks 額外模型消耗提示:掛載在 PreToolUse 上的 prompt 鉤子會在每次匹配工具執行前發起一次模型判定請求,長鏈路任務下累計消耗明顯高於純腳本模式。日常開啟語義守衛的開發者,建議通過 Claude Pro 會員自助充值 保持訂閱,或直接升級 Claude Max 會員服務 留足安全餘量。

三、HTTP Hooks 配置實戰:統一網關鑑權與返回格式

跨平台團隊如果把 .claude/settings.json 提交進 Git,Windows 成員跑 .sh 腳本常報錯。改用 type: "http" 把事件發往團隊內網服務即可跨系統統一:

鉤子選型與攔截流轉判斷

圖:本站根據 Claude Code 官方文檔:Automate workflows with hooks 整理的示意圖

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "http",
            "url": "https://audit.internal.example.com/claude-hook",
            "headers": {
              "Authorization": "Bearer $AUDIT_HOOK_TOKEN"
            },
            "allowedEnvVars": ["AUDIT_HOOK_TOKEN"],
            "timeout": 15
          }
        ]
      }
    ]
  }
}

配置 HTTP 鉤子要注意兩點:

  1. 必須配 allowedEnvVars:為了防止惡意倉庫借請求頭偷發你本機的環境變量,未列進 allowedEnvVars 數組的 $變量名 會按空串處理;
  2. 用 JSON 正文而不是 HTTP 500 表達攔截:服務端要拒絕本次工具執行時,應正常返回 200 OK 並在響應 JSON 裏帶上 permissionDecision: "deny"(或頂層 "decision": "block" 與 "reason"),日常靜態權限白名單則可配合 Claude Code 權限模式配置。

常見問題

問:type: "prompt" 鉤子裏模型能自己去讀項目裏的其他文件嗎?

答:不能。prompt 鉤子是無工具的單輪快速判定,只能看到傳入的事件 JSON;如果必須先去翻源碼核實才能下結論,官方文檔提供了支持多輪讀文件的 "type": "agent" 鉤子。

問:HTTP 鉤子接口超時或掛掉會把開發者的終端卡死嗎?

答:按官方說明,網絡超時或非 2xx 狀態碼預設按非阻斷警告處理並允許繼續工作,但建議設短 timeout(如 10 至 15 秒)減少等待。

問:拉取別人的開源倉庫,裏面的惡意 HTTP 鉤子會自動執行嗎?

答:Claude Code 對項目級配置文件中的鉤子有信任確認與安全審查機制,首次打開陌生倉庫切勿盲目點信任,也可在交互中輸 /hooks 檢查當前生效列表。

問:國內團隊沒有外幣信用卡,怎麼開通訂閱並開報銷發票?

答:可通過本站 Claude Code 訂閱專頁 或 AI 會員充值總覽 辦理,支持支付寶、微信支付與 AlipayHK,提供免交密碼的卡密自助兌換,企業採購可開具國內增值稅發票。實時價格與售後細則以頁面為準:訂閱期內非違規掉訂閱按剩餘天數折退,風控封號不在質保範圍。

相關教學

參考資料

  • Claude Code 官方文檔:Automate workflows with hooks — https://code.claude.com/docs/en/hooks
  • Claude Code 官方文檔:Claude Code settings — https://code.claude.com/docs/en/settings

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    Anthropic Contextual Retrieval(上下文增強檢索)是什麼、怎麼實現:給文檔塊自動補背景摘要結合緩存降失誤率

    長文檔切成小塊後丟了公司名、年份和主語指代導致 RAG 頻頻搜錯?本文按 Anthropic 官方技術文章詳解 Contextual Retrieval 原理、官方公開評測失誤率下降 49% 至 67% 的組合架構,以及用 Claude 提示詞緩存低成本批量生成切片背景的完整 Python 代碼。

    Claude其他 AI 工具0
  2. 02

    RAG 知識庫回答不準怎麼調優:切片大小(Chunking)、BM25 + 向量混合檢索與 Rerank 重排序三步排查法

    搭好的 RAG 企業知識庫一問具體型號、報錯碼或跨行表格就答非所問?本文按 OpenAI 與 Anthropic 官方檢索文檔,給出先隔離檢索與生成故障、再按結構化切片(Chunking)、BM25 加向量混合召回(RRF)與 Rerank 重排序逐層調優的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 開源本地部署(Docker Compose)與提示詞版本管理(Prompt Management)從零上手教學

    企業內網嚴禁業務日誌出境,又想免費擁有大模型調用鏈追蹤與不發版熱更新提示詞的能力?本文按 Langfuse 官方文檔整理 Docker Compose 本地一鍵啟動(含 ClickHouse 架構注意事項)、密鑰配置與 Prompt Management 標籤化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入門教學:給 LangGraph 與原生 OpenAI / Claude 接口加調用鏈追蹤、Token 成本統計與免費層限額

    智能體多步調用總是找不到哪一輪提示詞跑偏、單次請求到底燒了多少 Token?本文按 LangSmith 官方文檔講清環境變量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 與 @traceable 追蹤原生接口,以及 Developer 免費層額度與留存規則。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效讀英文文獻:PDF 翻譯插件、批註導出精讀與防捏造參考文獻流程

    在 Zotero 裏讀英文頂會論文怎麼無縫聯動 Claude 與 ChatGPT?本文整理 Translate for Zotero 劃詞翻譯配置、高亮批註導出精讀提示詞,以及杜絕 AI 捏造假 DOI 參考文獻的核驗閉環。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 與本地 Ollama 做個人雙鏈筆記問答:主流插件配置與私隱脫敏邊界

    想在 Obsidian 裏基於自己的雙鏈筆記庫做 AI 問答又擔心私隱外泄?本文對比 Copilot 與 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 與本地 Ollama 的步驟及敏感目錄隔離規則。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~