Claude Code Hooks 完全拆解：用 Shell 命令接管 AI 的每个动作

为什么 Hooks 比 CLAUDE.md 更可靠

五种生命周期事件

配置结构与三个作用域

• ~/.claude/settings.json：用户全局，对所有项目生效
• .claude/settings.json：项目级，可提交 git 供团队共享
• .claude/settings.local.json：本地个人配置，建议加入 .gitignore

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black \"$file\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/send-telegram.sh 'Claude finished the task'"
          }
        ]
      }
    ]
  }
}

钩子如何控制 Claude 的决策

用退出码传递状态

• 退出码 0：成功，stdout 会在对话记录模式（Ctrl-R）里展示给用户
• 退出码 2：阻塞错误，stderr 会回传给 Claude——对于 PreToolUse 这意味着工具调用被取消，Claude 会看到你的错误信息并重新决策；对于 Stop 则会阻止 Claude 停止并要求它继续处理
• 其他退出码：非阻塞错误，只展示 stderr，不打断流程

用 JSON 输出精细控制

{
  "decision": "block",
  "reason": "检测到生产环境配置文件写入，已拦截。请确认操作范围后重试。"
}

三个实用配置示例

1. Python 文件写入后自动 Black 格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black \"$file\""
          }
        ]
      }
    ]
  }
}

2. 任务完成后发 macOS 系统语音通知

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "say 'Claude has finished the task'"
          }
        ]
      }
    ]
  }
}

3. 拦截生产配置文件写入

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\npath = data.get('tool_input', {}).get('file_path', '')\nif 'production' in path or '.env' in path:\n    print(json.dumps({'decision': 'block', 'reason': f'拦截生产文件写入: {path}'}))\nelse:\n    print(json.dumps({'decision': 'approve'}))\n\""
          }
        ]
      }
    ]
  }
}

Hooks 读取的 stdin 数据结构

• tool_name：工具名称（Write、Bash、Edit 等）
• tool_input：工具入参，结构随工具类型变化（比如 Write 包含 file_path 和 content）
• tool_response（仅 PostToolUse）：工具执行结果

与 MCP 工具的搭配

{
  "matcher": "mcp__.*__write.*",
  "hooks": [{ "type": "command", "command": "/scripts/validate-mcp-write.py" }]
}

快速上手：5 分钟最小配置

// .claude/settings.json
{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(npm:*)"]
  },
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "say 'Claude has finished'"
          }
        ]
      }
    ]
  }
}

边界与注意事项

• --dangerously-skip-permissions 慎用：在自动化脚本里跑 Claude Code 时经常会用到这个标志来绕过所有权限确认，风险较高，务必配合 permissions.allow 白名单使用，而不是图省事什么都放行。2
• Stop 钩子的 stop_hook_active 字段：如果你在 Stop 钩子里触发了新的 Claude 操作，可能导致无限循环。官方文档里会在 Stop 事件的 stdin 携带 stop_hook_active 标记，用来检测当前是否已经在一次钩子触发的流程里。1
• 成本：Hooks 本身不消耗 token，但 decision: block 让 Claude 继续处理、或 Stop 钩子里触发了新任务，都会产生额外的 token 消耗。