4 4
5# mod 문제 해결5# mod 문제 해결
6 6
7> Claude Code mod이 작동하지 않는 이유를 파악합니다: 증상이나 메시지를 원인과 일치시키고, 거부 메시지를 조회하며, 디버그 로그를 읽습니다.7> Claude Code mod가 아무 동작도 하지 않는 이유를 찾습니다. 증상이나 메시지를 원인과 대조하고, 거부 메시지를 조회하고, 디버그 로그를 확인합니다.
8 8
9mod의 모듈이나 해당 hook 중 하나가 실패하면 Claude Code는 이를 건너뛰고 세션이 계속되므로, 손상된 mod은 아무것도 하지 않는 것처럼 보일 수 있습니다. Claude Code가 mod에서 읽은 내용과 문제를 보고하는 위치를 확인하여 시작한 다음, 발생한 증상이나 메시지를 찾습니다.9mod의 모듈이나 훅 중 하나가 실패하면 Claude Code는 이를 건너뛰고 세션을 계속 진행하므로, 손상된 mod가 아무 동작도 하지 않는 mod처럼 보일 수 있습니다. 먼저 Claude Code가 mod에서 무엇을 읽었는지, 어디에서 문제를 보고하는지 확인한 다음, 해당하는 증상이나 메시지를 찾습니다.
10 10
11<h2 id="find-out-why-a-mod-does-nothing">11<h2 id="find-out-why-a-mod-does-nothing">
12 mod이 아무것도 하지 않는 이유 파악12 mod가 아무 동작도 하지 않는 이유 찾기
13</h2>13</h2>
14 14
15mod이 아무것도 하지 않을 때, 두 가지 확인으로 이유를 찾을 수 있습니다: 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가 읽을 수 없는 모듈을 포착합니다.15mod가 아무 동작도 하지 않으면 Claude Code가 mod의 파일에서 무엇을 읽는지, 그리고 무언가를 건너뛸 때 기록하는 줄을 확인합니다. 첫 번째의 경우, 셸에서 `claude plugin validate ./first-mod`처럼 mod의 디렉터리를 지정하여 [`claude plugin validate`](/docs/ko/plugins/mods/create#check-what-claude-code-reads-from-your-mod)를 실행합니다. 이 명령은 세션을 시작하지 않고도 철자가 틀린 이벤트, 잘못된 매니페스트, Claude Code가 읽을 수 없는 모듈을 찾아냅니다.
16 16
17모듈이 로드되지 않거나, hook이 건너뛰어지거나, 다른 mod이 귀사의 mod을 거부할 때, Claude Code는 귀사의 mod의 이름을 지정하는 한 줄을 작성합니다. 해당 줄을 읽는 위치는 세션에 따라 다릅니다:17모듈이 로드되지 않거나, 훅을 건너뛰거나, 다른 mod가 사용자의 mod를 거부하면 Claude Code는 해당 mod의 이름이 포함된 한 줄을 기록합니다. 이 줄을 확인하는 위치는 세션에 따라 다릅니다.
18 18
19* **플러그인 디렉터리를 핫 리로드하는 세션**: 트랜스크립트의 흐린 줄입니다. 이는 `--plugin-dir`로 시작한 대화형 세션이거나, Claude가 작성한 mod에 대해 [핫 리로딩을 활성화](/docs/ko/plugins/mods/create#ask-claude-for-a-mod)한 세션입니다.19* **플러그인 디렉터리를 핫 리로드하는 세션**: 트랜스크립트에 흐리게 표시되는 줄입니다. `--plugin-dir`로 시작한 대화형 세션이나, Claude가 작성한 mod에 대해 [핫 리로드를 활성화한](/docs/ko/plugins/mods/create#ask-claude-for-a-mod) 세션이 이에 해당합니다.
20* **마켓플레이스에서 설치한 mod을 실행하는 것과 같은 다른 모든 대화형 세션**: [디버그 로그](#read-the-debug-log)만 해당합니다. 하나를 얻으려면 `claude --debug`로 세션을 시작합니다.20* **그 외의 대화형 세션(예: 마켓플레이스에서 설치한 mod를 실행하는 세션)**: [디버그 로그](#read-the-debug-log)에만 기록됩니다. 디버그 로그를 얻으려면 `claude --debug`로 세션을 시작합니다.
21* **`--plugin-dir`을 사용한 `claude -p` 실행**: stderr, 기본 텍스트 출력 형식입니다. 다른 mod의 거부는 디버그 로그로만 이동합니다.21* **`--plugin-dir`을 사용한 `claude -p` 실행**: 기본 텍스트 출력 형식에서 stderr로 출력됩니다. 다른 mod에 의한 거부는 디버그 로그에만 기록됩니다.
22 22
23<h2 id="check-whether-mods-can-load">23<h2 id="check-whether-mods-can-load">
24 mod이 로드될 수 있는지 확인24 mod를 로드할 수 있는지 확인하기
25</h2>25</h2>
26 26
27설정이 mod을 로드할 수 있는지 확인하려면 mod을 설치하지 않고도 셸에서 `claude plugin test`를 실행합니다(mod을 보유하지 않은 디렉터리에서). 세션이 필요하지 않습니다. 인쇄되는 메시지는 상태를 알려줍니다:27mod를 설치하지 않고도 현재 설정에서 mod를 로드할 수 있는지 확인하려면, mod가 없는 디렉터리에서 셸에 `claude plugin test`를 실행합니다. 세션은 필요하지 않습니다. 출력되는 메시지를 통해 상태를 알 수 있습니다.
28 28
29| 메시지 포함 | 의미 |29| 메시지에 포함된 내용 | 의미 |
30| :- | :- |30| :- | :- |
31| `no hooks module to load` | mod을 로드할 수 있습니다. 명령이 이 디렉터리에서 테스트할 mod을 찾지 못했습니다. |31| `no hooks module to load` | mod를 로드할 수 있습니다. 이 명령이 현재 디렉터리에서 테스트할 mod를 찾지 못했습니다. |
32| `hooks modules are turned off here` | 설정이 mod을 차단하고 있습니다: 자신의 설정에서 `disableAllHooks` 또는 조직의 정책 |32| `hooks modules are turned off here` | 설정이 mod를 차단하고 있습니다. 사용자 설정의 `disableAllHooks` 또는 조직의 정책이 원인입니다 |
33| `hooks modules are turned off in this process` | Anthropic이 설치된 mod을 원격으로 비활성화했습니다. 컴퓨터의 어떤 설정도 이를 다시 켤 수 없습니다. |33| `hooks modules are turned off in this process` | Anthropic이 설치된 mod를 원격으로 껐습니다. 사용자 컴퓨터의 어떤 설정으로도 다시 켤 수 없습니다. |
34 34
35조직은 또한 `allowManagedModsOnly`를 설정하여 자신의 mod만 허용할 수 있으며, 이 명령은 이를 보고하지 않습니다. 이 경우 설치한 mod이 로드되지 않으며, [메시지가 이유를 설명합니다](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard).35조직은 `allowManagedModsOnly`를 설정하여 조직 자체의 mod만 허용할 수도 있으며, 이 명령은 이를 보고하지 않습니다. 이 경우 사용자가 설치한 mod는 로드되지 않으며, [그 이유를 알려 주는 메시지](/docs/ko/plugins/mods/troubleshoot#messages-from-the-built-in-guard)가 표시됩니다.
36 36
37<h2 id="the-mod-doesn’t-load">37<h2 id="the-mod-doesn’t-load">
38 mod이 로드되지 않음38 mod가 로드되지 않음
39</h2>39</h2>
40 40
41mod이 추가하는 것이 아무것도 나타나지 않습니다: 명령, 그리기, 동작 변화가 없습니다.41mod가 추가하는 항목이 전혀 나타나지 않습니다. 명령도, 그리기도, 동작의 변화도 없습니다.
42 42
43<h3 id="your-version-is-older-than-2-1-287">43<h3 id="your-version-is-older-than-2-1-287">
44 버전이 2.1.287보다 오래됨44 버전이 2.1.287보다 오래됨
45</h3>45</h3>
46 46
47`claude --version`은 2.1.287보다 오래된 버전을 인쇄합니다. 버전이 mod이 기본적으로 켜지기 전의 것입니다.47`claude --version`이 2.1.287보다 오래된 버전을 출력합니다. 해당 버전은 mod가 기본적으로 켜지기 이전 버전입니다.
48 48
49[Claude Code 업데이트](/docs/ko/setup#update-claude-code).49[Claude Code를 업데이트하세요](/docs/ko/setup#update-claude-code).
50 50
51<h3 id="the-mods-active-line-doesn’t-name-the-mod">51<h3 id="the-mods-active-line-doesn’t-name-the-mod">
52 `mods active` 줄이 mod의 이름을 지정하지 않음52 `mods active` 줄에 mod 이름이 없음
53</h3>53</h3>
54 54
55mod이 추가하는 것이 아무것도 나타나지 않으며, `/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`).55mod가 추가하는 항목이 전혀 나타나지 않고, `/plugin`의 [`mods active` 줄](/docs/ko/plugins/mods/overview#see-which-mods-a-session-loaded)에도 mod 이름이 표시되지 않습니다. 훅 모듈이 로드되지 않은 것입니다. Claude Code가 훅 모듈을 거부한 경우, 디버그 로그에 `hooks module`, mod 이름, `not loaded:`로 시작하는 줄이 있습니다. 예를 들어 `--plugin-dir`로 로드한 mod의 경우 `hooks module first-mod@inline not loaded: disableAllHooks in managed settings`와 같이 표시됩니다.
56 56
57콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다. 로그에 그러한 줄이 없으면 이 그룹의 다른 항목을 통해 작업합니다.57콜론 뒤의 이유를 확인합니다. [거부 메시지](#refusal-messages) 섹션에 각 메시지가 나와 있습니다. 로그에 이러한 줄이 없다면 이 그룹의 다른 항목을 차례로 확인합니다.
58
59일부 설정은 mod를 중지시키지만 해당 플러그인의 나머지 부분은 계속 작동하게 둡니다. [mod 켜기 또는 끄기](/docs/ko/plugins/mods/overview#turn-mods-on-or-off)에 해당 설정이 나와 있습니다.
58 60
59<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">61<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">
60 `claude -p` 실행이 `hooks module not loaded` 인쇄62 `claude -p` 실행 시 `hooks module not loaded`가 출력됨
61</h3>63</h3>
62 64
63줄은 mod의 이름으로 시작하여 stderr로 이동합니다. hooks 모듈이 거부되었습니다. 비대화형 실행에는 트랜스크립트가 없으므로 메시지는 stderr로 이동합니다.65이 줄은 mod 이름으로 시작하며 stderr로 출력됩니다. 훅 모듈이 거부된 것입니다. 비대화형 실행에는 트랜스크립트가 없으므로 메시지가 stderr로 출력됩니다.
64 66
65콜론 뒤의 이유를 읽습니다. [거부 메시지](#refusal-messages) 섹션에는 각각이 나열되어 있습니다.67콜론 뒤의 이유를 확인합니다. [거부 메시지](#refusal-messages) 섹션에 각 메시지가 나와 있습니다.
66 68
67<h3 id="refusal-messages">69<h3 id="refusal-messages">
68 거부 메시지70 거부 메시지
69</h3>71</h3>
70 72
71각각은 디버그 로그에서 `hooks module`, mod의 이름, `not loaded:` 뒤에 옵니다.73디버그 로그에서 다음 각 메시지는 `hooks module`, mod 이름, `not loaded:` 뒤에 나옵니다.
72 74
73| 메시지 시작 | 의미 |75| 메시지 시작 부분 | 의미 |
74| :- | :- |76| :- | :- |
75| `hooks modules are turned off for installed plugins in this process` | Anthropic이 설치된 mod을 원격으로 비활성화했습니다. 컴퓨터의 어떤 설정도 이를 다시 켤 수 없습니다. |77| `hooks modules are turned off for installed plugins in this process` | Anthropic이 설치된 mod를 원격으로 껐습니다. 사용자 컴퓨터의 어떤 설정으로도 다시 켤 수 없습니다. |
76| `disableAllHooks in managed settings` | 조직이 설치된 플러그인의 hook을 비활성화했습니다 |78| `disableAllHooks in managed settings` | 조직에서 설치된 플러그인의 훅을 껐습니다 |
77| `only managed plugins and built-in plugins run` | `allowManagedHooksOnly`가 설정되었거나 관리되는 설정이 아닌 설정 파일에서 `disableAllHooks`가 설정되었습니다 |79| `only managed plugins and built-in plugins run` | `allowManagedHooksOnly`가 설정되어 있거나, 관리형 설정이 아닌 설정 파일에 `disableAllHooks`가 설정되어 있습니다 |
78| `installed plugins that are not managed load no hooks module in this mode (--bare)` | `--bare`로 Claude Code를 시작했습니다 |80| `installed plugins that are not managed load no hooks module in this mode (--bare)` | Claude Code를 `--bare`로 시작했습니다 |
79| `another plugin of that name loads first` | 두 플러그인이 이름을 공유합니다. 관리되는 것 또는 먼저 로드된 것이 사용됩니다. |81| `another plugin of that name loads first` | 두 플러그인의 이름이 같습니다. 관리되는 플러그인 또는 먼저 로드된 플러그인이 사용됩니다. |
80 82
81<h3 id="messages-from-the-built-in-guard">83<h3 id="messages-from-the-built-in-guard">
82 기본 제공 가드의 메시지84 기본 제공 가드의 메시지
83</h3>85</h3>
84 86
85관리되는 설정이 있는 컴퓨터 또는 Team 또는 Enterprise 플랜으로 로그인한 사용자의 경우, [기본 제공 가드](/docs/ko/plugins/mods/admin#know-what-happens-by-default)는 mod 또는 해당 답변 중 하나를 거부할 수 있습니다. 각 메시지는 조직의 관리자가 규칙을 변경하도록 설정하는 옵션의 이름을 지정합니다.87관리형 설정이 있는 컴퓨터에서, 또는 Team이나 Enterprise 플랜으로 로그인한 사용자의 경우, [기본 제공 가드](/docs/ko/plugins/mods/admin#know-what-happens-by-default)가 mod 또는 mod의 응답 중 하나를 거부할 수 있습니다. 각 메시지에는 조직의 관리자가 규칙을 변경하기 위해 설정하는 옵션이 명시되어 있습니다.
86 88
87| 메시지 포함 | 의미 | 나타나는 위치 |89| 메시지 포함 내용 | 의미 | 표시 위치 |
88| :- | :- | :- |90| :- | :- | :- |
89| `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)의 트랜스크립트 |91| `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)의 트랜스크립트 |
90| `tried to lift a deny rule in your settings` | mod의 [`tool.check`](/docs/ko/plugins/mods/reference#tools) hook이 `deny` 규칙이 거부하는 호출을 승인했습니다. 호출은 거부된 상태로 유지됩니다. | 트랜스크립트 및 디버그 로그, 세션의 각 mod마다 한 번씩. `claude -p` 실행에서는 디버그 로그만 해당합니다. |92| `tried to lift a deny rule in your settings` | mod의 [`tool.check`](/docs/ko/plugins/mods/reference#tools) 훅이 `deny` 규칙에서 거부하는 호출을 승인했습니다. 해당 호출은 계속 거부됩니다. | 트랜스크립트와 디버그 로그, 세션에서 mod마다 한 번씩. `claude -p` 실행에서는 디버그 로그에만 표시됩니다. |
91| `the deny rules in your settings could not be checked for this call, so it is refused` | 가드가 mod이 승인한 호출을 확인하는 동안 실패했으므로 호출을 거부했습니다 | 거부된 호출에 대해 Claude가 읽는 이유 |93| `the deny rules in your settings could not be checked for this call, so it is refused` | mod가 승인한 호출을 확인하는 중에 가드가 실패하여 해당 호출을 거부했습니다 | 거부된 호출에 대해 Claude가 읽는 이유 |
92 94
93<h3 id="validate-passes-and-lists-no-hooks-line">95<h3 id="validate-passes-and-lists-no-hooks-line">
94 `validate`가 통과하고 `hooks` 줄을 나열하지 않음96 `validate`는 통과하지만 `hooks` 줄이 나열되지 않음
95</h3>97</h3>
96 98
97`hooks/hooks.json`에 `modules` 키가 없거나 키가 잘못 입력되었습니다.99`hooks/hooks.json`에 `modules` 키가 없거나 키의 철자가 잘못되었습니다.
98 100
99`"modules": ["./register.js"]`를 추가합니다.101`"modules": ["./register.js"]`를 추가합니다.
100 102
102 `hooks module did not load`104 `hooks module did not load`
103</h3>105</h3>
104 106
105줄은 mod의 이름으로 시작한 다음 `hooks module did not load:` 및 이유가 뒤따르며, 문제가 코드에 있을 때 파일과 줄을 제공합니다. Claude Code가 모듈을 로드할 수 없었습니다(예: 최상위 코드가 throw되었기 때문).107이 줄은 mod 이름으로 시작하고, 그 뒤에 `hooks module did not load:`와 이유가 나옵니다. 문제가 코드에 있는 경우 이유에 파일과 줄이 표시됩니다. Claude Code가 모듈을 로드할 수 없었습니다. 예를 들어 모듈의 최상위 코드에서 예외가 발생한 경우입니다.
106 108
107이유가 이름 지정하는 오류를 수정합니다.109이유에 명시된 오류를 수정합니다.
108 110
109<h3 id="options-do-not-fit-plugin-json-userconfig">111<h3 id="options-do-not-fit-plugin-json-userconfig">
110 `options do not fit plugin.json userConfig`112 `options do not fit plugin.json userConfig`
111</h3>113</h3>
112 114
113줄은 mod의 이름으로 시작한 다음 `hooks module did not load: options do not fit plugin.json userConfig:` 및 이유가 뒤따릅니다. 옵션이 [`userConfig`](/docs/ko/plugins/components#user-configuration) 필드에 맞지 않습니다(예: 필드의 `max` 위의 숫자 또는 필수 필드에 값이 없음).115이 줄은 mod 이름으로 시작하고, 그 뒤에 `hooks module did not load: options do not fit plugin.json userConfig:`와 이유가 나옵니다. 옵션이 해당 [`userConfig`](/docs/ko/plugins/components#user-configuration) 필드에 대한 검증에 실패했습니다. 예를 들어 숫자가 필드의 `max`를 초과하거나, 필수 필드에 값이 없는 경우입니다.
114 116
115값을 설정하거나 변경합니다. 줄의 끝은 `settings.json`의 `pluginConfigs` 항목의 이름을 지정합니다.117값을 설정하거나 변경합니다. 줄 끝에 `settings.json`의 해당 `pluginConfigs` 항목이 명시되어 있습니다.
116 118
117<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">119<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">
118 처음 열린 디렉터리에서 mod이 로드되지 않음120 처음 연 디렉터리에서 mod가 로드되지 않음
119</h3>121</h3>
120 122
121디렉터리에 대한 신뢰 프롬프트에 답변하지 않았습니다.123해당 디렉터리의 신뢰 프롬프트에 응답하지 않았습니다.
122 124
123`claude`를 사용하여 해당 디렉터리에서 대화형 세션을 시작하고 열리는 신뢰 프롬프트를 수락합니다.125해당 디렉터리에서 `claude`로 대화형 세션을 시작하고, 세션 시작 시 표시되는 신뢰 프롬프트를 수락합니다.
124 126
125<h3 id="no-installed-plugin-loads-at-all">127<h3 id="no-installed-plugin-loads-at-all">
126 설치된 플러그인이 로드되지 않음128 설치된 플러그인이 전혀 로드되지 않음
127</h3>129</h3>
128 130
129`--safe-mode`로 Claude Code를 시작했습니다.131Claude Code를 `--safe-mode`로 시작했습니다.
130 132
131플래그 없이 시작합니다.133이 플래그 없이 시작합니다.
132 134
133<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">135<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">
134 hook이 건너뛰어지거나 mod이 언로드됨136 훅이 건너뛰어지거나 mod가 언로드되는 경우
135</h2>137</h2>
136 138
137mod이 로드되었고, Claude Code가 해당 hook 중 하나를 건너뛰거나 언로드했습니다.139mod가 로드된 후 Claude Code가 해당 mod의 훅 중 하나를 건너뛰었거나 mod를 언로드했습니다.
138 140
139<h3 id="hook-skipped">141<h3 id="hook-skipped">
140 `hook skipped`142 `hook skipped`
141</h3>143</h3>
142 144
143줄은 mod과 이벤트의 이름을 지정한 다음 `hook skipped:` 및 이유를 말합니다(예: `first-mod: tool.call hook skipped: threw Error: boom`). hook이 throw되었거나, [10초 시간 제한](/docs/ko/plugins/mods/reference#limits)을 초과하여 실행되었거나, 잘못된 모양의 결과를 반환했습니다. 줄은 mod이 다시 로드될 때까지 각 이벤트 및 실패 종류마다 한 번씩 나타납니다.145이 줄은 mod와 이벤트의 이름을 표시한 다음 `hook skipped:`와 이유를 표시합니다. 예를 들면 `first-mod: tool.call hook skipped: threw Error: boom`과 같습니다. 훅이 예외를 발생시켰거나, [시간 제한](/docs/ko/plugins/mods/reference#limits)을 초과했거나, 잘못된 형태의 결과를 반환한 경우입니다. 이 줄은 mod가 다시 로드될 때까지 이벤트와 실패 유형마다 한 번씩 표시됩니다.
144 146
145오류를 수정합니다. 디버그 로그에는 모든 발생에 대한 줄이 있습니다.147오류를 수정하십시오. 디버그 로그에는 발생할 때마다 한 줄씩 기록됩니다.
146 148
147<h3 id="no-command-run-hook-answered-it">149<h3 id="no-command-run-hook-answered-it">
148 `no command.run hook answered it`150 `no command.run hook answered it`
149</h3>151</h3>
150 152
151사용자가 mod이 추가한 명령을 실행하면, 회신은 mod과 명령의 이름을 지정합니다(예: `first-mod registered /tally but no command.run hook answered it`). 그런 다음 hook을 추가하도록 지시합니다. Claude Code는 명령이 답변 없이 체인의 끝에 도달할 때 해당 회신을 출력합니다. 이는 두 가지 경우에 발생합니다:153mod가 추가한 명령을 실행하면, 응답에 mod와 명령의 이름이 표시되고(예: `first-mod registered /tally but no command.run hook answered it`) 훅을 추가하라는 안내가 이어집니다. Claude Code는 명령이 응답 없이 체인의 끝에 도달하면 이 응답을 출력하며, 이는 다음 두 가지 경우에 발생합니다.
152 154
153* **hook이 명령에 답변하지 않음**: 모듈에 `command.run` hook이 없거나, hook의 [필터](/docs/ko/plugins/mods/events#filter-which-events-a-hook-handles)가 다른 명령의 이름을 지정하거나, hook이 `next(e)`를 반환했습니다.155* **명령에 응답한 훅이 없는 경우**: 모듈에 `command.run` 훅이 없거나, 훅의 [필터](/docs/ko/plugins/mods/events#filter-which-events-a-hook-handles)가 다른 명령을 지정하거나, 훅이 `next(e)`를 반환한 경우입니다
154* **Claude Code가 hook을 건너뜀**: [`hook skipped`](#hook-skipped)에 이유가 나열됩니다. [`$.ui.open`](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)에 `focus: false`를 전달하는 것이 이 상황에 도달하는 한 가지 방법입니다.156* **Claude Code가 훅을 건너뛴 경우**: [`hook skipped`](#hook-skipped)에 그 이유가 나열되어 있습니다. [`$.ui.open`](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)에 `focus: false`를 전달하는 것도 이러한 상황이 발생하는 한 가지 방법입니다.
155 157
156모듈에 이미 회신이 설명하는 hook이 있으면, `command.run`의 이름을 지정하는 `hook skipped` 줄을 찾으십시오. 이는 이유를 제공합니다. 명령을 실행하는 [테스트](/docs/ko/plugins/mods/test)는 동일한 이유로 실패합니다.158모듈에 응답에서 설명하는 훅이 이미 있다면, `command.run`을 지정하는 `hook skipped` 줄을 찾아 이유를 확인하십시오. 해당 명령을 실행하는 [테스트](/docs/ko/plugins/mods/test)도 같은 이유로 실패합니다.
157 159
158<h3 id="it-crashed-the-hooks-worker">160<h3 id="it-crashed-the-hooks-worker">
159 `it crashed the hooks worker`161 `it crashed the hooks worker`
160</h3>162</h3>
161 163
162줄은 mod의 이름으로 시작합니다(예: `first-mod was unloaded: it crashed the hooks worker`). 설치된 mod은 하나의 워커 스레드를 공유합니다. 워커가 응답을 중지하거나 충돌했으며, Claude Code가 이를 이 mod으로 추적하고 언로드했습니다. 스레드를 차단하는 hook(예: 절대 await하지 않는 루프)이 한 가지 원인입니다.164이 줄은 mod의 이름으로 시작합니다. 예를 들면 `first-mod was unloaded: it crashed the hooks worker`와 같습니다. 설치된 mod는 하나의 워커 스레드를 공유합니다. 워커가 응답을 멈추거나 충돌했고, Claude Code가 그 원인을 이 mod로 추적하여 언로드한 것입니다. 한 번도 await하지 않는 루프처럼 스레드를 차단하는 훅이 한 가지 원인입니다.
163 165
164hook을 수정합니다.166훅을 수정하십시오.
165 167
166<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">168<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">
167 `mods that run in the hooks worker are off for this session`169 `mods that run in the hooks worker are off for this session`
168</h3>170</h3>
169 171
170줄은 `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`를 읽습니다. 워커가 3번 중지되었고 Claude Code가 중지를 하나의 mod으로 추적할 수 없어서 기본 제공되지 않은 모든 mod(조직이 설치하는 mod 포함)을 언로드했습니다. 이 줄은 모든 대화형 세션의 트랜스크립트에 도달합니다.172이 줄은 `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`로 표시됩니다. 워커가 세 번 중단되었고 Claude Code가 그 원인을 하나의 mod로 추적할 수 없었기 때문에, 조직에서 설치한 mod를 포함하여 내장되지 않은 모든 mod를 언로드한 것입니다. 이 줄은 모든 대화형 세션의 트랜스크립트에 표시됩니다.
171 173
172`/reload-plugins`를 실행하여 다시 로드합니다.174`/reload-plugins`를 실행하여 다시 로드하십시오.
173 175
174<h2 id="a-tool-call-is-denied">176<h2 id="a-tool-call-is-denied">
175 도구 호출이 거부됨177 도구 호출이 거부되는 경우
176</h2>178</h2>
177 179
178mod이 로드되었고 해당 hook이 실행되며, 이를 건드린 도구 호출이 거부됩니다.180mod가 로드되고 해당 훅이 실행되었지만, 그 mod가 관여한 도구 호출이 거부됩니다.
179 181
180<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">182<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">
181 `a hook changed this call's input after the model wrote it`183 `a hook changed this call's input after the model wrote it`
182</h3>184</h3>
183 185
184자동 모드에서 거부된 도구 호출은 이 이유를 제공합니다. 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일 수 있습니다. 메시지는 어느 것인지 말하지 않습니다.186자동 모드에서 도구 호출이 거부되면 이 사유가 표시됩니다. [서버 측 분류기](/docs/ko/permission-modes#server-side-classifier-review)가 도구 호출의 입력을 검토한 후에 훅이 그 입력을 변경했으므로, 해당 검토는 실제로 실행될 내용을 다루지 않습니다. 이 훅은 mod의 [`tool.call`](/docs/ko/plugins/mods/reference#tools) 또는 [`turn.step`](/docs/ko/plugins/mods/reference#turns) 훅이거나, [`PreToolUse`](/docs/ko/hooks#pretooluse) 설정 훅일 수 있습니다. 메시지에는 어느 쪽인지 표시되지 않습니다.
185 187
186메시지는 Claude에게 기록된 대로 호출을 다시 한 번 발급하도록 지시합니다. 그것도 거부되면 hook은 매번 입력을 변경하므로 mod 또는 hook을 끄거나 자동 모드를 떠나 호출을 직접 승인합니다.188이 메시지는 Claude에게 기록된 그대로 호출을 한 번 더 실행하도록 지시합니다. 그 호출도 거부된다면 훅이 매번 입력을 변경하고 있는 것이므로, 해당 mod나 훅을 끄거나 자동 모드를 종료하고 호출을 직접 승인해야 합니다.
187 189
188<h3 id="a-message-about-the-deny-rules-in-your-settings">190<h3 id="a-message-about-the-deny-rules-in-your-settings">
189 설정의 거부 규칙에 대한 메시지191 설정의 거부 규칙에 관한 메시지
190</h3>192</h3>
191 193
192`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`는 모두 기본 제공 가드에서 옵니다.194`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`는 모두 기본 제공 가드에서 발생하는 메시지입니다.
193 195
194[기본 제공 가드의 메시지](#messages-from-the-built-in-guard)에서 조회합니다.196[기본 제공 가드의 메시지](#messages-from-the-built-in-guard)에서 확인하십시오.
195 197
196<h2 id="a-drawing-doesn’t-appear-or-respond">198<h2 id="a-drawing-doesn’t-appear-or-respond">
197 그리기가 나타나지 않거나 응답하지 않음199 그림이 나타나지 않거나 반응하지 않음
198</h2>200</h2>
199 201
200mod이 로드되었고 해당 pane, band 또는 컨트롤이 예상대로 작동하지 않습니다.202mod는 로드되었지만 해당 pane, band 또는 컨트롤이 예상대로 동작하지 않습니다.
201 203
202<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">204<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">
203 pane 또는 band가 비어 있거나 Claude Code의 일반적인 콘텐츠를 표시함205 pane 또는 band가 비어 있거나 Claude Code의 일반 콘텐츠를 표시함
204</h3>206</h3>
205 207
206hook이 반환한 [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`가 동일한 이유와 함께 있습니다.208훅이 반환한 [트리](/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`가 기록됩니다.
207 209
208해당 줄의 이유를 읽습니다. 일반적인 원인은 요소가 취하지 않는 prop과 앱이 없는 요소입니다.210해당 줄에 표시된 이유를 확인합니다. 흔한 원인은 해당 요소가 받지 않는 prop을 사용했거나 앱에 없는 요소를 사용한 경우입니다.
209 211
210<h3 id="ui-open-runs-and-no-pane-appears">212<h3 id="$-ui-open-runs-and-no-pane-appears">
211 `$.ui.open`이 실행되고 pane이 나타나지 않음213 `$.ui.open`이 실행되지만 pane이 나타나지 않음
212</h3>214</h3>
213 215
214호출이 사용자가 한 것에서 오지 않았으며 터미널이 144열보다 좁습니다.216호출이 사용자의 동작에서 비롯되지 않았고, 터미널 너비가 [해당 pane에 필요한 너비](/docs/ko/plugins/mods/interface#when-a-pane-waits-for-a-wider-terminal)보다 좁습니다.
215 217
216명령 또는 버튼에서 pane을 열거나 호출의 `isPlaced` 결과를 확인합니다. [올바른 시간에 pane 열기](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)를 참조합니다.218명령이나 버튼에서 pane을 열거나, 호출의 `isPlaced` 결과를 확인합니다. [적절한 시점에 pane 열기](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)를 참조하세요.
217 219
218<h3 id="hotkeys-do-nothing">220<h3 id="hotkeys-do-nothing">
219 핫키가 아무것도 하지 않음221 단축키가 작동하지 않음
220</h3>222</h3>
221 223
222pane에 키보드 포커스가 없습니다.224pane에 키보드 포커스가 없습니다.
223 225
224Ctrl+X를 누른 다음 Tab을 누르거나 pane을 클릭합니다. `focus: true`로 명령에서 열기합니다.226Ctrl+X를 누른 다음 Tab을 누르거나 pane을 클릭합니다. 명령에서 `focus: true`로 pane을 엽니다.
225 227
226<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">228<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">
227 그리기가 터미널에서 작동하고 Desktop 앱에서는 작동하지 않음229 그림이 터미널에서는 작동하지만 Desktop 앱에서는 작동하지 않음
228</h3>230</h3>
229 231
230사이트 또는 요소를 사용할 수 없습니다.232해당 지점 또는 요소를 Desktop 앱에서 사용할 수 없습니다.
231 233
232[렌더 사이트](/docs/ko/plugins/mods/reference#render-sites) 및 [요소](/docs/ko/plugins/mods/reference#elements) 테이블을 확인합니다.234[렌더링 지점](/docs/ko/plugins/mods/reference#render-sites) 및 [요소](/docs/ko/plugins/mods/reference#elements) 표를 확인하세요.
233 235
234<h2 id="an-edit-or-a-value-is-lost">236<h2 id="an-edit-or-a-value-is-lost">
235 편집 또는 값이 손실됨237 편집 내용이나 값이 사라짐
236</h2>238</h2>
237 239
238mod이 실행되고 변경하거나 유지한 값이 없습니다.240mod가 실행되지만, 사용자가 적용한 변경 사항이나 mod가 유지하던 값이 없습니다.
239 241
240<h3 id="your-edits-don’t-take-effect">242<h3 id="your-edits-don’t-take-effect">
241 편집이 적용되지 않음243 편집 내용이 적용되지 않음
242</h3>244</h3>
243 245
244설치한 플러그인을 편집하고 있습니다. Claude Code는 설치된 버전의 캐시된 복사본을 실행합니다.246설치한 플러그인을 편집하고 있는 경우입니다. Claude Code는 설치된 버전의 캐시된 사본을 실행합니다.
245 247
246`claude --plugin-dir ./first-mod`와 같이 작업 복사본을 가리키는 `--plugin-dir`로 개발합니다. 이는 저장할 때 다시 로드됩니다.248`claude --plugin-dir ./first-mod`와 같이 `--plugin-dir`을 작업 사본으로 지정하여 개발하면, 저장할 때마다 다시 로드됩니다.
247 249
248<h3 id="a-value-resets-when-the-module-reloads">250<h3 id="a-value-resets-when-the-module-reloads">
249 모듈이 다시 로드될 때 값이 재설정됨251 모듈이 다시 로드될 때 값이 초기화됨
250</h3>252</h3>
251 253
252모듈 수준 변수는 각 다시 로드 시 다시 초기화됩니다.254모듈 수준 변수는 다시 로드될 때마다 다시 초기화됩니다.
253 255
254[값을 `$.state` 또는 `$.store`에 유지합니다](/docs/ko/plugins/mods/interface#keep-state).256[값을 `$.state` 또는 `$.store`에 보관합니다](/docs/ko/plugins/mods/interface#keep-state).
255 257
256<h3 id="a-value-resets-after-/clear-/resume-or-/branch">258<h3 id="a-value-resets-after-/clear-/resume-or-/branch">
257 `/clear`, `/resume` 또는 `/branch` 후 값이 재설정됨259 `/clear`, `/resume` 또는 `/branch` 이후 값이 초기화됨
258</h3>260</h3>
259 261
260값이 재설정되거나 저장된 값이 기본값으로 대체됩니다. 이러한 각 명령은 `$.state`를 기본값으로 재설정하며, `session.start`는 다시 실행되지 않습니다.262값이 초기화되거나, 저장된 값이 기본값으로 대체됩니다. 이러한 명령은 각각 `$.state`를 기본값으로 재설정하며, `session.start`는 다시 발생하지 않습니다.
261 263
262[`classic.SessionStart` hook에서 저장된 값을 다시 로드합니다](/docs/ko/plugins/mods/interface#load-a-saved-value-again-after-clear).264`classic.SessionStart` 훅에서 [저장된 값을 다시 로드합니다](/docs/ko/plugins/mods/interface#load-a-saved-value-again-after-clear).
263 265
264<h2 id="read-the-debug-log">266<h2 id="read-the-debug-log">
265 디버그 로그 읽기267 디버그 로그 읽기
266</h2>268</h2>
267 269
268디버그 로그에는 Claude Code가 로드하거나 거부하는 모든 모듈, 실패하는 모든 hook, 거부하는 모든 결과에 대한 줄이 있으므로 트랜스크립트가 아무것도 표시하지 않을 때 볼 위치입니다. 하나를 작성하려면 셸에서 `--debug`로 Claude Code를 시작하거나 `--debug-file <path>`로 위치를 선택합니다:270디버그 로그에는 Claude Code가 로드하거나 거부하는 모든 모듈, 실패하는 모든 훅, 거부하는 모든 결과에 대한 줄이 기록되므로, 트랜스크립트에 아무것도 표시되지 않을 때 확인할 곳입니다. 로그를 작성하려면 셸에서 `--debug`로 Claude Code를 시작하거나, 저장 위치를 지정하려면 `--debug-file <path>`로 시작합니다:
269 271
270```bash theme={null}272```bash theme={null}
271claude --debug-file ./mod-debug.log --plugin-dir ./first-mod273claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
272```274```
273 275
274다른 터미널에서 파일을 따르고 mod의 이름으로 필터링합니다:276다른 터미널에서 파일을 따라가며 mod 이름으로 필터링합니다:
275 277
276```bash theme={null}278```bash theme={null}
277tail -f ./mod-debug.log | grep first-mod279tail -f ./mod-debug.log | grep first-mod
278```280```
279 281
280로드된 mod에는 이름을 지정하고 hook하는 이벤트를 나열하는 줄이 있습니다. `--plugin-dir`로 로드된 mod은 이름 뒤에 `@inline`으로 나타납니다:282로드된 mod에는 해당 mod의 이름을 표시하고 처리하는 이벤트를 나열하는 줄이 있습니다. `--plugin-dir`로 로드된 mod는 이름 뒤에 `@inline`이 붙어 표시됩니다:
281 283
282```text theme={null}284```text theme={null}
283hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render285hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
284```286```
285 287
286유효성 검사를 통과하지 못한 그리기는 거부된 결과로 계산되며 줄도 가져옵니다. 로그에 자신의 줄을 작성하려면 [`$.ui.log`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)를 두 번째 인수와 함께 호출합니다(예: `$.ui.log('message', { to: 'debug' })`). 두 번째 인수 없이 `$.ui.log`는 트랜스크립트에 흐린 줄을 추가합니다.288유효성 검사를 통과하지 못한 드로잉도 거부된 결과로 간주되어 줄이 기록됩니다. 로그에 직접 줄을 작성하려면 `$.ui.log('message', { to: 'debug' })`처럼 두 번째 인수와 함께 [`$.ui.log`](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)를 호출합니다. 두 번째 인수가 없으면 `$.ui.log`는 트랜스크립트에 흐린 줄을 추가합니다.
287 289
288`--plugin-dir`로 로드된 mod을 편집하는 동안 트랜스크립트는 mod의 이름을 지정하고 해당 hook을 나열하는 각 다시 로드에 대한 줄을 표시합니다. 저장이 모듈을 손상시키면 줄은 `reload failed, the previous version stays loaded:`를 이유와 함께 말하며, 마지막 작동 버전이 계속 실행됩니다.290`--plugin-dir`로 로드된 mod를 편집하는 동안, 트랜스크립트에는 다시 로드할 때마다 mod의 이름을 표시하고 해당 훅을 나열하는 줄이 나타납니다. 저장으로 인해 모듈이 손상되면 해당 줄에 이유와 함께 `reload failed, the previous version stays loaded:`가 표시되며, 마지막으로 정상 작동한 버전이 계속 실행됩니다.
289 291
290<h2 id="next-steps">292<h2 id="next-steps">
291 다음 단계293 다음 단계
292</h2>294</h2>
293 295
294* [mod 테스트](/docs/ko/plugins/mods/test): 문제가 세션에 도달하기 전에 포착합니다296* [mod 테스트하기](/docs/ko/plugins/mods/test): 문제가 세션에 도달하기 전에 미리 발견합니다
295* [플러그인 문제 해결](/docs/ko/plugins/troubleshooting): mod에 특정하지 않은 플러그인 설치 및 로드 문제297* [플러그인 문제 해결](/docs/ko/plugins/troubleshooting): mod에 국한되지 않는 플러그인 설치 및 로드 관련 문제를 해결합니다
