Claude 与 Skill
Claude Code Hooks 入门:五种类型、关键事件和拦截机制一次讲清
这篇基于 Anthropic 官方文档整理的指南,系统梳理了 Claude Code hooks 的定义、五种类型、常用事件和配置位置,并讲清了退出码 2 拦截动作的机制。还覆盖了企业通过 managed settings 控制哪些 hooks 能跑的做法,以及 hooks 与权限系统的边界。
今天就能做
- 先在项目 .claude/settings.json 里加一个带 matcher 的 PreToolUse hook(如匹配 Edit|Write),用退出码 2 拦截危险操作,跑 /hooks 确认配置生效
- 记住边界:PostToolUse 不能撤销操作,硬性 allow/deny 交给权限系统而不是 hook
- 生产或共享环境部署 hooks 前,逐条审查命令内容——它们以你的完整权限运行
Hooks 是什么:确定性的自动控制
- Hooks 是用户定义的 shell 命令等处理器,在会话生命周期的固定节点自动执行,比如工具调用前或 Claude 回答结束后
- 核心价值是确定性控制:某些动作一定会发生,而不是指望模型自己选择去做
- 常见用途包括格式化代码、发通知、校验命令和强制执行项目规则
- 共五种类型:command、http、mcp_tool、prompt、agent,其中 prompt 和 agent 用模型判断条件,agent 类型标记为实验性
常用事件和配置位置
- 最常用的六个事件:SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd,其他事件覆盖子代理、权限请求、上下文压缩等场景
- 配置写在 settings 文件的 hooks 块里,每条包含事件名、可选 matcher 和处理器;不加 matcher 则每次事件都触发,官方示例常用 Edit|Write 这类工具名收窄范围
- 作用域由文件位置决定:~/.claude/settings.json 全局生效、.claude/settings.json 可提交进仓库给全团队用、settings.local.json 仅本地
- 插件、skills 和 subagents 也能携带 hooks;在 Claude Code 里运行 /hooks 可查看当前配置
- 部分事件和选项有最低版本要求,使用前需对照文档确认
拦截机制:退出码 2 是关键
- Hook 以退出码 2 结束并向 stderr 写原因即可拦截:PreToolUse 拦下工具调用,UserPromptSubmit 拒绝提示词
- PreToolUse 的退出码 0 不等于批准,调用仍走正常权限流程;PostToolUse 无法撤销已执行的操作
- 大多数事件上其他退出码只是非阻断错误,动作照常执行,除非设置 onFailure 为 block(需 v2.1.295+)
- 官方明确建议:硬性的允许或拒绝应交给权限系统,而不是用 hook 实现;if 过滤器按工具参数收窄只是 best-effort
企业管控与安全提醒
- 管理员可在 managed settings 里设置 allowManagedHooksOnly,屏蔽用户、项目、本地和插件层的 hooks
- disableAllHooks 无法从外部关掉 managed settings 强制的 hooks
- Hook 运行的是你自己的命令,且以你的完整用户权限执行,能改、删、访问你账号能碰的任何文件,每个 hook 都要当作代码来审查和测试
使用前注意
- Anthropic 文档页面没有标注最后更新日期,事件名、选项和版本要求可能变化,动手前应核对当前官方文档
- 作者未实际运行过 hooks,文中内容均来自文档阅读而非实测
- Hooks 和 permissions 是两套机制:hooks 在事件点跑你的处理器,permissions 是独立的权限规则,不要混用
团队落地建议
- 想让全团队共享 hooks,放进项目里的 .claude/settings.json 并提交到仓库
- 组织级管控用 managed policy settings
- 团队应书面约定:哪些检查放 hooks、哪些放权限系统、各自由谁负责维护
原文:Claude Code Hooks: Events, Setup and Controls | Kriv AI
来源:Kriv AI · 2026-11-07
查看原文本文由 AI 阅读原文后整理,未经人工逐字核对,内容以原文为准。
登录后可以点赞、查看和发表评论