> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# mod 문제 해결

> Claude Code mod이 작동하지 않는 이유를 파악합니다: 증상이나 메시지를 원인과 일치시키고, 거부 메시지를 조회하며, 디버그 로그를 읽습니다.

mod의 모듈이나 해당 hook 중 하나가 실패하면 Claude Code는 이를 건너뛰고 세션이 계속되므로, 손상된 mod은 아무것도 하지 않는 것처럼 보일 수 있습니다. Claude Code가 mod에서 읽은 내용과 문제를 보고하는 위치를 확인하여 시작한 다음, 발생한 증상이나 메시지를 찾습니다.

<h2 id="find-out-why-a-mod-does-nothing">
  mod이 아무것도 하지 않는 이유 파악
</h2>

mod이 아무것도 하지 않을 때, 두 가지 확인으로 이유를 찾을 수 있습니다: Claude Code가 mod의 파일에서 읽은 내용과 무언가를 건너뛸 때 작성하는 줄입니다. 첫 번째의 경우, 셸에서 [`claude plugin validate`](/docs/ko/plugins/mods/create#check-what-claude-code-reads-from-your-mod)를 mod의 디렉터리와 함께 실행합니다(예: `claude plugin validate ./first-mod`). 이는 세션을 시작하지 않고도 잘못된 이벤트, 잘못된 manifest, Claude Code가 읽을 수 없는 모듈을 포착합니다.

모듈이 로드되지 않거나, hook이 건너뛰어지거나, 다른 mod이 귀사의 mod을 거부할 때, Claude Code는 귀사의 mod의 이름을 지정하는 한 줄을 작성합니다. 해당 줄을 읽는 위치는 세션에 따라 다릅니다:

* **플러그인 디렉터리를 핫 리로드하는 세션**: 트랜스크립트의 흐린 줄입니다. 이는 `--plugin-dir`로 시작한 대화형 세션이거나, Claude가 작성한 mod에 대해 [핫 리로딩을 활성화](/docs/ko/plugins/mods/create#ask-claude-for-a-mod)한 세션입니다.
* **마켓플레이스에서 설치한 mod을 실행하는 것과 같은 다른 모든 대화형 세션**: [디버그 로그](#read-the-debug-log)만 해당합니다. 하나를 얻으려면 `claude --debug`로 세션을 시작합니다.
* **`--plugin-dir`을 사용한 `claude -p` 실행**: stderr, 기본 텍스트 출력 형식입니다. 다른 mod의 거부는 디버그 로그로만 이동합니다.

<h2 id="check-whether-mods-can-load">
  mod이 로드될 수 있는지 확인
</h2>

설정이 mod을 로드할 수 있는지 확인하려면 mod을 설치하지 않고도 셸에서 `claude plugin test`를 실행합니다(mod을 보유하지 않은 디렉터리에서). 세션이 필요하지 않습니다. 인쇄되는 메시지는 상태를 알려줍니다:

| 메시지 포함 | 의미 |
| :- | :- |
| `no hooks module to load` | mod을 로드할 수 있습니다. 명령이 이 디렉터리에서 테스트할 mod을 찾지 못했습니다. |
| `hooks modules are turned off here` | 설정이 mod을 차단하고 있습니다: 자신의 설정에서 `disableAllHooks` 또는 조직의 정책 |
| `hooks modules are turned off in this process` | Anthropic이 설치된 mod을 원격으로 비활성화했습니다. 컴퓨터의 어떤 설정도 이를 다시 켤 수 없습니다. |

조직은 또한 `allowManagedModsOnly`를 설정하여 자신의 mod만 허용할 수 있으며, 이 명령은 이를 보고하지 않습니다. 이 경우 설치한 mod이 로드되지 않으며, [메시지가 이유를 설명합니다](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard).

<h2 id="the-mod-doesn’t-load">
  mod이 로드되지 않음
</h2>

mod이 추가하는 것이 아무것도 나타나지 않습니다: 명령, 그리기, 동작 변화가 없습니다.

<h3 id="your-version-is-older-than-2-1-287">
  버전이 2.1.287보다 오래됨
</h3>

`claude --version`은 2.1.287보다 오래된 버전을 인쇄합니다. 버전이 mod이 기본적으로 켜지기 전의 것입니다.

[Claude Code 업데이트](/docs/ko/setup#update-claude-code).

<h3 id="the-mods-active-line-doesn’t-name-the-mod">
  `mods active` 줄이 mod의 이름을 지정하지 않음
</h3>

mod이 추가하는 것이 아무것도 나타나지 않으며, `/plugin`의 [`mods active` 줄](/docs/ko/plugins/mods/overview#see-which-mods-a-session-loaded)이 이를 이름 지정하지 않습니다. hooks 모듈이 로드되지 않았습니다. Claude Code가 이를 거부했을 때, 디버그 로그에는 `hooks module`, mod의 이름, `not loaded:`로 시작하는 줄이 있습니다(예: `--plugin-dir`로 로드된 mod의 경우 `hooks module first-mod@inline not loaded: disableAllHooks in managed settings`).

콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다. 로그에 그러한 줄이 없으면 이 그룹의 다른 항목을 통해 작업합니다.

<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">
  `claude -p` 실행이 `hooks module not loaded` 인쇄
</h3>

줄은 mod의 이름으로 시작하여 stderr로 이동합니다. hooks 모듈이 거부되었습니다. 비대화형 실행에는 트랜스크립트가 없으므로 메시지는 stderr로 이동합니다.

콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다.

<h3 id="refusal-messages">
  거부 메시지
</h3>

각각은 디버그 로그에서 `hooks module`, mod의 이름, `not loaded:` 뒤에 옵니다.

| 메시지 시작 | 의미 |
| :- | :- |
| `hooks modules are turned off for installed plugins in this process` | Anthropic이 설치된 mod을 원격으로 비활성화했습니다. 컴퓨터의 어떤 설정도 이를 다시 켤 수 없습니다. |
| `disableAllHooks in managed settings` | 조직이 설치된 플러그인의 hook을 비활성화했습니다 |
| `only managed plugins and built-in plugins run` | `allowManagedHooksOnly`가 설정되었거나 관리되는 설정이 아닌 설정 파일에서 `disableAllHooks`가 설정되었습니다 |
| `installed plugins that are not managed load no hooks module in this mode (--bare)` | `--bare`로 Claude Code를 시작했습니다 |
| `another plugin of that name loads first` | 두 플러그인이 이름을 공유합니다. 관리되는 것 또는 먼저 로드된 것이 사용됩니다. |

<h3 id="messages-from-the-built-in-guard">
  기본 제공 가드의 메시지
</h3>

관리되는 설정이 있는 컴퓨터 또는 Team 또는 Enterprise 플랜으로 로그인한 사용자의 경우, [기본 제공 가드](/docs/ko/plugins/mods/admin#know-what-happens-by-default)는 mod 또는 해당 답변 중 하나를 거부할 수 있습니다. 각 메시지는 조직의 관리자가 규칙을 변경하도록 설정하는 옵션의 이름을 지정합니다.

| 메시지 포함 | 의미 | 나타나는 위치 |
| :- | :- | :- |
| `mods are limited to your organization's by policy (allowManagedModsOnly)` | 조직이 [자신의 mod만](/docs/ko/plugins/mods/admin#install-your-organizations-mods) 허용하므로 귀사의 mod이 로드되지 않았습니다 | 디버그 로그 및 [플러그인 디렉터리를 핫 리로드하는 세션](#find-out-why-a-mod-does-nothing)의 트랜스크립트 |
| `tried to lift a deny rule in your settings` | mod의 [`tool.check`](/docs/ko/plugins/mods/reference#tools) hook이 `deny` 규칙이 거부하는 호출을 승인했습니다. 호출은 거부된 상태로 유지됩니다. | 트랜스크립트 및 디버그 로그, 세션의 각 mod마다 한 번씩. `claude -p` 실행에서는 디버그 로그만 해당합니다. |
| `the deny rules in your settings could not be checked for this call, so it is refused` | 가드가 mod이 승인한 호출을 확인하는 동안 실패했으므로 호출을 거부했습니다 | 거부된 호출에 대해 Claude가 읽는 이유 |

<h3 id="validate-passes-and-lists-no-hooks-line">
  `validate`가 통과하고 `hooks` 줄을 나열하지 않음
</h3>

`hooks/hooks.json`에 `modules` 키가 없거나 키가 잘못 입력되었습니다.

`"modules": ["./register.js"]`를 추가합니다.

<h3 id="hooks-module-did-not-load">
  `hooks module did not load`
</h3>

줄은 mod의 이름으로 시작한 다음 `hooks module did not load:` 및 이유가 뒤따르며, 문제가 코드에 있을 때 파일과 줄을 제공합니다. Claude Code가 모듈을 로드할 수 없었습니다(예: 최상위 코드가 throw되었기 때문).

이유가 이름 지정하는 오류를 수정합니다.

<h3 id="options-do-not-fit-plugin-json-userconfig">
  `options do not fit plugin.json userConfig`
</h3>

줄은 mod의 이름으로 시작한 다음 `hooks module did not load: options do not fit plugin.json userConfig:` 및 이유가 뒤따릅니다. 옵션이 [`userConfig`](/docs/ko/plugins/components#user-configuration) 필드에 맞지 않습니다(예: 필드의 `max` 위의 숫자 또는 필수 필드에 값이 없음).

값을 설정하거나 변경합니다. 줄의 끝은 `settings.json`의 `pluginConfigs` 항목의 이름을 지정합니다.

<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">
  처음 열린 디렉터리에서 mod이 로드되지 않음
</h3>

디렉터리에 대한 신뢰 프롬프트에 답변하지 않았습니다.

`claude`를 사용하여 해당 디렉터리에서 대화형 세션을 시작하고 열리는 신뢰 프롬프트를 수락합니다.

<h3 id="no-installed-plugin-loads-at-all">
  설치된 플러그인이 로드되지 않음
</h3>

`--safe-mode`로 Claude Code를 시작했습니다.

플래그 없이 시작합니다.

<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">
  hook이 건너뛰어지거나 mod이 언로드됨
</h2>

mod이 로드되었고, Claude Code가 해당 hook 중 하나를 건너뛰거나 언로드했습니다.

<h3 id="hook-skipped">
  `hook skipped`
</h3>

줄은 mod과 이벤트의 이름을 지정한 다음 `hook skipped:` 및 이유를 말합니다(예: `first-mod: tool.call hook skipped: threw Error: boom`). hook이 throw되었거나, [10초 시간 제한](/docs/ko/plugins/mods/reference#limits)을 초과하여 실행되었거나, 잘못된 모양의 결과를 반환했습니다. 줄은 mod이 다시 로드될 때까지 각 이벤트 및 실패 종류마다 한 번씩 나타납니다.

오류를 수정합니다. 디버그 로그에는 모든 발생에 대한 줄이 있습니다.

<h3 id="it-crashed-the-hooks-worker">
  `it crashed the hooks worker`
</h3>

줄은 mod의 이름으로 시작합니다(예: `first-mod was unloaded: it crashed the hooks worker`). 설치된 mod은 하나의 워커 스레드를 공유합니다. 워커가 응답을 중지하거나 충돌했으며, Claude Code가 이를 이 mod으로 추적하고 언로드했습니다. 스레드를 차단하는 hook(예: 절대 await하지 않는 루프)이 한 가지 원인입니다.

hook을 수정합니다.

<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">
  `mods that run in the hooks worker are off for this session`
</h3>

줄은 `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`를 읽습니다. 워커가 3번 중지되었고 Claude Code가 중지를 하나의 mod으로 추적할 수 없어서 기본 제공되지 않은 모든 mod(조직이 설치하는 mod 포함)을 언로드했습니다. 이 줄은 모든 대화형 세션의 트랜스크립트에 도달합니다.

`/reload-plugins`를 실행하여 다시 로드합니다.

<h2 id="a-tool-call-is-denied">
  도구 호출이 거부됨
</h2>

mod이 로드되었고 해당 hook이 실행되며, 이를 건드린 도구 호출이 거부됩니다.

<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">
  `a hook changed this call's input after the model wrote it`
</h3>

자동 모드에서 거부된 도구 호출은 이 이유를 제공합니다. hook이 [서버 측 분류자](/docs/ko/permission-modes#server-side-classifier-review)가 검토한 후 도구 호출의 입력을 변경했으므로 해당 검토는 실행될 내용을 포함하지 않습니다. hook은 mod의 [`tool.call`](/docs/ko/plugins/mods/reference#tools) 또는 [`turn.step`](/docs/ko/plugins/mods/reference#turns) hook이거나 [`PreToolUse`](/docs/ko/hooks#pretooluse) 설정 hook일 수 있습니다. 메시지는 어느 것인지 말하지 않습니다.

메시지는 Claude에게 기록된 대로 호출을 다시 한 번 발급하도록 지시합니다. 그것도 거부되면 hook은 매번 입력을 변경하므로 mod 또는 hook을 끄거나 자동 모드를 떠나 호출을 직접 승인합니다.

<h3 id="a-message-about-the-deny-rules-in-your-settings">
  설정의 거부 규칙에 대한 메시지
</h3>

`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`는 모두 기본 제공 가드에서 옵니다.

[기본 제공 가드의 메시지](#messages-from-the-built-in-guard)에서 조회합니다.

<h2 id="a-drawing-doesn’t-appear-or-respond">
  그리기가 나타나지 않거나 응답하지 않음
</h2>

mod이 로드되었고 해당 pane, band 또는 컨트롤이 예상대로 작동하지 않습니다.

<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">
  pane 또는 band가 비어 있거나 Claude Code의 일반적인 콘텐츠를 표시함
</h3>

hook이 반환한 [tree](/docs/ko/plugins/mods/interface#build-a-tree-from-elements)가 유효성 검사를 통과하지 못했습니다. `--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`가 동일한 이유와 함께 있습니다.

해당 줄의 이유를 읽습니다. 일반적인 원인은 요소가 취하지 않는 prop과 앱이 없는 요소입니다.

<h3 id="ui-open-runs-and-no-pane-appears">
  `$.ui.open`이 실행되고 pane이 나타나지 않음
</h3>

호출이 사용자가 한 것에서 오지 않았으며 터미널이 144열보다 좁습니다.

명령 또는 버튼에서 pane을 열거나 호출의 `isPlaced` 결과를 확인합니다. [올바른 시간에 pane 열기](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)를 참조합니다.

<h3 id="hotkeys-do-nothing">
  핫키가 아무것도 하지 않음
</h3>

pane에 키보드 포커스가 없습니다.

Ctrl+X를 누른 다음 Tab을 누르거나 pane을 클릭합니다. `focus: true`로 명령에서 열기합니다.

<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">
  그리기가 터미널에서 작동하고 Desktop 앱에서는 작동하지 않음
</h3>

사이트 또는 요소를 사용할 수 없습니다.

[렌더 사이트](/docs/ko/plugins/mods/reference#render-sites) 및 [요소](/docs/ko/plugins/mods/reference#elements) 테이블을 확인합니다.

<h2 id="an-edit-or-a-value-is-lost">
  편집 또는 값이 손실됨
</h2>

mod이 실행되고 변경하거나 유지한 값이 없습니다.

<h3 id="your-edits-don’t-take-effect">
  편집이 적용되지 않음
</h3>

설치한 플러그인을 편집하고 있습니다. Claude Code는 설치된 버전의 캐시된 복사본을 실행합니다.

`claude --plugin-dir ./first-mod`와 같이 작업 복사본을 가리키는 `--plugin-dir`로 개발합니다. 이는 저장할 때 다시 로드됩니다.

<h3 id="a-value-resets-when-the-module-reloads">
  모듈이 다시 로드될 때 값이 재설정됨
</h3>

모듈 수준 변수는 각 다시 로드 시 다시 초기화됩니다.

[값을 `$.state` 또는 `$.store`에 유지합니다](/docs/ko/plugins/mods/interface#keep-state).

<h3 id="a-value-resets-after-/clear-/resume-or-/branch">
  `/clear`, `/resume` 또는 `/branch` 후 값이 재설정됨
</h3>

값이 재설정되거나 저장된 값이 기본값으로 대체됩니다. 이러한 각 명령은 `$.state`를 기본값으로 재설정하며, `session.start`는 다시 실행되지 않습니다.

[`classic.SessionStart` hook에서 저장된 값을 다시 로드합니다](/docs/ko/plugins/mods/interface#load-a-saved-value-again-after-clear).

<h2 id="read-the-debug-log">
  디버그 로그 읽기
</h2>

디버그 로그에는 Claude Code가 로드하거나 거부하는 모든 모듈, 실패하는 모든 hook, 거부하는 모든 결과에 대한 줄이 있으므로 트랜스크립트가 아무것도 표시하지 않을 때 볼 위치입니다. 하나를 작성하려면 셸에서 `--debug`로 Claude Code를 시작하거나 `--debug-file <path>`로 위치를 선택합니다:

```bash theme={null}
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
```

다른 터미널에서 파일을 따르고 mod의 이름으로 필터링합니다:

```bash theme={null}
tail -f ./mod-debug.log | grep first-mod
```

로드된 mod에는 이름을 지정하고 hook하는 이벤트를 나열하는 줄이 있습니다. `--plugin-dir`로 로드된 mod은 이름 뒤에 `@inline`으로 나타납니다:

```text theme={null}
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
```

유효성 검사를 통과하지 못한 그리기는 거부된 결과로 계산되며 줄도 가져옵니다. 로그에 자신의 줄을 작성하려면 [`$.ui.log`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)를 두 번째 인수와 함께 호출합니다(예: `$.ui.log('message', { to: 'debug' })`). 두 번째 인수 없이 `$.ui.log`는 트랜스크립트에 흐린 줄을 추가합니다.

`--plugin-dir`로 로드된 mod을 편집하는 동안 트랜스크립트는 mod의 이름을 지정하고 해당 hook을 나열하는 각 다시 로드에 대한 줄을 표시합니다. 저장이 모듈을 손상시키면 줄은 `reload failed, the previous version stays loaded:`를 이유와 함께 말하며, 마지막 작동 버전이 계속 실행됩니다.

<h2 id="next-steps">
  다음 단계
</h2>

* [mod 테스트](/docs/ko/plugins/mods/test): 문제가 세션에 도달하기 전에 포착합니다
* [플러그인 문제 해결](/docs/ko/plugins/troubleshooting): mod에 특정하지 않은 플러그인 설치 및 로드 문제