AI 原生开放教材

外观

Claude Code & OpenClaw & Codex & WorkBuddy 中文教程课时教程·中文原文 ↗原件 ↓仓库 ↗

第二部分：5分钟快速开始（立即见效） ​

本节目的：用最快速度配置第一个Hook，让你立即看到效果！

⏱️ 预计时间：5-10分钟

2.1 配置第一个Hook（最简单版本） ​

为什么选这个示例？

  • ✅ 最简单，只需要3个文件
  • ✅ 效果直观，立即看到输出
  • ✅ 无依赖，不需要安装任何东西

步骤1：创建Hook脚本目录 ​

这一步要做什么：在项目根目录创建 .claude/hooks/ 目录

Windows系统（PowerShell）：

powershell
# 进入你的项目目录
cd C:\你的项目路径

# 创建hooks目录
New-Item -ItemType Directory -Path ".claude\hooks" -Force

macOS/Linux系统：

bash
# 进入你的项目目录
cd ~/你的项目路径

# 创建hooks目录
mkdir -p .claude/hooks

验证是否成功：

bash
# 检查目录是否存在
ls .claude/hooks
# 应该显示空目录（暂时没有文件）

步骤2：创建最简单的Hook脚本 ​

这一步要做什么：创建一个Python脚本，在每次Write工具执行后打印提示

创建文件 .claude/hooks/post-write-hello.py：

💡 你有两种选择：

选择A：在Claude Code对话框里说人话（推荐新手）

帮我创建.claude/hooks/post-write-hello.py文件，内容是一个PostToolUse Hook脚本，在Write工具执行后打印提示信息

（换行用 Shift + Enter，最后按 Enter 发送）

Claude Code会自动帮你创建正确格式的文件！

选择B：在终端里用命令行（熟悉命令行的用户） 见下方PowerShell/Bash代码

Windows（PowerShell）：

powershell
@'
#!/usr/bin/env python3
"""
最简单的PostToolUse Hook示例
每次Write工具执行后记录日志
"""
import sys
import json
from pathlib import Path
from datetime import datetime

# 从stdin读取工具执行信息
try:
    input_data = json.loads(sys.stdin.read())
except:
    sys.exit(0)

# 获取工具名称和文件路径
tool_name = input_data.get('tool_name', '')
tool_input = input_data.get('tool_input', {})
file_path = tool_input.get('file_path', '')

# 只处理Write工具
if tool_name == 'Write':
    # PostToolUse Hook执行后处理任务
    # 注意：PostToolUse Hook无法向用户输出信息
    # Claude Code只会显示"Hook执行成功"
    # 如果需要调试，可以写入日志文件
    log_file = Path.home() / '.claude' / 'hooks' / 'post-write.log'
    log_file.parent.mkdir(parents=True, exist_ok=True)
    with open(log_file, 'a', encoding='utf-8') as f:
        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
        f.write(f"[{timestamp}] ✅ 文件已保存: {file_path}\n")

sys.exit(0)
'@ | Out-File -FilePath ".claude\hooks\post-write-hello.py" -Encoding utf8

macOS/Linux：

bash
cat > .claude/hooks/post-write-hello.py << 'EOF'
# 粘贴上方 Windows 示例中 @' 和 '@ 之间的完整 Python 脚本
EOF

# 添加执行权限（macOS/Linux必须）
chmod +x .claude/hooks/post-write-hello.py

这两个平台使用的是同一份 Python 脚本，差别只在写入文件的命令和 macOS/Linux 需要 chmod +x。不要维护两份略有差异的 Hook 代码，否则排查时很容易把平台问题误判成脚本问题。

验证脚本创建成功：

bash
# 查看文件内容
cat .claude/hooks/post-write-hello.py
# 应该显示你刚才写入的Python代码

步骤3：配置settings.json ​

这一步要做什么：告诉Claude Code在PostToolUse时运行你的脚本

创建或编辑 .claude/settings.json：

💡 你有两种选择：

选择A：在Claude Code对话框里说人话（推荐新手）

帮我创建.claude/settings.json配置文件，配置PostToolUse Hook监听Write工具并运行post-write-hello.py脚本

（换行用 Shift + Enter，最后按 Enter 发送）

Claude Code会自动帮你创建正确格式的配置文件！

选择B：在终端里用命令行（熟悉命令行的用户） 见下方PowerShell/Bash代码

Windows（PowerShell）：

powershell
@'
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/post-write-hello.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
'@ | Out-File -FilePath ".claude\settings.json" -Encoding utf8

macOS/Linux：

bash
cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/post-write-hello.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
EOF

💡 配置说明：

  • "PostToolUse"：Hook类型，工具执行后触发
  • "matcher": "Write"：只匹配Write工具
  • "command"：要执行的脚本命令
  • "timeout": 10：超时10秒

步骤4：启动Claude Code并测试 ​

这一步要做什么：重启Claude Code，让它读取新配置

bash
# 在项目目录启动Claude Code
claude

测试命令：

你：帮我创建一个test.txt文件，内容是"Hello Hooks!"

预期结果：

Claude：我来帮你创建test.txt文件。

[Write工具执行]

✅ Hook执行成功

文件已创建成功！

💡 重要说明：

  • PostToolUse Hook执行后，Claude Code只会显示"Hook执行成功"
  • Hook的日志已写入~/.claude/hooks/post-write.log文件
  • 你可以查看日志文件确认Hook确实执行了：
    bash
    cat ~/.claude/hooks/post-write.log
# 应该看到类似：[2026-03-05 16:30:00] ✅ 文件已保存: /path/to/test.txt

✅ 关键确认：看到 Hook触发成功！ 说明Hook配置正确并成功执行！

2.2 验证Hook工作正常 ​

完整验证清单：

  • [ ] .claude/hooks/ 目录存在
  • [ ] .claude/hooks/post-write-hello.py 文件存在且内容正确
  • [ ] .claude/settings.json 文件存在且JSON格式正确
  • [ ] macOS/Linux上脚本有执行权限（chmod +x）
  • [ ] Claude Code启动时没有报错
  • [ ] 让Claude创建文件后看到Hook输出

如果没有看到Hook输出：

  1. 检查JSON格式：
bash
# 验证JSON格式是否正确
python -c "import json; json.load(open('.claude/settings.json'))"
# 如果没报错说明格式正确
  1. 检查Python是否可用：
bash
python --version
# 应该显示Python 3.x
  1. 手动测试脚本：
bash
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.txt"}}' | python .claude/hooks/post-write-hello.py
# 应该显示Hook触发成功的消息

2.3 恭喜完成第一个Hook！ ​

你刚才完成了什么？

  1. ✅ 创建了Hook脚本目录
  2. ✅ 编写了第一个Hook脚本
  3. ✅ 配置了settings.json
  4. ✅ 验证了Hook正常工作

接下来可以：

  • 继续学习15种Hook类型（第三部分）
  • 学习实战应用场景（第四部分）
  • 遇到问题查看故障排查（第五部分）