Claude Code 钩子系统的详细配置指南——从基础到高级用法。
钩子基础
钩子是在 Claude Code 执行某些操作前后自动运行的 Shell 脚本。它们让你插入自定义逻辑到 Claude 的工作流程中。
配置方式
项目级配置
在 .claude/settings.json 中配置：
{
"permissions": {
"hooks": {
"pre-command": "echo '即将运行: $COMMAND'",
"post-command": "echo '完成，状态: $STATUS'",
"post-turn": "date >> ~/.claude/sessions.log"
}
}
}用户级配置
在 ~/.claude/settings.json 中配置，对所有项目生效。
所有可用钩子
| 钩子 | 触发时机 | 可用变量 |
|---|---|---|
pre-command | 运行命令之前 | $COMMAND |
post-command | 运行命令之后 | $COMMAND, $STATUS |
pre-tool-use | 使用工具之前 | $TOOL |
post-tool-use | 使用工具之后 | $TOOL, $OUTPUT |
pre-turn | Claude 回复之前 | 无 |
post-turn | Claude 回复之后 | 无 |
notification | 发送通知时 | $MESSAGE |
user-message-submit | 用户发送消息之前 | $MESSAGE |
实战示例
示例 1：自动代码格式化
Claude 每次编辑文件后自动运行格式化工具：
{
"permissions": {
"hooks": {
"post-tool-use": "if [ "$TOOL" = "Edit" ]; then black . --quiet; fi"
}
}
}示例 2：安全审计日志
记录 Claude 运行的所有命令：
{
"permissions": {
"hooks": {
"post-command": "echo $(date +%T) "$COMMAND" (exit: $STATUS) >> claude-audit.log"
}
}
}示例 3：拦截危险操作
阻止 Claude 运行特定命令：
{
"permissions": {
"hooks": {
"pre-command": "if echo "$COMMAND" | grep -qE 'rm -rf /|chmod 777'; then echo '禁止危险操作'; exit 1; fi"
}
}
}示例 4：自动通知
Claude 完成工作后发送通知：
{
"permissions": {
"hooks": {
"post-turn": "notify-send 'Claude Code' '一轮对话完成'"
}
}
}注意事项
- 保持简短：钩子脚本应该快速执行，长时间运行的钩子会阻塞 Claude
- 错误处理：钩子退出码非零时，对应的操作会被取消
- 安全性：钩子中不要硬编码密钥或敏感信息
- 调试：钩子脚本的错误输出会显示在终端中