ClaudeCode的Hooks学习
1. Hooks 是什么
Hooks是用户自定义的 shell 命令、HTTP 接口或 LLM 提示符，它们会在 Claude Code 生命周期的特定节点自动执行。它们能够对 Claude Code 的行为进行确定性控制，确保某些操作始终发生，而无需依赖生命周期管理 (LLM) 来决定是否执行。
LLM提示词交互会有不确定性，hooks可以保证在特定事件发生时候自动执行预设的命令
我们可以将开发过程中规定化、固定化的流程使用hooks来配置，确保流程的确定性自动化执行。
拦截危险操作：如果模型正在修改危险的核心代码、文件等，hooks钩子去拦截
自动测试：hooks在代码改完提交前，进行自动化测试。
代码审查：代码提交前进行代码审查
2. Hooks 原理
2.1 hooks生命周期
| Hook 名称 | 触发时机 | 核心作用 |
|---|---|---|
PreToolUse |
工具执行前 | 工具调用前的参数校验、权限控制与日志审计 |
PostToolUse |
工具执行成功后 | 工具结果的后处理、状态同步与日志记录 |
PostToolUseFailure |
工具执行失败后 | 错误捕获、自动重试与异常告警 |
Notification |
发送通知时 | 消息转发、自定义通知渠道集成 |
UserPromptSubmit |
用户提交指令时 | 输入校验、指令预处理与审计记录 |
SessionStart |
新会话启动时 | 会话级初始化、环境准备与状态重置 |
Stop |
Claude 结束响应前 | 会话结果校验、收尾工作与状态保存 |
StopFailure |
会话因 API 错误结束时 | 错误场景下的资源清理与异常上报 |
SubagentStart |
子代理（Agent 工具调用）启动时 | 子任务初始化、环境隔离与上下文准备 |
SubagentStop |
子代理结束响应前 | 子任务结果汇总、资源回收与状态同步 |
PreCompact |
会话压缩前 | 压缩前数据预处理、关键信息备份 |
PostCompact |
会话压缩后 | 压缩后数据恢复、状态校验与上下文补全 |
SessionEnd |
会话结束时 | 会话资源清理、最终状态保存与日志归档 |
PermissionRequest |
权限请求弹窗出现时 | 权限申请流程控制、用户授权审计 |
Setup |
仓库初始化 / 维护时 | 项目环境初始化、依赖安装与配置校验 |
TeammateIdle |
协作代理即将进入空闲状态时 | 空闲资源释放、状态同步与任务交接 |
TaskCompleted |
任务被标记为完成时 | 任务结果校验、进度同步与后续流程触发 |
Elicitation |
MCP 服务请求用户输入时 | 用户输入请求拦截、提示增强与输入校验 |
ElicitationResult |
用户响应 MCP 输入请求后 | 输入结果处理、校验与后续流程触发 |
ConfigChange |
会话期间配置文件变更时 | 配置变更感知、动态加载与配置校验 |
WorktreeCreate |
为 MCP 代理创建隔离工作区时 | 工作区初始化、环境隔离与依赖配置 |
WorktreeRemove |
移除之前创建的工作区时 | 工作区清理、资源回收与状态重置 |
2.2 hooks通用模板
{
"hooks": {
"【生命周期名称】": [
{
"matcher": "【工具名或 *】",
"description": "【可选，钩子描述】",
"enabled": true,
"hooks": [
{
"type": "【command / http / prompt / agent】",
"name": "【可选，钩子名称】",
"description": "【可选，钩子功能描述】",
"if": "【可选，触发条件】",
// --- 下面字段根据 type 类型选择其一配置 ---
// type: "command" 时配置
"command": "【要执行的命令/脚本路径】",
"timeout": 30000,
"silent": false,
"continueOnError": false,
// type: "http" 时配置
"url": "【接口地址】",
"method": "POST",
"headers": { "Content-Type": "application/json" },
"body": "【请求体】",
// type: "prompt" 时配置
"prompt": "【要注入/修改的提示词】",
// type: "agent" 时配置
"agent": "【子代理配置】"
}
]
}
]
}
}
生命周期维度字段
| 字段 | 是否必需 | 说明 |
|---|---|---|
matcher |
是 | 工具匹配器，指定钩子生效的工具类型，如 Bash / Write / * |
hooks |
是 | 钩子规则数组，每个元素为一个具体钩子配置对象 |
description |
否 | 该组钩子的描述信息 |
enabled |
否 | 是否启用该组钩子，默认 true |
钩子规则公共字段（hooks [].*）
| 字段 | 是否必需 | 说明 |
|---|---|---|
type |
是 | 钩子类型，决定后续配置字段，可选值：command / http / prompt / agent |
if |
否 | 触发条件，满足条件时才执行钩子，如 Bash(rm *) |
name |
否 | 钩子名称 |
description |
否 | 钩子功能描述 |
continueOnError |
否 | 钩子执行失败时，是否继续 Claude 流程，默认 false |
type: "command"（命令执行钩子）
| 字段 | 是否必需 | 说明 |
|---|---|---|
command |
是 | 要执行的命令或脚本路径 |
timeout |
否 | 命令执行超时时间（毫秒），默认 30000 |
silent |
否 | 是否静默执行，不输出日志 |
| async | 否 | 钩子的异步执行，不会阻塞claudecode任务 |
type: "http"（HTTP 请求钩子）
| 字段 | 是否必需 | 说明 |
|---|---|---|
url |
是 | 请求地址 |
method |
否 | 请求方法，默认 POST |
headers |
否 | 请求头对象 |
body |
否 | 请求体内容，支持模板变量 |
type: "prompt"（提示词钩子）
| 字段 | 是否必需 | 说明 |
|---|---|---|
prompt |
是 | 要注入 / 修改的提示词内容 |
type: "agent"（子代理钩子）
| 字段 | 是否必需 | 说明 |
|---|---|---|
agent |
是 | 子代理配置对象（包含指令、权限等） |
2.3 hooks作用域
| 配置来源 | 作用范围 | 说明 |
|---|---|---|
~/.claude/settings.json |
用户全局 | 对当前用户的所有项目生效 |
.claude/settings.json |
项目级别 | 仅对当前项目生效 |
.claude/settings.local.json |
项目本地 | 仅本地生效，不提交到 Git |
3. Hooks 配置使用
3.1 配置hooks
手动添加hooks操作步骤
- 打开
~/.claude/settings.json并添加某个生命周期钩子。- 如果hooks还没有对应的生命周期则新建。
- 如果某个生命周期内已经有对应的hooks,则数组形式追加而非覆盖
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display SessionStart \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
钩子含义：当 每次打开 / 新建 Claude Code 会话（
SessionStart生命周期触发）时，在你的 Mac 电脑右上角弹出一条系统通知提醒
交互形式添加：通过在命令行界面 (CLI) 中描述你想要的功能，让 Claude 为你编写钩子。
### 3.2 验证配置
输入命令
/hooks打开hooks列表，可以看到事件的对应的hooks数量
点击
具体的生命周期(SessionStart)确认钩子存在,以及对应详情
重启Claude Code
3.3 测试hooks
笔者配置的是SessionStart 事件，新建会话startup、恢复 / 继续之前会话resume、清空会话clear、压缩会话compact/ 会触发SessionStart。
如上图开启会话后，打印了信息到hook-test.txt了。说明hooks配置成功
4.常用钩子配置
4.1 常用示例
-
用户确认 / 输入时的发送通知提醒（Notification）
-
格式化代码（PostToolUse）
-
阻止对受保护文件写操作（PreToolUse）
-
上下文压缩后自动重新（SessionStart）
-
记录 / 审计文件的变更（ConfigChange）
4.2 保护敏感文件
场景：阻止 Claude 修改敏感文件，例如.env、package-lock.json或 中的任何内容.git/。Claude 会收到反馈，解释为什么编辑被阻止，以便调整其方法。
创建钩子脚本
保存到.claude/hooks/protect-files.sh
#!/bin/bash
# 功能：保护敏感文件不被 Claude Code 修改/删除
# 作用：拦截 Write/Edit/Delete 等文件操作，匹配到敏感文件则阻止执行
# 读取 Claude 传入的 JSON 格式钩子输入数据
INPUT=$(cat)
# 从输入数据中解析出要操作的文件路径
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
# 定义需要保护的敏感文件/目录列表
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
# 遍历保护列表，检查文件路径是否匹配
for pattern in "${PROTECTED_PATTERNS[@]}"; do
# 如果路径包含保护关键词，判定为危险操作
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
# 输出错误日志
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
# 退出码 2 = 拦截操作，禁止执行
exit 2
fi
done
# 无匹配 → 放行操作
exit 0
为脚本设置权限
chmod +x .claude/hooks/protect-files.sh
注册hooks
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}
$CLAUDE_PROJECT_DIRClaude 内置环境变量，代表当前项目根目录。 意思是：对于当前项目目录 执行protect-files.sh脚本。=
5. 开源的hooks
| 项目名称 | 地址 |
|---|---|
| 官方示例 | https://code.claude.com/docs/en/hooks-guide#what-you-can-automate |
| claude-code-hooks | https://github.com/maxkelley23/claude-code-hooks |
| claude-hooks | https://pypi.org/project/claude-hooks/ |
| everything-claude-code | https://github.com/affaan-m/everything-claude-code |
| awesome-claude-code | https://github.com/hesreallyhim/awesome-claude-code |
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
13
0- 0
已为社区贡献4条内容
所有评论(0)