Claude Code Hooks Mastery完全指南：13个生命周期钩子全解析

詹筱桃Drew

580人浏览 · 2026-02-06 00:17:28

詹筱桃Drew · 2026-02-06 00:17:28 发布

Claude Code Hooks Mastery完全指南：13个生命周期钩子全解析

【免费下载链接】claude-code-hooks-mastery 项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery

Claude Code Hooks Mastery是一套功能强大的生命周期钩子系统，能够帮助开发者在Claude Code会话的不同阶段实现自动化控制和自定义逻辑。通过这13个精心设计的生命周期钩子，你可以轻松实现从会话启动到结束的全流程管理，包括工具调用控制、权限管理、上下文注入等核心功能。

什么是Claude Code Hooks？

Claude Code Hooks是一套事件驱动的自动化工具，允许你在Claude Code会话的关键节点插入自定义逻辑。这些钩子就像"智能开关"，能够在特定事件发生时自动触发预定义的操作，从而实现对AI助手行为的精细控制。

无论是验证用户输入、控制工具调用，还是自动化后续处理，Claude Code Hooks都能帮你实现更智能、更安全、更高效的AI开发工作流。

Claude Code Hooks生命周期展示了从会话开始到结束的完整钩子触发流程

快速上手：钩子的基本结构

每个Claude Code钩子都遵循统一的配置结构，让你能够轻松定义何时触发以及如何响应特定事件：

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

EventName：指定要响应的生命周期事件
matcher：用于匹配特定工具或事件类型的模式（支持正则表达式）
type：钩子类型，可选择"command"（执行命令）或"prompt"（LLM评估）
command/prompt：钩子触发时执行的具体内容

你可以在多个配置文件中定义钩子，包括用户级别的~/.claude/settings.json和项目级别的.claude/settings.json，实现灵活的作用域管理。

13个核心生命周期钩子全解析

1. SessionStart：会话启动钩子

触发时机：当Claude Code启动新会话或恢复现有会话时

主要用途：

加载开发上下文（如项目问题、最近代码变更）
设置环境变量
执行初始化脚本

示例场景：自动加载项目的README内容作为上下文，或设置特定的环境变量：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat $CLAUDE_PROJECT_DIR/README.md"
          }
        ]
      }
    ]
  }
}

2. UserPromptSubmit：用户输入提交钩子

触发时机：用户提交提示后，Claude处理前

主要用途：

验证用户输入
添加额外上下文
过滤敏感信息
阻止不当请求

示例场景：检查用户输入中是否包含敏感信息，并自动添加当前时间作为上下文：

#!/usr/bin/env python3
import json
import sys
import re
import datetime

input_data = json.load(sys.stdin)
prompt = input_data.get("prompt", "")

# 检查敏感模式
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "包含潜在敏感信息")
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        output = {
            "decision": "block",
            "reason": f"安全策略违规：{message}。请删除敏感信息后重试。"
        }
        print(json.dumps(output))
        sys.exit(0)

# 添加当前时间到上下文
context = f"当前时间：{datetime.datetime.now()}"
print(context)
sys.exit(0)

3. PreToolUse：工具使用前钩子

触发时机：Claude创建工具参数后，执行工具调用前

主要用途：

验证工具参数
修改工具输入
自动批准或拒绝工具调用
添加额外上下文

常用匹配器：

Bash - Shell命令
Read/Write/Edit - 文件操作
WebFetch/WebSearch - 网络操作
Task - 子代理任务

示例场景：自动批准读取文档文件，阻止危险的Bash命令：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python3 $CLAUDE_PROJECT_DIR/scripts/auto-approve-docs.py"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 $CLAUDE_PROJECT_DIR/scripts/block-dangerous-commands.py"
          }
        ]
      }
    ]
  }
}

4. PermissionRequest：权限请求钩子

触发时机：当系统显示权限请求对话框时

主要用途：

自动批准或拒绝权限请求
修改工具输入参数
记录权限请求

示例场景：自动批准特定目录的文件写入请求：

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 $CLAUDE_PROJECT_DIR/scripts/approve-write-requests.py"
          }
        ]
      }
    ]
  }
}

5. PostToolUse：工具使用后钩子

触发时机：工具成功执行后

主要用途：

处理工具输出
验证结果
触发后续操作
记录工具使用情况

示例场景：代码格式化工具执行后自动运行代码检查：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

6. PostToolUseFailure：工具使用失败钩子

触发时机：工具执行失败后

主要用途：

处理错误情况
提供修复建议
记录失败信息
自动重试

7. SubagentStart：子代理启动钩子

触发时机：当生成子代理时

主要用途：

初始化子代理上下文
设置子代理权限
记录子代理创建

Claude Code子代理工作流展示了主代理与子代理之间的协作关系

8. SubagentStop：子代理停止钩子

触发时机：当子代理完成任务后

主要用途：

评估子代理成果
整合子代理输出
决定是否继续或终止子代理

示例场景：使用prompt-based hook智能评估子代理是否完成任务：

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "评估子代理是否应停止。输入：$ARGUMENTS\n\n检查：\n- 子代理是否完成了分配的任务\n- 是否发生需要修复的错误\n- 是否需要收集更多上下文\n\n返回：{\"ok\": true}允许停止，或{\"ok\": false, \"reason\": \"解释\"}继续。"
          }
        ]
      }
    ]
  }
}

9. Stop：主代理停止钩子

触发时机：主代理完成响应后

主要用途：

评估任务完成情况
决定是否需要继续工作
执行最终清理操作

示例场景：智能判断是否所有任务都已完成：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "评估Claude是否应停止工作。上下文：$ARGUMENTS\n\n分析对话并确定：\n1. 所有用户请求的任务是否已完成\n2. 是否有需要解决的错误\n3. 是否需要后续工作\n\n返回JSON：{\"ok\": true}允许停止，或{\"ok\": false, \"reason\": \"你的解释\"}继续工作。"
          }
        ]
      }
    ]
  }
}

10. PreCompact：上下文压缩前钩子

触发时机：Claude准备压缩上下文前

主要用途：

保存重要上下文
自定义压缩策略
清理敏感信息

匹配器：

manual - 用户调用/compact命令
auto - 系统自动触发压缩

11. Setup：设置钩子

触发时机：当使用--init、--init-only或--maintenance标志启动Claude时

主要用途：

安装依赖
运行数据库迁移
执行定期维护任务

示例场景：项目初始化时自动安装依赖：

{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": "npm install"
          }
        ]
      }
    ]
  }
}

12. Notification：通知钩子

触发时机：当Claude Code发送通知时

主要用途：

自定义通知处理
发送到外部系统
记录重要事件

常用匹配器：

permission_prompt - 权限请求通知
idle_prompt - 闲置提示
auth_success - 认证成功通知

示例场景：不同类型通知触发不同操作：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

13. SessionEnd：会话结束钩子

触发时机：当Claude Code会话结束时

主要用途：

清理临时文件
保存会话状态
生成会话报告
执行最终备份

结束原因：

clear - 用户执行/clear命令
logout - 用户登出
prompt_input_exit - 用户在输入提示时退出
other - 其他退出原因

钩子输出控制：两种决策方式

Claude Code Hooks提供两种输出控制方式，让你能够灵活地影响Claude的行为：

1. 退出代码控制（简单方式）

退出代码0：成功执行，stdout会被添加到上下文（对UserPromptSubmit和SessionStart）
退出代码2：阻塞操作，stderr会作为错误消息反馈给Claude
其他非零代码：非阻塞错误，仅在详细模式下显示stderr

2. JSON输出控制（高级方式）

通过JSON格式输出可以实现更精细的控制：

{
  "decision": "block",
  "reason": "必须提供的阻止原因",
  "hookSpecificOutput": {
    "additionalContext": "提供给Claude的额外上下文"
  }
}

不同钩子类型支持不同的JSON字段，允许你批准/拒绝操作、修改输入参数、添加上下文等高级功能。

安全最佳实践

使用Claude Code Hooks时，请遵循以下安全原则：

验证和清理输入 - 不要盲目信任输入数据
始终引用shell变量 - 使用"$VAR"而非$VAR
阻止路径遍历 - 检查文件路径中的".."模式
使用绝对路径 - 为脚本指定完整路径
跳过敏感文件 - 避免处理.env、.git/、密钥等敏感文件

安全的钩子配置可防止未授权访问和数据泄露

钩子调试技巧

如果你的钩子不按预期工作，可以尝试以下调试方法：

检查配置 - 运行/hooks命令查看已注册的钩子
验证语法 - 确保JSON配置有效
手动测试命令 - 先在终端中测试钩子命令
检查权限 - 确保脚本具有可执行权限
启用调试模式 - 使用claude --debug查看详细执行日志

调试输出示例：

[DEBUG] 为PostToolUse:Write执行钩子
[DEBUG] 获取PostToolUse的匹配钩子命令，查询：Write
[DEBUG] 在设置中找到1个钩子匹配器
[DEBUG] 为查询"Write"匹配到1个钩子
[DEBUG] 找到1个要执行的钩子命令
[DEBUG] 执行钩子命令：<你的命令>，超时60000ms
[DEBUG] 钩子命令完成，状态0：<你的输出>

总结

Claude Code Hooks Mastery提供了13个强大的生命周期钩子，让你能够全面控制AI助手的行为。从会话启动到结束，从工具调用到权限管理，这些钩子为你提供了无限可能。

通过本文介绍的钩子功能和最佳实践，你可以构建更智能、更安全、更高效的AI开发工作流。无论是个人项目还是企业级应用，Claude Code Hooks都能帮助你实现自动化控制，释放AI助手的全部潜力。

要开始使用Claude Code Hooks，只需克隆仓库并按照官方文档配置你的第一个钩子：

git clone https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery

探索钩子的无限可能，提升你的AI开发体验！

Claude Code Hooks工作流程展示了钩子如何在不同阶段协同工作

【免费下载链接】claude-code-hooks-mastery 项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery

CSDN-OPC开发者社区

这里是“一人公司”的成长家园。我们提供从产品曝光、技术变现到法律财税的全栈内容，并连接云服务、办公空间等稀缺资源，助你专注创造，无忧运营。

更多推荐

【AI工具】OfficeCLI 火了：让 AI 智能体接管你的 Word、Excel和PPT

OfficeCLI是全球首个专为AI智能体设计的开源Office套件，解决了AI无法"看见"文档的问题。它提供单二进制文件，无需安装Microsoft Office即可读写Word、Excel、PPT文档，并内置HTML渲染引擎实现实时预览。核心功能包括：一键创建/编辑文档、实时可视化反馈、AI友好接口（支持Claude Code等主流AI工具）、自然语言操作界面。安装简单，支持多平台，通过命令行

CSDN-OPC开发者社区

深演智能黄晓南出席 The MarTech Summit Hong Kong：布局全球化，把中国的企业AI实践带向世界

对这些企业来说，割裂的系统意味着割裂的客户理解——它们真正需要的，是一套既在中国 “work”、又在亚太“work”的 AI 能力和解决方案。作为港股企业决策 AI 智能体第一股，深演智能正在把 “AI for Growth” 从中国实践变成全球命题：以企业级 AI Agent 服务各行各业，让在中国被验证过的智能能力，成为全球企业增长的新基础设施。——AI 的价值不只是节省成本、提升效率，而是帮