Claude Code Hooks не выполняются на удалённом Mac? Руководство по диагностике 2026

Вывод для диагностики

В документации Claude Code код завершения Hook 2 описан как блокирующая ошибка. Поэтому сначала проверьте событие и matcher, затем запуск скрипта и SSH-среду, а после — код завершения и результат Hook; не отключайте контроль разрешений в попытке «починить» выполнение. Описание кодов завершения и результата Hook

Подходит: разработчикам, которые работают с Claude Code на удалённом Mac по SSH, и инженерам, поддерживающим общие Hook-настройки проекта.
Также подойдёт: тем, кому нужно запускать на macOS проверки, форматирование, тесты или сборку.
Не подойдёт: если задача — настроить Claude Code с нуля, выбрать модель или разобрать установку инструмента: здесь рассматривается именно цепочка отказа Hook.

Когда Claude Code Hooks на удалённом Mac не выполняются, сначала определите, что именно не произошло: событие не наступило, matcher не подошёл, команда не стартовала или скрипт отработал, но не дал ожидаемого эффекта. Запишите версию Claude Code, способ запуска сессии и точные действия для воспроизведения. Такая запись позволяет сравнивать результаты, не меняя настройки наугад.

Как отличить отсутствие события от неудачного результата?

Почему Claude Code Hooks не срабатывают? Причину стоит искать по этапам: проверьте, произошло ли событие, подходит ли ему matcher, запускается ли команда и что она возвращает. Наличие записи в настройках само по себе не подтверждает, что конкретное действие вызвало этот Hook.

В справочнике событий и типов Hook сверьте выбранное событие с действием, которое вы выполняете. Если конфигурация ожидает запуск при использовании инструмента, но проверка происходит при завершении сессии, тест не проверяет нужный сценарий. Отдельно убедитесь, что matcher соответствует фактически используемому инструменту или другому объекту сопоставления: название события и условие выбора решают разные задачи.

Чтобы исключить побочные эффекты, временно замените полезную команду простой диагностикой. Например, используйте короткий скрипт, который записывает отметку запуска и текущий каталог в отдельный временный файл. В тестовой конфигурации укажите событие и matcher, соответствующие реальному действию; точный формат проверьте по официальному примеру настройки Hook. Если запись не появилась, переходите к проверке загрузки настройки, совпадения matcher и доступности команды. Если появилась — событие и запуск уже подтверждены, и нужно анализировать результат полезного скрипта.

Не смешивайте настройки пользователя и проекта. В документации по настройкам описаны файлы конфигурации и их область действия. Проверьте, откуда запущена сессия, какой проект открыт и какой файл настроек должен применяться. Для проверки загруженных Hook используйте встроенную команду /hooks, а не предположение, что нужный файл автоматически подхвачен. Синтаксис команды и её назначение можно сверить в справочнике команд Claude Code.

Сравните этапы отказа

Это диагностическая развилка, а не утверждение о внутреннем состоянии конкретной установки. Фиксируйте фактическое наблюдение на каждом этапе: оно сужает область поиска и снижает риск исправить не ту причину.

Первая проверка: скрипт, путь и права

Как проверить права Hook и рабочий каталог? Проверяйте именно удалённый компьютер, из той учётной записи и проекта, где запускается Claude Code. Успешный запуск из локального терминала не доказывает, что удалённая сессия видит тот же путь или файл.

На удалённом Mac откройте SSH-сеанс и выполните проверки для фактического файла:

pwd
ls -l /полный/путь/к/hook.sh
head -n 1 /полный/путь/к/hook.sh
test -x /полный/путь/к/hook.sh && echo "executable" || echo "not executable"

Замените путь на значение из конфигурации. Убедитесь, что файл существует, первая строка указывает на доступный интерпретатор, а команда проверки исполнения проходит. Если Hook запускается через интерпретатор явно, например sh /path/to/script.sh, проверьте, что путь в настройке соответствует этому способу запуска; не переносите предположения о правах на иной вариант вызова.

Минимальный файл для проверки может выглядеть так:

#!/bin/sh
printf 'hook started; cwd=%s\n' "$PWD" >> /tmp/claude-hook-check.log

После сохранения запустите его вручную тем же способом, который указан в Hook, затем выполните действие Claude Code, способное вызвать соответствующее событие, и проверьте файл журнала:

tail -n 5 /tmp/claude-hook-check.log

Этот тест показывает только то, что команда была вызвана и смогла записать данные. Он не подтверждает, что ваш форматтер, тестовый раннер или сборка доступны, что результат Hook интерпретирован ожидаемым образом или что тестовая запись будет видна в диалоге. После диагностики удалите временный файл и тестовую настройку, если они больше не нужны.

Сверьте структуру настройки, тип Hook и способ передачи входных данных с официальным руководством по Hook. Не добавляйте в конфигурацию несуществующие поля по аналогии с чужими примерами: неверная структура может скрыть простую ошибку сопоставления.

SSH-среда и рабочий каталог: проверка различий

Почему после SSH подключения Hook не находит команду? Запуск из интерактивного терминала и запуск Hook могут получить разные значения PATH, переменные окружения и текущий каталог. Сравните фактические значения в обоих случаях, прежде чем менять путь к инструменту или переустанавливать пакет.

Сначала выполните эти команды в терминале SSH:

printf 'PATH=%s\n' "$PATH"
printf 'HOME=%s\n' "$HOME"
pwd
command -v brew
command -v git

Затем добавьте временную запись тех же значений в диагностический скрипт Hook и сравните результаты. Если command -v возвращает путь в SSH-терминале, но не в диагностике Hook, проблема относится к окружению запуска, а не обязательно к отсутствию программы на Mac.

Для проверки переменных среды Claude Code используйте официальные имена и назначение переменных. Не предполагайте, что Hook наследует каждый параметр интерактивной оболочки: фиксируйте только те значения, от которых зависит ваш скрипт. Для важной команды укажите проверенный абсолютный путь или явно сформируйте необходимый PATH внутри скрипта; перед этим убедитесь, что путь существует на целевой машине.

Рабочий каталог проверяйте отдельно. Команда pwd внутри Hook должна показать каталог, из которого сценарий действительно выполняется. Если скрипт рассчитывает на относительный путь вроде ./scripts/check.sh, такой путь может указывать не туда, когда запуск происходит из другого каталога. Используйте путь, определённый относительно корня проекта надёжным способом, либо сначала явно переходите в каталог проекта, который вы проверили в этой сессии.

Именно поэтому успешный тест в локальной оболочке недостаточен для удалённого Mac: он не подтверждает ни совпадение PATH, ни рабочую директорию, ни доступ к проектным файлам в контексте Hook.

Когда команда стартует, но результата нет

После подтверждённого запуска проверьте отдельно стандартный вывод, поток ошибок и код завершения. Ошибка самого скрипта и обработка результата Claude Code — разные участки цепочки. В официальном описании Hook код 2 относится к блокирующей ошибке; другие исходы нужно трактовать согласно документации для выбранного события, а не переносить поведение одного события на другое.

Где искать причину сбоя Hook? Сначала проверьте вывод скрипта и его код завершения, затем включите предусмотренную документацией отладку Claude Code и сопоставьте запись журнала с точным действием. В инструкции по отладке конфигурации описаны диагностические средства; следуйте актуальному формату запуска из этой инструкции.

При анализе лога отвечайте на конкретные вопросы: зарегистрировано ли нужное событие, какой Hook был выбран, какую команду пыталась запустить система и что завершило её выполнение? Не считайте отсутствие текста в диалоге доказательством того, что скрипт не запускался: проверка может оставить след в журнале, не показывая ожидаемое сообщение в разговоре. Если диагностика выявляет секреты или внутренние пути, не публикуйте журнал целиком; удалите чувствительные значения перед передачей коллегам.

Для разделения ошибок временно направьте stdout и stderr в разные диагностические файлы или явно выведите статус команды в оболочке. После теста верните обычную настройку: постоянное журналирование может сохранять данные проекта, которых нет необходимости хранить. Не расширяйте разрешения, чтобы заставить Hook работать: сверяйте нужный способ подтверждения с документацией по безопасности и настройкам разрешений.

Порядок повторной проверки на macOS

Используйте последовательность ниже, чтобы изменения оставались обратимыми и можно было установить, какой именно шаг устранил неисправность:

1. Запишите версию Claude Code, тип сессии, проект, действие для воспроизведения и активный файл настроек. Не меняйте сразу конфигурацию, права и окружение одновременно.
2. Через /hooks проверьте, загружена ли нужная запись. Сверьте имя события и matcher с действием и инструментом; если запись не загружена, устраните проблему настройки до проверки скрипта.
3. Запустите минимальный безопасный Hook, который оставляет диагностическую отметку. Подтвердите, что запуск произошёл, и проверьте фактический каталог.
4. На удалённом Mac проверьте путь, интерпретатор, права и доступность команды от той учётной записи, которая открывает сессию. Затем сравните PATH и необходимые переменные SSH-терминала и Hook.
5. Включите отладочную информацию по официальной инструкции и изучите код завершения, stdout и stderr. Убедитесь, что интерпретируете результат для нужного события.
6. Только после диагностики выполните проектную проверку: сначала форматирование или тест без разрушительных действий, затем сборку. Удалите временные настройки и проверьте, что нормальный сценарий проекта остался неизменным.

Начинайте с команды, которая не удаляет файлы, не отправляет данные наружу и не меняет состояние проекта. Перед добавлением автоматических действий просмотрите их побочные эффекты, пределы разрешений и обращение с секретами. Hook — исполняемый код, поэтому его конфигурация и безопасность остаются ответственностью команды; наличие удалённого Mac не делает произвольные команды безопасными. Эти границы подробно описаны в руководстве по безопасности Claude Code.

Если проблема проявляется только на удалённом хосте, зафиксируйте различия между локальной оболочкой и SSH-сеансом, а не подменяйте проверку отключением ограничений. Если локальный Mac уже обеспечивает нужный инструментальный набор и не требует постоянной доступности, удалённый хост может быть лишним. Но когда локальная машина выключается, её ресурсы заняты или проекту нужен постоянно доступный macOS-инструментарий, удалённая среда помогает отделить работу от личного компьютера. При выборе сравните условия удалённого доступа и владения машиной в сравнении вариантов работы с Mac, а сведения о вариантах размещения проверьте на странице размещения в Японии.

Сначала пройдите диагностику в уже доступной среде. Если после этого проекту всё же нужен длительно доступный Mac для проверок, сборок или тестов, аренда у OakVM может быть практичнее покупки отдельной машины для временной или проектной нагрузки. Она не заменит локальный Mac там, где необходимы физические интерфейсы или постоянная работа с устройством; если же вам нужен именно удалённый macOS-хост, уточните детали через контакты OakVM.