Skip to main content
Claude Code 钩子是用户定义的 shell 命令,在 Claude Code 生命周期的各个点执行。钩子提供对 Claude Code 行为的确定性控制,确保某些操作总是发生,而不是依赖 LLM 选择运行它们。
有关钩子的参考文档,请参阅 钩子参考
钩子的示例用例包括:
  • 通知:自定义当 Claude Code 等待您的输入或权限运行某些操作时如何获得通知。
  • 自动格式化:在每次文件编辑后对 .ts 文件运行 prettier,对 .go 文件运行 gofmt 等。
  • 日志记录:跟踪和计数所有执行的命令以进行合规性或调试。
  • 反馈:当 Claude Code 生成不遵循您的代码库约定的代码时提供自动反馈。
  • 自定义权限:阻止对生产文件或敏感目录的修改。
通过将这些规则编码为钩子而不是提示指令,您将建议转变为应用级代码,每次在预期运行时执行。
在添加钩子时,您必须考虑钩子的安全隐患,因为钩子在代理循环期间使用您当前环境的凭证自动运行。例如,恶意钩子代码可能会泄露您的数据。在注册钩子之前,始终审查您的钩子实现。有关完整的安全最佳实践,请参阅钩子参考文档中的 安全考虑

钩子事件概述

Claude Code 提供了在工作流的不同点运行的多个钩子事件:
  • PreToolUse:在工具调用之前运行(可以阻止它们)
  • PermissionRequest:在显示权限对话框时运行(可以允许或拒绝)
  • PostToolUse:在工具调用完成后运行
  • UserPromptSubmit:当用户提交提示时运行,在 Claude 处理之前
  • Notification:当 Claude Code 发送通知时运行
  • Stop:当 Claude Code 完成响应时运行
  • SubagentStop:当子代理任务完成时运行
  • PreCompact:在 Claude Code 即将运行压缩操作之前运行
  • SessionStart:当 Claude Code 启动新会话或恢复现有会话时运行
  • SessionEnd:当 Claude Code 会话结束时运行
每个事件接收不同的数据,并可以以不同的方式控制 Claude 的行为。

快速入门

在本快速入门中,您将添加一个钩子来记录 Claude Code 运行的 shell 命令。

前置条件

安装 jq 用于命令行中的 JSON 处理。

步骤 1:打开钩子配置

运行 /hooks 斜杠命令 并选择 PreToolUse 钩子事件。 PreToolUse 钩子在工具调用之前运行,可以阻止它们,同时向 Claude 提供关于如何不同处理的反馈。

步骤 2:添加匹配器

选择 + Add new matcher… 仅在 Bash 工具调用上运行您的钩子。 为匹配器输入 Bash
您可以使用 * 来匹配所有工具。

步骤 3:添加钩子

选择 + Add new hook… 并输入此命令:

步骤 4:保存您的配置

对于存储位置,选择 User settings,因为您正在记录到您的主目录。然后此钩子将应用于所有项目,而不仅仅是您的当前项目。 然后按 Esc 直到您返回 REPL。您的钩子现在已注册。

步骤 5:验证您的钩子

再次运行 /hooks 或检查 ~/.claude/settings.json 以查看您的配置:

步骤 6:测试您的钩子

要求 Claude 运行一个简单的命令,如 ls,并检查您的日志文件:
您应该看到类似的条目:

更多示例

有关完整的示例实现,请参阅我们公共代码库中的 bash 命令验证器示例

代码格式化钩子

在编辑后自动格式化 TypeScript 文件:

Markdown 格式化钩子

自动修复 markdown 文件中缺失的语言标签和格式化问题:
使用以下内容创建 .claude/hooks/markdown_formatter.py
使脚本可执行:
此钩子自动:
  • 检测未标记代码块中的编程语言
  • 为语法突出显示添加适当的语言标签
  • 修复过多的空行,同时保留代码内容
  • 仅处理 markdown 文件(.md.mdx

自定义通知钩子

当 Claude 需要输入时获得桌面通知:

文件保护钩子

阻止对敏感文件的编辑:

了解更多

  • 有关钩子的参考文档,请参阅 钩子参考
  • 有关全面的安全最佳实践和安全指南,请参阅钩子参考文档中的 安全考虑
  • 有关故障排除步骤和调试技术,请参阅钩子参考文档中的 调试
Last modified on February 12, 2026