学习精选 · AI 工具
Claude 与 Skill

Claude Code Hooks 入门:五种类型、关键事件和拦截机制一次讲清

Kriv AI2026-11-07约 5 分钟读完AI 整理查看原文

这篇基于 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 阅读原文后整理,未经人工逐字核对,内容以原文为准。

登录后可以点赞、查看和发表评论