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 条评论

登录 后参与评论

还没有评论,来抢沙发~