使用 Hooks 自动化操作

原文：Automate actions with hooks

一句话

在 Claude Code 的特定生命周期节点自动执行 shell 命令，实现代码格式化、通知发送、命令验证和项目规则执行。

什么时候翻这页

• 需要在 Claude Code 编辑文件后自动执行某些操作
• 想要设置通知提醒，当 Claude 等待用户输入时获得提醒
• 需要阻止对敏感文件的修改
• 希望在上下文压缩后重新注入关键信息

核心概念

• Hooks（钩子）：用户定义的 shell 命令，在 Claude Code 生命周期的特定点执行
• 事件（Event）：触发 hooks 的特定时机，如文件编辑、任务完成、需要输入等
• 匹配器（Matcher）：过滤特定事件或工具类型的条件
• 命令钩子（Command hooks）：执行 shell 命令的 hooks
• 提示钩子（Prompt-based hooks）：使用 Claude 模型进行决策的 hooks
• 代理钩子（Agent-based hooks）：使用子代理检查文件或运行命令的 hooks
• HTTP 钩子（HTTP hooks）：将事件数据 POST 到 HTTP 端点的 hooks

怎么做

设置第一个 Hook

1. 在设置文件中添加 hooks 块
2. 创建一个通知钩子，当 Claude 需要输入时提醒你
3. 使用 /hooks 命令验证配置
4. 测试钩子是否正常工作

常见用例

1. 当 Claude 需要输入时获得通知

   • 使用 Notification 事件
   • 根据平台使用不同的通知命令

2. 在编辑后自动格式化代码

   • 使用 PostToolUse 事件和 Edit|Write 匹配器
   • 结合 jq 和 Prettier 实现自动格式化

3. 阻止对受保护文件的编辑

   • 创建保护脚本并设置可执行权限
   • 使用 PreToolUse 事件在执行前阻止编辑

4. 在压缩后重新注入上下文

   • 使用 SessionStart 事件和 compact 匹配器
   • 通过命令输出添加关键信息到上下文

5. 审核配置更改

   • 使用 ConfigChange 事件记录变更
   • 可以阻止未经授权的修改

6. 在目录或文件更改时重新加载环境

   • 结合 SessionStart 和 CwdChanged 事件
   • 使用 direnv 等工具管理环境变量

7. 自动批准特定权限提示

   • 使用 PermissionRequest 事件
   • 返回 JSON 决策 "behavior": "allow"

命令 / 配置速查

基本配置结构

{
  "hooks": {
    "事件名称": [
      {
        "matcher": "匹配条件",
        "hooks": [
          {
            "type": "command",
            "command": "要执行的命令"
          }
        ]
      }
    ]
  }
}

常用事件

匹配器示例

环境变量

• CLAUDE_PROJECT_DIR：项目目录路径
• CLAUDE_ENV_FILE：环境变量文件路径

初学者易错点

1. 钩子未触发：检查匹配器是否正确，事件类型是否匹配，以及钩子是否在正确的位置配置

2. JSON 解析错误：确保输出的是有效的 JSON，避免在 shell 配置中添加无条件 echo 语句

3. 脚本未执行：确保脚本有执行权限，使用 chmod +x 设置

4. 权限问题：某些平台需要额外配置通知权限（如 macOS 的 Script Editor）

5. 超时问题：不同类型的钩子有不同的超时限制，长时间运行的命令可能超时

相关词条

• skills 为 Claude 提供额外指令和可执行命令
• sub-agents 在隔离上下文中运行任务
• plugins 打包扩展以便在项目间共享
• permissions 管理工具使用权限
• memory 使用 CLAUDE.md 管理上下文