Устранение неполадок мода
Узнайте, почему мод Claude Code ничего не делает: сопоставьте симптом или сообщение с его причиной, посмотрите сообщения об отказе и прочитайте лог отладки.
Когда модуль мода или один из его хуков дает сбой, Claude Code пропускает его и сессия продолжается, поэтому неработающий мод может выглядеть как мод, который ничего не делает. Начните с проверки того, что Claude Code прочитал из вашего мода и где он сообщает о проблеме, затем найдите симптом или сообщение, которое у вас есть.
Узнайте, почему мод ничего не делает
Когда мод ничего не делает, проверьте, что 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 в вашей оболочке из директории, которая не содержит мода. Вам не нужен сеанс. Сообщение, которое оно печатает, говорит вам о состоянии:
| Сообщение включает | Что это означает |
|---|---|
no hooks module to load |
Моды могут загружаться. Команда не нашла мода для тестирования в этой директории. |
hooks modules are turned off here |
Настройка препятствует вашим модам: disableAllHooks в ваших собственных настройках или политика вашей организации |
hooks modules are turned off in this process: the rollout switch served off |
Anthropic отключила установленные моды удаленно. |
hooks modules are turned off in this process: the rollout switch was saved off by an earlier session |
Команда использовала значение, сохраненное более ранней сессией, которое может быть устаревшим. Запустите claude один раз, чтобы обновить его, затем снова выполните команду. |
Организация также может установить allowManagedModsOnly, чтобы разрешить только свои моды, что эта команда не сообщает. В этом случае 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: в журнале отладки.
| Сообщение начинается с | Что это означает |
|---|---|
hooks modules are turned off for installed plugins in this process: the rollout switch served off |
Anthropic отключила установленные моды удаленно. |
hooks modules are turned off for installed plugins in this process: the rollout switch was saved off by an earlier session |
Сессия использовала значение, сохраненное более ранней сессией, которое может быть устаревшим. Запустите Claude Code снова, чтобы обновить его. |
disableAllHooks in managed settings |
Ваша организация отключила hooks из установленных плагинов |
only managed plugins and built-in plugins run |
allowManagedHooksOnly установлен или disableAllHooks установлен в файле параметров, отличном от управляемых параметров |
installed plugins that are not managed load no hooks module in this mode (--bare) |
Вы запустили Claude Code с --bare |
another plugin of that name loads first |
Два плагина имеют одно имя. Используется управляемый или загруженный первым. |
Сообщения от встроенной защиты
На машине с управляемыми параметрами или для пользователя, вошедшего в систему с планом Team или Enterprise, встроенная защита может отказать моду или одному из его ответов. Каждое сообщение называет опцию, которую администратор вашей организации устанавливает для изменения правила.
| Сообщение содержит | Что это означает | Где оно появляется |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
Ваша организация разрешает только свои моды, поэтому ваш был отклонен | Лог отладки, а также транскрипт в сессии, которая выполняет горячую перезагрузку директории плагина |
tried to lift a deny rule in your settings |
Hook вашего мода tool.check одобрил вызов, который правило deny отказывает. Вызов остается отказанным. |
Стенограмма и журнал отладки, один раз для каждого мода в сеансе. В запуске claude -p только журнал отладки. |
the deny rules in your settings could not be checked for this call, so it is refused |
Защита не прошла при проверке вызова, который одобрил мод, поэтому она отказала вызову | Причина, которую Claude читает для отказанного вызова |
`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. Хук выбросил исключение, превысил свое ограничение по времени или вернул результат неправильной формы. Строка появляется один раз для каждого события и вида сбоя до перезагрузки мода.
Исправьте ошибку. Журнал отладки имеет строку для каждого возникновения.
`no command.run hook answered it`
Вы запускаете команду, которую добавил ваш мод, и ответ называет мод и команду, как в first-mod registered /tally but no command.run hook answered it, затем говорит вам добавить hook. Claude Code выводит этот ответ, когда команда достигает конца цепи без ответа, что происходит в двух случаях:
- Ни один hook не ответил на команду: модуль не имеет
command.runhook, фильтр hook называет другую команду или hook вернулnext(e) - Claude Code пропустила hook:
hook skippedперечисляет причины. Передачаfocus: falseв$.ui.open— один из способов туда попасть.
Если модуль уже имеет hook, который описывает ответ, ищите строку hook skipped, которая называет command.run, что дает причину. Тест, который запускает команду, не проходит по той же причине.
`it crashed the hooks worker`
Строка начинается с имени мода, как в first-mod was unloaded: it crashed the hooks worker. Установленные моды используют один рабочий поток. Рабочий перестал отвечать или упал, и Claude Code проследила это до этого мода и выгрузила его. Hook, который блокирует поток, например цикл, который никогда не ожидает, является одной из причин.
Исправьте hook.
`its session.start ran again in a fresh copy`
Строка начинается с имени мода и называет вызов $.prompt.submit, $.command.run или $.agent.spawn, как в first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again. Claude Code снова загрузила модуль мода, например после того как рабочий поток хуков упал и был заменен, и в свежей копии выполнился хук session.start. Вызов, названный в строке, вернул результат своего первого выполнения вместо повторного выполнения, поэтому ваш мод не отправляет промпт, не запускает команду и не запускает субагента дважды. Остальная часть хука выполнилась как обычно.
Исправлять ничего не нужно.
До v2.1.292 вызов выполнялся второй раз, поэтому промпт отправлялся, команда запускалась или субагент запускался дважды.
`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
Дерево, которое вернул ваш хук, не прошло валидацию. С --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 с той же причиной.
Прочитайте причину на этой строке. Частые причины - это проп, который элемент не принимает, и элемент, которого нет в приложении.
`the module failed without a message`
Client завершился с ошибкой без сообщения, например throw new Error(). Строка на его месте выглядит как my-mod: Client client/spinner.js: the module failed without a message.
Найдите throw в коде вашего Client и задайте ошибке сообщение. Тогда строка покажет это сообщение.
До v2.1.289 строка вместо этого показывала Error в качестве причины.
`$.ui.open` работает и панель не появляется
Вызов не поступил от чего-то, что сделал пользователь, и терминал уже, чем ширина, необходимая этой панели.
Откройте панель из команды или кнопки или проверьте результат 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 загружает или отклоняет, для каждого хука, завершившегося сбоем, и для каждого отклонённого результата, поэтому именно туда стоит смотреть, когда транскрипт ничего не показывает. Чтобы записать лог, запустите Claude Code в оболочке с --debug или с --debug-file <path>, чтобы выбрать место назначения:
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
В другом терминале следите за файлом и фильтруйте по имени вашего мода:
tail -f ./mod-debug.log | grep first-mod
Для загруженного мода есть строка, в которой указано его имя и перечислены события, которые он обрабатывает. Мод, загруженный с --plugin-dir, отображается под своим именем, за которым следует @inline:
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
Рисунок, который не прошёл валидацию, считается отклонённым результатом и тоже получает строку. Чтобы записать собственные строки в лог, вызовите $.ui.log со вторым аргументом, как в $.ui.log('message', { to: 'debug' }). Без второго аргумента $.ui.log добавляет тусклую строку в транскрипт.
Пока вы редактируете мод, загруженный с --plugin-dir, транскрипт показывает строку для каждой перезагрузки, в которой указано имя мода и перечислены его хуки. Если после сохранения модуль ломается, в строке выводится reload failed, the previous version stays loaded: с причиной, а последняя рабочая версия продолжает работать до следующей перезагрузки плагинов в Claude Code, например когда вы запускаете /reload-plugins.
Следующие шаги
- Протестируйте мод: ловите проблемы до того, как они достигнут сеанса
- Устранение неполадок плагинов: проблемы с установкой и загрузкой плагина, которые не специфичны для модов