83| `Your account does not have access to Claude. Please login again or contact your administrator.` | [인증](#oauth-token-revoked-or-expired) |83| `Your account does not have access to Claude. Please login again or contact your administrator.` | [인증](#oauth-token-revoked-or-expired) |
84| `API Error: 401 Invalid authentication credentials` | [인증](#api-error-401-invalid-authentication-credentials) |84| `API Error: 401 Invalid authentication credentials` | [인증](#api-error-401-invalid-authentication-credentials) |
85| `Login expired · Please run /login` | [인증](#login-expired) |85| `Login expired · Please run /login` | [인증](#login-expired) |
86| `The browser can't return the sign-in to Claude Code automatically` | [인증](#couldnt-start-the-local-sign-in-listener) |
87| `Couldn't start the local listener that receives the browser sign-in. Try again.` | [인증](#couldnt-start-the-local-sign-in-listener) |
86| `Failed to start OAuth callback server` | [인증](#failed-to-start-oauth-callback-server) |88| `Failed to start OAuth callback server` | [인증](#failed-to-start-oauth-callback-server) |
87| `Claude login not accepted · Run /login, then try again` | [인증](#claude-login-not-accepted) |89| `Claude login not accepted · Run /login, then try again` | [인증](#claude-login-not-accepted) |
88| `Artifacts need a claude.ai login` | [인증](#artifacts-need-a-claude-ai-login) |90| `Artifacts need a claude.ai login` | [인증](#artifacts-need-a-claude-ai-login) |
100| `claude.ai rejected the session token` / `session token rejected` | [인증](#claude-ai-rejected-the-session-token) |102| `claude.ai rejected the session token` / `session token rejected` | [인증](#claude-ai-rejected-the-session-token) |
101| `MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)` | [인증](#mcp-server-needs-you-to-sign-in-again) |103| `MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)` | [인증](#mcp-server-needs-you-to-sign-in-again) |
102| `rejected the credential from its headersHelper` / `rejected the Authorization header in its config` | [인증](#mcp-server-needs-you-to-sign-in-again) |104| `rejected the credential from its headersHelper` / `rejected the Authorization header in its config` | [인증](#mcp-server-needs-you-to-sign-in-again) |
105| `(check the helper, then start a new task or chat)` / `(update it, then start a new task or chat)` | [인증](#mcp-credential-rejected-in-cowork) |
103| `MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate` | [인증](#mcp-server-needs-you-to-sign-in-again) |106| `MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate` | [인증](#mcp-server-needs-you-to-sign-in-again) |
104| `MCP server "<name>" requires re-authorization (token expired)` | [인증](#mcp-server-needs-you-to-sign-in-again) |107| `MCP server "<name>" requires re-authorization (token expired)` | [인증](#mcp-server-needs-you-to-sign-in-again) |
105| `This server's URL is missing or not a valid URL, so sign-in can't start` | [인증](#mcp-server-url-is-missing-or-not-a-valid-url) |108| `This server's URL is missing or not a valid URL, so sign-in can't start` | [인증](#mcp-server-url-is-missing-or-not-a-valid-url) |
200| `Installation was killed before it could finish (exit code 137)` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#installation-was-killed-before-it-could-finish) |203| `Installation was killed before it could finish (exit code 137)` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#installation-was-killed-before-it-could-finish) |
201| `The connection dropped while downloading the update` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |204| `The connection dropped while downloading the update` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |
202| `Download timed out: exceeded the total deadline` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |205| `Download timed out: exceeded the total deadline` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |
206| `Release verification failed for Claude Code <version> (<reason>). The update was not installed.` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#release-verification-failed) |
207| `Auto-update failed · Run claude doctor` | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#auto-update-failed) |
203| `--bg and --print conflict` | [명령줄 오류](#conflict-between-bg-and-print) |208| `--bg and --print conflict` | [명령줄 오류](#conflict-between-bg-and-print) |
204| `Couldn't tell whether --bg is a flag or text here, so nothing was started` | [명령줄 오류](#couldnt-tell-whether-bg-is-a-flag-or-text) |209| `Couldn't tell whether --bg is a flag or text here, so nothing was started` | [명령줄 오류](#couldnt-tell-whether-bg-is-a-flag-or-text) |
205| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [명령줄 오류](#conflict-between-a-system-prompt-flag-and-its-file-form) |210| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [명령줄 오류](#conflict-between-a-system-prompt-flag-and-its-file-form) |
270| `Custom output styles can't be selected over Remote Control or from a relayed message` | [명령줄 오류](#custom-output-styles-cant-be-selected-over-remote-control) |275| `Custom output styles can't be selected over Remote Control or from a relayed message` | [명령줄 오류](#custom-output-styles-cant-be-selected-over-remote-control) |
271| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [명령줄 오류](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |276| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [명령줄 오류](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |
272| `/recap only runs when you ask for it yourself in this session` | [명령줄 오류](#recap-only-runs-when-you-ask-for-it-yourself) |277| `/recap only runs when you ask for it yourself in this session` | [명령줄 오류](#recap-only-runs-when-you-ask-for-it-yourself) |
278| `/feedback is disabled by your organization's policy`, 또는 `/bug`나 `/share`에 대한 동일한 메시지 | [명령줄 오류](#feedback-is-disabled-by-your-organizations-policy) |
273| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [플러그인 오류](#plugin-eval-is-currently-in-early-access) |279| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [플러그인 오류](#plugin-eval-is-currently-in-early-access) |
274| `cannot be evaluated where sessions load it` | [eval로 플러그인 테스트](/docs/ko/plugin-evals#cannot-be-evaluated-where-sessions-load-it) |280| `cannot be evaluated where sessions load it` | [eval로 플러그인 테스트](/docs/ko/plugin-evals#cannot-be-evaluated-where-sessions-load-it) |
275| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |281| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |
289| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#the-packages-it-lists-are-not-installed) |295| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#the-packages-it-lists-are-not-installed) |
290| `does not load (...), so Claude Code ignores the whole file` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#does-not-load-so-claude-code-ignores-the-whole-file) |296| `does not load (...), so Claude Code ignores the whole file` | [플러그인 문제 해결](/docs/ko/plugins/troubleshooting#does-not-load-so-claude-code-ignores-the-whole-file) |
291| `path escapes plugin directory` | [플러그인 오류](#path-escapes-plugin-directory) |297| `path escapes plugin directory` | [플러그인 오류](#path-escapes-plugin-directory) |
298| `Plugin not loaded: its manifest <path> was not read` | [플러그인 오류](#plugin-not-loaded-its-manifest-was-not-read) |
292| `path could not be checked` | [플러그인 오류](#path-could-not-be-checked) |299| `path could not be checked` | [플러그인 오류](#path-could-not-be-checked) |
293| `its marketplace entry path does not stay inside the marketplace directory` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |300| `its marketplace entry path does not stay inside the marketplace directory` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |
294| `Plugin source path refused` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |301| `Plugin source path refused` | [플러그인 오류](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |
304| `File is covered by a Read deny rule in your permission settings` | [도구 오류](#file-is-covered-by-a-read-deny-rule) |311| `File is covered by a Read deny rule in your permission settings` | [도구 오류](#file-is-covered-by-a-read-deny-rule) |
305| `cannot contain null bytes (\0)` | [도구 오류](#path-cannot-contain-null-bytes) |312| `cannot contain null bytes (\0)` | [도구 오류](#path-cannot-contain-null-bytes) |
306| `Path contains null bytes` | [도구 오류](#path-cannot-contain-null-bytes) |313| `Path contains null bytes` | [도구 오류](#path-cannot-contain-null-bytes) |
314| `File is too large to read as an image (the limit is 128MB)` | [도구 오류](#file-is-too-large-to-read-as-an-image) |
315| `Cannot read this as an image: <path> is a pipe or a device` | [도구 오류](#file-is-too-large-to-read-as-an-image) |
307| `subagent_type is required: the general-purpose agent is not available in this session` | [도구 오류](#subagent-type-is-required) |316| `subagent_type is required: the general-purpose agent is not available in this session` | [도구 오류](#subagent-type-is-required) |
308| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [도구 오류](#memory-index-is-over-its-read-limit) |317| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [도구 오류](#memory-index-is-over-its-read-limit) |
309| `pkill: refusing to run` | [도구 오류](#pkill-pattern-matches-the-claude-code-process) |318| `pkill: refusing to run` | [도구 오류](#pkill-pattern-matches-the-claude-code-process) |
310| `Failed to write to <name>'s inbox — nothing was sent` | [도구 오류](#failed-to-write-to-a-teammate-inbox) |319| `Failed to write to <name>'s inbox — nothing was sent` | [도구 오류](#failed-to-write-to-a-teammate-inbox) |
311| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [도구 오류](#failed-to-write-to-a-teammate-inbox) |320| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [도구 오류](#failed-to-write-to-a-teammate-inbox) |
312| `Its agent definition was not restored: the folder its definition file came from is not trusted` | [도구 오류](#teammate-agent-definition-not-restored) |321| `Its agent definition was not restored: the folder its definition file came from is not trusted` | [도구 오류](#teammate-agent-definition-not-restored) |
322| `Only a teammate can approve a shutdown request` | [도구 오류](#only-a-teammate-can-approve-a-shutdown-request) |
313| `Message too large for cross-session delivery` | [도구 오류](#message-too-large-for-cross-session-delivery) |323| `Message too large for cross-session delivery` | [도구 오류](#message-too-large-for-cross-session-delivery) |
314| `Too many messages to this session just now` | [도구 오류](#too-many-messages-to-this-session-just-now) |324| `Too many messages to this session just now` | [도구 오류](#too-many-messages-to-this-session-just-now) |
315| `Cross-session message was dropped at the recipient session's inbox` | [도구 오류](#cross-session-message-dropped-at-the-inbox) |325| `Cross-session message was dropped at the recipient session's inbox` | [도구 오류](#cross-session-message-dropped-at-the-inbox) |
325| `Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |335| `Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |
326| `The filesystem with Claude Code's temp directory <dir>, or your disk quota on it, is full (ENOSPC)` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |336| `The filesystem with Claude Code's temp directory <dir>, or your disk quota on it, is full (ENOSPC)` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |
327| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |337| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |
338| `The command was not started: this computer's disk is full (ENOSPC)` / `(EDQUOT)` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |
328| `File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary` | [도구 오류](#file-is-not-valid-utf-8) |339| `File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary` | [도구 오류](#file-is-not-valid-utf-8) |
329| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |340| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |
330| `the source file has the replacement character U+FFFD` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |341| `the source file has the replacement character U+FFFD` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |
331| `Not published: that file is on a network share` | [도구 오류](#not-published-that-file-is-on-a-network-share) |342| `Not published: that file is on a network share` | [도구 오류](#not-published-that-file-is-on-a-network-share) |
343| `Not published: Claude sent the same content again after a newer version of the artifact turned it away` / `Not published: Claude sent its changes again over the same file after a newer version of the artifact turned them away` | [도구 오류](#not-published-a-newer-version-of-the-artifact-turned-it-away) |
332| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |344| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |
333| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |345| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [도구 오류](#reading-a-local-file-from-outside-the-connected-folders) |
334| `WebFetch cannot fetch localhost or other hostnames without a dot` | [도구 오류](#webfetch-cannot-fetch-localhost) |346| `WebFetch cannot fetch localhost or other hostnames without a dot` | [도구 오류](#webfetch-cannot-fetch-localhost) |
345| `Can't open — this session is running in another terminal` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |357| `Can't open — this session is running in another terminal` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |
346| `This conversation is already open in another running Claude session` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |358| `This conversation is already open in another running Claude session` | [백그라운드 세션 오류](#this-session-is-running-in-another-terminal) |
347| `This session's saved conversation is no longer on disk` | [백그라운드 세션 오류](#this-sessions-saved-conversation-is-no-longer-on-disk) |359| `This session's saved conversation is no longer on disk` | [백그라운드 세션 오류](#this-sessions-saved-conversation-is-no-longer-on-disk) |
348| `Bypass permissions was requested at launch and ignored` | [bypassPermissions 모드로 모든 검사 건너뛰기](/docs/ko/permission-modes#bypass-permissions-acceptance) |360| `Bypass permissions was requested at launch and ignored` | [백그라운드 세션에서 권한 우회가 무시됨](/docs/ko/permission-modes#bypass-permissions-ignored-in-a-background-session) |
349| `kept <id> — its worktree is still at <path>` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |361| `kept <id> — its worktree is still at <path>` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |
350| `kept <id> — <n> unpushed commits on <branch>` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |362| `kept <id> — <n> unpushed commits on <branch>` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |
351| `kept <id> — worktree has commits that are not pushed anywhere` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |363| `kept <id> — worktree has commits that are not pushed anywhere` | [백그라운드 세션 오류](#worktree-has-commits-that-are-not-pushed-anywhere) |
354| `Session <id> was stopped while the respawn was in flight` | [백그라운드 세션 오류](#session-was-stopped-while-the-respawn-was-in-flight) |366| `Session <id> was stopped while the respawn was in flight` | [백그라운드 세션 오류](#session-was-stopped-while-the-respawn-was-in-flight) |
355| `This session was running agent '<name>', which is no longer available` | [백그라운드 세션 오류](#session-agent-no-longer-available) |367| `This session was running agent '<name>', which is no longer available` | [백그라운드 세션 오류](#session-agent-no-longer-available) |
356| `This session restarted <time> after its next /loop wakeup was due, so that wakeup will not fire` | [백그라운드 세션 오류](#restarted-after-its-next-loop-wakeup-was-due) |368| `This session restarted <time> after its next /loop wakeup was due, so that wakeup will not fire` | [백그라운드 세션 오류](#restarted-after-its-next-loop-wakeup-was-due) |
369| `No LLM gateway: a gateway set in your shell isn't passed to a session opened from another folder` | [백그라운드 세션 오류](#no-llm-gateway-opened-from-another-folder) |
370| `No LLM gateway: opened from another folder · respawn from <folder>` | [백그라운드 세션 오류](#no-llm-gateway-opened-from-another-folder) |
357| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [백그라운드 세션 오류](#claude_code_process_wrapper-launcher-errors) |371| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [백그라운드 세션 오류](#claude_code_process_wrapper-launcher-errors) |
358| `EUNKNOWN: unknown error, uv_spawn` | [백그라운드 세션 오류](#eunknown-when-starting-a-background-session) |372| `EUNKNOWN: unknown error, uv_spawn` | [백그라운드 세션 오류](#eunknown-when-starting-a-background-session) |
359| `EACCES: permission denied, posix_spawn` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |373| `EACCES: permission denied, posix_spawn` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |
394| `API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name` | [구성 경고](#anthropic-foundry-resource-must-be-a-foundry-resource-name) |408| `API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name` | [구성 경고](#anthropic-foundry-resource-must-be-a-foundry-resource-name) |
395| `headersHelper not run — this workspace has no persisted trust` | [구성 경고](#headershelper-not-run) |409| `headersHelper not run — this workspace has no persisted trust` | [구성 경고](#headershelper-not-run) |
396| `Invalid permission rule "..." was skipped: Malformed Tool(content) rule` | [구성 경고](#malformed-tool-content-rule) |410| `Invalid permission rule "..." was skipped: Malformed Tool(content) rule` | [구성 경고](#malformed-tool-content-rule) |
411| `matches no tool · check for typos` / `matches no known tool — check for typos` | [구성 경고](#matches-no-tool) |
397| `... is not matched by file permission checks` | [구성 경고](#is-not-matched-by-file-permission-checks) |412| `... is not matched by file permission checks` | [구성 경고](#is-not-matched-by-file-permission-checks) |
413| `Write(<path>) never matches · use Edit(<path>)` / `Glob(<path>) never matches · use Read(<path>)` | [구성 경고](#is-not-matched-by-file-permission-checks) |
398| `... has a wildcard before the rest of the command` | [구성 경고](#has-a-wildcard-before-the-rest-of-the-command) |414| `... has a wildcard before the rest of the command` | [구성 경고](#has-a-wildcard-before-the-rest-of-the-command) |
415| `allows any option at its * · use an exact value` | [구성 경고](#has-a-wildcard-before-the-rest-of-the-command) |
399| `Denying Bash also turns off the PowerShell tool, so Claude has neither` | [구성 경고](#denying-bash-also-turns-off-the-powershell-tool) |416| `Denying Bash also turns off the PowerShell tool, so Claude has neither` | [구성 경고](#denying-bash-also-turns-off-the-powershell-tool) |
400| `CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced` | [구성 경고](#the-200k-limit-isnt-enforced) |417| `CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced` | [구성 경고](#the-200k-limit-isnt-enforced) |
418| `CLAUDE_CODE_AUTO_COMPACT_WINDOW="<value>" reads as <N> tokens, so Claude Code treats it as the 100k minimum` | [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`의 값 및 경고](/docs/ko/model-config#claude_code_auto_compact_window-values) |
419| `CLAUDE_CODE_AUTO_COMPACT_WINDOW="<value>" is too large, so Claude Code treats it as the 1M maximum` | [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`의 값 및 경고](/docs/ko/model-config#claude_code_auto_compact_window-values) |
420| `CLAUDE_CODE_AUTO_COMPACT_WINDOW="<value>" isn't a usable size, so Claude Code ignores it` | [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`의 값 및 경고](/docs/ko/model-config#claude_code_auto_compact_window-values) |
401| `Model "<model>" isn't recognized · context assumed to be 200k tokens` | [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |421| `Model "<model>" isn't recognized · context assumed to be 200k tokens` | [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |
402| `Claude Code doesn't recognize the model "<model>", so it assumes a context window of 200k tokens` | [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |422| `Claude Code doesn't recognize the model "<model>", so it assumes a context window of 200k tokens` | [게이트웨이 또는 사용자 지정 모델 ID의 윈도우 수정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |
403| `[claude-code:unrecognized_model]` | [구성 경고](#unrecognized-model-id-on-a-request) |423| `[claude-code:unrecognized_model]` | [구성 경고](#unrecognized-model-id-on-a-request) |
462| [`CLAUDE_CODE_MAX_RETRIES`](/docs/ko/env-vars) | 10 | 재시도 횟수입니다. v2.1.186부터 최대 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 스크립트에서 실패를 더 빨리 확인하려면 값을 낮추세요. |482| [`CLAUDE_CODE_MAX_RETRIES`](/docs/ko/env-vars) | 10 | 재시도 횟수입니다. v2.1.186부터 최대 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 스크립트에서 실패를 더 빨리 확인하려면 값을 낮추세요. |
463| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |483| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |
464| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우 각 API 요청이 `429` 및 `529` 오류가 해소되기를 기다리는 최대 시간(밀리초)입니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다. |484| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우 각 API 요청이 `429` 및 `529` 오류가 해소되기를 기다리는 최대 시간(밀리초)입니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다. |
485| [`CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`](/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 상태에서 요청이 [사용 한도](#youve-hit-your-session-limit)가 재설정되기를 기다리는 동안, 해당 한도가 이미 해제되었는지 확인하는 검사 사이의 최소 간격(밀리초)입니다. 검사에서 한도가 해제된 것으로 확인되면 요청이 즉시 전송됩니다. `60000`에서 `10800000` 사이의 숫자만 입력하세요. 설정하지 않거나 해당 범위를 벗어나면 검사를 수행하지 않습니다. Claude Code가 이러한 검사를 건너뛰는 경우는 [환경 변수 참조](/docs/ko/env-vars)를 참조하세요. Claude Code v2.1.305 이상이 필요합니다. |
465| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |486| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |
466| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](/docs/ko/env-vars) | 32000 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 상한(밀리초)입니다. API가 용량 한계에 도달했을 때 이후 재시도 간격이 계속 벌어지도록 하려면 최대 64000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.296 이상이 필요합니다. |487| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](/docs/ko/env-vars) | 32000 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 상한(밀리초)입니다. API가 용량 한계에 도달했을 때 이후 재시도 간격이 계속 벌어지도록 하려면 최대 64000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.296 이상이 필요합니다. |
467| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 각 요청 시도가 응답 헤더를 받기까지 주어지는 시간(밀리초)입니다. 그 이후 스트리밍 응답이 진행되는 시간은 제한하지 않습니다. 느린 네트워크나 프록시의 경우 값을 높이세요. 이 값이 첫 바이트 기한의 상한으로 사용되는 방식은 [No response from API](#no-response-from-api)를 참조하세요. |488| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 각 요청 시도가 응답 헤더를 받기까지 주어지는 시간(밀리초)입니다. 그 이후 스트리밍 응답이 진행되는 시간은 제한하지 않습니다. 느린 네트워크나 프록시의 경우 값을 높이세요. 이 값이 첫 바이트 기한의 상한으로 사용되는 방식은 [No response from API](#no-response-from-api)를 참조하세요. |
490 511
491* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 활성 인시던트를 확인합니다512* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 활성 인시던트를 확인합니다
492* 1분 기다린 후 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신 `try again`을 입력할 수 있습니다.513* 1분 기다린 후 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신 `try again`을 입력할 수 있습니다.
514* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키고 모든 요청이 이런 방식으로 실패하면 게이트웨이가 Claude Code가 기본적으로 보내는 도구 검색 필드를 거부하는지 확인합니다. 확인하려면 [LLM 게이트웨이를 통한 도구 검색](/docs/ko/mcp#tool-search-through-a-gateway)에 설명된 대로 `ENABLE_TOOL_SEARCH=false`를 설정한 후 다시 시도합니다. v2.1.304 이전에는 `ENABLE_TOOL_SEARCH`로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.
493* 오류가 게시된 인시던트 없이 계속되면 `/feedback`을 실행하여 Anthropic이 요청 세부 정보로 조사할 수 있도록 합니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하세요.515* 오류가 게시된 인시던트 없이 계속되면 `/feedback`을 실행하여 Anthropic이 요청 세부 정보로 조사할 수 있도록 합니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하세요.
494 516
495### API 오류: 반복된 529 오버로드 오류517### API 오류: 반복된 529 오버로드 오류
520Request timed out542Request timed out
521```543```
522 544
523기본 요청 타임아웃은 10분입니다.545기본 요청 타임아웃은 10분입니다. [`API_TIMEOUT_MS`](/docs/ko/env-vars)를 `0`으로 설정하면 이 요청 타임아웃이 꺼집니다. [첫 바이트 마감 시간](#no-response-from-api)과 본문 유휴 타임아웃은 `0`으로 설정해도 꺼지지 않으므로, 스트리밍 요청은 여전히 [연결에 적용되는 타임아웃](/docs/ko/network-config#streaming-idle-watchdogs)에 따라 실행됩니다. 비스트리밍 시도는 로컬 세션에서 300초 제한을 유지하므로 여전히 이 메시지로 끝날 수 있습니다.
524 546
525**수행할 작업:**547**수행할 작업:**
526 548
549* 모든 요청이 이 메시지로 실패하고 `API_TIMEOUT_MS`를 `0`으로 설정한 경우 `claude --version`을 확인합니다. v2.1.305 이전 버전이면 Claude Code를 업데이트하거나 양수 값을 설정합니다.
527* 요청을 다시 시도합니다550* 요청을 다시 시도합니다
528* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다551* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다
529* 시간 초과가 빈번하고 네트워크가 정상인 경우 아래의 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하세요552* 시간 초과가 빈번하고 네트워크가 정상인 경우 아래의 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하세요
541* **첫 시도**: 1 이상으로 설정할 때 [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/ko/env-vars), 10초에서 30분 사이로 제한됩니다. 그렇지 않으면 Claude Code는 [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)에 나열된 바이트 수준 감시자 타임아웃을 사용하므로 해당 타임아웃을 변경하는 변수가 이 대기도 변경합니다. 어느 쪽이든 Claude Code는 요청 본문의 32KB마다 1초를 추가합니다.564* **첫 시도**: 1 이상으로 설정할 때 [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/ko/env-vars), 10초에서 30분 사이로 제한됩니다. 그렇지 않으면 Claude Code는 [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)에 나열된 바이트 수준 감시자 타임아웃을 사용하므로 해당 타임아웃을 변경하는 변수가 이 대기도 변경합니다. 어느 쪽이든 Claude Code는 요청 본문의 32KB마다 1초를 추가합니다.
542* **재시도**: `API_TIMEOUT_MS`보다 1초 적게, 기본값으로 거의 10분이므로 재시도가 응답을 생성이 완료될 때까지 보유하는 프록시 또는 게이트웨이를 초과할 수 있습니다. Amazon Bedrock에서 재시도는 첫 시도와 동일한 마감 시간을 사용하며 메시지는 두 가지 대신 하나의 기간을 표시합니다.565* **재시도**: `API_TIMEOUT_MS`보다 1초 적게, 기본값으로 거의 10분이므로 재시도가 응답을 생성이 완료될 때까지 보유하는 프록시 또는 게이트웨이를 초과할 수 있습니다. Amazon Bedrock에서 재시도는 첫 시도와 동일한 마감 시간을 사용하며 메시지는 두 가지 대신 하나의 기간을 표시합니다.
543 566
567 Amazon Bedrock을 제외하고, `API_TIMEOUT_MS`를 `0`으로 설정하면 재시도는 10분에 32KB당 1초를 더한 시간 동안 대기하며, 첫 시도의 대기가 더 길면 첫 시도만큼 대기합니다.
568
544어느 대기도 양수 `API_TIMEOUT_MS`보다 1초 적은 값을 초과하지 않으며, 11초 미만의 양수 `API_TIMEOUT_MS`는 마감 시간을 끕니다. 바이트 수준 감시자는 응답 헤더가 도착한 후에만 시작되므로 그 후 바이트 전송을 중지하는 응답은 이 마감 시간 대신 [정지된 스트림 규칙](#automatic-retries)을 따릅니다.569어느 대기도 양수 `API_TIMEOUT_MS`보다 1초 적은 값을 초과하지 않으며, 11초 미만의 양수 `API_TIMEOUT_MS`는 마감 시간을 끕니다. 바이트 수준 감시자는 응답 헤더가 도착한 후에만 시작되므로 그 후 바이트 전송을 중지하는 응답은 이 마감 시간 대신 [정지된 스트림 규칙](#automatic-retries)을 따릅니다.
545 570
546**수행할 작업:**571**수행할 작업:**
845* `/status`를 실행하여 활성 자격 증명이 예상한 것인지 확인합니다. 환경에 남아 있는 `ANTHROPIC_API_KEY`로 인해 요청이 구독 대신 낮은 티어의 키를 통해 라우팅될 수 있습니다.870* `/status`를 실행하여 활성 자격 증명이 예상한 것인지 확인합니다. 환경에 남아 있는 `ANTHROPIC_API_KEY`로 인해 요청이 구독 대신 낮은 티어의 키를 통해 라우팅될 수 있습니다.
846* 제공업체 콘솔에서 활성 한도를 확인하고 필요한 경우 더 높은 티어를 요청합니다871* 제공업체 콘솔에서 활성 한도를 확인하고 필요한 경우 더 높은 티어를 요청합니다
847* Anthropic API 키의 경우 티어의 작동 방식과 워크스페이스별 상한을 설정하는 방법은 [속도 제한 참조](https://platform.claude.com/docs/en/api/rate-limits)를 확인하세요872* Anthropic API 키의 경우 티어의 작동 방식과 워크스페이스별 상한을 설정하는 방법은 [속도 제한 참조](https://platform.claude.com/docs/en/api/rate-limits)를 확인하세요
848* 동시성을 줄입니다. [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/ko/env-vars)를 낮추거나, 여러 서브에이전트를 병렬로 실행하지 않거나, 대량 스크립트 실행 시 `/model`로 더 작은 모델로 전환합니다873* 동시성을 줄입니다. 여러 서브에이전트를 병렬로 실행하지 않거나, 대량 스크립트 실행 시 `/model`로 더 작은 모델로 전환합니다
849 874
850### You've hit your monthly spend limit875### You've hit your monthly spend limit
851 876
1267* `/status`에 로그인만 표시된다면 `/login`을 한 번 실행합니다. 자격 증명이 폐기된 경우 새 로그인이 이를 대체합니다.1292* `/status`에 로그인만 표시된다면 `/login`을 한 번 실행합니다. 자격 증명이 폐기된 경우 새 로그인이 이를 대체합니다.
1268* 같은 로그인 계정에 대해 같은 메시지가 다시 나타나면 계정이나 조직이 더 이상 활성 상태가 아닙니다. `/status`가 보고하는 계정과 조직을 확인하고, 조직 관리자에게 액세스 복원을 요청합니다.1293* 같은 로그인 계정에 대해 같은 메시지가 다시 나타나면 계정이나 조직이 더 이상 활성 상태가 아닙니다. `/status`가 보고하는 계정과 조직을 확인하고, 조직 관리자에게 액세스 복원을 요청합니다.
1269* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키는 경우, `401` 뒤의 텍스트는 Anthropic이 아닌 게이트웨이의 메시지이며 `/login`으로 바뀌지 않습니다. 대신 게이트웨이가 요구하는 자격 증명을 수정합니다.1294* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키는 경우, `401` 뒤의 텍스트는 Anthropic이 아닌 게이트웨이의 메시지이며 `/login`으로 바뀌지 않습니다. 대신 게이트웨이가 요구하는 자격 증명을 수정합니다.
1295* 게이트웨이에 필요한 자격 증명을 제공했는데도 모든 요청이 `401`로 실패한다면, Claude Code가 기본적으로 보내는 도구 검색 필드를 게이트웨이가 거부하고 있는지 확인합니다. 확인하려면 [LLM 게이트웨이를 통한 도구 검색](/docs/ko/mcp#tool-search-through-a-gateway)에 설명된 대로 `ENABLE_TOOL_SEARCH=false`를 설정한 다음 다시 시도합니다. v2.1.304 이전에는 `ENABLE_TOOL_SEARCH`로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.
1270 1296
1271### 로그인 만료1297### 로그인 만료
1272 1298
1338* 다른 플랫폼에서는 `/login`을 다시 실행합니다1364* 다른 플랫폼에서는 `/login`을 다시 실행합니다
1339* 로그인이 여전히 저장되지 않으면, 키체인 잠금 해제 명령과 기타 자격 증명 저장소 복구 단계는 [로그인되지 않음 또는 토큰 만료](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오1365* 로그인이 여전히 저장되지 않으면, 키체인 잠금 해제 명령과 기타 자격 증명 저장소 복구 단계는 [로그인되지 않음 또는 토큰 만료](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오
1340 1366
1341### OAuth 콜백 서버를 시작하지 못함1367### Couldn't start the local listener that receives the browser sign-in
1342 1368
1343`/login`, `claude auth login` 또는 `claude setup-token`이 브라우저를 통해 로그인할 때, Claude Code는 브라우저가 로그인 결과를 돌려보낼 수 있도록 `127.0.0.1`에 수신 포트를 엽니다. 이 메시지는 Claude Code가 해당 포트를 열 수 없었다는 뜻이며, 브라우저 창이나 로그인 URL이 나타나기 전에 로그인이 중단됩니다.1369`/login`, `claude auth login` 또는 `claude setup-token`에서 표시되는 다음 메시지들은 모두 Claude Code가 브라우저가 로그인 결과를 반환하는 `127.0.0.1`의 포트를 열 수 없었다는 의미입니다.
1344 1370
1345```text theme={null}1371`The browser can't return the sign-in to Claude Code automatically`로 시작하는 알림이 표시되면, 로그인은 해당 포트 없이 계속 진행됩니다. 브라우저는 열리지 않으며, 알림은 대신 로그인할 URL 위에 표시됩니다.
1346Failed to start OAuth callback server: Failed to start server. Is port 0 in use?1372
1373```text wrap theme={null}
1374The browser can't return the sign-in to Claude Code automatically. After you sign in, paste the code shown.
1347```1375```
1348 1376
1349메시지가 `Is port 0 in use?`로 끝나면 IPv4 루프백 주소 `127.0.0.1`에서 수신하려는 시도가 완전히 실패한 것입니다. 로그인 URL이 생성되기 전에 실패하므로 `Paste code here if prompted` 흐름을 해결 방법으로 사용할 수 없습니다.1377`Couldn't start the local listener`가 포함된 메시지가 표시되면 로그인이 중단된 것입니다. 예를 들어 `claude auth login`에 입력을 파이프로 전달하는 경우 이런 일이 발생합니다.
1378
1379```text theme={null}
1380Couldn't start the local listener that receives the browser sign-in. Try again.
1381```
1350 1382
1351**해결 방법:**1383**해결 방법:**
1352 1384
1353* 로컬 수신기 없이 바로 로그인하려면: claude.ai 구독을 사용하는 경우 로그인이 작동하는 머신에서 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)을 실행하고, 출력된 토큰을 이 머신에서 `CLAUDE_CODE_OAUTH_TOKEN`으로 설정합니다. 그렇지 않으면 `ANTHROPIC_API_KEY`를 [Claude Console](https://platform.claude.com/settings/keys)의 키로 설정합니다. Claude Code가 자격 증명 중에서 선택하는 방식은 [인증 우선순위](/docs/ko/authentication#authentication-precedence)에서 설명합니다.1385* **`The browser can't return the sign-in to Claude Code automatically`**: 먼저 수정할 것은 없습니다. 알림 아래에 표시된 URL을 브라우저에서 열고 로그인합니다. 그러면 브라우저에 코드가 표시됩니다. `Paste code here >` 프롬프트에서 Claude Code에 코드를 붙여 넣으면 로그인이 계속 진행됩니다.
1354* 대신 이 머신에서 브라우저 로그인을 사용하려면 Claude Code가 `127.0.0.1`에서 수신할 수 있어야 합니다. 샌드박스 안에서 실행되는 경우 샌드박스 정책이 로컬 포트 수신을 허용하는지 확인한 다음 `/login`을 다시 실행합니다. 수신할 수 있어야 하는데도 계속 실패하면 `/feedback`을 실행하여 보고서에 환경 세부 정보가 포함되도록 합니다.1386* **`Couldn't start the local listener that receives the browser sign-in`**: 같은 명령을 다시 실행합니다. 같은 방식으로 중단되면 브라우저 대신 토큰이나 API 키로 로그인합니다. 또는 `claude auth login`에 입력을 파이프로 전달했다면, 붙여 넣은 코드를 받을 수 있도록 터미널에서 실행합니다.
1387* **브라우저 대신 토큰이나 API 키로 로그인하려면**: claude.ai 구독을 사용한다면 로그인이 작동하는 머신에서 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)을 실행합니다. 그런 다음 출력된 토큰을 이 머신에서 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 환경 변수로 설정합니다. 그렇지 않다면 `ANTHROPIC_API_KEY` 환경 변수를 [Claude Console](https://platform.claude.com/settings/keys)의 키로 설정합니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)에서 Claude Code가 자격 증명 중 무엇을 선택하는지 설명합니다.
1388* **브라우저 자동 반환을 다시 사용하려면**: Claude Code가 `127.0.0.1`에서 수신 대기할 수 있어야 합니다. 샌드박스 안에서 실행 중이라면 샌드박스 정책이 로컬 포트 수신 대기를 허용하는지 확인한 다음 다시 로그인합니다. 수신 대기가 가능해야 하는 환경인데도 알림이 계속 표시된다면, 보고서에 환경 세부 정보가 포함되도록 `/feedback`을 실행합니다.
1389
1390v2.1.305 이전에는 포트를 열 수 없으면 즉시 로그인이 중단되었고 로그인할 URL도 표시되지 않았습니다. 메시지는 예를 들어 `Failed to start OAuth callback server: Failed to start server. Is port 0 in use?`와 같았습니다. 해당 버전에서는 Claude Code를 업데이트하고 다시 로그인하거나, 브라우저 대신 토큰이나 API 키로 로그인하십시오.
1355 1391
1356### Claude 로그인이 수락되지 않음1392### Claude 로그인이 수락되지 않음
1357 1393
1513 1549
1514서버가 구성된 위치에서 헤더 값을 업데이트한 다음 `/mcp`에서 다시 연결합니다.1550서버가 구성된 위치에서 헤더 값을 업데이트한 다음 `/mcp`에서 다시 연결합니다.
1515 1551
1516v2.1.273 이전에는 만료된 로그인, `headersHelper`, `Authorization` 헤더의 경우 모두 `MCP server "<name>" requires re-authorization (token expired)`가 표시되었습니다.1552Claude Desktop 앱에서 사용자의 머신에서 실행되는 [Cowork](https://claude.com/docs/cowork/overview) 세션의 경우, 다음 메시지는 MCP 서버가 제공받은 자격 증명을 거부했다는 의미입니다. 메시지에 표시된 항목을 수정한 후 Cowork에서 새 작업이나 채팅을 시작합니다.
1553
1554```text theme={null}
1555MCP server "<name>" rejected the credential from its headersHelper (check the helper, then start a new task or chat)
1556MCP server "<name>" rejected the Authorization header in its config (update it, then start a new task or chat)
1557```
1558
1559* **`headersHelper` 자격 증명 거부**: 헬퍼가 서버에서 받아들이는 자격 증명을 반환하는지 확인한 후 Cowork에서 새 작업이나 채팅을 시작합니다
1560* **`Authorization` 헤더 거부**: 해당 서버 구성의 `headers` 아래에 있는 `Authorization` 값을 업데이트한 후 Cowork에서 새 작업이나 채팅을 시작합니다
1561
1562v2.1.302 이전에는 Cowork 세션에서 `/mcp`를 사용할 수 없는데도 `run /mcp to reconnect` 어미가 대신 표시되었습니다. Cowork에서 이러한 어미가 표시되더라도 헬퍼를 확인하거나 헤더를 업데이트한 후 새 작업이나 채팅을 시작하십시오. v2.1.273 이전에는 로그인 만료, `headersHelper`, `Authorization` 헤더의 경우 모두 `MCP server "<name>" requires re-authorization (token expired)`가 표시되었습니다.
1517 1563
1518서버는 범위 승인을 요청하기 위해 HTTP 403 `insufficient_scope`로 도구 호출을 거부할 수도 있으며, 때로는 토큰에 이미 포함된 범위를 요청하기도 합니다. 메시지에 해당 범위가 표시됩니다.1564서버는 범위 승인을 요청하기 위해 HTTP 403 `insufficient_scope`로 도구 호출을 거부할 수도 있으며, 때로는 토큰에 이미 포함된 범위를 요청하기도 합니다. 메시지에 해당 범위가 표시됩니다.
1519 1565
1812* 동일한 셸에서 `curl -I https://api.anthropic.com`을 실행하여 API 호스트에 도달할 수 있는지 확인합니다. Windows PowerShell에서는 `curl.exe -I https://api.anthropic.com`을 사용하여 기본 제공 `Invoke-WebRequest` 별칭이 사용되지 않도록 합니다.1858* 동일한 셸에서 `curl -I https://api.anthropic.com`을 실행하여 API 호스트에 도달할 수 있는지 확인합니다. Windows PowerShell에서는 `curl.exe -I https://api.anthropic.com`을 사용하여 기본 제공 `Invoke-WebRequest` 별칭이 사용되지 않도록 합니다.
1813* 회사 프록시 뒤에 있는 경우, Claude Code를 시작하기 전에 `HTTPS_PROXY`를 설정하고 [네트워크 구성](/docs/ko/network-config)을 참조합니다.1859* 회사 프록시 뒤에 있는 경우, Claude Code를 시작하기 전에 `HTTPS_PROXY`를 설정하고 [네트워크 구성](/docs/ko/network-config)을 참조합니다.
1814* LLM 게이트웨이 또는 릴레이를 통해 라우팅하는 경우, [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 해당 주소로 설정합니다. 설정은 [Claude Code를 LLM 게이트웨이에 연결](/docs/ko/llm-gateway-connect)을 참조합니다.1860* LLM 게이트웨이 또는 릴레이를 통해 라우팅하는 경우, [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 해당 주소로 설정합니다. 설정은 [Claude Code를 LLM 게이트웨이에 연결](/docs/ko/llm-gateway-connect)을 참조합니다.
1861* `ANTHROPIC_BASE_URL`이 이미 게이트웨이를 가리키고 있는데 모든 요청이 `Connection dropped`로 끝나는 경우, Claude Code가 기본적으로 보내는 도구 검색 필드를 게이트웨이가 거부하고 있는지 확인합니다. 확인하려면 [LLM 게이트웨이를 통한 도구 검색](/docs/ko/mcp#tool-search-through-a-gateway)에 설명된 대로 `ENABLE_TOOL_SEARCH=false`를 설정한 다음 다시 시도합니다. v2.1.304 이전에는 `ENABLE_TOOL_SEARCH`로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.
1815* 방화벽이 [네트워크 액세스 요구 사항](/docs/ko/network-config#network-access-requirements)에 나열된 호스트를 허용하는지 확인합니다.1862* 방화벽이 [네트워크 액세스 요구 사항](/docs/ko/network-config#network-access-requirements)에 나열된 호스트를 허용하는지 확인합니다.
1816* 간헐적 실패는 [자동으로 재시도](#automatic-retries)됩니다. 지속적인 실패는 로컬 네트워크 문제를 나타냅니다.1863* 간헐적 실패는 [자동으로 재시도](#automatic-retries)됩니다.
1817 1864
1818`curl`이 성공하지만 Claude Code가 여전히 실패하는 경우, 원인은 일반적으로 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다:1865`curl`이 성공하지만 Claude Code가 여전히 실패하는 경우, 원인은 일반적으로 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다:
1819 1866
2093 2140
2094## 요청 오류2141## 요청 오류
2095 2142
2096이러한 오류는 요청의 내용과 관련이 있습니다. 대부분은 API가 요청을 거부한 후 반환되며, 일부는 요청이 전송되기 전에 Claude Code에서 로컬로 생성됩니다.2143이 오류들은 요청의 내용과 관련이 있습니다. 대부분은 API가 요청을 거부한 후 반환되며, 일부는 요청이 전송되기 전에 Claude Code가 로컬에서 생성합니다.
2097 2144
2098### Prompt is too long2145### Prompt is too long
2099 2146
2100대화와 첨부된 파일이 모델의 컨텍스트 윈도우를 초과합니다.2147대화와 첨부 파일의 합이 모델의 컨텍스트 윈도우를 초과했습니다.
2101 2148
2102```text theme={null}2149```text theme={null}
2103Prompt is too long2150Prompt is too long
2104```2151```
2105 2152
2106대화형 세션에서 Claude Code는 이 오류를 다음과 같이 표시합니다:2153대화형 세션에서 Claude Code는 이 오류를 다음과 같이 표시합니다.
2107 2154
2108```text theme={null}2155```text theme={null}
2109Context limit reached · /compact or /clear to continue2156Context limit reached · /compact or /clear to continue
2110```2157```
2111 2158
2112[`DISABLE_COMPACT`](/docs/ko/env-vars)가 설정된 경우에는 이 줄에 `/clear`만 표시됩니다. 아래의 압축 실패 형식과 같은 더 긴 오류 형식은 `Prompt is too long ·` 표현을 유지합니다. `-p` 출력 및 트랜스크립트에서 텍스트는 `Prompt is too long`으로 유지됩니다.2159[`DISABLE_COMPACT`](/docs/ko/env-vars)가 설정된 경우 이 줄에는 `/clear`만 표시됩니다. 아래의 압축 실패 형태와 같은 더 긴 형태의 오류는 `Prompt is too long ·` 문구를 유지합니다. `-p` 출력과 트랜스크립트에서는 텍스트가 `Prompt is too long`으로 유지됩니다.
2113 2160
2114[사용자 설정](/docs/ko/settings-reference#autocompactenabled)에서 자동 압축을 끈 경우, 이 줄에 그 사실도 함께 표시됩니다:2161[사용자 설정](/docs/ko/settings-reference#autocompactenabled)에서 자동 압축을 끈 경우, 이 줄에 해당 내용도 표시됩니다.
2115 2162
2116```text theme={null}2163```text theme={null}
2117Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on2164Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on
2118```2165```
2119 2166
2120`/config`의 **자동 압축** 토글은 사용자 설정에 `autoCompactEnabled`를 씁니다. 이 힌트는 `/config` 변경이 적용될 때만 나타납니다. 예를 들어, [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](/docs/ko/env-vars)가 자동 압축을 끈 경우에는 나타나지 않습니다. 또한 프로젝트 또는 관리형 설정과 같은 더 높은 우선순위 범위가 `autoCompactEnabled`를 `false`로 설정한 경우에도 나타나지 않습니다. v2.1.235 이전에는 이 줄에 자동 압축 힌트가 없었습니다.2167`/config`의 **Auto-compact** 토글은 사용자 설정에 `autoCompactEnabled`를 기록합니다. 이 힌트는 `/config` 변경이 실제로 적용될 때만 표시됩니다. 예를 들어 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](/docs/ko/env-vars)로 자동 압축이 꺼진 경우에는 표시되지 않습니다. 또한 프로젝트 설정이나 관리형 설정처럼 우선순위가 더 높은 범위에서 `autoCompactEnabled`를 `false`로 설정한 경우에도 표시되지 않습니다. v2.1.235 이전에는 이 줄에 자동 압축 힌트가 없었습니다.
2121 2168
2122Amazon Bedrock은 이 조건을 `Input is too long for requested model.`로 보고하며, Claude Code는 이를 동일한 방식으로 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock 표현을 인식하지 못했으므로 자동 압축이 트리거되지 않았고 `/compact`는 동일한 오류로 실패했습니다.2169Amazon Bedrock은 이 상황을 `Input is too long for requested model.`로 보고하며, Claude Code는 이를 동일하게 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock 문구를 인식하지 못했기 때문에 자동 압축이 트리거되지 않았고 `/compact`도 같은 오류로 실패했습니다.
2123 2170
2124[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway-config#upstream-error-messages)는 클라우드 업스트림이 제공자의 자체 오류 형식으로 요청을 거부할 때 이 조건을 `capability_rejected: prompt_too_long`으로 보고합니다. Claude Code는 이 토큰을 `Prompt is too long`과 동일하게 처리합니다. v2.1.228 이전에는 Claude Code가 이 토큰을 인식하지 못했으므로 자동 압축이 트리거되지 않았습니다.2171[Claude apps gateway](/docs/ko/claude-apps-gateway-config#upstream-error-messages)는 클라우드 업스트림이 공급자 고유의 오류 형태로 요청을 거부할 때 이 상황을 `capability_rejected: prompt_too_long`으로 보고합니다. Claude Code는 이 토큰을 `Prompt is too long`과 동일하게 처리합니다. v2.1.228 이전에는 Claude Code가 이 토큰을 인식하지 못했기 때문에 자동 압축이 트리거되지 않았습니다.
2125 2172
2126자동 압축이 이 턴에서 실행되었지만 사용할 수 없는 모델 또는 인증 실패와 같은 기본 오류로 실패한 경우, 메시지는 구분자 뒤에 해당 오류를 표시합니다:2173이번 턴에서 자동 압축이 실행되었지만 사용할 수 없는 모델이나 인증 실패와 같은 근본 오류로 실패한 경우, 메시지는 구분 기호 뒤에 해당 오류를 표시합니다.
2127 2174
2128```text theme={null}2175```text theme={null}
2129Prompt is too long · automatic compaction failed: <the underlying error>2176Prompt is too long · automatic compaction failed: <the underlying error>
2130```2177```
2131 2178
2132명명된 오류를 먼저 해결하십시오. 해결할 때까지 `/compact`는 동일한 오류로 실패합니다. v2.1.229 이전에는 실패한 자동 압축이 원인 없이 `Prompt is too long`을 표시했습니다.2179표시된 오류를 먼저 해결하십시오. 해결하기 전까지 `/compact`도 같은 오류로 실패합니다. v2.1.229 이전에는 자동 압축이 실패하면 원인 없이 `Prompt is too long`만 표시되었습니다.
2133 2180
2134자동 압축이 이 오류에서 실행될 때, 일반적으로 가장 오래된 교환을 요약하고 가장 최신 교환을 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다:2181이 오류에 대해 자동 압축이 실행되면 일반적으로 가장 오래된 대화 교환을 요약하고 최신 교환은 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다.
2135 2182
2136* 전체 교환을 요약할 수 없는 경우, Claude Code는 가장 최신 프롬프트를 그대로 유지하고 그 이전의 모든 것을 요약합니다.2183* 어떤 교환 전체도 요약할 수 없는 경우, Claude Code는 최신 프롬프트를 그대로 유지하고 그 이전의 모든 내용을 요약합니다.
2137* 이 경우, 대화가 프롬프트로 끝나지 않으면 Claude Code는 전체 대화를 대신 요약합니다.2184* 이 경우 대화가 사용자의 프롬프트로 끝나지 않으면, Claude Code는 대신 대화 전체를 요약합니다.
2138 2185
2139이어서 전달할 내용에 모델 응답이 없고 사용자 자신의 텍스트가 약 1,000토큰 미만인 경우(예: 크기가 큰 붙여넣기 후에 보낸 짧은 재시도) Claude Code는 이 복구를 건너뜁니다. `/clear`를 실행하여 새로 시작하십시오. v2.1.269 이전에는 전체 교환을 요약할 수 없을 때마다 압축이 실패했으므로 이 상태의 세션은 매 턴마다 이 오류를 다시 만났습니다.2186이어서 전달할 내용에 모델 응답이 없고 사용자 자신의 텍스트가 약 1,000 토큰 미만인 경우(예: 너무 큰 붙여넣기 후 보낸 짧은 재시도), Claude Code는 이 복구를 건너뜁니다. 새로 시작하려면 `/clear`를 실행하십시오. v2.1.269 이전에는 교환 전체를 요약할 수 없을 때마다 압축이 실패했기 때문에, 그런 상태의 세션은 매 턴마다 이 오류가 다시 발생했습니다.
2140 2187
2141단일 교환 대화에는 요약할 이전 턴이 없습니다. 이러한 대화에서 자동 압축이 실행되려 할 때, Claude Code는 시도를 건너뛰고 무엇이 요청을 채우고 있는지 설명합니다. API가 오류에서 토큰 수를 보고하지 않으면 메시지는 다음과 같습니다:2188단일 교환으로 이루어진 대화에는 요약할 이전 턴이 없습니다. 이런 대화에서 자동 압축이 실행될 상황이 되면, Claude Code는 시도를 건너뛰고 대신 요청을 채우는 내용이 무엇인지 설명합니다. API가 오류에 토큰 수를 보고하지 않는 경우 메시지는 다음과 같습니다.
2142 2189
2143```text theme={null}2190```text theme={null}
2144Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.2191Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.
2145```2192```
2146 2193
2147API가 오류에서 토큰 수를 보고하면 Claude Code는 이를 자체적으로 추정한 대화 크기와 비교하여 요청의 대부분이 무엇인지 알려줍니다: 대화 자체의 내용인지, 아니면 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의 및 첨부 내용인지입니다. 대화 자체의 내용이 요청의 대부분인 경우 메시지는 다음과 같습니다:2194API가 오류에 토큰 수를 보고하는 경우, Claude Code는 이를 대화 크기에 대한 자체 추정치와 비교하여 요청의 대부분이 대화 자체의 내용인지, 아니면 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의, 첨부 내용인지 판단합니다. 대화 자체의 내용이 요청의 대부분인 경우 메시지는 다음과 같습니다.
2148 2195
2149```text theme={null}2196```text theme={null}
2150Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).2197Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).
2151```2198```
2152 2199
2153요청의 대부분이 대화 외부에 있으면 메시지는 다음과 같습니다:2200요청의 대부분이 대화 외부에 있는 경우 메시지는 다음과 같습니다.
2154 2201
2155```text theme={null}2202```text theme={null}
2156Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.2203Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.
2157```2204```
2158 2205
2159v2.1.162 이전에는 Claude Code가 그래도 압축을 시도했고 실패했을 때 `Prompt is too long`만 표시했습니다.2206v2.1.162 이전에는 Claude Code가 그래도 압축을 시도했고, 실패하면 `Prompt is too long`만 표시했습니다.
2160 2207
2161**할 일:**2208**해결 방법:**
2162 2209
2163* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다. `/compact`가 `Not enough messages to compact.`로 응답하면 대화는 요약할 이전 내용이 없는 단일 교환이므로 공간은 해당 프롬프트와 Claude Code가 모든 요청과 함께 보내는 것으로 채워집니다: `/clear`를 실행하고 더 적은 붙여넣은 텍스트 또는 더 작은 첨부 파일로 다시 보내거나, 아래 단계를 사용하여 도구 정의 및 메모리 파일을 줄입니다.2210* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다. `/compact`가 `Not enough messages to compact.`로 응답하면 대화가 요약할 이전 내용이 없는 단일 교환이라는 뜻이므로, 공간은 그 하나의 프롬프트와 Claude Code가 모든 요청에 함께 보내는 내용이 차지하고 있습니다. `/clear`를 실행하고 붙여넣은 텍스트를 줄이거나 더 작은 첨부 파일로 다시 보내거나, 아래 단계에 따라 도구 정의와 메모리 파일을 줄이십시오
2164* `/context`를 실행하여 윈도우를 소비하는 것의 분석을 확인합니다: 시스템 프롬프트, 도구, 메모리 파일 및 메시지2211* `/context`를 실행하여 시스템 프롬프트, 도구, 메모리 파일, 메시지 등 윈도우를 차지하는 항목의 세부 내역을 확인합니다
2165* `/mcp disable <name>`으로 사용하지 않는 MCP 서버를 비활성화하여 컨텍스트에서 도구 정의를 제거합니다.2212* 사용하지 않는 MCP 서버를 `/mcp disable <name>`으로 비활성화하여 해당 도구 정의를 컨텍스트에서 제거합니다
2166* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 지시사항을 관련이 있을 때만 로드되는 [경로 범위 규칙](/docs/ko/memory#path-specific-rules)으로 이동합니다.2213* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 관련 있을 때만 로드되는 [경로 범위 규칙](/docs/ko/memory#path-specific-rules)으로 지침을 옮깁니다
2167* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config`에서 또는 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars)로 끈 경우 다시 켭니다. 끈 상태로 유지하면 윈도우가 채워지기 전에 `/compact`를 직접 실행합니다.2214* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config` 또는 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars)로 끈 경우 다시 켜십시오. 계속 꺼 두려면 윈도우가 가득 차기 전에 직접 `/compact`를 실행하십시오.
2168* 더 많은 토큰을 허용하는 모델에서 200K 토큰 근처에서 오류가 나타난다면, 한 가지 원인은 Claude Code가 인식하지 못하는 모델 ID입니다. Claude Code는 그런 ID에 대해 200K 윈도우를 가정하므로, 그 지점을 넘어 계속 작업하려면 [모델의 실제 컨텍스트 윈도우를 지정합니다](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id).2215* 더 많은 토큰을 허용하는 모델에서 200K 토큰 근처에서 오류가 발생한다면, Claude Code가 인식하지 못하는 모델 ID가 원인일 수 있습니다. Claude Code는 이런 ID에 대해 200K 윈도우를 가정하므로, 그 이상으로 계속 작업하려면 [모델의 실제 컨텍스트 윈도우를 지정](/docs/ko/model-config#correct-the-window-for-a-gateway-or-custom-model-id)하십시오.
2216* Claude가 대화를 압축하는 도중에 중지한 직후 오류가 나타났다면, 대화는 변경되지 않았으며 여전히 압축이 필요할 만큼 큽니다. `/compact`를 실행하고 메시지를 다시 보내세요. 오류가 재발하지 않도록 하려면 Claude Code를 v2.1.304 이상으로 [업데이트](/docs/ko/setup#update-claude-code)하세요. v2.1.304 이전에는 그 시점에 중지하면 턴이 이 오류로 끝날 수 있었습니다.
2169 2217
2170[컨텍스트 윈도우 탐색](/docs/ko/context-window)에서 컨텍스트가 어떻게 채워지는지에 대한 대화형 보기를 참조하십시오.2218컨텍스트가 채워지는 방식을 대화형으로 확인하려면 [컨텍스트 윈도우 살펴보기](/docs/ko/context-window)를 참조하십시오.
2171 2219
2172### 컨텍스트가 토큰 제한을 초과합니다2220### Context exceeds the token limit
2173 2221
2174`/context`는 대화가 모델의 컨텍스트 윈도우를 초과했을 때 출력 상단에 이 경고를 표시합니다. 공간을 확보할 때까지 요청이 [`Prompt is too long`](#prompt-is-too-long)으로 실패합니다. 대화형 세션은 해당 오류를 `Context limit reached` 줄로 표시합니다.2222대화가 모델의 컨텍스트 윈도우를 넘어서 커진 경우 `/context`는 출력 상단에 이 경고를 표시합니다. 공간을 확보할 때까지 요청은 [`Prompt is too long`](#prompt-is-too-long)으로 실패합니다. 대화형 세션은 이 오류를 `Context limit reached` 줄로 표시합니다.
2175 2223
2176```text theme={null}2224```text theme={null}
2177Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2225Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
2178```2226```
2179 2227
2180초과한 제한이 1M 컨텍스트 모델의 200K 경계와 같은 압축 윈도우인 경우 경고는 다르게 표시됩니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로 이를 넘는 요청도 여전히 성공할 수 있습니다.2228초과한 한도가 1M 컨텍스트 모델의 200K 경계와 같은 압축 윈도우인 경우 경고 문구가 달라집니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로, 이를 넘은 요청도 여전히 성공할 수 있습니다.
2181 2229
2182```text theme={null}2230```text theme={null}
2183Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.2231Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.
2184```2232```
2185 2233
2186두 형식 모두 [`DISABLE_COMPACT`](/docs/ko/env-vars)를 설정한 경우 `/compact` 대신 `/clear`를 표시합니다.2234[`DISABLE_COMPACT`](/docs/ko/env-vars)를 설정한 경우 두 형태 모두 `/compact` 대신 `/clear`를 표시합니다.
2187 2235
2188**할 일:**2236**해결 방법:**
2189 2237
2190* 다중 턴 대화에서 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보합니다. 대신 새로 시작하려면 `/clear`를 실행합니다.2238* 여러 턴으로 이루어진 대화에서는 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보합니다. 대신 새로 시작하려면 `/clear`를 실행합니다
2191* 사용량을 줄이는 더 많은 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오.2239* 사용량을 줄이는 다른 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오
2192 2240
2193v2.1.216 이전에는 `/context`가 100% 이상의 사용량을 표시했으며 그것이 의미하는 바 또는 복구 방법을 설명하는 경고 줄이 없었습니다.2241v2.1.216 이전에는 `/context`가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.
2194 2242
2195### Request too large2243### Request too large
2196 2244
2197원본 요청 본문이 토큰화 전에 API의 32MB 제한을 초과했습니다. 일반적으로 큰 붙여넣은 내용, 도구 결과 또는 첨부 파일 때문입니다. 이 제한은 [컨텍스트 윈도우](#prompt-is-too-long)와 별개입니다.2245토큰화 이전의 원시 요청 본문이 API의 32MB 한도를 초과했습니다. 보통 큰 붙여넣기 내용, 도구 결과 또는 첨부 파일 때문입니다. 이 한도는 [컨텍스트 윈도우](#prompt-is-too-long)와는 별개입니다.
2198 2246
2199```text theme={null}2247```text theme={null}
2200Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.2248Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.
2201```2249```
2202 2250
2203요청이 Claude API로 직접 전송되었고 API 자체가 이를 거부한 경우, Claude Code는 대화를 측정하고 복구가 가능한지 여부에 따라 메시지를 표현합니다. 프록시, 게이트웨이 또는 클라우드 제공자를 통하는 경우에는 일반 메시지를 받습니다. 측정된 형식:2251요청이 Claude API로 직접 전송되었고 API 자체가 이를 거부한 경우, Claude Code는 대화를 측정하고 복구가 가능한지에 따라 메시지 문구를 정합니다. 프록시, 게이트웨이 또는 클라우드 공급자를 거치는 경우에는 일반 메시지가 표시됩니다. 측정된 형태는 다음과 같습니다.
2204 2252
2205* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지 또는 문서가 요청을 제한 이상으로 밀어냈습니다. Claude Code는 이들을 제거하고 재시도합니다.2253* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지나 문서 때문에 요청이 한도를 초과했습니다. Claude Code는 이를 제거한 상태로 재시도합니다.
2206* `Request too large for the API's 32MB request limit`: 메시지만으로도 제한을 초과하므로 메시지는 `compacting cannot make it fit`이라고 말하고 Claude Code는 재시도하지 않습니다. [비대화형 모드](/docs/ko/headless)에서 메시지는 대신 입력을 줄이거나 새 세션을 시작하도록 안내합니다.2254* `Request too large for the API's 32MB request limit`: 메시지만으로도 한도를 초과하므로, 메시지에 `compacting cannot make it fit`이 표시되고 Claude Code는 재시도하지 않습니다. [비대화형 모드](/docs/ko/headless)에서는 대신 입력을 줄이거나 새 세션을 시작하라는 메시지가 표시됩니다.
2207 2255
2208v2.1.212 이전에는 이미지가 충분히 누적된 대화가 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 매 턴마다 실패했습니다. v2.1.229 이전에는 Claude Code가 압축이 도움이 될 수 없을 때도 모든 거부에 대해 첨부 파일 조언을 표시했습니다.2256v2.1.212 이전에는 이미지가 충분히 누적된 대화가 매 턴마다 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 실패했습니다. v2.1.229 이전에는 압축으로 해결할 수 없는 경우에도 Claude Code가 모든 거부에 대해 첨부 파일 관련 안내를 표시했습니다.
2209 2257
2210**할 일:**2258**해결 방법:**
2211 2259
2212* 메시지가 `compacting cannot make it fit`이라고 말하면 Esc를 두 번 눌러 큰 내용을 추가한 턴 이전으로 되돌아가거나 `/clear`를 실행하여 새로 시작합니다.2260* 메시지에 `compacting cannot make it fit`이 표시되면 Esc를 두 번 눌러 큰 내용을 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작합니다
2213* 그렇지 않으면 `/compact`를 실행합니다. 이는 누적된 이미지 및 첨부 파일을 제거합니다.2261* 그렇지 않으면 누적된 이미지와 첨부 파일을 제거하는 `/compact`를 실행합니다
2214* 내용을 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다.2262* 큰 파일은 내용을 붙여넣는 대신 경로로 참조하여 Claude가 나누어 읽을 수 있게 합니다
2215* 이미지의 경우 아래의 [Image was too large](#image-was-too-large)를 참조하십시오.2263* 이미지의 경우 아래의 [Image was too large](#image-was-too-large)를 참조하십시오
2216 2264
2217### Image was too large2265### Image was too large
2218 2266
2219붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.2267붙여넣거나 첨부한 이미지가 API의 크기 또는 해상도 한도를 초과했습니다.
2220 2268
2221```text theme={null}2269```text theme={null}
2222Image was too large. Double press esc to go back and try again with a smaller image.2270Image was too large. Double press esc to go back and try again with a smaller image.
2224API Error: an image in the conversation could not be processed and was removed.2272API Error: an image in the conversation could not be processed and was removed.
2225```2273```
2226 2274
2227`could not be processed and was removed` 줄은 크기 또는 해상도 한도를 초과한 이미지처럼 API가 대화의 이미지를 거부했다는 의미입니다.2275`could not be processed and was removed` 줄은 API가 대화 내의 이미지(예: 크기 또는 해상도 한도를 초과한 이미지)를 거부했다는 뜻입니다.
2228 2276
2229이러한 오류 중 하나가 계속 반복되면 Claude Code를 업데이트합니다. 이전 버전에서는 다음과 같은 이유로 이미지 오류가 반복될 수 있었습니다:2277이러한 오류 중 하나가 계속 발생하면 Claude Code를 업데이트하십시오. 이전 버전에서는 다음과 같은 이유로 이미지 오류가 반복될 수 있었습니다.
2230 2278
2231* v2.1.299 이전에는 이미지가 많은 긴 대화에서 Claude Code가 한도를 초과한 이미지 대신 마지막으로 첨부한 이미지를 제거할 수 있었습니다. 그러면 `was removed` 줄이 매 턴마다 반복되었고 Claude는 새 이미지를 보지 못했습니다.2279* v2.1.299 이전에는 이미지가 많은 긴 대화에서 Claude Code가 한도를 초과한 이미지 대신 마지막으로 첨부한 이미지를 제거할 수 있었습니다. 그 결과 `was removed` 줄이 매 턴마다 반복되었고, Claude는 새 이미지를 볼 수 없었습니다.
2232* v2.1.299 이전에는 VS Code, Desktop 앱, Agent SDK에서 Claude가 작업하는 동안 첨부한 이미지에 다른 첨부 이미지와 같은 크기 조정이 적용되지 않았습니다. 이러한 이미지는 원본 크기 그대로 API에 전달되어 긴 대화에서 이미지 오류가 반복되었습니다.2280* v2.1.299 이전에는 VS Code, Desktop 앱, Agent SDK에서 Claude가 작업하는 동안 첨부한 이미지가 다른 첨부 이미지와 달리 크기 조정되지 않았습니다. 이 이미지는 원래 크기 그대로 API에 전달되어 긴 대화에서 이미지 오류가 반복되었습니다.
2233* v2.1.166 이전에는 붙여넣은 이미지가 대화에 남아 이후 모든 메시지에서 같은 오류가 반복될 수 있었습니다2281* v2.1.166 이전에는 붙여넣은 이미지가 대화에 남아 이후 모든 메시지에서 같은 오류가 반복될 수 있었습니다
2234 2282
2235**할 일:**2283**해결 방법:**
2236 2284
2237* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 변 기준 최대 8000픽셀, 컨텍스트에 이미지가 20개를 초과할 때는 3000픽셀까지의 이미지를 허용합니다.2285* 붙여넣기 전에 이미지 크기를 줄입니다. API는 단일 이미지의 경우 긴 변 기준 최대 8000픽셀, 컨텍스트에 이미지가 20개를 초과하는 경우 최대 3000픽셀까지 허용합니다.
2238* 전체 화면 대신 관련 영역만 더 좁게 스크린샷을 찍습니다.2286* 전체 화면 대신 관련 영역만 좁게 스크린샷을 찍습니다
2239 2287
2240### Unable to resize image2288### Unable to resize image
2241 2289
2242Claude Code가 API로 보내기 전에 첨부된 이미지를 축소할 수 없었습니다.2290Claude Code가 첨부된 이미지를 API로 보내기 전에 축소하지 못했습니다.
2243 2291
2244```text theme={null}2292```text theme={null}
2245Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.2293Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
2251Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.2299Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.
2252```2300```
2253 2301
2254Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이러한 오류는 이미지를 디코딩하거나 API 제한 내에 맞게 크기를 조정할 수 없음을 의미합니다.2302Claude Code는 일반적으로 큰 이미지의 크기를 자동으로 조정합니다. 이러한 오류는 이미지를 디코딩하거나 API 한도에 맞게 크기를 조정할 수 없었다는 뜻입니다.
2255 2303
2256**할 일:**2304**해결 방법:**
2257 2305
2258* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지를 디코딩하지 않고 파일 헤더에서 이러한 형식의 치수를 확인할 수 있습니다.2306* 메시지가 이미지 변환을 요청하면 PNG, JPEG, GIF 또는 WebP로 변환한 후 다시 첨부합니다. Claude Code는 이러한 형식의 경우 이미지를 디코딩하지 않고도 파일 헤더에서 해상도를 확인할 수 있습니다.
2259* 메시지가 치수 또는 크기 제한을 보고하면 해당 제한 아래로 이미지 크기를 조정하거나 다시 압축한 후 첨부합니다.2307* 메시지가 해상도 또는 크기 한도를 보고하면, 첨부하기 전에 이미지를 해당 한도 이하로 크기 조정하거나 다시 압축합니다.
2260* 메시지가 CMYK JPEG, 애니메이션 WebP 또는 손상된 파일 가능성과 같은 원인을 표시하면 메시지가 제안하는 형식으로 이미지를 다시 저장하고 첨부합니다.2308* 메시지가 CMYK JPEG, 애니메이션 WebP, 손상되었을 수 있는 파일과 같은 원인을 명시하면, 메시지가 제안하는 형식으로 이미지를 다시 저장한 후 다시 첨부합니다.
2261 2309
2262### Request rejected as unprocessable by the model2310### Request rejected as unprocessable by the model
2263 2311
2264API가 요청을 모델이 처리할 수 없는 요청으로 거부했습니다. 이 메시지는 API 자체의 메시지입니다.2312API가 모델이 처리할 수 없는 요청으로 판단하여 거부했습니다. 이 메시지는 API 자체의 메시지입니다.
2265 2313
2266```text theme={null}2314```text theme={null}
2267API Error: 400 Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters)2315API Error: 400 Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters)
2268```2316```
2269 2317
2270Claude Code는 거부된 요청에서 가장 오래된 이미지와 문서를 제거하고 다시 보낼 수 있습니다. v2.1.290 이전에는 Claude Code가 이 거부에 대해 이미지를 제거하지 않았으므로, 이미지가 수백 개 누적된 긴 세션은 매 턴마다 이 오류로 실패할 수 있었습니다.2318Claude Code는 거부된 요청에서 가장 오래된 이미지와 문서를 제거한 후 다시 보낼 수 있습니다. v2.1.290 이전에는 Claude Code가 이 거부에 대해 이미지를 제거하지 않았기 때문에, 이미지가 수백 개 누적된 긴 세션은 매 턴마다 이 오류로 실패할 수 있었습니다.
2271 2319
2272**해결 방법:**2320**해결 방법:**
2273 2321
2274* 이미지나 문서가 포함된 대화에서 이 메시지가 계속 표시되면 직접 제거하십시오. Esc를 두 번 눌러 해당 항목을 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작합니다.2322* 이미지나 문서가 포함된 대화에서 이 메시지가 계속 나타나면 직접 제거하십시오. Esc를 두 번 눌러 해당 내용을 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작합니다.
2275 2323
2276### PDF 오류2324### PDF 오류
2277 2325
2278첨부한 PDF를 처리할 수 없었습니다. 메시지는 여기에 비대화형 형식으로 표시됩니다. 대화형 세션에서는 대신 Esc를 두 번 누르고 다시 시도하도록 안내합니다.2326첨부한 PDF를 처리할 수 없었습니다. 여기에 표시된 메시지는 비대화형 형태이며, 대화형 세션에서는 대신 esc를 두 번 눌러 다시 시도하라는 안내가 표시됩니다.
2279 2327
2280```text theme={null}2328```text theme={null}
2281PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).2329PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
2283The PDF file was not valid. Try converting it to text first (e.g., pdftotext).2331The PDF file was not valid. Try converting it to text first (e.g., pdftotext).
2284```2332```
2285 2333
2286**할 일:**2334**해결 방법:**
2287 2335
2288* 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Read 도구로 페이지 범위를 읽도록 Claude에 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 출력 파일을 경로로 참조합니다.2336* 크기가 큰 PDF의 경우 파일 전체를 첨부하는 대신 Claude에게 Read 도구로 페이지 범위를 읽도록 요청하거나, `pdftotext` 같은 도구로 텍스트를 추출한 후 출력 파일을 경로로 참조합니다
2289* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다.2337* 보호되었거나 유효하지 않은 PDF의 경우 비밀번호를 제거하거나 원본 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다
2290 2338
2291Claude가 Read 도구로 PDF에서 페이지 범위를 읽을 때, 읽기가 다른 메시지로 실패할 수 있습니다:2339Claude가 Read 도구로 PDF의 페이지 범위를 읽을 때, 다른 메시지와 함께 읽기가 실패할 수 있습니다.
2292 2340
2293```text theme={null}2341```text theme={null}
2294pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.2342pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.
2295```2343```
2296 2344
2297페이지 범위 읽기는 `pdftoppm`으로 페이지를 렌더링합니다. 메시지가 제공하는 명령으로 poppler-utils를 설치하거나, 다른 플랫폼에서는 `pdftoppm`을 `PATH`에 배치하는 poppler 빌드를 설치합니다. 어떤 PDF가 페이지 범위로 읽히는지는 [Read 도구 동작](/docs/ko/tools-reference#read-tool-behavior)을 참조하십시오.2345페이지 범위 읽기는 `pdftoppm`으로 페이지를 렌더링합니다. 메시지가 제시하는 명령으로 poppler-utils를 설치하거나, 다른 플랫폼에서는 `PATH`에 `pdftoppm`을 추가하는 poppler 빌드를 설치하십시오. 어떤 PDF가 페이지 범위로 읽히는지는 [Read 도구 동작](/docs/ko/tools-reference#read-tool-behavior)을 참조하십시오.
2298 2346
2299### Extra inputs are not permitted2347### Extra inputs are not permitted
2300 2348
2301Claude Code와 API 사이의 프록시 또는 LLM 게이트웨이가 `anthropic-beta` 요청 헤더를 제거했으므로 API가 이 헤더에 의존하는 필드를 거부했습니다.2349요청을 받은 엔드포인트가 요청의 필드 중 하나를 허용하지 않는 입력으로 판단하여 거부했으며, 엔드포인트의 메시지에 해당 필드가 명시됩니다.
2302 2350
2303```text theme={null}2351```text theme={null}
2304API Error: 400 ... Extra inputs are not permitted ... context_management2352API Error: 400 ... context_management: Extra inputs are not permitted
2305```2353```
2306 2354
2307Claude Code는 `context_management`와 같은 베타 전용 필드를 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문은 전달하지만 헤더를 제거하면 API는 인식하지 못하는 필드를 보게 됩니다.2355Claude Code는 `context_management`나 도구 검색의 `defer_loading` 같은 베타 전용 필드를 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문은 전달하지만 헤더를 삭제하면, API는 인식하지 못하는 필드를 보게 됩니다. 게이트웨이가 Anthropic 형식의 본문을 스키마가 다른 업스트림으로 전달하면, 해당 업스트림이 그런 필드를 거부합니다. [베타 헤더와 본문 필드 쌍](/docs/ko/llm-gateway-protocol#beta-header-and-body-field-pairs)에서 두 경우를 모두 다룹니다.
2308 2356
2309**할 일:**2357**해결 방법:**
2358
2359* 메시지에 `context_management: Extra inputs are not permitted`가 포함되어 있으면 [Claude Code를 v2.1.304 이상으로 업데이트](/docs/ko/setup#update-claude-code)하십시오. 업데이트 후에는 Claude Code가 이 거부에 대해 해당 필드 없이 요청을 한 번 더 보냅니다. v2.1.304 이전에는 Claude Code가 이 거부에 대해 재시도하지 않았습니다.
2360* 메시지에 `defer_loading` 또는 `tool_reference`가 명시되어 있으면 Claude Code를 업데이트하거나 [도구 검색](/docs/ko/mcp#tool-search-through-a-gateway)을 끄십시오.
2361 * [Claude Code를 v2.1.305 이상으로 업데이트](/docs/ko/setup#update-claude-code)합니다. 그러면 Claude Code가 이 거부에 대해 도구 검색 필드 없이 요청을 한 번 더 보냅니다.
2362 * 업데이트할 수 없거나 업데이트 후에도 메시지가 계속 나타나면, 셸 또는 [설정 `env`](/docs/ko/settings-reference#env)에서 `ENABLE_TOOL_SEARCH=false`를 설정합니다. 설정 파일에서 이미 이 변수를 설정하고 있다면, 그 값이 [셸 export를 재정의할 수 있으므로](/docs/ko/settings-reference#how-env-values-interact-with-your-shell) 해당 파일에서 변경하십시오. 그러면 Claude Code는 MCP 도구를 미리 로드합니다.
2363* 게이트웨이가 헤더를 삭제하는 경우, `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성하십시오. 게이트웨이가 전달해야 하는 항목은 [기능 패스스루](/docs/ko/llm-gateway-protocol#feature-pass-through)를 참조하십시오.
2364* 대안으로, 실행하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/ko/env-vars)을 설정하십시오. 정확한 범위는 [사전 출시 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에서 다룹니다.
2310 2365
2311* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. 게이트웨이가 전달해야 하는 것에 대해서는 [기능 통과](/docs/ko/llm-gateway-protocol#feature-pass-through)를 참조하십시오.2366v2.1.302 이전에는 게이트웨이가 관여하지 않아도 이 오류가 `diagnostics` 필드를 명시할 수 있었습니다. 이는 이미 Anthropic API를 사용한 세션이 재시작 없이 Amazon Bedrock 또는 Google Cloud's Agent Platform으로 전환될 때 발생했습니다. 예를 들어 열어 둔 세션은 다른 Claude Code 창에서 [`/setup-bedrock`](/docs/ko/commands)을 실행하면 Bedrock으로 전환됩니다. 해당 버전에서는 그 세션에서 `/clear`를 실행하거나 세션을 재시작하십시오.
2312* 폴백으로, 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/ko/env-vars)을 설정합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)에서 정확한 범위를 다룹니다.
2313 2367
2314### 도구 입력 스키마가 유효하지 않습니다2368### Tool input schema is invalid
2315 2369
2316요청의 도구가 API의 JSON Schema 검증에 실패하는 `input_schema`를 선언했으므로 API가 전체 요청을 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며 조회할 수 있는 이름이 아닙니다.2370요청에 포함된 도구가 API의 JSON Schema 검증을 통과하지 못하는 `input_schema`를 선언했기 때문에 API가 요청 전체를 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.
2317 2371
2318```text theme={null}2372```text theme={null}
2319API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid2373API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
2320API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'2374API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'
2321```2375```
2322 2376
2323첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아님을 의미합니다. 두 번째는 최상위 속성 이름이 메시지가 인용하는 패턴과 일치하지 않음을 의미합니다.2377첫 번째 형태는 스키마가 유효한 JSON Schema draft 2020-12가 아니라는 뜻입니다. 두 번째 형태는 최상위 속성 이름이 메시지에 인용된 패턴과 일치하지 않는다는 뜻입니다.
2324 2378
2325Claude Code는 서버의 도구를 로드할 때 [이 검증에 실패할 입력 스키마를 가진 MCP 도구를 제외](/docs/ko/mcp#tools-with-invalid-input-schemas)하므로, 요청에는 일반적으로 그러한 도구가 포함되지 않습니다.2379Claude Code는 서버의 도구를 로드할 때 [입력 스키마가 이 검증에 실패할 MCP 도구를 제외](/docs/ko/mcp#tools-with-invalid-input-schemas)하므로, 일반적으로 요청에 그런 도구가 포함되지 않습니다.
2326 2380
2327[플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서 또는 플래그가 한 번도 도착하지 않은 머신에서는 Claude Code가 거부될 도구를 서버의 로그에 기록하지만 그대로 보내므로 이 오류가 여전히 발생할 수 있습니다.2381[플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)나 플래그를 한 번도 받지 못한 머신에서는 Claude Code가 어떤 도구가 거부될지를 서버 로그에 기록하지만 그래도 해당 도구를 보내므로, 이 오류가 여전히 발생할 수 있습니다.
2328 2382
2329이 오류는 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언하는 스키마를 가진 도구에서도 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마에 대해 확인하지 않지만 최상위 속성 이름 확인은 여전히 적용됩니다.2383스키마가 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언한 도구에서도 이 오류가 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마와 대조하여 검사하지 않지만, 최상위 속성 이름 검사는 여전히 적용됩니다.
2330 2384
2331v2.1.216 이전에는 어떤 배포에서도 제외 확인을 실행하지 않았습니다.2385v2.1.216 이전에는 어떤 배포에서도 제외 검사가 실행되지 않았습니다.
2332 2386
2333**할 일:**2387**해결 방법:**
2334 2388
2335* Claude Code 버전이 v2.1.216보다 이전이면 `claude update`를 실행합니다.2389* Claude Code 버전이 v2.1.216 이전이면 `claude update`를 실행합니다.
2336* 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 [비활성화](/docs/ko/mcp#disable-a-server-without-removing-it)합니다. 오류는 도구를 위치로만 표시합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 표시하는 줄을 확인합니다. 그러한 도구를 표시하는 로그가 없으면 서버를 하나씩 비활성화합니다.2390* 유효하지 않은 스키마를 선언한 MCP 서버를 제거하거나 [비활성화](/docs/ko/mcp#disable-a-server-without-removing-it)합니다. 오류는 도구를 위치로만 표시합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 명시하는 줄을 확인하십시오. 해당 도구를 명시하는 로그가 없으면 서버를 하나씩 비활성화해 보십시오.
2337* 서버를 유지 관리하는 경우 도구의 `input_schema`를 수정합니다. 스키마는 유효한 JSON Schema여야 하며 최상위 속성 이름은 1\~64자 길이여야 하고 ASCII 문자와 숫자, `_`, `.` 및 `-`만 사용해야 합니다. [유효하지 않은 입력 스키마를 가진 도구](/docs/ko/mcp#tools-with-invalid-input-schemas)를 참조하십시오.2391* 서버를 직접 관리한다면 도구의 `input_schema`를 수정하십시오. 스키마는 유효한 JSON Schema여야 하며, 최상위 속성 이름은 1\~64자 길이에 ASCII 문자와 숫자, `_`, `.`, `-`만 사용해야 합니다. [입력 스키마가 유효하지 않은 도구](/docs/ko/mcp#tools-with-invalid-input-schemas)를 참조하십시오.
2338 2392
2339### MCP 도구 이름이 128자를 초과합니다2393### 128자를 초과하는 MCP 도구 이름
2340 2394
2341MCP 서버가 `mcp__<server>__<tool>`과 같은 전체 이름이 API가 허용하는 128자보다 긴 도구를 나열합니다. Claude Code는 [해당 도구를 Claude에 보내는 도구에서 제외](/docs/ko/mcp#tools-with-names-longer-than-128-characters)하며, 서버의 다른 도구는 계속 작동합니다. 셸에서 `claude --debug`로 시작한 세션에서 Claude Code는 `~/.claude/debug/<session-id>.txt`의 디버그 로그에 다음 메시지를 기록합니다:2395MCP 서버가 `mcp__<server>__<tool>` 같은 전체 이름이 API가 허용하는 128자보다 긴 도구를 나열합니다. Claude Code는 [해당 도구를 Claude에게 보내는 도구 목록에서 제외](/docs/ko/mcp#tools-with-names-longer-than-128-characters)하며, 서버의 다른 도구는 계속 작동합니다. 셸에서 `claude --debug`로 시작한 세션에서는 Claude Code가 `~/.claude/debug/<session-id>.txt`의 디버그 로그에 다음 메시지를 기록합니다.
2342 2396
2343```text theme={null}2397```text theme={null}
2344Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 1282398Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128
2345```2399```
2346 2400
2347**할 일:**2401**해결 방법:**
2348 2402
2349* 서버를 유지 관리하는 경우 도구의 이름을 줄입니다.2403* 서버를 직접 관리한다면 도구 이름을 줄이십시오.
2350* 서버가 [MCP 구성](/docs/ko/mcp#mcp-installation-scopes)에 있는 경우 그곳에서 `analytics-database` 대신 `db`처럼 더 짧은 이름을 지정합니다. 그런 다음 [권한 규칙](/docs/ko/permissions#mcp) 및 [훅 matcher](/docs/ko/hooks#match-mcp-tools)처럼 이전 이름으로 서버나 해당 도구를 참조하는 항목을 업데이트합니다.2404* 서버가 [MCP 구성](/docs/ko/mcp#mcp-installation-scopes)에 있다면 그곳에서 `analytics-database` 대신 `db`처럼 더 짧은 이름을 지정하십시오. 그런 다음 [권한 규칙](/docs/ko/permissions#mcp)과 [훅 matcher](/docs/ko/hooks#match-mcp-tools)처럼 이전 이름으로 서버나 도구를 참조하는 항목을 업데이트하십시오.
2351* [플러그인이 서버를 번들로 포함](/docs/ko/mcp#plugin-provided-mcp-servers)하는 경우 도구의 전체 이름에는 플러그인 이름도 포함됩니다. 플러그인 유지 관리자에게 서버 또는 도구 이름을 줄이도록 요청합니다.2405* [플러그인이 서버를 번들로 포함](/docs/ko/mcp#plugin-provided-mcp-servers)하는 경우 도구의 전체 이름에 플러그인 이름도 포함됩니다. 플러그인 관리자에게 서버 또는 도구 이름을 줄여 달라고 요청하십시오.
2352 2406
2353v2.1.292 이전에는 Claude Code가 그래도 도구를 보냈고, API는 이를 포함하는 모든 요청을 `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`로 거부했습니다.2407v2.1.292 이전에는 Claude Code가 그래도 도구를 보냈고, API는 해당 도구가 포함된 모든 요청을 `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`로 거부했습니다.
2354 2408
2355### tool\_use.name이 200자를 초과합니다2409### 200자를 초과하는 tool\_use.name
2356 2410
2357대화 기록의 도구 호출이 API가 요청에서 허용하는 200자보다 긴 이름을 포함합니다:2411대화 기록의 도구 호출이 API가 요청에서 허용하는 200자보다 긴 이름을 가지고 있습니다.
2358 2412
2359```text theme={null}2413```text theme={null}
2360API Error: 400 ... tool_use.name: String should have at most 200 characters2414API Error: 400 ... tool_use.name: String should have at most 200 characters
2361```2415```
2362 2416
2363Claude Code는 응답이 도착할 때와 저장된 대화를 로드할 때 이러한 이름을 200자로 자릅니다. 따라서 호출은 [`No such tool available`](#no-such-tool-available) 도구 오류로 실패하고 대화는 이 API 오류 없이 계속됩니다.2417Claude Code는 응답이 도착할 때와 저장된 대화를 로드할 때 이런 이름을 200자로 자르므로, 해당 호출은 [`No such tool available`](#no-such-tool-available) 도구 오류로 실패하고 대화는 이 API 오류 없이 계속됩니다.
2364 2418
2365**할 일:**2419**해결 방법:**
2366 2420
2367* `claude update`를 실행한 다음 대화를 재개합니다. 업데이트된 버전은 트랜스크립트를 로드할 때 과도하게 긴 이름을 복구하므로 막혔던 대화가 다시 작동합니다.2421* `claude update`를 실행한 후 대화를 재개합니다. 업데이트된 버전은 트랜스크립트를 로드할 때 너무 긴 이름을 복구하므로, 멈춰 있던 대화가 다시 작동합니다.
2368 2422
2369v2.1.281 이전에는 과도하게 긴 이름이 기록에 남아 있었고 API는 `/compact` 및 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했으므로 이 오류가 반복되고 대화가 막혔습니다.2423v2.1.281 이전에는 너무 긴 이름이 기록에 남아 API가 `/compact`와 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했기 때문에, 이 오류가 반복되고 대화가 멈춰 있었습니다.
2370 2424
2371### There's an issue with the selected model2425### There's an issue with the selected model
2372 2426
2373구성된 모델 이름을 인식하지 못했거나 계정에 해당 모델에 대한 액세스 권한이 없습니다. v2.1.160부터 뒤따르는 힌트(여기서는 대화형 형식으로 표시)는 사용 환경에 따라 다릅니다.2427구성된 모델 이름이 인식되지 않았거나 계정에 해당 모델에 대한 액세스 권한이 없습니다. v2.1.160부터 끝부분의 힌트(여기서는 대화형 형태로 표시)는 사용 환경에 따라 다릅니다.
2374 2428
2375```text theme={null}2429```text theme={null}
2376There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.2430There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.
2377```2431```
2378 2432
2379**할 일:**2433**해결 방법:**
2380 2434
2381* **대화형 CLI**: `/model`을 실행하여 계정에서 사용 가능한 모델 중에서 선택합니다.2435* **대화형 CLI**: `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택합니다.
2382* **비대화형 모드(`-p`)**: 유효한 별칭 또는 ID로 `--model`을 전달하거나 [`ANTHROPIC_MODEL`](/docs/ko/env-vars)을 설정합니다. 이 사용 환경에서는 오류 텍스트에 `Run --model`이 표시됩니다.2436* **비대화형 모드(`-p`)**: 유효한 별칭이나 ID와 함께 `--model`을 전달하거나 [`ANTHROPIC_MODEL`](/docs/ko/env-vars)을 설정합니다. 이 사용 환경에서는 오류 텍스트에 `Run --model`이 표시됩니다.
2383* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트는 힌트를 생략합니다. TypeScript에서 [`Options`의 `model`](/docs/ko/agent-sdk/typescript#options)을 설정하거나 Python에서 [`ClaudeAgentOptions(model=...)`](/docs/ko/agent-sdk/python#claudeagentoptions)을 설정하고, 구조화된 `model_not_found` 오류를 처리하여 자체 재시도 또는 모델 선택기를 표시합니다.2437* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트에 힌트가 생략됩니다. TypeScript에서는 [`Options`의 `model`](/docs/ko/agent-sdk/typescript#options)을, Python에서는 [`ClaudeAgentOptions(model=...)`](/docs/ko/agent-sdk/python#claudeagentoptions)을 설정하고, 구조화된 `model_not_found` 오류를 처리하여 자체 재시도나 모델 선택기를 제공하십시오.
2384* 전체 버전 ID 대신 `sonnet` 또는 `opus`와 같은 별칭을 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래된 값이 되지 않습니다. [모델 구성](/docs/ko/model-config)을 참조하십시오.2438* 버전이 포함된 전체 ID 대신 `sonnet`이나 `opus` 같은 별칭을 사용하십시오. 별칭은 관리되는 기본값으로 해석되므로 오래되지 않습니다. [모델 구성](/docs/ko/model-config)을 참조하십시오.
2385* 잘못된 모델이 CLI에서 계속 다시 나타나면 어딘가에 오래된 ID가 설정되어 있습니다. [우선순위 순서](/docs/ko/model-config#setting-your-model)대로 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거합니다.2439* CLI에서 잘못된 모델이 계속 다시 나타난다면 어딘가에 오래된 ID가 설정되어 있는 것입니다. 모델을 설정할 수 있는 위치를 [우선순위 순서](/docs/ko/model-config#setting-your-model)대로 확인하고 오래된 값을 제거하십시오.
2386* Claude Code는 만료된 claude.ai 로그인을 이 오류가 아닌 [로그인 만료됨](#login-expired)으로 보고합니다. v2.1.206 이전에는 더 이상 새로 고칠 수 없는 만료된 로그인으로 인해 모든 모델이 이 오류로 실패했습니다. 이전 버전에서 이를 보면 `/login`을 실행합니다.2440* Claude Code는 만료된 claude.ai 로그인을 이 오류가 아닌 [Login expired](#login-expired)로 보고합니다. v2.1.206 이전에는 더 이상 갱신할 수 없는 만료된 로그인이 모든 모델에서 이 오류로 실패했습니다. 이전 버전에서 이 현상이 나타나면 `/login`을 실행하십시오.
2387* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/docs/ko/google-vertex-ai#troubleshooting)을 참조하십시오.2441* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키고 모든 모델이 이런 방식으로 실패한다면, 게이트웨이가 Claude Code가 기본적으로 보내는 도구 검색 필드를 거부하고 있는지 확인하세요. 확인하려면 [LLM 게이트웨이를 통한 도구 검색](/docs/ko/mcp#tool-search-through-a-gateway)에 설명된 대로 `ENABLE_TOOL_SEARCH=false`를 설정한 후 다시 시도하세요. v2.1.304 이전에는 `ENABLE_TOOL_SEARCH`로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.
2442* Google Cloud's Agent Platform 배포의 경우 [Google Cloud's Agent Platform 문제 해결](/docs/ko/google-vertex-ai#troubleshooting)을 참조하십시오.
2388 2443
2389### Model is not a recognized model id2444### Model is not a recognized model id
2390 2445
2391모델 전환에 전달한 문자열이 Claude Code가 모델로 사용할 수 있는 것이 아니므로 요청을 보내지 않고 전환을 거부했으며 세션은 현재 모델을 유지합니다. 이 오류는 [Agent SDK](/docs/ko/agent-sdk/typescript) `setModel()` 메서드를 통해 모델을 설정할 때, [Desktop 앱](/docs/ko/desktop)처럼 Claude Code CLI를 대신 실행하는 앱이 모델을 설정할 때, 또는 [Remote Control](/docs/ko/remote-control)로 연결된 장치에서 모델을 선택할 때 발생할 수 있습니다. v2.1.200 이전에는 Claude Code가 문자열을 저장했고 다음 요청에서 [There's an issue with the selected model](#theres-an-issue-with-the-selected-model)로 실패했습니다.2446모델 전환에 전달한 문자열을 Claude Code가 모델로 사용할 수 없으므로, 요청을 보내지 않고 전환을 거부했으며 세션은 현재 모델을 유지합니다. 이 오류는 [Agent SDK](/docs/ko/agent-sdk/typescript)의 `setModel()` 메서드로 모델을 설정할 때, [Desktop 앱](/docs/ko/desktop)처럼 Claude Code CLI를 대신 실행하는 앱이 모델을 설정할 때, 또는 [Remote Control](/docs/ko/remote-control)로 연결된 기기에서 모델을 선택할 때 발생할 수 있습니다. v2.1.200 이전에는 Claude Code가 문자열을 저장한 후 다음 요청에서 [There's an issue with the selected model](#theres-an-issue-with-the-selected-model)로 실패했습니다.
2392 2447
2393```text theme={null}2448```text theme={null}
2394Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?2449Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?
2395```2450```
2396 2451
2397이 예에서는 앱이 표시 이름 `Sonnet 5`를 보냈으며, 메시지는 이를 공백 없이 반복합니다. 뒤따르는 힌트는 가장 가깝게 일치하는 별칭 또는 모델 ID를 표시합니다. 충분히 가까운 것이 없으면 대신 `Run /model to see available models.`로 표시됩니다. [Desktop 앱](/docs/ko/desktop)이 시작하는 세션에서는 일치하는 항목이 없을 때의 힌트가 `Switch to a different model.`로 표시됩니다.2452이 예에서는 앱이 표시 이름 `Sonnet 5`를 보냈고, 메시지는 이를 공백 없이 반복합니다. 끝부분의 힌트는 가장 가깝게 일치하는 별칭이나 모델 ID를 표시합니다. 충분히 가까운 항목이 없으면 대신 `Run /model to see available models.`가 표시됩니다. [Desktop 앱](/docs/ko/desktop)이 시작한 세션에서는 일치 항목이 없을 때의 힌트가 `Switch to a different model.`로 표시됩니다.
2398 2453
2399Anthropic API에서 Agent SDK 또는 앱을 통해 전환하는 경우, 표시 이름이나 빈 문자열처럼 모델 ID가 될 수 없는 문자열만 이 오류를 받습니다.2454Anthropic API에서 Agent SDK나 앱을 통해 전환할 때는 표시 이름이나 빈 문자열처럼 모델 ID가 될 수 없는 문자열만 이 오류가 발생합니다.
2400 2455
2401Remote Control 장치에서 모델을 선택하면 Claude Code가 문자열을 로컬에서 확인합니다. 모델 별칭, Claude Code가 나열하거나 사용자가 구성한 모델, 또는 `claude-`로 시작하는 ID가 아닌 모든 문자열은 이 오류를 받으며, `claud-sonnet-5`와 같이 오타가 있는 ID도 포함됩니다. v2.1.260 이전에는 이 확인이 Remote Control 선택을 다루지 않았으므로 인식되지 않은 문자열이 적용되어 다음 요청에서 실패했습니다.2456Remote Control 기기에서 모델을 선택하면 Claude Code가 문자열을 로컬에서 검사합니다. 모델 별칭, Claude Code가 나열하거나 사용자가 구성한 모델, 또는 `claude-`로 시작하는 ID가 아닌 모든 문자열은 이 오류가 발생하며, `claud-sonnet-5` 같은 오타가 있는 ID도 포함됩니다. v2.1.260 이전에는 이 검사가 Remote Control 선택을 다루지 않았기 때문에, 인식되지 않은 문자열이 적용된 후 다음 요청에서 실패했습니다.
2402 2457
2403**할 일:**2458**해결 방법:**
2404 2459
2405* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용 가능한 모델 중에서 선택한 다음 거기에 표시된 별칭 또는 ID를 전달합니다.2460* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용할 수 있는 모델 중에서 선택한 후, 그곳에 표시된 별칭이나 ID를 전달합니다
2406* 최신 Claude Code 버전에서만 지원하는 별칭을 사용한 경우 `claude update`를 실행하거나 대신 모델의 전체 ID를 전달합니다. 서버는 여전히 해당 모델에 대해 최소 Claude Code 버전을 요구할 수 있습니다. [Claude Code does not support this model](#claude-code-does-not-support-this-model)을 참조하십시오.2461* 최신 Claude Code 버전에서만 지원하는 별칭을 사용한 경우 `claude update`를 실행하거나 대신 모델의 전체 ID를 전달합니다. 서버는 여전히 해당 모델에 대해 최소 Claude Code 버전을 요구할 수 있습니다. [Claude Code does not support this model](#claude-code-does-not-support-this-model)을 참조하십시오.
2407* v2.1.200 이전에 저장된 모델은 이 확인으로 복구되지 않습니다. 오래된 값이 계속 다시 나타나면 [모델 설정](/docs/ko/model-config#setting-your-model)에 나열된 위치에서 제거합니다.2462* v2.1.200 이전에 저장된 모델은 이 검사로 복구되지 않습니다. 오래된 값이 계속 다시 나타나면 [모델 설정](/docs/ko/model-config#setting-your-model)에 나열된 위치에서 제거하십시오.
2408* Anthropic API 이외의 제공자나 게이트웨이 또는 사용자 지정 `ANTHROPIC_BASE_URL` 뒤에서는 빈 문자열만 이 오류를 받습니다. Claude Code는 여전히 모든 제공자에서 요청 시점에 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)을 기록할 수 있습니다.2463* Anthropic API 이외의 공급자에서, 또는 게이트웨이나 사용자 지정 `ANTHROPIC_BASE_URL` 뒤에서는 빈 문자열만 이 오류가 발생합니다. Claude Code는 모든 공급자에서 요청 시점에 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)을 여전히 기록할 수 있습니다.
2409 2464
2410### Model not found2465### Model not found
2411 2466
2412이름으로 모델을 전환했고 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 Claude Code가 로컬에서 허용하는 다른 표기가 아닌 경우 Claude Code는 최소 API 요청으로 이를 확인하며, 이 오류는 일반적으로 API 엔드포인트의 응답입니다. `/model <name>`에서는 공백을 포함하는 이름처럼 애초에 모델 ID가 될 수 없는 이름도 동일한 메시지를 받습니다.2467이름으로 모델을 전환했지만 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](/docs/ko/model-config#model-aliases)이나 Claude Code가 로컬에서 허용하는 다른 표기가 아닌 경우, Claude Code는 최소한의 API 요청으로 이를 확인하며, 이 오류는 보통 API 엔드포인트의 응답입니다. `/model <name>`에서 공백이 포함된 이름처럼 모델 ID가 될 수 없는 이름은 같은 메시지가 표시됩니다.
2413 2468
2414```text theme={null}2469```text theme={null}
2415Model 'claude-opus-9' not found2470Model 'claude-opus-9' not found
2416```2471```
2417 2472
2418제공자별 모델 ID를 사용하는 제공자에서는 메시지에 대체 모델의 제공자 ID를 표시하는 `Try '...' instead` 제안이 추가될 수 있습니다.2473공급자별 모델 ID를 사용하는 공급자에서는 메시지에 공급자의 대체 모델 ID를 명시하는 `Try '...' instead` 제안이 추가될 수 있습니다.
2419 2474
2420**할 일:**2475**해결 방법:**
2421 2476
2422* 인수 없이 `/model`을 실행하고 계정에서 사용 가능한 모델 중에서 선택하거나, 유지 관리되는 기본값으로 확인되는 `sonnet`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases)을 사용합니다.2477* 인수 없이 `/model`을 실행하고 계정에서 사용할 수 있는 모델 중에서 선택하거나, 관리되는 기본값으로 해석되는 `sonnet` 같은 [모델 별칭](/docs/ko/model-config#model-aliases)을 사용합니다
2423* 전체 ID를 입력한 경우 제공자의 모델 카탈로그와 대조해 확인합니다. 새로 출시된 모델은 제공자나 리전에서 제공되기 전에 Anthropic API에서 먼저 사용 가능할 수 있습니다.2478* 전체 ID를 입력했다면 공급자의 모델 카탈로그와 대조하여 확인합니다. 새로 출시된 모델은 공급자나 리전에서 제공되기 전에 Anthropic API에서 먼저 사용 가능할 수 있습니다.
2424* Agent SDK에서 `setModel()`은 이 메시지로 실패하고 세션은 이전 모델에서 계속 실행됩니다. TypeScript SDK에서는 [`supportedModels()`](/docs/ko/agent-sdk/typescript#query-object)를 호출하여 전환할 수 있는 모델을 나열합니다.2479* Agent SDK에서는 `setModel()`이 이 메시지로 실패하고 세션은 이전 모델로 계속 실행됩니다. TypeScript SDK에서는 [`supportedModels()`](/docs/ko/agent-sdk/typescript#query-object)를 호출하여 전환할 수 있는 모델 목록을 확인하십시오.
2425* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 표기도 이 오류로 거부했습니다. 이러한 버전에서는 Claude Code를 업데이트하거나, 대신 [설정](/docs/ko/model-config#setting-your-model)에서 또는 `--model`로 모델을 설정합니다.2480* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 표기도 이 오류로 거부했습니다. 해당 버전에서는 Claude Code를 업데이트하거나 대신 [설정](/docs/ko/model-config#setting-your-model) 또는 `--model`로 모델을 설정하십시오.
2426 2481
2427### Couldn't confirm model with the API2482### Couldn't confirm model with the API
2428 2483
2429[Agent SDK](/docs/ko/agent-sdk/typescript) `setModel()` 메서드를 통해 또는 [Desktop 앱](/docs/ko/desktop)과 같이 Claude Code CLI를 대신 실행하는 앱을 통해 모델을 전환했고, 모델 ID를 API 엔드포인트로 확인하는 요청이 5초 이내에 응답을 받지 못했습니다. 세션은 현재 모델을 유지합니다.2484[Agent SDK](/docs/ko/agent-sdk/typescript)의 `setModel()` 메서드나 [Desktop 앱](/docs/ko/desktop)처럼 Claude Code CLI를 대신 실행하는 앱을 통해 모델을 전환했지만, API 엔드포인트로 모델 ID를 확인하는 요청이 5초 이내에 응답을 받지 못했습니다. 세션은 현재 모델을 유지합니다.
2430 2485
2431```text theme={null}2486```text theme={null}
2432Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.2487Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.
2433```2488```
2434 2489
2435[Desktop 앱](/docs/ko/desktop)이 시작하는 세션에서는 메시지가 `Try again.`에서 끝납니다.2490[Desktop 앱](/docs/ko/desktop)이 시작한 세션에서는 메시지가 `Try again.`에서 끝납니다.
2436 2491
2437**할 일:**2492**해결 방법:**
2438 2493
2439* 모델로 다시 전환합니다.2494* 모델로 다시 전환합니다
2440* 전환이 계속 실패하면 Claude Code가 API 엔드포인트에 연결할 수 있는지 확인합니다. [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오.2495* 전환이 계속 실패하면 Claude Code가 API 엔드포인트에 연결할 수 있는지 확인하십시오. [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오
2441 2496
2442### 선택한 모델을 확인할 때 API 오류2497### 선택한 모델 확인 중 API 오류
2443 2498
2444`/model <name>`으로 모델을 선택했거나 세션에 연결된 앱이 전환을 요청했습니다. Claude Code가 모델을 확인하기 위해 보내는 최소 요청을 API가 별도 항목이 없는 이유(예: 속도 제한 또는 서버 오류)로 거부했습니다. 세션은 현재 모델을 유지하며, 메시지 끝에 그 사실이 표시됩니다:2499`/model <name>`으로 모델을 선택했거나, 세션에 연결된 앱이 전환을 요청했습니다. API가 속도 제한이나 서버 오류처럼 별도 항목이 없는 이유로, Claude Code가 모델 확인을 위해 보내는 최소한의 요청을 거부했습니다. 세션은 현재 모델을 유지하며, 메시지 끝에 그 사실이 표시됩니다.
2445 2500
2446```text theme={null}2501```text theme={null}
2447API error: 429 <the server's explanation> · model not changed2502API error: 429 <the server's explanation> · model not changed
2448```2503```
2449 2504
2450메시지의 중간 부분은 HTTP 상태와 서버 자체의 설명입니다.2505메시지 중간 부분은 HTTP 상태와 서버 자체의 설명입니다.
2451 2506
2452**할 일:**2507**해결 방법:**
2453 2508
2454* 서버의 설명에 따라 조치합니다. 속도 제한 또는 5xx 상태의 경우 기다렸다가 모델을 다시 선택합니다.2509* 서버의 설명에 따라 조치합니다. 속도 제한이나 5xx 상태인 경우 잠시 기다린 후 모델을 다시 선택합니다
2455* 고유한 문구가 있는 거부는 [Model not found](#model-not-found) 및 [Model is restricted by your organization's settings](#model-is-restricted-by-your-organizations-settings)와 같은 주변 항목에서 다룹니다.2510* 고유한 문구가 있는 거부는 [Model not found](#model-not-found)와 [Model is restricted by your organization's settings](#model-is-restricted-by-your-organizations-settings) 같은 주변 항목에서 다룹니다
2456 2511
2457### Claude Opus is not available with the Claude Pro plan2512### Claude Opus is not available with the Claude Pro plan
2458 2513
2459활성 구독 플랜에 선택한 모델이 포함되지 않습니다.2514현재 구독 플랜에 선택한 모델이 포함되어 있지 않습니다.
2460 2515
2461```text theme={null}2516```text theme={null}
2462Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.2517Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.
2463```2518```
2464 2519
2465Claude Desktop 앱이 실행하는 세션에서는 메시지가 명령을 표시하는 대신 `sign out and sign in again`이라고 안내합니다.2520Claude Desktop 앱이 실행하는 세션에서는 메시지가 명령 이름 대신 `sign out and sign in again`이라고 안내합니다.
2466 2521
2467**할 일:**2522**해결 방법:**
2468 2523
2469* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다.2524* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다
2470* 최근에 플랜을 업그레이드했는데도 여전히 이 메시지가 표시되면 `/logout`을 실행한 다음 `/login`을 실행합니다. 저장된 토큰은 로그인 시점의 플랜을 반영하므로 claude.ai에서 업그레이드해도 다시 인증할 때까지 기존 세션에는 적용되지 않습니다.2525* 최근에 플랜을 업그레이드했는데도 이 메시지가 나타나면 `/logout`을 실행한 후 `/login`을 실행합니다. 저장된 토큰은 로그인 시점의 플랜을 반영하므로, claude.ai에서 업그레이드해도 다시 인증하기 전까지 기존 세션에는 적용되지 않습니다.
2471* 각 플랜에 포함된 모델에 대해서는 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.2526* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오
2472 2527
2473### Claude Code does not support this model2528### Claude Code does not support this model
2474 2529
2475Claude Code 버전이 필요한 최소 버전보다 낮기 때문에 API가 400으로 요청을 거부했습니다. 선택한 모델이 더 최신 버전을 요구하거나(서버가 모델별로 확인), 조직의 정책이 이를 요구합니다. 400에는 오류 코드 `claude_code_version_too_old`가 포함되며, 메시지에 어떤 최소 버전이 적용되는지 표시됩니다.2530Claude Code 버전이 요구되는 최소 버전보다 낮아서 API가 400으로 요청을 거부했습니다. 선택한 모델이 서버가 모델별로 검사하는 더 새로운 버전을 요구하거나, 조직 정책이 특정 버전을 요구하는 경우입니다. 400에는 오류 코드 `claude_code_version_too_old`가 포함되며, 메시지에 어떤 최소 버전이 적용되는지 표시됩니다.
2476 2531
2477```text theme={null}2532```text theme={null}
2478API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.2533API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.
2479```2534```
2480 2535
2481조직 정책 문구는 다음과 같습니다:2536조직 정책 문구는 다음과 같습니다.
2482 2537
2483```text theme={null}2538```text theme={null}
2484API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.2539API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.
2485```2540```
2486 2541
2487API가 확인하는 버전은 요청을 보낸 Claude Code 바이너리가 보고하는 버전입니다.2542API가 검사하는 버전은 요청을 보낸 Claude Code 바이너리가 보고하는 버전입니다.
2488 2543
2489**할 일:**2544**해결 방법:**
2490 2545
2491해당 바이너리를 업데이트한 다음 새 세션을 시작합니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-deploy#pin-the-version)을 제외하면 업데이트 방법은 바이너리의 출처에 따라 결정됩니다:2546해당 바이너리를 업데이트한 후 새 세션을 시작하십시오. [자체 호스팅 환경](/docs/ko/self-hosted-environments-deploy#pin-the-version)을 제외하면, 바이너리의 출처에 따라 업데이트 방법이 결정됩니다.
2492 2547
2493| 요청을 보낸 바이너리 | 업데이트 방법 |2548| 요청을 보낸 바이너리 | 업데이트 방법 |
2494| :- | :- |2549| :- | :- |
2495| 설치한 Claude Code | `claude update` 실행 |2550| 직접 설치한 Claude Code | `claude update` 실행 |
2496| Claude Desktop 앱 | 앱 업데이트 |2551| Claude desktop 앱 | 앱 업데이트 |
2497| [VS Code 확장](/docs/ko/vs-code)에 번들로 포함된 바이너리 | 확장 업데이트 |2552| [VS Code 확장](/docs/ko/vs-code)에 번들로 포함된 바이너리 | 확장 업데이트 |
2498| Agent SDK 패키지에 번들로 포함된 바이너리 | [SDK 패키지 업그레이드](/docs/ko/agent-sdk/hosting#runtime-dependencies) 후 애플리케이션 다시 시작. [컴파일된 단일 파일 실행 파일](/docs/ko/agent-sdk/typescript#compile-to-a-single-executable)에서는 다시 빌드 |2553| Agent SDK 패키지에 번들로 포함된 바이너리 | [SDK 패키지를 업그레이드](/docs/ko/agent-sdk/hosting#runtime-dependencies)한 후 애플리케이션을 재시작합니다. [컴파일된 단일 파일 실행 파일](/docs/ko/agent-sdk/typescript#compile-to-a-single-executable)의 경우 다시 빌드합니다 |
2499 2554
2500* [stable 릴리스 채널](/docs/ko/setup#configure-release-channel)에서 `claude update`를 실행하면 최신 stable 릴리스 이후로는 이동하지 않으며, 이 릴리스는 여전히 필요한 최소 버전보다 낮을 수 있습니다. latest 채널로 이동한 다음 다시 업데이트합니다. 조직이 [관리형 설정](/docs/ko/managed-settings)을 통해 채널이나 버전을 고정하는 경우 관리자에게 변경을 요청합니다.2555* [stable 릴리스 채널](/docs/ko/setup#configure-release-channel)에서 `claude update`를 실행하면 최신 stable 릴리스보다 더 새로운 버전으로 이동하지 않으며, 이 릴리스도 요구되는 최소 버전보다 낮을 수 있습니다. latest 채널로 이동한 후 다시 업데이트하십시오. 조직이 [관리형 설정](/docs/ko/managed-settings)으로 채널이나 버전을 고정한 경우 관리자에게 변경을 요청하십시오
2501* 모델별 문구의 경우 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다: CLI에서 `/model`을 실행하거나, 스트리밍 입력 모드에서 TypeScript SDK의 `Query` 객체에서 [`setModel()`](/docs/ko/agent-sdk/typescript#query-object)을 호출하거나, Python SDK의 `ClaudeSDKClient`에서 [`set_model()`](/docs/ko/agent-sdk/python#claudesdkclient)을 호출합니다.2556* 모델별 문구의 경우 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다. CLI에서는 `/model`을 실행하고, 스트리밍 입력 모드에서는 TypeScript SDK의 `Query` 객체에서 [`setModel()`](/docs/ko/agent-sdk/typescript#query-object)을, Python SDK의 `ClaudeSDKClient`에서 [`set_model()`](/docs/ko/agent-sdk/python#claudesdkclient)을 호출하십시오
2502* 조직 정책 문구의 경우 계속하기 전에 업데이트합니다.2557* 조직 정책 문구의 경우 계속하기 전에 업데이트하십시오
2503 2558
2504### Model is restricted by your organization's settings2559### Model is restricted by your organization's settings
2505 2560
2506조직 관리자가 claude.ai 관리자 콘솔에서 이 모델을 비활성화했거나, 관리형 설정이 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록 또는 [`deniedModels`](/docs/ko/model-config#block-specific-models-or-versions) 목록을 통해 이 모델을 제외합니다. 이 알림은 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정이 제한된 모델을 지정했을 때 시작 시 나타나며, 세션이 대신 사용하는 모델을 표시합니다. 관리형 설정이 세션에서 사용할 수 있는 허용된 모델을 남기지 않는 경우 [관리형 설정이 기본 모델을 차단합니다](#managed-settings-block-the-default-model)를 참조하십시오. 대체 알림은 관리자가 claude.ai 관리자 콘솔에서 세션이 실행 중인 모델을 비활성화한 후 세션 도중에도 나타날 수 있습니다.2561조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나, 관리형 설정이 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록이나 [`deniedModels`](/docs/ko/model-config#block-specific-models-or-versions) 목록으로 이 모델을 제외했습니다. 이 알림은 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정이 제한된 모델을 지정했을 때 시작 시 표시되며, 세션이 대신 사용하는 모델을 명시합니다. 관리형 설정으로 인해 세션이 사용할 수 있는 허용된 모델이 없는 경우 [관리형 설정이 기본 모델을 차단하는 경우](#managed-settings-block-the-default-model)를 참조하십시오. 관리자가 claude.ai 관리 콘솔에서 세션이 실행 중인 모델을 비활성화하면 세션 도중에도 대체 알림이 표시될 수 있습니다.
2507 2562
2508```text theme={null}2563```text theme={null}
2509Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.2564Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.
2510```2565```
2511 2566
2512제한된 모델에 대해 `/model <name>`을 입력하면 거부되고 세션은 현재 모델을 유지합니다. 관리자 콘솔에서 비활성화된 모델의 경우 거부 메시지는 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`입니다. 관리형 설정이 제외하는 모델의 경우 `Model '<name>' is not available. Your organization restricts model selection.`입니다.2567제한된 모델에 대해 `/model <name>`을 입력하면 거부되고 세션은 현재 모델을 유지합니다. 관리 콘솔에서 비활성화된 모델의 경우 거부 메시지는 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`입니다. 관리형 설정이 제외한 모델의 경우 `Model '<name>' is not available. Your organization restricts model selection.`입니다.
2513 2568
2514알림 앞에 에이전트, 스킬 또는 명령 이름이 붙어 있으면 제한이 해당 [서브에이전트의 요청된 모델](/docs/ko/sub-agents#choose-a-model)에 적용되었음을 의미합니다: 서브에이전트는 대체 모델에서 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 시작된 서브에이전트에 대해서만 알림을 표시했습니다.2569에이전트, 스킬 또는 명령 이름이 앞에 붙은 알림은 제한이 해당 [서브에이전트가 요청한 모델](/docs/ko/sub-agents#choose-a-model)에 적용되었다는 뜻입니다. 서브에이전트는 대체된 모델에서 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 실행된 서브에이전트에 대해서만 이 알림을 표시했습니다.
2515 2570
2516Claude Code는 모델 패밀리 별칭(`opus`, `sonnet`, `haiku`, `fable` 중 하나)을 최신 버전이 아닌 해당 패밀리에 대한 요청으로 취급합니다. Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에서 제한된 패밀리 별칭은 조직의 설정이 허용하는 해당 패밀리의 최신 버전으로 확인되며, 대체 알림은 해당 버전을 표시합니다. Claude Code는 패밀리의 모든 버전이 제한된 경우에만 `/model <alias>`를 거부합니다. v2.1.205 이전에는 같은 패밀리의 이전 버전이 허용되더라도 패밀리 별칭이 최신 버전만을 기준으로 대체되거나 거부되었습니다.2571Claude Code는 `opus`, `sonnet`, `haiku`, `fable` 중 하나인 모델 패밀리 별칭을 최신 버전이 아닌 해당 패밀리에 대한 요청으로 처리합니다. Anthropic API와 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에서는 제한된 패밀리 별칭이 조직 설정에서 허용하는 해당 패밀리의 최신 버전으로 해석되며, 대체 알림에 해당 버전이 표시됩니다. Claude Code는 패밀리의 모든 버전이 제한된 경우에만 `/model <alias>`를 거부합니다. v2.1.205 이전에는 같은 패밀리의 이전 버전이 허용되더라도 패밀리 별칭이 최신 버전만을 기준으로 대체되거나 거부되었습니다.
2517 2572
2518**할 일:**2573**해결 방법:**
2519 2574
2520* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에서 숨겨집니다.2575* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에 표시되지 않습니다.
2521* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드 또는 [서브에이전트](/docs/ko/sub-agents#choose-a-model), 스킬 또는 명령의 `model` frontmatter에 설정된 경우 해당 값을 제거하거나 업데이트하여 알림이 반복되지 않도록 합니다.2576* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드, 또는 [서브에이전트](/docs/ko/sub-agents#choose-a-model), 스킬, 명령의 `model` frontmatter에 설정되어 있다면, 알림이 반복되지 않도록 해당 값을 제거하거나 업데이트하십시오
2522* 제한된 모델에 액세스해야 하는 경우 조직 관리자에게 활성화를 요청합니다. [조직 모델 제한](/docs/ko/model-config#organization-model-restrictions)을 참조하십시오.2577* 제한된 모델에 액세스해야 한다면 조직 관리자에게 활성화를 요청하십시오. [조직 모델 제한](/docs/ko/model-config#organization-model-restrictions)을 참조하십시오.
2523 2578
2524### Can't switch to the default model2579### Can't switch to the default model
2525 2580
2526기본 모델을 선택했습니다. 예를 들어 `/model` 선택기에서 Default 행을 선택하거나 `/model default`를 입력했습니다. Claude Code가 전환을 거부했으므로 세션은 현재 모델을 유지합니다.2581`/model` 선택기에서 Default 행을 선택하거나 `/model default`를 입력하는 등의 방법으로 Default 모델을 선택했습니다. Claude Code가 전환을 거부했으므로 세션은 현재 모델을 유지합니다.
2527 2582
2528```text theme={null}2583```text theme={null}
2529Can't switch to the default model: your organization's managed settings block it (claude-opus-4-6) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".2584Can't switch to the default model: your organization's managed settings block it (claude-opus-4-6) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".
2530```2585```
2531 2586
2532콜론 뒤의 문구는 무엇이 전환을 차단했는지 나타냅니다:2587콜론 뒤의 문구는 전환을 차단한 원인을 나타냅니다.
2533 2588
2534* **`your organization's managed settings block it ... in "deniedModels"`**: 관리형 거부 목록이 Default 옵션이 확인되는 모델을 차단합니다.2589* **`your organization's managed settings block it ... in "deniedModels"`**: 관리형 거부 목록이 Default 옵션이 해석되는 모델을 차단합니다
2535* **`your organization allows only the models listed in "availableModels"`**: [`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch)가 `"exact"`로 설정된 관리형 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록이 Default 옵션이 확인되는 모델을 제외합니다.2590* **`your organization allows only the models listed in "availableModels"`**: [`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch)가 `"exact"`로 설정된 관리형 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에 Default 옵션이 해석되는 모델이 없습니다
2536* **`Claude Code couldn't read your organization's managed settings to check which models they allow`**: [관리형 설정](/docs/ko/managed-settings)을 읽을 수 없었고, Claude Code는 확인되지 않은 전환을 적용하는 대신 거부합니다.2591* **`Claude Code couldn't read your organization's managed settings to check which models they allow`**: [관리형 설정](/docs/ko/managed-settings)을 읽을 수 없어서, Claude Code가 확인 없이 전환을 적용하는 대신 거부했습니다
2537 2592
2538**할 일:**2593**해결 방법:**
2539 2594
2540* [`deniedModels`](/docs/ko/settings-reference#deniedmodels) 및 `availableModels` 문구의 경우 `/model`을 실행하고 조직이 허용하는 모델을 이름으로 선택합니다.2595* [`deniedModels`](/docs/ko/settings-reference#deniedmodels) 및 `availableModels` 문구의 경우 `/model`을 실행하고 조직이 허용하는 모델을 이름으로 선택합니다
2541* 관리자에게 메시지가 지정하는 관리형 설정을 업데이트하도록 요청합니다.2596* 관리자에게 메시지가 명시하는 관리형 설정을 업데이트해 달라고 요청합니다
2542* `couldn't read` 문구의 경우 Claude Code를 다시 시작합니다. 계속 발생하면 관리자에게 관리형 설정을 확인하도록 요청합니다.2597* `couldn't read` 문구의 경우 Claude Code를 재시작합니다. 계속 발생하면 관리자에게 관리형 설정을 확인해 달라고 요청하십시오
2543 2598
2544이러한 관리형 설정에서 세션이 대신 `Claude Code can't start` 메시지와 함께 시작되지 않는 경우 [관리형 설정이 기본 모델을 차단합니다](#managed-settings-block-the-default-model)를 참조하십시오.2599이러한 관리형 설정에서 세션이 대신 `Claude Code can't start` 메시지와 함께 시작되지 않는 경우 [관리형 설정이 기본 모델을 차단하는 경우](#managed-settings-block-the-default-model)를 참조하십시오.
2545 2600
2546### Model switch was blocked by a PreModelSwitch hook2601### Model switch was blocked by a PreModelSwitch hook
2547 2602
2548[PreModelSwitch 훅](/docs/ko/hooks#premodelswitch)이 사용자 또는 클라이언트가 요청한 모델 전환을 승인하지 않았으므로 세션은 현재 모델을 유지합니다. 전환이 사용자가 입력한 명령이 아니라 [Agent SDK](/docs/ko/agent-sdk/overview) 호스트 또는 [Remote Control](/docs/ko/remote-control)에서 온 경우 메시지는 대상 모델을 표시하지 않고 `Model switch blocked by a PreModelSwitch hook`으로 표시됩니다.2603[PreModelSwitch 훅](/docs/ko/hooks#premodelswitch)이 사용자나 클라이언트가 요청한 모델 전환을 승인하지 않았으므로 세션은 현재 모델을 유지합니다. 직접 입력한 명령이 아니라 [Agent SDK](/docs/ko/agent-sdk/overview) 호스트나 [Remote Control](/docs/ko/remote-control)에서 전환이 요청된 경우, 메시지는 대상 모델을 명시하지 않고 `Model switch blocked by a PreModelSwitch hook`으로 표시됩니다.
2549 2604
2550```text theme={null}2605```text theme={null}
2551Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.2606Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.
2552```2607```
2553 2608
2554콜론 뒤의 이유는 무엇이 전환을 거부했는지 나타냅니다:2609콜론 뒤의 이유는 무엇이 전환을 거부했는지를 나타냅니다.
2555 2610
2556* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](/docs/ko/hooks#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청 내용을 해결하거나 훅이 허용하는 모델을 선택합니다.2611* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](/docs/ko/hooks#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청 사항을 해결하거나 훅이 허용하는 모델을 선택하십시오.
2557* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](/docs/ko/hooks#timeouts) 전에 응답하지 않는 훅은 전환을 차단합니다. 멈춘 명령을 수정하거나 해당 훅의 `timeout`을 높인 다음 다시 전환합니다.2612* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](/docs/ko/hooks#timeouts) 전에 응답하지 않는 훅은 전환을 차단합니다. 멈춘 명령을 수정하거나 해당 훅의 `timeout`을 늘린 후 다시 전환하십시오.
2558* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했으며, 제어 요청에는 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](/docs/ko/headless)의 `/model` 명령은 이유 뒤에 `(run /model interactively to confirm)`을 붙여 동일한 조건을 보고합니다. 대화형 세션에서 전환하거나 이 모델에 대한 훅의 결정을 변경합니다.2613* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했으며, 제어 요청에는 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](/docs/ko/headless)의 `/model` 명령은 이유 뒤에 `(run /model interactively to confirm)`을 붙여 같은 상황을 보고합니다. 대화형 세션에서 전환하거나, 이 모델에 대한 훅의 결정을 변경하십시오.
2559* **`so organization-managed PreModelSwitch hooks could not be checked`**: Claude Code가 조직의 [관리형 플러그인](/docs/ko/settings-reference#enabledplugins)이 제공하는 PreModelSwitch 훅을 파악할 수 없었습니다. 예를 들어 관리형 플러그인이 로드되지 않은 경우입니다. 이러한 훅 중 하나가 전환을 차단할 수 있으므로 Claude Code는 확인되지 않은 전환을 적용하는 대신 거부합니다. 이유의 앞부분은 무엇이 실패했는지 나타냅니다. Claude Code는 모든 전환 시도마다 다시 확인하므로 이후 해소된 실패는 더 이상 차단하지 않습니다. 계속 실패하면 `claude --debug`를 실행하고 다시 전환하여 세부 정보를 캡처한 다음 플러그인을 수정하거나 관리자에게 수정을 요청합니다.2614* **`so organization-managed PreModelSwitch hooks could not be checked`**: 예를 들어 관리형 플러그인 로드가 실패하여, Claude Code가 조직의 [관리형 플러그인](/docs/ko/settings-reference#enabledplugins)이 제공하는 PreModelSwitch 훅을 확인할 수 없었습니다. 그 훅 중 하나가 전환을 차단할 수 있으므로, Claude Code는 확인 없이 전환을 적용하는 대신 거부합니다. 이유의 시작 부분에 무엇이 실패했는지 표시됩니다. Claude Code는 전환을 시도할 때마다 다시 확인하므로, 이미 해소된 실패는 더 이상 차단하지 않습니다. 계속 실패하면 `claude --debug`를 실행하고 다시 전환하여 세부 정보를 확인한 후, 플러그인을 수정하거나 관리자에게 수정을 요청하십시오.
2560* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 판정 없이 끝났으며, Claude Code는 이를 승인으로 취급하지 않습니다. `claude --debug`를 실행하여 무엇이 실패했는지 확인한 다음 다시 전환합니다.2615* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 판정 없이 종료되었으며, Claude Code는 이를 승인으로 처리하지 않습니다. `claude --debug`를 실행하여 무엇이 실패했는지 확인한 후 다시 전환하십시오.
2561 2616
2562v2.1.260 이전에는 관리형 플러그인 거부 메시지가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`였습니다. Claude Code는 플러그인 로드를 한 번 재시도한 다음, 조직이 관리하는 플러그인이 없는 경우에도 세션의 이후 전환을 거부했습니다. 이러한 버전에서는 세션을 다시 시작하여 플러그인 로드를 다시 실행합니다.2617v2.1.260 이전에는 관리형 플러그인 거부 메시지가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`였습니다. Claude Code는 플러그인 로드를 한 번 재시도한 후, 조직이 관리하는 플러그인이 없는 경우에도 세션의 이후 전환을 거부했습니다. 해당 버전에서는 세션을 재시작하여 플러그인 로드를 다시 실행하십시오.
2563 2618
2564### Couldn't save it as your default2619### Couldn't save it as your default
2565 2620
2566모델을 기본값으로 저장하도록 선택했지만(예: `/model <name>` 또는 `/model` 선택기에서 `Enter`), Claude Code가 사용자 설정 파일 `~/.claude/settings.json`에 선택을 쓸 수 없었습니다. 전환 자체는 적용되었으므로 현재 세션은 선택한 모델에서 실행되지만 기본값은 변경되지 않으며 다음 세션은 이전 값으로 시작됩니다.2621`/model <name>` 또는 `/model` 선택기에서 `Enter`를 누르는 등의 방법으로 기본값으로 저장할 모델을 선택했지만, Claude Code가 사용자 설정 파일인 `~/.claude/settings.json`에 선택 내용을 기록할 수 없었습니다. 전환 자체는 적용되었으므로 현재 세션은 선택한 모델로 실행되지만, 기본값은 변경되지 않았으며 다음 세션은 이전 값으로 시작됩니다.
2567 2622
2568```text theme={null}2623```text theme={null}
2569Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)2624Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)
2570```2625```
2571 2626
2572파일 경로 뒤의 이유는 무엇이 실패했는지 나타냅니다:2627파일 경로 뒤의 이유는 무엇이 실패했는지를 나타냅니다.
2573 2628
2574* **`can't be written (<code>)`**: 쓰기가 괄호 안의 운영 체제 오류 코드로 실패했습니다. 예를 들어 파일 또는 파일이 링크하는 대상이 쓰기를 거부하는 파일 시스템에 있을 때 `EROFS`가 표시됩니다. 파일을 쓰기 가능하게 만들고 다시 전환합니다. 다른 도구가 파일을 생성하는 경우 대신 해당 도구에서 `model` 키를 설정합니다. [Claude Code에서 만든 변경 사항이 새 세션에서 사라집니다](/docs/ko/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)를 참조하십시오.2629* **`can't be written (<code>)`**: 괄호 안의 운영 체제 오류 코드와 함께 기록이 실패했습니다. 예를 들어 파일 또는 파일이 링크하는 대상이 쓰기를 거부하는 파일 시스템에 있는 경우 `EROFS`가 표시됩니다. 파일을 쓰기 가능하게 만든 후 다시 전환하십시오. 다른 도구가 파일을 생성하는 경우 대신 해당 도구에서 `model` 키를 설정하십시오. [Claude Code에서 변경한 내용이 새 세션에서 사라지는 경우](/docs/ko/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)를 참조하십시오.
2575* **`isn't valid JSON`**: 디스크의 파일이 구문 분석되지 않으며, Claude Code는 다시 읽을 수 없는 내용을 덮어쓰지 않도록 파일을 그대로 둡니다. 구문 오류를 수정한 다음 다시 전환합니다. [손상된 설정 파일 수정](/docs/ko/settings#fix-a-broken-settings-file)을 참조하십시오.2630* **`isn't valid JSON`**: 디스크의 파일을 파싱할 수 없으며, Claude Code는 다시 읽을 수 없는 내용을 덮어쓰지 않고 그대로 둡니다. 구문 오류를 수정한 후 다시 전환하십시오. [손상된 설정 파일 수정](/docs/ko/settings#fix-a-broken-settings-file)을 참조하십시오.
2576 2631
2577`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 알림은 3초가 지나도 쓰기가 완료되지 않았음을 의미합니다. 쓰기는 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델로 시작되는지 확인하거나 `/model <name>`을 다시 실행합니다.2632`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 알림은 3초가 지나도 기록이 완료되지 않았다는 뜻입니다. 기록은 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델로 시작되는지 확인하거나 `/model <name>`을 다시 실행하십시오.
2578 2633
2579v2.1.265 이전에는 쓰기가 실패한 경우에도 알림이 모델이 `saved as your default for new sessions`되었다고 표시했습니다.2634v2.1.265 이전에는 기록이 실패한 경우에도 알림에 모델이 `saved as your default for new sessions`라고 표시되었습니다.
2580 2635
2581### Advisor가 현재 메인 모델보다 성능이 낮습니다2636### Advisor is less capable than the current main model
2582 2637
2583[advisor 모델](/docs/ko/advisor)이 세션의 메인 모델보다 순위가 낮으므로, Claude Code는 선택을 유지하지만 메인 모델의 요청에 advisor를 연결하지 않습니다.2638[advisor 모델](/docs/ko/advisor)의 순위가 세션의 메인 모델보다 낮으므로, Claude Code는 선택 내용을 유지하지만 advisor를 메인 모델의 요청에 연결하지 않습니다.
2584 2639
2585```text theme={null}2640```text theme={null}
2586Advisor set to Opus 4.82641Advisor set to Opus 4.8
2587Note: Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.2642Note: Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.
2588```2643```
2589 2644
2590다른 메시지도 동일한 조건을 보고합니다:2645다른 메시지도 같은 상황을 보고합니다.
2591 2646
2592* 대화형 세션에서는 알림에 `Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor`가 표시됩니다.2647* 대화형 세션에서는 `Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor`라는 알림이 표시됩니다.
2593* `--advisor` 플래그로 시작할 때는 경고에 `"<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.`가 표시되며, 세션은 그대로 시작됩니다.2648* [비대화형 모드](/docs/ko/headless)에서 `--advisor` 플래그와 함께 실행하고 해당 실행이 [백그라운드 세션](/docs/ko/agent-view)이 아닌 경우, stderr에 경고가 출력되고 실행은 그대로 시작됩니다. 경고는 `"<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.`입니다. 대화형 세션은 이 경고를 [디버그 로그](#configuration-warnings)에만 기록합니다.
2594 2649
2595**할 일:**2650**해결 방법:**
2596 2651
2597* 더 높은 순위의 advisor 또는 더 낮은 순위의 메인 모델을 선택합니다. [advisor 모델 선택](/docs/ko/advisor#choose-an-advisor-model)에서 순위와 각 메인 모델에 허용되는 advisor 목록을 확인할 수 있습니다.2652* 순위가 더 높은 advisor나 순위가 더 낮은 메인 모델을 선택합니다. [advisor 모델 선택](/docs/ko/advisor#choose-an-advisor-model)에서 순위를 확인하고 각 메인 모델에 허용되는 advisor 목록을 볼 수 있습니다.
2598* advisor가 조언할 수 있는 모델을 사용하는 [서브에이전트](/docs/ko/sub-agents)가 계속 advisor를 사용하도록 하려면 advisor 설정을 그대로 둡니다.2653* advisor가 자문할 수 있는 모델의 [서브에이전트](/docs/ko/sub-agents)가 계속 advisor를 사용하도록 하려면 advisor 설정을 그대로 두십시오
2599 2654
2600v2.1.287 이전에는 Claude Code가 여러 조합의 순위를 다르게 매겼습니다. Opus 4.7 또는 Opus 4.8 메인 모델에 Sonnet 5.5 advisor를 사용할 때 이 메모를 표시했지만, 이 조합은 이제 허용됩니다. 또한 Sonnet 5.5 메인 모델에 Opus 4.8 advisor를 사용하는 경우처럼 현재는 이 메모가 표시되는 일부 advisor를 연결했습니다.2655v2.1.287 이전에는 Claude Code가 여러 조합의 순위를 다르게 매겼습니다. Opus 4.7 또는 Opus 4.8 메인 모델과 Sonnet 5.5 advisor 조합에 대해 이 안내를 표시했지만, 현재는 이 조합을 허용합니다. 또한 Sonnet 5.5 메인 모델과 Opus 4.8 advisor처럼 현재는 이 안내를 표시하는 일부 advisor를 연결했습니다.
2601 2656
2602### thinking.type.enabled is not supported for this model2657### thinking.type.enabled is not supported for this model
2603 2658
2604Claude Code 버전이 선택한 모델의 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.2659Claude Code 버전이 선택한 모델에 필요한 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.
2605 2660
2606```text theme={null}2661```text theme={null}
2607API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.2662API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
2608```2663```
2609 2664
2610**할 일:**2665**해결 방법:**
2611 2666
2612* `claude update`를 실행하고 Claude Code를 다시 시작합니다. Opus 4.7은 v2.1.111 이상이 필요합니다. Opus 4.8은 v2.1.154 이상이 필요합니다. Sonnet 5는 v2.1.197 이상이 필요합니다. Opus 5는 v2.1.219 이상이 필요합니다. Opus 5.5는 v2.1.280 이상이 필요합니다. Sonnet 5.5는 v2.1.284 이상이 필요합니다.2667* `claude update`를 실행하고 Claude Code를 재시작합니다. Opus 4.7에는 v2.1.111 이상이 필요합니다. Opus 4.8에는 v2.1.154 이상이 필요합니다. Sonnet 5에는 v2.1.197 이상이 필요합니다. Opus 5에는 v2.1.219 이상이 필요합니다. Opus 5.5에는 v2.1.280 이상이 필요합니다. Sonnet 5.5에는 v2.1.284 이상이 필요합니다
2613* [stable 릴리스 채널](/docs/ko/setup#configure-release-channel)에서는 업데이트해도 최신 stable 릴리스 이후로는 이동하지 않으며, 이 릴리스는 여전히 이러한 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 다음 업데이트합니다.2668* [stable 릴리스 채널](/docs/ko/setup#configure-release-channel)에서는 업데이트해도 최신 stable 릴리스보다 더 새로운 버전으로 이동하지 않으며, 이 릴리스도 위 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 후 업데이트하십시오
2614* 업그레이드할 수 없으면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택합니다.2669* 업그레이드할 수 없다면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택합니다
2615* [Agent SDK](/docs/ko/agent-sdk/overview)에서 이 오류가 발생하면 대신 SDK 패키지를 업그레이드합니다. Opus 4.8은 TypeScript SDK v0.3.154 이상 및 Python SDK v0.2.88 이상이 필요합니다. Sonnet 5는 TypeScript SDK v0.3.197 이상이 필요합니다. Opus 5는 TypeScript SDK v0.3.219 이상이 필요합니다. Opus 5.5는 TypeScript SDK v0.3.280 이상이 필요합니다. Sonnet 5.5는 TypeScript SDK v0.3.284 이상이 필요합니다.2670* [Agent SDK](/docs/ko/agent-sdk/overview)에서 이 오류가 발생하면 대신 SDK 패키지를 업그레이드하십시오. Opus 4.8에는 TypeScript SDK v0.3.154 이상과 Python SDK v0.2.88 이상이 필요합니다. Sonnet 5에는 TypeScript SDK v0.3.197 이상이 필요합니다. Opus 5에는 TypeScript SDK v0.3.219 이상이 필요합니다. Opus 5.5에는 TypeScript SDK v0.3.280 이상이 필요합니다. Sonnet 5.5에는 TypeScript SDK v0.3.284 이상이 필요합니다
2616 2671
2617### 사고가 꺼져 있으면 effort를 사용할 수 없습니다2672### 사고가 꺼진 상태에서는 effort를 사용할 수 없음
2618 2673
2619[확장 사고](/docs/ko/model-config#extended-thinking)를 끄고 `high`보다 높은 [effort 수준](/docs/ko/model-config#adjust-effort-level)으로 실행했습니다. 모델이 해당 조합을 허용하지 않으므로 API가 요청을 거부했습니다.2674[확장 사고](/docs/ko/model-config#extended-thinking)를 끈 상태에서 `high`보다 높은 [effort 수준](/docs/ko/model-config#adjust-effort-level)으로 실행했습니다. 모델이 이 조합을 허용하지 않으므로 API가 요청을 거부했습니다.
2620 2675
2621```text theme={null}2676```text theme={null}
2622API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)2677API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)
2623```2678```
2624 2679
2625`·` 뒤의 힌트는 세션에 따라 다릅니다: 비대화형 세션에서는 `use --effort high (or the effortLevel setting)`로, Claude Desktop 앱이 실행하는 세션에서는 `you can lower effort to High`로 표시됩니다.2680`·` 뒤의 힌트는 세션에 따라 다릅니다. 비대화형 세션에서는 `use --effort high (or the effortLevel setting)`으로, Claude Desktop 앱이 실행하는 세션에서는 `you can lower effort to High`로 표시됩니다.
2626 2681
2627**할 일:**2682**해결 방법:**
2628 2683
2629* [effort 수준을 낮춰](/docs/ko/model-config#set-the-effort-level) `high` 이하로 설정합니다.2684* [effort 수준을](/docs/ko/model-config#set-the-effort-level) `high` 이하로 낮춥니다.
2630* 사고를 다시 켭니다. 예를 들어 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars) 설정을 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](/docs/ko/settings-reference#alwaysthinkingenabled)를 제거합니다.2685* 예를 들어 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars) 설정을 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](/docs/ko/settings-reference#alwaysthinkingenabled)를 제거하여 사고를 다시 켭니다.
2631 2686
2632v2.1.242 이전에는 Claude Code가 API 자체의 메시지를 표시했습니다: `API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` v2.1.251 이전에는 Claude Code가 설정한 effort 수준으로 요청을 보냈으므로, 사고가 꺼져 있을 때 Opus 5는 `high`보다 높은 모든 요청을 거부했습니다. 이제 Claude Code는 Opus 5처럼 이 조합을 거부하는 것으로 알려진 모델에는 대신 effort `high`를 보냅니다.2687v2.1.242 이전에는 Claude Code가 API 자체의 메시지를 표시했습니다: `API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` v2.1.251 이전에는 Claude Code가 설정한 effort 수준 그대로 요청을 보냈기 때문에, 사고가 꺼진 상태에서 Opus 5는 `high`보다 높은 모든 요청을 거부했습니다. 이제 Claude Code는 Opus 5처럼 이 조합을 거부하는 것으로 알려진 모델에는 대신 effort `high`로 요청을 보냅니다.
2633 2688
2634### 사고 예산이 출력 제한을 초과합니다2689### Thinking budget exceeds output limit
2635 2690
2636구성된 확장 사고 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.2691구성된 확장 사고 예산이 최대 응답 길이를 초과하여 실제 답변을 위한 공간이 남아 있지 않습니다.
2637 2692
2638```text theme={null}2693```text theme={null}
2639API Error: 400 ... max_tokens must be greater than thinking.budget_tokens2694API Error: 400 ... max_tokens must be greater than thinking.budget_tokens
2640```2695```
2641 2696
2642**할 일:**2697**해결 방법:**
2643 2698
2644* [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를 사고 예산보다 높게 올립니다.2699* [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를 사고 예산보다 높게 올립니다
2645* 예산이 출력 길이와 상호 작용하는 방식은 [확장 사고](/docs/ko/model-config#extended-thinking)를 참조하십시오.2700* 예산이 출력 길이와 어떻게 상호 작용하는지는 [확장 사고](/docs/ko/model-config#extended-thinking)를 참조하십시오
2646 2701
2647### Response exceeded the output token maximum2702### Response exceeded the output token maximum
2648 2703
2649Claude의 응답이 요청에서 허용한 최대 출력 토큰 수에 도달하여 그 지점에서 잘렸습니다:2704Claude의 응답이 요청에서 허용한 최대 출력 토큰 수에 도달하여 그 지점에서 잘렸습니다.
2650 2705
2651```text theme={null}2706```text theme={null}
2652API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.2707API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.
2653API Error: Claude's response exceeded the 64000 output token maximum for a request sent without streaming. The CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable cannot raise this limit.2708API Error: Claude's response exceeded the 64000 output token maximum for a request sent without streaming. The CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable cannot raise this limit.
2654```2709```
2655 2710
2656`a request sent without streaming`이 표시되는 형식은 스트리밍 요청이 실패하여 Claude Code가 스트리밍 없이 다시 보냈다는 의미이며, 이 경우 응답은 64,000 출력 토큰으로 제한됩니다. v2.1.299 이전에는 이렇게 다시 보낸 요청에서 응답이 잘리면 이 메시지 없이 응답이 완료된 것처럼 턴이 종료되었습니다.2711`a request sent without streaming`을 명시하는 형태는 스트리밍 요청이 실패하여 Claude Code가 스트리밍 없이 다시 보냈다는 뜻이며, 이 경우 응답은 64,000 출력 토큰으로 제한됩니다. v2.1.299 이전에는 이렇게 다시 보낸 요청에서 잘린 응답이 이 메시지 없이 응답이 완료된 것처럼 턴을 종료했습니다.
2657 2712
2658**해결 방법:**2713**해결 방법:**
2659 2714
2660* 응답이 잘리기 전에 Claude가 일부 텍스트를 작성했다면 대화형 세션에서 `continue`라고 답하여 나머지를 요청합니다. 해당 텍스트는 대화에 남아 있습니다.2715* 응답이 잘리기 전에 Claude가 일부 텍스트를 작성했다면, 대화형 세션에서 `continue`로 답하여 나머지를 요청합니다. 그 텍스트는 대화에 남아 있습니다.
2661* 메시지에 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`를 설정하라고 표시되면, 값의 상한이 어떻게 적용되는지는 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를, 설정 위치는 [환경 변수 설정](/docs/ko/env-vars#set-environment-variables)을 참조하세요2716* 메시지가 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`를 설정하라고 안내하면, 값의 상한은 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를, 설정 위치는 [환경 변수 설정](/docs/ko/env-vars#set-environment-variables)을 참조하십시오
2662* 각 응답을 한도 내로 유지하려면 응답당 파일 하나나 섹션 하나처럼 더 작은 단위로 출력을 요청합니다2717* 각 응답이 한도를 넘지 않도록 하려면, 응답당 파일 하나나 섹션 하나처럼 Claude에게 출력을 더 작은 단위로 요청하십시오
2663 2718
2664### 도구 사용 또는 thinking 블록 불일치2719### Tool use or thinking block mismatch
2665 2720
2666대화 기록이 일관성 없는 상태로 API에 도달했습니다.2721대화 기록이 일관되지 않은 상태로 API에 도달했습니다.
2667 2722
2668```text theme={null}2723```text theme={null}
2669API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.2724API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
2673API Error: 400 ... thinking blocks ... cannot be modified2728API Error: 400 ... thinking blocks ... cannot be modified
2674```2729```
2675 2730
2676모든 변형은 동일한 의미입니다: 기록의 `tool_use`, `tool_result` 및 `thinking` 블록의 순서가 더 이상 API가 예상하는 것과 일치하지 않습니다.2731모든 변형은 같은 의미입니다. 기록에 있는 `tool_use`, `tool_result`, `thinking` 블록의 순서가 더 이상 API가 기대하는 것과 일치하지 않습니다.
2677 2732
2678**할 일:**2733**해결 방법:**
2679 2734
2680* Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`로는 해결되지 않습니다.2735* Opus 4.7 또는 Opus 4.8을 사용 중이라면 먼저 `claude update`를 실행하십시오. v2.1.156 이전 버전은 일반적인 도구 사용 중에도 이 오류를 일으킬 수 있으며, `/rewind`로 해결되지 않습니다.
2681* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 되돌아가 거기서 계속합니다. 체크포인트가 생성되고 복원되는 방식은 [체크포인트](/docs/ko/checkpointing)를 참조하십시오.2736* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 되돌아간 후 그 지점부터 계속합니다. 체크포인트가 생성되고 복원되는 방식은 [체크포인트](/docs/ko/checkpointing)를 참조하십시오.
2682 2737
2683### redacted\_thinking 블록의 유효하지 않은 데이터2738### Invalid data in redacted\_thinking block
2684 2739
2685대화 기록의 이전 턴에 포함된 `redacted_thinking` 블록을 API가 허용할 수 없기 때문에 400으로 요청을 거부했습니다.2740대화 기록의 이전 턴에 포함된 `redacted_thinking` 블록을 API가 수락할 수 없어서 400으로 요청을 거부했습니다.
2686 2741
2687```text theme={null}2742```text theme={null}
2688API Error: 400 ... Invalid `data` in `redacted_thinking` block2743API Error: 400 ... Invalid `data` in `redacted_thinking` block
2689```2744```
2690 2745
2691Claude Code는 대화의 이전 사고를 요청에서 제외하고 한 번 재시도하므로 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했고 이후의 모든 턴이 동일한 오류로 실패했습니다.2746Claude Code는 대화의 이전 사고를 요청에서 제외하고 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했기 때문에 이후 모든 턴이 같은 오류로 실패했습니다.
2692 2747
2693**할 일:**2748**해결 방법:**
2694 2749
2695* v2.1.281 이하 버전을 사용 중이고 모든 턴이 이 오류로 실패하면 `claude update`를 실행하고 세션을 재개합니다.2750* v2.1.281 이하 버전에서 모든 턴이 이 오류로 실패한다면 `claude update`를 실행하고 세션을 재개합니다
2696* 오류가 지속되면 `/clear`를 실행하여 해당 블록이 포함되지 않은 대화를 시작합니다.2751* 오류가 계속되면 `/clear`를 실행하여 해당 블록이 없는 대화를 시작합니다
2697 2752
2698### Unsupported tool content removed2753### Unsupported tool content removed
2699 2754
2700Claude Code가 Anthropic API에 직접 연결된 상태에서 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 내용을 제거하고 제거된 내용이 두 thinking 블록 사이에 있던 위치에 이 줄을 남깁니다:2755Claude Code가 Anthropic API에 직접 연결하여 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 내용을 제거하고, 제거된 내용이 두 thinking 블록 사이에 있던 위치에 다음 줄을 남깁니다.
2701 2756
2702```text theme={null}2757```text theme={null}
2703[Unsupported tool content removed]2758[Unsupported tool content removed]
2704```2759```
2705 2760
2706이러한 내용은 Anthropic API가 아닌 다른 무언가가 API 형식으로 응답했을 때 세션 파일에 들어갑니다. 일반적으로 다른 제공자의 도구 호출을 변환하는, [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)로 설정된 타사 프록시입니다. Claude Code는 세션이 Anthropic API에 직접 연결된 경우에만 이를 제거하며, 세션이 프록시를 통하거나 다른 제공자에서 실행되는 경우에는 저장된 기록을 그대로 로드합니다. v2.1.246 이전에는 Claude Code가 도구 사용과 그 결과를 API로 다시 보냈고, 재개된 세션의 모든 턴이 `messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...`와 같은 400 오류로 실패했습니다.2761이러한 내용은 Anthropic API 이외의 무언가가 API 형식으로 응답했을 때 세션 파일에 들어갑니다. 일반적으로 다른 공급자의 도구 호출을 변환하는, [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)로 설정된 서드파티 프록시가 원인입니다. Claude Code는 세션이 Anthropic API에 직접 연결된 경우에만 이를 제거하며, 세션이 프록시를 거치거나 다른 공급자에서 실행되는 경우에는 저장된 기록을 그대로 로드합니다. v2.1.246 이전에는 Claude Code가 도구 사용과 그 결과를 API로 다시 보냈기 때문에, 재개된 세션의 모든 턴이 `messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...` 같은 400 오류로 실패했습니다.
2707 2762
2708**할 일:**2763**해결 방법:**
2709 2764
2710* 자리 표시자 줄이 표시될 때는 아무 조치도 필요하지 않습니다. 세션은 제거된 내용 없이 계속됩니다.2765* 자리 표시자 줄이 보이면 별도 조치가 필요하지 않습니다. 세션은 제거된 내용 없이 계속됩니다.
2711* 재개된 세션의 모든 턴이 대신 400 오류로 실패하면 `claude update`를 실행하고 세션을 다시 재개합니다. v2.1.246 이전 버전은 해당 내용을 제거하지 않습니다.2766* 대신 재개된 세션의 모든 턴이 400 오류로 실패한다면 `claude update`를 실행하고 세션을 다시 재개하십시오. v2.1.246 이전 버전은 해당 내용을 제거하지 않습니다.
2712 2767
2713### role 'system' must precede an 'assistant' message2768### role 'system' must precede an 'assistant' message
2714 2769
2715대화에서 API가 허용하지 않는 위치에 시스템 메시지가 있기 때문에 API가 400으로 요청을 거부했습니다:2770시스템 메시지가 대화에서 API가 허용하지 않는 위치에 있기 때문에 API가 400으로 요청을 거부했습니다.
2716 2771
2717```text theme={null}2772```text theme={null}
2718API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...2773API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...
2719```2774```
2720 2775
2721Claude Code는 일부 리마인더 및 첨부 텍스트를 대화 내부의 시스템 메시지로 보냅니다. API가 그중 하나의 위치를 거부하면 Claude Code는 해당 텍스트를 일반 사용자 메시지로 대신 보내 요청을 한 번 재시도합니다. `use the top-level 'system' parameter for the initial system prompt`와 같은 API의 유사한 배치 관련 문구도 동일한 복구가 적용됩니다.2776Claude Code는 일부 리마인더 및 첨부 텍스트를 대화 내의 시스템 메시지로 보냅니다. API가 그 위치를 거부하면, Claude Code는 해당 텍스트를 일반 사용자 메시지로 보내는 방식으로 요청을 한 번 재시도합니다. `use the top-level 'system' parameter for the initial system prompt` 같은 API의 유사한 위치 관련 문구도 같은 방식으로 복구됩니다.
2722 2777
2723오류가 표시된다면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 일반적으로 Claude Code와 API 사이의 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했음을 의미합니다.2778오류가 실제로 표시된다면, 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 보통 Claude Code와 API 사이의 프록시나 [LLM 게이트웨이](/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했다는 뜻입니다.
2724 2779
2725**할 일:**2780**해결 방법:**
2726 2781
2727* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)로 구성된 프록시 또는 게이트웨이 뒤에서 오류가 매 턴마다 반복되면 프록시 없이 연결하여 원인을 확인하고, 해당 프록시를 운영하는 담당자에게 오류를 보고합니다.2782* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)로 구성된 프록시나 게이트웨이 뒤에서 오류가 매 턴마다 반복된다면, 프록시 없이 연결하여 원인을 확인하고 해당 프록시 운영자에게 오류를 보고하십시오
2728* `/clear`를 실행하여 새 대화를 시작합니다. 거기서도 오류가 다시 발생하면 원인은 저장된 대화가 아닌 요청 경로에 있습니다.2783* `/clear`를 실행하여 새 대화를 시작합니다. 거기서도 오류가 다시 발생한다면, 원인은 저장된 대화가 아니라 요청 경로에 있습니다.
2729 2784
2730v2.1.280 이전에는 Claude Code가 이 문구를 인식하지 못했으므로 거부된 시스템 메시지가 Claude Code 자체가 보낸 것일 때도 오류가 표시되었고, 대화의 이후 모든 턴이 동일한 방식으로 실패했습니다.2785v2.1.280 이전에는 Claude Code가 이 문구를 인식하지 못했기 때문에, 거부된 시스템 메시지가 Claude Code 자신이 보낸 것일 때도 오류가 표시되었고 대화의 이후 모든 턴이 같은 방식으로 실패했습니다.
2731 2786
2732### search\_result 블록의 유효하지 않은 encrypted\_content2787### Invalid encrypted\_content in search\_result block
2733 2788
2734대화 기록에 API가 해독할 수 없는 호스팅 웹 검색 내용이 포함되어 있기 때문에 API가 400으로 요청을 거부했습니다. 문구는 읽을 수 없는 필드를 나타냅니다:2789대화 기록에 API가 복호화할 수 없는 호스팅 웹 검색 내용이 포함되어 있어 API가 400으로 요청을 거부했습니다. 문구에는 읽을 수 없는 필드가 명시됩니다.
2735 2790
2736```text theme={null}2791```text theme={null}
2737API Error: 400 ... Invalid `encrypted_content` in `search_result` block2792API Error: 400 ... Invalid `encrypted_content` in `search_result` block
2740API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block2795API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block
2741```2796```
2742 2797
2743API의 호스팅 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) 결과에는 API만 읽을 수 있는 암호화된 필드가 포함됩니다. `encrypted_stdout` 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직을 위해 생성된 내용처럼 해독할 수 없는 내용을 다시 보내는 요청을 거부합니다.2798API의 호스팅 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) 결과에는 API만 읽을 수 있는 암호화된 필드가 포함됩니다. `encrypted_stdout` 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직을 위해 생성된 내용처럼 복호화할 수 없는 내용을 다시 보내는 요청을 거부합니다.
2744 2799
2745Claude Code 자체의 [WebSearch 도구](/docs/ko/tools-reference#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 일반적으로 호스팅 웹 검색을 자체적으로 실행한 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 대화에 들어옵니다.2800Claude Code 자체의 [WebSearch 도구](/docs/ko/tools-reference#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 보통 호스팅 웹 검색을 직접 실행한 프록시나 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 대화에 들어옵니다.
2746 2801
2747세 가지 웹 검색 문구의 경우 Claude Code는 검색 호출, 결과 및 인용을 보내는 내용에서 제외하고 요청을 한 번 재시도하므로 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 문구에는 이러한 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했고, 이후의 모든 턴과 `/compact`가 동일한 방식으로 실패했습니다.2802세 가지 웹 검색 문구의 경우, Claude Code는 검색 호출, 결과, 인용을 전송 내용에서 제외하고 요청을 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 문구에는 이러한 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했기 때문에, 이후 모든 턴과 `/compact`가 같은 방식으로 실패했습니다.
2748 2803
2749**할 일:**2804**해결 방법:**
2750 2805
2751* v2.1.281 이하 버전을 사용 중이고 모든 턴이 웹 검색 문구 중 하나로 실패하면 `claude update`를 실행하고 세션을 재개합니다.2806* v2.1.281 이하 버전에서 모든 턴이 웹 검색 문구 중 하나로 실패한다면 `claude update`를 실행하고 세션을 재개합니다
2752* 오류가 지속되거나 메시지가 `encrypted_stdout`을 나타내면 `/rewind`를 실행하여 해당 내용을 추가한 턴 이전의 체크포인트로 되돌아가거나, `/clear`를 실행하여 해당 내용이 포함되지 않은 대화를 시작합니다.2807* 오류가 계속되거나 메시지에 `encrypted_stdout`이 명시된 경우, `/rewind`를 실행하여 해당 내용을 추가한 턴 이전의 체크포인트로 되돌아가거나, `/clear`를 실행하여 해당 내용이 없는 대화를 시작합니다
2753* 프록시 또는 게이트웨이 뒤에서 Claude Code를 실행하는 경우 해당 프록시나 게이트웨이를 운영하는 담당자에게 오류를 보고합니다.2808* 프록시나 게이트웨이 뒤에서 Claude Code를 실행한다면 해당 운영자에게 오류를 보고하십시오
2754 2809
2755### 사용 정책 거부2810### Usage Policy refusal
2756 2811
2757대화의 내용이 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 API가 응답을 거부했습니다.2812대화의 내용이 [이용 정책](https://www.anthropic.com/legal/aup) 검사를 트리거하여 API가 응답을 거절했습니다.
2758 2813
2759메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있으면 [안전 조치가 Claude의 추론에 대한 요청을 플래그했습니다](#safeguards-flagged-a-request-for-claudes-reasoning)를 참조하십시오.2814메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [세이프가드가 Claude의 추론에 대한 요청을 감지한 경우](#safeguards-flagged-a-request-for-claudes-reasoning)를 참조하십시오.
2760 2815
2761메시지에는 거부가 잘못되었다고 생각되는 경우 지원팀에 제시할 수 있는 요청 ID 및 메시지 ID가 포함됩니다.2816메시지에는 거절이 잘못되었다고 판단될 때 지원팀에 전달할 수 있는 Request ID와 Message ID가 포함됩니다.
2762 2817
2763```text theme={null}2818```text theme={null}
2764API Error: Opus 4.6 can't help with this. Start a new session to continue.2819API Error: Opus 4.6 can't help with this. Start a new session to continue.
2766Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup2821Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup
2767```2822```
2768 2823
2769메시지는 거부한 모델을 표시하며, 기록된 모델이 없으면 `Claude`를 표시합니다.2824메시지에는 거절한 모델의 이름이 표시되며, 기록된 모델이 없으면 `Claude`가 표시됩니다.
2770 2825
2771확인은 최신 프롬프트뿐 아니라 전체 대화를 평가하므로 같은 세션에서 새 메시지를 보내면 일반적으로 동일한 거부가 다시 트리거됩니다. 디스크의 트랜스크립트에 트리거한 내용이 여전히 포함되어 있으므로 종료한 후 `--continue` 또는 `--resume`으로 세션을 다시 열어도 마찬가지입니다. [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 및 [Microsoft Foundry](/docs/ko/microsoft-foundry)에서는 이 메시지가 모델의 안전 조치가 사이버 보안 주제로 플래그한 요청도 다룹니다. [안전 조치가 사이버 보안 주제를 플래그했습니다](#safety-measures-flagged-a-cybersecurity-topic)를 참조하십시오.2826검사는 최신 프롬프트뿐만 아니라 대화 전체를 평가하므로, 같은 세션에서 새 메시지를 보내면 보통 같은 거절이 다시 트리거됩니다. 디스크의 트랜스크립트에 여전히 트리거한 내용이 남아 있으므로, 세션을 종료한 후 `--continue` 또는 `--resume`으로 다시 열어도 마찬가지입니다. [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry)에서는 이 메시지가 모델의 안전 조치가 사이버 보안 주제로 감지한 요청에도 표시됩니다. [안전 조치가 사이버 보안 주제를 감지한 경우](#safety-measures-flagged-a-cybersecurity-topic)를 참조하십시오.
2772 2827
2773v2.1.219 이전에는 메시지가 `Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.`였습니다.2828v2.1.219 이전에는 메시지가 `Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.`였습니다.
2774 2829
2775**할 일:**2830**해결 방법:**
2776 2831
2777* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 다르게 표현하거나 다른 접근 방식을 취합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.2832* Esc를 두 번 누르거나 `/rewind`를 실행하여 거절을 트리거한 턴 이전의 체크포인트로 되돌아간 후, 표현을 바꾸거나 다른 접근 방식을 사용합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.
2778* 어떤 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 계속 사용할 수 있습니다.2833* 어떤 턴이 원인인지 파악할 수 없다면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 계속 사용할 수 있습니다.
2779* 되감기를 사용할 수 없는 [비대화형 모드](/docs/ko/headless)(`-p`)에서는 `--continue` 없이 새 세션에서 다르게 표현한 프롬프트로 재시도합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 경우에 따라 거부가 해결될 수도 있습니다.2834* 되감기를 사용할 수 없는 [비대화형 모드](/docs/ko/headless)(`-p`)에서는 `--continue` 없이 새 세션에서 표현을 바꾼 프롬프트로 재시도하십시오. 정책 검사는 모델마다 다르므로, 경우에 따라 `--model`로 다른 모델로 전환하면 거절이 해결될 수도 있습니다.
2780 2835
2781### 안전 조치가 사이버 보안 주제를 플래그했습니다2836### 안전 조치가 사이버 보안 주제로 플래그 지정함
2782 2837
2783모델의 안전 조치가 대화의 내용을 사이버 보안 주제로 플래그했습니다. 메시지는 요청을 플래그한 모델을 표시합니다:2838모델의 안전 조치가 대화 내용을 사이버 보안 주제로 플래그 지정했습니다. 메시지에는 요청을 플래그 지정한 모델의 이름이 표시됩니다.
2784 2839
2785```text theme={null}2840```text theme={null}
2786API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude2841API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude
2787```2842```
2788 2843
2789메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있으면 [안전 조치가 Claude의 추론에 대한 요청을 플래그했습니다](#safeguards-flagged-a-request-for-claudes-reasoning)를 참조하십시오.2844메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [안전 장치가 Claude의 추론을 요청하는 것으로 플래그 지정함](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하세요.
2790 2845
2791이 메시지는 정당한 사이버 보안 작업에 대한 액세스를 부여하는 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)으로 연결됩니다. [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)이 적용되는 모델은 이 링크 없이 다른 메시지를 출력하며, Opus 5.5 및 Sonnet 5.5에서는 해당 메시지가 `<model>'s safeguards flagged this session`으로 시작합니다. 해당 섹션에서는 Claude Code가 대신 모델을 전환하는 경우도 다룹니다.2846이 메시지는 정당한 사이버 보안 작업에 대한 액세스 권한을 부여하는 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)으로 연결됩니다. [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)이 적용되는 모델은 이 링크 없이 다른 메시지를 출력하며, Opus 5.5와 Sonnet 5.5에서는 `<model>'s safeguards flagged this session`으로 시작합니다. 해당 섹션에서는 Claude Code가 대신 모델을 전환하는 경우도 다룹니다.
2792 2847
2793[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 및 [Microsoft Foundry](/docs/ko/microsoft-foundry)에서는 사이버 보안 플래그가 대신 [사용 정책 거부](#usage-policy-refusal) 메시지를 생성합니다.2848[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud's Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry)에서는 사이버 보안 플래그가 지정되면 대신 [사용 정책 거부](#usage-policy-refusal) 메시지가 표시됩니다.
2794 2849
2795**할 일:**2850**해결 방법:**
2796 2851
2797* 작업에 이 내용이 필요하면 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다.2852* 작업에 이 콘텐츠가 필요한 경우 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다
2798* 요청이 사이버 보안 주제와 관련이 없었다면 `/feedback`을 실행하여 오탐을 보고합니다.2853* 요청이 사이버 보안 주제와 관련이 없었다면 `/feedback`을 실행하여 오탐을 보고합니다
2799* 같은 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 이전의 체크포인트로 되돌아간 다음 다른 접근 방식을 취합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.2854* 같은 세션에서 작업을 계속하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 유발한 턴 이전의 체크포인트로 되돌아간 다음 다른 방식으로 접근합니다. [체크포인트](/docs/ko/checkpointing)를 참조하세요.
2800 2855
2801표시된 메시지의 문구가 대신 다음 중 하나와 같다면, 이전 Claude Code 버전에서 발생한 동일한 플래그입니다.2856표시되는 메시지의 문구가 다음 중 하나와 같다면 이전 Claude Code 버전에서 표시되는 동일한 플래그입니다.
2802 2857
2803* v2.1.219부터 v2.1.296까지는 메시지의 마지막 문장 앞에 `Apply to the Cyber Verification Program to reduce these interruptions.`가 포함될 수도 있었습니다2858* v2.1.219부터 v2.1.296까지는 메시지의 마지막 문장 앞에 `Apply to the Cyber Verification Program to reduce these interruptions.`가 포함될 수도 있었습니다
2804* v2.1.203부터 v2.1.218까지는 메시지가 `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:`였으며 뒤에 동일한 도움말 센터 링크가 이어졌습니다. 대화형 세션에서는 `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`이 이어졌습니다2859* v2.1.203부터 v2.1.218까지는 메시지가 `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:`였으며 그 뒤에 동일한 고객 센터 링크가 이어졌습니다. 대화형 세션에서는 `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`가 이어졌습니다
2805* v2.1.203 이전에는 메시지가 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:`였으며 뒤에 예외 신청 양식 링크가 이어졌습니다2860* v2.1.203 이전에는 메시지가 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:`였으며 그 뒤에 예외 신청 양식 링크가 이어졌습니다
2806 2861
2807### 안전 조치가 Claude의 추론에 대한 요청을 플래그했습니다2862### 안전 장치가 Claude의 추론을 요청하는 것으로 플래그 지정함
2808 2863
2809안전 조치가 요청을 모델의 내부 추론을 응답에서 재현하도록 요구하는 것으로 플래그했기 때문에 API가 요청을 거부했습니다. API는 이 [거부 범주](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)를 `reasoning_extraction`이라고 부르며, 거부 메시지에는 다음 줄이 포함됩니다:2864안전 장치가 요청을 모델의 내부 추론을 응답에 재현하도록 요구하는 것으로 플래그 지정하여 API가 요청을 거부했습니다. API는 이 [거부 범주](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)를 `reasoning_extraction`이라고 부르며, 거부 메시지에는 다음 줄이 포함됩니다.
2810 2865
2811```text theme={null}2866```text theme={null}
2812Details: `[reasoning_extraction]`2867Details: `[reasoning_extraction]`
2814 2869
2815v2.1.234 이전에는 거부 메시지에 `Details` 줄이 포함되지 않았습니다.2870v2.1.234 이전에는 거부 메시지에 `Details` 줄이 포함되지 않았습니다.
2816 2871
2817**할 일:**2872**해결 방법:**
2818 2873
2819* Claude에게 사고나 추론을 그대로 또는 고정된 형식으로 작성하도록 요구하는 지시를 제거하거나 다르게 표현합니다. 예를 들어 `<thinking>` 섹션, 스크래치패드 섹션 또는 JSON 출력의 `reasoning` 필드 등이 있습니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일 또는 MCP 도구 설명처럼 Claude Code가 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다.2874* Claude에게 사고나 추론을 그대로 또는 고정된 형식으로 작성하도록 요청하는 지시(예: `<thinking>` 섹션, 스크래치패드 섹션, JSON 출력의 `reasoning` 필드)를 제거하거나 다르게 표현합니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일, MCP 도구 설명처럼 Claude Code가 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다.
2820* 사용자 지정 항목이 원인인지 확인하려면 터미널에서 [`claude --safe-mode`](/docs/ko/cli-reference#cli-flags)를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음 동일한 프롬프트를 보냅니다.2875* 사용자 지정 항목이 원인인지 확인하려면 터미널에서 [`claude --safe-mode`](/docs/ko/cli-reference#cli-flags)를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음 같은 프롬프트를 보냅니다
2821* 사용자 지정 항목을 변경한 후에는 새 세션을 시작합니다.2876* 사용자 지정 항목을 변경한 후에는 새 세션을 시작합니다
2822* 이미 보낸 프롬프트를 다르게 표현하려면 [되감기 및 요약](/docs/ko/checkpointing#rewind-and-summarize)을 참조하십시오.2877* 이미 보낸 프롬프트를 다르게 표현하려면 [되감기 및 요약](/docs/ko/checkpointing#rewind-and-summarize)을 참조하세요
2823* Claude에게 답변을 설명하도록 요청하는 것은 여전히 가능합니다. 짧은 설명, 결과의 근거 또는 수행한 작업의 요약을 요청합니다. Claude의 사고 요약을 읽으려면 [`showThinkingSummaries`](/docs/ko/settings-reference#showthinkingsummaries)를 참조하십시오.2878* Claude에게 답변에 대한 설명을 요청하는 것은 여전히 가능합니다. 간단한 설명, 결과의 근거, 수행한 작업의 요약을 요청하세요. Claude의 사고 요약을 읽으려면 [`showThinkingSummaries`](/docs/ko/settings-reference#showthinkingsummaries)를 참조하세요.
2824* 더 많은 예시와 다르게 표현한 요청도 거부될 때의 조치는 [추론을 thinking 블록에 유지하기](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks)를 참조하십시오.2879* 더 많은 예시와 다르게 표현한 요청이 여전히 거부될 때의 해결 방법은 [추론을 thinking 블록에 유지하기](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks)를 참조하세요
2825 2880
2826### Output blocked by content filtering policy2881### Output blocked by content filtering policy
2827 2882
2828API의 출력 콘텐츠 필터가 Claude가 생성하던 응답을 중단했습니다. 메시지 텍스트는 API에서 제공됩니다:2883API의 출력 콘텐츠 필터가 Claude가 생성 중이던 응답을 중단했습니다. 메시지 텍스트는 API에서 제공됩니다.
2829 2884
2830```text theme={null}2885```text theme={null}
2831API Error: Output blocked by content filtering policy2886API Error: Output blocked by content filtering policy
2832```2887```
2833 2888
2834**할 일:**2889**해결 방법:**
2835 2890
2836* 마지막 메시지를 다르게 표현하거나 다른 접근 방식을 취합니다.2891* 마지막 메시지를 다르게 표현하거나 다른 방식으로 접근합니다
2837* 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.2892* 차단을 유발한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행합니다. [체크포인트](/docs/ko/checkpointing)를 참조하세요
2838 2893
2839## 명령줄 오류2894## 명령줄 오류
2840 2895
3362관련 메시지는 명령이 실행되기도 전에 발생합니다:3417관련 메시지는 명령이 실행되기도 전에 발생합니다:
3363 3418
3364* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사에서 허용되지 않았습니다. [주입된 명령에 대한 권한 검사](/docs/ko/skills#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지, 그리고 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다3419* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사에서 허용되지 않았습니다. [주입된 명령에 대한 권한 검사](/docs/ko/skills#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지, 그리고 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다
3365* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 머신에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령의 실행 방식](/docs/ko/skills#how-injected-commands-run)을 참조하십시오3420* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 시스템에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](/docs/ko/skills#how-injected-commands-run)을 참조하세요
3366* `No shell command in <name> was run`: 파일의 `!` 명령 중 하나에 탭이나 줄 바꿈 이외의 원시 제어 문자가 포함되어 있어 어떤 명령도 실행되지 않습니다. [해당 문자를 찾아 제거하는 방법](#no-shell-command-was-run)을 참조하십시오3421* `No shell command in <name> was run`: 파일의 `!` 명령 중 하나에 탭이나 줄 바꿈 이외의 원시 제어 문자가 포함되어 있어 어떤 명령도 실행되지 않습니다. [해당 문자를 찾아 제거하는 방법](#no-shell-command-was-run)을 참조하십시오
3367 3422
3368**해결 방법:**3423**해결 방법:**
3464Claude Code는 이 세션의 메뉴에 나열된 명령 이름이나 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 대개 다음 중 하나입니다:3519Claude Code는 이 세션의 메뉴에 나열된 명령 이름이나 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 대개 다음 중 하나입니다:
3465 3520
3466* `/help`를 `/hepl`로 입력한 것 같은 오타. [명령 메뉴가 입력 내용과 일치시키는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)에서 제출 전에 가까운 항목을 선택하는 방법을 다룹니다3521* `/help`를 `/hepl`로 입력한 것 같은 오타. [명령 메뉴가 입력 내용과 일치시키는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)에서 제출 전에 가까운 항목을 선택하는 방법을 다룹니다
3467* 명령은 존재하지만 플랫폼, 플랜 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 경우. [`/web-setup`](/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 및 [`/schedule`](/docs/ko/routines#schedule-returns-unknown-command)의 문제 해결 항목에서 두 가지 일반적인 사례를 설명합니다. 일부 명령은 조직 정책에 의해 비활성화된 경우 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)처럼 자체 메시지로 응답합니다3522* 명령은 존재하지만 플랫폼, 플랜, 인증 방법 등의 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없습니다. [`/web-setup`](/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command), [`/schedule`](/docs/ko/routines#schedule-returns-unknown-command), [`/auto-mode-setup`](/docs/ko/auto-mode-config#auto-mode-setup-returns-unknown-command) 항목을 참조하세요. 일부 명령은 조직 정책에 의해 비활성화되었을 때 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)처럼 자체 메시지로 응답합니다
3468* 이 세션에 설치되거나 연결되지 않은 [플러그인](/docs/ko/plugins/overview) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령3523* 이 세션에 설치되거나 연결되지 않은 [플러그인](/docs/ko/plugins/overview) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령
3469 3524
3470Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 밖의 모든 세션에서는 프롬프트를 일반 메시지로 Claude에 보내며, 명령이 실행되지 않았다는 메모와 세션에서 Claude가 실행할 수 있는 명령 목록을 함께 보냅니다. 이러한 세션은 다음과 같습니다:3525Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 밖의 모든 세션에서는 프롬프트를 일반 메시지로 Claude에 보내며, 명령이 실행되지 않았다는 메모와 세션에서 Claude가 실행할 수 있는 명령 목록을 함께 보냅니다. 이러한 세션은 다음과 같습니다:
3513 3568
3514* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다3569* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다
3515* **클론에 이미 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다3570* **클론에 이미 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다
3516* **클론에 없던 기본 브랜치를 전달한 경우**: Claude Code가 비교하기 전에 origin에서 해당 브랜치를 fetch했습니다. 안내는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``입니다. Claude Code가 클론이 shallow인지 판단할 수 없으면 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 fetch한 모든 기본 브랜치에 대해 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다.3571* **클론에 없던 기본 브랜치를 전달한 경우**: Claude Code는 비교 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``이며, Claude Code가 클론이 얕은 클론인지 판단할 수 없으면 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 `git fetch --unshallow origin`을 제안했는데, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다.
3517 3572
3518**해결 방법:**3573**해결 방법:**
3519 3574
3856* 세션을 직접 열고 그곳에서 `/recap`을 실행합니다: 해당 터미널, [Desktop 앱](/docs/ko/desktop) 또는 [모바일 앱](/docs/ko/mobile), [claude.ai/code](https://claude.ai/code), 또는 [Remote Control](/docs/ko/remote-control)을 통해 실행할 수 있습니다3911* 세션을 직접 열고 그곳에서 `/recap`을 실행합니다: 해당 터미널, [Desktop 앱](/docs/ko/desktop) 또는 [모바일 앱](/docs/ko/mobile), [claude.ai/code](https://claude.ai/code), 또는 [Remote Control](/docs/ko/remote-control)을 통해 실행할 수 있습니다
3857* 클라우드 예약 작업이나 다른 프로그램이 보낸 경우 해당 프롬프트에서 `/recap`을 제거합니다3912* 클라우드 예약 작업이나 다른 프로그램이 보낸 경우 해당 프롬프트에서 `/recap`을 제거합니다
3858 3913
3914### /feedback is disabled by your organization's policy
3915
3916이 메시지는 조직의 정책이 Claude Code에서의 제품 피드백을 허용하지 않아 `/feedback`, `/bug`, `/share`가 피드백 대화 상자를 열지 않는다는 의미입니다. 메시지에는 Claude Code 프롬프트에 입력한 명령이 표시됩니다.
3917
3918```text wrap theme={null}
3919/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.
3920```
3921
3922메시지가 첫 문장만으로 표시될 수도 있습니다.
3923
3924**해결 방법:**
3925
3926* 버그를 보고하려면 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 이슈를 엽니다. 이곳의 이슈는 누구나 읽을 수 있으므로 코드, 트랜스크립트 및 기타 기밀 정보는 포함하지 않습니다.
3927
3928v2.1.302 이전에는 전체 메시지가 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`였습니다.
3929
3859## 플러그인 오류3930## 플러그인 오류
3860 3931
3861이러한 오류는 [플러그인](/docs/ko/plugins/overview) 및 [마켓플레이스](/docs/ko/plugins/overview) 구성에서 발생합니다. 이 페이지의 메시지 중 하나를 생성하지 않는 플러그인 문제(예: 로드되지 않는 마켓플레이스 URL 또는 설치되지만 나타나지 않는 플러그인)의 경우 [플러그인 문제 해결](/docs/ko/plugins/troubleshooting)을 참조하십시오.3932이러한 오류는 [플러그인](/docs/ko/plugins/overview) 및 [마켓플레이스](/docs/ko/plugins/overview) 구성에서 발생합니다. 이 페이지의 메시지 중 하나를 생성하지 않는 플러그인 문제(예: 로드되지 않는 마켓플레이스 URL 또는 설치되지만 나타나지 않는 플러그인)의 경우 [플러그인 문제 해결](/docs/ko/plugins/troubleshooting)을 참조하십시오.
4001 4072
4002### Path escapes plugin directory4073### Path escapes plugin directory
4003 4074
4004플러그인 구성 요소 경로는 플러그인의 `plugin.json` 또는 [마켓플레이스 항목](/docs/ko/plugins/marketplace-reference#plugin-entries)에서 선언되며 플러그인의 자체 디렉터리 외부로 확인됩니다. Claude Code는 해당 경로를 삭제하고 플러그인의 나머지 부분을 로드합니다. 메시지의 구성 요소 이름(예: `commands` 또는 `hooks`)은 경로를 선언한 필드의 이름을 지정합니다.4075플러그인의 구성 요소 경로 중 하나가 플러그인 디렉터리 외부로 이어지거나 플러그인 내부에 있는지 확인할 수 없으므로 Claude Code는 해당 경로를 삭제하고 플러그인의 나머지 부분을 로드합니다. 플러그인이 `plugin.json` 또는 [마켓플레이스 항목](/docs/ko/plugins/marketplace-reference#plugin-entries)에서 선언한 경로의 경우 메시지의 구성 요소 이름(예: `commands` 또는 `hooks`)은 경로를 선언한 필드의 이름을 지정합니다.
4005 4076
4006```text theme={null}4077```text theme={null}
4007commands path escapes plugin directory: ./../shared.md4078commands path escapes plugin directory: ./../shared.md
4015commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory4086commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory
4016```4087```
4017 4088
4089마켓플레이스 플러그인 자체 파일 중 하나(예: `hooks/hooks.json`)의 전체 경로를 제공하는 메시지는 Claude Code가 해당 파일을 건너뛰었음을 의미합니다. 이는 Claude Code가 파일이 플러그인 내부에 있는지, 또는 [로컬 마켓플레이스](/docs/ko/plugins/loading#in-place-and-copied-plugins)의 플러그인의 경우 해당 마켓플레이스 내부에 있는지 확인할 수 없을 때 발생합니다. 메시지는 이러한 각 파일을 다음 구성 요소 이름으로 보고합니다:
4090
4091* `hooks/hooks.json`: `hooks`
4092* `monitors/monitors.json`: `monitors`
4093* `settings.json`: `settings`
4094* 플러그인 루트의 `SKILL.md`: `skills`
4095
4096예를 들어 이 메시지는 플러그인과 해당 로컬 마켓플레이스 모두의 외부로 확인되는 `hooks/hooks.json`에 대한 것입니다:
4097
4098```text theme={null}
4099hooks path escapes plugin directory: /home/user/my-marketplace/my-plugin/hooks/hooks.json — it resolves to /home/user/dotfiles/hooks.json, outside the plugin directory and its marketplace directory
4100```
4101
4018macOS 및 Linux에서 Claude Code는 경로가 플러그인 내부에 머물러 있을 때도 경로의 어디든지 백슬래시를 포함하는 구성 요소 경로를 거부합니다. 구성 요소 경로가 Windows 스타일 구분 기호를 사용하는 플러그인은 Windows에서 로드되고 다른 플랫폼에서 이 거부를 트리거합니다:4102macOS 및 Linux에서 Claude Code는 경로가 플러그인 내부에 머물러 있을 때도 경로의 어디든지 백슬래시를 포함하는 구성 요소 경로를 거부합니다. 구성 요소 경로가 Windows 스타일 구분 기호를 사용하는 플러그인은 Windows에서 로드되고 다른 플랫폼에서 이 거부를 트리거합니다:
4019 4103
4020```text theme={null}4104```text theme={null}
4023 4107
4024v2.1.251 이전에는 Claude Code가 마켓플레이스 항목에서 선언된 `commands` 경로를 플러그인 디렉터리 외부를 가리킬 때도 로드했습니다.4108v2.1.251 이전에는 Claude Code가 마켓플레이스 항목에서 선언된 `commands` 경로를 플러그인 디렉터리 외부를 가리킬 때도 로드했습니다.
4025 4109
4026v2.1.257 이전에는 확인이 경로의 철자만 보았으며 심볼릭 링크가 이어지는 위치는 보지 않았습니다.4110v2.1.257 이전에는 플러그인이 선언한 경로에 대한 확인이 경로의 철자만 보았으며 심볼릭 링크가 이어지는 위치는 보지 않았습니다.
4027 4111
4028**수행할 작업:**4112**수행할 작업:**
4029 4113
4030* 참조된 파일을 플러그인 디렉터리 내부로 이동하고 `./` 상대 경로로 경로를 가리키십시오.4114* 플러그인을 설치했지만 유지 관리하지 않는 경우 메시지를 작성자에게 보고하십시오.
4031* 경로가 플러그인 외부의 파일에 대한 심볼릭 링크인 경우 심볼릭 링크를 파일의 복사본으로 바꾸십시오.4115* 플러그인이 선언한 경로의 경우 참조된 파일을 플러그인 디렉터리 내부로 이동하고 `./` 상대 경로로 경로를 가리키십시오.
4032* 메시지가 경로에 백슬래시가 포함되어 있다고 말하면 경로를 정방향 슬래시로 작성하십시오. 예를 들어 `./commands/deploy.md`4116* 경로 또는 플러그인 내부에서 그 위에 있는 폴더가 플러그인 외부로 이어지는 심볼릭 링크인 경우 심볼릭 링크를 그것이 가리키는 대상의 복사본으로 바꾸십시오.
4117* 메시지가 플러그인이 선언한 경로에 백슬래시가 포함되어 있다고 말하면 경로를 정방향 슬래시로 작성하십시오. 예를 들어 `./commands/deploy.md`
4118* 메시지가 `EACCES`로 끝나면 경로가 지정하는 파일 또는 폴더로 이어지는 모든 디렉터리에 대한 실행 권한을 복원하십시오. 경로 위의 디렉터리를 확인한 다음 도달하는 각 심볼릭 링크를 따라가 그것이 가리키는 위치로 이어지는 디렉터리를 확인하십시오. 다른 오류 코드의 경우 [확인할 수 없는 경로의 원인 및 단계](#path-could-not-be-checked)에서 찾아보십시오.
4033* 동일한 마켓플레이스의 다른 플러그인과 파일을 공유하려면 플러그인 디렉터리 내의 심볼릭 링크로 연결하고 [심볼릭 링크 규칙](/docs/ko/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)을 따르십시오.4119* 동일한 마켓플레이스의 다른 플러그인과 파일을 공유하려면 플러그인 디렉터리 내의 심볼릭 링크로 연결하고 [심볼릭 링크 규칙](/docs/ko/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)을 따르십시오.
4034 4120
4121### Plugin not loaded: its manifest was not read
4122
4123Claude Code는 `.claude-plugin/plugin.json`에 있는 마켓플레이스 플러그인의 [매니페스트](/docs/ko/plugins/manifest-reference)가 플러그인 내부에 있는지 확인할 수 없었으므로 해당 플러그인에서 아무것도 로드하지 않습니다. [로컬 마켓플레이스](/docs/ko/plugins/loading#in-place-and-copied-plugins)의 플러그인의 경우 Claude Code는 매니페스트가 해당 마켓플레이스 내부에 있는지도 확인할 수 없었습니다. 메시지는 `/plugin` **오류** 탭에 나타나며, 끝부분의 이유는 Claude Code가 발견한 내용을 알려 줍니다.
4124
4125예를 들어 이 메시지는 `.claude-plugin` 폴더가 마켓플레이스 외부로 이어지는 심볼릭 링크인 로컬 마켓플레이스의 플러그인에 대한 것입니다:
4126
4127```text theme={null}
4128Plugin not loaded: its manifest /home/user/my-marketplace/my-plugin/.claude-plugin/plugin.json was not read, because it resolves to /home/user/dotfiles/my-plugin/.claude-plugin/plugin.json, outside the plugin directory and its marketplace directory
4129```
4130
4131**수행할 작업:**
4132
4133* 이유가 `EACCES`로 끝나면 매니페스트로 이어지는 모든 디렉터리에 대한 실행 권한을 복원하십시오. 매니페스트 위의 디렉터리를 확인한 다음 도달하는 각 심볼릭 링크를 따라가 그것이 가리키는 위치로 이어지는 디렉터리를 확인하십시오. 다른 오류 코드의 경우 [확인할 수 없는 경로의 원인 및 단계](#path-could-not-be-checked)에서 찾아보십시오.
4134* 플러그인을 유지 관리하고 있으며 이유에 매니페스트가 확인되는 위치가 표시되어 있다면 `.claude-plugin` 폴더 또는 `plugin.json` 자체가 그 위치로 이어지는 심볼릭 링크입니다. 해당 링크를 그것이 가리키는 대상의 복사본으로 바꾸십시오.
4135* 플러그인을 설치했지만 유지 관리하지 않는 경우 메시지를 작성자에게 보고하십시오.
4136
4035### Path could not be checked4137### Path could not be checked
4036 4138
4037Claude Code는 플러그인 경로가 존재하는지 운영 체제에 물었고 "찾을 수 없음" 이외의 오류를 받았으므로 경로가 이름을 지정하는 것을 로드하지 않습니다. 플러그인의 얼마나 많은 부분이 로드되는지는 어느 경로가 실패했는지에 따라 다릅니다:4139Claude Code는 플러그인 경로가 존재하는지 운영 체제에 물었고 "찾을 수 없음" 이외의 오류를 받았으므로 경로가 이름을 지정하는 것을 로드하지 않습니다. 플러그인의 얼마나 많은 부분이 로드되는지는 어느 경로가 실패했는지에 따라 다릅니다:
4226 4328
4227v2.1.281 이전에는 Read, Write, Edit 또는 NotebookEdit 경로의 null 바이트가 `Path contains null bytes`라는 이름의 오류로 전체 턴을 종료했으며 도구는 실행되지 않았습니다.4329v2.1.281 이전에는 Read, Write, Edit 또는 NotebookEdit 경로의 null 바이트가 `Path contains null bytes`라는 이름의 오류로 전체 턴을 종료했으며 도구는 실행되지 않았습니다.
4228 4330
4331### File is too large to read as an image
4332
4333Claude가 [Read 도구](/docs/ko/tools-reference#read-tool-behavior)로 파일을 이미지로 읽으려고 했지만, 파일이 Read가 이미지 파일에서 로드하는 최대 크기인 128MB보다 큽니다. 아무것도 읽히지 않았으며 Claude는 이 오류를 도구 결과로 받습니다:
4334
4335```text wrap theme={null}
4336File is too large to read as an image (the limit is 128MB): <path>. If it is an image, resize it or export a smaller copy, then read that.
4337```
4338
4339경로가 일반 파일이 아닌 파이프 또는 장치이면 Read는 128MB를 초과하는 데이터가 도착하는 즉시 중지하고 대신 이 오류를 반환합니다:
4340
4341```text wrap theme={null}
4342Cannot read this as an image: <path> is a pipe or a device, not a regular file, and it sent more than 128MB without ending.
4343```
4344
4345**할 일:**
4346
4347* Claude가 `File is too large` 메시지에 따라 이미지 크기를 조정하거나 더 작은 사본을 읽었다면 아무것도 하지 않습니다.
4348* Claude가 오류에서 멈췄다면 예를 들어 더 낮은 해상도로 128MB 미만의 사본을 직접 내보내고 Claude가 해당 파일을 사용하도록 지정합니다.
4349* 경로가 파이프 또는 장치였다면 대신 일반 이미지 파일을 Claude에 지정합니다.
4350
4229### subagent\_type is required4351### subagent\_type is required
4230 4352
4231```text theme={null}4353```text theme={null}
4316* [디버그 로그](/docs/ko/debug-your-config)가 지정하는 폴더에서 `claude`를 실행하고 신뢰 대화를 수락합니다. 정의는 Claude Code가 팀원을 다시 복구할 때 다시 적용됩니다. 리드 세션을 다시 시작할 필요가 없습니다.4438* [디버그 로그](/docs/ko/debug-your-config)가 지정하는 폴더에서 `claude`를 실행하고 신뢰 대화를 수락합니다. 정의는 Claude Code가 팀원을 다시 복구할 때 다시 적용됩니다. 리드 세션을 다시 시작할 필요가 없습니다.
4317* 또는 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 `true`로 설정합니다. 디버그 로그가 인쇄하는 정확한 `projects["<path>"]` 키를 사용합니다.4439* 또는 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 `true`로 설정합니다. 디버그 로그가 인쇄하는 정확한 `projects["<path>"]` 키를 사용합니다.
4318 4440
4441### Only a teammate can approve a shutdown request
4442
4443Claude Code는 [에이전트 팀](/docs/ko/agent-teams) 종료 승인을 보낸 세션이 팀원으로 실행 중이 아니므로 해당 승인을 거부했습니다. 아무것도 전송되지 않았고 아무것도 종료되지 않았습니다. 거부는 전송 세션의 도구 결과에 나타납니다:
4444
4445```text wrap theme={null}
4446Only a teammate can approve a shutdown request, and this session is not running as one. Nothing was sent. To shut down a teammate, send that teammate a shutdown_request message. The teammate is the one that approves it.
4447```
4448
4449**할 일:**
4450
4451* 리드 세션에서 거부가 나타났다면 먼저 팀원이 그 사이에 종료되었는지 확인합니다. 거부는 대신 `shutdown_request`를 보내라는 지시와 함께 Claude에 반환되며 턴이 계속됩니다. 대화형 리드 세션에서는 팀원이 종료 요청을 승인하면 `<name> has shut down.`이 표시됩니다.
4452* 팀원이 아직 실행 중이면 리드의 프롬프트에서 팀원을 종료하도록 요청합니다. 예를 들어 `Ask the researcher teammate to shut down`입니다. [팀원 종료](/docs/ko/agent-teams#shut-down-teammates)를 참조합니다.
4453* `claude --resume`으로 직접 재개한 이전 팀원이 이 거부를 받았다면 아무것도 전송되지 않았습니다. 해당 세션을 종료하려면 해당 세션의 프롬프트에서 `/exit`를 실행합니다.
4454
4319### Message too large for cross-session delivery4455### Message too large for cross-session delivery
4320 4456
4321Claude의 [교차 세션 메시지](/docs/ko/cross-session-messaging)가 이 머신의 다른 세션으로 너무 길어서 보낼 수 없었습니다. Claude Code가 거부했고 수신 세션이 아무것도 받지 못했습니다. 거부는 터미널의 배너가 아닌 전송 세션의 도구 결과에 나타납니다. 두 크기와 메시지를 맞추는 방법을 지정합니다:4457Claude의 [교차 세션 메시지](/docs/ko/cross-session-messaging)가 이 머신의 다른 세션으로 너무 길어서 보낼 수 없었습니다. Claude Code가 거부했고 수신 세션이 아무것도 받지 못했습니다. 거부는 터미널의 배너가 아닌 전송 세션의 도구 결과에 나타납니다. 두 크기와 메시지를 맞추는 방법을 지정합니다:
4449 4585
4450### 디스크 할당량 또는 임시 파일 시스템이 가득 참4586### 디스크 할당량 또는 임시 파일 시스템이 가득 참
4451 4587
4452Claude Code는 각 Bash 및 PowerShell 명령의 출력을 임시 디렉터리 아래의 파일에 저장합니다. 명령이 0이 아닌 코드로 종료되고 출력이 전혀 없으면 Claude Code는 해당 파일을 보유한 파일 시스템이 공간 또는 inode가 부족한지, 또는 디스크 할당량이 사용되었는지 확인합니다. 그렇다면 진단이 빈 출력 대신 명령의 결과에 나타납니다:4588Claude Code는 각 Bash 및 PowerShell 명령의 출력을 임시 디렉터리 아래의 파일에 저장합니다. 명령 결과에 나타나는 이러한 메시지는 해당 디렉터리를 보유한 파일 시스템 또는 그 파일 시스템에 대한 디스크 할당량이 가득 찼음을 의미합니다.
4589
4590파일 시스템 또는 그에 대한 할당량이 가득 차서 Claude Code가 해당 파일을 만들 수 없으면 명령이 시작되지 않으며 결과는 다음과 같습니다:
4591
4592```text wrap theme={null}
4593The command was not started: this computer's disk is full (ENOSPC), so the file that captures command output could not be created. Nothing ran. If this is the user's own computer, tell them before deleting anything to make room.
4594```
4595
4596명령이 0이 아닌 코드로 종료되고 출력이 전혀 없으면 Claude Code는 출력 파일을 보유한 파일 시스템을 확인합니다. 해당 파일 시스템에 공간 또는 inode가 부족하거나 디스크 할당량이 모두 사용되었으면 진단이 명령 결과의 빈 출력을 대체합니다:
4453 4597
4454```text wrap theme={null}4598```text wrap theme={null}
4455Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.4599Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.
4460* `Your disk quota is full ... (EDQUOT)`: 해당 파일 시스템에 대한 사용자 본인의 할당량이 사용되었습니다. 할당량은 파일 시스템이 여전히 여유 공간을 표시하는 동안 가득 찰 수 있습니다.4604* `Your disk quota is full ... (EDQUOT)`: 해당 파일 시스템에 대한 사용자 본인의 할당량이 사용되었습니다. 할당량은 파일 시스템이 여전히 여유 공간을 표시하는 동안 가득 찰 수 있습니다.
4461* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`: 파일 시스템 또는 할당량에 공간이 남지 않았습니다.4605* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`: 파일 시스템 또는 할당량에 공간이 남지 않았습니다.
4462* `Command output was lost: the temp filesystem at ... is full` 또는 `... is out of inodes`: 파일 시스템에 거의 여유 공간이 남지 않았거나 inode가 부족합니다.4606* `Command output was lost: the temp filesystem at ... is full` 또는 `... is out of inodes`: 파일 시스템에 거의 여유 공간이 남지 않았거나 inode가 부족합니다.
4607* `The command was not started: this computer's disk is full (ENOSPC)` 또는 `... (EDQUOT)`: 파일 시스템에 출력 파일을 위한 공간이 남지 않았거나, `EDQUOT`의 경우 해당 파일 시스템에 대한 사용자 본인의 할당량이 사용되었습니다.
4463 4608
4464**할 일:**4609**할 일:**
4465 4610
4466* Claude Code의 임시 디렉터리를 보유한 파일 시스템에서 더 이상 필요하지 않은 파일을 삭제합니다. `EDQUOT`의 경우 사용자 본인의 할당량에 포함되는 파일을 삭제합니다. `out of inodes`의 경우 각 파일이 크기에 관계없이 하나의 inode를 차지하므로 몇 개의 큰 파일이 아닌 많은 파일을 삭제합니다.4611* Claude Code의 임시 디렉터리를 보유한 파일 시스템에서 더 이상 필요하지 않은 파일을 삭제합니다. 메시지에 해당 디렉터리가 표시되지 않으면 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars) 참조에서 기본 위치를 확인합니다. `EDQUOT`의 경우 사용자 본인의 할당량에 포함되는 파일을 삭제합니다. `out of inodes`의 경우 각 파일이 크기에 관계없이 하나의 inode를 차지하므로 몇 개의 큰 파일이 아닌 많은 파일을 삭제합니다.
4467* 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 여유 공간이 있는 파일 시스템의 디렉터리로 설정하여 Claude Code를 다시 시작합니다.4612* 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 여유 공간이 있는 파일 시스템의 디렉터리로 설정하여 Claude Code를 다시 시작합니다.
4468* 그런 다음 Claude에 명령을 다시 실행하도록 합니다. 인쇄한 출력은 손실되었으며 잘리지 않았습니다.4613* 그런 다음 Claude에 명령을 다시 실행하도록 합니다.
4614
4615v2.1.305 이전에는 디스크가 가득 차서 Claude Code가 시작할 수 없었던 명령이 운영 체제의 오류 텍스트만 반환했습니다. 해당 텍스트는 예를 들어 `ENOSPC: no space left on device, open <path>.output`였습니다.
4469 4616
4470### File is not valid UTF-84617### File is not valid UTF-8
4471 4618
4524* Windows에서 Claude가 공유에서 직접 게시할 수 있게 하려면 공유를 드라이브 문자에 매핑하고 Claude Code를 시작할 때 해당 드라이브를 전달합니다. 예를 들어 PowerShell에서 `net use Z: \\server\share`를 실행한 다음 `claude --add-dir Z:\`를 실행합니다. 그러면 Claude가 해당 드라이브의 파일을 게시할 수 있습니다. 세션 도중 `/add-dir`로 드라이브를 추가하는 것으로는 충분하지 않습니다.4671* Windows에서 Claude가 공유에서 직접 게시할 수 있게 하려면 공유를 드라이브 문자에 매핑하고 Claude Code를 시작할 때 해당 드라이브를 전달합니다. 예를 들어 PowerShell에서 `net use Z: \\server\share`를 실행한 다음 `claude --add-dir Z:\`를 실행합니다. 그러면 Claude가 해당 드라이브의 파일을 게시할 수 있습니다. 세션 도중 `/add-dir`로 드라이브를 추가하는 것으로는 충분하지 않습니다.
4525* macOS 또는 Linux에서는 `/mnt` 또는 `/Volumes` 아래와 같은 디렉터리에 공유를 마운트하고, 자동 마운트 경로 대신 해당 경로에서 게시합니다.4672* macOS 또는 Linux에서는 `/mnt` 또는 `/Volumes` 아래와 같은 디렉터리에 공유를 마운트하고, 자동 마운트 경로 대신 해당 경로에서 게시합니다.
4526 4673
4674### Not published: Claude sent the same content again after a newer version of the artifact turned it away
4675
4676Artifact 호출 아래에 표시되는 이 빨간색 줄은 Claude Code가 반복된 게시를 중지했음을 의미합니다: [아티팩트](/docs/ko/artifacts)는 업데이트되지 않았으며, Claude가 게시에 사용하는 파일에도 아무것도 쓰이지 않았습니다. Claude가 게시하지 않고 멈추지 않는 한 아무것도 할 필요가 없습니다.
4677
4678세션 앞부분에서 Claude Code는 아티팩트에 더 새로운 버전이 있어서 게시를 거절했습니다. 예를 들어 [편집자](/docs/ko/artifacts#let-someone-edit-with-you)나 사용자의 다른 세션이 게시한 버전입니다. 줄의 끝부분은 Claude가 다음에 해야 할 일을 알려줍니다:
4679
4680```text wrap theme={null}
4681Not published: Claude sent the same content again after a newer version of the artifact turned it away. Claude needs to work from that newer version first.
4682Not published: Claude sent the same content again after a newer version of the artifact turned it away. The artifact hasn't changed since, so publishing it once more should go through.
4683Not published: Claude sent its changes again over the same file after a newer version of the artifact turned them away. Claude needs to work from that newer version first.
4684Not published: Claude sent its changes again over the same file after a newer version of the artifact turned them away. The artifact hasn't changed since, so publishing once more should go through.
4685```
4686
4687**할 일:**
4688
4689* **`Claude needs to work from that newer version first`로 끝나는 경우**: Claude가 거기서 멈췄다면 아티팩트의 현재 버전을 가져와 변경 사항을 병합한 다음 다시 게시하도록 요청합니다.
4690* **`should go through`로 끝나는 경우**: Claude가 거기서 멈췄다면 다시 게시하도록 요청합니다.
4691
4527### Cowork 세션에서 연결된 폴더 외부의 로컬 파일 읽기4692### Cowork 세션에서 연결된 폴더 외부의 로컬 파일 읽기
4528 4693
4529Claude Desktop 앱에서 머신에서 실행 중인 [Cowork](https://claude.com/docs/cowork/overview) 세션에서 Claude가 [아티팩트](/docs/ko/artifacts)에 대한 로컬 파일의 이름을 지정했습니다. Claude Code가 파일이 세션의 연결된 폴더 내의 일반 파일인지 확인할 수 없습니다: 경로가 해당 폴더 외부에 있거나, 심볼릭 링크를 통과하거나, 나타나는 것과 다른 파일의 이름을 지정할 수 있는 방식으로 철자가 지정되었습니다. 그러한 파일을 읽으려면 승인이 필요하며, 승인 카드를 표시할 수 없는 세션(예: 모든 승인을 건너뛰도록 설정된 세션)에서 Claude Code는 읽기를 거부합니다.4694Claude Desktop 앱에서 머신에서 실행 중인 [Cowork](https://claude.com/docs/cowork/overview) 세션에서 Claude가 [아티팩트](/docs/ko/artifacts)에 대한 로컬 파일의 이름을 지정했습니다. Claude Code가 파일이 세션의 연결된 폴더 내의 일반 파일인지 확인할 수 없습니다: 경로가 해당 폴더 외부에 있거나, 심볼릭 링크를 통과하거나, 나타나는 것과 다른 파일의 이름을 지정할 수 있는 방식으로 철자가 지정되었습니다. 그러한 파일을 읽으려면 승인이 필요하며, 승인 카드를 표시할 수 없는 세션(예: 모든 승인을 건너뛰도록 설정된 세션)에서 Claude Code는 읽기를 거부합니다.
4816* 루프를 계속하려면 [세션에 답장](/docs/ko/agent-view#peek-and-reply)하여 `keep the loop running`과 같이 그렇게 말합니다. Claude는 답장과 함께 알림을 읽고 다음 깨우기를 예약할 수 있습니다.4981* 루프를 계속하려면 [세션에 답장](/docs/ko/agent-view#peek-and-reply)하여 `keep the loop running`과 같이 그렇게 말합니다. Claude는 답장과 함께 알림을 읽고 다음 깨우기를 예약할 수 있습니다.
4817* 루프를 더 이상 사용하지 않으려면 아무것도 하지 않습니다. 루프는 이미 중지되었습니다.4982* 루프를 더 이상 사용하지 않으려면 아무것도 하지 않습니다. 루프는 이미 중지되었습니다.
4818 4983
4984### No LLM gateway: a gateway set in your shell isn't passed to a session opened from another folder
4985
4986이 메시지를 표시하는 [백그라운드 세션](/docs/ko/agent-view)은 [LLM 게이트웨이](/docs/ko/llm-gateway)를 사용하지 않습니다. 게이트웨이 주소를 받지 못했으므로 요청이 실패합니다. 메시지는 Claude의 응답 대신 대화에 나타나며, 세션의 ID와 폴더가 채워져 있습니다:
4987
4988```text wrap theme={null}
4989No LLM gateway: a gateway set in your shell isn't passed to a session opened from another folder. To fix, run `claude respawn abc12345` from ~/project in another terminal where your gateway is set, or set ANTHROPIC_BASE_URL and its API key or token in a settings file's env block.
4990```
4991
4992세션에 연결되어 있는 동안 프롬프트 아래의 알림에는 짧은 형식인 `No LLM gateway: opened from another folder · respawn from ~/project`가 표시됩니다.
4993
4994`ANTHROPIC_BASE_URL`이 게이트웨이로 설정된 상태에서 메시지가 명시하는 폴더가 아닌 다른 폴더에서 세션을 디스패치하거나, 깨우거나, 다시 시작했습니다. 셸에서 내보낸 게이트웨이가 백그라운드 세션에 전달되는 경우는 [LLM 게이트웨이](/docs/ko/agent-view#llm-gateway)를 참조하십시오.
4995
4996**할 일:**
4997
4998* **설정에서 게이트웨이를 지정하는 프로젝트에서 에이전트 뷰를 사용한 경우**: `ANTHROPIC_BASE_URL`과 해당 API 키 또는 토큰을 [설정 파일의 `env` 블록](/docs/ko/llm-gateway-connect#set-in-a-settings-file)에 넣습니다. `~/.claude/settings.json` 또는 세션 자체 프로젝트의 `.claude/settings.local.json`을 사용하십시오. 둘 다 다시 시작된 세션이 읽는 파일입니다. 그런 다음 아무 폴더에서나 셸에서 `claude respawn <id>`를 실행합니다.
4999* **터미널에서 게이트웨이를 내보낸 경우**: 게이트웨이 변수를 내보낸 터미널에서 메시지가 명시하는 폴더로 `cd`한 다음 메시지의 `claude respawn <id>` 명령을 실행합니다. 세션은 저장된 대화에서 다시 시작됩니다.
5000 * 게이트웨이는 [슈퍼바이저](/docs/ko/agent-view#the-supervisor-process) 자체가 같은 게이트웨이를 내보낸 셸에서 시작된 경우에만 세션에 전달됩니다. 그렇지 않은 경우 [`Could not resolve authentication method`로 디스패치가 실패하는 경우](/docs/ko/agent-view#dispatch-fails-with-could-not-resolve-authentication-method)에 설명된 대로 해당 터미널에서 슈퍼바이저를 다시 시작한 다음 respawn 명령을 다시 실행합니다.
5001
5002v2.1.302 이전에는 이 상황의 백그라운드 세션이 폴더를 명시하지 않고 대신 [`Not logged in · Please run /login`](#not-logged-in)과 같은 로그인 오류를 표시했습니다.
5003
4819### CLAUDE\_CODE\_PROCESS\_WRAPPER 런처 오류5004### CLAUDE\_CODE\_PROCESS\_WRAPPER 런처 오류
4820 5005
4821[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/ko/corporate-launcher)가 설정되었으며 해당 값을 사용할 수 없으므로 Claude Code는 런처 없이 실행하는 대신 영향을 받는 프로세스를 시작하기를 거부합니다. 구성 문제는 변수 이름으로 시작하고 이유를 명시하는 메시지로 보고됩니다. 예를 들어:5006[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/ko/corporate-launcher)가 설정되었으며 해당 값을 사용할 수 없으므로 Claude Code는 런처 없이 실행하는 대신 영향을 받는 프로세스를 시작하기를 거부합니다. 구성 문제는 변수 이름으로 시작하고 이유를 명시하는 메시지로 보고됩니다. 예를 들어:
5094 5279
5095## 구성 경고5280## 구성 경고
5096 5281
5097Claude Code는 이러한 메시지 대부분을 대화가 아닌 stderr에 기록하며, 대부분 시작 시에 기록합니다. 메시지가 디버그 로그나 대화 보기의 시작 알림 같은 다른 곳에 나타나거나, 요청 시점의 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)처럼 다른 시점에 나타나는 경우 해당 항목에 그렇게 명시되어 있습니다.5282대화형 세션에서 Claude Code가 시작 시 표시한 경고를 찾으려면 먼저 시작 배너 아래를 확인한 다음 디버그 로그를 확인하세요:
5283
5284* **시작 배너 아래의 행**: [`⚠ Deny rule Bsh matches no tool · check for typos`](#matches-no-tool)처럼 [권한 규칙](/docs/ko/permissions)에 관한 일부 경고
5285* **디버그 로그**: Claude Code는 디버그 모드에서만 이 로그를 유지합니다. 로그의 경고를 읽으려면 셸에서 `claude --debug-file <path>`로 Claude Code를 시작한 다음 해당 경로의 파일을 여세요.
5286
5287텍스트 출력을 사용하는 [비대화형 모드](/docs/ko/headless)에서는 [백그라운드 세션](/docs/ko/agent-view)이 아닌 경우 stderr에서 시작 경고를 확인하세요.
5288
5289v2.1.305 이전에는 대화형 세션에서도 stderr를 확인하세요. 현재 배너 아래에 행으로 표시되는 권한 규칙 경고도 마찬가지입니다.
5098 5290
5099### Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨5291### Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨
5100 5292
5214 5406
5215### 작업 디렉터리가 네트워크 경로임5407### 작업 디렉터리가 네트워크 경로임
5216 5408
5217Claude Code는 네트워크 경로를 작업 디렉터리로 추가하지 않습니다. 네트워크 경로를 조회하면 경로에 지정된 호스트에 연결할 수 있으며, Windows에서는 이 연결로 호스트에 자격 증명이 전송될 수 있으므로 Claude Code는 조회하지 않고 경로를 거부합니다. 이러한 경로로 `/add-dir`을 실행하거나 시작 시 경고로 이 메시지가 표시됩니다. 시작 시 나타나면 Claude Code는 해당 디렉터리 없이 시작합니다.5409Claude Code는 네트워크 경로를 작업 디렉터리로 추가하지 않습니다. 네트워크 경로를 조회하면 경로에 지정된 호스트에 연결할 수 있으며, Windows에서는 이 연결로 호스트에 자격 증명이 전송될 수 있습니다. 따라서 Claude Code는 조회하지 않고 경로를 거부합니다.
5410
5411네트워크 경로로 `/add-dir`을 실행하면 다음 메시지가 표시됩니다:
5218 5412
5219```text theme={null}5413```text theme={null}
5220\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).5414\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).
5221```5415```
5222 5416
5417대신 시작 시 `--add-dir` 또는 `permissions.additionalDirectories`로 네트워크 경로를 전달하면 Claude Code는 해당 디렉터리 없이 시작합니다. 대화형 세션에서는 메시지가 다른 [시작 경고](#configuration-warnings)와 함께 디버그 로그에 기록되므로 시작 시 메시지가 표시되지 않습니다.
5418
5223Claude Code가 이 방식으로 거부하는 경로는 다음과 같습니다:5419Claude Code가 이 방식으로 거부하는 경로는 다음과 같습니다:
5224 5420
5225* `\\server\share` 같은 UNC 공유5421* `\\server\share` 같은 UNC 공유
5465 5661
5466v2.1.260 이전에는 Claude Code가 괄호가 짝이 맞지 않는 규칙을 `Mismatched parentheses`로 보고했습니다.5662v2.1.260 이전에는 Claude Code가 괄호가 짝이 맞지 않는 규칙을 `Mismatched parentheses`로 보고했습니다.
5467 5663
5468### 파일 권한 검사와 일치하지 않음5664### Matches no tool · check for typos
5469 5665
5470Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리형 설정](/docs/ko/managed-settings), 또는 `--allowedTools`, `--disallowedTools`, `--settings` 플래그 값에서 경로가 포함된 `Write`, `NotebookEdit`, `MultiEdit`, 또는 `Glob` [권한 규칙](/docs/ko/permissions#read-and-edit)을 찾았습니다. Claude Code는 파일 권한을 `Edit` 및 `Read` 규칙에 대해서만 검사하므로, 다른 파일 도구를 명시하는 경로 규칙은 전혀 참조하지 않습니다. 규칙은 유지되며 다른 것은 변경되지 않습니다. 경고는 규칙, 괄호 안의 소스, 그리고 대신 작성할 규칙을 명시합니다:5666시작 배너 아래의 이 행은 Claude Code가 도구 이름을 인식하지 못하는 거부 또는 확인 [권한 규칙](/docs/ko/permissions)을 명시하며, 해당 규칙은 의도한 도구에 적용되지 않습니다. `Bsh`로 작성한 거부 규칙은 Bash에 적용되지 않으며, 도구의 표준 이름 대신 트랜스크립트에 표시되는 레이블을 사용한 규칙도 마찬가지입니다. 행은 작성한 그대로의 규칙을 반복해서 보여 줍니다:
5471 5667
5472```text theme={null}5668```text theme={null}
5473Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).5669⚠ Deny rule Bsh matches no tool · check for typos
5670```
5671
5672텍스트 출력을 사용하는 [비대화형 모드](/docs/ko/headless)에서는 Claude Code가 대신 더 긴 형태의 경고를 stderr에 출력합니다:
5673
5674```text theme={null}
5675Permission deny rule "Bsh" matches no known tool — check for typos.
5474```5676```
5475 5677
5476**할 일:**5678**할 일:**
5477 5679
5680* 규칙의 도구 이름을 수정하세요. 예를 들어 `Bsh` 대신 `Bash`를 사용합니다. 표준 이름은 [도구 참조](/docs/ko/tools-reference)에서 확인하세요.
5681* 규칙이 정의된 위치를 찾으려면 세션에서 `/permissions`를 실행하고 규칙을 선택하세요. 세부 정보에 `From project local settings`, 또는 `--disallowedTools` 값의 경우 `From CLI argument`처럼 규칙의 출처가 표시됩니다.
5682* 세부 정보가 `From enterprise managed settings`로 표시되면 사용자가 직접 해당 규칙을 변경할 수 없으므로 [관리형 설정](/docs/ko/managed-settings)을 유지 관리하는 담당자에게 해당 행을 전달하세요.
5683
5684[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다.
5685
5686v2.1.305 이전에는 대화형 세션이 행을 표시하는 대신 시작 시 더 긴 형태의 경고를 stderr에 출력했습니다.
5687
5688### 파일 권한 검사와 일치하지 않음
5689
5690Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리형 설정](/docs/ko/managed-settings), 또는 `--allowedTools`, `--disallowedTools`, `--settings` 플래그 값에서 경로가 포함된 `Write`, `NotebookEdit`, `MultiEdit`, 또는 `Glob` [권한 규칙](/docs/ko/permissions#read-and-edit)을 찾았습니다. Claude Code는 파일 권한을 `Edit` 및 `Read` 규칙에 대해서만 검사하므로, 다른 파일 도구를 명시하는 경로 규칙은 전혀 참조하지 않습니다. 규칙은 유지되며 다른 것은 변경되지 않습니다.
5691
5692* **대화형 세션**: 전체 경고는 [디버그 로그](#configuration-warnings)에 기록되며, 이 형태의 거부 또는 확인 규칙은 시작 배너 아래에 다음 행으로도 표시됩니다:
5693
5694 ```text theme={null}
5695 ⚠ Deny rule Write(docs/**) never matches · use Edit(docs/**)
5696 ```
5697
5698 이 형태의 허용 규칙은 행이 표시되지 않습니다. 규칙이 정의된 위치를 찾으려면 세션에서 `/permissions`를 실행하고 규칙을 선택하세요.
5699* **텍스트 출력을 사용하는 [비대화형 모드](/docs/ko/headless)**: stderr의 전체 경고는 규칙, 괄호 안의 소스, 그리고 대신 작성할 규칙을 명시합니다:
5700
5701 ```text theme={null}
5702 Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).
5703 ```
5704* **[백그라운드 세션](/docs/ko/agent-view), 또는 `--output-format json`이나 `stream-json`**: 기계가 읽는 출력을 깨끗하게 유지하기 위해 전체 경고는 stderr 대신 디버그 로그에 기록됩니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다.
5705
5706**할 일:**
5707
5478* `Write(path)`, `NotebookEdit(path)`, 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구에 적용됩니다.5708* `Write(path)`, `NotebookEdit(path)`, 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구에 적용됩니다.
5479* Claude Code가 경고 없이 `Glob` 규칙을 수락하는 `--allowedTools`를 제외하고, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.5709* Claude Code가 경고 없이 `Glob` 규칙을 수락하는 `--allowedTools`를 제외하고, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.
5480* 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는 `--allowed-tools` 및 `--disallowed-tools`의 경우 플래그 자체입니다. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5710* 전체 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는 `--allowed-tools` 및 `--disallowed-tools`의 경우 플래그 자체입니다. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.
5481* `Write` 또는 `Glob` 같은 도구 이름만 있는 규칙은 그대로 두세요. Claude Code는 이러한 규칙을 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치시키며 경고하지 않습니다.5711* `Write` 또는 `Glob` 같은 도구 이름만 있는 규칙은 그대로 두세요. Claude Code는 이러한 규칙을 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치시키며 경고하지 않습니다.
5482* 소스가 `managed policy settings`로 표시되면 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 경고를 전달하세요.5712* 관리형 설정의 규칙인 경우 전체 경고의 괄호 안에 `managed policy settings`가 표시되고 `/permissions`의 규칙 세부 정보에 `From enterprise managed settings`가 표시됩니다. 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 해당 경고를 전달하세요.
5483 5713
5484[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5714v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다. v2.1.305 이전에는 대화형 세션이 전체 경고를 stderr에 출력했습니다.
5485 5715
5486### 명령의 나머지 부분 앞에 와일드카드가 있음5716### 명령의 나머지 부분 앞에 와일드카드가 있음
5487 5717
5488Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리형 설정](/docs/ko/managed-settings), 또는 `--allowedTools`나 `--settings` 플래그 값에서 `Bash(git * main)` 또는 `Bash(git -C * status *)`처럼 `*`가 어떤 명령인지를 결정하는 뒤쪽 단어보다 앞에 오는 `Bash` 허용 규칙을 찾았습니다. `*`는 해당 위치에 삽입된 옵션을 포함한 모든 텍스트와 일치합니다. 예를 들어 `Bash(git * main)`은 `git -c core.fsmonitor=<script> diff main`도 승인하는데, 여기서 `-c`는 git이 명령에 지정된 프로그램을 실행하게 만듭니다. [와일드카드 패턴](/docs/ko/permissions#wildcard-patterns)에서 일치 규칙을 확인할 수 있습니다.5718Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리형 설정](/docs/ko/managed-settings), 또는 `--allowedTools`나 `--settings` 플래그 값에서 `Bash(git * main)` 또는 `Bash(git -C * status *)`처럼 `*`가 어떤 명령인지를 결정하는 뒤쪽 단어보다 앞에 오는 `Bash` 허용 규칙을 찾았습니다. `*`는 해당 위치에 삽입된 옵션을 포함한 모든 텍스트와 일치합니다. 예를 들어 `Bash(git * main)`은 `git -c core.fsmonitor=<script> diff main`도 승인하는데, 여기서 `-c`는 git이 명령에 지정된 프로그램을 실행하게 만듭니다. [와일드카드 패턴](/docs/ko/permissions#wildcard-patterns)에서 일치 규칙을 확인할 수 있습니다.
5489 5719
5490이 경고는 의도보다 넓은 와일드카드를 가진 규칙의 범위를 좁힐 수 있도록 하기 위한 것입니다. Claude Code는 규칙을 유지하며 일치 방식도 변경하지 않습니다. 경고는 규칙과 괄호 안의 소스를 명시합니다:5720이 경고는 의도보다 넓은 와일드카드를 가진 규칙의 범위를 좁힐 수 있도록 하기 위한 것입니다. Claude Code는 규칙을 유지하며 일치 방식도 변경하지 않습니다. 텍스트 출력을 사용하는 [비대화형 모드](/docs/ko/headless)에서는 stderr의 경고가 규칙과 괄호 안의 소스를 명시합니다:
5491 5721
5492```text theme={null}5722```text theme={null}
5493Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).5723Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).
5494```5724```
5495 5725
5726대화형 세션에서는 전체 경고가 [디버그 로그](#configuration-warnings)에 기록되며, 규칙은 시작 배너 아래에 다음 행으로 표시됩니다:
5727
5728```text theme={null}
5729⚠ Allow rule Bash(git -C * status *) allows any option at its * · use an exact value
5730```
5731
5732규칙이 정의된 위치를 찾으려면 세션에서 `/permissions`를 실행하고 규칙을 선택하세요.
5733
5496**할 일:**5734**할 일:**
5497 5735
5498* 하위 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.5736* 하위 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.
5499* 모든 `*`를 하위 명령 뒤로 옮기세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 하위 명령마다 규칙을 하나씩 작성하세요.5737* 모든 `*`를 하위 명령 뒤로 옮기세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 하위 명령마다 규칙을 하나씩 작성하세요.
5500* 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 플래그 자체입니다. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5738* 전체 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 플래그 자체입니다. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.
5501* 소스가 `managed policy settings`로 표시되면 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 경고를 전달하세요.5739* 관리형 설정의 규칙인 경우 전체 경고의 괄호 안에 `managed policy settings`가 표시되고 `/permissions`의 규칙 세부 정보에 `From enterprise managed settings`가 표시됩니다. 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 해당 경고를 전달하세요.
5502 5740
5503[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5741[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.
5504 5742
5743v2.1.305 이전에는 대화형 세션이 행을 표시하는 대신 전체 경고를 stderr에 출력했습니다.
5744
5505### Bash를 거부하면 PowerShell 도구도 꺼짐5745### Bash를 거부하면 PowerShell 도구도 꺼짐
5506 5746
5507예를 들어 `--disallowedTools Bash`를 사용하거나 설정 파일 중 하나에 `Bash` 또는 `Bash(*)`만 있는 [거부 규칙](/docs/ko/permissions#match-all-uses-of-a-tool)을 사용하여 Bash 도구 전체를 제거했습니다. Git Bash가 설치된 Windows에서는 [Bash를 거부하면 PowerShell 도구도 꺼지므로](/docs/ko/tools-reference#bash-deny-rules-also-turn-off-the-powershell-tool) 세션이 셸 도구 없이 시작됩니다. Claude Code는 시작 시 다음 경고를 출력합니다:5747예를 들어 `--disallowedTools Bash`를 사용하거나 설정 파일 중 하나에 `Bash` 또는 `Bash(*)`만 있는 [거부 규칙](/docs/ko/permissions#match-all-uses-of-a-tool)을 사용하여 Bash 도구 전체를 제거했습니다. Git Bash가 설치된 Windows에서는 [Bash를 거부하면 PowerShell 도구도 꺼지므로](/docs/ko/tools-reference#bash-deny-rules-also-turn-off-the-powershell-tool) 세션이 셸 도구 없이 시작됩니다.
5748
5749텍스트 출력을 사용하는 [비대화형 모드](/docs/ko/headless)에서는 Claude Code가 시작 시 stderr에 이 경고를 출력하며, 대화형 세션에서는 [디버그 로그](#configuration-warnings)에만 기록합니다:
5508 5750
5509```text theme={null}5751```text theme={null}
5510Denying Bash also turns off the PowerShell tool, so Claude has neither. To use PowerShell, set CLAUDE_CODE_USE_POWERSHELL_TOOL=1.5752Denying Bash also turns off the PowerShell tool, so Claude has neither. To use PowerShell, set CLAUDE_CODE_USE_POWERSHELL_TOOL=1.
5517 5759
5518[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.287 이전에는 Claude Code가 경고를 출력하지 않고 같은 방식으로 PowerShell 도구를 껐습니다.5760[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다. v2.1.287 이전에는 Claude Code가 경고를 출력하지 않고 같은 방식으로 PowerShell 도구를 껐습니다.
5519 5761
5762v2.1.305 이전에는 대화형 세션도 시작 시 경고를 stderr에 출력했습니다.
5763
5520### crossSessionInbound는 accept, hold, refuse 중 하나여야 함5764### crossSessionInbound는 accept, hold, refuse 중 하나여야 함
5521 5765
5522설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 오타 `"reject"`처럼 Claude Code가 인식하지 못하는 값으로 설정했습니다. 경고의 두 번째 문장은 어느 파일에 값이 있는지에 따라 다르며, 사용자, 프로젝트, 로컬 또는 `--settings` 파일에서는 다음과 같습니다:5766설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 오타 `"reject"`처럼 Claude Code가 인식하지 못하는 값으로 설정했습니다. 경고의 두 번째 문장은 어느 파일에 값이 있는지에 따라 다르며, 사용자, 프로젝트, 로컬 또는 `--settings` 파일에서는 다음과 같습니다:
5566* 메시지가 이 버전이 인식하지 못하는 모델 ID를 명시하면 `claude update`를 실행하세요. 해당 ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.5810* 메시지가 이 버전이 인식하지 못하는 모델 ID를 명시하면 `claude update`를 실행하세요. 해당 ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.
5567* 세션이 대신 모델의 전체 윈도우를 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 이 경고는 200K 제한이 적용되지 않는다는 사실만 알립니다.5811* 세션이 대신 모델의 전체 윈도우를 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 이 경고는 200K 제한이 적용되지 않는다는 사실만 알립니다.
5568 5812
5569[백그라운드 세션](/docs/ko/agent-view)에서 또는 `--output-format json`이나 `stream-json`을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다.5813텍스트 출력을 사용하는 [비대화형 모드](/docs/ko/headless)에서는 이 경고가 stderr에 나타납니다. 대화형 세션, [백그라운드 세션](/docs/ko/agent-view), 또는 `--output-format json`이나 `stream-json`을 사용하는 경우에는 대신 디버그 로그에 기록됩니다. `--debug`로 실행하면 `~/.claude/debug/<session-id>.txt`에서 확인할 수 있습니다.
5814
5815v2.1.305 이전에는 대화형 세션이 시작 시 경고를 stderr에 출력했습니다.
5570 5816
5571### 요청에서 인식되지 않은 모델 ID5817### 요청에서 인식되지 않은 모델 ID
5572 5818
5678오류가 여기에 나열되지 않았거나 제안된 해결 방법이 도움이 되지 않는 경우:5924오류가 여기에 나열되지 않았거나 제안된 해결 방법이 도움이 되지 않는 경우:
5679 5925
5680* Claude Code 내에서 `/feedback`을 실행하여 기록 및 설명을 Anthropic에 전송하십시오. 이 명령은 미리 작성된 GitHub 이슈를 열 수 있는 옵션도 제공합니다. Anthropic에 전송하려면 [인증](/docs/ko/authentication)이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 기타 타사 제공자에서 또는 Anthropic 자격 증명이 구성되지 않은 경우, `/feedback`은 대신 Anthropic 계정 담당자에게 보낼 수 있는 로컬 아카이브를 저장합니다.5926* Claude Code 내에서 `/feedback`을 실행하여 기록 및 설명을 Anthropic에 전송하십시오. 이 명령은 미리 작성된 GitHub 이슈를 열 수 있는 옵션도 제공합니다. Anthropic에 전송하려면 [인증](/docs/ko/authentication)이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 기타 타사 제공자에서 또는 Anthropic 자격 증명이 구성되지 않은 경우, `/feedback`은 대신 Anthropic 계정 담당자에게 보낼 수 있는 로컬 아카이브를 저장합니다.
5927* `/feedback`이 조직의 정책에 의해 비활성화되었다고 응답하는 경우 [해당 메시지 항목](#feedback-is-disabled-by-your-organizations-policy)을 참조하십시오
5681* 셸에서 `claude doctor`를 실행하여 설치의 읽기 전용 진단을 수행하거나, Claude Code 내에서 `/doctor` 점검을 실행하여 설정 문제를 찾고 수정하십시오5928* 셸에서 `claude doctor`를 실행하여 설치의 읽기 전용 진단을 수행하거나, Claude Code 내에서 `/doctor` 점검을 실행하여 설정 문제를 찾고 수정하십시오
5682* [status.claude.com](https://status.claude.com)에서 활성 인시던트를 확인하십시오5929* [status.claude.com](https://status.claude.com)에서 활성 인시던트를 확인하십시오
5683* GitHub의 [기존 이슈](https://github.com/anthropics/claude-code/issues)를 검색하십시오5930* GitHub의 [기존 이슈](https://github.com/anthropics/claude-code/issues)를 검색하십시오
