Узнайте, почему мод ничего не делает
Когда мод ничего не делает, две проверки находят причину: что Claude Code читает из файлов мода и строку, которую он пишет, когда что-то пропускает. Для первого запуститеclaude plugin validate в вашей оболочке с директорией мода, как в claude plugin validate ./first-mod. Это ловит неправильно написанное событие, неправильный манифест и модуль, который Claude Code не может прочитать, без запуска сеанса.
Когда модуль не загружается, hook пропускается или другой мод отказывает вашему, Claude Code пишет одну строку, которая называет ваш мод. Где вы читаете эту строку, зависит от сеанса:
- Сеанс, который горячо перезагружает директорию плагина: тусклая строка в стенограмме. Это интерактивный сеанс, который вы запустили с
--plugin-dir, или сеанс, где вы включили горячую перезагрузку для модов, которые написал Claude. - Любой другой интерактивный сеанс, например тот, который запускает мод, установленный вами из маркетплейса: журнал отладки только. Чтобы получить его, запустите сеанс с
claude --debug. - Запуск
claude -pс--plugin-dir: stderr в формате вывода текста по умолчанию. Отказ другого мода идет только в журнал отладки.
Проверьте, могут ли загружаться моды
Чтобы проверить, позволяет ли ваша установка вообще загружать моды, без установки одного, запуститеclaude plugin test в вашей оболочке из директории, которая не содержит мода. Вам не нужен сеанс. Сообщение, которое оно печатает, говорит вам о состоянии:
Организация также может установить
allowManagedModsOnly, чтобы разрешить только свои моды, что эта команда не сообщает. В этом случае мод, который вы устанавливаете, не загружается, и сообщение говорит почему.
Мод не загружается
Ничего, что добавляет мод, не появляется: нет команды, нет рисунка и нет изменения в поведении.Ваша версия старше 2.1.287
claude --version печатает версию старше 2.1.287. Ваша версия предшествует тому, как моды были включены по умолчанию.
Обновите Claude Code.
Строка mods active не называет мод
Ничего, что добавляет мод, не появляется, и строка mods active в /plugin не называет его. Модуль hooks не загрузился. Когда Claude Code отказала ему, журнал отладки имеет строку, которая начинается с hooks module, имени мода и not loaded:, как в hooks module first-mod@inline not loaded: disableAllHooks in managed settings для мода, загруженного с --plugin-dir.
Прочитайте причину после двоеточия. Раздел сообщения об отказе перечисляет каждое. Если журнал не имеет такой строки, пройдите через другие записи в этой группе.
Запуск claude -p печатает hooks module not loaded
Строка начинается с имени мода и идет в stderr. Модуль hooks был отказан. Неинтерактивный запуск не имеет стенограммы, поэтому сообщение идет в stderr.
Прочитайте причину после двоеточия. Раздел сообщения об отказе перечисляет каждое.
Сообщения об отказе
Каждое из них следует заhooks module, именем мода и not loaded: в журнале отладки.
Сообщения от встроенной защиты
На машине с управляемыми параметрами или для пользователя, вошедшего в систему с планом Team или Enterprise, встроенная защита может отказать моду или одному из его ответов. Каждое сообщение называет опцию, которую администратор вашей организации устанавливает для изменения правила.validate проходит и не перечисляет строку hooks
hooks/hooks.json не имеет ключа modules или ключ неправильно написан.
Добавьте "modules": ["./register.js"].
hooks module did not load
Строка начинается с имени мода, затем hooks module did not load: и причина, которая дает файл и строку, когда проблема в вашем коде. Claude Code не смогла загрузить модуль, например потому что его код верхнего уровня выбросил.
Исправьте ошибку, которую называет причина.
options do not fit plugin.json userConfig
Строка начинается с имени мода, затем hooks module did not load: options do not fit plugin.json userConfig: и причина. Опция не подходит к своему полю userConfig, например число выше max поля или обязательное поле не имеет значения.
Установите или измените значение. Конец строки называет его запись pluginConfigs в settings.json.
Ни один мод не загружается в директории, которую вы открыли впервые
Вы не ответили на приглашение доверия для директории. Запустите интерактивный сеанс в этой директории сclaude и примите приглашение доверия, которое оно открывает.
Ни один установленный плагин не загружается вообще
Вы запустили Claude Code с--safe-mode.
Запустите без флага.
Hook пропускается или мод выгружается
Мод загрузился, а затем Claude Code пропустила один из его hooks или выгрузила его.hook skipped
Строка называет мод и событие, затем говорит hook skipped: и причину, как в first-mod: tool.call hook skipped: threw Error: boom. Hook выбросила, прошла мимо своего 10-секундного ограничения по времени или вернула результат неправильной формы. Строка появляется один раз для каждого события и вида отказа до перезагрузки мода.
Исправьте ошибку. Журнал отладки имеет строку для каждого возникновения.
it crashed the hooks worker
Строка начинается с имени мода, как в first-mod was unloaded: it crashed the hooks worker. Установленные моды используют один рабочий поток. Рабочий перестал отвечать или упал, и Claude Code проследила это до этого мода и выгрузила его. Hook, который блокирует поток, например цикл, который никогда не ожидает, является одной из причин.
Исправьте hook.
mods that run in the hooks worker are off for this session
Строка читает hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Рабочий остановился три раза и Claude Code не смогла проследить остановки до одного мода, поэтому она выгрузила каждый мод, который не встроен, включая моды, которые устанавливает ваша организация. Эта строка достигает стенограммы в каждом интерактивном сеансе.
Запустите /reload-plugins для их перезагрузки.
Вызов инструмента отказан
Мод загрузился и его hooks работают, и вызов инструмента, который он коснулся, отказан.a hook changed this call's input after the model wrote it
В автоматическом режиме отказанный вызов инструмента дает эту причину. Hook изменила входные данные вызова инструмента после того, как классификатор на стороне сервера его рассмотрел, поэтому этот обзор не охватывает то, что будет запущено. Hook может быть tool.call мода или turn.step hook или PreToolUse hook параметров. Сообщение не говорит, какой.
Сообщение говорит Claude выдать вызов еще раз, как записано. Если это также отказано, hook изменяет входные данные каждый раз, поэтому отключите мод или hook или выйдите из автоматического режима и одобрите вызов сами.
Сообщение о правилах deny в ваших параметрах
tried to lift a deny rule in your settings и the deny rules in your settings could not be checked for this call, so it is refused оба поступают от встроенной защиты.
Посмотрите их в Сообщения от встроенной защиты.
Рисунок не появляется или не отвечает
Мод загрузился, и его панель, полоса или элементы управления не ведут себя так, как вы ожидаете.Панель или полоса пуста или показывает обычное содержимое Claude Code
Дерево, которое вернула ваша hook, не прошло валидацию. С--plugin-dir стенограмма говорит ui.render (Pane) refused: с причиной, как в first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. Журнал отладки имеет a hook returned a tree that does not validate с той же причиной.
Прочитайте причину на этой строке. Частые причины - это свойство, которое элемент не принимает, и элемент, который приложение не имеет.
$.ui.open работает и панель не появляется
Вызов не поступил от чего-то, что сделал пользователь, и терминал уже, чем 144 столбца.
Откройте панель из команды или кнопки или проверьте результат isPlaced вызова. См. Откройте панель в нужное время.
Горячие клавиши ничего не делают
Ваша панель не имеет фокуса клавиатуры. Нажмите Ctrl+X затем Tab или щелкните панель. Откройте ее сfocus: true из команды.
Рисунок работает в терминале и не в приложении Desktop
Сайт или элемент там недоступны. Проверьте таблицы сайтов рендеринга и элементов.Редактирование или значение потеряно
Мод работает, и изменение, которое вы сделали, или значение, которое оно сохранило, отсутствует.Ваши редактирования не вступают в силу
Вы редактируете плагин, который установили. Claude Code запускает кэшированную копию для установленной версии. Разрабатывайте с--plugin-dir, указывающим на вашу рабочую копию, как в claude --plugin-dir ./first-mod, которая перезагружается при сохранении.
Значение сбрасывается при перезагрузке модуля
Переменные уровня модуля переинициализируются при каждой перезагрузке. Сохраняйте значение в$.state или $.store.
Значение сбрасывается после /clear, /resume или /branch
Значение сбрасывается или сохраненное значение заменяется его значением по умолчанию. Каждая из этих команд сбрасывает $.state на его значения по умолчанию, и session.start не срабатывает снова.
Загрузите сохраненное значение снова в hook classic.SessionStart.
Прочитайте журнал отладки
Журнал отладки имеет строку для каждого модуля, который Claude Code загружает или отказывает, каждого hook, который дает сбой, и каждого результата, который она отказывает, поэтому это место для поиска, когда стенограмма ничего не показывает. Чтобы написать один, в вашей оболочке запустите Claude Code с--debug или с --debug-file <path> для выбора места назначения:
--plugin-dir, появляется под его именем, за которым следует @inline:
$.ui.log со вторым аргументом, как в $.ui.log('message', { to: 'debug' }). Без второго аргумента $.ui.log добавляет тусклую строку в стенограмму.
Пока вы редактируете мод, загруженный с --plugin-dir, стенограмма показывает строку для каждой перезагрузки, которая называет мод и перечисляет его hooks. Если сохранение нарушает модуль, строка говорит reload failed, the previous version stays loaded: с причиной, и последняя рабочая версия продолжает работать.
Следующие шаги
- Протестируйте мод: ловите проблемы до того, как они достигнут сеанса
- Устранение неполадок плагинов: проблемы с установкой и загрузкой плагина, которые не специфичны для модов