Хуки Claude Code

Хуки Claude Code — этоопределяемые пользователем команды Shell,которые автоматически выполняются в определенных узлах жизненного цикла Claude Code.

С помощью хуков вы можете добиться точного контроля над поведением Claude Code, гарантируя, что определенные операции (например, форматирование кода, логирование)обязательно запускаются, вместо того чтобы полагаться на то, что большая модель самостоятельно решит, выполнять их или нет.

Типичные сценарии применения хуков

Хуки могут помочь вам реализовать множество практических функций. Распространенные сценарии включают:

  • Уведомления о сообщениях: Автоматически отправлять напоминания на рабочем столе/по электронной почте, когда Claude Code ожидает ввода или нуждается в разрешениях
  • Автоформатирование: После редактирования.tsфайлы, автоматически запускатьprettier, после изменения.goфайлы, выполнитьgofmt
  • Журналы операций: записывать все команды, выполненные Claude, для аудита соответствия или отладки/поиска неисправностей
  • Проверка соответствия стандартам кода: если код, сгенерированный Claude, не соответствует стандартам проекта (например, правилам именования), автоматически предоставлять обратную связь
  • Контроль прав доступа к файлам: запретить Claude изменять файлы конфигурации продакшен-среды или конфиденциальные каталоги (например,.env、.git)

По сравнению с ограничением поведения Claude с помощью промптов, хуки — этожёсткие правила уровня приложения, которые принудительно применяются, как только срабатывает соответствующее событие, обеспечивая более высокую стабильность и надёжность.

Важное напоминание о безопасности

Когда хуки выполняются, онинапрямую используют учётные данные текущего системного окружения(например, переменные окружения, права пользователя), что создаёт определённые риски безопасности:

  • Вредоносный код хука может привести к утечке ваших конфиденциальных данных (например, API-ключей, исходного кода проекта)
  • Некорректные команды хуков могут привести к случайному удалению файлов или сбоям в системе

Обязательные меры безопасности:

  1. Перед регистрацией хуков обязательно построчно проверьте логику и разрешения команд
  2. Избегайте выполнения скриптов неизвестного происхождения в хуках
  3. Подробные рекомендации по безопасности см. в разделе официальной документацииМеры предосторожности

Описание типов событий хуков

В Claude Code есть несколько встроенных событий жизненного цикла. Вы можете привязывать команды хуков к разным событиям. Каждое событие передаёт разные данные контекста и по-разному влияет на поведение Claude.

Название события Момент срабатывания Основная функция
PreToolUse Вызов инструментаПеред Может перехватывать выполнение инструмента (например, предотвращать изменение конфиденциальных файлов) и передавать Claude предложения обратной связи
PermissionRequest Когда появляется диалоговое окно запроса разрешения Автоматически одобрять или отклонять запросы разрешений
PostToolUse Вызов инструментаПосле завершения Выполнять пост-операции (например, форматировать код, записывать логи)
UserPromptSubmit После того как пользователь отправляет промпт, но до того как Claude обработает его Предобрабатывать пользовательский ввод (например, дополнять контекстную информацию)
Notification Когда Claude отправляет уведомления Настраивать способы уведомления (например, всплывающие окна на рабочем столе, SMS-оповещения)
Stop Когда Claude завершает ответ Выполнять завершающую работу (например, очищать временные файлы)
SubagentStop Когда задача субагента завершается Обрабатывать результаты выполнения субагента
PreCompact Когда предстоит выполнить сжатие контекста Настраивать правила сжатия
SessionStart При запуске новой сессии или возобновлении старой сессии Инициализация окружения сессии (например, загрузка конфигурации проекта)
SessionEnd При завершении сессии Сохранение данных сессии, очистка окружения

Быстрый старт: реализация логирования команд

Ниже, используязапись всех Bash-команд, выполняемых Claude,в качестве примера, мы пошагово покажем, как настроить и использовать хуки.

Предварительные требования

Установкаjqинструмент (для разбора JSON-данных из командной строки):

Шаг 1: Откройте интерфейс настройки хуков

В интерактивном интерфейсе Claude Code введите слэш-команду/hooks, нажмите Enter, затем выберите событие для привязки — здесь мы выбираемPreToolUse(срабатывает перед вызовами инструментов, подходит для логирования команд).

Шаг 2: Добавьте сопоставитель событий

Роль матчера заключается в том, чтобыограничить условия срабатывания хука, выполняя команду хука только при вызове указанного инструмента.

  1. Выбор+ Add new matcher…
  2. Введите ключевое слово для сопоставленияBash, то есть хук срабатывает только тогда, когда Claude вызывает инструмент Bash.

    Совет: введите*может совпадать совсеми инструментами, позволяя включить глобальный хук.

Шаг 3: Добавьте команду хука

Выбор+ Add new hook…, введите следующую команду (функция: извлечь содержимое команды и описание, записать в лог-файл):

jq -r '"\(.tool_input.command) - \(.tool_input.description // "无描述信息")"' >> ~/.claude/bash-command-log.txt

Описание команды:

  • jq -r ...: Извлечь команду из JSON (command) и описание (description), выводить «нет информации об описании», если описания нет.
  • >> ~/.claude/...: Дописать содержимое в лог-файл в домашнем каталоге пользователя.

Шаг 4: Выбор места хранения конфигурации

Место сохранения конфигурации определяет область действия хука:

  • Пользовательские настройки: Сохранить в конфигурацию уровня пользователя (~/.claude/settings.json),действует для всех проектов
  • Настройки проекта: Сохранить в конфигурацию текущего проекта (.claude/settings.local.json),действует только для текущего проекта

Здесь мы выбираемUser settings, чтобы включить глобальное журналирование команд. После выбора нажмитеEscклавишу, чтобы выйти из интерфейса конфигурации, и хук зарегистрирован.

Шаг 5: Проверка конфигурации хука

  1. Введите снова/hooksкоманду, чтобы просмотреть список настроенных хуков
  2. или сразу откройте файл конфигурации~/.claude/settings.json, и вы увидите следующую конфигурацию:
    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"无描述信息\")\"' >> ~/.claude/bash-command-log.txt"
              }
            ]
          }
        ]
      }
    }

Шаг 6: Проверка работы хука

  1. Введите команду в Claude Code:帮我执行 ls 命令
  2. После выполнения просмотрите лог-файл в терминале:
    cat ~/.claude/bash-command-log.txt
  3. Если в логе появится следующее содержимое, значит хук успешно настроен:
    ls - Lists files and directories

Практические примеры хуков

Ниже приведены несколько часто используемых конфигураций хуков. Вы можете скопировать их напрямую или изменить по необходимости.

📌 Полный пример кода см. в официальном репозитории:bash command validator example

Пример 1: Автоматическое форматирование файлов TypeScript

Функция: После редактирования/записи.tsфайлов, автоматически использоватьprettierдля форматирования кода

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write", // 匹配“编辑”和“写入”工具
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Пример 2: Автоматическое исправление форматирования Markdown-файлов

Функция: Автоматически добавляет языковые теги к блокам кода, в которых их нет, и удаляет лишние пустые строки

Шаг 1: Добавьте конфигурацию хука

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
          }
        ]
      }
    ]
  }
}

Второй шаг: Создайте скрипт форматирования

В каталоге проекта создайте новый файл.claude/hooks/markdown_formatter.py, затем вставьте следующий код:

Примеры

#!/usr/bin/env python3
"""
Инструмент форматирования Markdown: автоматически добавляет языковые теги к блокам кода, удаляет лишние пустые строки
"""

import json
import sys
import re
import os

def detect_language(code):
    """Автоматически определяет язык программирования на основе содержимого кода"""
    code = code.strip()
    # Определить JSON
    if re.search(r'^\s*[{\[]', code):
        try:
            json.loads(code)
            return 'json'
        except:
            pass
    # Определить Python
    if re.search(r'^\s*def\s+\w+\s*\(', code, re.M) or re.search(r'^\s*(import|from)\s+\w+', code, re.M):
        return 'python'
    # Определить JavaScript/TypeScript
    if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', code) or re.search(r'=>|console\.(log|error)', code):
        return 'javascript'
    # Определить Bash
    if re.search(r'^#!.*\b(bash|sh)\b', code, re.M) or re.search(r'\b(if|then|fi|for|in|do|done)\b', code):
        return 'bash'
    # Формат текста по умолчанию
    return 'text'

def format_markdown(content):
    """Форматировать содержимое Markdown"""
    # Добавить язык к неразмеченным блокам кода
    fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
    def add_lang(match):
        indent, info, body, closing = match.groups()
        if not info.strip():
            lang = detect_language(body)
            return f"{indent}```{lang}\n{body}{closing}\n"
        return match.group(0)
    content = re.sub(fence_pattern, add_lang, content)
    # Убрать лишние пустые строки (только содержимое вне блоков кода)
    content = re.sub(r'\n{3,}', '\n\n', content)
    return content.rstrip() + '\n'

if __name__ == "__main__":
    try:
        # Прочитать JSON-данные, переданные Claude
        input_data = json.load(sys.stdin)
        file_path = input_data.get('tool_input', {}).get('file_path', '')
        # Обрабатывать только файлы .md/.mdx
        if not file_path.endswith(('.md', '.mdx')):
            sys.exit(0)
        # Прочитать и отформатировать файл
        if os.path.exists(file_path):
            with open(file_path, 'r', encoding='utf-8') as f:
                content = f.read()
            formatted_content = format_markdown(content)
            # Записывать только при изменении содержимого
            if formatted_content != content:
                with open(file_path, 'w', encoding='utf-8') as f:
                    f.write(formatted_content)
                print(f"Форматированный Markdown-файл: {file_path}")
    except Exception as e:
        print(f"Ошибка форматирования: {e}", file=sys.stderr)
        sys.exit(1)

Третий шаг: предоставить скрипту право на выполнение

chmod +x .claude/hooks/markdown_formatter.py

Пример 3: Отправка уведомлений на рабочем столе, когда Claude ожидает ввода

Функция: когда Claude нуждается во вводе пользователя, автоматически показывать напоминание на рабочем столе (работает в Linux/macOS)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "", // 匹配所有通知事件
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code 提示' '请你输入指令或确认权限'"
          }
        ]
      }
    ]
  }
}

Пример 4: Предотвращение изменения конфиденциальных файлов

Функция: запретить Claude редактировать.env、package-lock.jsonи другие конфиденциальные файлы

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

Примечание: когда скрипт возвращает код состояния2, Claude Code перехватит этот вызов инструмента, тем самым предотвратив изменение файла.


Справочное руководство по хукам Claude Code

Путь к файлу конфигурации

Уровень конфигурации Путь к файлу Область действия
Пользовательский уровень ~/.claude/settings.json Все проекты
Уровень проекта .claude/settings.json Текущий проект
Локальный уровень проекта (не закоммичен) .claude/settings.local.json Текущий проект, не включён в систему контроля версий
Уровень управляемой политики Путь, заданный администратором Единый корпоративный/командный контроль

Основная структура конфигурации

Хуки организованы пособытию + сопоставителю, поддерживаяcommand(выполнять команды Shell) иprompt(вызывать LLM для принятия решений), два типа.

{
  "hooks": {
    "【钩子事件名】": [
      {
        "matcher": "【工具匹配规则】", // 部分事件可省略
        "hooks": [
          {
            "type": "command/prompt",
            "command": "【Shell 命令】", // type=command 时必填
            "prompt": "【LLM 提示词】",  // type=prompt 时必填
            "timeout": 30 // 可选,超时时间(秒)
          }
        ]
      }
    ]
  }
}

Правила сопоставления (применимо только к событиям инструментов)

Правило сопоставления Пример Описание
Точное совпадение Write Сопоставлять толькоWritetool
Сопоставление нескольких инструментов Edit | Write СопоставлениеEditилиWritetools
Сопоставление по префиксу Notebook.* Сопоставлять все инструменты, начинающиеся сNotebookпрефикс
Полное совпадение */ пустая строка Сопоставление всех инструментов

Специальные советы по настройке

Сценарий Способ настройки Пример
Ссылка на скрипт внутри проекта Использование переменных среды$CLAUDE_PROJECT_DIR "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
Хуки плагина Настраивается внутри плагинаhooks/hooks.json, используя${CLAUDE_PLUGIN_ROOT}для ссылки на файлы плагина "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
Хуки уровня компонента (Skill/Agent) Определяются в frontmatter компонента, область действия ограничена жизненным циклом компонента См. нижеНастройка расширенияТаблица

Расширенная конфигурация (навыки/агенты/слэш-команды)

Конфигурация расширения позволяет встраивать хуки непосредственно в определение навыка, агента или пользовательской слэш-команды. Эти хуки вступают в силу только тогда, когда соответствующий компонент активирован и запущен, и автоматически удаляются после завершения выполнения компонента, не влияя на глобальную сессию.

Поддерживаемые события хуков

Поддерживает толькоPreToolUse、PostToolUse、Stopтри типа событий с той же функциональностью, что и глобальные хуки, но область действия ограничена жизненным циклом текущего навыка/слэш-команды.

Эксклюзивная опция конфигурации

  • once: true(необязательно): если установлено вtrue, этот хук выполняется только один раз за всю сессию и автоматически удаляется после первого успешного выполнения, чтобы избежать повторного срабатывания.

Полный пример конфигурации

---
# Skill/斜杠命令的基础信息
name: secure-operations
description: 执行Shell命令前先做安全校验的工具
# Hooks 配置段
hooks:
  PreToolUse:
    # 匹配器:仅拦截Bash工具调用
    - matcher: "Bash"
      hooks:
        - type: "command"
          # 要执行的安全校验脚本
          command: "./scripts/security-check.sh"
          # 会话内仅执行一次
          once: true
          # 超时时间(秒),避免脚本卡死
          timeout: 15
---

Конфигурация хуков в агенте

Поддерживаемые события хуков

Также поддерживает толькоPreToolUse、PostToolUse、StopТри типа событий, область действия которых ограничена только жизненным циклом выполнения задач этого субагента.

Специфические элементы конфигурации

Нет дополнительных эксклюзивных элементов конфигурации, не поддерживаетсяonce: true(Хуки срабатывают каждый раз, когда Агент выполняет задачу).

Полный пример конфигурации

---
# Agent 的基础信息
name: code-reviewer
description: 自动审查代码修改并运行代码检查的子代理
# Hooks 配置段
hooks:
  PostToolUse:
    # 匹配器:拦截Edit(编辑)或Write(写入)工具
    - matcher: "Edit|Write"
      hooks:
        - type: "command"
          # 代码检查脚本,执行lint校验
          command: "./scripts/run-linter.sh"
          # 超时时间(秒)
          timeout: 30
---

Примечания:

  1. Правила сопоставления для хуков уровня компонента точно такие же, как для глобальных хуков: поддерживается точное сопоставление (например,"Write"), сопоставление нескольких инструментов (например,"Edit|Write"), сопоставление по маске ("*"), а сопоставление чувствительно к регистру;
  2. Хуки уровня компонента и глобальные хуки выполняются параллельно: если и глобальные, и хуки уровня компонента настроены для одного и того же события, оба типа хуков запустятся вместе при срабатывании, не конфликтуя друг с другом;
  3. Требования к формату конфигурации: хуки уровня компонента должны быть записаны в frontmatter (---заключённую область), следуя синтаксису YAML; ошибки в отступах сделают конфигурацию недействительной;
  4. Рекомендации по путям к скриптам: предпочитайте относительные пути (например,./scripts/xxx.sh), или используйте$CLAUDE_PROJECT_DIRпеременная окружения для указания абсолютного пути, гарантирующая, что компонент сможет найти скрипт в любом каталоге.

События хуков -- События инструментов (поддерживается сопоставление)

Название события Момент срабатывания Общие сопоставители Основная цель
PreToolUse Вызов инструментадо Bash/Edit/Write/Read Перехватывать выполнение инструмента, изменять входные параметры, автоматически одобрять/отклонять разрешения
PermissionRequest Когда появляется диалоговое окно запроса разрешения то же самоеPreToolUse Автоматически обрабатывать запросы разрешений без ручного подтверждения пользователя
PostToolUse Вызов инструментапосле успеха то же самоеPreToolUse Выполнять пост-операции (например, форматирование кода, логирование)
Notification Когда Claude отправляет уведомление permission_prompt/idle_prompt/auth_success Настраивать способы уведомления (например, всплывающие окна на рабочем столе, оповещения по электронной почте)
PreCompact Перед выполнением сжатия контекста manual(Ручной триггер) /auto(Автоматический триггер) Настроить правила сжатия, создать резервную копию важного контекста

События хуков -- События сессии/задачи (без сопоставителя)

Название события Момент срабатывания Основная цель
UserPromptSubmit После того как пользователь отправляет промпт, но до того как Claude обработает его Проверить допустимость промпта, дополнить контекстную информацию
Stop Когда основной агент завершает ответ (не запускается прерыванием пользователя) Интеллектуально определить, продолжать ли выполнение задачи
SubagentStop Когда задача субагента завершается Оценить результаты подзадачи, решить, завершать ли
SessionStart При запуске/возобновлении сессии Инициализировать окружение, загрузить конфигурацию проекта, установить постоянные переменные окружения
SessionEnd При завершении сессии Очистка временных файлов, запись журналов сеанса, сохранение рабочего состояния

Сравнение типов хуков

Claude Code поддерживает два типа хуков для удовлетворения потребностей различных сценариев.

Характеристика commandТип (командный хук) promptТип (промпт-хук)
Способ выполнения Запуск команд/скриптов Shell Вызов LLM (модель Haiku по умолчанию) для интеллектуального принятия решений
Логика принятия решений На основе логики кода,детерминированное суждение На основе контекста,гибкое семантическое суждение
Сложность настройки Требуется написание скриптов, высокий порог входа Нужно только писать промпты, просто и удобно
Скорость отклика Быстро (локальное выполнение) Медленнее (требуются вызовы API)
Применимые сценарии Фиксированные правила, такие как форматирование кода, логирование, перехват разрешений Гибкие сценарии, такие как оценка завершения задачи, сложное определение намерения
Основная конфигурация command + timeout prompt + timeout(Можно ссылаться$ARGUMENTSплейсхолдеры)

Ввод и вывод -- Ввод хука (JSON передаётся через stdin)

Все хуки получают общие поля, а некоторые события включают специфические поля.

Тип поля Общее поле Описание
Основная информация session_id Уникальный идентификатор сессии
transcript_path Путь к файлу истории беседы
cwd Текущий рабочий каталог во время выполнения хука
permission_mode Текущий режим разрешений (default/plan/acceptEdits и т. д.)
hook_event_name Имя текущего вызванного события хука

Примеры полей, специфичных для каждого события

Название события Специфические поля Пример
PreToolUse tool_name/tool_input {"tool_name":"Write","tool_input":{"file_path":"/test.txt"}}
UserPromptSubmit prompt {"prompt":"帮我写一个排序函数"}
SessionEnd reason {"reason":"clear/logout/other"}

Вывод хука (два метода)

Метод 1: код выхода (простые сценарии)

Передавайте статус выполнения через код выхода,stdout/stderrИспользуется для предоставления информации обратной связи.

Код выхода Значение Описание поведения
0 Выполнение успешно stdoutМожет возвращать JSON для расширенного управления; некоторые события (например,UserPromptSubmit) добавятstdoutв контекст
2 Заблокировать операцию Использовать толькоstderrв качестве сообщения об ошибке, передаваемого обратно Claude,блокируя продолжение выполнения текущего события
Другие ненулевые значения Неблокирующая ошибка stderrОтображается только в подробном режиме (ctrl+o), не влияет на выполнение события

Поведение кода выхода 2 в каждом событии

Название события Поведение при срабатывании
PreToolUse Заблокировать вызов инструмента и показать Claudestderr
UserPromptSubmit Заблокировать обработку запроса, стереть ввод пользователя
Stop Заблокировать остановку Claude, принудительно продолжить работу
PostToolUse/Notification Только отображатьstderr, не влияет на завершённые операции

Способ 2: вывод JSON (расширенные сценарии)

Когда код выхода равен0, вы можетеstdoutвернуть JSON для точного управления. Основные поля следующие:

Общие поля JSON Назначение
continue: true/false Разрешать ли событию продолжать выполнение (falseимеет приоритет над другими правилами)
stopReason continue=falseПричина, показываемая пользователю, когда
systemMessage Предупреждающее сообщение, отображаемое пользователю

Примеры полей JSON, специфичных для событий

Название события Специфические поля Пример
PreToolUse permissionDecision(allow/deny/ask) {"hookSpecificOutput":{"permissionDecision":"allow","updatedInput":{"file_path":"/new.txt"}}}
UserPromptSubmit decision: block/undefined {"decision":"block","reason":"提示包含敏感信息"}
PostToolUse additionalContext {"hookSpecificOutput":{"additionalContext":"文件已格式化完成"}}

Конфигурация хуков для MCP-инструментов

MCP-инструменты можно легко интегрировать с хуками и сопоставлять по определённым правилам именования.

Правила именования MCP-инструментов

mcp__<服务器名>__<工具名>

Пример:mcp__github__search_repositories、mcp__filesystem__read_file

Примеры сопоставления

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*", // 匹配 memory 服务器的所有工具
        "hooks": [{"type": "command", "command": "echo '内存操作日志' >> log.txt"}]
      },
      {
        "matcher": "mcp__.*__write.*", // 匹配所有服务器的写操作工具
        "hooks": [{"type": "command", "command": "./validate-write.py"}]
      }
    ]
  }
}

Безопасность и отладка

Лучшие практики безопасности

Ключевые моменты безопасности Конкретные действия
Проверка входных данных Строго проверяйтеtool_inputпути к файлам и параметры команд в, чтобы предотвратить обход пути (например,../)
ссылки на переменные Используйте в командах Shell"$VAR"вместо$VAR, чтобы избежать инъекции параметров
Принцип наименьших привилегий Скриптам хуков следует предоставлять только необходимые разрешения; избегайте использованияsudoи других команд высокого риска
Исключите конфиденциальные файлы Перехватывать операции с.env、.gitи операции с ключевыми файлами
Проверка команд Перед регистрацией хука вручную выполните команду, чтобы проверить логику и убедиться в отсутствии вредоносного поведения.

Советы по отладке

Тип проблемы Шаги по устранению неполадок
Хук не срабатывает 1. Выполните/hooksкоманду, чтобы проверить, зарегистрирована ли конфигурация<br>2. Убедитесь, что синтаксис JSON корректен<br>3. Проверьте, соответствует ли правило matcher имени инструмента (с учетом регистра)
Не удалось выполнить команду 1. Вручную запустите команду хука, чтобы убедиться, что она выполняется правильно<br>2. Проверьте, имеет ли скрипт права на выполнение (chmod +x script.sh)<br>3. Используйте абсолютный путь для вызова скрипта, чтобы избежать проблем с переменными окружения
Просмотреть подробные логи Добавьте при запуске Claude Code--debugпараметр для просмотра всего процесса выполнения хука

Справочная документация: полное описание функции хуков см. в официальнойсправочной документации по хукам。

Другие расширения