Hooks 是 Claude Code 的自动化机制：在 Claude 生命周期的关键节点自动执行你的 Shell 命令。确保某些操作总是发生——而不是依赖 LLM 去记得执行。
Hooks vs Skills vs 子代理
| 方式 | 适用场景 |
|---|---|
| Hooks | 确定性规则，总是执行（格式化、保护文件） |
| Skills | 给 Claude 增加指令或可执行命令 |
| 子代理 | 在隔离上下文中运行任务 |
| 提示型 Hooks | 需要 AI 判断的条件（分析变更质量） |
快速创建第一个 Hook
在 Claude Code 中输入 /hooks，进入交互式菜单：
- 选择 Hook 事件类型
- 设置匹配条件（
*表示全部） - 输入要执行的 Shell 命令
- 选择存储位置（用户设置或项目设置）
5 大实用场景
1. Claude 需要输入时发桌面通知
让 Claude 工作时你可以去做别的，完成后自动弹通知：
macOS：
json
{
"hooks": {
"Notification": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude 需要你的注意\" with title \"Claude Code\"'"
}
]
}
]
}
}Linux：
json
{
"hooks": {
"Notification": [
{
"matcher": "*",
"hooks": [
{ "type": "command", "command": "notify-send 'Claude Code' 'Claude 需要你的注意'" }
]
}
]
}
}2. 编辑后自动格式化代码
每次 Claude 修改文件后自动运行格式化工具：
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $CLAUDE_TOOL_RESULT_FILE_PATH 2>/dev/null || true"
}
]
}
]
}
}也可以按文件类型匹配：
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"matchers": [
{ "tool_input.file_path": { "pattern": ".*\\.py$" } }
],
"hooks": [
{ "type": "command", "command": "black $CLAUDE_TOOL_RESULT_FILE_PATH" }
]
}
]
}
}3. 保护关键文件不被修改
阻止 Claude 修改 .env、密钥文件等：
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"matchers": [
{ "tool_input.file_path": { "pattern": ".*\.env.*|.*secret.*|.*credential.*" } }
],
"hooks": [
{
"type": "command",
"command": "echo '{\"decision\": \"block\", \"reason\": \"Protected file - cannot modify env/secret files\"}'"
}
]
}
]
}
}4. 压缩后重新注入上下文
/compact 后某些关键信息会丢失，用 Hook 自动补回：
json
{
"hooks": {
"PostCompact": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "echo '当前分支：'$(git branch --show-current)'，项目：'$CLAUDE_PROJECT_DIR"
}
]
}
]
}
}5. 审计配置变更
记录所有配置文件修改到日志：
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"matchers": [
{ "tool_input.file_path": { "pattern": ".*\.json$|.*\.yaml$|.*\.yml$" } }
],
"hooks": [
{
"type": "command",
"command": "echo \"$(date): Modified $CLAUDE_TOOL_RESULT_FILE_PATH\" >> ~/.claude-audit.log"
}
]
}
]
}
}Hook 工作原理
输入
Hook 命令通过标准输入接收 JSON 数据：
json
{
"tool_name": "Write",
"tool_input": {
"file_path": "/path/to/file.py",
"content": "..."
},
"session_id": "xxx"
}输出
Hook 通过标准输出返回结果（可选）：
json
{ "decision": "approve" } // 允许操作
{ "decision": "block", "reason": "Protected" } // 阻止操作
{ "message": "注意：该文件已被修改" } // 给 Claude 的消息非零退出码通常表示警告但不阻止操作（取决于 Hook 类型）。
Hook 事件类型
| 事件 | 触发时机 |
|---|---|
PreToolUse | 工具执行前 |
PostToolUse | 工具执行后 |
Notification | Claude 需要输入时 |
PostCompact | 上下文压缩后 |
SessionStart | 会话开始时 |
配置位置
| 范围 | 文件位置 |
|---|---|
| 用户（所有项目） | ~/.claude/settings.json |
| 项目（团队共享） | .claude/settings.json |
| 本地项目（不提交） | .claude/settings.local.json |
高级：提示型和 Agent 型 Hook
需要 AI 判断时，可以用提示型 Hook：
json
{
"type": "prompt",
"prompt": "审查这次文件修改，如果有安全问题就阻止并说明原因"
}或 Agent 型 Hook（启动一个子代理做复杂分析）：
json
{
"type": "agent",
"agent": "security-reviewer"
}常见问题
Hook 没有触发？
- 检查事件类型是否正确
- 确认 matcher 模式是否匹配
- 运行
/hooks查看已配置的 Hook 列表
Stop Hook 一直运行？
- Stop hook 必须在有限时间内返回，否则 Claude Code 无法关闭
- 设置命令超时：
timeout 5 your-command
JSON 验证失败？
- Hook 输出必须是合法 JSON（如果有输出的话）
- 用
echo输出而不是 Shell 扩展字符串
原文：Automate workflows with hooks | 来源：Anthropic 官方文档