Claude Code：Hooks

lengleng

2026-01-02 (Updated: 2026-01-02)

Claude Code

系列导航

安装与配置

入门使用

高级功能

SlashCommands

Hooks（本文）

Agents（子代理）

MCP

Plan 模式

Skills 技能

头脑风暴（Superpowers）

1. 概述

简单来说，Hooks 就是在 Claude Code 特定时刻自动执行的命令。就像给你的 AI 助手装上了”自动驾驶”系统！

参考资源：https://github.com/disler/claude-code-hooks-mastery

Claude Code 提供了 4 种 Hook 类型：

PreToolUse：在工具调用前执行（可以阻止执行）
PostToolUse：在工具完成后执行
Notification：当 Claude Code 发送通知时触发
Stop：当 Claude Code 完成响应时执行

看到没？这不就是咱们梦寐以求的自动化吗！废话少说，先干起来再说。

2. 了解 Hooks

2.1 基本配置结构

先来看看 Hooks 的基本配置结构：

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

小贴士：这个配置通常放在 ~/.claude/ 目录下的配置文件中哦！

主要有不同级别的配置，你想针对哪个粒度的都可以：

~/.claude/settings.json - 用户设置
.claude/settings.json - 项目设置
.claude/settings.local.json - 本地项目设置（不提交到版本控制）

2.2 四个时机

相当于在不同的阶段放入回调，当这个步骤执行完后，就可以执行你配置的命令了。

PreToolUse：工具调用前运行，可阻止调用并反馈原因
PostToolUse：工具调用后运行
Notification：Claude Code 发送通知时运行
Stop：Claude Code 响应结束时运行

PreToolUse

常见的匹配器：

Task - Agent 任务
Bash - Shell 命令
Glob - 文件匹配
Grep - 内容搜索
Read - 文件读取
Edit, MultiEdit - 文件编辑
Write - 文件写入
WebFetch, WebSearch - 网页搜索

PostToolUse

工具成功运行后会启动这个任务，匹配的模式跟 PreToolUse 一样。

Notification

当 Claude Code 发送通知时，它就会运行。

不过我没有测试出来，哪位朋友测出来的可以来通知我呀

Stop

当 Claude Code 完成任务后运行。

3. 实战案例 - 自动记录命令日志

3.1 打开 hooks 配置

/hooks

3.2 选择时机（4 种）

有四个时机的选项可以选择，这里我们选择第一个

3.3 输入 matcher

输入 matcher，这里我们记录命令，所以选择的是 Bash

Bash

3.4 添加 hook

输入你的命令，这里使用 jq 命令从输入的 json 结构里面来过滤命令行

1	jq -r '[.tool_input.command, .tool_input.description // "No description"] \| join(" - ")' >> ~/.claude/bash-command-log.txt

3.5 保存

选择保存的配置的级别，这里我就选择用户级别了。

3.6 测试

让 Claude Code 帮我们执行 ls -ltr 命令，测试下是否可以行。

最后我们查看之前配置好的命令里面的文件，发现已经有记录了。

这样一个 hooks 就配置好了。这个 hooks 每次都会记录所有的执行命令。

4. 更多实用场景

4.1 场景一：代码自动格式化

每次不用手动运行命令了，改完的代码就符合规则。减少后期的维护和错误。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | select(endswith(\".js\") or endswith(\".ts\") or endswith(\".jsx\") or endswith(\".tsx\")) | xargs -r npx prettier --write"
          }
        ]
      }
    ]
  }
}

4.2 场景二：任务完成通知

可以看到这里我配置了有 3 个通知，其实就是测试了各种场景

"hooks": {
   "Stop": [
     {
       "matcher": "",
       "hooks": [
         {
           "type": "command",
           "command": "echo 'stop======完成工作，当前时间：'$(date '+%Y年%m月%d日(%a)%H:%M')"
         },
         {
           "type": "command",
           "command": "afplay /System/Library/Sounds/Glass.aiff && osascript -e 'display notification \"任务完成啦\" with title \"系统提示\"'"
         },
         {
           "type": "command",
           "command": "curl -H \"Title：ClaudeCode\" -d \"任务完成通知\" ntfy.sh/ccnotifications"
         }
       ]
     }
   ]
 }

第一种场景：普通打印日志

就是纯粹的打印。在终端使用 ctrl+r 可以看到。

第二种场景：电脑通知

不仅有提示音，还有提醒

第三种场景：手机通知

这个还是不错的，可以直接在手机上收到通知。

4.3 场景三：每次都记录代码

这个是什么功能了，相当于可以自动存档了，不需要手扶了（每次自己提交 git 记录，或者每次对话 CC 让他帮你提提交）

"hooks":{
    "Stop": {
        "matcher": "",
        "hooks": [
            "type": "command",
            "command":"jj show"
        ]
    }
}

如果有错误，你想恢复到之前的版本，直接用 jj op log 和 jj op restore 就搞定了。

这个可能跟你平常的提交 commit 不太一样，但是这个历史记录会很干净。

5. Hooks 输入输出说明

下面就详细说下 hooks 的输入和输出。

输入很简单就是 Claude Code 给你的参数，你可以通过这些参数来进行一定你的逻辑。

输出就是，你的逻辑执行完后，你可以用输出来控制 Claude Code 下一步操作