什么是 Hooks

Hooks 是 Claude Code 的事件钩子机制，允许在特定事件发生时自动执行 shell 命令。Hooks 在 settings.json 中配置，可以用于自动化工作流、添加校验、发送通知等。

事件类型

事件	触发时机
PreToolUse	工具调用之前
PostToolUse	工具调用之后
Notification	Claude 发送通知时
Stop	Claude 完成回复时
SubagentStop	子 Agent 完成时
UserPromptSubmit	用户提交消息时

配置格式

在 settings.json 中添加 hooks 字段：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to run a bash command'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Claude 完成了'"
          }
        ]
      }
    ]
  }
}

Hook 配置字段

字段	说明
matcher	匹配工具名称，空字符串表示匹配所有
hooks	钩子数组
hooks[].type	钩子类型，目前仅支持 command
hooks[].command	要执行的 shell 命令

环境变量

Hook 命令执行时，可以使用以下环境变量：

变量	说明
$CLAUDE_TOOL_NAME	当前工具名
$CLAUDE_FILE_PATH	操作的文件路径（文件相关工具）
$CLAUDE_TOOL_INPUT	工具输入的 JSON

实用示例

自动格式化

写入文件后自动运行 Prettier：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

禁止修改特定文件

防止 Claude 修改锁文件：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo $CLAUDE_FILE_PATH | grep -q 'lock\\|Lock' && echo 'BLOCKED: 不要修改锁文件' && exit 1 || true"
          }
        ]
      }
    ]
  }
}

完成通知（macOS）

Claude 完成任务后发送系统通知：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 任务完成\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

注意事项

• Hook 命令的输出会反馈给 Claude，Claude 会将其视为来自用户的信息
• 如果 Hook 返回非零退出码，操作会被阻止（对于 PreToolUse）
• Hook 命令应保持轻量，避免长时间运行的操作
• 调试时可以在命令中加入 echo 来查看变量值