Claude Code

Hooks 自动化

Claude Code Hooks 生命周期、事件、matcher、command/http/mcp_tool/prompt/agent handler,以及常见安全自动化模板。

Hooks 是 Claude Code 的自动化层。它能在会话开始、用户提交 prompt、工具执行前后、配置变化、上下文压缩等节点运行脚本、HTTP 请求、MCP 工具或 LLM 检查。

Hooks 是把团队规范变成机制的地方:格式化、审计、阻止危险命令、记录工具调用、通知长任务完成,都适合放这里。

#生命周期

频率	事件示例	用途
会话级	`SessionStart`, `SessionEnd`, `Setup`	初始化环境、打印说明、记录会话
每轮对话	`UserPromptSubmit`, `Stop`, `StopFailure`	检查 prompt、通知完成、错误诊断
工具调用	`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure`	阻止、审计、格式化、自动验证
批处理/子代理	`PostToolBatch`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`	追踪并行任务
配置/上下文	`InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `PreCompact`, `PostCompact`	观察配置和记忆加载
MCP 交互	`Elicitation`, `ElicitationResult`	处理 MCP 请求用户输入

常用事件:

PreToolUse:工具执行前,可阻止危险动作
PostToolUse:工具成功后,可格式化或跑轻量检查
UserPromptSubmit:用户输入进入模型前,可做校验或补充上下文
Stop:Claude 完成一轮回复后,可通知或记录
ConfigChange:settings、hooks、rules 变化时触发
FileChanged:监听指定文件变化,适合 .envrc、锁文件等

#基础配置

Hooks 写在 settings 文件里:

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

Hook 由三层组成:

事件,例如 PreToolUse
matcher group,例如只匹配 Bash
handler,例如 command、http、mcp_tool、prompt、agent

#Matcher 规则

写法	含义	示例
省略、空字符串、`*`	匹配全部	所有工具调用都触发
`Bash`	精确匹配工具名	只看 Bash
`Edit 和 Write`	多个精确工具	编辑文件后触发
`mcp__memory__.*`	正则	匹配 memory server 全部 MCP 工具

对工具事件,还可以用 if 字段做更细过滤:

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

if 使用权限规则语法。Bash 复合命令会按子命令检查,不是只匹配整行字符串。

#Handler 类型

类型	做什么	适合场景
`command`	执行本地命令,stdin 接收 JSON	本地格式化、审计、阻止
`http`	POST JSON 到 URL	集中审计、通知系统
`mcp_tool`	调用已连接 MCP 工具	把检查逻辑放进 MCP
`prompt`	让模型做单轮判断	轻量语义检查
`agent`	启动子代理验证	需要读文件或复杂判断

Command hook 的 stdin 是事件 JSON。输出可以是空,也可以返回 JSON 决策。

#阻止危险命令

.claude/hooks/block-rm.sh

#!/usr/bin/env bash
set -euo pipefail

COMMAND=$(jq -r '.tool_input.command // ""')

if echo "$COMMAND" | grep -Eq 'rm -rf (~/|/|\\$HOME)'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Refuse to remove home or root paths"
    }
  }'
fi

对应配置:

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Hook 保持沉默不等于批准。空输出或 exit 0 只是让 Claude Code 继续走正常权限流程。

#自动格式化

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix"
          }
        ]
      }
    ]
  }
}

大型项目不要每次编辑后跑完整构建。Hook 应该短、稳定、可预期。完整验证更适合让 Claude 在任务结束后手动跑。

#配置位置

位置	作用
`~/.claude/settings.json`	个人全局 Hook
`.claude/settings.json`	团队共享 Hook
`.claude/settings.local.json`	本项目个人 Hook
Managed settings	组织强制 Hook
Plugin hooks	插件启用时加载
Skill/agent frontmatter	技能或子代理激活时加载

#排错

现象	检查
Hook 没触发	`/hooks` 看实际加载和 matcher
settings 改了没生效	看 `ConfigChange`,确认 JSON 合法
命令找不到	用绝对路径或 `${CLAUDE_PROJECT_DIR}`
太慢	加 `if` 缩小范围,避免每次都 spawn
MCP 工具没匹配	工具名应为 `mcp__server__tool`
想验证是否配置干扰	`claude --safe-mode` 临时禁用自定义项

#官方参考

上一页MCP 工具接入下一页插件与 Skills

Support / 支持

Need help? / 需要帮助？

接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right