Claude Code 高级配置：如何设置 Hooks

Claude Code 高级用户自定义：如何配置钩子

了解如何配置 Claude Code 钩子，以自动化重复任务、强制执行项目规则，并为编码会话注入动态上下文。

• 分类Claude Code
• 产品Claude Code
• 日期2025年12月11日
• 阅读时间5分钟
• 分享复制链接https://claude.com/blog/how-to-configure-hooks

即使顺畅的Claude Code工作流程也会随时间积累摩擦点。每次 Claude 写入文件，Prettier都需要手动运行。每次运行 npm test，都会出现相同的权限提示。每次会话开始时，都需要将相同的样板项目上下文粘贴到第一条消息中。

好消息是？钩子消除了这些摩擦点。它们作为触发器，您可以在特定操作之前或之后配置执行，从而将自定义逻辑、脚本和命令直接注入 Claude 的操作中。

本文涵盖面向已熟悉 Claude Code 基础知识的开发者的高级配置。阅读本文后，您将了解八种钩子类型、各自的使用场景、如何配置它们，以及出现问题时如何调试。

让我们深入探讨。

什么是钩子？

钩子是一个自定义 shell 命令，当 Claude Code 会话中发生目标事件（例如 Claude 即将写入文件或您提交提示）时，它会自动执行。您可以为大量事项指定钩子：在操作执行前拦截、注入代理上下文、自动化审批或在操作发生前阻止操作。

钩子在您的设置文件中配置，使用包含事件名称、匹配器（用于过滤触发钩子的工具）和要运行的命令的 JSON 结构。它们在您的本地环境中用您的用户权限执行，通过 stdin 接收触发事件的信息，并通过退出代码和 stdout 进行通信。这使您能够精确控制 Claude Code 的行为，而无需修改工具本身。

为什么在 Claude Code 中使用钩子？

钩子解决三类问题。

首先，它们消除了重复的手动步骤。每次文件更改后，不必手动运行格式化程序，PostToolUse 钩子会自动处理。不必第一百次批准 npm test，PermissionRequest 钩子会自动批准。

其次，钩子自动强制执行项目特定规则。您可以在危险命令执行前阻止它们，在写入前验证文件路径，或确保遵循命名约定。这些护栏每次都会运行，而不仅仅是当您记得检查时。

第三，钩子无需手动努力即可注入动态上下文。 SessionStart 钩子可以将您当前的 git 状态和待办事项列表提供给 Claude。UserPromptSubmit 钩子可以将您的冲刺优先级附加到每个请求。Claude 能保持知情，而无需您重复自己。

Claude Code 钩子类型及其使用时机

Claude Code 提供八种钩子事件，覆盖了会话的完整生命周期，从启动到工具执行再到完成。每个事件在特定时刻触发，使您能够精确控制自动化运行的时间。选择正确的钩子取决于您想要完成什么。

钩子概览

PreToolUse

这是最常用的钩子，在 Claude 选择工具之后但工具实际执行之前触发。您的脚本可以检查计划的操作并批准、阻止、请求用户确认或修改参数，使用匹配器过滤哪些工具触发此钩子。

此 PreToolUse 钩子示例在文件写入执行前评估写入操作。Claude 根据指定标准审查计划操作，并根据提示逻辑批准、阻止或标记问题。

{
"hooks": {
"PreToolUse": [
      {
"matcher": "Write",
"hooks": [
          {
"type": "command",
"command": "/path/to/validate-file-path.sh"          }
        ]
      }
    ]
  }
}

何时使用 PreToolUse：

• 阻止危险的 Bash 命令，如 rm -rf 或强制推送
• 自动批准安全、重复的操作，以减少提示疲劳
• 在写入前验证文件路径，以防止意外覆盖
• 修改工具输入以注入项目特定默认设置

PermissionRequest

此钩子在 Claude 通常显示权限对话框时触发。此钩子拦截您看到确认提示之前的时刻，让您的脚本决定允许、拒绝或仍然询问用户。

{
"hooks": {
"PermissionRequest": [
      {
"matcher": "Bash(npm test*)",
"hooks": [
          {
"type": "command",
"command": "/path/to/validate-test-command.sh"          }
        ]
      }
    ]
  }
}

此示例自动批准任何以 npm test 开头的 Bash 命令。匹配器模式可以包含参数以实现更精细的控制。

何时使用 PermissionRequest：

• 自动批准每次会话中运行数十次的测试命令
• 阻止写入生产配置文件
• 允许对特定目录进行读取操作而无需提示
• 拒绝任何匹配危险模式的命令

PostToolUse

在工具成功完成后立即触发。您的脚本接收有关发生情况的信息，包括工具输出，使用匹配器过滤哪些工具触发它。

此 PostToolUse 示例对 Claude 写入或编辑的任何文件运行 Prettier。匹配器中的管道语法表示它对 Write 和 Edit 工具都触发。

{
"hooks": {
"PostToolUse": [
      {
"matcher": "Write|Edit",
"hooks": [
          {
"type": "command",
"command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""          }
        ]
      }
    ]
  }
}

何时使用 PostToolUse：

• 每次文件写入后运行 Prettier、Black 或 gofmt 以强制执行格式
• 记录所有文件修改到审计跟踪中
• 代码更改后触发 linter 并显示警告
• 某些操作完成时发送通知

PreCompact

在Claude压缩对话上下文以释放空间之前触发。压缩会总结对话的较旧部分，这意味着一些细节会丢失。这个钩子让你有机会在发生之前保留信息。

这个PreCompact示例在自动压缩之前备份了记录。匹配器可以是"auto"或"manual"，以便区分自动压缩和用户触发的压缩事件。

{
"hooks": {
"PreCompact": [
      {
"matcher": "auto",
"hooks": [
          {
"type": "command",
"command": "/path/to/backup-transcript.sh"          }
        ]
      }
    ]
  }
}

何时使用PreCompact：

• 在摘要之前将完整记录备份到文件中
• 提取并保存重要的决定或代码片段
• 记录会话里程碑供以后回顾

SessionStart

当Claude Code启动新会话或恢复现有会话时触发。无论你的脚本输出什么，都会被添加到对话上下文中，因此Claude在开始时已经加载了这些信息。

{
"hooks": {
"SessionStart": [
      {
"hooks": [
          {
"type": "command",
"command": "git status --short && echo '---' && cat TODO.md"          }
        ]
      }
    ]
  }
}

每个会话开始时，Claude都会知道你当前的git状态和TODO列表。标准输出自动成为上下文。

何时使用SessionStart：

• 向Claude提供你当前的git分支和最近的提交
• 加载你的TODO列表或冲刺积压的内容
• 注入特定于环境的配置详细信息

Stop

当Claude完成响应并通常会等待你的下一个输入时触发。你的脚本可以检查Claude生成的内容，并决定任务是否真正完成。

脚本可以返回带有"continue": true的JSON，使Claude继续工作，这对于多步骤工作流程很有用：

{
"hooks": {
"Stop": [
      {
"hooks": [
          {
"type": "prompt",
"prompt": "Review whether the task is complete. If all requirements are met, respond with 'complete'. If work remains, respond with 'continue' and specify what still needs to be done."          }
        ]
      }
    ]
  }
}

何时使用Stop：

• 强制Claude继续，直到清单中的所有项目都完成
• 在认为任务完成之前验证测试是否通过
• 在会话结束时触发摘要生成
• 在停止之前检查生成的代码是否编译

SubagentStop

每当通过Task工具创建的子代理完成时，此挂钩触发。工作方式与Stop相同，但在子代理完成其操作（而不是主代理）时专门触发。SubagentStop的配置与Stop挂钩结构相同：

{
"hooks": {
"SubagentStop": [
      {
"hooks": [
          {
"type": "prompt",
"prompt": "Evaluate the subagent's output. Verify the task was completed correctly and the results meet quality standards. If the output is satisfactory, respond with 'accept'. If issues exist, respond with 'reject' and explain what needs to be fixed."          }
        ]
      }
          ]
  }
}

何时使用SubagentStop：

• 验证子代理输出是否符合质量标准
• 根据子代理结果触发后续操作
• 记录子代理活动以供调试或审计

UserPromptSubmit

当你提交提示时触发，在Claude处理之前。无论你的脚本通过标准输出输出什么，都会与你的提示一起添加到Claude的上下文中，这使得UserPromptSubmit对于动态注入Claude应考虑的信息非常有用。

在这个示例中，每次你提交提示时，Claude都会收到你的冲刺上下文文件的内容。这使Claude了解当前的优先级，而无需你重述。

{
"hooks": {
"UserPromptSubmit": [
      {
"hooks": [
          {
"type": "command",
"command": "cat ./current-sprint-context.md"          }
        ]
      }
    ]
  }
}

何时使用UserPromptSubmit：

• 在每次提示时注入当前冲刺上下文或项目优先级
• 在提示到达Claude之前进行验证
• 根据内容阻止某些类型的请求
• 添加动态上下文，如最近的错误日志或测试结果

配置和文件位置

挂钩位于三个级别的JSON设置文件中。项目级挂钩位于你的存储库中的.claude/settings.json中，使它们可以与你的团队共享。用户级挂钩位于~/.claude/settings.json中，适用于你的所有项目。本地项目挂钩位于.claude/settings.local.json中，用于你不希望提交的个人配置。

项目级设置优先于用户级设置。还有企业管理的策略设置可用于组织控制。有关完整详细信息，请参阅Claude Code设置信息。

专业提示： 这是同一个文件，你可以在其中为Claude操作设置细粒度权限，在项目、用户或本地级别。例如，你可以明确允许Claude读取目录中的所有文件，这样你就不必每次都批准，或者阻止任何对敏感文件的修改。

匹配器语法

匹配器是过滤哪些工具可以触发你的挂钩的方式。它们只适用于PreToolUse、PostToolUse和PermissionRequest挂钩。

简单字符串匹配的工作方式与你预期的一样："Write"只匹配写入工具。

例如：

{
"hooks": {
"PreToolUse": [
      {
"matcher": "Write",
"hooks": [
          {
"type": "command",
"command": "your-command-here"          }
        ]
      }
    ]
  }
}

管道语法允许你匹配多个工具："Write|Edit"触发两者，而通配符匹配所有内容："*"或空字符串匹配所有工具。

注意： 匹配器区分大小写，因此"bash"不会与Bash工具匹配。

为了更精确的控制，参数模式如"Bash(npm test*)"可以匹配特定的命令参数。MCP工具模式遵循"mcp__memory__.*"的格式，用于模型上下文协议工具。

输入、输出和结构化响应

挂钩接收什么

所有挂钩通过stdin接收包含会话信息和事件特定数据的JSON。常见字段包括：session_id、transcript_path、cwd、permission_mode和hook_event_name。

此外，与工具相关的挂钩还会收到tool_name和tool_input。这些数据让你的脚本能够做出明智的决定，决定如何响应。

挂钩如何响应

退出代码决定基本结果。退出代码0表示成功，stdout要么被处理为JSON，要么被添加到上下文中。退出代码2表示阻塞错误：stderr成为错误消息，并且操作被阻止。

其他退出代码表示非阻塞错误，stderr在详细模式下显示。

除了退出代码外，挂钩可以返回结构化JSON以获得更多控制。字段包括：decision（approve、block、allow或deny）、reason（向Claude显示的解释）、continue（用于Stop挂钩以强制继续）以及updatedInput（用于在执行之前修改工具参数）。

环境和执行

挂钩可以访问环境变量，包括：CLAUDE_PROJECT_DIR用于项目根路径，CLAUDE_CODE_REMOTE在Web环境中为true，以及CLAUDE_ENV_FILE用于SessionStart挂钩以持久化变量。来自你的shell的标准环境变量也可以访问。

另外需要注意的是：挂钩有60秒的默认超时时间，可按挂钩配置。当多个挂钩匹配一个事件时，它们并行运行。相同的命令会自动去重。

安全考虑

钩子以你的用户权限执行任意 shell 命令。Claude Code 包含一项保护措施：直接编辑钩子配置文件需要先在 /hooks 菜单中审查，然后才能生效。这可以防止恶意代码悄悄地将钩子添加到你的配置中。

但是，如果你配置并批准了钩子，它们将以你的权限级别执行。

专业提示：在环境中运行任何命令之前，请考虑风险。如果你要运行带钩子的命令，请考虑良好的实践，例如：验证和清理来自标准输入的输入，对 shell 变量加引号以防止注入，使用脚本的绝对路径，并避免处理敏感文件，如 .env 或凭据。

调试与测试

Claude Code 将所有内容记录到转录文件中，无需任何设置即可查看工具调用和响应。每个钩子都会收到一个 transcript_path 字段，指向包含完整会话历史的 JSONL 文件。你可以使用 SessionStart 钩子来记录每个转录文件的位置：

{
"hooks": {
"SessionStart": [
      {
"hooks": [
          {
"type": "command",
"command": "jq -r '\"Session: \" + .transcript_path' >> ~/.claude/sessions.log"          }
        ]
      }
    ]
  }
}

然后使用 tail 命令实时查看 Claude 的工作：tail -f /path/to/transcript.jsonl | jq .

钩子特定调试

对于钩子特定调试，请在钩子脚本中添加日志记录。转录文件将显示 Claude 做了什么，但不会显示你的钩子为何批准或阻止某操作。

稍加努力，你可以添加一个小的 bash 脚本，用于包装你的工具并记录额外信息。例如，log-wrapper.sh：

#!/bin/bashLOG=~/.claude/hooks.log
INPUT=$(cat)
TOOL=$(echo"$INPUT" |
 jq -r '.tool_name // "n/a"')
EVENT=$(echo"$INPUT" | jq -r '.hook_event_name // "n/a"')
echo"=== $(date) | $EVENT | $TOOL ===" >> "$LOG"echo"$INPUT" | "$1"CODE=$?
echo"Exit: $CODE" >> "$LOG"exit$CODE

这个小的包装脚本将标准输入捕获到变量中，记录时间戳和工具名称，然后将输入传递给实际的工具。

编写 log-wrapper.sh 后，你需要将其前置到钩子中的工具调用：

{
"hooks": {
"PreToolUse": [
      {
"matcher": "Bash",
"hooks": [
          {
"type": "command",
"command": "log-wrapper.sh your-tool-command.py"          }
        ]
      }
    ]
  }
}

专业提示：有关更多调试技巧，请参阅 Claude Code 调试文档。

构建你自己的钩子

从一个简单的钩子开始，解决你工作流程中一个实际的痛点。PostToolUse 格式化钩子是一个不错的选择，因为反馈即时且可见。一旦它运行正常，就可以根据所学进行扩展。

有关所有可用字段和高级模式的完整参考文档，请参见官方钩子文档。

钩子让你可以塑造 Claude Code 以适应你的工作流程，而不是调整工作流程去适应工具。当你投入配置钩子时，每个会话都会受益。

立即开始使用钩子来定制你的 Claude Code 工作流程。

未找到项目。

上一页

0/5

下一页

获取 Claude Code

或阅读 文档

尝试 Claude Code

尝试 Claude Code

开发者文档

开发者文档

电子书

常见问题

未找到项目。

相关文章

探索更多产品新闻和最佳实践，帮助团队使用 Claude 构建。

2026年8月7日

自动模式现已成为 Claude Code 中 Pro、Max 和 Team 计划的默认设置

Claude Code

自动模式现已成为 Claude Code 中 Pro、Max 和 Team 计划的默认设置

自动模式现已成为 Claude Code 中 Pro、Max 和 Team 计划的默认设置

2026年8月7日

在生产环境中运行自动模式

Claude Code

在生产环境中运行自动模式

在生产环境中运行自动模式

2026年8月6日

Millennium 和 Anthropic 正在使用 Claude 构建数字风险分析师

企业 AI

Millennium 和 Anthropic 正在使用 Claude 构建数字风险分析师

Millennium 和 Anthropic 正在使用 Claude 构建数字风险分析师

2026年7月24日

Claude 模型解析：选择最佳模型以满足你的使用场景

企业 AI

Claude 模型解析：选择最佳模型以满足你的使用场景

Claude 模型解析：选择最佳模型以满足你的使用场景

利用 Claude 改变组织的运作方式

查看定价

查看定价

联系销售

联系销售

订阅开发者新闻通讯

产品更新、操作指南、社区亮点等。每月发送到你的邮箱。

谢谢！您已订阅。

抱歉，您提交时出现问题，请稍后重试。