返回首页

Hooks 配置指南

拦截 Claude Code 的工具调用，实现安全检查、自动审批、日志记录等自定义行为。

什么是 Hooks？

Hooks 是 Claude Code 的事件拦截机制。当 Claude 执行特定操作（如读写文件、运行命令）时，你可以编写脚本来检查、修改或阻止这些操作。

为什么需要 Hooks？

保护敏感文件不被修改、阻止危险命令执行、记录所有操作日志、实现自定义审批流程等。Hooks 是 Claude Code 安全使用的重要保障。

Hook 类型

Pre

PreToolUse

在工具执行之前触发。可以检查参数、阻止执行或修改输入。

阻止删除 .env 文件

Post

PostToolUse

在工具执行之后触发。可以检查结果、记录日志或触发后续操作。

记录所有文件修改

通知

Notification

特定事件发生时触发通知，如会话开始、错误发生等。

会话开始时发送通知

配置方式

Hooks 配置在 ~/.claude/settings.json 或项目的 .claude/settings.json 文件中。

基本结构

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/check_edit.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Command executed: $TOOL_INPUT\""
          }
        ]
      }
    ]
  }
}

配置参数说明

参数	说明	示例
`matcher`	匹配的工具名称（正则表达式）	`Edit\|Write`, `Bash`, `.*`
`type`	Hook 类型	`command`
`command`	要执行的命令	`python3 check.py`

环境变量

Hook 脚本可以通过环境变量获取上下文信息。

TOOL_NAME 当前执行的工具名称

TOOL_INPUT 工具的输入参数（JSON）

TOOL_OUTPUT 工具的输出结果（仅 PostToolUse）

SESSION_ID 当前会话 ID

PROJECT_DIR 当前项目目录

CLAUDE_PLUGIN_ROOT 插件根目录路径

实用示例

🛡️ 阻止修改敏感文件

安全

阻止 Claude 修改 .env、secrets.json 等敏感文件。

# check_sensitive.py
import os
import json
import sys

SENSITIVE_PATTERNS = ['.env', 'secrets', 'credentials', '.pem', '.key']

tool_input = json.loads(os.environ.get('TOOL_INPUT', '{}'))
file_path = tool_input.get('file_path', '')

for pattern in SENSITIVE_PATTERNS:
    if pattern in file_path.lower():
        print(f"⚠️ 拒绝修改敏感文件: {file_path}")
        sys.exit(1)

sys.exit(0)

📝 记录所有文件修改

日志

记录所有文件修改操作到日志文件。

# log_changes.py
import os
import json
from datetime import datetime

LOG_FILE = os.path.expanduser("~/.claude/edit_log.txt")

tool_name = os.environ.get('TOOL_NAME', '')
tool_input = json.loads(os.environ.get('TOOL_INPUT', '{}'))

with open(LOG_FILE, 'a') as f:
    timestamp = datetime.now().isoformat()
    file_path = tool_input.get('file_path', 'unknown')
    f.write(f"[{timestamp}] {tool_name}: {file_path}\n")

🚫 限制危险命令

安全

阻止执行危险的 shell 命令。

# check_command.py
import os
import json
import sys

DANGEROUS_COMMANDS = ['rm -rf', 'sudo', 'chmod 777', 'curl | bash']

tool_input = json.loads(os.environ.get('TOOL_INPUT', '{}'))
command = tool_input.get('command', '')

for dangerous in DANGEROUS_COMMANDS:
    if dangerous in command:
        print(f"⚠️ 危险命令被阻止: {command}")
        sys.exit(1)

sys.exit(0)

注意事项

返回码规则

Hook 脚本返回 0 表示允许继续，非 0 返回值会阻止操作执行。

性能影响

Hook 会在每次工具调用时执行，避免在 Hook 中执行耗时操作，以免影响使用体验。

错误处理

Hook 脚本崩溃不会阻止 Claude Code 运行，但会在控制台显示警告信息。

调试技巧

使用 echo 或日志文件调试 Hook 脚本，stdout 输出会显示给用户。

了解更多

查看官方文档了解 Hooks 的完整功能和高级用法。

官方文档