结论先说
- Hooks 不只有本地 Shell 脚本:在
settings.json中,钩子处理器除了传统的"type": "command",还原生支持"type": "http"与"type": "prompt"(需要读仓库文件核实时还有多轮"type": "agent")。 - 语义把关选
Prompt Hooks:由快速模型对工具入参或结束状态做单轮判断,返回{"ok": true}放行、返回{"ok": false, "reason": "..."}则拦截并把原因喂回主模型重做。 - 集中审计选
HTTP Hooks:无需本地装脚本依赖,直接向指定 URL 发送 JSONPOST请求;请求头里的鉴权变量必须列入allowedEnvVars才会展开。 - 每次触发
prompt钩子都会产生一次轻量模型调用:务必配好matcher(如只盯Bash或Stop),不要无差别挂载到每次读文件事件上。 - 开通与配额升级入口:开启模型判定钩子会增加高频交互的额度消耗;国内用户可通过本站 Claude Code 订阅专页 或免密兑换的 Claude Pro iOS 卡密 开通,重度防御配置建议选 5 倍额度的 Claude Max 升级服务。

图:本站根据 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 钩子要注意两点:
- 必须配
allowedEnvVars:为了防止恶意仓库借请求头偷发你本机的环境变量,未列进allowedEnvVars数组的$变量名会按空串处理; - 用 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 Hooks 怎么用:通知、格式化与拦截示例
- Claude Code Hooks 实战:提交前自动跑测试
- Claude Code settings.json 配置文件详解
- Claude Code 权限模式详解:auto、plan 与规则配置
参考资料
- 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
0 条评论
还没有评论,来抢沙发~