24| :- | :- |24| :- | :- |
25| `API Error: 500 Internal server error` | [서버 오류](#api-error-500-internal-server-error) |25| `API Error: 500 Internal server error` | [서버 오류](#api-error-500-internal-server-error) |
26| `API Error: Repeated 529 Overloaded errors` | [서버 오류](#api-error-repeated-529-overloaded-errors) |26| `API Error: Repeated 529 Overloaded errors` | [서버 오류](#api-error-repeated-529-overloaded-errors) |
27| `Opus is experiencing high load` / `Fable is experiencing high load` | [서버 오류](#api-error-repeated-529-overloaded-errors) |
27| `Request timed out` | [서버 오류](#request-timed-out), 또는 메시지에 인터넷 연결이 언급된 경우 [네트워크](#unable-to-connect-to-api) |28| `Request timed out` | [서버 오류](#request-timed-out), 또는 메시지에 인터넷 연결이 언급된 경우 [네트워크](#unable-to-connect-to-api) |
28| `API Error: No response from API` | [서버 오류](#no-response-from-api) |29| `API Error: No response from API` | [서버 오류](#no-response-from-api) |
29| `Server error mid-response. The response above may be incomplete.` | [서버 오류](#the-response-above-may-be-incomplete) |30| `Server error mid-response. The response above may be incomplete.` | [서버 오류](#the-response-above-may-be-incomplete) |
30| `Connection lost mid-response` / `Your computer went to sleep mid-response` / `The response stopped arriving` | [서버 오류](#the-response-above-may-be-incomplete) |31| `Connection lost mid-response` / `Your computer went to sleep mid-response` / `The response stopped arriving` | [서버 오류](#the-response-above-may-be-incomplete) |
31| `Connection closed mid-response` / `Response stalled mid-stream` | [서버 오류](#the-response-above-may-be-incomplete) |32| `Connection closed mid-response` / `Response stalled mid-stream` | [서버 오류](#the-response-above-may-be-incomplete) |
33| `Part of the response never arrived` / `The response stream was malformed` | [서버 오류](#the-response-above-may-be-incomplete) |
34| `API Error: Content block not found` / `API Error: Content block already closed` / `API Error: Stream event unreadable` | [서버 오류](#the-response-above-may-be-incomplete) |
32| `Connection lost before a response was produced` / `Your computer went to sleep before a response was produced` / `The response stalled before a response was produced` | [자동 재시도](#automatic-retries) |35| `Connection lost before a response was produced` / `Your computer went to sleep before a response was produced` / `The response stalled before a response was produced` | [자동 재시도](#automatic-retries) |
33| `Connection closed while thinking` / `Response stalled while thinking` | [자동 재시도](#automatic-retries) |36| `Connection closed while thinking` / `Response stalled while thinking` | [자동 재시도](#automatic-retries) |
34| `Connection lost while your computer was asleep` | [자동 재시도](#automatic-retries) |37| `Connection lost while your computer was asleep` | [자동 재시도](#automatic-retries) |
49| `Could not update your spend limit` | [사용 제한](#could-not-update-your-spend-limit) |52| `Could not update your spend limit` | [사용 제한](#could-not-update-your-spend-limit) |
50| `spend limit reached` / `spend limit unavailable` | [사용 제한](#spend-limit-reached) |53| `spend limit reached` / `spend limit unavailable` | [사용 제한](#spend-limit-reached) |
51| `Not logged in · Please run /login` | [인증](#not-logged-in) |54| `Not logged in · Please run /login` | [인증](#not-logged-in) |
55| `Couldn't save your login` | [인증](#couldnt-save-your-login) |
56| `Authentication required · Sign in again to continue` | [인증](#not-logged-in) |
52| `Could not resolve authentication method` | [인증](#could-not-resolve-authentication-method) |57| `Could not resolve authentication method` | [인증](#could-not-resolve-authentication-method) |
53| `Invalid API key` | [인증](#invalid-api-key) |58| `Invalid API key` | [인증](#invalid-api-key) |
54| `Your apiKeyHelper script is failing` | [인증](#your-apikeyhelper-script-is-failing) |59| `Your apiKeyHelper script is failing` | [인증](#your-apikeyhelper-script-is-failing) |
69| `signed-in claude.ai account or organization changed on this machine` | [인증](#remote-control-stopped-because-the-signed-in-account-changed) |74| `signed-in claude.ai account or organization changed on this machine` | [인증](#remote-control-stopped-because-the-signed-in-account-changed) |
70| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [인증](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |75| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [인증](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |
71| `Remote Control stopped — the app running this session is signed out of Claude` | [인증](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |76| `Remote Control stopped — the app running this session is signed out of Claude` | [인증](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |
77| `Couldn't verify your organization's policy for remote control` | [Remote Control 문제 해결](/docs/ko/remote-control#couldnt-verify-your-organizations-policy-for-remote-control) |
72| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |78| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |
73| `API Error: 401 Invalid authentication credentials` | [인증](#api-error-401-invalid-authentication-credentials) |79| `API Error: 401 Invalid authentication credentials` | [인증](#api-error-401-invalid-authentication-credentials) |
74| `Login expired · Please run /login` | [인증](#login-expired) |80| `Login expired · Please run /login` | [인증](#login-expired) |
77| `Not signed in to the Cloud gateway — run /login.` | [인증](#administrator-policy-requires-a-cloud-gateway-sign-in) |83| `Not signed in to the Cloud gateway — run /login.` | [인증](#administrator-policy-requires-a-cloud-gateway-sign-in) |
78| `Administrator policy requires a Cloud gateway sign-in on this machine` | [인증](#administrator-policy-requires-a-cloud-gateway-sign-in) |84| `Administrator policy requires a Cloud gateway sign-in on this machine` | [인증](#administrator-policy-requires-a-cloud-gateway-sign-in) |
79| `Failed to authenticate: OAuth session expired and could not be refreshed` | [인증](#login-expired) |85| `Failed to authenticate: OAuth session expired and could not be refreshed` | [인증](#login-expired) |
86| `Could not refresh your login because another Claude Code process is refreshing it` | [인증](#could-not-refresh-your-login) |
87| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [인증](#could-not-refresh-your-login) |
80| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |88| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |
81| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |89| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [인증](#your-account-is-on-hold) |
82| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [인증](#anthropic-profile-login-expired) |90| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [인증](#anthropic-profile-login-expired) |
120| `Couldn't reconnect to your Remote Control session` | [네트워크](#couldnt-reconnect-to-your-remote-control-session) |128| `Couldn't reconnect to your Remote Control session` | [네트워크](#couldnt-reconnect-to-your-remote-control-session) |
121| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [네트워크](#sessions-ended-while-this-machine-was-offline) |129| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [네트워크](#sessions-ended-while-this-machine-was-offline) |
122| `Couldn't share the transcript.` | [네트워크](#couldnt-share-the-transcript) |130| `Couldn't share the transcript.` | [네트워크](#couldnt-share-the-transcript) |
131| `Couldn't send feedback` | [네트워크](#couldnt-send-feedback) |
123| `Prompt is too long` / `Input is too long for requested model` | [요청 오류](#prompt-is-too-long) |132| `Prompt is too long` / `Input is too long for requested model` | [요청 오류](#prompt-is-too-long) |
124| `Prompt is too long · automatic compaction failed:` | [요청 오류](#prompt-is-too-long) |133| `Prompt is too long · automatic compaction failed:` | [요청 오류](#prompt-is-too-long) |
125| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [요청 오류](#prompt-is-too-long) |134| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [요청 오류](#prompt-is-too-long) |
139| `PDF too large` / `PDF is password protected` | [요청 오류](#pdf-errors) |148| `PDF too large` / `PDF is password protected` | [요청 오류](#pdf-errors) |
140| `Extra inputs are not permitted` | [요청 오류](#extra-inputs-are-not-permitted) |149| `Extra inputs are not permitted` | [요청 오류](#extra-inputs-are-not-permitted) |
141| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [요청 오류](#tool-input-schema-is-invalid) |150| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [요청 오류](#tool-input-schema-is-invalid) |
151| `tool_use.name: String should have at most 200 characters` | [요청 오류](#tool-use-name-over-200-characters) |
142| `There's an issue with the selected model` | [요청 오류](#theres-an-issue-with-the-selected-model) |152| `There's an issue with the selected model` | [요청 오류](#theres-an-issue-with-the-selected-model) |
143| `Model ... is not a recognized model id` | [요청 오류](#model-is-not-a-recognized-model-id) |153| `Model ... is not a recognized model id` | [요청 오류](#model-is-not-a-recognized-model-id) |
144| `Model ... not found` | [요청 오류](#model-not-found) |154| `Model ... not found` | [요청 오류](#model-not-found) |
155| `API error: ... · model not changed` | [요청 오류](#api-error-model-not-changed) |
145| `Claude Opus is not available with the Claude Pro plan` | [요청 오류](#claude-opus-is-not-available-with-the-claude-pro-plan) |156| `Claude Opus is not available with the Claude Pro plan` | [요청 오류](#claude-opus-is-not-available-with-the-claude-pro-plan) |
146| `Claude Code ... does not support this model; version ... or newer is required` | [요청 오류](#claude-code-does-not-support-this-model) |157| `Claude Code ... does not support this model; version ... or newer is required` | [요청 오류](#claude-code-does-not-support-this-model) |
147| `Claude Code ... is older than the minimum version required by your organization's policy` | [요청 오류](#claude-code-does-not-support-this-model) |158| `Claude Code ... is older than the minimum version required by your organization's policy` | [요청 오류](#claude-code-does-not-support-this-model) |
148| `Model ... is restricted by your organization's settings` | [요청 오류](#model-is-restricted-by-your-organizations-settings) |159| `Model ... is restricted by your organization's settings` | [요청 오류](#model-is-restricted-by-your-organizations-settings) |
160| `Model ... is not available. Your organization restricts model selection.` | [요청 오류](#model-is-restricted-by-your-organizations-settings) |
149| `Model switch ... blocked by a PreModelSwitch hook` | [요청 오류](#model-switch-was-blocked-by-a-premodelswitch-hook) |161| `Model switch ... blocked by a PreModelSwitch hook` | [요청 오류](#model-switch-was-blocked-by-a-premodelswitch-hook) |
150| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [요청 오류](#couldnt-save-it-as-your-default) |162| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [요청 오류](#couldnt-save-it-as-your-default) |
151| `thinking.type.enabled is not supported for this model` | [요청 오류](#thinking-type-enabled-is-not-supported-for-this-model) |163| `thinking.type.enabled is not supported for this model` | [요청 오류](#thinking-type-enabled-is-not-supported-for-this-model) |
155| `API Error: 400 due to tool use concurrency issues` | [요청 오류](#tool-use-or-thinking-block-mismatch) |167| `API Error: 400 due to tool use concurrency issues` | [요청 오류](#tool-use-or-thinking-block-mismatch) |
156| `API Error: 400 orphaned tool_result in conversation history` | [요청 오류](#tool-use-or-thinking-block-mismatch) |168| `API Error: 400 orphaned tool_result in conversation history` | [요청 오류](#tool-use-or-thinking-block-mismatch) |
157| `API Error: 400 duplicate tool_use ID in conversation history` | [요청 오류](#tool-use-or-thinking-block-mismatch) |169| `API Error: 400 duplicate tool_use ID in conversation history` | [요청 오류](#tool-use-or-thinking-block-mismatch) |
170| `Invalid data in redacted_thinking block` | [요청 오류](#invalid-data-in-redacted-thinking-block) |
158| `[Unsupported tool content removed]` | [요청 오류](#unsupported-tool-content-removed) |171| `[Unsupported tool content removed]` | [요청 오류](#unsupported-tool-content-removed) |
159| `role 'system' must precede an 'assistant' message` | [요청 오류](#role-system-must-precede-an-assistant-message) |172| `role 'system' must precede an 'assistant' message` | [요청 오류](#role-system-must-precede-an-assistant-message) |
160| `Invalid encrypted_content in search_result block` / `Invalid encrypted_index in text block` / `Failed to decrypt web search result content` | [요청 오류](#invalid-encrypted-content-in-search-result-block) |173| `Invalid encrypted_content in search_result block` / `Invalid encrypted_index in text block` / `Failed to decrypt web search result content` | [요청 오류](#invalid-encrypted-content-in-search-result-block) |
174| `Invalid encrypted_stdout in encrypted_code_execution_result block` | [요청 오류](#invalid-encrypted-content-in-search-result-block) |
161| `server_tool_use.name: Input should be` on every turn of a resumed session | [요청 오류](#unsupported-tool-content-removed) |175| `server_tool_use.name: Input should be` on every turn of a resumed session | [요청 오류](#unsupported-tool-content-removed) |
162| `<model> can't help with this. Start a new session to continue` | [요청 오류](#usage-policy-refusal) |176| `<model> can't help with this. Start a new session to continue` | [요청 오류](#usage-policy-refusal) |
163| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |177| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [요청 오류](#usage-policy-refusal) |
164| `<model>'s safeguards flagged this message` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |178| `<model>'s safeguards flagged this message` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |
165| `Opus 5.5's safeguards flagged this session` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |179| `<model>'s safeguards flagged this session` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |
166| `<model> has safety measures that flagged this message for a cybersecurity topic` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |180| `<model> has safety measures that flagged this message for a cybersecurity topic` | [요청 오류](#safety-measures-flagged-a-cybersecurity-topic) |
167| `Installation was killed before it could finish (exit code 137)` | [설치 오류](#installation-was-killed-before-it-could-finish) |181| `Installation was killed before it could finish (exit code 137)` | [설치 오류](#installation-was-killed-before-it-could-finish) |
168| `The connection dropped while downloading the update` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |182| `The connection dropped while downloading the update` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |
173| `Couldn't verify your organization's policy for cloud sessions` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |187| `Couldn't verify your organization's policy for cloud sessions` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |
174| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#command-line-errors) |188| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#command-line-errors) |
175| `Error: Invalid --agents configuration:` | [명령줄 오류](#invalid-agents-configuration) |189| `Error: Invalid --agents configuration:` | [명령줄 오류](#invalid-agents-configuration) |
190| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [명령줄 오류](#invalid-agents-configuration) |
191| `Error: --agents file not found` | [명령줄 오류](#invalid-agents-configuration) |
176| `Error: Settings file exceeds the 2MiB limit` | [명령줄 오류](#settings-file-exceeds-the-2mib-limit) |192| `Error: Settings file exceeds the 2MiB limit` | [명령줄 오류](#settings-file-exceeds-the-2mib-limit) |
177| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [명령줄 오류](#the-current-directory-no-longer-exists) |193| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [명령줄 오류](#the-current-directory-no-longer-exists) |
178| `Temp directory <dir> ... Refusing to use it` / `ENOSPC: no space left on device, mkdir '<dir>'` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |194| `Temp directory <dir> ... Refusing to use it` / `ENOSPC: no space left on device, mkdir '<dir>'` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |
207| `Single sign-on authorization needed` | [명령줄 오류](#single-sign-on-authorization-needed) |223| `Single sign-on authorization needed` | [명령줄 오류](#single-sign-on-authorization-needed) |
208| `Failed to resume the conversation` | [명령줄 오류](#failed-to-resume-the-conversation) |224| `Failed to resume the conversation` | [명령줄 오류](#failed-to-resume-the-conversation) |
209| `No conversation found with session ID: <session-id>` | [명령줄 오류](#no-conversation-found-with-the-session-id) |225| `No conversation found with session ID: <session-id>` | [명령줄 오류](#no-conversation-found-with-the-session-id) |
226| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [명령줄 오류](#windows-reported-an-error-ebadf) |
210| `Cannot switch renderers in this session` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |227| `Cannot switch renderers in this session` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |
211| `Cannot switch renderers while work is running in the background` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |228| `Cannot switch renderers while work is running in the background` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |
212| `Couldn't open Claude Desktop` | [명령줄 오류](#couldnt-open-claude-desktop) |229| `Couldn't open Claude Desktop` | [명령줄 오류](#couldnt-open-claude-desktop) |
218| `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) |235| `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) |
219| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [플러그인 오류](#plugin-eval-is-currently-in-early-access) |236| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [플러그인 오류](#plugin-eval-is-currently-in-early-access) |
220| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |237| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |
238| `Claude Code refuses the marketplace name "<name>"` | [플러그인 오류](#claude-code-refuses-the-marketplace-name) |
239| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [플러그인 오류](#claude-code-refuses-the-marketplace-name) |
221| `Marketplace "<name>" is already added from a different source` | [플러그인 오류](#marketplace-is-already-added-from-a-different-source) |240| `Marketplace "<name>" is already added from a different source` | [플러그인 오류](#marketplace-is-already-added-from-a-different-source) |
222| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [플러그인 오류](#marketplace-name-is-another-spelling-of-a-reserved-name) |241| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [플러그인 오류](#marketplace-name-is-another-spelling-of-a-reserved-name) |
223| `references ${user_config.*} in a shell-form command` | [플러그인 오류](#plugin-command-references-user-config) |242| `references ${user_config.*} in a shell-form command` | [플러그인 오류](#plugin-command-references-user-config) |
231| `Failed to load marketplace configuration` | [플러그인 오류](#failed-to-load-marketplace-configuration) |250| `Failed to load marketplace configuration` | [플러그인 오류](#failed-to-load-marketplace-configuration) |
232| `Marketplace configuration file is corrupted` | [플러그인 오류](#failed-to-load-marketplace-configuration) |251| `Marketplace configuration file is corrupted` | [플러그인 오류](#failed-to-load-marketplace-configuration) |
233| `Plugin "<name>@synced" is required by your organization and can't be disabled here` | [플러그인 오류](#plugin-is-required-by-your-organization) |252| `Plugin "<name>@synced" is required by your organization and can't be disabled here` | [플러그인 오류](#plugin-is-required-by-your-organization) |
253| `"<plugin>" was not uninstalled: it is still switched on in <file>` | [플러그인 오류](#plugin-was-not-uninstalled) |
254| `"<plugin>" was not uninstalled: <file> is there and could not be read` | [플러그인 오류](#plugin-was-not-uninstalled) |
234| `would be spawned with zero tools — refusing` | [도구 오류](#agent-would-be-spawned-with-zero-tools) |255| `would be spawned with zero tools — refusing` | [도구 오류](#agent-would-be-spawned-with-zero-tools) |
235| `File is covered by a Read deny rule in your permission settings` | [도구 오류](#file-is-covered-by-a-read-deny-rule) |256| `File is covered by a Read deny rule in your permission settings` | [도구 오류](#file-is-covered-by-a-read-deny-rule) |
257| `cannot contain null bytes (\0)` | [도구 오류](#path-cannot-contain-null-bytes) |
258| `Path contains null bytes` | [도구 오류](#path-cannot-contain-null-bytes) |
236| `subagent_type is required: the general-purpose agent is not available in this session` | [도구 오류](#subagent-type-is-required) |259| `subagent_type is required: the general-purpose agent is not available in this session` | [도구 오류](#subagent-type-is-required) |
237| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [도구 오류](#memory-index-is-over-its-read-limit) |260| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [도구 오류](#memory-index-is-over-its-read-limit) |
238| `pkill: refusing to run` | [도구 오류](#pkill-pattern-matches-the-claude-code-process) |261| `pkill: refusing to run` | [도구 오류](#pkill-pattern-matches-the-claude-code-process) |
248| `Refusing to read <path>: its symlink resolution changed after permission was checked (<reason>)` / `Refusing to search <path>: its symlink resolution changed after permission was checked` | [도구 오류](#refusing-after-a-symlink-changed) |271| `Refusing to read <path>: its symlink resolution changed after permission was checked (<reason>)` / `Refusing to search <path>: its symlink resolution changed after permission was checked` | [도구 오류](#refusing-after-a-symlink-changed) |
249| `Refusing to write <path>: its parent-directory symlink resolution changed after permission was checked` / `Refusing to write <path>: it is a symbolic link. Write to the link's target path instead` | [도구 오류](#refusing-after-a-symlink-changed) |272| `Refusing to write <path>: its parent-directory symlink resolution changed after permission was checked` / `Refusing to write <path>: it is a symbolic link. Write to the link's target path instead` | [도구 오류](#refusing-after-a-symlink-changed) |
250| `Refusing to write through symlink: <path>` / `Refusing to write into symlinked directory: <path>` | [도구 오류](#refusing-after-a-symlink-changed) |273| `Refusing to write through symlink: <path>` / `Refusing to write into symlinked directory: <path>` | [도구 오류](#refusing-after-a-symlink-changed) |
274| `Refusing to write <path>: where it leads on disk could not be determined` / `Refusing to read <path>: where it leads on disk could not be determined` | [도구 오류](#refusing-after-a-symlink-changed) |
251| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [도구 오류](#refusing-after-a-symlink-changed) |275| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [도구 오류](#refusing-after-a-symlink-changed) |
252| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [도구 오류](#refusing-after-a-symlink-changed) |276| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [도구 오류](#refusing-after-a-symlink-changed) |
253| `task output swap refused (tasks dir moved or linked)` | [도구 오류](#task-output-swap-refused) |277| `task output swap refused (tasks dir moved or linked)` | [도구 오류](#task-output-swap-refused) |
254| `Command killed: its output file was replaced or could no longer be verified` | [도구 오류](#task-output-swap-refused) |278| `Command killed: its output file was replaced or could no longer be verified` | [도구 오류](#task-output-swap-refused) |
279| `Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |
280| `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) |
281| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |
255| `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) |282| `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) |
256| `the source file has the replacement character U+FFFD` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |283| `the source file has the replacement character U+FFFD` | [도구 오류](#the-source-file-is-not-valid-utf-8-text) |
257| `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) |284| `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) |
279| `EACCES: permission denied, posix_spawn` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |306| `EACCES: permission denied, posix_spawn` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |
280| `exited before it became reachable` | [백그라운드 세션 오류](#background-service-exited-before-it-became-reachable) |307| `exited before it became reachable` | [백그라운드 세션 오류](#background-service-exited-before-it-became-reachable) |
281| `Couldn't start a background session (working directory no longer exists or is not accessible: ...)` | [백그라운드 세션 오류](#working-directory-no-longer-exists-when-starting-a-background-session) |308| `Couldn't start a background session (working directory no longer exists or is not accessible: ...)` | [백그라운드 세션 오류](#working-directory-no-longer-exists-when-starting-a-background-session) |
309| `Workspace not trusted.` when starting or restarting a background session | [백그라운드 세션 오류](#workspace-not-trusted-when-dispatching-a-background-session) |
282| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |310| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |
283| `Claude Code process exited with code N` | [래퍼 및 IDE 오류](#claude-code-process-exited-with-code-n) |311| `Claude Code process exited with code N` | [래퍼 및 IDE 오류](#claude-code-process-exited-with-code-n) |
284| `The connection to Claude Code ended before this message completed` | [래퍼 및 IDE 오류](#the-connection-to-claude-code-ended-before-this-message-completed) |312| `The connection to Claude Code ended before this message completed` | [래퍼 및 IDE 오류](#the-connection-to-claude-code-ended-before-this-message-completed) |
291| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [구성 경고](#fullscreen-failed-start-notice) |319| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [구성 경고](#fullscreen-failed-start-notice) |
292| `Claude Code exited after an unrecoverable interface error (...)` | [구성 경고](#exited-after-an-unrecoverable-interface-error) |320| `Claude Code exited after an unrecoverable interface error (...)` | [구성 경고](#exited-after-an-unrecoverable-interface-error) |
293| `Agent descriptions are over the 15.0k-token limit` | [구성 경고](#agent-descriptions-are-over-the-15000-token-limit) |321| `Agent descriptions are over the 15.0k-token limit` | [구성 경고](#agent-descriptions-are-over-the-15000-token-limit) |
322| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [구성 경고](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |
294| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |323| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |
295| `is a network path, which cannot be added as a working directory` | [구성 경고](#working-directory-is-a-network-path) |324| `is a network path, which cannot be added as a working directory` | [구성 경고](#working-directory-is-a-network-path) |
296| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |325| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |
297| `Managed settings were not approved; exiting without applying them.` | [구성 경고](#managed-settings-were-not-approved) |326| `Managed settings were not approved; exiting without applying them.` | [구성 경고](#managed-settings-were-not-approved) |
327| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [구성 경고](#managed-settings-block-the-default-model) |
298| `MCP server <name> is blocked by enterprise managed policy` | [구성 경고](#mcp-server-is-blocked-by-enterprise-managed-policy) |328| `MCP server <name> is blocked by enterprise managed policy` | [구성 경고](#mcp-server-is-blocked-by-enterprise-managed-policy) |
299| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [구성 경고](#managed-settings-document-could-not-be-parsed) |329| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [구성 경고](#managed-settings-document-could-not-be-parsed) |
300| `Managed settings drop-in directory could not be read` | [구성 경고](#managed-settings-document-could-not-be-parsed) |330| `Managed settings drop-in directory could not be read` | [구성 경고](#managed-settings-document-could-not-be-parsed) |
390 420
391뒤따르는 문장은 서비스 상태를 확인할 위치를 명시하며 제공자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 구성은 해당 제공자의 서비스 상태를 명시합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 명시합니다.421뒤따르는 문장은 서비스 상태를 확인할 위치를 명시하며 제공자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 구성은 해당 제공자의 서비스 상태를 명시합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 명시합니다.
392 422
393이는 API 내부의 예상치 못한 실패를 나타냅니다. 이는 사용자의 프롬프트, 설정 또는 계정으로 인해 발생하지 않습니다.423API 자체의 5xx는 API 내부의 예상치 못한 실패를 나타냅니다. 이는 사용자의 프롬프트, 설정 또는 계정으로 인해 발생하지 않습니다.
424
425프록시, 로드 밸런서 또는 게이트웨이가 HTML 오류 페이지로 응답할 때 메시지는 상태 코드와 페이지의 제목(예: `API Error: 502 Bad Gateway`)을 표시합니다. 제목이 없는 페이지의 경우 메시지는 상태 코드와 표준 이름을 대신 표시합니다. v2.1.281 이전에는 페이지에 제목이 있을 때 상태 코드가 삭제되었고 제목이 없을 때 페이지의 원본 마크업이 인쇄되었습니다.
394 426
395**수행할 작업:**427**수행할 작업:**
396 428
416 448
417* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다449* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다
418* 몇 분 후에 다시 시도합니다450* 몇 분 후에 다시 시도합니다
419* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`입니다.451* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`입니다. Fable 모델에서 메시지는 Fable을 명시합니다.
452
453 Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는 `Opus is experiencing high load. Switch to Sonnet.`으로 읽히며 앱의 모델 선택기로 모델을 전환합니다.
420 454
421<h3 id="request-timed-out">455<h3 id="request-timed-out">
422 요청 시간 초과456 요청 시간 초과
474API Error: Connection lost mid-response. The response above may be incomplete.508API Error: Connection lost mid-response. The response above may be incomplete.
475API Error: Your computer went to sleep mid-response. The response above may be incomplete.509API Error: Your computer went to sleep mid-response. The response above may be incomplete.
476API Error: The response stopped arriving. The response above may be incomplete.510API Error: The response stopped arriving. The response above may be incomplete.
511API Error: Part of the response never arrived. The response above may be incomplete.
512API Error: The response stream was malformed. The response above may be incomplete.
477```513```
478 514
479* `Server error mid-response`: 스트림 중간 오버로드 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.515* `Server error mid-response`: 스트림 중간 오버로드 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.
480* `Connection lost mid-response`: 연결이 끊어졌습니다.516* `Connection lost mid-response`: 연결이 끊어졌습니다. 프록시 또는 게이트웨이가 응답이 완료되기 전에 응답 본문을 깔끔하게 종료할 때도 이 변형이 표시됩니다.
481* `Your computer went to sleep mid-response`: Claude Code가 응답이 스트리밍되는 동안 컴퓨터가 절전 모드로 전환되었음을 감지했습니다. 컴퓨터가 깨어나면 Claude Code는 연결을 끊어진 것으로 취급하고 읽기를 중지합니다.517* `Your computer went to sleep mid-response`: Claude Code가 응답이 스트리밍되는 동안 컴퓨터가 절전 모드로 전환되었음을 감지했습니다. 컴퓨터가 깨어나면 Claude Code는 연결을 끊어진 것으로 취급하고 읽기를 중지합니다.
518* `Part of the response never arrived`: 스트림 이벤트가 API와 Claude Code 사이에서 손실되어 나중 이벤트가 도착하지 않은 콘텐츠를 참조했습니다. v2.1.281 이전에는 이 경우 턴이 `API Error: Content block not found`로 종료되었습니다.
519* `The response stream was malformed`: 이미 완료된 콘텐츠 블록에 대한 이벤트가 도착했거나 손상된 이벤트가 도착했습니다. 손상된 이벤트는 데이터가 유효한 JSON이 아니거나 콘텐츠가 누락되었거나 콘텐츠가 이벤트의 유형과 일치하지 않는 이벤트입니다. v2.1.284 이전에는 파서의 원본 오류(예: `API Error: JSON Parse error`로 시작하는 오류)가 Claude가 생각, 텍스트 블록 또는 도구 호출을 완료한 후 유효하지 않은 JSON이 있는 이벤트가 도착했을 때 대신 나타났습니다.
482* `The response stopped arriving`: 연결은 열려 있었지만 데이터 전달을 중지했으므로 스트리밍 유휴 감시자가 중단했습니다. v2.1.222 이전에는 Claude Code가 `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`을 통해 도달한 [게이트웨이](/docs/ko/gateways) 연결에서 서버의 킵얼라이브 핑이 여전히 도착하는 동안 이 실패를 보고할 수 있었습니다. 파싱된 응답 이벤트만 계산했기 때문입니다. 업그레이드하면 해당 경로에서 이러한 거짓 시간 초과를 중지합니다. `ANTHROPIC_BEDROCK_BASE_URL`과 같은 제공자 기본 URL을 통해 도달한 게이트웨이는 바이트 감시자로 래핑되지 않습니다. [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)를 참조하세요.520* `The response stopped arriving`: 연결은 열려 있었지만 데이터 전달을 중지했으므로 스트리밍 유휴 감시자가 중단했습니다. v2.1.222 이전에는 Claude Code가 `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_AWS_BASE_URL`을 통해 도달한 [게이트웨이](/docs/ko/gateways) 연결에서 서버의 킵얼라이브 핑이 여전히 도착하는 동안 이 실패를 보고할 수 있었습니다. 파싱된 응답 이벤트만 계산했기 때문입니다. 업그레이드하면 해당 경로에서 이러한 거짓 시간 초과를 중지합니다. `ANTHROPIC_BEDROCK_BASE_URL`과 같은 제공자 기본 URL을 통해 도달한 게이트웨이는 바이트 감시자로 래핑되지 않습니다. [스트리밍 유휴 감시자](/docs/ko/network-config#streaming-idle-watchdogs)를 참조하세요.
483 521
484v2.1.227 이전에는 `Connection lost mid-response`가 `Connection closed mid-response`로 읽혔고 `The response stopped arriving`이 `Response stalled mid-stream`으로 읽혔습니다.522v2.1.227 이전에는 `Connection lost mid-response`가 `Connection closed mid-response`로 읽혔고 `The response stopped arriving`이 `Response stalled mid-stream`으로 읽혔습니다.
485 523
524Claude가 텍스트 또는 도구 호출을 시작하기 전에 손실되거나 중복된 스트림 이벤트가 도착하면 이 공지가 표시되지 않습니다:
525
526* Claude가 생각만 완료했으면 Claude Code가 요청을 다시 발급합니다. 다시 발급된 스트림이 동일한 방식으로 끊어지면 턴이 `Part of the response never arrived and no response was produced. Try again.` 또는 `The response stream was malformed and no response was produced. Try again.`으로 끝납니다.
527* 아무것도 완료되지 않았으면 Claude Code가 스트리밍 없이 요청을 다시 보냅니다. [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`](/docs/ko/env-vars)으로 해당 폴백을 끈 경우 턴이 손실된 이벤트에 대해 `API Error: Content block not found`로 끝나거나 중복된 이벤트에 대해 `API Error: Content block already closed`로 끝납니다. 손상된 이벤트의 경우 폴백이 꺼져 있으면 턴이 `API Error: Stream event unreadable` 또는 파서의 원본 오류로 끝납니다.
528
4864가지 경우에 Claude Code는 이 공지를 즉시 표시하지 않고 실패를 처리합니다:5294가지 경우에 Claude Code는 이 공지를 즉시 표시하지 않고 실패를 처리합니다:
487 530
488* 응답의 앞부분에서 Claude Code는 실패를 재시도하거나 다른 오류로 턴을 종료합니다. [자동 재시도](#automatic-retries)를 참조하세요.531* 응답의 앞부분에서 Claude Code는 실패를 재시도하거나 다른 오류로 턴을 종료합니다. [자동 재시도](#automatic-retries)를 참조하세요.
668API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context711API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context
669```712```
670 713
714Claude Desktop app이 실행하는 세션에서 힌트는 명령을 지정하지 않습니다: claude.ai 사용 설정 페이지를 가리키거나 Team 및 Enterprise 플랜에서는 claude.ai/admin-settings/usage에서 사용 크레딧을 켜거나 관리자에게 요청하도록 지시합니다.
715
671이는 할당량 소진이 아닌 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. 1M 컨텍스트를 직접 포함하는 플랜과 사용 크레딧이 필요한 플랜은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하십시오. Claude Code는 `/model`로 모델을 선택할 때 이 확인을 실행하며 Anthropic API에 대한 직접 연결에서만 실행됩니다. `ANTHROPIC_BASE_URL`을 [LLM gateway](/docs/ko/llm-gateway)로 지정하면 `/model`은 `[1m]` 선택을 허용하고 게이트웨이가 요청 성공 여부를 결정합니다.716이는 할당량 소진이 아닌 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. 1M 컨텍스트를 직접 포함하는 플랜과 사용 크레딧이 필요한 플랜은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하십시오. Claude Code는 `/model`로 모델을 선택할 때 이 확인을 실행하며 Anthropic API에 대한 직접 연결에서만 실행됩니다. `ANTHROPIC_BASE_URL`을 [LLM gateway](/docs/ko/llm-gateway)로 지정하면 `/model`은 `[1m]` 선택을 허용하고 게이트웨이가 요청 성공 여부를 결정합니다.
672 717
673이 오류가 컨텍스트가 200K 토큰을 초과하여 대화 중간에 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 한도 아래로 압축하고 이후 세션을 해당 한도로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서 복구하려면 `/clear`를 실행합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.718이 오류가 컨텍스트가 200K 토큰을 초과하여 대화 중간에 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 한도 아래로 압축하고 이후 세션을 해당 한도로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서 복구하려면 `/clear`를 실행합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.
733 778
734뒤따르는 문장은 서비스 상태를 확인할 위치를 지정하며 공급자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 구성은 Anthropic 상태 페이지 대신 해당 공급자의 서비스 상태를 지정합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 지정합니다.779뒤따르는 문장은 서비스 상태를 확인할 위치를 지정하며 공급자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 구성은 Anthropic 상태 페이지 대신 해당 공급자의 서비스 상태를 지정합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 지정합니다.
735 780
781Claude Code와 API 사이의 프록시, 로드 밸런서 또는 게이트웨이가 자체 HTML 429 페이지로 응답할 때 `·` 뒤의 텍스트는 해당 페이지의 제목(있는 경우)입니다(예: `Too Many Requests`). v2.1.281 이전에는 전체 페이지의 마크업이 `·` 뒤에 인쇄되었습니다.
782
736**수행할 작업:**783**수행할 작업:**
737 784
738* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경의 잘못된 `ANTHROPIC_API_KEY`는 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.785* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경의 잘못된 `ANTHROPIC_API_KEY`는 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.
839Not logged in · Please run /login886Not logged in · Please run /login
840```887```
841 888
889Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는 `Authentication required · Sign in again to continue`로 읽으며, 앱에서 다시 로그인합니다.
890
842**수행할 작업:**891**수행할 작업:**
843 892
844* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다.893* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다.
846* CI 또는 자동화에서 대화형 로그인이 불가능한 경우, 시작 시 키를 가져오는 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다.895* CI 또는 자동화에서 대화형 로그인이 불가능한 경우, 시작 시 키를 가져오는 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다.
847* [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하여 여러 자격증명이 있을 때 Claude Code가 어떤 자격증명을 사용하는지 이해합니다.896* [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하여 여러 자격증명이 있을 때 Claude Code가 어떤 자격증명을 사용하는지 이해합니다.
848 897
849반복적으로 로그인하라는 메시지가 표시되면, 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계에 대해 [로그인하지 않음 또는 토큰 만료](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오.898반복적으로 로그인하라는 메시지가 표시되면, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)에서 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조하십시오.
850 899
851<h3 id="could-not-resolve-authentication-method">900<h3 id="could-not-resolve-authentication-method">
852 인증 방법을 확인할 수 없음901 인증 방법을 확인할 수 없음
862 911
863**수행할 작업:**912**수행할 작업:**
864 913
865* 백그라운드 또는 클라우드 세션에 이것이 나타나고 자격증명이 이미 구성되어 있으면 v2.1.176 이상으로 업그레이드합니다.914* 백그라운드 또는 클라우드 세션에서 이것이 나타나고 자격증명이 이미 구성되어 있으면 v2.1.176 이상으로 업그레이드합니다.
866* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격증명이 대화형 셸뿐만 아니라 워커를 실행하는 환경에 설정되어 있는지 확인합니다.915* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격증명이 대화형 셸이 아닌 워커를 실행하는 환경에서 설정되어 있는지 확인합니다.
867* Agent SDK의 경우, [빠른 시작의 인증 설정](/docs/ko/agent-sdk/quickstart#setup)을 참조하십시오.916* Agent SDK의 경우, [빠른 시작의 인증 설정](/docs/ko/agent-sdk/quickstart#setup)을 참조합니다.
868* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어떤 자격증명 소스가 확인되는지 확인합니다.917* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어떤 자격증명 소스가 확인되는지 확인합니다.
869 918
870<h3 id="invalid-api-key">919<h3 id="invalid-api-key">
877Invalid API key · Fix external API key926Invalid API key · Fix external API key
878```927```
879 928
880메시지가 `Fix external API key` 이후로 `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).`와 같은 설명으로 계속되면, API는 키를 보지 못했습니다. Claude Code가 HTTP 헤더가 전달할 수 없는 문자를 찾았고 전송하기 전에 요청을 중지했습니다. 설명을 읽고 값을 수정하는 방법은 [잘못된 요청 헤더 값](#invalid-request-header-value)을 참조하십시오.929메시지가 `Fix external API key` 이후로 계속되고 `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).`와 같은 설명이 있으면, API는 키를 보지 못했습니다. Claude Code가 HTTP 헤더가 전달할 수 없는 문자를 찾았고 전송하기 전에 요청을 중지했습니다. 설명을 읽고 값을 수정하는 방법은 [잘못된 요청 헤더 값](#invalid-request-header-value)을 참조합니다.
881 930
882**수행할 작업:**931**수행할 작업:**
883 932
888* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.937* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.
889 938
890<h3 id="your-apikeyhelper-script-is-failing">939<h3 id="your-apikeyhelper-script-is-failing">
891 apiKeyHelper 스크립트가 실패함940 apiKeyHelper 스크립트가 실패 중입니다
892</h3>941</h3>
893 942
894Claude Code가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정의 명령을 실행했지만 키를 다시 받지 못했습니다. 키 없이는 요청이 자리 표시자 자격증명으로 API에 도달하고, API가 `401`로 거부합니다. 터미널의 `Authentication` 패널은 다음 중 어떤 일이 발생했는지 보여줍니다:943Claude Code가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정에서 명령을 실행했지만 키를 다시 받지 못했습니다. 키 없이 요청이 자리 표시자 자격증명으로 API에 도달하고, API가 `401`로 거부합니다. 터미널의 `Authentication` 패널은 다음 중 어떤 일이 발생했는지 보여줍니다:
895 944
896* 명령이 오류로 종료되었거나 시간 초과됨945* 명령이 오류로 종료되었거나 시간 초과되었습니다.
897* 명령이 stdout에 아무것도 인쇄하지 않음946* 명령이 stdout에 아무것도 인쇄하지 않았습니다.
898* 명령이 로그인 배너 또는 로그 라인과 같은 키 이외의 것을 인쇄했습니다. 패널은 `returned output that cannot be used as an API key`를 표시하고 무엇이 잘못되었는지 말하며, 출력을 반복하지 않습니다. v2.1.227 이전에는 Claude Code가 주변 공백을 자른 후 명령이 인쇄한 모든 것을 전송했습니다.947* 명령이 로그인 배너 또는 로그 라인과 같이 키 이외의 것을 인쇄했습니다. 패널은 `returned output that cannot be used as an API key`를 표시하고 무엇이 잘못되었는지 말하며, 출력을 반복하지 않습니다. v2.1.227 이전에는 Claude Code가 주변 공백을 자른 후 명령이 인쇄한 모든 것을 전송했습니다.
899 948
900```text theme={null}949```text theme={null}
901Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output950Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output
905 954
906Claude Code는 스크립트를 다시 실행하고 이 메시지를 표시하기 전에 요청을 최대 2회 더 재시도하므로, 실패는 3번의 시도 내에 표시됩니다. v2.1.208 이전에는 Claude Code가 전체 [재시도 예산](#automatic-retries)을 자리 표시자 자격증명으로 요청을 재전송하는 데 사용한 후 일반적인 `401` 인증 오류 대신 스크립트 실패를 보고했습니다.955Claude Code는 스크립트를 다시 실행하고 이 메시지를 표시하기 전에 요청을 최대 2회 더 재시도하므로, 실패는 3번의 시도 내에 표시됩니다. v2.1.208 이전에는 Claude Code가 전체 [재시도 예산](#automatic-retries)을 자리 표시자 자격증명으로 요청을 재전송하는 데 사용한 후 일반적인 `401` 인증 오류 대신 스크립트 실패를 보고했습니다.
907 956
908`/login`을 실행하는 것은 여기서 도움이 되지 않습니다: 헬퍼의 출력은 설정이 있는 한 저장된 로그인보다 [우선합니다](/docs/ko/authentication#authentication-precedence).957`/login`을 실행하는 것은 여기서 도움이 되지 않습니다: 헬퍼의 출력은 설정이 있는 한 저장된 로그인보다 [우선순위](/docs/ko/authentication#authentication-precedence)를 갖습니다.
909 958
910**수행할 작업:**959**수행할 작업:**
911 960
912* `apiKeyHelper`에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다.961* `apiKeyHelper`에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다.
913* 명령이 만료된 세션을 보고하면, 예를 들어 SSO 또는 비밀 자격증명 모음에 다시 로그인하여 자격증명 공급자로 다시 인증합니다.962* 명령이 만료된 세션을 보고하면, 예를 들어 SSO 또는 비밀 자격증명 모음에 다시 로그인하여 자격증명 공급자로 다시 인증합니다.
914* 명령이 stdout에만 키를 인쇄하도록 수정합니다. 최대 16,384자의 인쇄 가능한 ASCII의 단일 토큰으로, 종료 코드 0으로 종료합니다. 작동하는 설정은 [apiKeyHelper로 자격증명 회전](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper)을 참조하십시오.963* 명령이 stdout에만 키를 인쇄하도록 수정합니다. 단일 인쇄 가능한 ASCII 토큰으로 최대 16,384자이며 종료 코드 0으로 종료합니다. 작동하는 설정은 [apiKeyHelper로 자격증명 회전](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper)을 참조합니다.
915* `/status`를 실행하여 `apiKeyHelper`가 활성 자격증명 소스인지 확인합니다. `apiKeyHelper` 행은 `Failing`을 표시하며 마지막 실패의 세부 정보(예: 종료 코드 및 명령의 오류 출력)를 표시하고, 다음 성공적인 실행 후 사라집니다. v2.1.274 이전에는 `/status`가 자격증명 소스만 표시했고 실패를 표시하지 않았습니다.964* `/status`를 실행하여 실패를 확인하고 `apiKeyHelper`가 활성 자격증명 소스인지 확인합니다. `apiKeyHelper` 행은 종료 코드 및 명령의 오류 출력과 같은 마지막 실패의 세부 정보와 함께 `Failing`을 표시하며, 다음 성공적인 실행 후 사라집니다. v2.1.274 이전에는 `/status`가 실패가 아닌 자격증명 소스만 표시했습니다.
916* 명령이 실패할 때마다 종료 코드와 오류 출력이 터미널의 `Authentication` 패널에 나타납니다. v2.1.212 이전에는 패널의 제목이 `Cloud authentication`이었습니다.965* 명령이 실패할 때마다 종료 코드와 오류 출력도 터미널의 `Authentication` 패널에 나타납니다. v2.1.212 이전에는 패널의 제목이 `Cloud authentication`이었습니다.
917 966
918<h3 id="invalid-request-header-value">967<h3 id="invalid-request-header-value">
919 잘못된 요청 헤더 값968 잘못된 요청 헤더 값
921 970
922Claude Code가 요청 헤더로 전송하려던 값에 HTTP 헤더가 전달할 수 없는 문자가 포함되어 있습니다: 줄 바꿈, NUL 바이트 또는 `U+00FF` 위의 문자(예: 곡선 따옴표 또는 너비가 0인 공백). Claude Code는 아무것도 전송되기 전에 요청을 중지하고 수정할 변수 또는 설정의 이름을 지정합니다. 일반적인 원인은 보이지 않는 문자 또는 잘못된 줄 바꿈을 전달한 문서 또는 채팅에서 붙여넣은 자격증명입니다.971Claude Code가 요청 헤더로 전송하려던 값에 HTTP 헤더가 전달할 수 없는 문자가 포함되어 있습니다: 줄 바꿈, NUL 바이트 또는 `U+00FF` 위의 문자(예: 곡선 따옴표 또는 너비가 0인 공백). Claude Code는 아무것도 전송되기 전에 요청을 중지하고 수정할 변수 또는 설정의 이름을 지정합니다. 일반적인 원인은 보이지 않는 문자 또는 잘못된 줄 바꿈을 전달한 문서 또는 채팅에서 붙여넣은 자격증명입니다.
923 972
924Claude Code는 Claude API에 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 요청을 전송할 때 이 확인을 실행합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같은 타사 클라우드 공급자에서 Claude Code는 전송하기 전에 실행하지 않습니다.973Claude Code는 Claude API에 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 요청을 전송할 때 이 확인을 실행합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같은 타사 클라우드 공급자에서는 Claude Code가 전송하기 전에 실행하지 않습니다.
925 974
926```text theme={null}975```text theme={null}
927Invalid auth token · Fix external auth token976Invalid auth token · Fix external auth token
932메시지의 첫 번째 부분은 잘못된 값이 어디에서 왔는지에 따라 달라집니다:981메시지의 첫 번째 부분은 잘못된 값이 어디에서 왔는지에 따라 달라집니다:
933 982
934* `Invalid auth token`: [`ANTHROPIC_AUTH_TOKEN`](/docs/ko/env-vars) 또는 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 베어러 토큰983* `Invalid auth token`: [`ANTHROPIC_AUTH_TOKEN`](/docs/ko/env-vars) 또는 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 베어러 토큰
935* `Invalid ANTHROPIC_CUSTOM_HEADERS`: [`ANTHROPIC_CUSTOM_HEADERS`](/docs/ko/env-vars)에서 설정한 헤더 이름 또는 값입니다. 설명은 `distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS`와 같이 어떤 `Name: Value` 쌍이 잘못되었는지 세지만, 이름이나 값을 반복하지 않습니다.984* `Invalid ANTHROPIC_CUSTOM_HEADERS`: [`ANTHROPIC_CUSTOM_HEADERS`](/docs/ko/env-vars)에서 설정한 헤더 이름 또는 값입니다. 설명은 `ANTHROPIC_CUSTOM_HEADERS`에서 구문 분석된 3개 중 2번째 고유 헤더와 같이 어떤 `Name: Value` 쌍이 잘못되었는지 계산하며, 이름이나 값을 반복하지 않습니다.
936* `Invalid request header from the environment`: Claude Code가 `CLAUDE_AGENT_SDK_CLIENT_APP`과 같은 다른 환경 변수에서 요청 헤더로 복사하는 값입니다. 설명은 수정할 변수의 이름을 지정합니다.985* `Invalid request header from the environment`: Claude Code가 `CLAUDE_AGENT_SDK_CLIENT_APP`과 같은 다른 환경 변수에서 요청 헤더로 복사하는 값입니다. 설명은 수정할 변수의 이름을 지정합니다.
937 986
938Claude Code는 이 확인으로 포착된 잘못된 `ANTHROPIC_API_KEY`를 [잘못된 API 키](#invalid-api-key)로 보고하며, 동일한 후행 설명이 있습니다. 저장된 `/login` 자격증명이 잘못된 경우 [로그인하지 않음](#not-logged-in)으로 보고합니다. 대신 `/login`을 실행하여 새 자격증명을 저장합니다. [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트의 출력은 이 확인에 도달하지 않습니다: Claude Code는 스크립트가 실행될 때 유효성을 검사하고, HTTP 헤더가 전달할 수 없는 출력은 [apiKeyHelper 스크립트가 실패함](#your-apikeyhelper-script-is-failing)으로 실패합니다.987Claude Code는 이 확인으로 포착된 잘못된 `ANTHROPIC_API_KEY`를 [잘못된 API 키](#invalid-api-key)로 보고하며, 동일한 후행 설명이 있습니다. 잘못된 저장된 `/login` 자격증명을 [로그인하지 않음](#not-logged-in)으로 보고합니다. [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트의 출력은 이 확인에 도달하지 않습니다: Claude Code는 스크립트가 실행될 때 유효성을 검사하며, HTTP 헤더가 전달할 수 없는 출력은 [apiKeyHelper 스크립트가 실패 중입니다](#your-apikeyhelper-script-is-failing)로 실패합니다.
939 988
940두 번째 `·` 이후에 메시지는 다음과 같은 전체 예제에서 문제를 설명합니다:989두 번째 `·` 이후에 메시지는 다음과 같은 전체 예제에서 문제를 설명합니다:
941 990
943Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).992Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).
944```993```
945 994
946위치는 1부터 시작하는 문자를 세십시오. 설명은 고정된 구문과 문자 수로 구성되므로 값 자체를 포함하지 않습니다. 바이트 순서 표시, 너비가 0인 공백 또는 곡선 따옴표와 같은 잘 알려진 보이지 않는 또는 인쇄 문자인 경우에만 잘못된 문자의 이름을 지정하고, 다른 모든 것을 `a non-ASCII character`로 보고합니다.995위치는 1부터 시작하는 문자를 계산합니다. 설명은 고정된 구문과 문자 수로 구성되므로 값 자체를 포함하지 않습니다. 바이트 순서 표시, 너비가 0인 공백 또는 곡선 따옴표와 같이 잘 알려진 보이지 않는 또는 인쇄 문자인 경우에만 잘못된 문자의 이름을 지정하며, 다른 모든 것을 `a non-ASCII character`로 보고합니다.
947 996
948**수행할 작업:**997**수행할 작업:**
949 998
950* 메시지가 이름을 지정한 변수 또는 설정을 다시 설정하고, 동일한 소스에서 붙여넣지 않고 보고된 위치 주변의 문자를 다시 입력합니다.999* 메시지가 이름을 지정한 변수 또는 설정을 다시 설정하고, 동일한 소스에서 붙여넣는 대신 보고된 위치 주변의 문자를 다시 입력합니다.
951* `ANTHROPIC_CUSTOM_HEADERS`의 경우, 한 줄에 하나의 `Name: Value` 쌍을 유지하고 메시지가 세는 쌍을 다시 작성합니다.1000* `ANTHROPIC_CUSTOM_HEADERS`의 경우, 한 줄에 하나의 `Name: Value` 쌍을 유지하고 메시지가 계산하는 쌍을 다시 작성합니다.
952* `/status`를 실행하여 어떤 자격증명 소스가 활성인지 확인합니다.1001* `/status`를 실행하여 어떤 자격증명 소스가 활성화되어 있는지 확인합니다.
953 1002
954<h3 id="this-organization-has-been-disabled">1003<h3 id="this-organization-has-been-disabled">
955 이 조직이 비활성화됨1004 이 조직이 비활성화되었습니다
956</h3>1005</h3>
957 1006
958Claude Code가 비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`를 사용하고 있습니다. 저장된 구독 로그인이 있으면 키가 이를 재정의합니다.1007Claude Code가 비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`를 사용 중입니다. 저장된 구독 로그인이 있으면 키가 이를 재정의합니다.
959 1008
960```text theme={null}1009```text theme={null}
961Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead1010Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
965 1014
966`·` 이후의 힌트는 저장된 자격증명에 따라 달라집니다: 첫 번째 형식은 저장된 `/login`이 키를 설정 해제한 후 인수할 수 있을 때 나타나고, 두 번째는 키가 유일한 자격증명일 때 나타납니다.1015`·` 이후의 힌트는 저장된 자격증명에 따라 달라집니다: 첫 번째 형식은 저장된 `/login`이 키를 설정 해제한 후 인수할 수 있을 때 나타나고, 두 번째는 키가 유일한 자격증명일 때 나타납니다.
967 1016
968환경 변수는 `/login`보다 우선하므로, 셸 프로필에서 내보낸 키 또는 `.env` 파일에서 로드된 키는 작동하는 Pro 또는 Max 구독이 있어도 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.1017환경 변수는 `/login`보다 우선순위를 가지므로, 셸 프로필에서 내보낸 키 또는 `.env` 파일에서 로드된 키는 작동하는 Pro 또는 Max 구독이 있어도 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.
969 1018
970**수행할 작업:**1019**수행할 작업:**
971 1020
972* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 후 `claude`를 다시 실행합니다.1021* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 후 `claude`를 다시 실행합니다.
973* 메시지가 `Update or unset`이라고 말하면, 폴백할 저장된 로그인이 없습니다. 키를 설정 해제하고 `/login`을 실행하거나, 활성 Console 조직의 키로 바꿉니다.1022* 메시지가 `Update or unset`이라고 하면, 폴백할 저장된 로그인이 없습니다. 키를 설정 해제하고 `/login`을 실행하거나, 활성 Console 조직의 키로 바꿉니다.
974* 그 후 `/status`를 실행하여 활성 자격증명이 구독인지 확인합니다.1023* 그 후 `/status`를 실행하여 활성 자격증명이 구독인지 확인합니다.
975* 환경 변수가 설정되지 않았고 오류가 지속되면, 비활성화된 조직은 `/login`에 연결된 조직입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.1024* 환경 변수가 설정되지 않았고 오류가 지속되면, 비활성화된 조직은 `/login`에 연결된 조직입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.
976 1025
977<h3 id="your-organization-has-disabled-api-key-authentication">1026<h3 id="your-organization-has-disabled-api-key-authentication">
978 조직이 API 키 인증을 비활성화함1027 조직이 API 키 인증을 비활성화했습니다
979</h3>1028</h3>
980 1029
981이 메시지에는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 끄었으므로 API가 Claude Code가 전송하는 키를 거부합니다. 복구 힌트는 `·` 이후에 키가 어디에서 왔는지에 따라 달라집니다:1030이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 전송 중인 키를 거부합니다. 복구 힌트는 키가 어디에서 왔는지에 따라 `·` 이후에 달라집니다:
982 1031
983```text theme={null}1032```text theme={null}
984Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account1033Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
985Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead1034Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead
986Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account1035Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account
987Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account1036Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account
1037Your organization has disabled API key authentication · Sign in again with your claude.ai account
988```1038```
989 1039
990환경 변수와 `apiKeyHelper`는 `/login`보다 우선하므로, `/login`을 단독으로 실행하는 것은 둘 중 하나가 여전히 키를 공급하는 동안 도움이 되지 않습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하십시오.1040마지막 형식은 Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에 나타나며, 앱에서 다시 로그인합니다.
1041
1042환경 변수와 `apiKeyHelper`는 `/login`보다 우선순위를 가지므로, 둘 중 하나가 여전히 키를 제공하는 동안 `/login`을 실행하는 것만으로는 도움이 되지 않습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조합니다.
991 1043
992**수행할 작업:**1044**수행할 작업:**
993 1045
995* 메시지가 `apiKeyHelper`의 이름을 지정하면, `settings.json`에서 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정을 제거합니다.1047* 메시지가 `apiKeyHelper`의 이름을 지정하면, `settings.json`에서 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정을 제거합니다.
996* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.1048* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.
997* 그 후 `/status`를 실행하여 활성 자격증명이 API 키가 아닌 구독인지 확인합니다.1049* 그 후 `/status`를 실행하여 활성 자격증명이 API 키가 아닌 구독인지 확인합니다.
998* 자동화를 위해 API 키 인증이 필요한 경우, 조직 관리자에게 Console에서 다시 활성화하도록 요청합니다.1050* 자동화를 위해 API 키 인증이 필요하면, 조직 관리자에게 Console에서 이를 다시 활성화하도록 요청합니다.
999 1051
1000<h3 id="your-organization-has-disabled-claude-subscription-access">1052<h3 id="your-organization-has-disabled-claude-subscription-access">
1001 조직이 Claude 구독 액세스를 비활성화함1053 조직이 Claude 구독 액세스를 비활성화했습니다
1002</h3>1054</h3>
1003 1055
1004Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.1056Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.
1013 1065
1014**수행할 작업:**1066**수행할 작업:**
1015 1067
1016* 조직의 관리자에게 조직에 대한 Claude Code 액세스를 활성화하도록 요청합니다.1068* 조직 관리자에게 조직에 대한 Claude Code 액세스를 활성화하도록 요청합니다.
1017* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/docs/ko/authentication#claude-console-authentication)을 참조하십시오.1069* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/docs/ko/authentication#claude-console-authentication)을 참조합니다.
1018* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면, [Anthropic 지원](https://support.claude.com)에 문의합니다.1070* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면, [Anthropic 지원](https://support.claude.com)에 문의합니다.
1019 1071
1020<h3 id="routines-are-disabled-by-your-organizations-policy">1072<h3 id="routines-are-disabled-by-your-organizations-policy">
1021 루틴이 조직의 정책에 의해 비활성화됨1073 루틴이 조직의 정책에 의해 비활성화되었습니다
1022</h3>1074</h3>
1023 1075
1024Team 또는 Enterprise 조직의 Owner가 조직 수준에서 루틴을 끄었습니다. 오류는 예를 들어 claude.ai/code의 [루틴](/docs/ko/routines) UI에서 루틴을 만들거나 실행하려고 할 때 나타납니다. Claude Code v2.1.227 이상에서는 동일한 설정이 CLI에서 [`/schedule`도 숨깁니다](/docs/ko/routines#troubleshooting).1076Team 또는 Enterprise 조직의 Owner가 조직 수준에서 루틴을 비활성화했습니다. 오류는 예를 들어 claude.ai/code의 [루틴](/docs/ko/routines) UI에서 루틴을 생성하거나 실행하려고 할 때 나타납니다. Claude Code v2.1.227 이상에서는 동일한 설정이 CLI에서 [`/schedule`도 숨깁니다](/docs/ko/routines#troubleshooting).
1025 1077
1026```text theme={null}1078```text theme={null}
1027Routines are disabled by your organization's policy.1079Routines are disabled by your organization's policy.
1032**수행할 작업:**1084**수행할 작업:**
1033 1085
1034* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **루틴** 토글을 활성화하도록 요청합니다.1086* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **루틴** 토글을 활성화하도록 요청합니다.
1035* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우, [예약된 작업](/docs/ko/scheduled-tasks)을 참조하십시오.1087* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우, [예약된 작업](/docs/ko/scheduled-tasks)을 참조합니다.
1036 1088
1037<h3 id="remote-control-requires-the-anthropic-api">1089<h3 id="remote-control-requires-the-anthropic-api">
1038 원격 제어에는 Anthropic API가 필요함1090 Remote Control에는 Anthropic API가 필요합니다
1039</h3>1091</h3>
1040 1092
1041세션이 Anthropic API와 직접 통신하지 않으므로 [원격 제어](/docs/ko/remote-control)가 쌍을 이룰 claude.ai 백엔드가 없습니다.1093세션이 Anthropic API와 직접 통신하지 않으므로 [Remote Control](/docs/ko/remote-control)이 쌍을 이룰 claude.ai 백엔드가 없습니다.
1042 1094
1043```text theme={null}1095```text theme={null}
1044Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.1096Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.
1046 1098
1047두 번째 문장은 세션을 Anthropic API에서 멀어지게 한 것을 설명합니다. v2.1.219 이전에는 메시지가 첫 번째 문장만 있었습니다. 원인에 따라 메시지는 다음의 이름을 지정합니다:1099두 번째 문장은 세션을 Anthropic API에서 멀어지게 한 것을 설명합니다. v2.1.219 이전에는 메시지가 첫 번째 문장만 있었습니다. 원인에 따라 메시지는 다음의 이름을 지정합니다:
1048 1100
1049* [Amazon Bedrock](/docs/ko/amazon-bedrock)의 `CLAUDE_CODE_USE_BEDROCK` 또는 [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)의 `CLAUDE_CODE_USE_VERTEX`와 같은 `CLAUDE_CODE_USE_*` 공급자 변수1101* `CLAUDE_CODE_USE_BEDROCK`(예: [Amazon Bedrock](/docs/ko/amazon-bedrock)) 또는 `CLAUDE_CODE_USE_VERTEX`(예: [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai))와 같은 `CLAUDE_CODE_USE_*` 공급자 변수
1050* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 `api.anthropic.com` 이외의 호스트를 가리키고 있습니다. 예를 들어 [LLM 게이트웨이](/docs/ko/llm-gateway) 또는 프록시이며, claude.ai로 로그인할 때도 마찬가지입니다. v2.1.196 이전에는 사용자 정의 기본 URL이 원격 제어를 차단하지 않았습니다.1102* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 `api.anthropic.com` 이외의 호스트를 가리키고 있습니다. 예를 들어 [LLM 게이트웨이](/docs/ko/llm-gateway) 또는 프록시이며, claude.ai로 로그인할 때도 마찬가지입니다. v2.1.196 이전에는 사용자 정의 기본 URL이 Remote Control을 차단하지 않았습니다.
1051* `ANTHROPIC_UNIX_SOCKET`이 설정되어 있으므로 세션이 `api.anthropic.com`이 아닌 로컬 소켓을 통해 요청을 전송합니다.1103* `ANTHROPIC_UNIX_SOCKET`이 설정되어 있으므로 세션이 `api.anthropic.com`이 아닌 로컬 소켓을 통해 요청을 전송합니다.
1052* `/login`을 통한 엔터프라이즈 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인으로, 원격 제어를 지원하지 않으며 설정 해제할 변수가 없습니다.1104* `/login`을 통한 엔터프라이즈 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인으로, Remote Control을 지원하지 않으며 설정 해제할 변수가 없습니다.
1053 1105
1054**수행할 작업:**1106**수행할 작업:**
1055 1107
1056* 메시지가 이름을 지정한 변수(예: `CLAUDE_CODE_USE_BEDROCK` 또는 `ANTHROPIC_BASE_URL`)를 설정 해제하고 세션을 다시 시작하거나, Anthropic API와 직접 통신하는 세션에서 원격 제어를 시작합니다.1108* 메시지가 이름을 지정한 변수(예: `CLAUDE_CODE_USE_BEDROCK` 또는 `ANTHROPIC_BASE_URL`)를 설정 해제하고 세션을 다시 시작하거나, Anthropic API와 직접 통신하는 세션에서 Remote Control을 시작합니다.
1057* 변수가 셸에 설정되지 않았으면, [설정 파일](/docs/ko/settings#where-settings-live)의 `env` 키를 확인하십시오. 이는 모든 세션에 환경 변수를 적용합니다.1109* 변수가 셸에 설정되지 않았으면, [설정 파일](/docs/ko/settings#where-settings-live)의 `env` 키를 확인합니다. 이는 모든 세션에 환경 변수를 적용합니다.
1058* 이 및 다른 원격 제어 시작 메시지의 경우, [원격 제어 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조하십시오.1110* 이 및 다른 Remote Control 시작 메시지의 경우, [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조합니다.
1059 1111
1060<h3 id="remote-control-couldnt-refresh-your-login">1112<h3 id="remote-control-couldnt-refresh-your-login">
1061 원격 제어가 로그인을 새로 고칠 수 없음1113 Remote Control이 로그인을 새로 고칠 수 없습니다
1062</h3>1114</h3>
1063 1115
1064Claude Code는 저장된 claude.ai 로그인을 사용하여 얻고 갱신하는 단기 자격증명에서 라이브 [원격 제어](/docs/ko/remote-control) 연결을 실행합니다. claude.ai가 해당 로그인을 더 이상 수락하지 않거나 Claude Code에 저장된 로그인이 남아 있지 않으면, Claude Code는 원격 제어를 중지하고 다시 로그인하도록 요청합니다. 두 실패 모두 Claude Code가 여전히 연결 중이거나 나중에 자격증명을 갱신할 때 발생할 수 있습니다.1116Claude Code는 저장된 claude.ai 로그인을 사용하여 얻고 갱신하는 단기 자격증명에서 라이브 [Remote Control](/docs/ko/remote-control) 연결을 실행합니다. claude.ai가 해당 로그인을 더 이상 수락하지 않거나 Claude Code에 저장된 로그인이 남아 있지 않으면, Claude Code는 Remote Control을 중지하고 다시 로그인하도록 요청합니다. 두 실패 모두 Claude Code가 여전히 연결 중이거나 나중에 자격증명을 갱신할 때 발생할 수 있습니다.
1065 1117
1066Claude Code가 로그인 서비스에 저장된 로그인을 새로 고치도록 요청하고 응답을 받지 못하면, 원격 제어를 계속 실행하고 연결의 현재 자격증명이 여전히 유효한 동안 새로 고침을 다시 시도합니다. 새로 고침이 응답을 받지 못하는 경우는 Claude Code가 로그인 서비스에 도달할 수 없거나, 요청이 시간 초과되거나, 서비스가 로그인을 거부하지 않고 실패할 때입니다. 로그인 서비스가 해당 자격증명이 만료될 때까지 여전히 응답하지 않으면, Claude Code는 원격 제어를 중지하고 `OAuth token refresh failed`를 보고합니다.1118Claude Code가 로그인 서비스에 저장된 로그인을 새로 고치도록 요청하고 응답을 받지 못하면, Remote Control을 계속 실행하고 연결의 현재 자격증명이 여전히 유효한 동안 새로 고침을 다시 시도합니다. 새로 고침이 응답을 받지 못하는 경우는 Claude Code가 로그인 서비스에 도달할 수 없거나, 요청이 시간 초과되거나, 서비스가 로그인을 거부하지 않고 실패할 때입니다. 해당 자격증명이 만료될 때 로그인 서비스가 여전히 응답하지 않으면, Claude Code는 Remote Control을 중지하고 `OAuth token refresh failed`를 보고합니다.
1067 1119
1068Claude Code가 원격 제어를 중지하면, 경고 및 `Remote Control disconnected`로 시작하는 기록 라인에 이유를 표시합니다. 로컬 세션은 원격 제어 없이 계속 실행됩니다. 이 섹션은 다음 라인을 다룹니다:1120Claude Code가 Remote Control을 중지하면, 경고 및 `Remote Control disconnected`로 시작하는 기록 라인에 이유를 표시합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다. 이 섹션은 다음 라인을 다룹니다:
1069 1121
1070```text theme={null}1122```text theme={null}
1071Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control1123Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
1081 1133
1082* ` Claude.ai login expired` 및 `Claude.ai login was rejected`: claude.ai가 더 이상 저장된 로그인 토큰을 수락하지 않습니다. 만료되었거나 취소되었기 때문입니다.1134* ` Claude.ai login expired` 및 `Claude.ai login was rejected`: claude.ai가 더 이상 저장된 로그인 토큰을 수락하지 않습니다. 만료되었거나 취소되었기 때문입니다.
1083* ` OAuth token unavailable`: Claude Code가 연결의 자격증명이 갱신될 때 저장된 로그인 토큰이 없었습니다.1135* ` OAuth token unavailable`: Claude Code가 연결의 자격증명이 갱신될 때 저장된 로그인 토큰이 없었습니다.
1084* `OAuth token refresh failed`: claude.ai가 Claude Code가 다시 연결할 때 저장된 로그인 토큰을 거부했고, 토큰을 새로 고치면 새 토큰이 생성되지 않았습니다.1136* `OAuth token refresh failed`: Claude Code가 다시 연결할 때 claude.ai가 저장된 로그인 토큰을 거부했으며, 토큰을 새로 고치면 새 토큰이 생성되지 않았습니다.
1085* `JWT refresh failed: no OAuth token`: Claude Code가 갱신할 저장된 로그인 토큰을 찾지 못했습니다.1137* `JWT refresh failed: no OAuth token`: Claude Code가 갱신할 저장된 로그인 토큰을 찾지 못했습니다.
1086* ` Signed out of Claude`: 예를 들어 다른 터미널에서 `/logout`을 실행하여 이 머신에서 로그아웃했으므로 Claude Code가 연결을 갱신할 저장된 로그인이 없습니다.1138* ` Signed out of Claude`: 예를 들어 다른 터미널에서 `/logout`을 실행하여 이 머신에서 로그아웃했으므로 Claude Code가 연결을 갱신할 저장된 로그인이 없습니다.
1087 1139
1090* `/login`을 실행하여 다시 로그인합니다.1142* `/login`을 실행하여 다시 로그인합니다.
1091* `/remote-control`을 실행하여 세션을 다시 연결합니다. ` run /login to restore Remote Control`으로 끝나는 메시지는 이 단계가 필요하지 않습니다: Claude Code는 로그인하면 자동으로 다시 연결됩니다.1143* `/remote-control`을 실행하여 세션을 다시 연결합니다. ` run /login to restore Remote Control`으로 끝나는 메시지는 이 단계가 필요하지 않습니다: Claude Code는 로그인하면 자동으로 다시 연결됩니다.
1092 1144
1093v2.1.224 이전에는 `OAuth token refresh failed — run /login to re-authenticate`가 `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`으로 읽혔고, `JWT refresh failed: no OAuth token — run /login`이 `no OAuth token available for recovery (code <N>)`으로 읽혔습니다. ` Claude.ai login expired`, `Claude.ai login was rejected` 및 `OAuth token unavailable` 메시지는 v2.1.225에서 추가되었습니다.1145v2.1.224 이전에는 `OAuth token refresh failed — run /login to re-authenticate`가 `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`으로 읽혔으며, `JWT refresh failed: no OAuth token — run /login`이 `no OAuth token available for recovery (code <N>)`으로 읽혔습니다. ` Claude.ai login expired`, `Claude.ai login was rejected` 및 `OAuth token unavailable` 메시지는 v2.1.225에서 추가되었습니다.
1094 1146
1095v2.1.238 이전에는 Claude Code가 현재 `Signed out of Claude`라고 말하는 경우를 `JWT refresh failed: no OAuth token — run /login`으로 보고했고, 한 번의 로그인 새로 고침이 응답을 받지 못하자마자 `Claude.ai login expired — run /login to restore Remote Control`으로 원격 제어를 중지했습니다.1147v2.1.238 이전에는 Claude Code가 현재 `Signed out of Claude`라고 하는 경우를 `JWT refresh failed: no OAuth token — run /login`으로 보고했으며, 한 번의 로그인 새로 고침이 응답을 받지 못하자마자 `Claude.ai login expired — run /login to restore Remote Control`으로 Remote Control을 중지했습니다.
1096 1148
1097<h3 id="remote-control-stopped-because-the-signed-in-account-changed">1149<h3 id="remote-control-stopped-because-the-signed-in-account-changed">
1098 원격 제어가 로그인한 계정이 변경되어 중지됨1150 Remote Control이 로그인한 계정이 변경되어 중지되었습니다
1099</h3>1151</h3>
1100 1152
1101Claude Code는 [원격 제어](/docs/ko/remote-control) 세션 중에 이 라인을 표시합니다. 이 머신에서 다른 claude.ai 계정 또는 조직으로 로그인합니다. 예를 들어 다른 터미널에서 `/login`을 실행하여 Claude Code 세션 외부에서 전환했습니다.1153Claude Code는 이 머신에서 다른 claude.ai 계정 또는 조직으로 로그인할 때 [Remote Control](/docs/ko/remote-control) 세션 중에 이 라인을 표시합니다. 예를 들어 다른 터미널에서 `/login`을 실행하여 Claude Code 세션 외부에서 전환했습니다.
1102 1154
1103`/login`을 통해 로그인하는 동안 시작한 원격 제어 세션은 당시에 로그인한 claude.ai 계정 및 조직에 속합니다.1155`/login`을 통해 로그인하는 동안 시작한 Remote Control 세션은 당시 로그인한 claude.ai 계정 및 조직에 속합니다.
1104 1156
1105```text theme={null}1157```text theme={null}
1106Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control1158Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control
1107```1159```
1108 1160
1109Claude Code는 claude.ai가 계정 또는 조직이 변경되었음을 확인하는 즉시 원격 제어 세션을 중지합니다. 로컬 세션은 원격 제어 없이 계속 실행됩니다.1161Claude Code는 claude.ai가 계정 또는 조직이 변경되었음을 확인하자마자 Remote Control 세션을 중지합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다.
1110 1162
1111**수행할 작업:**1163**수행할 작업:**
1112 1164
1113* `/remote-control`을 실행하여 현재 계정 또는 조직에서 새 원격 제어 세션을 시작합니다.1165* `/remote-control`을 실행하여 현재 계정 또는 조직에서 새 Remote Control 세션을 시작합니다.
1114* 다시 전환하려면 `/login`을 실행하고 이전 계정 또는 조직으로 다시 로그인합니다. 그런 다음 `/remote-control`을 실행합니다.1166* 다시 전환하려면, `/login`을 실행하고 이전 계정 또는 조직으로 다시 로그인합니다. 그런 다음 `/remote-control`을 실행합니다.
1115 1167
1116v2.1.234 이전에는 Claude Code가 Claude Code 세션 외부에서 다른 계정 또는 조직으로 전환할 때 알아차리지 못했습니다. Claude Code는 원격 제어 서버에 대한 나중의 요청이 `Remote Control server rejected the request (HTTP 404)`로 실패할 때까지 원격 제어 세션을 연결된 상태로 유지했습니다. 이 실패는 전환 후 몇 시간 후에 올 수 있습니다.1168v2.1.234 이전에는 Claude Code가 Claude Code 세션 외부에서 다른 계정 또는 조직으로 전환할 때 알아차리지 못했습니다. Claude Code는 Remote Control 서버에 대한 나중의 요청이 `Remote Control server rejected the request (HTTP 404)`로 실패할 때까지 Remote Control 세션을 연결된 상태로 유지했습니다. 해당 실패는 전환 후 몇 시간이 지날 수 있습니다.
1117 1169
1118<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">1170<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">
1119 원격 제어가 세션을 실행하는 앱이 로그아웃하거나 계정을 전환했기 때문에 중지됨1171 Remote Control이 세션을 실행 중인 앱이 로그아웃하거나 계정을 전환하여 중지되었습니다
1120</h3>1172</h3>
1121 1173
1122Claude 데스크톱 앱 또는 IDE가 세션을 호스팅할 때, Claude Code는 `/login` 대신 해당 앱에서 로그인 토큰을 가져옵니다. claude.ai가 해당 토큰을 거부할 때, Claude Code는 앱에 새 토큰을 요청합니다. 앱이 로그아웃했거나 이제 다른 Claude 계정으로 로그인했다고 응답하면, Claude Code는 [원격 제어](/docs/ko/remote-control) 세션을 종료하고 앱에 다음 라인 중 하나를 보냅니다:1174Claude 데스크톱 앱 또는 IDE가 세션을 호스팅할 때, Claude Code는 `/login`이 아닌 해당 앱에서 로그인 토큰을 가져옵니다. claude.ai가 해당 토큰을 거부할 때, Claude Code는 앱에 새 토큰을 요청합니다. 앱이 로그아웃했거나 이제 다른 Claude 계정으로 로그인했다고 응답하면, Claude Code는 [Remote Control](/docs/ko/remote-control) 세션을 종료하고 앱에 다음 라인 중 하나를 보냅니다:
1123 1175
1124```text theme={null}1176```text theme={null}
1125Remote Control stopped — the app running this session is now signed in to a different Claude account1177Remote Control stopped — the app running this session is now signed in to a different Claude account
1126Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on1178Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on
1127```1179```
1128 1180
1129로컬 세션은 원격 제어 없이 계속 실행됩니다.1181로컬 세션은 Remote Control 없이 계속 실행됩니다.
1130 1182
1131**수행할 작업:**1183**수행할 작업:**
1132 1184
1133* 앱이 로그아웃되면, 다시 로그인한 후 앱에서 원격 제어를 다시 켭니다.1185* 앱이 로그아웃했으면, 다시 로그인한 후 앱에서 Remote Control을 다시 켭니다.
1134* 앱이 계정을 전환하면, Claude Code는 새 계정에서 종료된 세션을 계속할 수 없습니다. 해당 계정에서 새 원격 제어 세션을 시작합니다.1186* 앱이 계정을 전환했으면, Claude Code는 새 계정에서 종료된 세션을 계속할 수 없습니다. 해당 계정에서 새 Remote Control 세션을 시작합니다.
1135 1187
1136v2.1.238 이전에는 Claude Code가 두 경우 모두에서 [원격 제어가 로그인을 새로 고칠 수 없음](#remote-control-couldnt-refresh-your-login)에 나열된 `run /login` 메시지를 앱에 보냈습니다.1188v2.1.238 이전에는 Claude Code가 두 경우 모두에서 앱에 [Remote Control이 로그인을 새로 고칠 수 없습니다](#remote-control-couldnt-refresh-your-login)에 나열된 `run /login` 메시지를 보냈습니다.
1137 1189
1138<h3 id="oauth-token-revoked-or-expired">1190<h3 id="oauth-token-revoked-or-expired">
1139 OAuth 토큰이 취소되었거나 만료됨1191 OAuth 토큰이 취소되었거나 만료되었습니다
1140</h3>1192</h3>
1141 1193
1142저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.1194저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.
1143 1195
1144두 메시지 모두 Claude Code가 전송한 요청에 대해 API가 반환한 거부를 보고합니다. 저장된 로그인이 실패한 새로 고침 후 이미 지워진 경우, 대신 [로그인 만료됨](#login-expired)을 참조하십시오. [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 장기 토큰으로 인증하면, 해당 토큰이 만료되거나 취소될 때 동일한 메시지가 표시됩니다.1196두 메시지 모두 Claude Code가 전송한 요청에 대해 API가 반환한 거부를 보고합니다. 저장된 로그인이 실패한 새로 고침 후 이미 지워진 경우, 대신 [로그인 만료됨](#login-expired)을 봅니다. [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)에서 장기 토큰으로 인증하면, 해당 토큰이 만료되거나 취소될 때 동일한 메시지가 표시됩니다.
1145 1197
1146```text theme={null}1198```text theme={null}
1147OAuth token revoked · Please run /login1199OAuth token revoked · Please run /login
1152 1204
1153* `/login`을 실행하여 다시 로그인합니다.1205* `/login`을 실행하여 다시 로그인합니다.
1154* 오류가 다시 인증한 후 동일한 세션 내에서 반환되면, 먼저 `/logout`을 실행하여 저장된 토큰을 완전히 지운 후 `/login`을 실행합니다.1206* 오류가 다시 인증한 후 동일한 세션 내에서 반환되면, 먼저 `/logout`을 실행하여 저장된 토큰을 완전히 지운 후 `/login`을 실행합니다.
1155* ` CLAUDE_CODE_OAUTH_TOKEN` 환경 변수로 인증하면, Claude Code는 요청이 401로 실패한 후 설정한 값을 계속 전송하고, 저장된 로그인의 토큰으로 전환하지 않습니다. [`/status`](/docs/ko/commands)는 이 자격증명을 `Auth token` 행으로 표시하며 `CLAUDE_CODE_OAUTH_TOKEN`을 읽습니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 새 토큰을 생성하고 이를 사용하여 다시 시작하거나, 변수를 설정 해제하고 `/login`을 실행합니다. v2.1.225 이전에는 Claude Code가 세션 중에 변수의 값을 저장된 로그인의 단기 액세스 토큰으로 바꿀 수 있었고, 해당 토큰이 만료되면 세션이 다시 401 오류로 실패했습니다.1207* ` CLAUDE_CODE_OAUTH_TOKEN` 환경 변수로 인증하면, Claude Code는 요청이 401로 실패한 후 설정한 값을 계속 전송하며, 저장된 로그인의 토큰으로 전환하지 않습니다. [`/status`](/docs/ko/commands)는 이 자격증명을 `Auth token` 행으로 표시하며 `CLAUDE_CODE_OAUTH_TOKEN`을 읽습니다. [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 새 토큰을 생성하고 이를 사용하여 다시 시작하거나, 변수를 설정 해제하고 `/login`을 실행합니다. v2.1.225 이전에는 Claude Code가 세션 중에 변수의 값을 저장된 로그인의 단기 액세스 토큰으로 바꿀 수 있었으며, 해당 토큰이 만료되면 세션이 다시 401 오류로 실패했습니다.
1156* 시작 간 반복되는 로그인 프롬프트의 경우, [문제 해결](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조하십시오.1208* 시작 간 반복적인 로그인 프롬프트의 경우, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조합니다.
1157* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하십시오.1209* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조합니다.
1158 1210
1159<h3 id="api-error-401-invalid-authentication-credentials">1211<h3 id="api-error-401-invalid-authentication-credentials">
1160 API 오류: 401 잘못된 인증 자격증명1212 API 오류: 401 잘못된 인증 자격증명
1161</h3>1213</h3>
1162 1214
1163API가 자격증명의 형식을 인식했지만 뒤에 있는 계정 또는 조직을 거부했습니다. Anthropic은 자격증명이 최근에 취소되었을 때, 조직이 비활성화되었거나 액세스를 제거했을 때, 또는 계정 자체가 비활성화되었을 때 이 메시지를 반환하므로, 만료된 토큰이 원인이 아닙니다. 자격증명은 저장된 로그인 또는 승인된 `ANTHROPIC_API_KEY`일 수 있으며, 수정이 다르므로 `/status`를 실행하여 어떤 것이 활성인지 확인하여 시작합니다.1215API가 자격증명의 형식을 인식했지만 뒤에 있는 계정 또는 조직을 거부했습니다. Anthropic은 자격증명이 최근에 취소되었거나, 조직이 비활성화되었거나 액세스를 제거했거나, 계정 자체가 비활성화되었을 때 이 메시지를 반환하므로, 만료된 토큰이 원인이 아닙니다. 자격증명은 저장된 로그인 또는 승인된 `ANTHROPIC_API_KEY`일 수 있으며, 수정이 다르므로 `/status`를 실행하여 어떤 것이 활성화되어 있는지 확인하여 시작합니다.
1164 1216
1165```text theme={null}1217```text theme={null}
1166Please run /login · API Error: 401 Invalid authentication credentials1218Please run /login · API Error: 401 Invalid authentication credentials
1168 1220
1169**수행할 작업:**1221**수행할 작업:**
1170 1222
1171* `/status`가 사용 중이 아닌 것으로 표시되지 않은 `API key` 행을 표시하면, 승인된 [`ANTHROPIC_API_KEY`](/docs/ko/authentication#authentication-precedence)가 활성 자격증명이고 로그인보다 우선하므로 `/login`이 이를 바꾸지 않습니다. Claude Console에서 키를 회전하거나, `unset ANTHROPIC_API_KEY`를 실행하거나, PowerShell에서 `Remove-Item Env:ANTHROPIC_API_KEY`를 실행하여 구독으로 폴백합니다.1223* `/status`가 사용 중이 아닌 것으로 표시되지 않은 `API key` 행을 표시하면, 승인된 [`ANTHROPIC_API_KEY`](/docs/ko/authentication#authentication-precedence)가 활성 자격증명이며 로그인보다 우선순위를 가지므로 `/login`이 이를 바꾸지 않습니다. Claude Console에서 키를 회전하거나, `unset ANTHROPIC_API_KEY`를 실행하거나, PowerShell에서 `Remove-Item Env:ANTHROPIC_API_KEY`를 실행하여 구독으로 폴백합니다.
1172* `/status`가 로그인만 표시하면, `/login`을 한 번 실행합니다. 자격증명이 취소되었으면, 새 로그인이 이를 바꿉니다.1224* `/status`가 로그인만 표시하면, `/login`을 한 번 실행합니다. 자격증명이 취소되었으면, 새 로그인이 이를 바꿉니다.
1173* 동일한 로그인 계정에 대해 동일한 메시지가 반환되면, 계정 또는 조직이 더 이상 활성화되지 않습니다. `/status`가 보고하는 계정 및 조직을 확인하고, 조직 관리자에게 액세스를 복구하도록 요청합니다.1225* 동일한 로그인 계정에 대해 동일한 메시지가 반환되면, 계정 또는 조직이 더 이상 활성화되지 않습니다. `/status`가 보고하는 계정 및 조직을 확인하고, 조직 관리자에게 액세스를 복구하도록 요청합니다.
1174* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키면, `401` 이후의 텍스트는 Anthropic의 메시지가 아닌 게이트웨이의 메시지이고, `/login`이 이를 변경하지 않습니다. 대신 게이트웨이가 예상하는 자격증명을 수정합니다.1226* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키면, `401` 이후의 텍스트는 Anthropic의 메시지가 아닌 게이트웨이의 메시지이며, `/login`이 이를 변경하지 않습니다. 게이트웨이가 예상하는 자격증명을 대신 수정합니다.
1175 1227
1176<h3 id="login-expired">1228<h3 id="login-expired">
1177 로그인 만료됨1229 로그인 만료됨
1178</h3>1230</h3>
1179 1231
1180Claude Code가 저장된 claude.ai 또는 Claude Console 로그인을 갱신하려고 시도했고 OAuth 서비스가 저장된 새로 고침 토큰을 거부했으므로, Claude Code가 저장된 자격증명을 지웠습니다. 그 후, 각 모델 요청은 API에 도달하기 전에 로컬에서 이 메시지로 중지됩니다. `/login`만 새 자격증명을 만들 수 있기 때문입니다.1232Claude Code가 저장된 claude.ai 또는 Claude Console 로그인을 갱신하려고 했으며 OAuth 서비스가 저장된 새로 고침 토큰을 거부했으므로, Claude Code가 저장된 자격증명을 지웠습니다. 그 후, 각 모델 요청은 `/login`만 새 자격증명을 만들 수 있으므로 API에 도달하기 전에 로컬에서 이 메시지로 중지됩니다.
1181 1233
1182v2.1.206 이전에는 Claude Code가 환경에 남아 있는 모든 자격증명으로 모델 요청을 어쨌든 전송했고, 모든 모델이 로그인하라는 프롬프트 대신 [선택한 모델에 문제가 있음](#theres-an-issue-with-the-selected-model) 또는 401로 실패했습니다.1234v2.1.206 이전에는 Claude Code가 환경에 남아 있는 모든 자격증명으로 모델 요청을 어쨌든 전송했으며, 모든 모델이 로그인하라는 프롬프트 대신 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model) 또는 401로 실패했습니다.
1183 1235
1184```text theme={null}1236```text theme={null}
1185Login expired · Please run /login1237Login expired · Please run /login
1191Failed to authenticate: OAuth session expired and could not be refreshed1243Failed to authenticate: OAuth session expired and could not be refreshed
1192```1244```
1193 1245
1194이것은 [OAuth 토큰이 취소되었거나 만료됨](#oauth-token-revoked-or-expired)과 동일한 상태가 아닙니다. 이러한 메시지는 API가 반환한 거부를 보고합니다. Claude Code 자체는 이미 갱신하지 못한 로그인에 대해 `Login expired`를 생성하므로, 요청을 전송하지 않습니다. 갱신이 로그인이 오래되었기 때문이 아니라 계정 자체가 일시 중지되었기 때문에 실패하면, Claude Code는 대신 [계정이 보류 중임](#your-account-is-on-hold)을 표시합니다.1246이것은 [OAuth 토큰이 취소되었거나 만료되었습니다](#oauth-token-revoked-or-expired)와 동일한 상태가 아닙니다. 이러한 메시지는 API가 반환한 거부를 보고합니다. Claude Code 자체는 이미 갱신하지 못한 로그인에 대해 `Login expired`를 생성하므로, 요청을 전송하지 않습니다. 계정 자체가 일시 중단되었기 때문에 갱신이 실패하면, Claude Code는 대신 [계정이 보류 중입니다](#your-account-is-on-hold)를 표시합니다.
1195 1247
1196API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.1248API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.
1197 1249
1198` /status`를 실행하여 요청이 실패하기 전에 이 상태를 확인할 수 있습니다: 로그인 행을 표시하며 `Expired — log in again`을 읽고, 만료된 로그인에 대해 저장한 조직 및 이메일을 표시합니다. 행은 저장된 로그인이 활성 자격증명이고 더 이상 갱신할 수 없을 때만 나타납니다. 다른 방식으로 인증된 세션은 만료된 로그인이 남아 있어도 행을 표시하지 않습니다. v2.1.210 이전에는 `/status`가 이 상태에서 로그인이 존재했던 적이 있다는 표시를 주지 않았습니다. 지워진 자격증명이 보고할 것이 없었기 때문입니다.1250요청이 실패하기 전에 이 상태를 확인할 수 있습니다: [`/status`](/docs/ko/commands)는 `Login` 행을 표시하며 `Expired — log in again`을 읽고, 만료된 로그인에 대해 저장한 조직 및 이메일을 표시합니다. 행은 저장된 로그인이 활성 자격증명이고 더 이상 갱신할 수 없을 때만 나타납니다. 다른 방식으로 인증된 세션은 만료된 로그인이 저장되어 있어도 행을 표시하지 않습니다. v2.1.210 이전에는 `/status`가 이 상태에서 로그인이 존재했던 적이 있다는 표시를 주지 않았습니다. 지워진 자격증명이 보고할 것이 없었기 때문입니다.
1199 1251
1200**수행할 작업:**1252**수행할 작업:**
1201 1253
1202* `/login`을 실행하여 다시 로그인합니다. 로그인하지 않고 재시도하면 모든 요청에서 동일한 메시지가 표시됩니다.1254* `/login`을 실행하여 다시 로그인합니다. 로그인하지 않고 재시도하면 모든 요청에서 동일한 메시지가 표시됩니다.
1203* 비대화형 모드에서 동일한 환경에서 `claude`를 실행하고, `/login`을 완료한 후 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우, `ANTHROPIC_API_KEY` 또는 [`claude setup-token`으로 장기 토큰 생성](/docs/ko/authentication#generate-a-long-lived-token)으로 인증합니다.1255* 비대화형 모드에서는 동일한 환경에서 `claude`를 실행하고, `/login`을 완료한 후 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우, `ANTHROPIC_API_KEY`로 인증하거나 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 장기 토큰을 생성합니다.
1204* 로그인이 계속 실패하면, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하십시오.1256* 로그인이 계속 실패하면, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조합니다.
1257
1258<h3 id="could-not-refresh-your-login">
1259 다른 Claude Code 프로세스가 로그인을 새로 고치고 있어서 로그인을 새로 고칠 수 없습니다
1260</h3>
1261
1262이 메시지는 로그인이 거부되었다는 의미가 아닙니다. 저장된 claude.ai 로그인이 만료되었으며 갱신이 필요했습니다. 동일한 머신의 다른 Claude Code 프로세스가 공유 새로 고침 잠금을 보유했거나, 종료되고 뒤에 남겨두었으며, 이 세션이 기다리는 동안 새로 고침이 진행되지 않았습니다. Claude Code는 전송하기 전에 요청을 중지합니다:
1263
1264```text theme={null}
1265Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login
1266```
1267
1268[비대화형 모드](/docs/ko/headless)(`-p`) 및 [Agent SDK](/docs/ko/agent-sdk/overview)에서 메시지는 다음과 같이 읽으며, 구조화된 오류 코드는 `server_error`입니다:
1269
1270```text theme={null}
1271Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again
1272```
1273
1274API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.
1275
1276**수행할 작업:**
1277
1278* 1분 후에 다시 시도합니다. 다른 프로세스가 먼저 새로 고침을 완료하면, 이 세션이 갱신된 로그인을 사용합니다.
1279* 메시지가 계속 반환되면, 다른 Claude Code 창과 프로세스를 닫은 후 재시도합니다.
1280* 다른 Claude Code 프로세스가 실행 중이지 않은 상태에서 반환되면, `/login`을 실행합니다. 다시 로그인하면 새로 고침 잠금을 기다리지 않습니다.
1281
1282<h3 id="couldnt-save-your-login">
1283 로그인을 저장할 수 없습니다
1284</h3>
1285
1286claude.ai로 로그인했지만 Claude Code가 로그인을 자격증명 저장소에 저장할 수 없어서, 로그인이 완료되지 않았습니다. macOS에서는 예를 들어 절전 또는 유휴 후 로그인 키체인이 잠길 때 발생할 수 있으며, Claude Code가 동일한 세션 중에 이미 자격증명을 읽거나 저장한 후입니다.
1287
1288```text theme={null}
1289Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.
1290Couldn't save your login. Try logging in again.
1291```
1292
1293첫 번째 형식은 macOS에 나타나고 두 번째는 다른 곳에 나타납니다. 시간 초과 또는 읽을 수 없는 저장소와 같은 일시적인 자격증명 저장소 실패는 동일한 메시지를 생성합니다.
1294
1295**수행할 작업:**
1296
1297* macOS에서 로그인 키체인을 잠금 해제한 후 `/login`을 다시 실행합니다.
1298* 다른 플랫폼에서 `/login`을 다시 실행합니다.
1299* 로그인이 여전히 저장되지 않으면, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)에서 키체인 잠금 해제 명령 및 기타 자격증명 저장소 복구 단계를 참조합니다.
1205 1300
1206<h3 id="claude-login-not-accepted">1301<h3 id="claude-login-not-accepted">
1207 Claude 로그인이 수락되지 않음1302 Claude 로그인이 수락되지 않음
1208</h3>1303</h3>
1209 1304
1210[클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작하려고 시도했고, 서버가 401로 생성을 거부했습니다: 이 머신이 보낸 Claude 로그인을 수락하지 않았습니다. 일반적으로 로그인이 만료되었거나 취소되었기 때문입니다.1305[클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작하려고 했으며, 서버가 401로 생성을 거부했습니다: 이 머신이 전송한 Claude 로그인을 수락하지 않았습니다. 일반적으로 로그인이 만료되었거나 취소되었기 때문입니다.
1211 1306
1212라인의 첫 번째 부분은 서버가 제공할 때 서버의 자체 이유입니다. 그렇지 않으면 라인은 다음과 같이 읽습니다:1307라인의 첫 번째 부분은 서버가 제공할 때 서버 자신의 이유입니다. 그렇지 않으면 라인은 다음과 같이 읽습니다:
1213 1308
1214```text theme={null}1309```text theme={null}
1215Claude login not accepted · Run /login, then try again1310Claude login not accepted · Run /login, then try again
1220* `/login`을 실행하고, 로그인을 완료한 후 세션을 다시 시작합니다.1315* `/login`을 실행하고, 로그인을 완료한 후 세션을 다시 시작합니다.
1221 1316
1222<h3 id="artifacts-need-a-claude-ai-login">1317<h3 id="artifacts-need-a-claude-ai-login">
1223 아티팩트에 claude.ai 로그인이 필요함1318 아티팩트에 claude.ai 로그인이 필요합니다
1224</h3>1319</h3>
1225 1320
1226Claude Code가 [아티팩트](/docs/ko/artifacts) 게시 또는 읽기를 거부했습니다. 세션에 아티팩트에 사용할 수 있는 claude.ai 로그인이 없기 때문입니다.1321Claude Code가 세션에 아티팩트에 사용할 수 있는 claude.ai 로그인이 없어서 [아티팩트](/docs/ko/artifacts) 게시 또는 읽기를 거부했습니다.
1227 1322
1228메시지의 모든 형식은 동일한 단어로 시작하고, 세션이 인증하는 방식에 따라 달라지는 해결책이 뒤따릅니다. 경쟁하는 자격증명이 없으면 다음과 같이 읽습니다:1323메시지의 모든 형식은 동일한 단어로 시작하며, 그 뒤에 세션이 인증하는 방식에 따라 달라지는 해결책이 있습니다. 경쟁하는 자격증명이 없으면 다음과 같이 읽습니다:
1229 1324
1230```text theme={null}1325```text theme={null}
1231Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.1326Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.
1234**수행할 작업:**1329**수행할 작업:**
1235 1330
1236* `/login`을 실행하고 **Claude account with subscription**을 선택합니다. **Anthropic Console account** 옵션은 claude.ai 자격증명을 제공하지 않습니다.1331* `/login`을 실행하고 **Claude account with subscription**을 선택합니다. **Anthropic Console account** 옵션은 claude.ai 자격증명을 제공하지 않습니다.
1237* 메시지가 `ANTHROPIC_API_KEY`, `apiKeyHelper` 설정 또는 이전 `/login`으로 저장된 Console 키와 같이 우선하는 자격증명의 이름을 지정하면, 메시지가 말하는 방식으로 제거한 후 `/login`을 실행합니다.1332* 메시지가 `ANTHROPIC_API_KEY`, `apiKeyHelper` 설정 또는 이전 `/login`으로 저장된 Console 키와 같이 우선순위를 갖는 자격증명의 이름을 지정하면, 메시지가 말하는 방식으로 제거한 후 `/login`을 실행합니다.
1238* 메시지가 이 원격 세션이 이를 실행한 머신을 통해 인증된다고 말하면, 해당 머신에서 claude.ai에 로그인한 후 세션을 다시 연결합니다.1333* 메시지가 이 원격 세션이 이를 실행한 머신을 통해 인증한다고 하면, 해당 머신에서 claude.ai에 로그인한 후 세션을 다시 연결합니다.
1239* 메시지가 자격증명이 세션의 호스트 환경에 의해 주입된다고 말하면, 해당 세션에서 변경할 수 없습니다. claude.ai에 로그인한 세션을 시작합니다.1334* 메시지가 자격증명이 세션의 호스트 환경에 의해 주입된다고 하면, 해당 세션에서 이를 변경할 수 없습니다. claude.ai에 로그인한 세션을 시작합니다.
1240* [가용성](/docs/ko/artifacts#availability)에서 계획, 모델 공급자 및 조직 정책과 같은 아티팩트가 가진 다른 요구 사항을 참조하십시오.1335* 계획, 모델 공급자 및 조직 정책과 같은 아티팩트가 가진 다른 요구 사항은 [가용성](/docs/ko/artifacts#availability)을 참조합니다.
1241 1336
1242<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">1337<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">
1243 관리자 정책에 클라우드 게이트웨이 로그인이 필요함1338 관리자 정책에 Cloud 게이트웨이 로그인이 필요합니다
1244</h3>1339</h3>
1245 1340
1246관리자의 [관리 설정](/docs/ko/managed-settings)이 이 머신에서 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정했거나 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정했습니다. `CLAUDE_CODE_USE_BEDROCK`과 같은 변수를 통해 클라우드 공급자를 선택하지 않으면, Claude Code는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 로그인만 수락합니다. 두 메시지 중 하나가 표시됩니다:1341관리자의 [관리 설정](/docs/ko/managed-settings)이 이 머신에서 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정했거나 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정했습니다. `CLAUDE_CODE_USE_BEDROCK`과 같은 변수를 통해 클라우드 공급자를 선택하지 않으면, Claude Code는 [Claude apps 게이트웨이](/docs/ko/claude-apps-gateway) 로그인만 수락합니다. 두 가지 메시지 중 하나가 표시됩니다:
1247 1342
1248```text theme={null}1343```text theme={null}
1249Not signed in to the Cloud gateway — run /login.1344Not signed in to the Cloud gateway — run /login.
1251 1346
1252세션에 게이트웨이 로그인이 없을 때 모델 요청이 이 메시지로 실패합니다. 예를 들어 정책이 머신에 도달한 이후 `/login`을 실행하지 않았기 때문입니다.1347세션에 게이트웨이 로그인이 없을 때 모델 요청이 이 메시지로 실패합니다. 예를 들어 정책이 머신에 도달한 이후 `/login`을 실행하지 않았기 때문입니다.
1253 1348
1254`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격증명이 구성되어 있고 관리 설정이 `forceLoginMethod`를 설정하면, Claude Code는 대신 시작 시 다음과 같이 시작하는 메시지로 종료됩니다:1349또한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격증명이 구성되어 있고 관리 설정이 `forceLoginMethod`를 설정하면, Claude Code는 대신 시작 시 다음과 같이 시작하는 메시지로 종료됩니다:
1255 1350
1256```text theme={null}1351```text theme={null}
1257Administrator policy requires a Cloud gateway sign-in on this machine; the1352Administrator policy requires a Cloud gateway sign-in on this machine; the
1261 1356
1262**수행할 작업:**1357**수행할 작업:**
1263 1358
1264* `/login`을 실행하고 **클라우드 게이트웨이** 화면에서 로그인을 완료합니다.1359* `/login`을 실행하고 **Cloud gateway** 화면에서 로그인을 완료합니다.
1265* 시작 메시지의 경우, 구성한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 설정을 제거한 후 `claude`를 시작하고 `/login`을 실행합니다.1360* 시작 메시지의 경우, 구성한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 설정을 제거한 후 `claude`를 시작하고 `/login`을 실행합니다.
1266* 머신이 게이트웨이를 요구하지 않아야 한다고 생각하면, 관리자에게 관리 설정에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 제거하도록 요청합니다.1361* 머신이 게이트웨이를 요구하지 않아야 한다고 생각하면, 관리 설정에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 제거하도록 머신을 관리하는 관리자에게 요청합니다.
1267 1362
1268v2.1.265에서는 회귀로 인해 API 키, `apiKeyHelper` 또는 사용자 정의 헤더로 인증하는 일부 LLM 게이트웨이 및 프록시 구성에서도 첫 번째 메시지가 표시되었습니다. 머신에 관리자 요구 사항이 없어도 마찬가지입니다. v2.1.266 이상으로 업그레이드합니다. 구성을 변경할 필요가 없습니다.1363v2.1.265에서는 회귀가 API 키, `apiKeyHelper` 또는 사용자 정의 헤더로 인증하는 일부 LLM 게이트웨이 및 프록시 구성에서도 첫 번째 메시지를 표시했으며, 머신에 관리자 요구 사항이 없었습니다. v2.1.266 이상으로 업데이트합니다. 구성을 변경할 필요가 없습니다.
1269 1364
1270v2.1.261 이전에는 `forceLoginMethod`를 `"gateway"`로 설정한 머신에서 Claude Code가 모델 요청을 실패하는 대신 남은 저장된 로그인을 사용했고, 구성된 환경 자격증명을 시작 메시지 대신 `This machine's managed settings require a first-party login`으로 보고했습니다. v2.1.265 이전에는 관리 설정이 `forceLoginGatewayUrl`만 설정한 머신이 게이트웨이 로그인을 요구하지 않았고, Claude Code가 거기서 남은 자격증명을 사용했습니다.1365v2.1.261 이전에는 `forceLoginMethod`를 `"gateway"`로 설정한 머신에서 Claude Code가 모델 요청을 실패하는 대신 남은 저장된 로그인을 사용했으며, 구성된 환경 자격증명을 `This machine's managed settings require a first-party login` 대신 시작 메시지로 보고했습니다. v2.1.265 이전에는 관리 설정이 `forceLoginGatewayUrl`만 설정한 머신이 게이트웨이 로그인을 요구하지 않았으며, Claude Code가 거기서 남은 자격증명을 사용했습니다.
1271 1366
1272<h3 id="your-account-is-on-hold">1367<h3 id="your-account-is-on-hold">
1273 계정이 보류 중임1368 계정이 보류 중입니다
1274</h3>1369</h3>
1275 1370
1276Claude 계정이 로그인 뒤에 일시 중지되었습니다. Claude Code는 저장된 로그인을 갱신하려고 시도할 때 보류를 알게 되면 첫 번째 메시지를 표시하고, 브라우저에서 완료한 로그인이 이를 보고하면 두 번째 메시지를 표시합니다:1371로그인 뒤의 Claude 계정이 일시 중단되었습니다. Claude Code는 저장된 로그인을 갱신하려고 할 때 보류를 알게 되면 첫 번째 메시지를 표시하고, 브라우저에서 완료한 로그인이 이를 보고하면 두 번째 메시지를 표시합니다:
1277 1372
1278```text theme={null}1373```text theme={null}
1279Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted1374Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
1291 Anthropic 프로필 로그인 만료됨1386 Anthropic 프로필 로그인 만료됨
1292</h3>1387</h3>
1293 1388
1294Claude Code가 저장된 로그인 자격증명이 만료된 Anthropic 자격증명 프로필을 통해 인증하고 있으며, 프로필이 갱신하는 데 사용할 수 있는 새로 고침 자격증명을 보유하지 않습니다. Claude Code는 동일한 만료된 자격증명을 읽을 재시도가 하므로 각 요청을 로컬에서 중지합니다.1389Claude Code가 저장된 로그인 자격증명이 만료된 Anthropic 자격증명 프로필을 통해 인증 중이며, 프로필이 Claude Code가 갱신하는 데 사용할 수 있는 새로 고침 자격증명을 보유하지 않습니다. Claude Code는 동일한 만료된 자격증명을 읽을 재시도가 있으므로 각 요청을 로컬에서 중지합니다.
1295 1390
1296```text theme={null}1391```text theme={null}
1297Anthropic profile login expired · Re-authenticate your Anthropic profile1392Anthropic profile login expired · Re-authenticate your Anthropic profile
1298Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile1393Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile
1299```1394```
1300 1395
1301이것은 활성 자격증명이 Anthropic 자격증명 프로필에서 오는 경우에만 나타납니다. 하나는 `ANTHROPIC_PROFILE` 환경 변수로 선택하고, Claude Code가 Anthropic 구성 디렉토리에서 활성 프로필로 발견하거나, Claude Code가 [API 키 없이 로그인](/docs/ko/authentication#sign-in-without-an-api-key)할 때 작성했습니다. `/login`의 claude.ai 옵션, API 키, `ANTHROPIC_AUTH_TOKEN`과 같은 베어러 토큰 또는 타사 공급자로 인증된 세션은 이 메시지를 절대 보지 않습니다.1396이것은 활성 자격증명이 Anthropic 자격증명 프로필에서 올 때만 나타나며, `ANTHROPIC_PROFILE` 환경 변수로 선택하거나, Claude Code가 Anthropic 구성 디렉토리에서 활성 프로필로 발견하거나, Claude Code가 [API 키 없이 로그인](/docs/ko/authentication#sign-in-without-an-api-key)할 때 작성했습니다. `/login`의 claude.ai 옵션, API 키, `ANTHROPIC_AUTH_TOKEN`과 같은 베어러 토큰 또는 타사 공급자로 인증하는 세션은 이 메시지를 절대 보지 않습니다.
1302 1397
1303[키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서 `/login`을 실행하고, Anthropic Console 계정을 선택하고, 다시 로그인하여 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필을 갱신합니다. Claude Code는 해당 프로필의 만료된 자격증명을 바꿉니다. 페더레이션 프로필 또는 다른 도구가 만든 프로필의 경우, `/login`이 자격증명을 갱신하지 않습니다. 어떤 형식이 표시되는지는 프로필을 선택했는지 또는 Claude Code가 발견했는지에 따라 달라집니다:1398[키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서는 `/login`을 실행하고, Anthropic Console 계정을 선택하고, 다시 로그인하여 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필을 갱신합니다. Claude Code는 해당 프로필의 만료된 자격증명을 바꿉니다. 페더레이션 프로필 또는 다른 도구가 만든 프로필의 경우, `/login`이 자격증명을 갱신하지 않습니다. 어떤 형식을 보는지는 프로필을 선택했는지 아니면 Claude Code가 발견했는지에 따라 달라집니다:
1304 1399
1305* `ANTHROPIC_PROFILE`을 명시적으로 설정하면, 메시지는 `Re-authenticate your Anthropic profile`로 끝납니다.1400* `ANTHROPIC_PROFILE`을 명시적으로 설정하면, 메시지는 `Re-authenticate your Anthropic profile`로 끝납니다.
1306* Claude Code가 구성 디렉토리에서 프로필을 발견하면, 메시지는 `/login`을 제공합니다. Claude Code가 작동하는 `/login`을 발견된 프로필보다 우선하고 대신 claude.ai 또는 Console 계정으로 인증하기 때문입니다. v2.1.234 이전에는 Claude Code가 이 경우에도 `Re-authenticate your Anthropic profile` 형식을 표시했습니다.1401* Claude Code가 구성 디렉토리에서 프로필을 발견했으면, 메시지는 `/login`을 제공합니다. Claude Code가 작동하는 `/login`을 발견된 프로필보다 우선순위를 주고 대신 claude.ai 또는 Console 계정으로 인증하기 때문입니다. v2.1.234 이전에는 Claude Code가 이 경우에도 `Re-authenticate your Anthropic profile` 형식을 표시했습니다.
1307 1402
1308**수행할 작업:**1403**수행할 작업:**
1309 1404
1310* 프로필을 다시 인증한 후 재시도합니다: [키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서, 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필의 경우 `/login`을 실행하고 Anthropic Console 계정을 선택합니다. 다른 프로필의 경우, 프로필을 만든 도구를 사용합니다.1405* 프로필에 다시 로그인한 후 재시도합니다: [키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서는 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필의 경우 `/login`을 실행하고 Anthropic Console 계정을 선택합니다. 다른 프로필의 경우, 프로필을 만든 도구를 사용합니다.
1311* 관리자가 프로필의 자격증명을 프로비저닝했으면, 새 자격증명을 발급하도록 요청합니다.1406* 관리자가 프로필의 자격증명을 프로비저닝했으면, 새 자격증명을 발급하도록 요청합니다.
1312* `/status`를 실행하여 활성 자격증명 소스 및 프로필 이름을 확인합니다.1407* `/status`를 실행하여 활성 자격증명 소스 및 프로필 이름을 확인합니다.
1313* 프로필 사용을 중지하려면, 설정했으면 `ANTHROPIC_PROFILE`을 설정 해제한 후 `/login` 또는 `ANTHROPIC_API_KEY`와 같은 다른 방식으로 인증합니다.1408* 프로필 사용을 중지하려면, 설정했으면 `ANTHROPIC_PROFILE`을 설정 해제한 후 `/login` 또는 `ANTHROPIC_API_KEY`와 같은 다른 방식으로 인증합니다.
1316 OAuth 범위 요구 사항1411 OAuth 범위 요구 사항
1317</h3>1412</h3>
1318 1413
1319저장된 토큰이 최신 기능이 필요한 권한 범위보다 앞서 있습니다. 이것은 `/usage` 및 상태 라인 사용 표시기에서 가장 자주 표시됩니다:1414저장된 토큰이 최신 기능이 필요로 하는 권한 범위보다 앞서 있습니다. 이것은 `/usage` 및 상태 라인 사용 표시기에서 가장 자주 표시됩니다:
1320 1415
1321```text theme={null}1416```text theme={null}
1322OAuth token does not meet scope requirement: user:profile1417OAuth token does not meet scope requirement: user:profile
1327* `/login`을 실행하여 현재 범위가 있는 새 토큰을 가져옵니다. 먼저 로그아웃할 필요가 없습니다.1422* `/login`을 실행하여 현재 범위가 있는 새 토큰을 가져옵니다. 먼저 로그아웃할 필요가 없습니다.
1328 1423
1329<h3 id="claude-ai-rejected-the-session-token">1424<h3 id="claude-ai-rejected-the-session-token">
1330 claude.ai가 세션 토큰을 거부함1425 claude.ai가 세션 토큰을 거부했습니다
1331</h3>1426</h3>
1332 1427
1333[claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) 요청이 실패했습니다. claude.ai가 Claude Code 로그인의 토큰을 거부했습니다. 일반적으로 만료되었고 새로 고칠 수 없는 로그인입니다. 거부된 토큰은 로그인이지, 커넥터의 자체 claude.ai 인증이 아니므로, 커넥터를 다시 인증해도 해결되지 않습니다. `/mcp`에서 커넥터는 `connected · session token rejected`로 표시되고 세부 정보 보기는 다음과 같이 읽습니다:1428[claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) 요청이 실패했습니다. claude.ai가 Claude Code 로그인의 토큰을 거부했습니다. 일반적으로 만료되었거나 새로 고칠 수 없는 로그인입니다. 거부된 토큰은 로그인이며, 커넥터 자신의 claude.ai 인증이 아니므로, 커넥터를 다시 인증해도 해결되지 않습니다. `/mcp`에서 커넥터는 `connected · session token rejected`로 표시되며 세부 정보 보기는 다음과 같이 읽습니다:
1334 1429
1335```text theme={null}1430```text theme={null}
1336claude.ai rejected the session token. Run /login, then reconnect.1431claude.ai rejected the session token. Run /login, then reconnect.
1339**수행할 작업:**1434**수행할 작업:**
1340 1435
1341* `/login`을 실행하여 다시 로그인합니다.1436* `/login`을 실행하여 다시 로그인합니다.
1342* `/mcp`에서 커넥터를 다시 연결하거나, `/mcp reconnect <server>`를 실행합니다. 다시 로그인하기 전에 다시 연결하면 커넥터가 동일한 상태로 유지됩니다. `/mcp` 패널의 **다시 연결** 옵션은 `your claude.ai session token was rejected`를 보고합니다. 입력된 `/mcp reconnect <server>` 형식은 토큰이 여전히 거부되었음에도 불구하고 성공적인 다시 연결을 보고합니다.1437* `/mcp`에서 커넥터를 다시 연결하거나, `/mcp reconnect <server>`를 실행합니다. 다시 로그인하기 전에 다시 연결하면 커넥터가 동일한 상태로 유지됩니다. `/mcp` 패널의 **Reconnect** 옵션은 `your claude.ai session token was rejected`를 보고합니다. 입력된 `/mcp reconnect <server>` 형식은 토큰이 여전히 거부되었음에도 불구하고 성공적인 다시 연결을 보고합니다.
1343 1438
1344v2.1.222 이전에는 Claude Code가 커넥터를 인증이 필요한 것으로 표시했으며, 이는 완료해도 상태를 해결하지 않는 커넥터의 인증 흐름을 가리켰습니다.1439v2.1.222 이전에는 Claude Code가 커넥터를 인증이 필요한 것으로 표시했으며, 이는 완료해도 상태를 해결하지 못하는 커넥터의 인증 흐름을 가리켰습니다.
1345 1440
1346<h3 id="mcp-server-needs-you-to-sign-in-again">1441<h3 id="mcp-server-needs-you-to-sign-in-again">
1347 MCP 서버가 다시 로그인하도록 요청함1442 MCP 서버가 다시 로그인하도록 요청합니다
1348</h3>1443</h3>
1349 1444
1350원격 [MCP 서버](/docs/ko/mcp)가 세션 중에 도구 호출에 대한 자격증명을 거부했습니다. 일반적으로 로그인 또는 토큰이 만료되었거나 취소되었거나 토큰이 도구가 필요한 권한이 부족하기 때문입니다. 도구 호출이 실패하고 `/mcp`는 서버를 [인증이 필요한 것](/docs/ko/mcp#authenticate-with-remote-mcp-servers)으로 표시합니다.1445원격 [MCP 서버](/docs/ko/mcp)가 세션 중에 도구 호출에서 자격증명을 거부했습니다. 일반적으로 로그인 또는 토큰이 만료되었거나 취소되었거나 토큰이 도구가 필요로 하는 권한이 부족합니다. 도구 호출이 실패하고 `/mcp`가 서버를 [인증이 필요한 것](/docs/ko/mcp#authenticate-with-remote-mcp-servers)으로 표시합니다.
1351 1446
1352Claude Code에서 로그인하는 서버(claude.ai 커넥터 포함)의 경우, 로그인이 만료되었거나 취소되었습니다:1447Claude Code에서 로그인하는 서버(claude.ai 커넥터 포함)의 경우, 로그인이 만료되었거나 취소되었습니다:
1353 1448
1357 1452
1358`/mcp`를 실행하고, 서버를 선택하고, 메뉴에서 다시 로그인합니다.1453`/mcp`를 실행하고, 서버를 선택하고, 메뉴에서 다시 로그인합니다.
1359 1454
1360[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 스크립트로 구성된 서버의 경우, Claude Code가 이미 헬퍼를 다시 실행하고 호출을 한 번 재시도한 후 이것을 표시합니다:1455[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 스크립트로 구성된 서버의 경우, Claude Code가 이미 헬퍼를 다시 실행하고 표시하기 전에 호출을 한 번 재시도했습니다:
1361 1456
1362```text theme={null}1457```text theme={null}
1363MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)1458MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)
1365 1460
1366헬퍼가 서버가 수락하는 자격증명을 반환하는지 확인한 후, `/mcp`에서 다시 연결합니다. 이는 헬퍼를 다시 실행합니다.1461헬퍼가 서버가 수락하는 자격증명을 반환하는지 확인한 후, `/mcp`에서 다시 연결합니다. 이는 헬퍼를 다시 실행합니다.
1367 1462
1368구성에 정적 `Authorization` 헤더가 있는 서버의 경우:1463정적 `Authorization` 헤더가 있는 서버의 경우:
1369 1464
1370```text theme={null}1465```text theme={null}
1371MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)1466MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)
1375 1470
1376v2.1.273 이전에는 만료된 로그인, `headersHelper` 및 `Authorization` 헤더 경우가 모두 `MCP server "<name>" requires re-authorization (token expired)`를 표시했습니다.1471v2.1.273 이전에는 만료된 로그인, `headersHelper` 및 `Authorization` 헤더 경우가 모두 `MCP server "<name>" requires re-authorization (token expired)`를 표시했습니다.
1377 1472
1378서버는 HTTP 403 `insufficient_scope`로 도구 호출을 거부하여 범위를 인증하도록 요청할 수도 있습니다. 때로는 토큰이 이미 나열한 범위입니다. 메시지는 해당 범위의 이름을 지정합니다:1473서버는 HTTP 403 `insufficient_scope`로 도구 호출을 거부하여 범위를 요청할 수도 있습니다. 때로는 토큰이 이미 나열한 범위입니다. 메시지는 해당 범위의 이름을 지정합니다:
1379 1474
1380```text theme={null}1475```text theme={null}
1381MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate1476MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate
1385 1480
1386서버의 구성이 [`oauth.scopes`](/docs/ko/mcp#restrict-oauth-scopes) 또는 [`authServerMetadataUrl`](/docs/ko/mcp#override-oauth-metadata-discovery)을 설정하지 않으면, Claude Code가 서버가 이름을 지정한 범위를 요청합니다. 어느 설정이든 Claude Code가 해당 설정의 범위를 요청합니다. `oauth.scopes`를 고정했으면, 다시 인증하기 전에 누락된 범위를 해당 목록에 추가합니다.1481서버의 구성이 [`oauth.scopes`](/docs/ko/mcp#restrict-oauth-scopes) 또는 [`authServerMetadataUrl`](/docs/ko/mcp#override-oauth-metadata-discovery)을 설정하지 않으면, Claude Code가 서버가 이름을 지정한 범위를 요청합니다. 어느 설정이든 Claude Code가 해당 설정의 범위를 요청합니다. `oauth.scopes`를 고정했으면, 다시 인증하기 전에 누락된 범위를 해당 목록에 추가합니다.
1387 1482
1388v2.1.274 이전에는 이 경우가 `needs you to sign in again` 메시지를 표시했고, v2.1.273 이전에는 다른 경우처럼 `requires re-authorization (token expired)`를 표시했습니다.1483v2.1.274 이전에는 이 경우가 `needs you to sign in again` 메시지를 표시했으며, v2.1.273 이전에는 다른 경우처럼 `requires re-authorization (token expired)`를 표시했습니다.
1389 1484
1390<h3 id="issuer-mismatch-in-authorization-response">1485<h3 id="issuer-mismatch-in-authorization-response">
1391 인증 응답의 발급자 불일치1486 인증 응답의 발급자 불일치
1397Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"1492Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"
1398```1493```
1399 1494
1400`expected`는 서버의 OAuth 메타데이터의 발급자이고, `received`는 리디렉션이 전달한 `iss` 값입니다. 리디렉션이 `iss` 매개변수를 전달하지 않는 로그인은 확인을 통과합니다. 서버의 메타데이터가 `authorization_response_iss_parameter_supported`를 설정하지 않으면, 이 경우 Claude Code는 로그인을 실패합니다.1495`expected`는 서버의 OAuth 메타데이터의 발급자이며, `received`는 리디렉션이 전달한 `iss` 값입니다. `iss` 매개변수를 전달하지 않는 로그인은 확인을 통과합니다. 서버의 메타데이터가 `authorization_response_iss_parameter_supported`를 설정하지 않으면, 이 경우 Claude Code는 로그인을 실패합니다.
1401 1496
1402**수행할 작업:**1497**수행할 작업:**
1403 1498
1404* `/mcp`에서 로그인을 다시 시도합니다.1499* `/mcp`에서 로그인을 다시 시도합니다.
1405* 오류가 반복되면, 서버 운영자에게 보고합니다. 수정은 서버 측입니다: 인증 서버는 메타데이터에서 광고하는 것과 동일한 발급자를 `iss` 매개변수에서 반환해야 합니다.1500* 오류가 반복되면, 서버 운영자에게 보고합니다. 수정은 서버 측입니다: 인증 서버는 메타데이터에서 광고하는 것과 동일한 발급자를 `iss` 매개변수에서 반환해야 합니다.
1406* 서버가 수정되는 동안 연결하려면, [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 이 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 확인을 실행하지 않습니다. 이는 혼합 공격에 대한 보호를 제거하므로 서버 측 수정을 선호합니다.1501* 서버가 수정되는 동안 연결하려면, [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 해당 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 확인을 실행하지 않습니다. 이것은 혼합 공격에 대한 보호를 제거하므로 서버 측 수정을 선호합니다.
1407 1502
1408v2.1.232 이전에는 Claude Code가 점진적 롤아웃에서만 또는 `MCP_SDK_GENERATION=v2`를 설정할 때 v2 런타임을 사용했습니다.1503v2.1.232 이전에는 Claude Code가 점진적 롤아웃에서만 v2 런타임을 사용했거나 `MCP_SDK_GENERATION=v2`를 설정했을 때 사용했습니다.
1409 1504
1410<h3 id="aws-credentials-expired-or-invalid">1505<h3 id="aws-credentials-expired-or-invalid">
1411 AWS 자격증명이 만료되었거나 유효하지 않음1506 AWS 자격증명이 만료되었거나 유효하지 않습니다
1412</h3>1507</h3>
1413 1508
1414AWS 세션 토큰이 만료되었거나 거부되었습니다. 이 메시지는 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)의 401에 나타나며, 이는 해당 공급자가 만료된 보안 토큰을 보고하는 방법입니다.1509AWS 세션 토큰이 만료되었거나 거부되었습니다. 이 메시지는 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에서 401로 나타나며, 이는 해당 공급자가 만료된 보안 토큰을 보고하는 방식입니다.
1415 1510
1416중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `AWS credentials expired or invalid`입니다:1511중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `AWS credentials expired or invalid`입니다:
1417 1512
1423 1518
1424**수행할 작업:**1519**수행할 작업:**
1425 1520
1426* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1521* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1427* [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)가 설정되면, 메시지에서 이름을 지정한 명령(예: `aws sso login --profile myprofile`)을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 후 재시도합니다. 그렇지 않으면 직접 사용하는 AWS 자격증명을 새로 고칩니다: SSO 로그인, 액세스 키, API 키 또는 프록시 토큰1522* [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)가 설정되면, 메시지에서 이름을 지정한 명령(예: `aws sso login --profile myprofile`)을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 후 재시도합니다. 그렇지 않으면 사용하는 AWS 자격증명을 직접 새로 고칩니다: SSO 로그인, 액세스 키, API 키 또는 프록시 토큰입니다.
1428* 대화형 세션에서 `awsAuthRefresh`가 설정되면, 대신 `/login`을 실행하고, **3rd-party platform**을 선택한 후, **Using 3rd-party platforms** 아래에서 **Claude Platform on AWS · refresh credentials**를 선택하여 Claude Code를 다시 시작하지 않고 동일한 명령을 실행할 수 있습니다. [AWS 자격증명 구성](/docs/ko/claude-platform-on-aws#1-configure-aws-credentials)을 참조하십시오.1523* `awsAuthRefresh`가 대화형 세션에 설정되면, `/login`을 실행하고, **3rd-party platform**을 선택한 후, **Using 3rd-party platforms** 아래에서 **Claude Platform on AWS · refresh credentials**를 선택하여 Claude Code를 다시 시작하지 않고 동일한 명령을 실행할 수 있습니다. [AWS 자격증명 구성](/docs/ko/claude-platform-on-aws#1-configure-aws-credentials)을 참조합니다.
1429* 새로 고침 명령이 성공한 후 오류가 반복되면, 동일한 셸 및 프로필에서 `aws sts get-caller-identity`로 Claude Code 외부에서 ID가 유효한지 확인합니다.1524* 새로 고침 명령이 성공한 후에도 오류가 반복되면, 동일한 셸 및 프로필에서 `aws sts get-caller-identity`로 Claude Code 외부에서 ID가 유효한지 확인합니다.
1430 1525
1431<h3 id="aws-authentication-failed">1526<h3 id="aws-authentication-failed">
1432 AWS 인증 실패1527 AWS 인증 실패
1434 1529
1435AWS 공급자가 403을 반환했거나, [Amazon Bedrock](/docs/ko/amazon-bedrock)이 401을 반환했습니다.1530AWS 공급자가 403을 반환했거나, [Amazon Bedrock](/docs/ko/amazon-bedrock)이 401을 반환했습니다.
1436 1531
1437Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 403은 또한 누락된 IAM 권한과 같은 `AccessDeniedException`의 인증 거부를 보고하는 방법입니다. Claude Code는 이 두 원인을 구분할 수 없습니다.1532Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 403은 또한 누락된 IAM 권한과 같은 `AccessDeniedException`의 인증 거부를 보고하는 방식입니다. Claude Code는 이 두 원인을 구분할 수 없습니다.
1438 1533
1439Amazon Bedrock의 401은 또한 [AWS 자격증명이 만료되었거나 유효하지 않음](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. Amazon Bedrock이 만료된 토큰을 401로 보고하지 않기 때문입니다. 해당 엔드포인트의 401은 일반적으로 요청 경로의 다른 것(예: 회사 프록시)에서 옵니다.1534Amazon Bedrock의 401은 [AWS 자격증명이 만료되었거나 유효하지 않습니다](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. 해당 엔드포인트의 401은 일반적으로 요청 경로의 다른 것(예: 회사 프록시)에서 옵니다.
1440 1535
1441자격증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로, 메시지는 둘 다 제공합니다:1536자격증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로, 메시지는 둘 다 제공합니다:
1442 1537
1452 1547
1453**수행할 작업:**1548**수행할 작업:**
1454 1549
1455* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1550* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1456* 만료된 자격증명이 원인일 수 있으므로 AWS 자격증명을 새로 고칩니다: 설정되면 [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)에서 이름을 지정한 명령을 실행하거나, SSO 로그인, 액세스 키, API 키 또는 프록시 토큰을 직접 새로 고칩니다.1551* 만료된 자격증명이 원인일 수 있으므로 AWS 자격증명을 새로 고칩니다: 설정되면 [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)에서 이름을 지정한 명령을 실행하거나, SSO 로그인, 액세스 키, API 키 또는 프록시 토큰을 직접 새로 고칩니다.
1457* 자격증명이 최신이면, [IAM 구성](/docs/ko/amazon-bedrock#iam-configuration)의 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.1552* 자격증명이 현재이면, [IAM 구성](/docs/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.
1458* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.1553* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.
1459 1554
1460<h3 id="google-cloud-credentials-expired-or-invalid">1555<h3 id="google-cloud-credentials-expired-or-invalid">
1461 Google Cloud 자격증명이 만료되었거나 유효하지 않음1556 Google Cloud 자격증명이 만료되었거나 유효하지 않습니다
1462</h3>1557</h3>
1463 1558
1464[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)의 Google Cloud 자격증명이 만료되었거나 거부되었습니다: 요청이 401을 반환했으며, 이는 Agent Platform이 자격증명 만료를 보고하는 방법입니다.1559[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)에 대한 Google Cloud 자격증명이 만료되었거나 거부되었습니다: 요청이 401을 반환했으며, 이는 Agent Platform이 자격증명 만료를 보고하는 방식입니다.
1465 1560
1466중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud credentials expired or invalid`입니다:1561중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud credentials expired or invalid`입니다:
1467 1562
1471 1566
1472**수행할 작업:**1567**수행할 작업:**
1473 1568
1474* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1569* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1475* 애플리케이션 기본 자격증명으로 인증하면, 메시지에서 이름을 지정한 [`gcpAuthRefresh`](/docs/ko/google-vertex-ai#advanced-credential-configuration) 명령 또는 `gcloud auth application-default login`을 실행하고 로그인을 완료한 후 재시도합니다.1570* 애플리케이션 기본 자격증명으로 인증하면, 메시지에서 이름을 지정한 [`gcpAuthRefresh`](/docs/ko/google-vertex-ai#advanced-credential-configuration) 명령을 실행하거나, `gcloud auth application-default login`을 실행하고 로그인을 완료한 후 재시도합니다.
1476* `CLAUDE_CODE_SKIP_VERTEX_AUTH`가 설정된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅하면, `ANTHROPIC_AUTH_TOKEN` 또는 `ANTHROPIC_CUSTOM_HEADERS`의 게이트웨이 토큰을 새로 고친 후 재시도합니다.1571* `CLAUDE_CODE_SKIP_VERTEX_AUTH`가 설정된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 라우팅하면, `ANTHROPIC_AUTH_TOKEN` 또는 `ANTHROPIC_CUSTOM_HEADERS`의 게이트웨이 토큰을 새로 고친 후 재시도합니다.
1477* 서비스 계정 키 파일로 인증하면, `GOOGLE_APPLICATION_CREDENTIALS`가 유효한 키를 가리키는지 확인합니다. [GCP 자격증명 구성](/docs/ko/google-vertex-ai#3-configure-gcp-credentials)을 참조하십시오.1572* 서비스 계정 키 파일로 인증하면, `GOOGLE_APPLICATION_CREDENTIALS`가 유효한 키를 가리키는지 확인합니다. [GCP 자격증명 구성](/docs/ko/google-vertex-ai#3-configure-gcp-credentials)을 참조합니다.
1478* 새로 고침 후 오류가 반복되면, 동일한 셸에서 `gcloud auth application-default print-access-token`으로 Claude Code 외부에서 ID가 작동하는지 확인합니다.1573* 새로 고침 후에도 오류가 반복되면, 동일한 셸에서 `gcloud auth application-default print-access-token`으로 Claude Code 외부에서 ID가 작동하는지 확인합니다.
1479 1574
1480v2.1.273 이전에는 Agent Platform의 401이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, Google Cloud 자격증명을 새로 고칠 수 없습니다.1575v2.1.273 이전에는 Agent Platform의 401이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.
1481 1576
1482<h3 id="google-cloud-authentication-failed">1577<h3 id="google-cloud-authentication-failed">
1483 Google Cloud 인증 실패1578 Google Cloud 인증 실패
1484</h3>1579</h3>
1485 1580
1486[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)이 403을 반환했으며, 이는 만료된 자격증명이 아닌 인증 거부에 사용합니다. 일반적으로 인증하는 ID에 IAM 권한이 누락되었거나 모델이 프로젝트에 대해 활성화되지 않았습니다.1581[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)이 403을 반환했으며, 이는 만료된 자격증명이 아닌 인증 거부에 사용합니다. 일반적으로 인증하는 ID에 IAM 권한이 부족하거나, 모델이 프로젝트에 대해 활성화되지 않았습니다.
1487 1582
1488중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud authentication failed`입니다:1583중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud authentication failed`입니다:
1489 1584
1493 1588
1494**수행할 작업:**1589**수행할 작업:**
1495 1590
1496* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1591* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1497* [IAM 구성](/docs/ko/google-vertex-ai#iam-configuration)의 역할이 인증하는 ID에 부여되었는지 확인합니다.1592* [IAM 구성](/docs/ko/google-vertex-ai#iam-configuration)의 역할이 인증하는 ID에 부여되어 있는지 확인합니다.
1498* 모델이 프로젝트에 대해 활성화되었는지 확인합니다. [모델 액세스 요청](/docs/ko/google-vertex-ai#2-request-model-access)을 참조하십시오.1593* 모델이 프로젝트에 대해 활성화되어 있는지 확인합니다. [모델 액세스 요청](/docs/ko/google-vertex-ai#2-request-model-access)을 참조합니다.
1499 1594
1500v2.1.273 이전에는 Agent Platform의 403이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, Google Cloud 자격증명을 새로 고칠 수 없습니다.1595v2.1.273 이전에는 Agent Platform의 403이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.
1501 1596
1502<h3 id="microsoft-foundry-authentication-failed">1597<h3 id="microsoft-foundry-authentication-failed">
1503 Microsoft Foundry 인증 실패1598 Microsoft Foundry 인증 실패
1511 1606
1512**수행할 작업:**1607**수행할 작업:**
1513 1608
1514* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1609* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1515* [Azure 자격증명 구성](/docs/ko/microsoft-foundry#2-configure-azure-credentials)에서 구성한 자격증명을 새로 고칩니다: `ANTHROPIC_FOUNDRY_API_KEY`를 회전하거나, 새 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`을 발급하거나, `az login`을 실행하여 기본 Microsoft Entra 자격증명 체인이 다시 로그인할 수 있도록 합니다.1610* [Azure 자격증명 구성](/docs/ko/microsoft-foundry#2-configure-azure-credentials)에서 구성한 자격증명을 새로 고칩니다: `ANTHROPIC_FOUNDRY_API_KEY`를 회전하거나, 새 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`을 발급하거나, `az login`을 실행하여 기본 Microsoft Entra 자격증명 체인이 다시 로그인할 수 있도록 합니다.
1516* 자격증명이 최신이면, ID가 Foundry 리소스에 액세스할 수 있는지 확인합니다. [Azure RBAC 구성](/docs/ko/microsoft-foundry#azure-rbac-configuration)을 참조하십시오.1611* 자격증명이 현재이면, ID가 Foundry 리소스에 액세스할 수 있는지 확인합니다. [Azure RBAC 구성](/docs/ko/microsoft-foundry#azure-rbac-configuration)을 참조합니다.
1517 1612
1518v2.1.273 이전에는 Microsoft Foundry의 401 또는 403이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, Azure 자격증명을 새로 고칠 수 없습니다.1613v2.1.273 이전에는 Microsoft Foundry의 401 또는 403이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.
1519 1614
1520<h3 id="could-not-load-aws-or-google-cloud-credentials">1615<h3 id="could-not-load-aws-or-google-cloud-credentials">
1521 AWS 또는 Google Cloud 자격증명을 로드할 수 없음1616 AWS 또는 Google Cloud 자격증명을 로드할 수 없습니다
1522</h3>1617</h3>
1523 1618
1524Claude Code가 실행되는 머신의 AWS 자격증명 공급자 체인 또는 Google 애플리케이션 기본 자격증명에서 사용 가능한 자격증명을 얻을 수 없으므로, 클라우드 공급자에 도달한 요청이 없습니다. Claude Code는 캐시된 자격증명을 지우고 이 메시지를 표시하기 전에 두 번 재시도합니다. `·` 이후의 세부 정보는 만료된 SSO 세션, `Could not load the default credentials`로 보고된 누락된 애플리케이션 기본 자격증명 또는 `invalid_grant`로 보고된 취소된 로그인과 같은 특정 원인의 이름을 지정합니다:1619Claude Code가 AWS 자격증명 공급자 체인 또는 머신의 Google 애플리케이션 기본 자격증명에서 사용 가능한 자격증명을 얻을 수 없어서, 요청이 클라우드 공급자에 도달하지 않았습니다. Claude Code는 캐시된 자격증명을 지우고 표시하기 전에 두 번 재시도합니다. `·` 이후의 세부 정보는 만료된 SSO 세션, `Could not load the default credentials`로 보고된 누락된 애플리케이션 기본 자격증명 또는 `invalid_grant`로 보고된 취소된 로그인과 같은 특정 원인의 이름을 지정합니다:
1525 1620
1526```text theme={null}1621```text theme={null}
1527API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.1622API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.
1528API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.1623API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.
1529```1624```
1530 1625
1531[비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하고 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `cloud_credential_error`입니다. v2.1.267 이전에는 메시지가 `API Error:` 이후의 세부 정보 텍스트만 표시했고, 구조화된 코드는 `server_error` 또는 `unknown`이었습니다.1626[비대화형 모드](/docs/ko/headless)에서 `-p`와 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `cloud_credential_error`입니다. v2.1.267 이전에는 메시지가 `API Error:` 이후의 세부 정보만 표시했으며, 구조화된 코드는 `server_error` 또는 `unknown`이었습니다.
1532 1627
1533**수행할 작업:**1628**수행할 작업:**
1534 1629
1535* `aws sso login --profile myprofile` 또는 `gcloud auth application-default login`과 같은 공급자의 로그인 명령을 실행한 후 재시도합니다. [Bedrock, Agent Platform 또는 Foundry 자격증명이 로드되지 않음](/docs/ko/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading)은 Claude Code 외부에서 자격증명을 확인하는 방법을 보여줍니다.1630* `aws sso login --profile myprofile` 또는 `gcloud auth application-default login`과 같은 공급자의 로그인 명령을 실행한 후 재시도합니다. [Bedrock, Agent Platform 또는 Foundry 자격증명이 로드되지 않음](/docs/ko/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading)은 Claude Code 외부에서 자격증명을 확인하는 방법을 보여줍니다.
1536* 세부 정보가 `AWS default-chain credential resolve timed out`을 읽으면, 체인이 실패하지 않고 중단되었으므로, 대신 [AWS 기본 체인 자격증명 확인 시간 초과](#aws-default-chain-credential-resolve-timed-out)를 따릅니다.1631* 세부 정보가 `AWS default-chain credential resolve timed out`을 읽으면, 체인이 실패하지 않고 중단되었으므로, 대신 [AWS default-chain credential resolve timed out](#aws-default-chain-credential-resolve-timed-out)을 따릅니다.
1537 1632
1538<h3 id="aws-default-chain-credential-resolve-timed-out">1633<h3 id="aws-default-chain-credential-resolve-timed-out">
1539 AWS 기본 체인 자격증명 확인 시간 초과1634 AWS default-chain credential resolve timed out
1540</h3>1635</h3>
1541 1636
1542AWS 기본 자격증명 공급자 체인이 60초 내에 자격증명을 생성하지 않았으므로, Claude Code가 확인을 중지하고 요청을 실패했습니다. 이 시간 초과는 [AWS 또는 Google Cloud 자격증명을 로드할 수 없음](#could-not-load-aws-or-google-cloud-credentials)의 한 원인입니다. 실패는 로컬 자격증명 확인입니다: 요청이 [Amazon Bedrock](/docs/ko/amazon-bedrock), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에 도달하지 않았습니다. Claude Code는 이 오류가 표시되기 전에 반복된 시도에서 [자격증명 캐시](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)를 지우고 재시도하므로, 이 시점에서 체인이 반복된 시도에서 중단되었습니다.1637AWS 기본 자격증명 공급자 체인이 60초 내에 자격증명을 생성하지 않아서, Claude Code가 확인을 중지하고 요청을 실패했습니다. 이 시간 초과는 [AWS 또는 Google Cloud 자격증명을 로드할 수 없습니다](#could-not-load-aws-or-google-cloud-credentials)의 한 원인입니다. 실패는 로컬 자격증명 확인입니다: 요청이 [Amazon Bedrock](/docs/ko/amazon-bedrock), [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에 도달하지 않았습니다. Claude Code는 [자격증명 캐시](/docs/ko/amazon-bedrock#credential-caching-and-resolution-timeout)를 지우고 이 오류가 표시되기 전에 재시도하므로, 이를 볼 때쯤 체인이 반복된 시도에서 중단되었습니다.
1543 1638
1544```text theme={null}1639```text theme={null}
1545API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.1640API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.
1548일반적인 원인은 AWS 프로필의 `credential_process` 명령이 받을 수 없는 입력을 기다리고 있으며, 컨테이너 또는 VM의 인스턴스 메타데이터 서비스(IMDS)가 체인의 프로브에 응답하지 않습니다.1643일반적인 원인은 AWS 프로필의 `credential_process` 명령이 받을 수 없는 입력을 기다리고 있으며, 컨테이너 또는 VM의 인스턴스 메타데이터 서비스(IMDS)가 체인의 프로브에 응답하지 않습니다.
1549 1644
1550v2.1.267 이전에는 메시지가 `API Error: AWS default-chain credential resolve timed out`을 읽었습니다.1645v2.1.267 이전에는 메시지가 `API Error: AWS default-chain credential resolve timed out`을 읽었습니다.
1551v2.1.207 이전에는 중단된 체인이 요청을 무한정 기다리게 했습니다.1646v2.1.207 이전에는 중단된 체인이 실패하는 대신 요청을 무한정 기다리게 했습니다.
1552 1647
1553**수행할 작업:**1648**수행할 작업:**
1554 1649
1555* 동일한 셸에서 동일한 `AWS_PROFILE`로 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 프로필을 수정합니다. 대화형으로 프롬프트하는 `credential_process` 명령이 일반적인 원인입니다.1650* 동일한 셸에서 동일한 `AWS_PROFILE`로 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 프로필을 수정합니다. 대화형으로 프롬프트하는 `credential_process` 명령이 일반적인 원인입니다.
1556* Claude Code를 시작하기 전에 로그인 단계를 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행하여 체인이 로컬 SSO 캐시에서 확인되도록 합니다.1651* Claude Code를 시작하기 전에 로그인 단계를 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행하여 체인이 브라우저 흐름을 기다리는 대신 로컬 SSO 캐시에서 확인되도록 합니다.
1557* 체인이 `aws-vault`와 같은 래퍼를 통한 MFA를 사용하는 SSO와 같이 60초 이상 필요로 하는 대화형 로그인을 실행하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.1652* 체인이 `aws-vault`와 같은 래퍼를 통해 MFA가 있는 SSO와 같이 60초 이상 필요로 하는 대화형 로그인을 실행하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.
1558 1653
1559<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">1654<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">
1560 Bedrock 설정 확인이 AWS를 기다리다가 시간 초과됨1655 Bedrock 설정 확인이 AWS를 기다리다가 시간 초과되었습니다
1561</h3>1656</h3>
1562 1657
1563[Bedrock 설정 마법사](/docs/ko/amazon-bedrock#sign-in-with-bedrock)의 자격증명 확인 중 AWS 호출(예: 자격증명 조회 또는 ID 확인)이 60초 제한 내에 완료되지 않았습니다. 마법사가 기다리기를 중지하고 확인 단계를 실패합니다:1658[Bedrock 설정 마법사](/docs/ko/amazon-bedrock#sign-in-with-bedrock)의 자격증명 확인 중 AWS에 대한 호출(예: 자격증명 조회 또는 ID 확인)이 60초 제한 내에 완료되지 않았습니다. 마법사가 기다리기를 중지하고 확인 단계를 실패합니다:
1564 1659
1565```text theme={null}1660```text theme={null}
1566Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.1661Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.
1568 1663
1569숫자는 제한을 반영합니다: 기본적으로 60초 또는 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 설정한 값입니다.1664숫자는 제한을 반영합니다: 기본적으로 60초 또는 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 설정한 값입니다.
1570 1665
1571일반적인 원인은 AWS에 대한 요청을 중단하는 네트워크 또는 프록시(SSO 토큰 새로 고침 포함) 및 입력을 기다리는 자격증명 헬퍼입니다. 헬퍼가 합법적으로 더 많은 시간이 필요한 경우에만 제한을 높입니다.1666일반적인 원인은 SSO 토큰 새로 고침을 포함하여 AWS에 대한 요청을 중단하는 네트워크 또는 프록시이며, 자격증명 헬퍼가 볼 수 없는 입력을 기다리고 있습니다. 헬퍼가 합법적으로 더 많은 시간이 필요할 때만 제한을 높입니다.
1572 1667
1573AWS에 대한 단일 중단된 요청도 자체 요청별 시간 초과에서 실패할 수 있으며, 동일한 단계에서 더 짧은 메시지를 표시합니다:1668AWS에 대한 단일 중단된 요청도 자체 요청별 시간 초과로 실패할 수 있으며, 동일한 단계에서 더 짧은 메시지를 표시합니다:
1574 1669
1575```text theme={null}1670```text theme={null}
1576A request to AWS timed out. Check your network and proxy settings, then try again.1671A request to AWS timed out. Check your network and proxy settings, then try again.
1577```1672```
1578 1673
1579동일한 시간 초과가 모델 핀 단계에서 발생하면, 마법사는 모델을 `unreachable`로 표시하는 대신 두 메시지 중 하나를 표시합니다.1674동일한 시간 초과가 모델 핀 단계에서 발생하면, 마법사가 메시지를 표시하는 대신 모델을 `unreachable`로 표시합니다.
1580 1675
1581**수행할 작업:**1676**수행할 작업:**
1582 1677
1583* 동일한 셸에서 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 중단이 Claude Code 외부에 있습니다. 네트워크, 프록시 또는 AWS 프로필의 자격증명 헬퍼에서 먼저 수정합니다.1678* 동일한 셸에서 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 중단이 Claude Code 외부에 있습니다. 네트워크, 프록시 또는 AWS 프로필의 자격증명 헬퍼에서 먼저 수정합니다.
1584* 마법사를 열기 전에 대화형 로그인을 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행합니다.1679* 마법사를 열기 전에 대화형 로그인을 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행합니다.
1585* AWS 프로필의 자격증명 헬퍼가 합법적으로 60초 이상 필요하여 프롬프트하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.1680* AWS 프로필의 자격증명 헬퍼가 합법적으로 60초 이상 프롬프트를 기다려야 하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.
1586 1681
1587<h3 id="cloud-gateway-session-expired">1682<h3 id="cloud-gateway-session-expired">
1588 클라우드 게이트웨이 세션 만료됨1683 클라우드 게이트웨이 세션 만료됨
1589</h3>1684</h3>
1590 1685
1591[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했고, 이 머신에 저장된 게이트웨이 세션이 만료되었고 갱신할 수 없거나, 게이트웨이가 더 이상 수락하지 않습니다. 예를 들어 게이트웨이의 [JWT 비밀이 교체된](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation) 후입니다. 대화형으로 `claude`를 시작할 때 이 라인이 표시되면, 세션이 게이트웨이에서 로그아웃된 상태로 열렸습니다:1686[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했으며, 이 머신에 저장된 게이트웨이 세션이 만료되었으며 갱신할 수 없거나, 게이트웨이가 더 이상 수락하지 않습니다. 예를 들어 게이트웨이의 [JWT 비밀이 교체된](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation) 후입니다. 대화형으로 `claude`를 시작할 때 이 라인을 보면, 세션이 게이트웨이에서 로그아웃된 상태로 열렸습니다:
1592 1687
1593```text theme={null}1688```text theme={null}
1594Cloud gateway session expired — run /login to reconnect.1689Cloud gateway session expired — run /login to reconnect.
1595```1690```
1596 1691
1597동일한 라인은 게이트웨이 자격증명이 만료되고 Claude Code가 갱신할 수 없을 때 세션 중에 나타날 수 있습니다.1692동일한 라인이 게이트웨이 자격증명이 만료되고 Claude Code가 갱신할 수 없을 때 세션 중에 나타날 수 있습니다.
1598 1693
1599[비대화형](/docs/ko/headless) 실행, 백그라운드 또는 기타 무인 세션 또는 `claude auth` 이외의 `claude` 하위 명령에서, 게이트웨이가 더 이상 세션을 수락하지 않으면 Claude Code는 대신 이 메시지로 종료됩니다:1694[비대화형](/docs/ko/headless) 실행, 백그라운드 또는 기타 무인 세션 또는 `claude auth` 이외의 `claude` 하위 명령에서, Claude Code는 게이트웨이가 더 이상 세션을 수락하지 않을 때 대신 이 메시지로 종료됩니다:
1600 1695
1601```text theme={null}1696```text theme={null}
1602Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.1697Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.
1608* 비대화형 실행의 경우, 동일한 환경에서 `claude`를 시작하고, `/login`을 실행한 후 명령을 다시 실행합니다.1703* 비대화형 실행의 경우, 동일한 환경에서 `claude`를 시작하고, `/login`을 실행한 후 명령을 다시 실행합니다.
1609 1704
1610<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">1705<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">
1611 로그인 시간 초과 중 계속 대기1706 로그인이 계속하기를 기다리다가 시간 초과되었습니다
1612</h3>1707</h3>
1613 1708
1614[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 로그인 중에 게이트웨이가 로그인한 계정의 이름을 지정했고, Claude Code가 저장하기 전에 확인하도록 요청했습니다. 로그인의 자체 만료를 지나 확인을 열어 두었고, 게이트웨이가 새로 고침 토큰을 발급하지 않았으므로, Claude Code는 계속할 때 아무것도 저장하지 않았습니다:1709[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway) 로그인 중에 게이트웨이가 로그인한 계정의 이름을 지정했으며, Claude Code가 자격증명을 저장하기 전에 확인하도록 요청했습니다. 로그인 자신의 만료를 지나 확인을 열어 두었으며, 게이트웨이가 갱신할 수 있는 새로 고침 토큰을 발급하지 않았으므로, Claude Code가 계속할 때 아무것도 저장하지 않았습니다:
1615 1710
1616```text theme={null}1711```text theme={null}
1617Sign-in timed out while waiting for you to continue. Try again.1712Sign-in timed out while waiting for you to continue. Try again.
1622* `/login`을 다시 실행하고 로그인이 만료되기 전에 계정을 확인합니다.1717* `/login`을 다시 실행하고 로그인이 만료되기 전에 계정을 확인합니다.
1623 1718
1624<h3 id="gateway-refused-the-request">1719<h3 id="gateway-refused-the-request">
1625 게이트웨이가 요청을 거부함1720 게이트웨이가 요청을 거부했습니다
1626</h3>1721</h3>
1627 1722
1628[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했고, 요청이 403을 반환했습니다: 게이트웨이 또는 뒤의 업스트림이 거부했습니다. 다시 로그인하면 거부가 변경되지 않으므로, 메시지는 게이트웨이 관리자를 가리킵니다:1723[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했으며, 요청이 403을 반환했습니다: 게이트웨이 또는 뒤의 업스트림이 거부했습니다. 다시 로그인하면 거부가 변경되지 않으므로, 메시지는 게이트웨이 관리자를 가리킵니다:
1629 1724
1630```text theme={null}1725```text theme={null}
1631Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...1726Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...
1634**수행할 작업:**1729**수행할 작업:**
1635 1730
1636* 게이트웨이 관리자에게 요청을 조회하도록 요청합니다. `API Error:` 꼬리는 게이트웨이가 반환한 거부를 전달합니다.1731* 게이트웨이 관리자에게 요청을 조회하도록 요청합니다. `API Error:` 꼬리는 게이트웨이가 반환한 거부를 전달합니다.
1637* 관리자의 경우: 게이트웨이의 [액세스 제어 규칙](/docs/ko/claude-apps-gateway-config#http-tuning)이 [감사 로그](/docs/ko/claude-apps-gateway-deploy#logs)가 이유와 함께 기록하는 403을 반환하고, 업스트림의 인증 거부는 [업스트림 오류 메시지](/docs/ko/claude-apps-gateway-config#upstream-error-messages)에 따라 통과합니다.1732* 관리자의 경우: 게이트웨이의 [액세스 제어 규칙](/docs/ko/claude-apps-gateway-config#http-tuning)이 [감사 로그](/docs/ko/claude-apps-gateway-deploy#logs)가 이유와 함께 기록하는 403을 반환하며, 업스트림의 인증 거부는 [업스트림 오류 메시지](/docs/ko/claude-apps-gateway-config#upstream-error-messages)에 따라 통과합니다.
1638 1733
1639v2.1.273 이전에는 게이트웨이 세션의 403이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했고, 다시 로그인해도 거부가 지워지지 않았습니다.1734v2.1.273 이전에는 게이트웨이 세션의 403이 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, 다시 로그인해도 거부가 지워지지 않았습니다.
1640 1735
1641<h2 id="network-and-connection-errors">1736<h2 id="network-and-connection-errors">
1642 네트워크 및 연결 오류1737 네트워크 및 연결 오류
1677 1772
1678`curl`이 성공하지만 Claude Code가 여전히 실패하는 경우, 원인은 일반적으로 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다:1773`curl`이 성공하지만 Claude Code가 여전히 실패하는 경우, 원인은 일반적으로 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다:
1679 1774
1775* `ANTHROPIC_BASE_URL`이 설정되어 있는지 `echo $ANTHROPIC_BASE_URL`을 실행하여 확인하거나, PowerShell에서 `echo $env:ANTHROPIC_BASE_URL`을 실행하고 [설정 파일](/docs/ko/settings)의 `env` 블록에서 찾습니다. 설정되면 Claude Code는 모델 요청을 `api.anthropic.com` 대신 해당 주소로 보내므로, 더 이상 실행되지 않는 로컬 프록시 또는 게이트웨이를 가리키는 남은 값은 `curl`이 API에 도달하더라도 `Connection refused`를 생성합니다. 셸 프로필 또는 설정에서 제거하고 새 터미널에서 Claude Code를 시작합니다.
1680* Linux 및 WSL에서 `/etc/resolv.conf`에서 도달할 수 없는 네임서버를 확인합니다. 특히 WSL은 호스트에서 손상된 리졸버를 상속할 수 있습니다.1776* Linux 및 WSL에서 `/etc/resolv.conf`에서 도달할 수 없는 네임서버를 확인합니다. 특히 WSL은 호스트에서 손상된 리졸버를 상속할 수 있습니다.
1681* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.1777* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.
1682* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 배제하기 위해 종료하고 다시 시도합니다.1778* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 배제하기 위해 종료하고 다시 시도합니다.
1897* `claude --remote-control`로 새 세션을 시작하여 새 Remote Control 세션을 만듭니다.1993* `claude --remote-control`로 새 세션을 시작하여 새 Remote Control 세션을 만듭니다.
1898* 다른 Remote Control 시작 메시지는 [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조합니다.1994* 다른 Remote Control 시작 메시지는 [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조합니다.
1899 1995
1900서버가 대신 이전 세션이 없다고 보고하면 이 메시지가 표시되지 않습니다. Claude Code는 [대화의 재연결 기록](/docs/ko/remote-control#resume-outcomes)에 따라 새 세션을 시작하거나 [`Previous session is unavailable — run /remote-control to start a new one`](/docs/ko/remote-control#previous-session-is-unavailable)을 표시합니다. v2.1.227부터 v2.1.231까지 Claude Code는 `Remote Control could not resume the previous session under the current login`으로 시작하는 메시지를 표시했으며, [이전 버전은 다시 다르게 작동했습니다](/docs/ko/remote-control#reconnect-history).1996서버가 대신 이전 세션이 없다고 보고하면 이 메시지가 표시되지 않습니다. Claude Code는 새 세션을 시작하거나 [`Previous session is unavailable — run /remote-control to start a new one`](/docs/ko/remote-control#previous-session-is-unavailable)을 표시합니다.
1901 1997
1902<h3 id="sessions-ended-while-this-machine-was-offline">1998<h3 id="sessions-ended-while-this-machine-was-offline">
1903 이 머신이 오프라인 상태인 동안 세션이 종료됨1999 이 머신이 오프라인 상태인 동안 세션이 종료됨
1931* `/feedback`을 실행하여 발생한 상황에 대한 설명과 함께 트랜스크립트를 보냅니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조합니다.2027* `/feedback`을 실행하여 발생한 상황에 대한 설명과 함께 트랜스크립트를 보냅니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조합니다.
1932* 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.2028* 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.
1933 2029
2030<h3 id="couldnt-send-feedback">
2031 피드백을 보낼 수 없습니다
2032</h3>
2033
2034[`/feedback`, `/bug`, 또는 `/share` 대화](/docs/ko/commands#all-commands)에서 보고서를 보냈고 Anthropic으로의 업로드가 실패했습니다. 대화는 텍스트를 유지하므로 다시 시도할 수 있습니다.
2035
2036```text theme={null}
2037Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.
2038```
2039
2040접두사 뒤의 텍스트는 실패한 것을 명시합니다:
2041
2042* **`: not signed in. Run /login, then retry.`**: 대화는 Claude Code가 열릴 때 Anthropic 자격 증명을 찾았을 때만 업로드되며, 보낼 때까지 사용 가능한 것이 없었습니다. 예를 들어, 그 사이에 이 머신에서 로그아웃했거나, 로그인을 더 이상 새로 고칠 수 없었습니다.
2043* **괄호 안의 내용**: `(server returned <status>)`는 서비스의 응답 코드입니다. `(request timed out)` 및 `(couldn't reach the service)`는 네트워크 실패입니다. Claude Code가 이유를 명시할 수 없으면 괄호 안의 내용이 없습니다.
2044
2045[피드백 초안 큐](/docs/ko/tools-reference#sendfeedback-tool-behavior)에서 동일한 실패는 `The draft is still queued. Try again later.`로 끝나며, 초안은 다른 시도를 위해 큐에 남아 있습니다.
2046
2047**수행할 작업:**
2048
2049* 서명되지 않은 표현의 경우, `/login`을 실행하고 다시 보냅니다.
2050* 그 외의 경우, 다시 보냅니다. 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.
2051* 계속 실패하면 메시지가 말하는 대로 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 보고서를 제출합니다.
2052
2053v2.1.281 이전에는 Remote Control **중지** 또는 긴급 교차 세션 메시지가 대화가 열려 있는 동안 도착했을 때 모든 전송이 이 메시지로 실패했습니다. 이러한 버전에서는 대화를 닫고, 다시 열고, 다시 보냅니다.
2054
2055***
2056
2057title: "요청 오류"
2058description: "요청 내용과 관련된 오류 및 해결 방법"
2059------------------------------------
2060
1934<h2 id="request-errors">2061<h2 id="request-errors">
1935 요청 오류2062 요청 오류
1936</h2>2063</h2>
1953Context limit reached · /compact or /clear to continue2080Context limit reached · /compact or /clear to continue
1954```2081```
1955 2082
1956[`DISABLE_COMPACT`](/docs/ko/env-vars)가 설정된 경우에만 줄에 `/clear`만 표시됩니다. 아래의 압축 실패 형식과 같은 더 긴 오류 형식은 `Prompt is too long ·` 표현을 유지합니다. `-p` 출력 및 기록에서 텍스트는 `Prompt is too long`으로 유지됩니다.2083[`DISABLE_COMPACT`](/docs/ko/env-vars)가 설정된 경우에만 `/clear`를 표시합니다. 아래의 압축 실패 형식과 같은 더 긴 오류 형식은 `Prompt is too long ·` 표현을 유지합니다. `-p` 출력 및 기록에서 텍스트는 `Prompt is too long`으로 유지됩니다.
1957 2084
1958[사용자 설정](/docs/ko/settings-reference#autocompactenabled)에서 자동 압축을 끈 경우, 줄에도 다음과 같이 표시됩니다:2085[사용자 설정](/docs/ko/settings-reference#autocompactenabled)에서 자동 압축을 끈 경우, 이 줄은 다음과 같이 표시됩니다:
1959 2086
1960```text theme={null}2087```text theme={null}
1961Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on2088Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on
1962```2089```
1963 2090
1964`/config`의 **Auto-compact** 토글은 사용자 설정에 `autoCompactEnabled`를 씁니다. 힌트는 `/config` 변경이 적용될 때만 나타납니다. 예를 들어, [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](/docs/ko/env-vars)가 자동 압축을 끈 경우에는 나타나지 않습니다. 또한 프로젝트 또는 관리 설정과 같은 더 높은 우선순위 범위가 `autoCompactEnabled`를 `false`로 설정한 경우에도 나타나지 않습니다. v2.1.235 이전에는 줄에 자동 압축 힌트가 없었습니다.2091`/config`의 **자동 압축** 토글은 사용자 설정에 `autoCompactEnabled`를 씁니다. 이 힌트는 `/config` 변경이 적용될 때만 나타납니다. 예를 들어, [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](/docs/ko/env-vars)가 자동 압축을 끈 경우에는 나타나지 않습니다. 또한 프로젝트 또는 관리 설정과 같은 더 높은 우선순위 범위가 `autoCompactEnabled`를 `false`로 설정한 경우에도 나타나지 않습니다. v2.1.235 이전에는 이 줄에 자동 압축 힌트가 없었습니다.
1965 2092
1966Amazon Bedrock은 이 조건을 `Input is too long for requested model.`로 보고하며, Claude Code는 동일한 방식으로 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock 표현을 인식하지 못했으므로 자동 압축이 트리거되지 않았고 `/compact`는 동일한 오류로 실패했습니다.2093Amazon Bedrock은 이 조건을 `Input is too long for requested model.`로 보고하며, Claude Code는 동일한 방식으로 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock 표현을 인식하지 못했으므로 자동 압축이 트리거되지 않았고 `/compact`는 동일한 오류로 실패했습니다.
1967 2094
1968[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가 토큰을 인식하지 못했으므로 자동 압축이 트리거되지 않았습니다.2095[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가 토큰을 인식하지 못했으므로 자동 압축이 트리거되지 않았습니다.
1969 2096
1970자동 압축이 이 턴에서 실행되었지만 사용할 수 없는 모델 또는 인증 실패와 같은 기본 오류에서 실패한 경우, 메시지는 구분 기호 뒤에 해당 오류를 이름으로 지정합니다:2097자동 압축이 이 턴에서 실행되었지만 사용할 수 없는 모델 또는 인증 실패와 같은 기본 오류로 실패한 경우, 메시지는 구분자 뒤에 해당 오류를 표시합니다:
1971 2098
1972```text theme={null}2099```text theme={null}
1973Prompt is too long · automatic compaction failed: <the underlying error>2100Prompt is too long · automatic compaction failed: <the underlying error>
1974```2101```
1975 2102
1976명명된 오류를 먼저 해결하십시오. `/compact`는 해결할 때까지 동일한 오류로 실패합니다. v2.1.229 이전에는 실패한 자동 압축이 원인 없이 `Prompt is too long`을 표시했습니다.2103명명된 오류를 먼저 해결하십시오. 해결할 때까지 `/compact`는 동일한 오류로 실패합니다. v2.1.229 이전에는 실패한 자동 압축이 원인 없이 `Prompt is too long`을 표시했습니다.
1977 2104
1978자동 압축이 이 오류에서 실행될 때, 일반적으로 가장 오래된 교환을 요약하고 가장 최신의 것을 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다:2105자동 압축이 이 오류에서 실행될 때, 일반적으로 가장 오래된 교환을 요약하고 가장 최신 교환을 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다:
1979 2106
1980* 전체 교환을 요약할 수 없을 때, Claude Code는 가장 최신 프롬프트를 그대로 유지하고 그 이전의 모든 것을 요약합니다.2107* 전체 교환을 요약할 수 없는 경우, Claude Code는 가장 최신 프롬프트를 그대로 유지하고 그 이전의 모든 것을 요약합니다.
1981* 그 경우, 대화가 프롬프트로 끝나지 않으면 Claude Code는 전체 대화를 대신 요약합니다.2108* 이 경우, 대화가 프롬프트로 끝나지 않으면 Claude Code는 전체 대화를 대신 요약합니다.
1982 2109
1983Claude Code는 전달할 내용이 모델 응답을 보유하지 않고 짧은 재시도와 같은 약 1,000개 토큰 미만의 자신의 텍스트를 보유할 때 이 복구를 건너뜁니다. `/clear`를 실행하여 새로 시작합니다. v2.1.269 이전에는 전체 교환을 요약할 수 없을 때마다 압축이 실패했으므로 이 상태의 세션은 모든 턴에서 이 오류를 다시 맞았습니다.2110Claude Code는 전달할 내용이 모델 응답을 포함하지 않고 짧은 재시도와 같은 약 1,000개 토큰 미만의 자신의 텍스트를 포함하는 경우 이 복구를 건너뜁니다. `/clear`를 실행하여 새로 시작하십시오. v2.1.269 이전에는 전체 교환을 요약할 수 없을 때마다 압축이 실패했으므로 이 상태의 세션은 매 턴마다 이 오류를 다시 만났습니다.
1984 2111
1985단일 교환 대화에는 요약할 이전 턴이 없습니다. 자동 압축이 하나에서 실행되었을 때, Claude Code는 시도를 건너뛰고 요청을 채우는 것을 설명합니다. API가 오류에서 토큰 수를 보고하지 않으면 메시지는 다음과 같이 읽힙니다:2112단일 교환 대화에는 요약할 이전 턴이 없습니다. 자동 압축이 하나에서 실행되었을 때, Claude Code는 시도를 건너뛰고 요청을 채우는 것을 설명합니다. API가 오류에서 토큰 수를 보고하지 않으면 메시지는 다음과 같이 읽습니다:
1986 2113
1987```text theme={null}2114```text theme={null}
1988Prompt 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.2115Prompt 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.
1989```2116```
1990 2117
1991API가 오류에서 토큰 수를 보고하면 Claude Code는 이를 대화 크기의 자체 추정치와 비교하여 요청의 대부분을 차지하는 것이 무엇인지 알려줍니다: 대화 자체의 내용, 또는 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의 및 첨부 내용입니다. 대화 자체의 내용이 요청의 대부분인 경우 메시지는 다음과 같이 읽힙니다:2118API가 오류에서 토큰 수를 보고하면 Claude Code는 이를 자신의 대화 크기 추정치와 비교하여 요청의 대부분이 무엇인지 알려줍니다: 대화 자체의 내용, 또는 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의 및 첨부 내용. 대화 자체의 내용이 요청의 대부분인 경우 메시지는 다음과 같이 읽습니다:
1992 2119
1993```text theme={null}2120```text theme={null}
1994Prompt 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).2121Prompt 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).
1995```2122```
1996 2123
1997요청의 대부분이 대화 외부에 있으면 메시지는 다음과 같이 읽힙니다:2124요청의 대부분이 대화 외부에 있으면 메시지는 다음과 같이 읽습니다:
1998 2125
1999```text theme={null}2126```text theme={null}
2000Prompt 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.2127Prompt 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.
2001```2128```
2002 2129
2003v2.1.162 이전에는 Claude Code가 압축을 시도했으며 실패했을 때 기본 `Prompt is too long`을 표시했습니다.2130v2.1.162 이전에는 Claude Code가 압축을 시도했고 실패했을 때 기본 `Prompt is too long`을 표시했습니다.
2004 2131
2005**할 일:**2132**할 일:**
2006 2133
2007* 다중 턴 대화에서 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다. `/compact`가 `Not enough messages to compact.`로 응답하면, 대화는 요약할 이전 내용이 없는 단일 교환이므로 공간은 해당 프롬프트와 Claude Code가 모든 요청과 함께 보내는 것으로 차지됩니다: `/clear`를 실행하고 붙여넣은 텍스트가 적거나 첨부 파일이 작은 상태로 다시 보내거나, 아래 단계를 사용하여 도구 정의 및 메모리 파일을 줄입니다2134* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다. `/compact`가 `Not enough messages to compact.`로 응답하면 대화는 요약할 이전 내용이 없는 단일 교환이므로 공간은 해당 프롬프트와 Claude Code가 모든 요청과 함께 보내는 것으로 채워집니다: `/clear`를 실행하고 더 적은 붙여넣은 텍스트 또는 더 작은 첨부 파일로 다시 보내거나, 아래 단계를 사용하여 도구 정의 및 메모리 파일을 줄입니다.
2008* `/context`를 실행하여 윈도우를 소비하는 것의 분석을 확인합니다: 시스템 프롬프트, 도구, 메모리 파일 및 메시지2135* `/context`를 실행하여 윈도우를 소비하는 것의 분석을 확인합니다: 시스템 프롬프트, 도구, 메모리 파일 및 메시지
2009* `/mcp disable <name>`으로 사용하지 않는 MCP 서버를 비활성화하여 컨텍스트에서 도구 정의를 제거합니다2136* `/mcp disable <name>`으로 사용하지 않는 MCP 서버를 비활성화하여 컨텍스트에서 도구 정의를 제거합니다.
2010* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 지침을 관련이 있을 때만 로드되는 [경로 범위 규칙](/docs/ko/memory#path-specific-rules)으로 이동합니다2137* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 지시사항을 관련이 있을 때만 로드되는 [경로 범위 규칙](/docs/ko/memory#path-specific-rules)으로 이동합니다.
2011* 서브에이전트는 부모 세션에서 모든 MCP 도구 정의를 상속하므로 첫 번째 턴 전에 컨텍스트 윈도우를 채울 수 있습니다. 서브에이전트를 생성하기 전에 사용하지 않는 MCP 서버를 비활성화합니다2138* 하위 에이전트는 부모 세션의 모든 MCP 도구 정의를 상속하므로 첫 번째 턴 전에 컨텍스트 윈도우를 채울 수 있습니다. 하위 에이전트를 생성하기 전에 사용하지 않는 MCP 서버를 비활성화합니다.
2012* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config`에서 또는 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars)로 끈 경우 다시 켭니다. 끈 상태로 유지하면 윈도우가 채워지기 전에 `/compact`를 직접 실행합니다.2139* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config`에서 또는 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars)로 끈 경우 다시 켭니다. 끈 상태로 유지하면 윈도우가 채워지기 전에 `/compact`를 직접 실행합니다.
2013 2140
2014[컨텍스트 윈도우 탐색](/docs/ko/context-window)에서 컨텍스트가 어떻게 채워지는지에 대한 대화형 보기를 참조하십시오.2141[컨텍스트 윈도우 탐색](/docs/ko/context-window)에서 컨텍스트가 어떻게 채워지는지에 대한 대화형 보기를 참조하십시오.
2017 컨텍스트가 토큰 제한을 초과합니다2144 컨텍스트가 토큰 제한을 초과합니다
2018</h3>2145</h3>
2019 2146
2020`/context`는 대화가 모델의 컨텍스트 윈도우를 초과했을 때 출력 상단에 이 경고를 표시합니다. [`Prompt is too long`](#prompt-is-too-long)을 해제할 때까지 요청이 실패합니다. 대화형 세션은 해당 오류를 `Context limit reached` 줄로 표시합니다.2147`/context`는 대화가 모델의 컨텍스트 윈도우를 초과했을 때 출력 상단에 이 경고를 표시합니다. [`Prompt is too long`](#prompt-is-too-long)으로 공간을 확보할 때까지 요청이 실패합니다. 대화형 세션은 해당 오류를 `Context limit reached` 줄로 표시합니다.
2021 2148
2022```text theme={null}2149```text theme={null}
2023Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2150Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
2024```2151```
2025 2152
2026초과한 제한이 1M 컨텍스트 모델의 200K 경계와 같은 모델의 컨텍스트 윈도우보다 작은 압축 윈도우인 경우, 경고는 다르게 읽힙니다. 압축 윈도우는 모델의 컨텍스트 윈도우 아래에 있을 수 있으므로 그것을 지난 요청은 여전히 성공할 수 있습니다.2153초과한 제한이 1M 컨텍스트 모델의 200K 경계와 같은 압축 윈도우인 경우 경고는 다르게 읽힙니다. 압축 윈도우는 모델의 컨텍스트 윈도우 아래에 있을 수 있으므로 그 이후의 요청은 여전히 성공할 수 있습니다.
2027 2154
2028```text theme={null}2155```text theme={null}
2029Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.2156Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.
2030```2157```
2031 2158
2032두 형식 모두 [`DISABLE_COMPACT`](/docs/ko/env-vars)를 설정한 경우 `/compact` 대신 `/clear`를 이름으로 지정합니다.2159두 형식 모두 [`DISABLE_COMPACT`](/docs/ko/env-vars)를 설정한 경우 `/compact` 대신 `/clear`를 표시합니다.
2033 2160
2034**할 일:**2161**할 일:**
2035 2162
2036* 다중 턴 대화에서 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보합니다. 대신 새로 시작하려면 `/clear`를 실행합니다2163* 다중 턴 대화에서 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보합니다. 대신 새로 시작하려면 `/clear`를 실행합니다.
2037* 사용량을 줄이는 더 많은 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오2164* 사용량을 줄이는 더 많은 방법은 [프롬프트가 너무 깁니다](#prompt-is-too-long)를 참조하십시오.
2038 2165
2039v2.1.216 이전에는 `/context`가 100% 이상의 사용량을 표시했으며 그것이 의미하는 바 또는 복구 방법을 설명하는 경고 줄이 없었습니다.2166v2.1.216 이전에는 `/context`가 100% 이상의 사용량을 표시했으며 그것이 의미하는 바 또는 복구 방법을 설명하는 경고 줄이 없었습니다.
2040 2167
2052 2179
2053**할 일:**2180**할 일:**
2054 2181
2055* Esc를 두 번 눌러 메시지 목록을 열고 여러 턴을 뒤로 이동합니다. 이렇게 하면 컨텍스트에서 가장 최근 메시지가 제거됩니다. 그런 다음 `/compact`를 다시 실행합니다.2182* Esc를 두 번 눌러 메시지 목록을 열고 여러 턴을 뒤로 이동합니다. 이렇게 하면 가장 최근 메시지가 컨텍스트에서 제거됩니다. 그런 다음 `/compact`를 다시 실행합니다.
2056* 뒤로 이동해도 충분한 공간이 확보되지 않으면 `/clear`를 실행하여 새 세션을 시작합니다. 이전 대화는 보존되며 `/resume`으로 다시 열 수 있습니다.2183* 뒤로 이동해도 충분한 공간이 확보되지 않으면 `/clear`를 실행하여 새 세션을 시작합니다. 이전 대화는 보존되며 `/resume`으로 다시 열 수 있습니다.
2057 2184
2058이 메시지 및 기타 `/compact` 실패는 오류 스타일로 표시됩니다. v2.1.216 이전에는 성공한 명령 출력과 동일한 흐릿한 스타일로 렌더링되었으므로 실패한 압축을 성공으로 읽을 수 있었습니다.2185이 메시지 및 기타 `/compact` 실패는 오류 스타일로 표시됩니다. v2.1.216 이전에는 성공적인 명령 출력과 동일한 흐릿한 스타일로 렌더링되어 실패한 압축을 성공으로 읽을 수 있었습니다.
2059 2186
2060<h3 id="request-too-large">2187<h3 id="request-too-large">
2061 요청이 너무 큽니다2188 요청이 너무 큽니다
2069 2196
2070요청이 Claude API로 직접 이동했고 API 자체가 거부한 경우, Claude Code는 대화를 측정하고 복구가 작동할 수 있는지 여부에 따라 메시지를 표현합니다. 프록시, 게이트웨이 또는 클라우드 제공자를 통해 일반 메시지를 받습니다. 측정된 형식:2197요청이 Claude API로 직접 이동했고 API 자체가 거부한 경우, Claude Code는 대화를 측정하고 복구가 작동할 수 있는지 여부에 따라 메시지를 표현합니다. 프록시, 게이트웨이 또는 클라우드 제공자를 통해 일반 메시지를 받습니다. 측정된 형식:
2071 2198
2072* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지 또는 문서가 요청을 초과했습니다. Claude Code는 이를 제거하고 다시 시도합니다.2199* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지 또는 문서가 요청을 제한 이상으로 밀어냈습니다. Claude Code는 이들을 제거하고 다시 시도합니다.
2073* `Request too large for the API's 32MB request limit`: 메시지 자체가 제한을 초과하므로 메시지는 `compacting cannot make it fit`이라고 말하고 Claude Code는 다시 시도하지 않습니다. [비대화형 모드](/docs/ko/headless)에서 메시지는 입력을 줄이거나 대신 새 세션을 시작하도록 알려줍니다.2200* `Request too large for the API's 32MB request limit`: 메시지만 제한을 초과하므로 메시지는 `compacting cannot make it fit`이라고 말하고 Claude Code는 다시 시도하지 않습니다. [비대화형 모드](/docs/ko/headless)에서 메시지는 입력을 줄이거나 대신 새 세션을 시작하도록 알려줍니다.
2074 2201
2075v2.1.212 이전에는 충분한 누적 이미지가 있는 대화가 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 모든 턴에서 실패했습니다. v2.1.229 이전에는 Claude Code가 압축이 도움이 될 수 없을 때도 모든 거부에 대해 첨부 조언을 표시했습니다.2202v2.1.212 이전에는 충분한 누적 이미지가 있는 대화가 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 매 턴마다 실패했습니다. v2.1.229 이전에는 Claude Code가 압축이 도움이 될 수 없을 때도 모든 거부에 대해 첨부 파일 조언을 표시했습니다.
2076 2203
2077**할 일:**2204**할 일:**
2078 2205
2079* 메시지가 `compacting cannot make it fit`이라고 말하면 큰 내용을 추가한 턴을 지나 Esc를 두 번 눌러 뒤로 이동하거나 `/clear`를 실행하여 새로 시작합니다2206* 메시지가 `compacting cannot make it fit`이라고 말하면 Esc를 두 번 눌러 큰 내용을 추가한 턴을 지나 뒤로 이동하거나 `/clear`를 실행하여 새로 시작합니다.
2080* 그렇지 않으면 `/compact`를 실행하여 누적된 이미지 및 첨부 파일을 제거합니다2207* 그렇지 않으면 `/compact`를 실행합니다. 이는 누적된 이미지 및 첨부 파일을 제거합니다.
2081* 내용을 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다2208* 내용을 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다.
2082* 이미지의 경우 아래의 [Image was too large](#image-was-too-large)를 참조하십시오2209* 이미지의 경우 아래의 [이미지가 너무 컸습니다](#image-was-too-large)를 참조하십시오.
2083 2210
2084<h3 id="image-was-too-large">2211<h3 id="image-was-too-large">
2085 이미지가 너무 큽니다2212 이미지가 너무 컸습니다
2086</h3>2213</h3>
2087 2214
2088붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.2215붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.
2092API Error: 400 ... image dimensions exceed max allowed size2219API Error: 400 ... image dimensions exceed max allowed size
2093```2220```
2094 2221
2095Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지가 성공합니다. 2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 모든 메시지에서 동일한 오류를 반복합니다. 이러한 버전에서 복구하려면 Esc를 두 번 눌러 이미지가 추가된 턴을 지나 뒤로 이동합니다.2222Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지는 성공합니다. v2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 모든 메시지에서 동일한 오류를 반복했습니다. 이러한 버전에서 복구하려면 Esc를 두 번 누르고 이미지가 추가된 턴을 지나 뒤로 이동합니다.
2096 2223
2097**할 일:**2224**할 일:**
2098 2225
2099* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀을 허용하거나 많은 이미지가 컨텍스트에 있을 때 2000픽셀을 허용합니다.2226* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀, 또는 많은 이미지가 컨텍스트에 있을 때 2000픽셀까지의 이미지를 허용합니다.
2100* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다2227* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다.
2101 2228
2102<h3 id="unable-to-resize-image">2229<h3 id="unable-to-resize-image">
2103 이미지 크기를 조정할 수 없습니다2230 이미지 크기를 조정할 수 없습니다
2115Unable 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.2242Unable 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.
2116```2243```
2117 2244
2118Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이러한 오류는 이미지를 디코딩하거나 API 제한 내에 맞게 크기 조정할 수 없음을 의미합니다.2245Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이러한 오류는 이미지를 디코딩하거나 API 제한 내에 맞게 크기를 조정할 수 없음을 의미합니다.
2119 2246
2120**할 일:**2247**할 일:**
2121 2248
2122* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지를 디코딩하지 않고 파일 헤더에서 이러한 형식의 치수를 확인할 수 있습니다.2249* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지를 디코딩하지 않고 파일 헤더에서 이러한 형식의 치수를 확인할 수 있습니다.
2123* 메시지가 치수 또는 크기 제한을 보고하면 해당 제한 아래로 이미지 크기를 조정하거나 다시 압축한 후 첨부합니다.2250* 메시지가 치수 또는 크기 제한을 보고하면 해당 제한 아래로 이미지 크기를 조정하거나 다시 압축한 후 첨부합니다.
2124* 메시지가 CMYK JPEG, 애니메이션 WebP 또는 손상된 파일과 같은 원인을 이름으로 지정하면 메시지가 제안하는 형식으로 이미지를 다시 저장하고 첨부합니다.2251* 메시지가 CMYK JPEG, 애니메이션 WebP 또는 손상된 파일 가능성과 같은 원인을 표시하면 메시지가 제안하는 형식으로 이미지를 다시 저장하고 첨부합니다.
2125 2252
2126<h3 id="pdf-errors">2253<h3 id="pdf-errors">
2127 PDF 오류2254 PDF 오류
2128</h3>2255</h3>
2129 2256
2130첨부한 PDF를 처리할 수 없었습니다. 메시지는 비대화형 형식으로 표시됩니다. 대화형 세션에서는 대신 Esc를 두 번 눌러 다시 시도하도록 요청합니다.2257첨부한 PDF를 처리할 수 없었습니다. 메시지는 여기에 비대화형 형식으로 표시됩니다. 대화형 세션에서는 대신 Esc를 두 번 누르고 다시 시도하도록 요청합니다.
2131 2258
2132```text theme={null}2259```text theme={null}
2133PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).2260PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
2137 2264
2138**할 일:**2265**할 일:**
2139 2266
2140* 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Read 도구로 Claude에게 페이지 범위를 읽도록 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 출력 파일을 경로로 참조합니다2267* 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Read 도구로 페이지 범위를 읽도록 Claude에 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 출력 파일을 경로로 참조합니다.
2141* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다2268* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다.
2142 2269
2143<h3 id="extra-inputs-are-not-permitted">2270<h3 id="extra-inputs-are-not-permitted">
2144 추가 입력은 허용되지 않습니다2271 추가 입력은 허용되지 않습니다
2155 2282
2156**할 일:**2283**할 일:**
2157 2284
2158* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. 게이트웨이가 전달해야 하는 것은 [기능 통과](/docs/ko/llm-gateway-protocol#feature-pass-through)를 참조하십시오.2285* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. 게이트웨이가 전달해야 하는 것에 대해서는 [기능 통과](/docs/ko/llm-gateway-protocol#feature-pass-through)를 참조하십시오.
2159* 대체로 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/ko/env-vars)을 설정합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)는 정확한 범위를 다룹니다.2286* 대체로 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/ko/env-vars)을 설정합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)는 정확한 범위를 다룹니다.
2160 2287
2161<h3 id="tool-input-schema-is-invalid">2288<h3 id="tool-input-schema-is-invalid">
2162 도구 입력 스키마가 유효하지 않습니다2289 도구 입력 스키마가 유효하지 않습니다
2163</h3>2290</h3>
2164 2291
2165요청의 도구가 API의 JSON Schema 검증에 실패하는 `input_schema`를 선언했으므로 API가 전체 요청을 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.2292요청의 도구가 API의 JSON Schema 검증에 실패하는 `input_schema`를 선언했으므로 API가 전체 요청을 거부했습니다. `tools.` 뒤의 숫자는 실패한 도구의 위치이며 조회할 수 있는 이름이 아닙니다.
2166 2293
2167```text theme={null}2294```text theme={null}
2168API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid2295API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
2171 2298
2172첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아님을 의미합니다. 두 번째는 최상위 속성 이름이 메시지가 인용하는 패턴과 일치하지 않음을 의미합니다.2299첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아님을 의미합니다. 두 번째는 최상위 속성 이름이 메시지가 인용하는 패턴과 일치하지 않음을 의미합니다.
2173 2300
2174Claude Code는 로드할 때 [이 검증에 실패할 입력 스키마가 있는 MCP 도구를 제외](/docs/ko/mcp#tools-with-invalid-input-schemas)하므로 요청은 일반적으로 하나를 포함하지 않습니다.2301Claude Code는 [이 검증에 실패할 입력 스키마를 가진 MCP 도구를 제외합니다](/docs/ko/mcp#tools-with-invalid-input-schemas). 서버의 도구를 로드할 때 요청은 일반적으로 하나를 포함하지 않습니다.
2175 2302
2176[플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서 또는 플래그가 도착한 적이 없는 머신에서 Claude Code는 서버의 로그에 거부될 도구를 기록하지만 어쨌든 보내므로 이 오류가 여전히 발생할 수 있습니다.2303[플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서 또는 플래그가 도착한 적이 없는 머신에서 Claude Code는 서버의 로그에 거부될 도구를 기록하지만 어쨌든 보내므로 이 오류가 여전히 발생할 수 있습니다.
2177 2304
2178오류는 또한 스키마가 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언하는 도구에 대해 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마에 대해 확인하지 않지만 최상위 속성 이름 확인은 여전히 적용됩니다.2305오류는 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언하는 도구의 스키마에서도 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마에 대해 확인하지 않지만 최상위 속성 이름 확인은 여전히 적용됩니다.
2179 2306
2180v2.1.216 이전에는 배포가 제외 확인을 실행하지 않았습니다.2307v2.1.216 이전에는 배포가 제외 확인을 실행하지 않았습니다.
2181 2308
2182**할 일:**2309**할 일:**
2183 2310
2184* Claude Code 버전이 v2.1.216보다 이전이면 `claude update`를 실행합니다.2311* Claude Code 버전이 v2.1.216보다 이전이면 `claude update`를 실행합니다.
2185* 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 [비활성화](/docs/ko/mcp#disable-a-server-without-removing-it)합니다. 오류는 도구를 위치로만 이름으로 지정합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 이름으로 지정하는 줄을 확인합니다. 로그가 하나를 이름으로 지정하지 않으면 서버를 하나씩 비활성화합니다.2312* 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 [비활성화](/docs/ko/mcp#disable-a-server-without-removing-it)합니다. 오류는 도구를 위치로만 표시합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 표시하는 줄을 확인합니다. 로그가 하나를 표시하지 않으면 서버를 하나씩 비활성화합니다.
2186* 서버를 유지 관리하면 도구의 `input_schema`를 수정합니다. 스키마는 유효한 JSON Schema여야 하며 최상위 속성 이름은 1\~64자 길이여야 하고 ASCII 문자와 숫자, `_`, `.` 및 `-`만 사용해야 합니다. [유효하지 않은 입력 스키마가 있는 도구](/docs/ko/mcp#tools-with-invalid-input-schemas)를 참조하십시오.2313* 서버를 유지 관리하면 도구의 `input_schema`를 수정합니다. 스키마는 유효한 JSON Schema여야 하며 최상위 속성 이름은 1\~64자 길이여야 하고 ASCII 문자와 숫자, `_`, `.` 및 `-`만 사용해야 합니다. [유효하지 않은 입력 스키마를 가진 도구](/docs/ko/mcp#tools-with-invalid-input-schemas)를 참조하십시오.
2314
2315<h3 id="tool-use-name-over-200-characters">
2316 tool\_use.name이 200자를 초과합니다
2317</h3>
2318
2319대화 기록의 도구 호출이 API가 요청에서 허용하는 200자보다 긴 이름을 포함합니다:
2320
2321```text theme={null}
2322API Error: 400 ... tool_use.name: String should have at most 200 characters
2323```
2324
2325Claude Code는 응답이 도착할 때와 저장된 대화를 로드할 때 이러한 이름을 200자로 자릅니다. 따라서 호출은 일반적인 `No such tool available` 도구 오류로 실패하고 대화는 이 API 오류 없이 계속됩니다.
2326
2327**할 일:**
2328
2329* `claude update`를 실행한 다음 대화를 재개합니다. 업데이트된 버전은 기록을 로드할 때 과도하게 긴 이름을 복구하므로 막힌 대화가 다시 작동합니다.
2330
2331v2.1.281 이전에는 과도하게 긴 이름이 기록에 남아 있었고 API는 `/compact` 및 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했으므로 이 오류가 반복되고 대화가 막혔습니다.
2187 2332
2188<h3 id="theres-an-issue-with-the-selected-model">2333<h3 id="theres-an-issue-with-the-selected-model">
2189 선택한 모델에 문제가 있습니다2334 선택한 모델에 문제가 있습니다
2190</h3>2335</h3>
2191 2336
2192구성된 모델 이름이 인식되지 않았거나 계정에 액세스 권한이 없습니다. v2.1.160부터 뒤따르는 힌트는 표시 표면에 따라 다르며 여기에 대화형 형식으로 표시됩니다.2337구성된 모델 이름을 인식하지 못했거나 계정이 이에 대한 액세스 권한이 없습니다. v2.1.160부터 뒤따르는 힌트는 표시 표면에 따라 다릅니다.
2193 2338
2194```text theme={null}2339```text theme={null}
2195There'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.2340There'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.
2200* **대화형 CLI**: `/model`을 실행하여 계정에서 사용 가능한 모델 중에서 선택합니다.2345* **대화형 CLI**: `/model`을 실행하여 계정에서 사용 가능한 모델 중에서 선택합니다.
2201* **비대화형 모드(`-p`)**: 유효한 별칭 또는 ID로 `--model`을 전달하거나 [`ANTHROPIC_MODEL`](/docs/ko/env-vars)을 설정합니다. 오류 텍스트는 이 표면에서 `Run --model`을 표시합니다.2346* **비대화형 모드(`-p`)**: 유효한 별칭 또는 ID로 `--model`을 전달하거나 [`ANTHROPIC_MODEL`](/docs/ko/env-vars)을 설정합니다. 오류 텍스트는 이 표면에서 `Run --model`을 표시합니다.
2202* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트는 힌트를 생략합니다. TypeScript에서 [`Options`의 `model`](/docs/ko/agent-sdk/typescript#options)을 설정하거나 Python에서 [`ClaudeAgentOptions(model=...)`](/docs/ko/agent-sdk/python#claudeagentoptions)을 설정하고 구조화된 `model_not_found` 오류를 처리하여 자신의 재시도 또는 모델 선택기를 표시합니다.2347* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트는 힌트를 생략합니다. TypeScript에서 [`Options`의 `model`](/docs/ko/agent-sdk/typescript#options)을 설정하거나 Python에서 [`ClaudeAgentOptions(model=...)`](/docs/ko/agent-sdk/python#claudeagentoptions)을 설정하고 구조화된 `model_not_found` 오류를 처리하여 자신의 재시도 또는 모델 선택기를 표시합니다.
2203* `claude-...`의 전체 버전 ID 대신 `sonnet` 또는 `opus`와 같은 별칭을 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래되지 않습니다. [모델 구성](/docs/ko/model-config)을 참조하십시오.2348* `sonnet` 또는 `opus`와 같은 별칭을 전체 버전 ID 대신 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래되지 않습니다. [모델 구성](/docs/ko/model-config)을 참조하십시오.
2204* CLI에서 잘못된 모델이 계속 돌아오면 어딘가에 오래된 ID가 설정되어 있습니다. [우선순위 순서](/docs/ko/model-config#setting-your-model)로 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거합니다.2349* 잘못된 모델이 CLI에서 계속 돌아오면 어딘가에 오래된 ID가 설정되어 있습니다. [우선순위 순서](/docs/ko/model-config#setting-your-model)로 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거합니다.
2205* 새로 출시된 모델은 Anthropic API에서 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry가 제공하기 전에 사용 가능할 수 있습니다. 이러한 제공자 중 하나에서 새 모델 ID를 고정했고 이 오류가 표시되면 제공자의 모델 카탈로그에서 지역의 가용성을 확인하고 새 모델이 나타날 때까지 이전 버전을 고정된 상태로 유지합니다.2350* 새로 출시된 모델은 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry가 제공하기 전에 Anthropic API에서 사용 가능할 수 있습니다. 이러한 제공자 중 하나에서 새 모델 ID를 고정했고 이 오류가 표시되면 제공자의 모델 카탈로그에서 지역의 가용성을 확인하고 새 모델이 나타날 때까지 이전 버전을 고정된 상태로 유지합니다.
2206* Claude Code는 만료된 claude.ai 로그인을 [Login expired](#login-expired)로 보고하며, 이 오류로는 보고하지 않습니다. v2.1.206 이전에는 더 이상 새로 고칠 수 없는 만료된 로그인이 모든 모델에서 실패했습니다. 이전 버전에서 이를 보면 `/login`을 실행합니다.2351* Claude Code는 만료된 claude.ai 로그인을 [로그인 만료됨](#login-expired)으로 보고하며, 이 오류로는 보고하지 않습니다. v2.1.206 이전에는 더 이상 새로 고칠 수 없는 만료된 로그인이 모든 모델에서 실패했습니다. 이전 버전에서 이를 보면 `/login`을 실행합니다.
2207* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/docs/ko/google-vertex-ai#troubleshooting)을 참조하십시오.2352* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/docs/ko/google-vertex-ai#troubleshooting)을 참조하십시오.
2208 2353
2209<h3 id="model-is-not-a-recognized-model-id">2354<h3 id="model-is-not-a-recognized-model-id">
2210 모델이 인식된 모델 ID가 아닙니다2355 모델이 인식된 모델 ID가 아닙니다
2211</h3>2356</h3>
2212 2357
2213모델 스위치에 전달한 모델 문자열이 모델 별칭, 이 Claude Code 버전이 알고 있는 모델 ID 또는 `claude-`로 시작하는 ID가 아닙니다. 일반적인 원인은 ID의 오타, `Sonnet 5`와 같은 표시 이름(ID `claude-sonnet-5` 필요) 또는 최신 Claude Code 버전만 인식하는 별칭입니다. Claude Code는 스위치를 즉시 거부합니다. v2.1.200 이전에는 Claude Code가 문자열을 저장했고 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model)로 다음 요청에서 실패했습니다.2358모델 전환에 전달한 모델 문자열이 모델 별칭, 이 Claude Code 버전이 알고 있는 모델 ID 또는 `claude-`로 시작하는 ID가 아닙니다. 일반적인 원인은 ID의 오타, `Sonnet 5`와 같은 표시 이름(ID `claude-sonnet-5` 필요) 또는 최신 Claude Code 버전만 인식하는 별칭입니다. Claude Code는 즉시 전환을 거부합니다. v2.1.200 이전에는 Claude Code가 문자열을 저장했고 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model)로 다음 요청에서 실패했습니다.
2214 2359
2215```text theme={null}2360```text theme={null}
2216Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?2361Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?
2217```2362```
2218 2363
2219뒤따르는 힌트는 가장 가까운 일치하는 별칭 또는 모델 ID를 이름으로 지정합니다. 충분히 가까운 것이 없으면 `Run /model to see available models.`로 읽힙니다.2364뒤따르는 힌트는 가장 가까운 일치하는 별칭 또는 모델 ID를 표시합니다. 충분히 가까운 것이 없으면 `Run /model to see available models.`로 읽습니다. [Desktop 앱](/docs/ko/desktop)이 시작하는 세션에서 일치하지 않는 힌트는 `Switch to a different model.`로 읽습니다.
2220 2365
2221Claude Code는 API 요청이 이루어지기 전에 스위치가 요청되는 순간 로컬에서 이 오류를 생성합니다. [Agent SDK](/docs/ko/agent-sdk/typescript) `setModel()` 메서드를 통해 모델이 설정되거나 [Desktop 앱](/docs/ko/desktop)과 같은 앱이 Claude Code CLI를 실행하거나 [Remote Control](/docs/ko/remote-control)을 통해 연결된 장치에서 모델을 선택할 때 적용됩니다. v2.1.260 이전에는 확인이 Remote Control 선택을 다루지 않았으므로 Claude Code가 선택을 적용했고 다음 요청이 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model)로 실패했습니다.2366Claude Code는 전환이 요청되는 순간 로컬에서 이 오류를 생성하며, API 요청이 이루어지기 전입니다. [Agent SDK](/docs/ko/agent-sdk/typescript) `setModel()` 메서드를 통해 모델이 설정되거나 [Desktop 앱](/docs/ko/desktop)과 같은 앱이 Claude Code CLI를 실행할 때 또는 [Remote Control](/docs/ko/remote-control)을 통해 연결된 장치에서 모델을 선택할 때 적용됩니다. v2.1.260 이전에는 확인이 Remote Control 선택을 다루지 않았으므로 Claude Code가 선택을 적용했고 다음 요청이 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model)로 실패했습니다.
2222 2367
2223**할 일:**2368**할 일:**
2224 2369
2225* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용 가능한 모델 중에서 선택한 다음 거기에 표시된 별칭 또는 ID를 전달합니다2370* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용 가능한 모델 중에서 선택한 다음 거기에 표시된 별칭 또는 ID를 전달합니다.
2226* 최신 Claude Code 버전이 지원하는 별칭을 사용한 경우 `claude update`를 실행합니다. `claude-`로 시작하는 전체 ID는 모델이 Claude Code 버전보다 최신이어도 이 로컬 확인을 통과합니다. 서버는 여전히 해당 모델에 대한 최소 버전을 요구할 수 있습니다. [Claude Code가 이 모델을 지원하지 않습니다](#claude-code-does-not-support-this-model)를 참조하십시오.2371* 최신 Claude Code 버전이 지원하는 별칭을 사용한 경우 `claude update`를 실행합니다. `claude-`로 시작하는 전체 ID는 모델이 Claude Code 버전보다 최신이어도 이 로컬 확인을 통과합니다. 서버는 여전히 해당 모델에 대한 최소 버전을 요구할 수 있습니다. [Claude Code가 이 모델을 지원하지 않습니다](#claude-code-does-not-support-this-model)를 참조하십시오.
2227* v2.1.200 이전에 저장된 모델은 이 확인으로 복구되지 않습니다. 오래된 값이 계속 돌아오면 [모델 설정](/docs/ko/model-config#setting-your-model) 아래에 나열된 위치에서 제거합니다.2372* v2.1.200 이전에 저장된 모델은 이 확인으로 복구되지 않습니다. 오래된 값이 계속 돌아오면 [모델 설정](/docs/ko/model-config#setting-your-model)에 나열된 위치에서 제거합니다.
2228* 확인은 Anthropic API에서만 실행됩니다. 사용자 정의 `ANTHROPIC_BASE_URL`을 포함한 다른 제공자 또는 게이트웨이에서 제공자는 모델 이름을 정의하므로 Claude Code는 모든 문자열을 수락하고 통과합니다. Claude Code는 여전히 요청 시간에 모든 제공자에서 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)을 쓸 수 있습니다.2373* 확인은 Anthropic API에서만 실행됩니다. 사용자 정의 `ANTHROPIC_BASE_URL`을 포함한 다른 제공자 또는 게이트웨이에서 제공자는 모델 이름을 정의하므로 Claude Code는 모든 문자열을 허용하고 통과합니다. Claude Code는 여전히 요청 시간에 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)을 모든 제공자에서 쓸 수 있습니다.
2229 2374
2230<h3 id="model-not-found">2375<h3 id="model-not-found">
2231 모델을 찾을 수 없습니다2376 모델을 찾을 수 없습니다
2232</h3>2377</h3>
2233 2378
2234`/model <name>`으로 모델을 선택했고 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 Claude Code가 로컬에서 수락하는 다른 철자가 아닌 경우 `/model`은 최소 API 요청으로 확인하고 이 오류는 일반적으로 API 엔드포인트의 답변입니다. 공백을 포함하는 것과 같이 모델 ID가 될 수 없는 이름은 동일한 메시지를 받습니다.2379`/model <name>`으로 모델을 선택했고 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 Claude Code가 로컬로 허용하는 다른 철자가 아닌 경우 `/model`은 최소 API 요청으로 이를 확인하고 이 오류는 일반적으로 API 엔드포인트의 응답입니다. 공백을 포함하는 것과 같이 모델 ID가 될 수 없는 이름은 동일한 메시지를 받습니다.
2235 2380
2236```text theme={null}2381```text theme={null}
2237Model 'claude-opus-9' not found2382Model 'claude-opus-9' not found
2238```2383```
2239 2384
2240제공자별 모델 ID가 있는 제공자에서 메시지는 대체 모델에 대한 제공자의 ID를 이름으로 지정하는 `Try '...' instead` 제안을 추가할 수 있습니다.2385제공자별 모델 ID를 가진 제공자에서 메시지는 대체 모델에 대한 제공자의 ID를 표시하는 `Try '...' instead` 제안을 추가할 수 있습니다.
2241 2386
2242**할 일:**2387**할 일:**
2243 2388
2244* 인수 없이 `/model`을 실행하고 계정에서 사용 가능한 모델 중에서 선택하거나 `sonnet`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases)을 사용합니다. 이는 유지 관리되는 기본값으로 확인됩니다2389* 인수 없이 `/model`을 실행하고 계정에서 사용 가능한 모델 중에서 선택하거나 `sonnet`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases)을 사용합니다. 이는 유지 관리되는 기본값으로 확인됩니다.
2245* 전체 ID를 입력한 경우 제공자의 모델 카탈로그에 대해 확인합니다. 새로 출시된 모델은 제공자 또는 지역이 제공하기 전에 Anthropic API에서 사용 가능할 수 있습니다.2390* 전체 ID를 입력한 경우 제공자의 모델 카탈로그에 대해 확인합니다. 새로 출시된 모델은 제공자 또는 지역이 제공하기 전에 Anthropic API에서 사용 가능할 수 있습니다.
2246* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 철자를 이 오류로 거부했습니다. 이러한 버전에서는 Claude Code를 업데이트하거나 [설정](/docs/ko/model-config#setting-your-model) 또는 `--model`에서 모델을 설정합니다.2391* v2.1.265 이전에는 `/model`도 `opusplan[1m]` 별칭 철자를 이 오류로 거부했습니다. 이러한 버전에서는 Claude Code를 업데이트하거나 [설정](/docs/ko/model-config#setting-your-model)에서 또는 `--model` 대신 모델을 설정합니다.
2392
2393<h3 id="api-error-model-not-changed">
2394 선택한 모델을 확인할 때 API 오류
2395</h3>
2396
2397`/model <name>`으로 모델을 선택했거나 앱이 세션에 연결되어 전환을 요청했습니다. API가 Claude Code가 모델을 확인하기 위해 보내는 최소 요청을 거부했습니다. 이유가 없는 이유(예: 속도 제한 또는 서버 오류)로 인해. 세션은 현재 모델을 유지하고 메시지는 그렇게 말하면서 끝납니다:
2398
2399```text theme={null}
2400API error: 429 <the server's explanation> · model not changed
2401```
2402
2403메시지의 중간은 HTTP 상태 및 서버의 자체 설명입니다.
2404
2405**할 일:**
2406
2407* 서버의 설명에 따라 행동합니다. 속도 제한 또는 5xx 상태의 경우 기다렸다가 모델을 다시 선택합니다.
2408* 자신의 표현이 있는 거부는 [모델을 찾을 수 없습니다](#model-not-found) 및 [모델이 조직의 설정으로 제한됩니다](#model-is-restricted-by-your-organizations-settings)와 같은 주변 항목으로 다룹니다.
2247 2409
2248<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">2410<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">
2249 Claude Opus는 Claude Pro 플랜에서 사용할 수 없습니다2411 Claude Opus는 Claude Pro 플랜에서 사용할 수 없습니다
2255Claude 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.2417Claude 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.
2256```2418```
2257 2419
2420Claude Desktop 앱이 실행하는 세션에서 메시지는 명령을 표시하는 대신 `sign out and sign in again`이라고 말합니다.
2421
2258**할 일:**2422**할 일:**
2259 2423
2260* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다2424* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다.
2261* 최근에 플랜을 업그레이드했는데도 여전히 이를 보면 `/logout`을 실행한 다음 `/login`을 실행합니다. 저장된 토큰은 로그인 시 플랜을 반영하므로 웹에서 업그레이드해도 기존 세션에서 다시 인증할 때까지 적용되지 않습니다.2425* 최근에 플랜을 업그레이드했는데도 여전히 이를 보면 `/logout`을 실행한 다음 `/login`을 실행합니다. 저장된 토큰은 로그인 시점의 플랜을 반영하므로 claude.ai에서 업그레이드하면 다시 인증할 때까지 기존 세션에서 적용되지 않습니다.
2262* [claude.com/pricing](https://claude.com/pricing)에서 각 플랜에 포함된 모델을 참조하십시오2426* 각 플랜에 포함된 모델에 대해서는 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.
2263 2427
2264<h3 id="claude-code-does-not-support-this-model">2428<h3 id="claude-code-does-not-support-this-model">
2265 Claude Code가 이 모델을 지원하지 않습니다2429 Claude Code가 이 모델을 지원하지 않습니다
2266</h3>2430</h3>
2267 2431
2268API가 Claude Code 버전이 필요한 최소값 아래에 있기 때문에 400으로 요청을 거부했습니다. 선택한 모델이 최신 버전을 요구하거나(서버가 모델별로 확인) 조직의 정책이 하나를 요구합니다. 400은 오류 코드 `claude_code_version_too_old`를 전달하고 메시지는 어느 최소값이 적용되는지 말합니다.2432API가 Claude Code 버전이 필요한 최소값 아래에 있기 때문에 400으로 요청을 거부했습니다. 선택한 모델이 최신 버전을 요구하거나(서버가 모델별로 확인) 조직의 정책이 하나를 요구합니다. 400은 오류 코드 `claude_code_version_too_old`를 포함하고 메시지는 어떤 최소값이 적용되는지 말합니다.
2269 2433
2270```text theme={null}2434```text theme={null}
2271API 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.2435API 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.
2272```2436```
2273 2437
2274조직 정책 표현은 다음과 같이 읽힙니다:2438조직 정책 표현은 다음과 같이 읽습니다:
2275 2439
2276```text theme={null}2440```text theme={null}
2277API 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.2441API 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.
2279 2443
2280**할 일:**2444**할 일:**
2281 2445
2282* `claude update`를 실행하거나 Claude 데스크톱 앱을 업데이트한 다음 새 세션을 시작합니다2446* `claude update`를 실행하거나 Claude Desktop 앱을 업데이트한 다음 새 세션을 시작합니다.
2283* 모델별 표현의 경우 `/model`로 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다2447* 모델별 표현의 경우 `/model`로 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다.
2284* 조직 정책 표현의 경우 계속하기 전에 업데이트합니다2448* 조직 정책 표현의 경우 계속하기 전에 업데이트합니다.
2285 2449
2286<h3 id="model-is-restricted-by-your-organizations-settings">2450<h3 id="model-is-restricted-by-your-organizations-settings">
2287 모델이 조직의 설정으로 제한됩니다2451 모델이 조직의 설정으로 제한됩니다
2288</h3>2452</h3>
2289 2453
2290조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나 관리 설정의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록으로 제외되었습니다. 제한된 모델이 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정으로 설정된 경우 Claude Code는 허용된 모델을 대체하고 계속합니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다. 대체 공지는 세션이 실행 중인 모델을 관리자가 claude.ai 관리 콘솔에서 비활성화한 후 세션 중간에 나타날 수도 있습니다.2454조직 관리자가 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 관리 콘솔에서 세션이 실행 중인 모델을 비활성화한 후 세션 중간에도 나타날 수 있습니다.
2291 2455
2292```text theme={null}2456```text theme={null}
2293Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.2457Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.
2294```2458```
2295 2459
2296에이전트, 스킬 또는 명령 이름이 앞에 붙은 공지는 제한이 해당 [서브에이전트의 요청된 모델](/docs/ko/sub-agents#choose-a-model)에 적용되었음을 의미합니다: 서브에이전트는 대체 모델에서 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 시작된 서브에이전트에 대해서만 공지를 표시했습니다.2460제한된 모델에 대해 `/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.`로 읽습니다.
2461
2462에이전트, 스킬 또는 명령 이름이 앞에 붙은 알림은 제한이 해당 [하위 에이전트의 요청된 모델](/docs/ko/sub-agents#choose-a-model)에 적용되었음을 의미합니다: 하위 에이전트는 대체 모델에서 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 시작된 하위 에이전트에 대해서만 알림을 표시했습니다.
2297 2463
2298Claude Code는 모델 패밀리 별칭(`opus`, `sonnet`, `haiku` 또는 `fable` 중 하나)을 최신 버전에 대한 요청이 아닌 해당 패밀리에 대한 요청으로 취급합니다. Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에서 제한된 패밀리 별칭은 조직과 `availableModels` 허용 목록이 허용하는 패밀리의 최신 버전으로 확인되고 대체 공지는 해당 버전을 이름으로 지정합니다. Claude Code는 패밀리의 모든 버전이 제한된 경우에만 `/model <alias>`를 거부합니다. v2.1.205 이전에는 패밀리 별칭이 같은 패밀리의 이전 버전이 허용된 경우에도 최신 버전만을 기반으로 대체되거나 거부되었습니다.2464Claude Code는 모델 패밀리 별칭(하나의 `opus`, `sonnet`, `haiku` 또는 `fable`)을 최신 버전이 아닌 해당 패밀리에 대한 요청으로 취급합니다. Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에서 제한된 패밀리 별칭은 조직의 설정이 허용하는 패밀리의 최신 버전으로 확인되고 대체 알림은 해당 버전을 표시합니다. Claude Code는 패밀리의 모든 버전이 제한된 경우에만 `/model <alias>`를 거부합니다. v2.1.205 이전에는 패밀리 별칭이 최신 버전만을 기반으로 대체되거나 거부되었으며, 같은 패밀리의 이전 버전이 허용되었을 때도 마찬가지였습니다.
2299 2465
2300**할 일:**2466**할 일:**
2301 2467
2302* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에서 숨겨집니다.2468* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에서 숨겨집니다.
2303* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드 또는 [서브에이전트](/docs/ko/sub-agents#choose-a-model), 스킬 또는 명령의 `model` 프론트매터에 설정된 경우 해당 값을 제거하거나 업데이트하여 공지가 다시 나타나지 않도록 합니다2469* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드 또는 [하위 에이전트](/docs/ko/sub-agents#choose-a-model), 스킬 또는 명령의 `model` frontmatter에 설정된 경우 해당 값을 제거하거나 업데이트하여 알림이 반복되지 않도록 합니다.
2304* 제한된 모델에 액세스해야 하면 조직 관리자에게 활성화를 요청합니다. [조직 모델 제한](/docs/ko/model-config#organization-model-restrictions)을 참조하십시오.2470* 제한된 모델에 액세스해야 하면 조직 관리자에게 활성화를 요청합니다. [조직 모델 제한](/docs/ko/model-config#organization-model-restrictions)을 참조하십시오.
2305 2471
2306<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">2472<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">
2307 모델 스위치가 PreModelSwitch 훅으로 차단되었습니다2473 모델 전환이 PreModelSwitch 훅에 의해 차단되었습니다
2308</h3>2474</h3>
2309 2475
2310[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`을 읽습니다.2476[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`으로 읽습니다.
2311 2477
2312```text theme={null}2478```text theme={null}
2313Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.2479Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.
2314```2480```
2315 2481
2316콜론 뒤의 이유는 스위치를 거부한 것을 말합니다:2482콜론 뒤의 이유는 전환을 거부한 것을 말합니다:
2317 2483
2318* **훅이 작성한 이유**: PreModelSwitch 훅이 [스위치를 거부하거나 확인을 요청](/docs/ko/hooks#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청하는 것을 해결하거나 훅이 허용하는 모델을 선택합니다.2484* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](/docs/ko/hooks#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청하는 것을 해결하거나 훅이 허용하는 모델을 선택합니다.
2319* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](/docs/ko/hooks#timeouts) 전에 응답하지 않는 훅이 스위치를 차단합니다. 행(hung) 명령을 수정하거나 해당 훅의 `timeout`을 높인 다음 다시 전환합니다.2485* **`PreModelSwitch hook <name> did not respond before its timeout`**: 훅이 [timeout](/docs/ko/hooks#timeouts) 전에 응답하지 않으면 전환을 차단합니다. 행이 걸린 명령을 수정하거나 해당 훅의 `timeout`을 높인 다음 다시 전환합니다.
2320* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했고 제어 요청이 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](/docs/ko/headless)의 모델 스위치는 이유 뒤에 `(run /model interactively to confirm)`으로 동일한 조건을 보고합니다. 대화형 세션에서 스위치를 만들거나 이 모델에 대한 훅의 결정을 변경합니다.2486* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했고 제어 요청이 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](/docs/ko/headless)의 제어 요청은 이유 뒤에 `(run /model interactively to confirm)`으로 동일한 조건을 보고합니다. 대화형 세션에서 전환을 만들거나 이 모델에 대한 훅의 결정을 변경합니다.
2321* **`so organization-managed PreModelSwitch hooks could not be checked`**: Claude Code가 조직의 [관리 플러그인](/docs/ko/settings-reference#enabledplugins)이 제공하는 PreModelSwitch 훅을 알 수 없었습니다. 예를 들어 관리 플러그인이 로드되지 않았기 때문입니다. 이러한 훅 중 하나가 스위치를 차단할 수 있으므로 Claude Code는 확인되지 않은 스위치를 적용하기보다는 거부합니다. 이유의 시작은 실패한 것을 이름으로 지정합니다. Claude Code는 모든 스위치 시도에서 다시 확인하므로 이후 지워진 실패는 차단을 중지합니다. 계속 실패하면 `claude --debug`를 실행하고 다시 전환하여 세부 정보를 캡처한 다음 플러그인을 수정하거나 관리자에게 수정을 요청합니다.2487* **`so organization-managed PreModelSwitch hooks could not be checked`**: Claude Code가 조직의 [관리 플러그인](/docs/ko/settings-reference#enabledplugins)이 제공하는 PreModelSwitch 훅을 알 수 없습니다. 예를 들어 관리 플러그인이 로드되지 않았기 때문입니다. 이러한 훅 중 하나가 전환을 차단할 수 있으므로 Claude Code는 확인되지 않은 전환을 적용하는 대신 거부합니다. 이유의 시작은 실패한 것을 표시합니다. Claude Code는 모든 전환 시도에서 다시 확인하므로 이후 지워진 실패는 차단을 중지합니다. 계속 실패하면 `claude --debug`를 실행하고 다시 전환하여 세부 정보를 캡처한 다음 플러그인을 수정하거나 관리자에게 수정을 요청합니다.
2322* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 평결 없이 종료되었고 Claude Code는 이를 승인으로 취급하지 않습니다. `claude --debug`를 실행하여 실패한 것을 확인한 다음 다시 전환합니다.2488* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 판정 없이 끝났고 Claude Code는 이를 승인으로 취급하지 않습니다. `claude --debug`를 실행하여 실패한 것을 확인한 다음 다시 전환합니다.
2323 2489
2324v2.1.260 이전에는 관리 플러그인 거부가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`로 읽혔습니다. Claude Code는 플러그인 로드를 한 번 재시도한 다음 조직이 플러그인을 관리하지 않은 경우에도 세션의 이후 스위치를 거부했습니다. 이러한 버전에서 플러그인 로드를 다시 실행하려면 세션을 다시 시작합니다.2490v2.1.260 이전에는 관리 플러그인 거부가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`로 읽었습니다. Claude Code는 플러그인 로드를 한 번 재시도한 다음 세션의 이후 전환을 거부했습니다. 조직이 플러그인을 관리하지 않은 경우에도 마찬가지였습니다. 이러한 버전에서 세션을 다시 시작하여 플러그인 로드를 다시 실행합니다.
2325 2491
2326<h3 id="couldnt-save-it-as-your-default">2492<h3 id="couldnt-save-it-as-your-default">
2327 기본값으로 저장할 수 없습니다2493 기본값으로 저장할 수 없었습니다
2328</h3>2494</h3>
2329 2495
2330모델을 선택하여 기본값으로 저장했습니다. 예를 들어 `/model <name>` 또는 `/model` 선택기의 `Enter`를 사용하고 Claude Code가 사용자 설정 파일 `~/.claude/settings.json`에 선택을 쓸 수 없었습니다. 스위치 자체가 적용되었으므로 현재 세션은 선택한 모델에서 실행되지만 기본값은 변경되지 않으며 다음 세션은 이전 값에서 시작됩니다.2496모델을 기본값으로 저장하도록 선택했습니다. 예를 들어 `/model <name>` 또는 `/model` 선택기에서 `Enter`를 사용하고 Claude Code가 사용자 설정 파일 `~/.claude/settings.json`에 선택을 쓸 수 없었습니다. 전환 자체가 적용되었으므로 현재 세션은 선택한 모델에서 실행되지만 기본값은 변경되지 않으며 다음 세션은 이전 값에서 시작됩니다.
2331 2497
2332```text theme={null}2498```text theme={null}
2333Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)2499Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)
2335 2501
2336파일 경로 뒤의 이유는 실패한 것을 말합니다:2502파일 경로 뒤의 이유는 실패한 것을 말합니다:
2337 2503
2338* **`can't be written (<code>)`**: 쓰기가 괄호의 `EROFS`와 같은 운영 체제 오류 코드로 실패했습니다. 파일이 링크하는 파일이 쓰기를 거부하는 파일 시스템에 있을 때입니다. 파일을 쓰기 가능하게 만들고 다시 전환합니다. 다른 도구가 파일을 생성하면 해당 도구에서 `model` 키를 설정합니다. [Claude Code에서 만든 변경 사항이 새 세션에서 손실됨](/docs/ko/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)을 참조하십시오.2504* **`can't be written (<code>)`**: 쓰기가 운영 체제 오류 코드(예: 파일 또는 링크하는 파일이 쓰기를 거부하는 파일 시스템에 있을 때 `EROFS`)로 실패했습니다. 파일을 쓰기 가능하게 만들고 다시 전환합니다. 다른 도구가 파일을 생성하면 대신 해당 도구에서 `model` 키를 설정합니다. [Claude Code에서 만든 변경 사항이 새 세션에서 손실됩니다](/docs/ko/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)를 참조하십시오.
2339* **`isn't valid JSON`**: 디스크의 파일이 구문 분석되지 않으며 Claude Code는 읽을 수 없는 내용을 덮어쓰기보다는 그대로 둡니다. 구문 오류를 수정한 다음 다시 전환합니다. [손상된 설정 파일 수정](/docs/ko/settings#fix-a-broken-settings-file)을 참조하십시오.2505* **`isn't valid JSON`**: 디스크의 파일이 구문 분석되지 않으며 Claude Code는 읽을 수 없는 내용을 덮어쓰지 않고 그대로 둡니다. 구문 오류를 수정한 다음 다시 전환합니다. [손상된 설정 파일 수정](/docs/ko/settings#fix-a-broken-settings-file)을 참조하십시오.
2340 2506
2341`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 공지는 3초 후에 쓰기가 완료되지 않았음을 의미합니다. 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 시작되는 모델을 확인하거나 `/model <name>`을 다시 실행합니다.2507`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)` 끝나는 알림은 쓰기가 3초 후에 완료되지 않았음을 의미합니다. 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델에서 시작되는지 확인하거나 `/model <name>`을 다시 실행합니다.
2342 2508
2343v2.1.265 이전에는 공지가 쓰기가 실패했을 때도 모델이 `saved as your default for new sessions`이라고 말했습니다.2509v2.1.265 이전에는 알림이 쓰기가 실패했을 때도 모델이 `saved as your default for new sessions`이라고 말했습니다.
2344 2510
2345<h3 id="thinking-type-enabled-is-not-supported-for-this-model">2511<h3 id="thinking-type-enabled-is-not-supported-for-this-model">
2346 thinking.type.enabled는 이 모델에서 지원되지 않습니다2512 thinking.type.enabled은 이 모델에서 지원되지 않습니다
2347</h3>2513</h3>
2348 2514
2349Claude Code 버전이 선택한 모델에 필요한 최소값보다 오래되었습니다. CLI가 모델이 더 이상 수락하지 않는 사고 구성을 보냈습니다.2515Claude Code 버전이 선택한 모델의 최소값보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 생각 구성을 보냈습니다.
2350 2516
2351```text theme={null}2517```text theme={null}
2352API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.2518API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
2354 2520
2355**할 일:**2521**할 일:**
2356 2522
2357* `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 이상이 필요합니다2523* `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 이상이 필요합니다.
2358* 업그레이드할 수 없으면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택합니다2524* 업그레이드할 수 없으면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택합니다.
2359* [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 이상이 필요합니다2525* [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 이상이 필요합니다.
2360 2526
2361<h3 id="effort-isnt-available-with-thinking-turned-off">2527<h3 id="effort-isnt-available-with-thinking-turned-off">
2362 사고가 꺼져 있을 때 노력을 사용할 수 없습니다2528 생각이 꺼져 있으면 노력을 사용할 수 없습니다
2363</h3>2529</h3>
2364 2530
2365[확장 사고](/docs/ko/model-config#extended-thinking)를 끄고 `high` 이상의 [노력 수준](/docs/ko/model-config#adjust-effort-level)에서 실행했습니다. 모델이 해당 조합을 수락하지 않으므로 API가 요청을 거부했습니다.2531[확장 생각](/docs/ko/model-config#extended-thinking)을 끄고 `high` 이상의 [노력 수준](/docs/ko/model-config#adjust-effort-level)에서 실행했습니다. 모델이 해당 조합을 허용하지 않으므로 API가 요청을 거부했습니다.
2366 2532
2367```text theme={null}2533```text theme={null}
2368API 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)2534API 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)
2369```2535```
2370 2536
2537`·` 뒤의 힌트는 세션에 따라 다릅니다: 비대화형 세션에서는 `use --effort high (or the effortLevel setting)`로 읽고 Claude Desktop 앱이 실행하는 세션에서는 `you can lower effort to High`로 읽습니다.
2538
2371**할 일:**2539**할 일:**
2372 2540
2373* [노력 수준을 낮춥니다](/docs/ko/model-config#set-the-effort-level) `high` 이하로.2541* [노력 수준](/docs/ko/model-config#set-the-effort-level)을 `high` 이하로 낮춥니다.
2374* 사고를 다시 켭니다. 예를 들어 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars)을 설정 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](/docs/ko/settings-reference#alwaysthinkingenabled)를 제거합니다.2542* 생각을 다시 켭니다. 예를 들어 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars)을 설정 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](/docs/ko/settings-reference#alwaysthinkingenabled)를 제거합니다.
2375 2543
2376v2.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가 설정한 노력 수준에서 요청을 보냈으므로 Opus 5는 사고가 꺼져 있을 때 `high` 이상의 모든 요청을 거부했습니다. Claude Code는 이제 Opus 5와 같이 조합을 거부하는 것으로 알고 있는 모델에 노력 `high`를 보내므로 v2.1.251 이상에서 이 오류는 Claude Code가 거부하는 것을 알지 못하는 모델에서만 도달합니다.2544v2.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가 설정한 노력 수준에서 요청을 보냈으므로 Opus 5는 생각이 꺼져 있을 때 `high` 이상의 모든 요청을 거부했습니다. Claude Code는 이제 Opus 5와 같이 조합을 거부하는 것으로 알려진 모델에 노력 `high`를 대신 보내므로 v2.1.251 이상에서 이 오류는 Claude Code가 거부하는 것을 알 수 없는 모델에서만 도달합니다.
2377 2545
2378<h3 id="thinking-budget-exceeds-output-limit">2546<h3 id="thinking-budget-exceeds-output-limit">
2379 사고 예산이 출력 제한을 초과합니다2547 생각 예산이 출력 제한을 초과합니다
2380</h3>2548</h3>
2381 2549
2382구성된 확장 사고 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.2550구성된 확장 생각 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.
2383 2551
2384```text theme={null}2552```text theme={null}
2385API Error: 400 ... max_tokens must be greater than thinking.budget_tokens2553API Error: 400 ... max_tokens must be greater than thinking.budget_tokens
2386```2554```
2387 2555
2388Claude Code는 Anthropic API에서 이러한 값을 자동으로 조정합니다. 일반적으로 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars)이 제공자의 출력 제한보다 높게 설정되었거나 계획 모드가 사고 예산을 높일 때 Amazon Bedrock 또는 Google Cloud의 Agent Platform에서 이 오류를 봅니다.2556Claude Code는 Anthropic API에서 이러한 값을 자동으로 조정합니다. 일반적으로 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars)이 제공자의 출력 제한보다 높게 설정되었을 때 또는 계획 모드가 생각 예산을 높일 때 Amazon Bedrock 또는 Google Cloud의 Agent Platform에서 이 오류를 봅니다.
2389 2557
2390**할 일:**2558**할 일:**
2391 2559
2392* `MAX_THINKING_TOKENS`를 낮추거나 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를 사고 예산 이상으로 높입니다2560* `MAX_THINKING_TOKENS`를 낮추거나 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를 생각 예산 이상으로 높입니다.
2393* [확장 사고](/docs/ko/model-config#extended-thinking)에서 예산이 출력 길이와 상호 작용하는 방식을 참조하십시오2561* [확장 생각](/docs/ko/model-config#extended-thinking)에서 예산이 출력 길이와 상호 작용하는 방식을 참조하십시오.
2394 2562
2395<h3 id="tool-use-or-thinking-block-mismatch">2563<h3 id="tool-use-or-thinking-block-mismatch">
2396 도구 사용 또는 사고 블록 불일치2564 도구 사용 또는 생각 블록 불일치
2397</h3>2565</h3>
2398 2566
2399대화 기록이 일관성 없는 상태로 API에 도달했습니다. 일반적으로 도구 호출이 중단되거나 턴이 스트림 중간에 편집된 후입니다.2567대화 기록이 일관성 없는 상태로 API에 도달했습니다. 일반적으로 도구 호출이 중단되거나 턴이 스트림 중간에 편집된 후입니다.
2413* Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.2581* Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.
2414* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/docs/ko/checkpointing)에서 체크포인트가 생성되고 복원되는 방식을 참조하십시오.2582* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/docs/ko/checkpointing)에서 체크포인트가 생성되고 복원되는 방식을 참조하십시오.
2415 2583
2584<h3 id="invalid-data-in-redacted-thinking-block">
2585 redacted\_thinking 블록의 유효하지 않은 데이터
2586</h3>
2587
2588API가 대화 기록의 이전 턴이 포함하는 `redacted_thinking` 블록을 허용할 수 없기 때문에 400으로 요청을 거부했습니다.
2589
2590```text theme={null}
2591API Error: 400 ... Invalid `data` in `redacted_thinking` block
2592```
2593
2594Claude Code는 대화의 이전 생각을 요청에서 제외하고 한 번 다시 시도하므로 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했고 모든 이후 턴이 동일한 오류로 실패했습니다.
2595
2596**할 일:**
2597
2598* v2.1.281 이상에 있고 모든 턴이 이 오류로 실패하면 `claude update`를 실행하고 세션을 재개합니다.
2599* 오류가 지속되면 `/clear`를 실행하여 블록을 포함하지 않는 대화를 시작합니다.
2600
2416<h3 id="unsupported-tool-content-removed">2601<h3 id="unsupported-tool-content-removed">
2417 지원되지 않는 도구 내용이 제거되었습니다2602 지원되지 않는 도구 내용이 제거되었습니다
2418</h3>2603</h3>
2419 2604
2420Claude Code가 Anthropic API에 직접 연결되고 저장된 세션을 로드하거나 미리 볼 때 Anthropic API가 수락하지 않는 도구 내용을 제거하고 두 사고 블록 사이에 제거된 내용이 있던 위치에 이 줄을 남깁니다:2605Claude Code가 Anthropic API에 직접 연결되고 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 내용을 제거하고 제거된 내용이 두 생각 블록 사이에 있던 위치에 이 줄을 남깁니다:
2421 2606
2422```text theme={null}2607```text theme={null}
2423[Unsupported tool content removed]2608[Unsupported tool content removed]
2424```2609```
2425 2610
2426이러한 내용은 일반적으로 [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 통해 설정된 타사 프록시가 다른 제공자의 도구 호출을 API 형식으로 변환할 때 API 형식으로 세션 파일에 도달합니다. 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 오류로 실패했습니다.2611이러한 내용은 일반적으로 다른 제공자의 도구 호출을 변환하는 [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 통해 설정된 타사 프록시인 API 형식으로 응답할 때 세션 파일에 도달합니다. 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 오류로 실패했습니다.
2427 2612
2428**할 일:**2613**할 일:**
2429 2614
2431* 재개된 세션의 모든 턴이 대신 400 오류로 실패하면 `claude update`를 실행하고 세션을 다시 재개합니다. v2.1.246 이전 버전은 내용을 제거하지 않습니다.2616* 재개된 세션의 모든 턴이 대신 400 오류로 실패하면 `claude update`를 실행하고 세션을 다시 재개합니다. v2.1.246 이전 버전은 내용을 제거하지 않습니다.
2432 2617
2433<h3 id="role-system-must-precede-an-assistant-message">2618<h3 id="role-system-must-precede-an-assistant-message">
2434 role 'system' must precede an 'assistant' message2619 역할 'system'은 'assistant' 메시지 앞에 와야 합니다
2435</h3>2620</h3>
2436 2621
2437API가 대화에서 수락하지 않는 위치에 시스템 메시지가 있기 때문에 400으로 요청을 거부했습니다:2622API가 대화에서 허용하지 않는 위치에 시스템 메시지가 있기 때문에 400으로 요청을 거부했습니다:
2438 2623
2439```text theme={null}2624```text theme={null}
2440API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...2625API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...
2441```2626```
2442 2627
2443Claude Code는 일부 미리 알림 및 첨부 텍스트를 대화 내 시스템 메시지로 보냅니다. API가 하나의 위치를 거부하면 Claude Code는 요청을 한 번 다시 시도하고 해당 텍스트를 일반 사용자 메시지로 대신 보냅니다. `top-level 'system' parameter for the initial system prompt` 사용과 같은 API의 형제 배치 표현은 동일한 복구를 받습니다.2628Claude Code는 일부 미리 알림 및 첨부 텍스트를 대화 내 시스템 메시지로 보냅니다. API가 하나의 위치를 거부하면 Claude Code는 해당 텍스트를 대신 일반 사용자 메시지로 보내는 요청을 한 번 다시 시도합니다. API의 형제 배치 표현(예: `use the top-level 'system' parameter for the initial system prompt`)은 동일한 복구를 받습니다.
2444 2629
2445오류가 나타나면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 일반적으로 Claude Code와 API 사이의 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)가 시스템 메시지를 추가했거나 대화를 재정렬했음을 의미합니다.2630오류가 나타나면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 일반적으로 Claude Code와 API 사이의 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했거나 대화를 재정렬했음을 의미합니다.
2446 2631
2447**할 일:**2632**할 일:**
2448 2633
2449* `/clear`를 실행하여 새 대화를 시작합니다. 오류가 거기서도 돌아오면 원인은 저장된 대화가 아닌 요청 경로에 있습니다.2634* `/clear`를 실행하여 새 대화를 시작합니다. 오류가 거기서도 반환되면 원인은 저장된 대화가 아닌 요청 경로에 있습니다.
2450* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 통해 구성된 프록시 또는 게이트웨이 뒤에서 오류가 모든 턴에서 반복되면 프록시 없이 연결하여 원인을 확인하고 오류를 운영하는 사람에게 보고합니다2635* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 통해 구성된 프록시 또는 게이트웨이 뒤에서 오류가 모든 턴에서 반복되면 프록시 없이 연결하여 소스를 확인하고 오류를 운영하는 사람에게 보고합니다.
2451 2636
2452v2.1.280 이전에는 Claude Code가 이 표현을 인식하지 못했으므로 거부된 시스템 메시지가 Claude Code 자체가 보낸 것일 때도 오류가 나타났고 대화의 모든 이후 턴이 동일한 방식으로 실패했습니다.2637v2.1.280 이전에는 Claude Code가 이 표현을 인식하지 못했으므로 거부된 시스템 메시지가 Claude Code 자체가 보낸 것일 때도 오류가 나타났고 대화의 모든 이후 턴이 동일한 방식으로 실패했습니다.
2453 2638
2454<h3 id="invalid-encrypted-content-in-search-result-block">2639<h3 id="invalid-encrypted-content-in-search-result-block">
2455 Invalid encrypted\_content in search\_result block2640 search\_result 블록의 유효하지 않은 encrypted\_content
2456</h3>2641</h3>
2457 2642
2458API가 대화 기록이 해독할 수 없는 호스팅된 웹 검색 내용을 보유하고 있기 때문에 400으로 요청을 거부했습니다. 표현은 읽을 수 없는 필드를 이름으로 지정합니다:2643API가 대화 기록이 보유한 호스팅된 웹 검색 내용을 해독할 수 없기 때문에 400으로 요청을 거부했습니다. 표현은 읽을 수 없는 필드를 표시합니다:
2459 2644
2460```text theme={null}2645```text theme={null}
2461API Error: 400 messages.21.content.0: Invalid `encrypted_content` in `search_result` block2646API Error: 400 ... Invalid `encrypted_content` in `search_result` block
2462API Error: 400 messages.21.content.3.citations.0: Invalid `encrypted_index` in `text` block2647API Error: 400 ... Invalid `encrypted_index` in `text` block
2463API Error: 400 Failed to decrypt web search result content2648API Error: 400 ... Failed to decrypt web search result content
2649API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block
2464```2650```
2465 2651
2466API의 호스팅된 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)의 결과는 API만 읽을 수 있는 암호화된 필드를 전달합니다. API는 다른 조직을 위해 생성된 내용과 같이 해독할 수 없는 내용을 재생하는 요청을 거부합니다.2652API의 호스팅된 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)의 결과는 API만 읽을 수 있는 암호화된 필드를 포함합니다. `encrypted_stdout` 표현은 이러한 결과를 읽은 호스팅된 코드 실행 프로그램의 출력을 표시하며, API는 이를 암호화합니다. API는 해독할 수 없는 내용(예: 다른 조직을 위해 생성된 내용)을 재생하는 요청을 거부합니다.
2467 2653
2468Claude Code의 자체 [WebSearch 도구](/docs/ko/tools-reference#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로 이러한 블록은 일반적으로 호스팅된 웹 검색을 자체적으로 실행한 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 대화에 도달합니다.2654Claude Code의 자체 [WebSearch 도구](/docs/ko/tools-reference#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로 이러한 블록은 일반적으로 호스팅된 웹 검색을 자체적으로 실행한 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 대화에 도달합니다.
2469 2655
2470거부된 블록은 대화 기록에 남아 있으므로 모든 이후 턴과 `/compact`는 동일한 방식으로 실패합니다.2656세 가지 웹 검색 표현의 경우 Claude Code는 검색 호출, 결과 및 인용을 보내는 것에서 제외하고 요청을 한 번 다시 시도하므로 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 표현에는 그러한 복구가 없으므로 해당 메시지는 여전히 도달합니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했고 모든 이후 턴 및 `/compact`가 동일한 방식으로 실패했습니다.
2471 2657
2472**할 일:**2658**할 일:**
2473 2659
2474* `/clear`를 실행하거나 새 세션을 시작합니다. 새 대화는 거부된 블록을 전달하지 않습니다2660* v2.1.281 이상에 있고 모든 턴이 웹 검색 표현 중 하나로 실패하면 `claude update`를 실행하고 세션을 재개합니다.
2475* Claude Code를 프록시 또는 게이트웨이 뒤에서 실행하면 오류를 운영하는 사람에게 보고합니다2661* 오류가 지속되거나 메시지가 `encrypted_stdout`을 표시하면 `/rewind`를 실행하여 내용을 추가한 턴 전의 체크포인트로 뒤로 이동하거나 `/clear`를 실행하여 이를 포함하지 않는 대화를 시작합니다.
2662* Claude Code를 프록시 또는 게이트웨이 뒤에서 실행하면 오류를 운영하는 사람에게 보고합니다.
2476 2663
2477<h3 id="usage-policy-refusal">2664<h3 id="usage-policy-refusal">
2478 사용 정책 거부2665 사용 정책 거부
2479</h3>2666</h3>
2480 2667
2481API가 대화의 내용이 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 응답을 거부했습니다. 메시지에는 거부가 잘못되었다고 생각하면 지원팀에 인용할 수 있는 요청 ID가 포함됩니다.2668API가 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거한 대화의 내용 때문에 응답을 거부했습니다.
2669
2670메시지에는 정책 거부가 잘못되었다고 생각하는 경우 지원팀에 인용할 수 있는 요청 ID 및 메시지 ID가 포함됩니다.
2482 2671
2483```text theme={null}2672```text theme={null}
2484API Error: Opus 4.6 can't help with this. Start a new session to continue.2673API Error: Opus 4.6 can't help with this. Start a new session to continue.
2486Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup2675Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup
2487```2676```
2488 2677
2489메시지는 거부한 모델을 이름으로 지정하거나 모델이 기록되지 않으면 `Claude`를 이름으로 지정합니다.2678메시지는 거부한 모델을 표시하거나 모델이 기록되지 않은 경우 `Claude`를 표시합니다.
2490 2679
2491확인은 최신 프롬프트뿐만 아니라 전체 대화를 평가하므로 동일한 세션에서 새 메시지를 보내면 일반적으로 동일한 거부를 다시 트리거합니다. 동일한 내용이 디스크의 기록에 여전히 포함되어 있으므로 세션을 종료하고 `--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)를 참조하십시오.2680확인은 전체 대화를 평가하므로 같은 세션에서 새 메시지를 보내면 일반적으로 동일한 거부를 다시 트리거합니다. 동일한 내용이 디스크의 기록에 여전히 포함되어 있으므로 `--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)를 참조하십시오.
2492 2681
2493v2.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.`로 읽혔습니다.2682v2.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.`로 읽었습니다.
2494 2683
2495**할 일:**2684**할 일:**
2496 2685
2497* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다시 표현하거나 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.2686* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다시 표현하거나 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.
2498* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.2687* 어떤 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.
2499* [비대화형 모드](/docs/ko/headless)(`-p`)에서 되감기를 사용할 수 없으므로 `--continue` 없이 새 세션에서 다시 표현된 프롬프트로 다시 시도합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.2688* [비대화형 모드](/docs/ko/headless)(`-p`)에서 되감기를 사용할 수 없으므로 새 세션에서 `--continue` 없이 다시 표현된 프롬프트로 다시 시도합니다. 정책 확인은 모델에 따라 다르므로 `/model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.
2500 2689
2501<h3 id="safety-measures-flagged-a-cybersecurity-topic">2690<h3 id="safety-measures-flagged-a-cybersecurity-topic">
2502 안전 조치가 사이버 보안 주제를 플래그했습니다2691 안전 조치가 사이버 보안 주제를 플래그했습니다
2503</h3>2692</h3>
2504 2693
2505모델의 안전 조치가 대화의 내용을 사이버 보안 주제로 플래그했습니다. 메시지는 요청을 플래그한 모델을 이름으로 지정합니다:2694모델의 안전 조치가 대화의 내용을 사이버 보안 주제로 플래그했습니다. 메시지는 요청을 플래그한 모델을 표시합니다:
2506 2695
2507```text theme={null}2696```text theme={null}
2508API 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. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude2697API 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. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude
2509```2698```
2510 2699
2511메시지는 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)에 연결되며, 이는 합법적인 사이버 보안 작업에 대한 액세스를 부여합니다. Opus 5.5에서는 v2.1.280 이상이 필요하며, 메시지는 `Opus 5.5's safeguards flagged this session` 대신 시작됩니다. 플래그된 카테고리에 대체 모델을 사용할 수 있으면 Claude Code는 이 오류를 표시하는 대신 [모델을 전환](/docs/ko/model-config#automatic-model-fallback)합니다.2700메시지는 정당한 사이버 보안 작업에 대한 액세스를 부여하는 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)에 연결됩니다. Opus 5.5 및 Sonnet 5.5에서 메시지는 `<model>'s safeguards flagged this session`으로 시작합니다. 플래그된 범주에 대체 모델을 사용할 수 있으면 Claude Code는 이 오류를 표시하는 대신 [모델을 전환합니다](/docs/ko/model-config#automatic-model-fallback).
2512 2701
2513[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 및 [Microsoft Foundry](/docs/ko/microsoft-foundry)에서 사이버 보안 플래그는 대신 [사용 정책 거부](#usage-policy-refusal) 메시지를 생성합니다.2702[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 및 [Microsoft Foundry](/docs/ko/microsoft-foundry)에서 사이버 보안 플래그는 대신 [사용 정책 거부](#usage-policy-refusal) 메시지를 생성합니다.
2514 2703
2515안전 조치 자체는 서버 측이며 v2.1.203보다 앞서 있습니다. 이후 클라이언트 릴리스는 메시지의 표현만 변경했습니다.2704안전 조치 자체는 서버 측이며 v2.1.203보다 앞서 있습니다. 그 이후의 클라이언트 릴리스는 메시지의 표현만 변경했습니다.
2516v2.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.`를 추가했습니다.2705v2.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.`를 추가했습니다.
2517v2.1.203 이전에는 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:`로 읽혔고 면제 양식 링크가 뒤따랐습니다.2706v2.1.203 이전에는 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:`로 읽었고 면제 양식 링크가 뒤따랐습니다.
2518 2707
2519**할 일:**2708**할 일:**
2520 2709
2521* 작업에 이 내용이 필요하면 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다2710* 작업에 이 내용이 필요하면 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다.
2522* 요청이 사이버 보안 주제가 아닌 경우 `/feedback`을 실행하여 거짓 양성을 보고합니다2711* 요청이 사이버 보안 주제가 아니었으면 `/feedback`을 실행하여 거짓 양성을 보고합니다.
2523* 동일한 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.2712* 같은 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.
2524 2713
2525<h2 id="installation-errors">2714<h2 id="installation-errors">
2526 설치 오류2715 설치 오류
2573 명령줄 오류2762 명령줄 오류
2574</h2>2763</h2>
2575 2764
2576이러한 오류는 `claude` 명령줄과 그 하위 명령어에서 발생하며, 프롬프트에서 제출한 명령어 이름에서도 발생합니다. 또한 셸 명령어를 실행하여 컨텍스트를 수집한 후 프롬프트를 실행하는 `/security-review` 같은 명령어에서도 발생합니다. 이들은 CLI를 다시 시작하는 `/tui`에서도 발생합니다.2765이러한 오류는 `claude` 명령줄과 그 하위 명령어, 프롬프트에서 제출하는 명령어 이름, 그리고 셸 명령어를 실행하여 컨텍스트를 수집한 후 프롬프트를 실행하는 `/security-review` 같은 명령어에서 발생합니다. 또한 CLI를 다시 시작하는 `/tui`에서도 발생합니다.
2577 2766
2578<h3 id="conflict-between-bg-and-print">2767<h3 id="conflict-between-bg-and-print">
2579 \--bg와 --print 간의 충돌2768 \--bg와 --print 간의 충돌
2580</h3>2769</h3>
2581 2770
2582이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 연결할 수 있는 [백그라운드 세션](/docs/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형](/docs/ko/headless)으로 실행되며 `claude agents`가 연결할 수 있는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 조용히 생성했습니다.2771이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 연결할 수 있는 [백그라운드 세션](/docs/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형](/docs/ko/headless)으로 실행되며 `claude agents`가 연결할 수 있는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 자동으로 생성했습니다.
2583 2772
2584```text theme={null}2773```text theme={null}
2585--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.2774--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.
2587 2776
2588**해야 할 일:**2777**해야 할 일:**
2589 2778
2590* `-p` 또는 `--print`를 제거하세요. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령어입니다. [셸에서 새 에이전트 디스패치](/docs/ko/agent-view#from-your-shell)를 참조하세요.2779* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령어입니다. [셸에서 새 에이전트 디스패치](/docs/ko/agent-view#from-your-shell)를 참조하세요.
2591* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 생성하는 대신 결과를 인쇄하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행하세요.2780* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 만드는 대신 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다.
2592 2781
2593<h3 id="invalid-agents-configuration">2782<h3 id="invalid-agents-configuration">
2594 잘못된 --agents 구성2783 잘못된 --agents 구성
2595</h3>2784</h3>
2596 2785
2597`--agents`에 전달한 값이 유효하지 않아서 `claude`가 세션을 시작하는 대신 코드 1로 종료됩니다. `--safe-mode`, `--resume`, 또는 `--continue`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars#variables)를 설정하면 Claude Code는 값을 확인하지 않고 세션을 시작합니다. v2.1.242 이전에는 Claude Code가 어쨌든 세션을 시작했고 로드할 수 없는 정의를 생략했습니다.2786`--agents`에 전달한 값이 유효하지 않아서 `claude`가 세션을 시작하는 대신 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 확인되지 않고 세션이 시작됩니다. 파일에서 읽은 값은 매번 시작할 때 확인됩니다. v2.1.242 이전에는 Claude Code가 어쨌든 세션을 시작했고 로드할 수 없는 정의를 생략했습니다.
2598 2787
2599```text theme={null}2788```text theme={null}
2600Error: Invalid --agents configuration:2789Error: Invalid --agents configuration:
2601<what failed>2790<what failed>
2602```2791```
2603 2792
2604첫 번째 줄 다음에 오는 내용은 값이 어떻게 실패했는지에 따라 다릅니다. Claude Code는 이러한 확인을 순서대로 실행하고 실패하는 첫 번째 확인에서 중지합니다. 값에 두 가지 문제가 있으면 첫 번째를 수정한 후에만 두 번째를 볼 수 있습니다:2793첫 번째 줄 다음에 오는 내용은 값이 어떻게 실패했는지에 따라 달라집니다. Claude Code는 이러한 확인을 순서대로 실행하고 실패하는 첫 번째 확인에서 중지합니다. 값에 두 가지 문제가 있으면 첫 번째를 수정한 후에만 두 번째를 볼 수 있습니다:
2605 2794
26061. 값이 JSON으로 파싱되지 않으면 Claude Code는 JSON 파서의 메시지를 포함하는 `invalid JSON:` 줄 하나를 인쇄합니다.27951. 값이 `{`로 시작하지만 JSON으로 파싱되지 않거나 `--agents` 파일의 내용이 파싱되지 않으면 Claude Code는 JSON 파서의 메시지를 포함하는 `invalid JSON:` 줄 하나를 출력합니다.
26072. 파싱되지만 에이전트 정의가 [CLI 정의 하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)의 스키마와 일치하지 않으면 Claude Code는 문제당 한 줄을 인쇄합니다.27962. 파싱되지만 에이전트 정의가 [CLI 정의 하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)의 스키마와 일치하지 않으면 Claude Code는 문제당 한 줄을 출력합니다.
26083. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 인쇄합니다.27973. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다.
2609 2798
2610문제 줄이 20개를 초과하면 Claude Code는 처음 20개를 인쇄하고 나머지를 `…and N more`로 바꿉니다.2799문제 줄이 20개를 초과하면 Claude Code는 처음 20개를 출력하고 나머지를 `…and N more`로 바꿉니다.
2800
2801`--print`를 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일의 경로](/docs/ko/sub-agents#choose-the-subagent-scope)도 허용합니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 허용했고 파일 경로를 유효하지 않은 JSON으로 취급했습니다. 파일 형식에는 이 메시지 대신 출력되는 자체 거부가 있습니다:
2802
2803* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: Claude Code가 대화형 세션에서 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나 `-p`를 추가하여 파일에서 읽습니다.
2804* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽혀지므로 셸이 손상시킨 인라인 JSON도 이런 식으로 실패할 수 있습니다. 경로 또는 인용을 확인하고 명령어를 다시 실행합니다.
2611 2805
2612**해야 할 일:**2806**해야 할 일:**
2613 2807
2614* 메시지가 나열한 각 문제를 수정한 후 명령어를 다시 실행하세요. [CLI 정의 하위 에이전트가 사용하는 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.2808* 메시지가 나열한 각 문제를 수정한 후 명령어를 다시 실행합니다. [CLI 정의 하위 에이전트가 사용하는 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.
2615 2809
2616<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">2810<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">
2617 클라우드 세션을 --restricted 세션에서 생성할 수 없음2811 클라우드 세션을 --restricted 세션에서 만들 수 없음
2618</h3>2812</h3>
2619 2813
2620[`--restricted`](/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 이 세션에서 [클라우드 세션](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)을 생성하기를 거부합니다. 새 세션이 제한된 프로세스 외부에서 실행되고 제한된 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:2814[`--restricted`](/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 이 세션에서 [클라우드 세션](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션이 제한된 프로세스 외부에서 실행되고 제한된 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:
2621 2815
2622```text theme={null}2816```text theme={null}
2623Cloud sessions cannot be created from a --restricted session: they would not enforce it.2817Cloud sessions cannot be created from a --restricted session: they would not enforce it.
2625 2819
2626**해야 할 일:**2820**해야 할 일:**
2627 2821
2628* 제한된 세션에서 로컬로 작업을 실행하세요.2822* 제한된 세션에서 로컬로 작업을 실행합니다.
2629* 세션이 어떻게 시작되었는지 제어할 수 있으면 `--restricted` 없이 새 `claude` 세션을 시작하고 거기서 클라우드 세션을 생성하세요.2823* 세션이 어떻게 시작되었는지 제어할 수 있으면 `--restricted` 없이 새 `claude` 세션을 시작하고 거기서 클라우드 세션을 만듭니다.
2630 2824
2631v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.2825v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었고 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부했습니다.
2632 2826
2633<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">2827<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">
2634 조직의 정책에 의해 클라우드 세션이 비활성화됨2828 조직의 정책에 의해 클라우드 세션이 비활성화됨
2640Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.2834Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.
2641```2835```
2642 2836
2643이 메시지는 [터미널에서 클라우드 세션을 생성](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)할 때 나타나며 `/teleport`, `/remote-env`, 또는 `/web-setup` 같은 클라우드 세션이 필요한 명령어를 제출할 때도 나타납니다. v2.1.268 이전에는 이러한 명령어 중 하나를 제출하면 대신 [`Unknown command`](#unknown-command)를 반환했습니다.2837메시지는 [터미널에서 클라우드 세션을 만들](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud) 때 나타나고 `/teleport`, `/remote-env`, 또는 `/web-setup` 같은 클라우드 세션이 필요한 명령어를 제출할 때 나타납니다. v2.1.268 이전에는 이러한 명령어 중 하나를 제출하면 대신 [`Unknown command`](#unknown-command)를 반환했습니다.
2644 2838
2645이것은 서버 측 조직 정책이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.2839이것은 서버 측 조직 정책이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.
2646 2840
2648 2842
2649**해야 할 일:**2843**해야 할 일:**
2650 2844
2651* 조직의 [Owner](/docs/ko/server-managed-settings#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청하세요.2845* 조직의 [Owner](/docs/ko/server-managed-settings#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청합니다.
2652* 메시지가 정책을 확인할 수 없다고 하면 네트워크 연결을 확인한 후 Claude Code를 다시 시작하고 다시 시도하세요.2846* 메시지에서 정책을 확인할 수 없다고 하면 네트워크 연결을 확인한 후 Claude Code를 다시 시작하고 다시 시도합니다.
2653 2847
2654<h3 id="the-json-schema-value-is-not-a-valid-json-schema">2848<h3 id="the-json-schema-value-is-not-a-valid-json-schema">
2655 \--json-schema 값이 유효한 JSON Schema가 아님2849 \--json-schema 값이 유효한 JSON Schema가 아님
2656</h3>2850</h3>
2657 2851
2658[비대화형 모드](/docs/ko/headless#get-structured-output)에서 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하는 대신 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용한 모든 스키마는 유효하지 않은 것으로 처리되었습니다.2852[비대화형 모드](/docs/ko/headless#get-structured-output)에서 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하는 대신 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했고 `format` 키워드를 사용하는 모든 스키마는 유효하지 않은 것으로 처리되었습니다.
2659 2853
2660```text theme={null}2854```text theme={null}
2661Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values2855Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values
2662```2856```
2663 2857
2664두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 이름 지정합니다. `"format": "email"` 같은 `format` 키워드를 사용하는 스키마는 유효합니다: Claude Code는 `format`을 주석으로 수용하고 적용하지 않습니다.2858두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 이름 지정합니다. `"format": "email"` 같은 `format` 키워드를 사용하는 스키마는 유효합니다: Claude Code는 `format`을 주석으로 허용하고 적용하지 않습니다.
2665 2859
2666Claude Code는 스키마 컴파일 전에 두 가지 확인을 실행합니다: 파싱 불가능한 JSON 값을 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON을 `Error: --json-schema must be a JSON object`로 거부합니다.2860Claude Code는 스키마 컴파일 전에 두 가지 확인을 실행합니다: 파싱할 수 없는 JSON 값을 `Error: --json-schema is not valid JSON`으로 거부하고 유효한 JSON이지만 객체가 아닌 것을 `Error: --json-schema must be a JSON object`로 거부합니다.
2667 2861
2668**해야 할 일:**2862**해야 할 일:**
2669 2863
2670* 진단이 이름 지정한 스키마 부분을 수정한 후 명령어를 다시 실행하세요.2864* 진단이 이름 지정한 스키마 부분을 수정한 후 명령어를 다시 실행합니다.
2671* 진단이 `schema too large`이면 스키마의 중첩과 `$ref` 재사용을 줄이세요.2865* 진단이 `schema too large`이면 스키마의 중첩과 `$ref` 재사용을 줄입니다.
2672* [구조화된 출력 가져오기](/docs/ko/headless#get-structured-output)에서 작동하는 스키마와 명령어를 참조하세요.2866* [구조화된 출력 가져오기](/docs/ko/headless#get-structured-output)에서 작동하는 스키마와 명령어를 참조하세요.
2673 2867
2674<h3 id="settings-file-exceeds-the-2mib-limit">2868<h3 id="settings-file-exceeds-the-2mib-limit">
2675 설정 파일이 2MiB 제한을 초과함2869 설정 파일이 2MiB 제한을 초과함
2676</h3>2870</h3>
2677 2871
2678[`--settings`](/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 크므로 `claude`가 로드하는 대신 시작 시 코드 1로 종료됩니다. 설정 파일은 작은 JSON 문서이므로 이 크기의 파일은 보통 경로가 잘못된 파일을 가리킵니다. v2.1.214 이전에는 Claude Code가 크기 확인 없이 파일을 읽었으며, 수 기가바이트 파일이나 `/dev/zero` 같은 장치 파일이 메모리를 무한정 증가시켰습니다.2872[`--settings`](/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 크므로 `claude`가 시작 시 코드 1로 종료되고 로드하지 않습니다. 설정 파일은 작은 JSON 문서이므로 이 크기의 파일은 보통 경로가 잘못된 파일을 가리킵니다. v2.1.214 이전에는 Claude Code가 크기 확인 없이 파일을 읽었고 수 기가바이트 파일이나 `/dev/zero` 같은 장치 파일이 메모리를 무한정 증가시켰습니다.
2679 2873
2680```text theme={null}2874```text theme={null}
2681Error: Settings file exceeds the 2MiB limit: /path/to/settings.json2875Error: Settings file exceeds the 2MiB limit: /path/to/settings.json
2682```2876```
2683 2877
2684Claude Code는 일반 파일이 아닌 `--settings` 경로를 같은 방식으로 거부합니다: 장치, FIFO 또는 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`을 보고하고 경로를 따르며, 디렉토리는 `EISDIR` 이유를 보고합니다.2878Claude Code는 일반 파일이 아닌 `--settings` 경로를 같은 방식으로 거부합니다: 장치, FIFO 또는 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`을 보고하고 경로를 따르며 디렉토리는 `EISDIR` 이유를 보고합니다.
2685 2879
2686**해야 할 일:**2880**해야 할 일:**
2687 2881
2688* `--settings`를 2MiB 미만의 일반 JSON 설정 파일로 지정하세요. 형식은 [설정](/docs/ko/settings)을 참조하세요.2882* `--settings`를 2MiB 미만의 일반 JSON 설정 파일로 지정합니다. 형식은 [설정](/docs/ko/settings)을 참조하세요.
2689 2883
2690<h3 id="the-current-directory-no-longer-exists">2884<h3 id="the-current-directory-no-longer-exists">
2691 현재 디렉토리가 더 이상 존재하지 않음2885 현재 디렉토리가 더 이상 존재하지 않음
2692</h3>2886</h3>
2693 2887
2694셸이 디렉토리에 들어간 후 삭제되거나 이동된 디렉토리에서 `claude`를 시작했습니다. 예를 들어 worktree 또는 다른 셸이 제거한 임시 디렉토리입니다. Claude Code가 작업 디렉토리를 읽을 수 없어서 대화형 및 [비대화형](/docs/ko/headless) 모드 모두에서 세션을 시작하기 전에 코드 1로 종료됩니다. v2.1.239 이전에는 Claude Code가 축소된 번들 소스와 stderr의 원본 `ENOENT ... uv_cwd` 스택으로 충돌했습니다.2888셸이 디렉토리에 들어간 후 삭제되거나 이동된 디렉토리에서 `claude`를 시작했습니다. 예를 들어 다른 셸이 제거한 worktree 또는 임시 디렉토리입니다. Claude Code가 작업 디렉토리를 읽을 수 없으므로 대화형 및 [비대화형](/docs/ko/headless) 모드 모두에서 세션을 시작하기 전에 코드 1로 종료됩니다. v2.1.239 이전에는 Claude Code가 축소된 번들 소스와 stderr의 원시 `ENOENT ... uv_cwd` 스택으로 충돌했습니다.
2695 2889
2696```text theme={null}2890```text theme={null}
2697The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.2891The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
2700 2894
2701원인과 해결책은 두 형식 모두 동일합니다.2895원인과 해결책은 두 형식 모두 동일합니다.
2702 2896
2703Claude Code가 다른 이유(예: 권한 변경)로 작업 디렉토리를 읽을 수 없으면 메시지가 오류 코드를 이름 지정합니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`2897Claude Code가 권한 변경 같은 다른 이유로 작업 디렉토리를 읽을 수 없으면 메시지는 오류 코드를 이름 지정합니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`
2704 2898
2705macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive의 디렉토리에 대한 `EPERM`은 보통 macOS가 터미널 앱을 해당 폴더에서 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령어도 같은 방식으로 실패합니다: `ls`는 `sudo`를 사용해도 `Operation not permitted`를 보고합니다.2899macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive의 디렉토리에 대한 `EPERM`은 보통 macOS가 터미널 앱을 해당 폴더에서 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령어도 같은 방식으로 실패합니다: `ls`는 `sudo`를 사용해도 `Operation not permitted`를 보고합니다.
2706 2900
2707**해야 할 일:**2901**해야 할 일:**
2708 2902
2709* 홈 또는 프로젝트 디렉토리 같은 존재하는 디렉토리로 변경한 후 `claude`를 다시 실행하세요.2903* 홈 또는 프로젝트 디렉토리 같은 존재하는 디렉토리로 변경한 후 `claude`를 다시 실행합니다.
2710* 디렉토리가 같은 경로에서 다시 생성되었으면 셸이 여전히 삭제된 디렉토리를 보유하고 있습니다. `cd "$PWD"`를 실행하거나 디렉토리를 나갔다가 다시 들어간 후 `claude`를 실행하세요.2904* 디렉토리가 같은 경로에서 다시 생성되었으면 셸이 여전히 삭제된 것을 보유합니다. `cd "$PWD"`를 실행하거나 디렉토리를 나갔다가 다시 들어간 후 `claude`를 다시 실행합니다.
2711* macOS에서 `EPERM`의 경우 Cmd+Q로 터미널 앱을 종료하고 다시 열어서 해당 폴더로 돌아가 `claude`를 실행하세요. 해당 폴더의 `ls`가 여전히 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대한 폴더를 켠 후 터미널을 다시 열어세요.2905* macOS의 `EPERM`의 경우 Cmd+Q로 터미널 앱을 종료하고 다시 열고 해당 폴더로 돌아가 `claude`를 실행합니다. 해당 폴더의 `ls`가 여전히 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대한 폴더를 켠 후 터미널을 다시 엽니다.
2712 2906
2713<h3 id="temp-directory-refused-or-cannot-be-created">2907<h3 id="temp-directory-refused-or-cannot-be-created">
2714 임시 디렉토리가 거부되었거나 생성할 수 없음2908 임시 디렉토리가 거부되었거나 만들 수 없음
2715</h3>2909</h3>
2716 2910
2717macOS 및 Linux에서 Claude Code는 시작 시 개인 임시 디렉토리를 생성합니다. 시스템 임시 디렉토리 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars) 재정의 아래의 `claude-<uid>`입니다. 디렉토리를 생성할 수 없거나 해당 경로의 항목이 안전 확인에 실패하면 Claude Code는 실패를 stderr에 인쇄하고 세션을 시작하는 대신 코드 1로 종료됩니다:2911macOS 및 Linux에서 Claude Code는 시작 시 시스템 임시 디렉토리 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars) 재정의 아래에 `claude-<uid>` 개인 임시 디렉토리를 만듭니다. 디렉토리를 만들 수 없거나 해당 경로의 항목이 안전 확인에 실패하면 Claude Code는 세션을 시작하는 대신 실패를 stderr에 출력하고 코드 1로 종료됩니다:
2718 2912
2719```text wrap theme={null}2913```text wrap theme={null}
2720ENOSPC: no space left on device, mkdir '/tmp/claude-501'2914ENOSPC: no space left on device, mkdir '/tmp/claude-501'
2728 2922
2729**해야 할 일:**2923**해야 할 일:**
2730 2924
2731* `ENOSPC`의 경우 임시 디렉토리를 보유한 볼륨의 디스크 공간을 확보하세요.2925* `ENOSPC`의 경우 임시 디렉토리를 보유하는 볼륨의 디스크 공간을 확보합니다.
2732* `Refusing to use it` 형식의 경우 링크가 가리키는 것이 아닌 이름 지정된 항목 자체를 제거하고 Claude Code를 다시 시작하세요. `owned by uid` 형식의 경우 관리자 또는 해당 사용자만 제거할 수 있습니다.2926* `Refusing to use it` 형식의 경우 링크가 가리키는 것이 아니라 이름 지정된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자 또는 해당 사용자만 제거할 수 있습니다.
2733* `is not readable`의 경우 이름 지정된 디렉토리에서 `chmod 0700`을 실행하거나 제거한 후 다시 시작하세요.2927* `is not readable`의 경우 이름 지정된 디렉토리에서 `chmod 0700`을 실행하거나 제거하고 다시 시작합니다.
2734* 이러한 경우 중 하나에서 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 제어하는 디렉토리로 설정하고 Claude Code를 시작하세요. 거부된 경로는 그대로 두세요.2928* 이러한 경우 중 하나에서 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 제어하는 디렉토리로 설정하고 Claude Code를 시작하여 거부된 경로를 그대로 둡니다.
2735 2929
2736<h3 id="directory-couldnt-be-resolved-to-a-real-location">2930<h3 id="directory-couldnt-be-resolved-to-a-real-location">
2737 디렉토리를 실제 위치로 확인할 수 없음2931 디렉토리를 실제 위치로 확인할 수 없음
2738</h3>2932</h3>
2739 2933
2740작업 디렉토리의 하위 디렉토리에 대해 `/add-dir`을 실행했는데 Claude Code가 디렉토리를 실제 위치로 확인할 수 없습니다.2934작업 디렉토리의 하위 디렉토리에 대해 `/add-dir`을 실행했고 Claude Code가 디렉토리를 실제 위치로 확인할 수 없습니다.
2741 2935
2742작업 디렉토리의 하위 디렉토리에 대한 파일 액세스가 이미 있으므로 `/add-dir`은 해당 스킬, 명령어 및 에이전트만 로드합니다. 로드하기 전에 Claude Code는 심볼릭 링크가 확인된 디렉토리의 실제 위치가 작업 디렉토리 내부에 있는지 확인합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 로드하지 않고 이 메시지를 표시합니다:2936작업 디렉토리의 하위 디렉토리에 이미 파일 액세스 권한이 있으므로 `/add-dir`은 해당 스킬, 명령어 및 에이전트만 로드합니다. 로드하기 전에 Claude Code는 심볼릭 링크가 확인된 디렉토리의 실제 위치가 작업 디렉토리 내부에 있는지 확인합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 로드하지 않고 이 메시지를 표시합니다:
2743 2937
2744```text theme={null}2938```text theme={null}
2745packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.2939packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.
2747 2941
2748**해야 할 일:**2942**해야 할 일:**
2749 2943
2750* 경로가 작업 디렉토리 내부의 실제 디렉토리를 이름 지정하는지 확인한 후 `/add-dir`을 다시 실행하세요.2944* 경로가 작업 디렉토리 내부의 실제 디렉토리를 이름 지정하는지 확인한 후 `/add-dir`을 다시 실행합니다.
2751* 메시지는 파일 액세스를 변경하지 않습니다. 디렉토리의 `.claude/` 콘텐츠가 로드되지 않았음을 보고할 뿐입니다.2945* 메시지는 파일 액세스를 변경하지 않습니다. 디렉토리의 `.claude/` 콘텐츠가 로드되지 않았음을 보고할 뿐입니다.
2752 2946
2753v2.1.261 이전에는 작업 디렉토리가 `/net/<host>` 자동 마운트에 있을 때마다 이 메시지가 모든 `/add-dir <subdirectory>`에 대해 나타났습니다. Claude Code는 설계상 경로를 확인하기를 거부합니다. 디렉토리는 정상이었고 재시도할 수 없었습니다.2947v2.1.261 이전에는 작업 디렉토리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해 이 메시지가 나타났습니다. Claude Code는 설계상 경로를 확인하기를 거부합니다. 디렉토리는 정상이었고 재시도할 수 없었습니다.
2754 2948
2755<h3 id="workspace-not-trusted-when-starting-remote-control">2949<h3 id="workspace-not-trusted-when-starting-remote-control">
2756 Remote Control 시작 시 작업 공간을 신뢰하지 않음2950 Remote Control 시작 시 작업 영역을 신뢰하지 않음
2757</h3>2951</h3>
2758 2952
2759신뢰하지 않은 디렉토리에서 `claude remote-control` 또는 그 `claude rc` 별칭으로 [Remote Control](/docs/ko/remote-control) 서버 모드를 시작했습니다. 명령어는 작업 공간 신뢰 대화를 표시하지 않으므로 코드 1로 종료되고 수정 사항을 이름 지정합니다:2953신뢰하지 않은 디렉토리에서 `claude remote-control` 또는 그 `claude rc` 별칭으로 [Remote Control](/docs/ko/remote-control) 서버 모드를 시작했습니다. 명령어의 표준 입력 또는 표준 출력이 터미널이 아닐 때 이 메시지가 나타납니다. 예를 들어 하나가 리디렉션되거나 파이프되었을 때입니다. 명령어는 코드 1로 종료됩니다:
2760 2954
2761```text theme={null}2955```text theme={null}
2762Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.2956Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.
2763```2957```
2764 2958
2765홈 디렉토리에서 메시지가 다릅니다. 작업 공간 신뢰 대화가 홈 디렉토리에 대한 신뢰를 저장하지 않기 때문입니다. v2.1.214 이전에는 홈 디렉토리가 위의 메시지를 표시했으며, 그 조언은 거기서 성공할 수 없습니다.2959터미널에 나타나는 두 가지 변형도 신뢰 디렉토리를 켜는 것을 표시하기에 너무 작은 터미널이나 크기를 보고하지 않은 터미널에서 시작됩니다. 창을 확대하거나 일반 터미널 창으로 전환한 후 `claude rc`를 다시 실행합니다.
2960
2961홈 디렉토리에서 메시지는 다릅니다. 작업 영역 신뢰 대화가 홈 디렉토리에 대한 신뢰를 저장하지 않기 때문입니다. v2.1.214 이전에는 홈 디렉토리가 위의 메시지를 표시했고 그 조언은 거기서 성공할 수 없었습니다.
2766 2962
2767```text theme={null}2963```text theme={null}
2768Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).2964Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).
2769```2965```
2770 2966
2967[`Trust <directory>?` 질문](/docs/ko/remote-control#requirements)에서 `n`을 답하거나 Enter를 누르면 명령어는 디렉토리를 이름 지정하는 `Remote Control did not start` 메시지를 출력하고 코드 1로 종료됩니다. `claude rc`를 다시 실행하여 `y`를 답합니다.
2968
2771**해야 할 일:**2969**해야 할 일:**
2772 2970
2773* 디렉토리에서 `claude`를 실행하고 [작업 공간 신뢰 대화](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 수락한 후 `claude remote-control`을 다시 실행하세요.2971* 먼저 터미널에서 디렉토리를 신뢰합니다: 거기서 `claude rc`를 실행하고 `y`를 답하거나 거기서 `claude`를 실행하고 [작업 영역 신뢰 대화](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 수락한 후 원래 명령어를 다시 실행합니다.
2774* 홈 디렉토리에서 프로젝트 디렉토리로 변경하고 거기서 Remote Control을 시작하세요.2972* 홈 디렉토리에서 프로젝트 디렉토리로 변경하고 거기서 Remote Control을 시작합니다.
2973
2974v2.1.284 이전에는 명령어가 터미널에서도 묻지 않았습니다.
2775 2975
2776<h3 id="not-carried-over-to-the-sessions-remote-control-starts">2976<h3 id="not-carried-over-to-the-sessions-remote-control-starts">
2777 Remote Control이 시작하는 세션으로 이월되지 않음2977 Remote Control이 시작하는 세션으로 이월되지 않음
2778</h3>2978</h3>
2779 2979
2780`remote-control` 동사 앞에 전역 `claude` 플래그로 [Remote Control](/docs/ko/remote-control)을 시작했습니다. Remote Control이 시작하는 세션을 제한하거나 구성할 플래그입니다. 예를 들어 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools` 또는 `--mcp-config`입니다. 동사 앞에 배치된 플래그는 절대 이러한 세션에 도달하지 않습니다. Claude Code는 플래그를 이름 지정하는 대신 시작을 거부합니다:2980[Remote Control](/docs/ko/remote-control)을 `remote-control` 동사 앞의 전역 `claude` 플래그로 시작했습니다. Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 예를 들어 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools` 또는 `--mcp-config`입니다. 동사 앞에 배치된 플래그는 절대 이러한 세션에 도달하지 않습니다. Claude Code는 대신 시작을 거부하고 플래그를 이름 지정합니다:
2781 2981
2782```text theme={null}2982```text theme={null}
2783Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).2983Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).
2784```2984```
2785 2985
2786Claude Code는 `--verbose`, `--model` 또는 래퍼 주입 `--session-id` 또는 `--plugin-dir` 같은 드롭하기에 무해한 전역 플래그를 거부하지 않습니다: 이를 무시하고 Remote Control이 시작됩니다.2986Claude Code는 `--verbose`, `--model` 또는 래퍼 주입 `--session-id` 또는 `--plugin-dir` 같은 드롭하기에 무해한 전역 플래그를 거부하지 않습니다: 무시하고 Remote Control이 시작됩니다.
2787 2987
2788Claude Code는 또한 아직 무해한 것으로 인식하지 못하는 전역 플래그를 거부하므로 최신 릴리스에 추가된 플래그는 이후 릴리스가 이를 무해한 것으로 표시할 때까지 이 메시지에 나타날 수 있습니다.2988Claude Code는 또한 아직 무해한 것으로 인식하지 못하는 전역 플래그를 거부하므로 최신 릴리스에 추가된 플래그는 나중 릴리스가 무해한 것으로 표시할 때까지 이 메시지에 나타날 수 있습니다.
2789 2989
2790**해야 할 일:**2990**해야 할 일:**
2791 2991
2792* 동사 앞에서 플래그를 제거하고 [Remote Control의 자체 옵션](/docs/ko/remote-control#start-a-remote-control-session)을 그 뒤에 전달하세요. `claude remote-control --help`가 이를 나열합니다.2992* 동사 앞에서 플래그를 제거하고 [Remote Control의 자체 옵션](/docs/ko/remote-control#start-a-remote-control-session)을 그 뒤에 전달합니다. `claude remote-control --help`가 이를 나열합니다.
2793* 거부된 플래그가 `--permission-mode`이면 `claude remote-control --permission-mode <mode>`를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정하세요.2993* 거부된 플래그가 `--permission-mode`이면 `claude remote-control --permission-mode <mode>`를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다.
2794 2994
2795v2.1.248 이전에는 `claude remote-control`이 전역 플래그가 먼저 올 때 자체 플래그를 수용하지 않았으며, 명령어가 알 수 없는 옵션 오류로 실패했습니다.2995v2.1.248 이전에는 `claude remote-control`이 전역 플래그가 먼저 올 때 자체 플래그를 허용하지 않았고 명령어가 알 수 없는 옵션 오류로 실패했습니다.
2796 2996
2797<h3 id="claude-import-is-not-yet-available-in-this-build">2997<h3 id="claude-import-is-not-yet-available-in-this-build">
2798 claude import는 이 빌드에서 아직 사용할 수 없음2998 claude import는 이 빌드에서 아직 사용할 수 없음
2799</h3>2999</h3>
2800 3000
2801[`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했는데 Claude Code가 가져오기 흐름이 꺼져 있음을 발견했으므로 명령어가 이 메시지를 인쇄하는 대신 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드가 `import`를 프롬프트로 취급하고 이 메시지를 인쇄하는 대신 대화형 세션을 시작했습니다.3001[`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했고 Claude Code가 가져오기 흐름이 꺼져 있음을 발견했으므로 명령어가 이 메시지를 출력하는 대신 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드가 `import`를 프롬프트로 취급하고 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.
2802 3002
2803```text theme={null}3003```text theme={null}
2804`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.3004`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.
2805```3005```
2806 3006
2807Claude Code는 Anthropic에서 가져오고 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 보통 다음 중 하나입니다:3007Claude Code는 Anthropic에서 가져온 기능 플래그를 통해 `claude import`를 켜고 디스크에 캐시합니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 보통 다음 중 하나입니다:
2808 3008
2809* 설치 후 세션을 시작하지 않았으므로 Claude Code가 플래그를 아직 가져오지 않았습니다. 첫 번째 `claude import`는 기능을 사용할 수 있을 때도 이를 인쇄할 수 있습니다.3009* 설치 후 세션을 시작하지 않았으므로 Claude Code가 플래그를 아직 가져오지 않았습니다. 첫 번째 `claude import`는 기능을 사용할 수 있을 때도 이를 출력할 수 있습니다.
2810* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS를 통해 Claude Code를 사용하거나 [Claude apps gateway](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 사용합니다. Claude Code는 이러한 세션에서 기능 플래그를 가져오지 않으므로 `claude import`는 사용할 수 없습니다.3010* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS를 통해 Claude Code를 사용하거나 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 사용합니다. Claude Code는 이러한 세션에서 기능 플래그를 가져오지 않으므로 `claude import`는 사용할 수 없습니다.
2811* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)를 설정했으므로 기능 플래그 가져오기가 꺼져 있고 `claude import`는 사용할 수 없습니다.3011* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)를 설정했습니다. 이는 기능 플래그 가져오기를 끕니다. 따라서 `claude import`는 사용할 수 없습니다.
2812 3012
2813**해야 할 일:**3013**해야 할 일:**
2814 3014
2815* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 후 종료하고 `claude import`를 다시 실행하세요.3015* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 후 종료하고 `claude import`를 다시 실행합니다.
2816* 기능 플래그 가져오기가 꺼진 경우 구성을 직접 설정하세요: [`claude mcp add`](/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고 [CLAUDE.md 파일](/docs/ko/memory#how-claude-md-files-load), [스킬 및 명령어](/docs/ko/skills#where-skills-live) 및 [하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)를 생성하세요. 메시지는 또한 `~/.claude/settings.json`을 이름 지정합니다. `claude import`가 이월하는 구성 중에서 해당 파일은 [권한 모드](/docs/ko/settings-reference#permission-settings)만 보유합니다. Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.3016* 기능 플래그 가져오기가 꺼진 경우 구성을 직접 설정합니다: [`claude mcp add`](/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고 [`CLAUDE.md` 파일](/docs/ko/memory#how-claude-md-files-load), [스킬 및 명령어](/docs/ko/skills#where-skills-live) 및 [하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)를 만듭니다. 메시지는 또한 `~/.claude/settings.json`을 이름 지정합니다. `claude import`가 이월하는 구성 중에서 해당 파일은 [권한 모드](/docs/ko/settings-reference#permission-settings)만 보유합니다. Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.
2817 3017
2818<h3 id="could-not-read-claude-code-config">3018<h3 id="could-not-read-claude-code-config">
2819 Claude Code 구성을 읽을 수 없음3019 Claude Code 구성을 읽을 수 없음
2820</h3>3020</h3>
2821 3021
2822Claude Code가 로그인 및 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 동안 [`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했습니다. 하위 명령어는 가용성을 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화를 표시하지 않으므로 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 구성 파일이 있는 `claude import`가 대화형 세션을 시작했으며, 복구 대화가 파일을 처리했습니다.3022로그인 및 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 동안 [`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했습니다. 하위 명령어는 가용성을 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화를 표시하지 않으므로 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 구성 파일이 있는 `claude import`가 대화형 세션을 시작했고 복구 대화가 파일을 처리했습니다.
2823 3023
2824```text theme={null}3024```text theme={null}
2825Could not read Claude Code config — run `claude` with no arguments to recover it.3025Could not read Claude Code config — run `claude` with no arguments to recover it.
2827 3027
2828**해야 할 일:**3028**해야 할 일:**
2829 3029
2830* 인수 없이 `claude`를 실행하세요. Claude Code가 유효하지 않은 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행하세요.3030* 인수 없이 `claude`를 실행합니다. Claude Code가 유효하지 않은 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.
2831* 수동으로 편집한 내용을 유지하려면 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 후 `claude import`를 다시 실행하세요.3031* 수동으로 편집한 내용을 유지하려면 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 후 `claude import`를 다시 실행합니다.
2832 3032
2833<h3 id="could-not-import-a-server-from-claude-desktop">3033<h3 id="could-not-import-a-server-from-claude-desktop">
2834 Claude Desktop에서 서버를 가져올 수 없음3034 Claude Desktop에서 서버를 가져올 수 없음
2835</h3>3035</h3>
2836 3036
2837Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령어는 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버당 한 줄을 인쇄합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했고 선택된 서버 중 어느 것도 추가되지 않았습니다.3037Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령어는 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버당 한 줄을 출력합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했고 선택된 서버 중 어느 것도 추가되지 않았습니다.
2838 3038
2839```text theme={null}3039```text theme={null}
2840Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3040Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
2841```3041```
2842 3042
2843서버 이름 뒤의 텍스트가 이유입니다. 가장 일반적인 것은 이름 확인입니다: Claude Desktop은 서버 이름에 공백과 마침표 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈 및 밑줄로 제한합니다. 다른 이유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](/docs/ko/managed-mcp)에 의해 차단된 서버가 있습니다.3043서버 이름 뒤의 텍스트는 이유입니다. 가장 일반적인 것은 이름 확인입니다: Claude Desktop은 서버 이름에 공백 및 마침표 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈 및 밑줄로 제한합니다. 다른 이유로는 검증에 실패하는 서버 구성과 조직의 [MCP 정책](/docs/ko/managed-mcp)에 의해 차단된 서버가 있습니다.
2844 3044
2845**해야 할 일:**3045**해야 할 일:**
2846 3046
2847* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈 및 밑줄만 사용하도록 변경한 후 `claude mcp add-from-claude-desktop`을 다시 실행하세요.3047* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈 및 밑줄만 사용하도록 바꾼 후 `claude mcp add-from-claude-desktop`을 다시 실행합니다.
2848* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가하세요. [Claude Desktop에서 MCP 서버 가져오기](/docs/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.3048* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/docs/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.
2849 3049
2850<h3 id="cannot-add-mcp-server-to-the-managed-scope">3050<h3 id="cannot-add-mcp-server-to-the-managed-scope">
2851 MCP 서버를 관리 범위에 추가할 수 없음3051 MCP 서버를 관리 범위에 추가할 수 없음
2852</h3>3052</h3>
2853 3053
2854`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 해당 범위는 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 관리 설정을 통해 제공하는 서버를 보유합니다. Claude Code는 관리 설정에서만 이를 읽으므로 명령어가 해당 범위에 서버를 쓸 수 없습니다.3054`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 해당 범위는 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 관리 설정을 통해 제공하는 서버를 보유합니다. Claude Code는 관리 설정에서만 읽으므로 명령어가 해당 범위에 서버를 쓸 수 없습니다.
2855 3055
2856```text theme={null}3056```text theme={null}
2857Cannot add MCP server to scope: managed3057Cannot add MCP server to scope: managed
2859 3059
2860**해야 할 일:**3060**해야 할 일:**
2861 3061
2862* 쓸 수 있는 범위에 서버를 추가하세요: `local`, `user` 또는 `project`. `--scope` 없이 명령어는 `local`을 사용합니다. [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)를 참조하세요.3062* 쓸 수 있는 범위에 서버를 추가합니다: `local`, `user` 또는 `project`. `--scope` 없이 명령어는 `local`을 사용합니다. [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)를 참조하세요.
2863* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리 설정의 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)에 추가하세요.3063* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리 설정의 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)에 추가합니다.
2864 3064
2865<h3 id="cant-read-mcp-json">3065<h3 id="cant-read-mcp-json">
2866 .mcp.json을 읽을 수 없음3066 .mcp.json을 읽을 수 없음
2867</h3>3067</h3>
2868 3068
2869프로젝트의 [`.mcp.json`](/docs/ko/mcp#project-scope)을 읽는 명령어(예: `--scope project`로 `claude mcp add` 또는 `claude mcp add-json`, 또는 `claude mcp remove`)가 현재 디렉토리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 발견했으므로 파일을 읽는 대신 이 오류로 종료됩니다.3069프로젝트의 [`.mcp.json`](/docs/ko/mcp#project-scope)을 읽는 명령어(예: `--scope project`로 `claude mcp add` 또는 `claude mcp add-json` 또는 `claude mcp remove`)가 현재 디렉토리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 발견했으므로 파일을 읽는 대신 이 오류로 종료됩니다.
2870 3070
2871```text theme={null}3071```text theme={null}
2872Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.3072Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.
2873```3073```
2874 3074
2875v2.1.257 이전에는 `.mcp.json`의 FIFO가 명령어를 출력 없이 영원히 기다리게 했으며, `/dev/zero` 같은 장치 파일로의 심볼릭 링크가 프로세스가 종료될 때까지 메모리를 증가시켰습니다.3075v2.1.257 이전에는 `.mcp.json`의 FIFO가 명령어를 출력 없이 영원히 기다리게 했고 `/dev/zero` 같은 장치 파일에 대한 심볼릭 링크가 프로세스가 종료될 때까지 메모리를 증가시켰습니다.
2876 3076
2877**해야 할 일:**3077**해야 할 일:**
2878 3078
2879* 현재 디렉토리의 `.mcp.json`에 무엇이 있는지 확인하세요. [프로젝트 범위 형식](/docs/ko/mcp#project-scope)의 일반 JSON 파일로 바꾸거나 삭제한 후 명령어를 다시 실행하세요.3079* 현재 디렉토리의 `.mcp.json`에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](/docs/ko/mcp#project-scope)의 일반 JSON 파일로 바꾸거나 삭제한 후 명령어를 다시 실행합니다.
2880 3080
2881<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">3081<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">
2882 서버는 Anthropic 호스팅이며 로컬 OAuth를 지원하지 않음3082 서버는 Anthropic 호스팅이며 로컬 OAuth를 지원하지 않음
2888"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.3088"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.
2889```3089```
2890 3090
2891Claude Code는 URL로 이러한 호스트를 일치시키므로 `claude mcp add` 또는 `.mcp.json`에 추가한 서버가 이 중 하나를 가리킬 때 메시지가 나타납니다.3091Claude Code는 URL로 이러한 호스트를 일치시키므로 `claude mcp add` 또는 `.mcp.json`으로 추가한 서버가 이 중 하나를 가리킬 때 메시지가 나타납니다.
2892 3092
2893**해야 할 일:**3093**해야 할 일:**
2894 3094
2895* `claude mcp remove <name>`으로 항목을 제거하여 같은 URL의 claude.ai 커넥터를 숨길 수 없도록 하세요.3095* `claude mcp remove <name>`으로 항목을 제거하여 같은 URL의 claude.ai 커넥터를 숨길 수 없습니다.
2896* 제거한 후 Claude Code에 로그인한 계정을 사용하는 동안 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결하세요. 연결되면 활성 인증 방법이 claude.ai 구독 로그인이면 [커넥터가 Claude Code에 자동으로 나타납니다](/docs/ko/mcp#use-mcp-servers-from-claude-ai).3096* 제거한 후 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. Claude Code에서 사용하는 계정에 로그인합니다. 연결되면 활성 인증 방법이 claude.ai 구독 로그인이면 [커넥터가 Claude Code에 자동으로 나타납니다](/docs/ko/mcp#use-mcp-servers-from-claude-ai).
2897 3097
2898<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">3098<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">
2899 서버가 구성된 headersHelper에 의해 발행된 Authorization 헤더를 거부함3099 서버가 구성된 headersHelper에 의해 발행된 Authorization 헤더를 거부함
2900</h3>3100</h3>
2901 3101
2902[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 HTTP 401 또는 403으로 연결에 응답했으므로 Claude Code는 연결을 실패로 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 [OAuth로 폴백하지 않습니다](/docs/ko/mcp#authenticate-with-remote-mcp-servers):3102[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 HTTP 401 또는 403으로 연결에 응답했으므로 Claude Code는 연결을 실패로 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 [서버에 대해 OAuth로 폴백하지 않습니다](/docs/ko/mcp#authenticate-with-remote-mcp-servers):
2903 3103
2904```text theme={null}3104```text theme={null}
2905Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.3105Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.
2906```3106```
2907 3107
2908Claude Code는 각 연결 시도에서 헬퍼를 다시 실행하므로 토큰 회전 경쟁 같은 일시적 거부 후 재시도가 새로운 자격 증명으로 성공할 수 있습니다.3108Claude Code는 각 연결 시도에서 헬퍼를 다시 실행하므로 토큰 회전 경쟁 같은 일시적 거부 후 재시도가 새 자격 증명으로 성공할 수 있습니다.
2909 3109
2910**해야 할 일:**3110**해야 할 일:**
2911 3111
2912* Claude Code가 실행하는 방식으로 `headersHelper` 명령어를 직접 실행하세요: [Claude Code가 실행하는 디렉토리](/docs/ko/mcp#where-the-helper-runs)에서, [Claude Code가 설정하는 환경 변수](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)를 사용하여, 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일의 서버에 대해 [Claude Code가 제거하는 자격 증명 변수](/docs/ko/mcp#which-variables-a-helper-can-read) 없이. 서버의 엔드포인트가 수용하는 `Authorization` 값을 인쇄하는지 확인하세요.3112* Claude Code가 실행하는 방식으로 `headersHelper` 명령어를 직접 실행합니다: [Claude Code가 실행하는 디렉토리](/docs/ko/mcp#where-the-helper-runs)에서, [Claude Code가 설정하는 환경 변수](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)를 사용하고, [Claude Code가 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일의 서버에 대해 제거하는 자격 증명 변수](/docs/ko/mcp#which-variables-a-helper-can-read) 없이. 서버의 엔드포인트가 허용하는 `Authorization` 값을 출력하는지 확인합니다.
2913* 헬퍼 또는 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택하세요.3113* 헬퍼 또는 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다.
2914 3114
2915v2.1.248 이전에는 Claude Code가 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해 OAuth 검색을 실행했습니다. 해당 검색이 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있습니다.3115v2.1.248 이전에는 Claude Code가 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해 OAuth 검색을 실행했습니다. 해당 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있습니다.
2916 3116
2917<h3 id="mcp-permission-prompt-tool-not-found">3117<h3 id="mcp-permission-prompt-tool-not-found">
2918 MCP 권한 프롬프트 도구를 찾을 수 없음3118 MCP 권한 프롬프트 도구를 찾을 수 없음
2919</h3>3119</h3>
2920 3120
2921[`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)에 전달한 도구가 실행이 처음 권한 결정이 필요할 때 연결된 MCP 도구 중에 없습니다. 서버가 연결되지 않았거나 연결된 서버가 해당 이름의 도구를 노출하지 않기 때문입니다. Claude Code는 여전히 프롬프트를 보냅니다: [비대화형](/docs/ko/headless) 실행이 승인이 필요한 첫 번째 도구 호출에서 이 오류로 종료되고 코드 1로 종료되므로 요청이 이루어졌음에도 불구하고 답변을 생성하지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](/docs/ko/env-vars)으로 설정된 서버당 연결 타임아웃 30초까지 해당 서버가 연결될 때까지 기다립니다. v2.1.206 이전에는 시작이 서버가 연결을 마칠 때까지 기다리지 않았으므로 느리게 시작하지만 정상인 서버가 이 오류를 생성했습니다.3121[`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)에 전달한 도구가 실행이 처음 권한 결정이 필요할 때 연결된 MCP 도구 중에 없습니다. 서버가 연결되지 않았거나 연결된 서버가 해당 이름의 도구를 노출하지 않기 때문입니다. Claude Code는 여전히 프롬프트를 보냅니다: [비대화형](/docs/ko/headless) 실행은 승인이 필요한 첫 번째 도구 호출에서 이 오류로 종료되고 코드 1로 종료되므로 요청이 이루어졌음에도 불구하고 답변을 생성하지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](/docs/ko/env-vars)으로 설정된 서버당 연결 타임아웃 30초까지 해당 서버가 연결될 때까지 기다립니다. v2.1.206 이전에는 시작이 서버가 연결을 완료할 때까지 기다리지 않았으므로 느리게 시작하지만 정상인 서버가 이 오류를 생성했습니다.
2922 3122
2923```text theme={null}3123```text theme={null}
2924Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3124Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none
2928 3128
2929**해야 할 일:**3129**해야 할 일:**
2930 3130
2931* 서버가 시작되고 연결된 상태를 유지하는지 확인하세요: 같은 디렉토리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 나열되는지 확인하세요.3131* 서버가 시작되고 연결된 상태로 유지되는지 확인합니다: 같은 디렉토리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 나열되는지 확인합니다.
2932* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인하세요.3132* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다.
2933* 서버가 시작하는 데 30초 이상 필요하면 [`MCP_TIMEOUT`](/docs/ko/env-vars)을 높이세요.3133* 서버가 시작하는 데 30초 이상 필요하면 [`MCP_TIMEOUT`](/docs/ko/env-vars)을 높입니다.
2934 3134
2935<h3 id="oauth-callback-port-is-already-in-use">3135<h3 id="oauth-callback-port-is-already-in-use">
2936 OAuth 콜백 포트가 이미 사용 중3136 OAuth 콜백 포트가 이미 사용 중
2937</h3>3137</h3>
2938 3138
2939OAuth를 사용하여 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 수신하기 위해 로컬 리스너를 시작합니다. 해당 리스너가 필요한 포트가 다른 프로세스에 의해 보유되면 로그인이 이 메시지로 실패합니다. 이는 주로 [`MCP_OAUTH_CALLBACK_PORT`](/docs/ko/env-vars) 변수 또는 `--callback-port`를 통해 설정된 [고정 콜백 포트](/docs/ko/mcp#use-a-fixed-oauth-callback-port)에서 발생합니다. 없으면 Claude Code가 사용 가능한 포트를 선택하기 때문입니다.3139OAuth를 사용하여 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 수신하기 위해 로컬 리스너를 시작합니다. 해당 리스너가 필요한 포트가 다른 프로세스에 의해 보유되면 로그인이 이 메시지로 실패합니다. 이는 주로 [`MCP_OAUTH_CALLBACK_PORT`](/docs/ko/env-vars) 변수 또는 `--callback-port`를 통해 설정된 [고정 콜백 포트](/docs/ko/mcp#use-a-fixed-oauth-callback-port)에서 발생합니다. 하나 없이 Claude Code는 사용 가능한 포트를 선택합니다.
2940 3140
2941```text theme={null}3141```text theme={null}
2942OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.3142OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.
2946 3146
2947**해야 할 일:**3147**해야 할 일:**
2948 3148
2949* 메시지의 명령어를 실행하여 포트를 보유한 프로세스를 찾고 중지하거나 완료될 때까지 기다리세요.3149* 메시지의 명령어를 실행하여 포트를 보유하는 프로세스를 찾고 중지하거나 완료될 때까지 기다립니다.
2950* 다른 프로그램이 해당 포트를 영구적으로 필요로 하면 서버에 다른 리디렉션 URI를 등록하고 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`(사용하는 것)로 포트를 설정하세요.3150* 다른 프로그램이 해당 포트를 영구적으로 필요로 하면 서버에 다른 리디렉션 URI를 등록하고 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`(사용하는 것)로 포트를 설정합니다.
2951* 그런 다음 로그인을 다시 시작하세요. 예를 들어 `/mcp`에서 서버를 선택하세요.3151* 그런 다음 로그인을 다시 시작합니다. 예를 들어 `/mcp`에서 서버를 선택합니다.
2952 3152
2953<h3 id="no-available-ports-for-oauth-redirect">3153<h3 id="no-available-ports-for-oauth-redirect">
2954 OAuth 리디렉션에 사용 가능한 포트 없음3154 OAuth 리디렉션에 사용 가능한 포트 없음
2964 3164
2965**해야 할 일:**3165**해야 할 일:**
2966 3166
2967* 보안 소프트웨어 또는 샌드박스 정책이 프로세스가 `127.0.0.1`에서 수신 대기하는 것을 차단하는지 확인하고 Claude Code가 로컬 포트를 바인드하도록 허용하세요.3167* 보안 소프트웨어 또는 샌드박스 정책이 프로세스가 `127.0.0.1`에서 수신 대기하는 것을 차단하는지 확인하고 Claude Code가 로컬 포트를 바인드하도록 허용합니다.
2968* 그런 다음 로그인을 다시 시작하세요. 예를 들어 `/mcp`에서 서버를 선택하세요.3168* 그런 다음 로그인을 다시 시작합니다. 예를 들어 `/mcp`에서 서버를 선택합니다.
2969 3169
2970<h3 id="security-review-fails-without-origin-head">3170<h3 id="security-review-fails-without-origin-head">
2971 /security-review가 origin/HEAD 없이 실패함3171 /security-review가 origin/HEAD 없이 실패함
2980'git <command> [<revision>...] -- [<file>...]'3180'git <command> [<revision>...] -- [<file>...]'
2981```3181```
2982 3182
2983메시지는 `git log` 또는 다른 `git diff`를 인용할 수 있습니다. Git은 원격이 기본 분기를 광고하고 fetch refspec이 이를 포함할 때만 `origin/HEAD`를 생성합니다. 전체 `git clone`이 커밋이 있는 원격을 수행합니다. ref는 이러한 설정에서 누락됩니다:3183메시지는 대신 `git log` 또는 다른 `git diff`를 인용할 수 있습니다. Git은 원격이 기본 분기를 광고하고 fetch refspec이 이를 포함할 때만 `origin/HEAD`를 만듭니다. 전체 `git clone`이 커밋이 있는 원격을 수행합니다. ref는 이러한 설정에서 누락됩니다:
2984 3184
2985* 단일 분기 또는 CI 체크아웃(너무 좁은 refspec을 가져옴)3185* 단일 분기 또는 CI 체크아웃(너무 좁은 refspec을 가져옴)
2986* 서버 측 HEAD가 아무도 푸시하지 않은 분기를 가리키는 원격3186* 서버 측 HEAD가 아무도 푸시하지 않은 분기를 가리키는 원격
2987* `origin` 원격이 없거나 절대 가져오지 않은 저장소3187* `origin` 원격이 없거나 가져온 적이 없는 저장소
2988 3188
2989Claude Code는 [동적 컨텍스트를 주입](/docs/ko/skills#when-an-injected-command-fails)하는 모든 스킬에 대해 같은 오류를 표시하며, 실패한 주입 명령어는 해당 스킬의 호출을 중단합니다. 명령어가 실행되기 전에 두 개의 형제 문자열이 발생합니다:3189Claude Code는 [동적 컨텍스트를 주입](/docs/ko/skills#when-an-injected-command-fails)하는 모든 스킬에 대해 동일한 오류를 표시하고 실패한 주입 명령어는 해당 스킬의 호출을 중단합니다. 명령어가 실행되기 전에 두 개의 형제 문자열이 발생합니다:
2990 3190
2991* `Shell command permission check failed for pattern "..."`: 명령어의 권한 확인이 이를 허용하지 않았습니다. [주입 명령어의 권한 확인](/docs/ko/skills#permission-checks-on-injected-commands)은 각 권한 모드에서 어떤 결과가 중단되는지 그리고 `allowed-tools`로 명령어를 사전 승인하는 방법을 다룹니다.3191* `Shell command permission check failed for pattern "..."`: 명령어의 권한 확인이 허용하지 않았습니다. [주입 명령어의 권한 확인](/docs/ko/skills#permission-checks-on-injected-commands)은 각 권한 모드에서 어떤 결과가 중단되는지 그리고 `allowed-tools`로 명령어를 사전 승인하는 방법을 다룹니다.
2992* ``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)을 참조하세요.3192* ``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)을 참조하세요.
2993 3193
2994**해야 할 일:**3194**해야 할 일:**
2995 3195
2996* 원격의 기본 분기를 이름 지정하여 ref를 생성하세요: `git remote set-head origin <default-branch>`. 이는 로컬 추적 ref `origin/<default-branch>`가 존재할 때마다 작동합니다. 단일 분기 클론처럼 없으면 먼저 분기를 가져오세요: `git remote set-branches --add origin <branch>`를 실행한 후 `git fetch origin`을 실행한 후 set-head 명령어를 다시 실행하세요. `/security-review`를 다시 실행하세요.3196* 원격의 기본 분기를 이름 지정하여 ref를 만듭니다: `git remote set-head origin <default-branch>`. 이는 로컬 추적 ref `origin/<default-branch>`가 존재할 때마다 작동합니다. 단일 분기 클론처럼 없으면 먼저 분기를 가져옵니다: `git remote set-branches --add origin <branch>`를 실행한 후 `git fetch origin`을 실행한 후 set-head 명령어를 다시 실행합니다. `/security-review`를 다시 실행합니다.
2997* 분기를 이름 지정하지 않으려면 `git fetch origin`을 실행한 후 `git remote set-head origin --auto`를 실행하세요. 이는 원격에 기본 분기가 무엇인지 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 분기를 가리킬 때 `error: Cannot determine remote HEAD`로 실패합니다. 분기를 명시적으로 이름 지정하세요. 클론이 해당 분기를 가져오지 않을 때 `error: Not a valid ref`로 실패합니다. 위에서 refspec을 확대하세요.3197* 분기를 이름 지정하지 않으려면 `git fetch origin`을 실행한 후 `git remote set-head origin --auto`를 실행합니다. 이는 원격에 기본 분기가 무엇인지 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 분기를 가리킬 때 `error: Cannot determine remote HEAD`로 실패합니다. 대신 분기를 명시적으로 이름 지정합니다. 클론이 해당 분기를 가져오지 않을 때 `error: Not a valid ref`로 실패합니다. 먼저 위와 같이 refspec을 넓힙니다.
2998* 저장소에 원격이 없으면 `git remote add origin <url>`로 추가하고 ref를 생성하기 전에 가져오세요. 원격이 비어 있으면 `git push -u origin HEAD`로 분기를 먼저 푸시하고 set-head 명령어에서 해당 분기를 이름 지정하세요. `origin/HEAD`는 방금 푸시한 분기를 가리키므로 `/security-review`는 분기가 이로부터 분기될 때까지 빈 diff를 봅니다.3198* 저장소에 원격이 없으면 `git remote add origin <url>`로 추가하고 ref를 만들기 전에 가져옵니다. 원격이 비어 있으면 `git push -u origin HEAD`로 분기를 먼저 푸시하고 set-head 명령어에서 해당 분기를 이름 지정합니다. `origin/HEAD`는 방금 푸시한 분기를 가리키므로 분기가 이와 달라질 때까지 `/security-review`는 빈 diff를 봅니다.
2999 3199
3000<h3 id="input-must-be-provided-when-using-print">3200<h3 id="input-must-be-provided-when-using-print">
3001 \--print 사용 시 입력을 제공해야 함3201 \--print 사용 시 입력을 제공해야 함
3002</h3>3202</h3>
3003 3203
3004베어 `claude`는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되거나 PowerShell ISE 및 일부 IDE 출력 창 같은 실제 터미널이 아닐 때 `claude`는 [비대화형](/docs/ko/headless) 모드로 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로 메시지는 플래그를 전달하지 않았을 때도 `--print`를 이름 지정합니다. 프롬프트 없이 `-p`/`--print`를 전달하고 stdin에 파이프된 것이 없으면 어디서나 같은 오류를 생성합니다.3204베어 `claude`는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되거나 PowerShell ISE 및 일부 IDE 출력 창 같은 실제 터미널이 아닐 때 `claude`는 대신 [비대화형](/docs/ko/headless)으로 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 동일한 모드이므로 메시지는 플래그를 전달하지 않았을 때도 `--print`를 이름 지정합니다. `-p`/`--print`를 프롬프트 없이 전달하고 stdin에 파이프된 것이 없으면 어디서나 동일한 오류를 생성합니다.
3005 3205
3006```text theme={null}3206```text theme={null}
3007Error: Input must be provided either through stdin or as a prompt argument when using --print3207Error: Input must be provided either through stdin or as a prompt argument when using --print
3009 3209
3010**해야 할 일:**3210**해야 할 일:**
3011 3211
3012* 대화형 사용의 경우 실제 터미널에서 `claude`를 실행하세요: PowerShell ISE가 아닌 Windows Terminal 또는 PowerShell 콘솔, IDE의 출력 창이 아닌 통합 터미널.3212* 대화형 사용의 경우 실제 터미널에서 `claude`를 실행합니다: ISE가 아닌 Windows Terminal 또는 PowerShell 콘솔, IDE의 통합 터미널이 아닌 출력 창.
3013* 일회용 사용의 경우 프롬프트를 전달하세요: `claude -p "your question"`, 또는 `echo "your question" | claude -p`로 파이프하세요.3213* 일회용 사용의 경우 프롬프트를 전달합니다: `claude -p "your question"` 또는 `echo "your question" | claude -p`로 파이프합니다.
3014 3214
3015<h3 id="input-contained-only-whitespace">3215<h3 id="input-contained-only-whitespace">
3016 입력에 공백만 포함됨3216 입력에 공백만 포함됨
3017</h3>3217</h3>
3018 3218
3019[비대화형 모드](/docs/ko/headless)에서 Claude Code는 API가 보이는 텍스트가 없는 메시지를 거부하기 때문에 공백, 탭 또는 줄 바꿈으로만 구성된 프롬프트를 보내는 대신 거부합니다. 어떤 메시지를 보는지는 빈 프롬프트가 어디서 왔는지에 따라 다릅니다:3219[비대화형 모드](/docs/ko/headless)에서 Claude Code는 API가 보이는 텍스트가 없는 메시지를 거부하기 때문에 공백, 탭 또는 줄 바꿈으로만 구성된 프롬프트를 보내는 대신 거부합니다. 어떤 메시지를 보는지는 빈 프롬프트가 어디서 왔는지에 따라 달라집니다:
3020 3220
3021* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`가 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`로 종료됩니다.3221* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`는 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`로 종료됩니다.
3022* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](/docs/ko/agent-sdk/overview) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하며 세션은 사용 가능한 상태로 유지됩니다. 거부는 정보 메시지로 그리고 턴의 결과 텍스트로 도착합니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`3222* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](/docs/ko/agent-sdk/overview) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하고 세션은 사용 가능한 상태로 유지됩니다. 거부는 정보 메시지로 그리고 턴의 결과 텍스트로 도착합니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`
3023 3223
3024v2.1.229 이전에는 Claude Code가 공백 전용 메시지를 API로 보냈으며, API가 400 오류로 요청을 거부했습니다.3224v2.1.229 이전에는 Claude Code가 공백 전용 메시지를 API로 보냈고 API는 400 오류로 요청을 거부했습니다.
3025 3225
3026**해야 할 일:**3226**해야 할 일:**
3027 3227
3028* 프롬프트에 보이는 텍스트를 포함하세요. 스크립트가 변수 또는 파일에서 프롬프트를 구축하면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인하세요.3228* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수 또는 파일에서 프롬프트를 구축하면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.
3029 3229
3030<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">3230<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">
3031 stream-json 입력이 줄 바꿈 없이 256M 문자를 초과함3231 stream-json 입력이 줄 바꿈 없이 256M 문자를 초과함
3032</h3>3232</h3>
3033 3233
3034프로그램이 `claude -p --input-format stream-json` 실행에 stdin으로 줄 바꿈 없이 268,435,456자 이상을 보냈으므로 Claude Code는 이 오류를 stderr에 인쇄하고 더 많은 입력을 버퍼링하는 대신 코드 1로 종료됩니다. 메시지는 해당 예산을 `256M`으로 명시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링했으며, 프로세스가 충돌하거나 종료될 때까지 메모리를 증가시켰습니다.3234프로그램이 `claude -p --input-format stream-json` 실행에 stdin으로 줄 바꿈 없이 268,435,456자 이상을 보냈으므로 Claude Code는 이 오류를 stderr에 출력하고 더 많은 입력을 버퍼링하는 대신 코드 1로 종료됩니다. 메시지는 해당 예산을 `256M`으로 명시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링했고 프로세스가 충돌하거나 종료될 때까지 메모리를 증가시켰습니다.
3035 3235
3036```text theme={null}3236```text theme={null}
3037Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.3237Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.
3038```3238```
3039 3239
3040줄 바꿈 없이 이 정도로 긴 입력은 보통 생산자가 stream-json 생산자가 아니라는 의미입니다. 예를 들어 실수로 파이프된 바이너리 파일 또는 일반 로그 출력입니다. 예산을 초과하는 단일 메시지가 같은 확인에 실패합니다.3240줄 바꿈 없이 이 정도로 긴 입력은 보통 생산자가 stream-json 생산자가 아니라는 의미입니다. 예를 들어 실수로 파이프된 바이너리 파일 또는 일반 로그 출력입니다. 예산을 초과하는 단일 메시지는 동일한 확인에 실패합니다.
3041 3241
3042**해야 할 일:**3242**해야 할 일:**
3043 3243
3044* stdin으로 파이프되는 것을 확인하세요. [`--input-format stream-json`](/docs/ko/cli-reference#cli-flags)을 사용하면 모든 메시지는 하나의 줄 바꿈으로 끝나는 JSON 줄이어야 합니다.3244* stdin으로 파이프되는 것을 확인합니다. [`--input-format stream-json`](/docs/ko/cli-reference#cli-flags)을 사용하면 모든 메시지는 줄 바꿈으로 종료된 JSON 줄 하나여야 합니다.
3045* 일반 텍스트를 대신 보내려면 `--input-format stream-json`을 제거하세요. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다.3245* 일반 텍스트를 대신 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다.
3046 3246
3047<h3 id="unknown-command">3247<h3 id="unknown-command">
3048 알 수 없는 명령어3248 알 수 없는 명령어
3054Unknown command: /hepl. Did you mean /help?3254Unknown command: /hepl. Did you mean /help?
3055```3255```
3056 3256
3057Claude Code는 이 세션의 메뉴가 나열하는 가장 가까운 명령어 이름 또는 별칭을 제안합니다. 가까운 것이 없으면 메시지가 이름 뒤에서 끝납니다. 원인은 보통 다음 중 하나입니다:3257Claude Code는 이 세션의 메뉴가 나열하는 가장 가까운 명령어 이름 또는 별칭을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에 끝납니다. 원인은 보통 다음 중 하나입니다:
3058 3258
3059* `/hepl`을 `/help`로 오타. [명령어 메뉴가 입력과 일치하는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)은 제출하기 전에 가까운 일치를 선택하는 것을 다룹니다.3259* `/hepl`을 `/help`로 하는 오타입니다. [명령어 메뉴가 입력과 일치하는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)은 제출하기 전에 가까운 일치를 선택하는 것을 다룹니다.
3060* 존재하지만 플랫폼, 계획 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령어. [`/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) 같은 자체 메시지로 응답합니다.3260* 플랫폼, 계획 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령어입니다. [`/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) 같은 자체 메시지로 응답합니다.
3061* [플러그인](/docs/ko/plugins) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령어가 이 세션에 설치되거나 연결되지 않음.3261* [플러그인](/docs/ko/plugins/overview) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령어가 이 세션에 설치되거나 연결되지 않았습니다.
3062 3262
3063Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이 방식으로 응답합니다. 다른 모든 세션에서는 프롬프트를 Claude에 일반 메시지로 보냅니다. 명령어가 실행되지 않았고 Claude가 세션에서 실행할 수 있는 명령어 목록이 있다는 참고 사항이 포함됩니다. 이러한 세션에는 다음이 포함됩니다:3263Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이 방식으로 응답합니다. 다른 모든 세션에서는 대신 프롬프트를 Claude에 일반 메시지로 보냅니다. 명령어가 실행되지 않았고 Claude가 세션에서 실행할 수 있는 명령어 목록이 있다는 메모가 포함됩니다. 이러한 세션에는 다음이 포함됩니다:
3064 3264
3065* `-p` 실행3265* `-p` 실행
3066* [Agent SDK](/docs/ko/agent-sdk/overview) 애플리케이션3266* [Agent SDK](/docs/ko/agent-sdk/overview) 애플리케이션
3067* [Desktop app](/docs/ko/desktop)의 Code 탭3267* [Desktop 앱](/docs/ko/desktop)의 Code 탭
3068* [VS Code extension](/docs/ko/vs-code)의 채팅 패널3268* [VS Code 확장](/docs/ko/vs-code)의 채팅 패널
3069* [클라우드 세션](/docs/ko/claude-code-on-the-web) 및 [루틴](/docs/ko/routines)3269* [클라우드 세션](/docs/ko/claude-code-on-the-web) 및 [루틴](/docs/ko/routines)
3070 3270
3071이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령어의 경우 Claude Code는 여전히 명령어를 Claude로 보내는 대신 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 루틴만 일치하지 않는 이름을 Claude로 보냈습니다. v2.1.273 이전에는 `Unknown command`로도 응답했습니다.3271이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령어의 경우 Claude Code는 여전히 명령어를 Claude로 보내는 대신 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 루틴만 일치하지 않는 이름을 Claude로 보냈습니다. v2.1.273 이전에는 `Unknown command`로도 응답했습니다.
3072 3272
3073Claude Code는 `/`로 시작하는 모든 프롬프트를 명령어로 취급하지 않습니다. `/` 뒤의 첫 번째 단어가 Lean doc 주석을 여는 `/--` 같은 구두점으로 시작하거나 `/var/log/syslog` 같은 경로일 때 프롬프트를 Claude에 일반 메시지로 보냅니다.3273Claude Code는 `/`로 시작하는 모든 프롬프트를 명령어로 취급하지 않습니다. `/` 뒤의 첫 번째 단어가 Lean doc 주석을 여는 `/-` 같은 구두점으로 시작하거나 `/var/log/syslog` 같은 경로일 때 프롬프트를 Claude에 일반 메시지로 보냅니다.
3074 3274
3075v2.1.236 이전에는 입력한 이름에 대해 명령어 메뉴가 가까운 일치를 나열하는 동안 Enter를 누르면 Claude Code가 해당 일치를 실행했으므로 `/hepl` 같은 오타가 이 메시지를 생성하는 대신 `/help`를 실행했습니다.3275v2.1.236 이전에는 명령어 메뉴가 입력한 이름에 대한 가까운 일치를 나열하는 동안 Enter를 누르면 Claude Code가 일치를 실행했으므로 `/hepl` 같은 오타가 이 메시지를 생성하는 대신 `/help`를 실행했습니다.
3076 3276
3077**해야 할 일:**3277**해야 할 일:**
3078 3278
3079* 제안된 이름을 실행하거나 `/`를 입력한 후 이름의 일부를 입력하여 이 세션에서 사용 가능한 것을 확인하세요.3279* 제안된 이름을 실행하거나 `/` 뒤에 이름의 일부를 입력하여 이 세션에서 사용 가능한 것을 확인합니다.
3080* Claude Code가 문서화된 명령어를 알 수 없는 것으로 보고하면 [명령어 참조](/docs/ko/commands)의 행에서 이름 지정하는 요구 사항을 확인하세요.3280* Claude Code가 문서화된 명령어를 알 수 없는 것으로 보고하면 [명령어 참조](/docs/ko/commands)의 행에서 이름 지정하는 요구 사항을 확인합니다.
3081 3281
3082<h3 id="diff-is-too-large-for-ultrareview">3282<h3 id="diff-is-too-large-for-ultrareview">
3083 Diff가 ultrareview에 너무 큼3283 Diff가 ultrareview에 너무 큼
3084</h3>3284</h3>
3085 3285
3086분기와 기본 분기 간의 diff(커밋되지 않은 변경 사항 및 스테이징된 변경 사항 포함)가 [ultrareview](/docs/ko/ultrareview)의 크기 제한을 초과하므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어가 클라우드 세션이 시작되기 전에 검토를 거부합니다. 거부된 검토는 무료 실행을 사용하지 않으며 사용 크레딧을 청구하지 않습니다. 메시지는 적용 중인 제한, diff의 크기 및 가장 많은 변경된 줄에 기여하는 파일을 이름 지정합니다. v2.1.216 이전에는 메시지가 원본 diff 통계만 표시했습니다.3286분기와 기본 분기 간의 diff(커밋되지 않은 변경 사항 및 스테이징된 변경 사항 포함)가 [ultrareview](/docs/ko/ultrareview)의 크기 제한을 초과하므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어는 클라우드 세션이 시작되기 전에 검토를 거부합니다. 거부된 검토는 무료 실행을 사용하지 않으며 사용 크레딧을 청구하지 않습니다. 메시지는 적용 중인 제한, diff의 크기 및 가장 많은 변경된 줄에 기여하는 파일을 이름 지정합니다. v2.1.216 이전에는 메시지가 원시 diff 통계만 표시했습니다.
3087 3287
3088```text theme={null}3288```text theme={null}
3089Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.3289Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.
3090```3290```
3091 3291
3092풀 요청을 검토하면 같은 제한이 적용됩니다. 해당 형식의 메시지는 `PR #<N> is too large for ultrareview`로 시작하고 PR의 파일 및 줄 수를 이름 지정합니다.3292풀 요청을 검토하면 동일한 제한이 적용됩니다. 해당 형식의 메시지는 `PR #<N> is too large for ultrareview`로 시작하고 PR의 파일 및 줄 수를 이름 지정합니다.
3093 3293
3094**해야 할 일:**3294**해야 할 일:**
3095 3295
3096* 기본 분기를 더 가깝게 전달하세요. 예를 들어 `/code-review ultra develop`이므로 검토가 해당 분기에 대한 diff만 포함합니다.3296* 기본 분기를 더 가깝게 전달합니다. 예를 들어 `/code-review ultra develop`이므로 검토는 해당 분기에 대한 diff만 포함합니다.
3097* 변경을 더 작은 분기로 분할하고 각각을 검토하세요. 메시지가 이름 지정한 파일이 가장 많은 변경된 줄에 기여하므로 이를 자체 분기로 이동하여 시작하세요.3297* 변경을 더 작은 분기로 분할하고 각각을 검토합니다. 메시지가 이름 지정하는 파일은 가장 많은 변경된 줄에 기여하므로 이들을 자신의 분기로 이동하여 시작합니다.
3098 3298
3099<h3 id="could-not-find-merge-base-with-the-base-branch">3299<h3 id="could-not-find-merge-base-with-the-base-branch">
3100 기본 분기와의 병합 기반을 찾을 수 없음3300 기본 분기와의 병합 기반을 찾을 수 없음
3101</h3>3301</h3>
3102 3302
3103`/code-review ultra` 및 `claude ultrareview` 하위 명령어는 분기와 기본 분기 간의 diff를 검토하며, 이는 두 분기가 공유하는 커밋이 필요합니다. `git merge-base`가 없음을 발견하면 Claude Code는 클라우드 세션이 시작되기 전에 검토를 거부합니다. Claude Code가 완전한 것으로 확인할 수 있는 클론에서 최소 하나의 분기가 있으면 대신 [모든 추적된 파일을 검토](/docs/ko/ultrareview#diff-limits-and-fallbacks)로 폴백합니다. 기본 분기를 전혀 찾을 수 없을 때, Claude Code가 클론이 완전한지 확인할 수 없을 때 또는 SHA-256 객체 형식 같은 드문 저장소에서 전체 트리 diff가 불가능할 때 이 거부를 봅니다.3303`/code-review ultra` 및 `claude ultrareview` 하위 명령어는 두 분기 간의 diff를 검토합니다. 이는 두 분기가 공유하는 커밋이 필요합니다. `git merge-base`가 없으면 Claude Code는 클라우드 세션이 시작되기 전에 검토를 거부합니다. Claude Code가 완전한 것으로 확인할 수 있는 클론에서 최소 하나의 분기가 있으면 대신 [모든 추적된 파일을 검토](/docs/ko/ultrareview#diff-limits-and-fallbacks)로 폴백합니다. 기본 분기를 전혀 찾을 수 없을 때, Claude Code가 클론이 완전한지 확인할 수 없을 때 또는 SHA-256 객체 형식 같은 전체 트리 diff가 불가능한 드문 저장소에서 이 거부를 봅니다.
3104 3304
3105```text theme={null}3305```text theme={null}
3106Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.3306Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.
3107```3307```
3108 3308
3109첫 번째 문장 뒤의 힌트는 Claude Code가 관찰한 것에 따라 다릅니다:3309첫 번째 문장 뒤의 힌트는 Claude Code가 관찰한 것에 따라 달라집니다:
3110 3310
3111* **기본 분기를 전달하지 않음**: Claude Code가 저장소의 기본 분기와 비교했으며 위의 예처럼 기본을 명시적으로 전달하도록 제안합니다.3311* **기본 분기를 전달하지 않았습니다**: Claude Code는 저장소의 기본 분기와 비교했고 위의 예와 같이 기본을 명시적으로 전달하도록 제안합니다.
3112* **이미 클론에 있는 기본 분기를 전달함**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``를 읽습니다.3312* **클론에 이미 있는 기본 분기를 전달했습니다**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``를 읽습니다.
3113* **클론에 없는 기본 분기를 전달함**: 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`로 실패합니다.3313* **클론에 없는 기본 분기를 전달했습니다**: 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`로 실패합니다.
3114 3314
3115**해야 할 일:**3315**해야 할 일:**
3116 3316
3117* 다른 분기가 실제 기본이면 명시적으로 전달하세요: `/code-review ultra <branch>`3317* 다른 분기가 실제 기본이면 명시적으로 전달합니다: `/code-review ultra <branch>`
3118* 클론이 전체 기록을 갖지 않을 수 있으면 `git fetch --unshallow origin`을 실행하고 검토를 다시 실행하세요.3318* 클론이 전체 기록을 갖지 않을 수 있으면 `git fetch --unshallow origin`을 실행하고 검토를 다시 실행합니다.
3119 3319
3120<h3 id="your-checkout-has-no-branches">3320<h3 id="your-checkout-has-no-branches">
3121 체크아웃에 분기가 없음3321 체크아웃에 분기가 없음
3122</h3>3322</h3>
3123 3323
3124체크아웃은 커밋을 가질 수 있지만 분기는 없습니다: `git init` 다음 `git fetch <url>` 및 `git checkout FETCH_HEAD`를 실행하면 분기가 없는 분리된 HEAD를 얻습니다. Claude Code는 저장소를 git 번들로 패키징하여 [ultrareview](/docs/ko/ultrareview)를 위해 업로드하며, 분기나 다른 ref가 없는 저장소를 번들할 수 없으므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어가 클라우드 세션이 시작되기 전에 검토를 거부합니다.3324체크아웃은 커밋을 가질 수 있지만 분기는 없습니다: `git init` 뒤에 `git fetch <url>` 및 `git checkout FETCH_HEAD`를 실행하면 분기가 없는 분리된 HEAD를 얻습니다. Claude Code는 저장소를 git 번들로 패키징하여 [ultrareview](/docs/ko/ultrareview)를 위해 업로드하고 분기나 다른 ref가 없는 저장소를 번들할 수 없으므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어는 클라우드 세션이 시작되기 전에 검토를 거부합니다.
3125 3325
3126```text theme={null}3326```text theme={null}
3127Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.3327Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.
3128```3328```
3129 3329
3130v2.1.221 이전에는 Claude Code가 이 체크아웃에서 모든 추적된 파일을 검토하려고 시도했으며, 업로드가 실패했습니다.3330v2.1.221 이전에는 Claude Code가 이 체크아웃의 모든 추적된 파일을 검토하려고 시도했고 업로드가 실패했습니다.
3131 3331
3132**해야 할 일:**3332**해야 할 일:**
3133 3333
3134* 현재 커밋에서 `git checkout -b <name>`으로 분기를 생성한 후 검토를 다시 실행하세요.3334* 현재 커밋에서 `git checkout -b <name>`으로 분기를 만든 후 검토를 다시 실행합니다.
3135 3335
3136<h3 id="no-github-account-is-connected-to-your-claude-account">3336<h3 id="no-github-account-is-connected-to-your-claude-account">
3137 Claude 계정에 연결된 GitHub 계정이 없음3337 GitHub 계정이 Claude 계정에 연결되지 않음
3138</h3>3338</h3>
3139 3339
3140`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했으며, 클라우드 세션을 생성하기 전에 Claude Code는 서버에 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소에 도달할 수 있는지 묻습니다. 계정이 연결되지 않았거나 연결이 만료되었으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.3340`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했고 클라우드 세션을 만들기 전에 Claude Code는 서버에 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소에 도달할 수 있는지 묻습니다. 계정이 연결되지 않았거나 연결이 만료되었으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.
3141 3341
3142```text theme={null}3342```text theme={null}
3143Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).3343Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).
3144```3344```
3145 3345
3146[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 세션에서 사용할 수 없으면 메시지는 claude.ai 링크만 이름 지정합니다.3346[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)이 세션에서 사용할 수 없으면 메시지는 claude.ai 링크만 이름 지정합니다.
3147 3347
3148**해야 할 일:**3348**해야 할 일:**
3149 3349
3150* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결하세요.3350* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다.
3151* 연결 1분 후 검토를 다시 실행하세요.3351* 연결 후 1분 후 검토를 다시 실행합니다.
3152 3352
3153v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.3353v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.
3154 3354
3156 연결된 GitHub 계정이 저장소를 볼 수 없음3356 연결된 GitHub 계정이 저장소를 볼 수 없음
3157</h3>3357</h3>
3158 3358
3159`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했으며, [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.3359`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했고 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.
3160 3360
3161```text theme={null}3361```text theme={null}
3162Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.3362Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.
3163```3363```
3164 3364
3165[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 세션에서 사용할 수 없으면 메시지는 앱 설치만 이름 지정합니다.3365[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)이 세션에서 사용할 수 없으면 메시지는 앱 설치만 이름 지정합니다.
3166 3366
3167**해야 할 일:**3367**해야 할 일:**
3168 3368
3169* 로컬 `gh` CLI가 저장소를 읽을 수 있으면 `/web-setup`을 실행하여 해당 로그인을 Claude 계정에 연결하세요.3369* 로컬 `gh` CLI가 저장소를 읽을 수 있으면 `/web-setup`을 실행하여 해당 로그인을 Claude 계정에 연결합니다.
3170* 변경 후 검토를 다시 실행하세요.3370* 변경 후 검토를 다시 실행합니다.
3171 3371
3172v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.3372v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.
3173 3373
3174<h3 id="the-github-app-preflight-failed-transiently">3374<h3 id="the-github-app-preflight-failed-transiently">
3175 GitHub App 사전 점검이 일시적으로 실패함3375 GitHub 앱 사전 점검이 일시적으로 실패함
3176</h3>3376</h3>
3177 3377
3178로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했으며, 두 단계가 함께 실패했습니다. Claude Code가 저장소 번들을 구축하거나 업로드할 수 없습니다. 업로드 전에 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했으며, 명확한 답변 대신 재시도가 지울 수 있는 오류로 끝났습니다. 예를 들어 네트워크 오류, 타임아웃 또는 임시 서버 오류입니다. 전체 메시지는 번들을 중지한 것으로 시작합니다. 예를 들어 `Could not upload repo bundle (<error>)`이고 사전 점검 문장으로 끝납니다:3378로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했고 두 단계가 함께 실패했습니다. Claude Code가 저장소 번들을 구축하거나 업로드할 수 없습니다. 업로드 전에 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했고 명확한 답변 대신 재시도가 지울 수 있는 오류로 끝났습니다. 예를 들어 네트워크 오류, 타임아웃 또는 임시 서버 오류입니다. 전체 메시지는 번들을 중지한 것으로 시작합니다. 예를 들어 `Could not upload repo bundle (<error>)`이고 사전 점검 문장으로 끝납니다:
3179 3379
3180```text theme={null}3380```text theme={null}
3181Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead3381Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead
3183 3383
3184**해야 할 일:**3384**해야 할 일:**
3185 3385
3186* 잠시 후 명령어를 다시 실행하세요. GitHub 확인이 통과하면 Claude Code가 GitHub 클론에서 시작할 수 있으므로 실패한 업로드가 더 이상 시작을 차단하지 않습니다.3386* 잠시 후 명령어를 다시 실행합니다. GitHub 확인이 통과하면 Claude Code는 GitHub 클론에서 세션을 시작할 수 있으므로 실패한 업로드가 더 이상 시작을 차단하지 않습니다.
3187* 재시도가 계속 실패하면 메시지의 시작이 업로드를 중지한 것을 이름 지정합니다. 해당 원인이 수정할 수 있는 것이면 수정하여 세션이 로컬 저장소에서 시작할 수 있도록 하세요.3387* 재시도가 계속 실패하면 메시지의 시작이 업로드를 중지한 것을 이름 지정합니다. 수정할 수 있는 원인이 있으면 수정하여 세션이 대신 로컬 저장소에서 시작할 수 있습니다.
3188 3388
3189v2.1.251 이전에는 Claude Code가 GitHub 확인이 일시적으로만 실패했을 때도 `Please set up GitHub on https://claude.ai/code`로 메시지를 끝냈으며, 설정 조언은 일시적 실패를 지울 수 없습니다.3389v2.1.251 이전에는 Claude Code가 GitHub 확인이 일시적으로만 실패했을 때도 `Please set up GitHub on https://claude.ai/code`로 메시지를 끝냈고 설정 조언은 일시적 실패를 지울 수 없습니다.
3190 3390
3191<h3 id="github-isnt-connected-to-your-claude-account">3391<h3 id="github-isnt-connected-to-your-claude-account">
3192 GitHub가 Claude 계정에 연결되지 않음3392 GitHub가 Claude 계정에 연결되지 않음
3193</h3>3393</h3>
3194 3394
3195로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했습니다. 예를 들어 `/autofix-pr`을 사용합니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code는 시작을 거부합니다:3395로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했습니다. 예를 들어 `/autofix-pr`을 사용합니다. GitHub 계정이 Claude 계정에 연결되지 않았거나 연결이 만료되었으므로 Claude Code는 시작을 거부합니다:
3196 3396
3197```text theme={null}3397```text theme={null}
3198GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github3398GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github
3199```3399```
3200 3400
3201[`/schedule`](/docs/ko/routines)로 루틴을 생성할 때 같은 메시지가 저장소를 이름 지정하는 설정 참고로 나타납니다. 참고는 루틴 생성을 차단하지 않습니다.3401[`/schedule`](/docs/ko/routines)로 루틴을 만들 때 동일한 메시지가 저장소를 이름 지정하는 설정 메모로 나타납니다. 메모는 루틴 만들기를 차단하지 않습니다.
3202 3402
3203**해야 할 일:**3403**해야 할 일:**
3204 3404
3205* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결하세요. [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options)을 참조하여 두 가지가 어떻게 다른지 확인하세요.3405* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options)을 참조하여 두 가지가 어떻게 다른지 확인합니다.
3206* 연결 1분 후 명령어를 다시 실행하세요.3406* 연결 후 1분 후 명령어를 다시 실행합니다.
3207 3407
3208v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 임시 실패로 보고했으며 재시도하거나 앱을 설치하도록 제안했습니다. 둘 다 GitHub 계정을 연결하지 않습니다.3408v2.1.268 이전에는 Claude Code가 이를 Claude GitHub 앱 확인의 임시 실패로 보고했고 재시도하거나 앱을 설치하도록 제안했습니다. 둘 다 GitHub 계정을 연결하지 않습니다.
3209 3409
3210<h3 id="single-sign-on-authorization-needed">3410<h3 id="single-sign-on-authorization-needed">
3211 단일 로그인 인증 필요3411 싱글 사인온 인증 필요
3212</h3>3412</h3>
3213 3413
3214[`/install-github-app`](/docs/ko/github-actions#quick-setup)을 실행했으며 SAML 단일 로그인을 적용하는 조직의 저장소를 선택했습니다. 설정 전에 Claude Code는 GitHub CLI로 저장소에 대한 액세스를 확인하며, GitHub는 `gh` 토큰이 아직 조직에 대해 인증되지 않았기 때문에 해당 확인을 거부했습니다. 마법사는 단계와 함께 경고를 표시합니다:3414[`/install-github-app`](/docs/ko/github-actions#quick-setup)을 실행했고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. 설정 전에 Claude Code는 GitHub CLI로 저장소에 대한 액세스를 확인하고 GitHub는 `gh` 토큰이 아직 조직에 대해 인증되지 않았기 때문에 해당 확인을 거부했습니다. 마법사는 인증 단계와 함께 경고를 표시합니다:
3215 3415
3216```text theme={null}3416```text theme={null}
3217Single sign-on authorization needed3417Single sign-on authorization needed
3220 3420
3221**해야 할 일:**3421**해야 할 일:**
3222 3422
3223* `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 인증하세요. `gh auth refresh -h github.com -s repo,workflow`를 실행하고 GitHub가 단일 로그인을 요청할 때 조직을 인증하세요.3423* `gh auth refresh -h github.com -s repo,workflow`를 실행하여 GitHub CLI 로그인을 `repo` 및 `workflow` 범위로 다시 인증하고 GitHub가 싱글 사인온을 요청할 때 조직을 인증합니다.
3224* `GH_TOKEN`에서 개인 액세스 토큰으로 인증하면 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택한 후 조직을 인증하세요.3424* `GH_TOKEN`에서 개인 액세스 토큰으로 인증하면 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택하고 조직을 인증합니다.
3225* `/install-github-app`을 다시 실행하세요.3425* `/install-github-app`을 다시 실행합니다.
3226 3426
3227v2.1.273 이전에는 Claude Code가 이 조건에 대해 `Admin permissions required` 경고를 표시했습니다.3427v2.1.273 이전에는 Claude Code가 이 조건에 대해 `Admin permissions required` 경고를 표시했습니다.
3228 3428
3229<h3 id="failed-to-resume-the-conversation">3429<h3 id="failed-to-resume-the-conversation">
3230 대화를 재개할 수 없음3430 대화를 재개하지 못함
3231</h3>3431</h3>
3232 3432
3233Claude Code가 [`claude --resume` 선택기](/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 기록을 읽거나 처리할 수 없어서 부분적으로 로드된 상태에서 계속하는 대신 프로세스를 종료합니다. 메시지는 재시도 명령어를 포함합니다:3433Claude Code가 [`claude --resume` 선택기](/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 기록을 읽거나 처리할 수 없으므로 부분적으로 로드된 상태에서 계속하는 대신 프로세스를 종료합니다. 메시지는 재시도 명령어를 포함합니다:
3234 3434
3235```text theme={null}3435```text theme={null}
3236Failed to resume the conversation.3436Failed to resume the conversation.
3237Run claude --resume <session-id> to retry, or claude to start a new session.3437Run claude --resume <session-id> to retry, or claude to start a new session.
3238```3438```
3239 3439
3240Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대화에서 `Failed to resume conversation`을 보고하며 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 실패한 재개가 `Resuming conversation…` 스피너에 무한정 머물렀습니다.3440Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대화에서 `Failed to resume conversation`을 보고하고 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 실패한 재개가 `Resuming conversation…` 스피너에 무한정 머물렀습니다.
3241 3441
3242**해야 할 일:**3442**해야 할 일:**
3243 3443
3244* 메시지의 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도하세요.3444* 메시지의 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도합니다.
3245* 재시도가 다시 실패하면 `claude update`를 실행하고 다시 재개하세요. v2.1.275 이전 버전은 저장된 기록에 읽을 수 없는 항목이 포함되어 있으면 재개에 실패합니다.3445* 모든 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. v2.1.275 이전의 버전은 저장된 기록에 읽을 수 없는 항목이 포함되어 있을 때 재개에 실패합니다.
3246* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작하세요.3446* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다.
3247 3447
3248<h3 id="no-conversation-found-with-the-session-id">3448<h3 id="no-conversation-found-with-the-session-id">
3249 세션 ID와 일치하는 대화를 찾을 수 없음3449 세션 ID와 일치하는 대화를 찾을 수 없음
3250</h3>3450</h3>
3251 3451
3252세션 ID를 `claude --resume <session-id>`에 전달했는데 저장된 기록이 일치하지 않습니다:3452`claude --resume <session-id>`에 세션 ID를 전달했고 저장된 기록이 일치하지 않습니다:
3253 3453
3254```text theme={null}3454```text theme={null}
3255No conversation found with session ID: <session-id>3455No conversation found with session ID: <session-id>
3256```3456```
3257 3457
3258Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. Claude Code는 [현재 프로젝트를 먼저 검색한 후 이 머신의 다른 모든 프로젝트를 검색](/docs/ko/sessions#resume-a-session)합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉토리와 git worktree에서 중지되었으므로 세션이 마지막으로 작동한 디렉토리에서 재개하세요.3458Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. Claude Code는 [현재 프로젝트를 먼저 검색한 후 이 머신의 다른 모든 프로젝트를 검색](/docs/ko/sessions#resume-a-session)합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉토리와 git worktree에서 중지되었으므로 세션이 마지막으로 작동한 디렉토리에서 재개합니다.
3259 3459
3260일반적인 원인:3460일반적인 원인:
3261 3461
3262* **잘못된 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다.3462* **잘못된 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다.
3263* **삭제된 기록**: Claude Code는 [보존 기간](/docs/ko/sessions#where-transcripts-are-stored) 후 기록을 제거합니다. 기본값은 30일이며, [보존 스윕 규칙](/docs/ko/claude-directory#cleaned-up-automatically)을 따릅니다.3463* **삭제된 기록**: Claude Code는 [보존 기간](/docs/ko/sessions#where-transcripts-are-stored) 후 기록을 제거합니다. 기본값은 30일이며 [보존 스윕 규칙](/docs/ko/claude-directory#cleaned-up-automatically)을 따릅니다.
3264* **다른 머신**: Claude Code는 기록을 로컬로 저장하므로 세션이 실행된 머신에서 재개하세요.3464* **다른 머신**: Claude Code는 기록을 로컬로 저장하므로 세션이 실행된 머신에서 재개합니다.
3265* **중복 복사본**: 프로젝트 디렉토리를 `~/.claude/projects` 아래로 복사했으므로 두 기록이 같은 ID를 가지면 Claude Code는 이 메시지를 보고하는 대신 임의로 하나의 복사본을 재개합니다.3465* **중복 복사본**: `~/.claude/projects` 아래에 프로젝트 디렉토리를 복사했으므로 두 기록이 동일한 ID를 가지면 Claude Code는 이 메시지를 보고하고 임의로 하나의 복사본을 재개하지 않습니다.
3266 3466
3267**해야 할 일:**3467**해야 할 일:**
3268 3468
3269* 대화형 세션의 경우 [`claude --resume`](/docs/ko/sessions#use-the-session-picker)으로 [세션 선택기](/docs/ko/sessions#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 확대한 후 세션을 선택하세요.3469* 대화형 세션의 경우 `claude --resume`으로 [세션 선택기](/docs/ko/sessions#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 확장한 후 세션을 선택합니다.
3270* `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 생성된 세션은 선택기에 나타나지 않으므로 원본 실행이 인쇄한 `session_id`에 대해 ID를 다시 확인하세요.3470* `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 만든 세션은 선택기에 나타나지 않으므로 원래 실행이 출력한 `session_id`에 대해 ID를 다시 확인합니다.
3471
3472<h3 id="windows-reported-an-error-ebadf">
3473 Windows가 이 세션의 기록 파일을 읽을 때 오류를 보고함 (EBADF)
3474</h3>
3475
3476Windows에서 세션을 재개했고 저장된 [기록 파일](/docs/ko/sessions#where-transcripts-are-stored)이 정상적으로 열렸으며 읽기가 EBADF 시스템 오류로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 말하지 않으므로 메시지는 가능한 원인과 시도할 것을 제안합니다:
3477
3478```text theme={null}
3479Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.
3480```
3481
3482메시지는 명령어의 자체 실패 줄을 따릅니다. 예를 들어 `Failed to resume session <session-id>`. `claude --resume` 또는 [`claude -p`](/docs/ko/headless) 명령어는 메시지를 표시한 후 코드 1로 종료됩니다. `/resume` 후 실행 중인 세션 내에서 현재 세션은 계속 실행됩니다.
3483
3484**해야 할 일:**
3485
3486* 보안, 암호화 또는 엔드포인트 관리 도구 같은 파일 읽기를 스캔하거나 가로채는 소프트웨어에서 기록을 보유하는 폴더를 제외합니다. 기록은 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있거나 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)이 이름 지정하는 디렉토리 아래에 있습니다.
3487* 제외를 추가할 수 없으면 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다.
3488* 세션을 다시 재개합니다.
3489
3490v2.1.282 이전에는 실패가 설명 없이 나타났습니다: `claude --resume <session-id>`는 `Failed to resume session <session-id>`에서 끝났고 `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read` 같은 시스템 오류 텍스트만 출력했습니다.
3271 3491
3272<h3 id="cannot-switch-renderers-in-this-session">3492<h3 id="cannot-switch-renderers-in-this-session">
3273 이 세션에서 렌더러를 전환할 수 없음3493 이 세션에서 렌더러를 전환할 수 없음
3274</h3>3494</h3>
3275 3495
3276렌더러를 전환하면 Claude Code가 프로세스를 다시 시작합니다. Claude Code가 다시 시작하기를 거부하는 세션에서 [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했으므로 전환되지 않고 아무것도 저장되지 않습니다. 어떤 메시지를 보는지는 원인을 알려줍니다:3496렌더러를 전환하면 Claude Code가 프로세스를 다시 시작합니다. [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 Claude Code가 다시 시작하기를 거부하는 세션에서 실행했으므로 전환하지 않고 아무것도 저장하지 않습니다. 어떤 메시지를 보는지는 원인을 알려줍니다:
3497
3498* `Cannot switch renderers while work is running in the background`: 백그라운드 셸 또는 하위 에이전트 같은 재시작이 중단할 백그라운드 작업이 실행 중입니다. [`/tasks`](/docs/ko/commands)로 작업이 완료될 때까지 기다리거나 중지한 후 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다.
3499*
3277 3500
3278* `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 하위 에이전트 같은 백그라운드에서 실행 중인 작업이 있습니다. 재시작이 이를 중단할 것입니다. 작업이 완료될 때까지 기다리거나 [`/tasks`](/docs/ko/commands)로 중지한 후 `/tui fullscreen` 또는 `/tui default`를 다시 실행하세요.3501`Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 어쨌든 다시 시작했고 다시 시작된 세션이 제한 없이 실행되었습니다.
3279* `Cannot switch renderers in this session`: 세션에 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 어쨌든 다시 시작했으며 다시 시작된 세션이 없이 실행되었습니다.
3280 3502
3281제한 메시지에서 괄호 안의 부분이 Claude Code가 발견한 제한을 이름 지정합니다:3503제한 메시지에서 괄호 안의 부분은 Claude Code가 찾은 제한을 이름 지정합니다:
3282 3504
3283```text theme={null}3505```text theme={null}
3284Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.3506Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.
3286 3508
3287메시지가 괄호 안에 표시할 수 있는 각 이유:3509메시지가 괄호 안에 표시할 수 있는 각 이유:
3288 3510
3289* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: 다시 시작된 프로세스로 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 및 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)이 포함됩니다.3511* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 및 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)이 포함됩니다.
3290* `permission rules set for this session only`: 훅 또는 SDK 호출자의 [권한 업데이트](/docs/ko/hooks#permission-update-entries)가 `session` 대상으로 거부 또는 요청 규칙을 추가했습니다. 세션 범위 허용 규칙은 거부를 트리거하지 않습니다. 재시작이 이를 제거하고 Claude Code가 대신 다시 프롬프트합니다.3512* `permission rules set for this session only`: 훅 또는 SDK 호출자의 [권한 업데이트](/docs/ko/hooks#permission-update-entries)가 `session` 대상으로 거부 또는 요청 규칙을 추가했습니다. 세션 범위 허용 규칙은 거부를 트리거하지 않습니다. 재시작이 이를 제거하고 Claude Code가 대신 다시 프롬프트합니다.
3291* `ask-before-running rules with no command-line form`: 훅 또는 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 전달하는 규칙과 함께 요청 규칙을 추가했습니다. 요청 규칙에 대한 플래그는 없습니다.3513* `ask-before-running rules with no command-line form`: 훅 또는 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 전달하는 규칙과 함께 요청 규칙을 추가했습니다. 요청 규칙에 대한 플래그는 없습니다.
3292* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 중간에 규칙 또는 디렉토리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄이 같은 값으로 텍스트를 전달할 수 없습니다.3514* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 중간에 규칙 또는 디렉토리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄이 텍스트를 동일한 값으로 전달할 수 없습니다.
3293 3515
3294**해야 할 일:**3516**해야 할 일:**
3295 3517
3296* 이러한 제한 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나 다시 전환하려면 `/tui default`를 실행하세요. Claude Code는 [`tui` 설정](/docs/ko/settings-reference#tui)을 거기에 저장합니다.3518* 이러한 제한 없이 시작된 세션에서 `/tui fullscreen` 또는 `/tui default`를 실행하여 다시 전환합니다. Claude Code는 [`tui` 설정](/docs/ko/settings-reference#tui)을 거기에 저장합니다.
3297 3519
3298<h3 id="couldnt-open-claude-desktop">3520<h3 id="couldnt-open-claude-desktop">
3299 Claude Desktop을 열 수 없음3521 Claude Desktop을 열 수 없음
3300</h3>3522</h3>
3301 3523
3302[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했는데 Claude Desktop을 열기 위해 Claude Code가 사용하는 시스템 명령어가 실패했습니다. 세션은 터미널에 남아 있습니다.3524[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했고 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령어가 실패했습니다. 세션은 터미널에 남아 있습니다.
3303 3525
3304```text theme={null}3526```text theme={null}
3305Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.3527Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.
3307 3529
3308**해야 할 일:**3530**해야 할 일:**
3309 3531
3310* Claude Desktop을 직접 열고 `/desktop`을 다시 실행하세요.3532* Claude Desktop을 직접 열고 `/desktop`을 다시 실행합니다.
3311* 해당 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행한 후 디버그 로그를 확인하세요.3533* 해당 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행한 후 디버그 로그를 확인합니다.
3312 3534
3313v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였으며 무엇이 실패했는지 말하지 않았습니다.3535v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였고 무엇이 실패했는지 말하지 않았습니다.
3314 3536
3315<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3537<h3 id="terminal-setup-left-your-zed-keymap-unchanged">
3316 /terminal-setup이 Zed 키맵을 변경하지 않음3538 /terminal-setup이 Zed 키맵을 변경하지 않음
3317</h3>3539</h3>
3318 3540
3319Zed에서 [`/terminal-setup`](/docs/ko/terminal-config#enter-multiline-prompts)을 실행했는데 Claude Code가 Zed `keymap.json`에 대한 업데이트를 완료할 수 없어서 파일을 그대로 두었습니다.3541Zed에서 [`/terminal-setup`](/docs/ko/terminal-config#enter-multiline-prompts)을 실행했고 Claude Code가 Zed `keymap.json`에 대한 업데이트를 완료할 수 없어서 파일을 그대로 두었습니다.
3320 3542
3321각 메시지는 키맵 경로를 이름 지정하고 직접 추가할 키바인딩 블록으로 끝납니다:3543각 메시지는 키맵 경로를 이름 지정하고 직접 추가할 키바인딩 블록으로 끝납니다:
3322 3544
3326{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }3548{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }
3327```3549```
3328 3550
3329메시지의 첫 줄이 원인을 이름 지정합니다:3551메시지의 첫 줄은 원인을 이름 지정합니다:
3330 3552
3331* `Couldn't read your Zed keymap, so it was left unchanged.`: Claude Code가 파일을 읽을 수 없습니다. 예를 들어 파일 권한 때문입니다.3553* `Couldn't read your Zed keymap, so it was left unchanged.`: Claude Code가 파일을 읽을 수 없습니다. 예를 들어 파일 권한 때문입니다.
3332* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일이 잘 읽혔지만 `//` 주석 및 후행 쉼표가 허용되어도 키바인딩 블록 배열로 파싱되지 않습니다.3554* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일이 잘 읽혔지만 `//` 주석 및 후행 쉼표가 허용되어도 키바인딩 블록 배열로 파싱되지 않습니다.
3335 3557
3336**해야 할 일:**3558**해야 할 일:**
3337 3559
3338* 메시지의 블록을 메시지가 이름 지정한 경로의 `keymap.json`의 최상위 배열에 복사하세요.3560* 메시지의 블록을 메시지가 이름 지정하는 경로의 `keymap.json`의 최상위 배열에 복사합니다.
3339* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 후 `/terminal-setup`을 다시 실행하세요.3561* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 후 `/terminal-setup`을 다시 실행합니다.
3340 3562
3341v2.1.247 이전에는 `/terminal-setup`이 `//` 주석 또는 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 설치된 것으로 보고하면서 자체 바인딩만으로 전체 파일을 바꿨습니다. 이전 버전이 바꾼 키맵을 복원하려면 [멀티라인 프롬프트 입력](/docs/ko/terminal-config#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용하세요.3563v2.1.247 이전에는 `/terminal-setup`이 `//` 주석 또는 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었고 전체 파일을 자신의 바인딩만으로 바꾸면서 바인딩이 설치되었다고 보고했습니다. 이전 버전이 바꾼 키맵을 복원하려면 [멀티라인 프롬프트 입력](/docs/ko/terminal-config#enter-multiline-prompts) 아래에 설명된 `.bak` 백업 파일을 사용합니다.
3342 3564
3343<h3 id="skill-usage-reports-are-not-available-on-this-connection">3565<h3 id="skill-usage-reports-are-not-available-on-this-connection">
3344 이 연결에서 스킬 사용 보고서를 사용할 수 없음3566 스킬 사용 보고서는 이 연결에서 사용할 수 없음
3345</h3>3567</h3>
3346 3568
3347[Remote Control](/docs/ko/remote-control)을 통해 [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행했습니다. 휴대폰 또는 브라우저에서 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며 대신 이 메시지로 응답합니다:3569[Remote Control](/docs/ko/remote-control)을 통해, 휴대폰 또는 브라우저에서 [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않고 대신 이 메시지로 응답합니다:
3348 3570
3349```text theme={null}3571```text theme={null}
3350Skill usage reports are not available on this connection.3572Skill usage reports are not available on this connection.
3352 3574
3353**해야 할 일:**3575**해야 할 일:**
3354 3576
3355* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나 거기서 `claude -p "/skill-doctor"`를 실행하세요.3577* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나 거기서 `claude -p "/skill-doctor"`를 실행합니다.
3356 3578
3357<h3 id="custom-output-styles-cant-be-selected-over-remote-control">3579<h3 id="custom-output-styles-cant-be-selected-over-remote-control">
3358 Remote Control 또는 릴레이된 메시지에서 사용자 정의 출력 스타일을 선택할 수 없음3580 사용자 정의 출력 스타일을 Remote Control을 통해 선택할 수 없음
3359</h3>3581</h3>
3360 3582
3361모바일 앱 또는 웹을 통해 [Remote Control](/docs/ko/remote-control)에서 [`/output-style`](/docs/ko/output-styles#change-your-output-style)을 실행했거나, 명령어가 세션으로 릴레이된 메시지에 도착했습니다. 이러한 턴은 계정 소유자에게서 오지 않을 수 있으므로 Claude Code는 [기본 제공 스타일](/docs/ko/output-styles#built-in-output-styles)만 나열하고 선택합니다. [사용자 정의 스타일](/docs/ko/output-styles#create-a-custom-output-style) 이름은 존재하지 않는 이름과 같은 응답을 받습니다:3583[Remote Control](/docs/ko/remote-control)을 통해 모바일 앱 또는 웹에서 [`/output-style`](/docs/ko/output-styles#change-your-output-style)을 실행했거나 명령어가 세션으로 릴레이된 메시지에 도착했습니다. 이러한 턴이 계정 소유자에게서 오지 않을 수 있으므로 Claude Code는 [기본 제공 스타일](/docs/ko/output-styles#built-in-output-styles)만 나열하고 선택하며 명령어가 스타일을 나열하거나 제공한 이름을 인식하지 못할 때마다 이 공지를 추가합니다. [사용자 정의 스타일](/docs/ko/output-styles#create-a-custom-output-style) 이름은 존재하지 않는 이름과 동일한 응답을 받습니다:
3362 3584
3363```text theme={null}3585```text theme={null}
3364Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.3586Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.
3366 3588
3367**해야 할 일:**3589**해야 할 일:**
3368 3590
3369* 기본 제공 스타일을 선택하세요. 예를 들어 `/output-style concise`3591* 기본 제공 스타일을 선택합니다. 예를 들어 `/output-style concise`.
3370* 사용자 정의 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션이 자체 터미널을 가지고 있으면 거기서 `/output-style <style>`을 실행하세요.3592* 사용자 정의 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle)을 설정하거나 세션 자체의 터미널에서 `/output-style <style>`을 실행합니다(있는 경우).
3371 3593
3372<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">3594<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">
3373 출력 스타일이 이 세션이 로드하지 않는 로컬 설정에 저장됨3595 출력 스타일이 이 세션이 로드하지 않는 로컬 설정에 저장됨
3374</h3>3596</h3>
3375 3597
3376`/output-style <style>` 또는 `/config outputStyle=<style>`으로 [출력 스타일](/docs/ko/output-styles)을 전환하려고 했습니다. 설정 소스가 `local`을 제외하는 세션에서 실행했습니다. 예를 들어 [`settingSources`](/docs/ko/agent-sdk/typescript#options)가 `"local"`을 생략하는 [Agent SDK](/docs/ko/agent-sdk/typescript) 세션과 [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 값이 `local`을 생략하는 CLI 세션입니다. 두 명령어 모두 스타일을 `.claude/settings.local.json`에 저장합니다. 이러한 세션은 절대 이 파일을 다시 읽지 않으므로 Claude Code는 효과가 없을 설정을 쓰는 대신 거부합니다:3598이 세션의 설정 소스가 `local`을 제외하는 세션에서 `/output-style <style>` 또는 `/config outputStyle=<style>`으로 [출력 스타일](/docs/ko/output-styles)을 전환하려고 했습니다. 예를 들어 [`settingSources`](/docs/ko/agent-sdk/typescript#options)가 `"local"`을 생략하는 [Agent SDK](/docs/ko/agent-sdk/typescript) 세션과 [`--setting-sources`](/docs/ko/cli-reference#cli-flags) 값이 `local`을 생략하는 CLI 세션입니다. 두 명령어 모두 스타일을 `.claude/settings.local.json`에 저장합니다. 이러한 세션은 절대 다시 읽지 않으므로 Claude Code는 효과가 없을 설정을 쓰는 대신 거부합니다:
3377 3599
3378```text theme={null}3600```text theme={null}
3379Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.3601Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.
3381 3603
3382**해야 할 일:**3604**해야 할 일:**
3383 3605
3384* 세션의 설정 소스에 `local`을 추가하고 다시 전환하세요.3606* 세션의 설정 소스에 `local`을 추가하고 다시 전환합니다.
3385* 세션이 로드하는 설정 파일(예: 프로젝트의 `.claude/settings.json` 또는 `~/.claude/settings.json`)에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle) 키를 설정하세요. TypeScript SDK에서는 대신 인라인 `settings` 객체 내에 `outputStyle`을 설정하세요. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요.3607* 세션이 로드하는 설정 파일(예: 프로젝트의 `.claude/settings.json` 또는 `~/.claude/settings.json`)에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle) 키를 설정합니다. TypeScript SDK에서 대신 인라인 `settings` 객체 내에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style)를 참조하세요.
3386 3608
3387<h2 id="plugin-errors">3609<h2 id="plugin-errors">
3388 플러그인 오류3610 플러그인 오류
3452* 마켓플레이스의 이름을 예약된 이름의 철자를 지정하지 않는 이름으로 바꾸고 다시 추가하십시오.3674* 마켓플레이스의 이름을 예약된 이름의 철자를 지정하지 않는 이름으로 바꾸고 다시 추가하십시오.
3453* 무시된 항목 경고의 경우 제공하는 `claude plugin marketplace remove` 명령을 실행하거나 `~/.claude/plugins/known_marketplaces.json`에서 항목을 제거하십시오.3675* 무시된 항목 경고의 경우 제공하는 `claude plugin marketplace remove` 명령을 실행하거나 `~/.claude/plugins/known_marketplaces.json`에서 항목을 제거하십시오.
3454 3676
3677<h3 id="claude-code-refuses-the-marketplace-name">
3678 Claude Code refuses the marketplace name
3679</h3>
3680
3681등록된 마켓플레이스의 이름이 [공식 Anthropic 마켓플레이스를 사칭합니다](/docs/ko/plugins/marketplace-reference#reserved-names). 해당 섹션에 나열된 규칙에 따릅니다.
3682
3683마켓플레이스가 확인이 이를 차단하기 전에 이러한 이름으로 등록된 경우 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. Claude Code는 마켓플레이스의 카탈로그를 읽을 때마다 이름을 확인하기 때문입니다. 이름이 공식 이름을 모방할 때 `claude plugin list` 및 `/plugin` **오류** 탭은 다음과 같이 시작하는 메시지와 함께 영향을 받는 각 플러그인을 보고합니다:
3684
3685```text theme={null}
3686Claude Code refuses the marketplace name "anthropic-plugins-v2"
3687```
3688
3689모방하는 이름의 경우 마켓플레이스 자체의 오류는 `Claude Code refuses this marketplace's name: it looks like one of Anthropic's own` 대신 읽습니다. `claude plugin marketplace add`는 모든 사칭 이름을 `Marketplace name impersonates an official Anthropic/Claude marketplace`로 거부합니다.
3690
3691v2.1.282 이전에는 `claude plugin list` 및 `/plugin`이 모방하는 이름의 플러그인을 마켓플레이스의 이름을 원인으로 명명하지 않고 로드 실패로 보고했습니다.
3692
3693**수행할 작업:**
3694
3695* `claude plugin marketplace remove <name>`을 실행하십시오. 이는 또한 마켓플레이스에서 설치된 플러그인을 제거하고 저장된 데이터를 삭제합니다.
3696* 대신 마켓플레이스를 유지하려면 유지 관리자가 이름을 바꿀 때까지 기다린 다음 `claude plugin marketplace update <name>`을 실행하십시오.
3697* 마켓플레이스를 게시하는 경우 `marketplace.json`에서 이름을 바꾸십시오. 사용자는 제거하는 대신 마켓플레이스를 업데이트합니다.
3698
3455<h3 id="marketplace-is-already-added-from-a-different-source">3699<h3 id="marketplace-is-already-added-from-a-different-source">
3456 Marketplace is already added from a different source3700 Marketplace is already added from a different source
3457</h3>3701</h3>
3654 3898
3655* claude.ai 조직의 관리자에게 claude.ai에서 플러그인의 필수 상태를 변경하도록 요청하십시오.3899* claude.ai 조직의 관리자에게 claude.ai에서 플러그인의 필수 상태를 변경하도록 요청하십시오.
3656 3900
3901<h3 id="plugin-was-not-uninstalled">
3902 Plugin was not uninstalled
3903</h3>
3904
3905[`claude plugin uninstall`](/docs/ko/plugins/cli-reference#plugin-uninstall)을 실행했거나 `/plugin` **설치됨** 탭에서 **제거**를 선택했으며 제거가 `"<plugin>" was not uninstalled:`로 시작하는 메시지와 함께 중지되었습니다.
3906
3907Claude Code가 `enabledPlugins`에서 플러그인의 항목을 제거하고 해당 범위의 설정 파일을 다시 읽었을 때 플러그인이 여전히 켜져 있었거나 이를 켤 수 있는 파일을 읽거나 확인할 수 없었습니다. 설정 항목이 이를 다시 켤 수 있는 동안 플러그인의 저장된 옵션, 비밀 및 데이터를 삭제하면 이를 잃게 되므로 제거가 대신 중지됩니다: 플러그인은 설치된 상태로 유지되고 저장된 것은 삭제되지 않습니다.
3908
3909```text theme={null}
3910✘ Failed to uninstall plugin "formatter": "formatter" was not uninstalled: it is still switched on in /home/user/project/.claude/settings.local.json, although the settings change reported no error. It is still installed. Take it out of "enabledPlugins" in that file yourself, then uninstall it again.
3911```
3912
3913메시지의 중간 부분은 파일과 원인의 이름을 지정합니다:
3914
3915* `it is still switched on in <file>, although the settings change reported no error`: 설정 쓰기가 성공를 보고했지만 파일을 읽을 때 항목이 여전히 있음
3916* `it is still switched on in <file>, and the settings change failed (<error>)`: 파일을 저장할 수 없음. 괄호 안의 이유
3917* `<file> is there and could not be read`: 파일이 존재하지만 설정으로 읽을 수 없음. 예를 들어 유효한 JSON이 아니므로 플러그인을 여전히 활성화할 수 있음
3918* `<file> (not read: it is on a network path or is a link to one, or could not be checked)`: Claude Code가 프로젝트 또는 로컬 설정 파일을 읽지 않았습니다. 파일 또는 이를 보유한 `.claude` 폴더가 네트워크 위치로 이어지는 링크이거나 해당 경로를 검사할 수 없기 때문입니다.
3919
3920`claude plugin uninstall`은 종료 코드 1로 종료되며 `--json`을 사용하면 결과는 `failureCode: "settings_still_on"`을 전달합니다. `/plugin`은 동일한 메시지를 표시합니다.
3921
3922**수행할 작업:**
3923
3924* 메시지의 마지막 문장을 따르십시오: 이를 명명한 설정 파일을 복구하거나 바꾸거나 해당 파일의 `enabledPlugins`에서 플러그인의 항목을 직접 제거한 다음 제거를 다시 실행하십시오.
3925
3657<h2 id="tool-errors">3926<h2 id="tool-errors">
3658 도구 오류3927 도구 오류
3659</h2>3928</h2>
3703* Claude가 파일을 변경할 수 있어야 하면 `/permissions`의 `Read` 거부 규칙을 제거하거나 좁힙니다. 또는 [설정](/docs/ko/settings-reference#permission-settings)에서 제거합니다.3972* Claude가 파일을 변경할 수 있어야 하면 `/permissions`의 `Read` 거부 규칙을 제거하거나 좁힙니다. 또는 [설정](/docs/ko/settings-reference#permission-settings)에서 제거합니다.
3704* 파일이 그대로 유지되어야 하면 규칙을 유지하고 NotebookEdit 도구도 차단하기 위해 동일한 경로에 `Edit` 거부 규칙을 추가합니다.3973* 파일이 그대로 유지되어야 하면 규칙을 유지하고 NotebookEdit 도구도 차단하기 위해 동일한 경로에 `Edit` 거부 규칙을 추가합니다.
3705 3974
3975<h3 id="path-cannot-contain-null-bytes">
3976 경로에 null 바이트가 포함될 수 없음
3977</h3>
3978
3979파일 도구 호출의 경로 또는 패턴 인수에 null 바이트가 포함되어 있으며, 파일 시스템과 검색 도구는 이를 수락할 수 없습니다. Read, Write, Edit, NotebookEdit, Glob 및 Grep은 이를 확인하고 메시지는 도구와 인수의 이름을 지정합니다:
3980
3981```text theme={null}
3982Read file_path cannot contain null bytes (\0). Remove the null byte and try again.
3983```
3984
3985도구 호출이 실패하고 Claude는 오류를 보며 턴이 계속됩니다.
3986
3987**할 일:**
3988
3989* 당신 쪽에서는 아무것도 할 필요가 없습니다: 오류는 도구의 결과로 Claude에 반환되며 메시지 자체가 Claude에 null 바이트를 제거하고 다시 시도하도록 지시합니다.
3990
3991v2.1.281 이전에는 Read, Write, Edit 또는 NotebookEdit 경로의 null 바이트가 `Path contains null bytes`라는 이름의 오류로 전체 턴을 종료했으며 도구는 실행되지 않았습니다.
3992
3706<h3 id="subagent-type-is-required">3993<h3 id="subagent-type-is-required">
3707 subagent\_type이 필수입니다3994 subagent\_type이 필수입니다
3708</h3>3995</h3>
3883 4170
3884* `its symlink resolution changed after permission was checked`: 경로를 따라 또는 Grep 또는 Glob 검색 루트에서 기호 링크가 권한 확인과 작업 사이에 대체되었습니다. 읽기 거부에서 괄호 안의 구문은 어느 비교가 실패했는지 지정합니다.4171* `its symlink resolution changed after permission was checked`: 경로를 따라 또는 Grep 또는 Glob 검색 루트에서 기호 링크가 권한 확인과 작업 사이에 대체되었습니다. 읽기 거부에서 괄호 안의 구문은 어느 비교가 실패했는지 지정합니다.
3885* `its parent-directory symlink resolution changed after permission was checked`: 쓰기 경로가 통과하는 디렉토리가 더 이상 승인된 위치로 해석되지 않습니다.4172* `its parent-directory symlink resolution changed after permission was checked`: 쓰기 경로가 통과하는 디렉토리가 더 이상 승인된 위치로 해석되지 않습니다.
3886* `it is a symbolic link. Write to the link's target path instead`: 기호 링크가 승인된 쓰기 위치 자체에 있습니다. 예를 들어 `CLAUDE.md`가 `AGENTS.md`로의 기호 링크입니다. 메시지는 Claude를 링크의 대상으로 지시합니다.4173* `where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve)`: Claude Code가 경로를 디스크의 최종 위치로 따를 수 없습니다. 예를 들어 경로의 기호 링크가 루프를 형성하거나 링크가 해석되지 않는 경우입니다.
4174* `it is a symbolic link. Write to the link's target path instead`: 기호 링크가 요청된 쓰기 위치 자체에 있습니다. 예를 들어 `CLAUDE.md`가 `AGENTS.md`로의 기호 링크입니다. 메시지는 Claude를 링크의 대상으로 지시합니다.
3887* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`: 다른 작성자가 파일을 열 때 같은 조건이 포착됩니다. 예를 들어 기호 링크된 `.mcp.json`에 대한 쓰기입니다.4175* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`: 다른 작성자가 파일을 열 때 같은 조건이 포착됩니다. 예를 들어 기호 링크된 `.mcp.json`에 대한 쓰기입니다.
3888* `Refusing to write into symlinked directory: <path>`: 파일을 보유한 디렉토리 자체가 기호 링크입니다. 예를 들어 프로젝트의 `.claude/` 디렉토리가 다른 위치로 연결되어 있습니다.4176* `Refusing to write into symlinked directory: <path>`: 파일을 보유한 디렉토리 자체가 기호 링크입니다. 예를 들어 프로젝트의 `.claude/` 디렉토리가 다른 위치로 연결되어 있습니다.
3889* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`: `Read` 거부 규칙이 기호 링크를 통과하는 경로의 이름을 지정했고 Claude Code가 검색을 준비하는 동안 해당 링크가 변경되었습니다.4177* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`: `Read` 거부 규칙이 기호 링크를 통과하는 경로의 이름을 지정했고 Claude Code가 검색을 준비하는 동안 해당 링크가 변경되었습니다.
3901 4189
3902v2.1.251 이전에는 Claude Code가 파일 쓰기에 대해서만 경로의 해석을 다시 확인했으므로 권한 확인 후 대체된 링크가 메시지 없이 읽기 또는 검색을 다른 위치로 리디렉션할 수 있었습니다. 이러한 거부 중에서 부모 디렉토리, 기호 링크를 통한, 그리고 기호 링크된 디렉토리 쓰기 거부만 이전 버전에 나타납니다.4190v2.1.251 이전에는 Claude Code가 파일 쓰기에 대해서만 경로의 해석을 다시 확인했으므로 권한 확인 후 대체된 링크가 메시지 없이 읽기 또는 검색을 다른 위치로 리디렉션할 수 있었습니다. 이러한 거부 중에서 부모 디렉토리, 기호 링크를 통한, 그리고 기호 링크된 디렉토리 쓰기 거부만 이전 버전에 나타납니다.
3903 4191
4192v2.1.280 이전에는 `where it leads on disk could not be determined` 거부가 나타나지 않았습니다.
4193
3904<h3 id="task-output-swap-refused">4194<h3 id="task-output-swap-refused">
3905 작업 출력 스왑 거부4195 작업 출력 스왑 거부
3906</h3>4196</h3>
3926* 또는 Claude Code 임시 디렉토리 아래의 프로젝트 디렉토리를 확인합니다. 예제 메시지의 `/private/tmp/claude-501/-Users-you-my-project`입니다. 해당 경로가 기호 링크이거나 거기에 있으면 안 되는 디렉토리이면 링크의 대상이 아닌 링크 또는 디렉토리 자체를 제거하고 Claude Code를 다시 시작합니다.4216* 또는 Claude Code 임시 디렉토리 아래의 프로젝트 디렉토리를 확인합니다. 예제 메시지의 `/private/tmp/claude-501/-Users-you-my-project`입니다. 해당 경로가 기호 링크이거나 거기에 있으면 안 되는 디렉토리이면 링크의 대상이 아닌 링크 또는 디렉토리 자체를 제거하고 Claude Code를 다시 시작합니다.
3927* 거부가 반복되면 프로세스가 세션이 실행되는 동안 Claude Code의 임시 디렉토리 아래의 항목을 대체, 링크 또는 제거합니다. [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 다른 것이 관리하지 않는 디렉토리로 설정하고 다시 시작합니다.4217* 거부가 반복되면 프로세스가 세션이 실행되는 동안 Claude Code의 임시 디렉토리 아래의 항목을 대체, 링크 또는 제거합니다. [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 다른 것이 관리하지 않는 디렉토리로 설정하고 다시 시작합니다.
3928 4218
4219<h3 id="disk-quota-or-temp-filesystem-is-full">
4220 디스크 할당량 또는 임시 파일 시스템이 가득 참
4221</h3>
4222
4223Claude Code는 각 Bash 및 PowerShell 명령의 출력을 임시 디렉토리 아래의 파일에 저장합니다. 명령이 0이 아닌 코드로 종료되고 출력이 전혀 없으면 Claude Code는 해당 파일을 보유한 파일 시스템이 공간 또는 inode가 부족한지, 또는 디스크 할당량이 사용되었는지 확인합니다. 그렇다면 진단이 빈 출력 대신 명령의 결과에 나타납니다:
4224
4225```text wrap theme={null}
4226Your 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.
4227```
4228
4229메시지는 무엇이 부족한지 지정합니다:
4230
4231* `Your disk quota is full ... (EDQUOT)`: 해당 파일 시스템에 대한 당신의 할당량이 사용되었습니다. 할당량은 파일 시스템이 여전히 여유 공간을 표시하는 동안 가득 찰 수 있습니다.
4232* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`: 파일 시스템 또는 할당량에 공간이 남지 않았습니다.
4233* `Command output was lost: the temp filesystem at ... is full` 또는 `... is out of inodes`: 파일 시스템에 거의 여유 공간이 남지 않았거나 inode가 부족합니다.
4234
4235**할 일:**
4236
4237* Claude Code의 임시 디렉토리를 보유한 파일 시스템에서 더 이상 필요하지 않은 파일을 삭제합니다. `EDQUOT`의 경우 당신의 할당량에 포함되는 파일을 삭제합니다. `out of inodes`의 경우 각 파일이 크기에 관계없이 하나의 inode를 차지하므로 몇 개의 큰 파일이 아닌 많은 파일을 삭제합니다.
4238* 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 여유 공간이 있는 파일 시스템의 디렉토리로 설정하여 Claude Code를 다시 시작합니다.
4239* 그런 다음 Claude에 명령을 다시 실행하도록 합니다. 인쇄한 출력은 손실되었으며 잘리지 않았습니다.
4240
3929<h3 id="the-source-file-is-not-valid-utf-8-text">4241<h3 id="the-source-file-is-not-valid-utf-8-text">
3930 소스 파일이 유효한 UTF-8 텍스트가 아님4242 소스 파일이 유효한 UTF-8 텍스트가 아님
3931</h3>4243</h3>
4275 4587
4276일부 계정에서 메시지는 `background service` 대신 `daemon`을 말합니다.4588일부 계정에서 메시지는 `background service` 대신 `daemon`을 말합니다.
4277 4589
4278npm 설치에서 `npm install -g @anthropic-ai/claude-code`가 바이너리를 대체하는 동안 나타나는 `EUNKNOWN`은 [`EACCES` during a reinstall](#eacces-when-starting-a-background-session)과 같은 원인을 가지며 설치가 완료된 후 재시도할 때 지워집니다.4590npm 설치에서 `npm install -g @anthropic-ai/claude-code`가 바이너리를 대체하는 동안 나타나는 `EUNKNOWN`은 [백그라운드 세션을 시작할 때 EACCES](#eacces-when-starting-a-background-session)와 같은 원인을 가지며 설치가 완료된 후 재시도할 때 지워집니다.
4279 4591
4280Claude Code는 서비스가 터미널을 닫을 때 생존하도록 PowerShell을 통해 백그라운드 서비스를 시작하며, PowerShell 7이 설치되어 있으면 PowerShell 7을 사용하고 그렇지 않으면 Windows PowerShell 5.1을 사용합니다. PowerShell이 실행될 수 없으면 Claude Code는 대신 서비스를 직접 시작하므로 PowerShell만 차단하는 정책은 이 오류를 발생시키지 않습니다. npm 설치가 실행 중이 아닌 동안 이를 보면 정책이 Claude Code 실행 파일 자체를 차단합니다.4592Claude Code는 서비스가 터미널을 닫을 때 생존하도록 PowerShell을 통해 백그라운드 서비스를 시작하며, PowerShell 7이 설치되어 있으면 PowerShell 7을 사용하고 그렇지 않으면 Windows PowerShell 5.1을 사용합니다. PowerShell이 실행될 수 없으면 Claude Code는 대신 서비스를 직접 시작하므로 PowerShell만 차단하는 정책은 이 오류를 발생시키지 않습니다. npm 설치가 실행 중이 아닌 동안 이를 보면 정책이 Claude Code 실행 파일 자체를 차단합니다.
4281 4593
4341 백그라운드 세션을 시작할 때 작업 디렉토리가 더 이상 존재하지 않음4653 백그라운드 세션을 시작할 때 작업 디렉토리가 더 이상 존재하지 않음
4342</h3>4654</h3>
4343 4655
4344더 이상 존재하지 않는 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하려고 했습니다. 이는 에이전트 뷰에서 디스패치하거나 작업 중인 디렉토리가 삭제되거나 이동된 후 `/background`를 실행할 때 발생합니다. 또한 프로세스가 종료되고 디렉토리가 없는 세션에 연결하거나 다시 시작할 때 발생합니다. 새 프로세스가 같은 디렉토리에서 시작되기 때문입니다. Claude Code는 세션을 시작하지 않으며 메시지는 누락된 디렉토리를 명시합니다:4656더 이상 존재하지 않는 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하려고 했습니다. Claude Code는 세션을 시작하지 않으며 메시지는 누락된 디렉토리를 명시합니다:
4345 4657
4346```text theme={null}4658```text theme={null}
4347Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)4659Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)
4353 4665
4354* 메시지가 명시하는 디렉토리를 다시 만들거나 존재하는 디렉토리에서 디스패치한 다음 다시 시도합니다.4666* 메시지가 명시하는 디렉토리를 다시 만들거나 존재하는 디렉토리에서 디스패치한 다음 다시 시도합니다.
4355 4667
4668<h3 id="workspace-not-trusted-when-dispatching-a-background-session">
4669 백그라운드 세션을 디스패치할 때 작업 공간을 신뢰하지 않음
4670</h3>
4671
4672[신뢰하지 않은](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하거나 다시 시작했으며, 작업 공간 신뢰 대화가 나타날 수 없었습니다. Claude Code는 세션을 시작하지 않습니다:
4673
4674```text theme={null}
4675Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.
4676```
4677
4678세션의 자체 디렉토리의 터미널에서 같은 명령은 신뢰 대화를 대신 표시하고 수락하면 세션을 시작합니다. 이 메시지는 스크립트와 같이 대화가 나타날 수 없는 곳이나 다른 디렉토리에서 세션을 다시 시작할 때 나타납니다.
4679
4680두 가지 변형은 다른 원인을 명시합니다:
4681
4682* **`The home directory is trusted one session at a time`**: 세션의 디렉토리는 홈 디렉토리입니다. Claude Code는 홈 디렉토리에 대한 신뢰를 절대 저장하지 않으므로 이전 세션에서 대화를 수락해도 계산되지 않습니다.
4683* **`<path> could not be resolved on disk`**: Claude Code가 디스크에서 세션의 디렉토리를 찾을 수 없었습니다.
4684
4685**할 일:**
4686
4687* 메시지가 명시하는 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락한 다음 명령을 다시 실행합니다.
4688* 홈 디렉토리 메시지의 경우 홈 디렉토리의 터미널에서 명령을 실행하여 대화가 나타날 수 있도록 하거나 프로젝트 디렉토리에서 대신 세션을 시작합니다.
4689* `could not be resolved on disk` 메시지의 경우 디렉토리를 다시 만들거나 존재하는 디렉토리에서 새 세션을 시작합니다.
4690
4356<h2 id="wrapper-and-ide-errors">4691<h2 id="wrapper-and-ide-errors">
4357 래퍼 및 IDE 오류4692 래퍼 및 IDE 오류
4358</h2>4693</h2>
4532 구성 경고4867 구성 경고
4533</h2>4868</h2>
4534 4869
4535Claude Code는 이러한 메시지의 대부분을 stderr에 기록하며, 대부분을 시작 시에 기록합니다. 항목이 디버그 로그나 대화 보기의 시작 알림 같은 다른 곳에 나타나거나 [인식되지 않은 모델 진단 라인](#unrecognized-model-id-on-a-request)처럼 요청 시간에 나타나는 경우 그렇게 표시됩니다.4870Claude Code는 이러한 메시지 대부분을 대화가 아닌 stderr에 기록하며, 대부분 시작 시에 기록합니다. 항목이 디버그 로그나 대화 보기의 시작 알림 같은 다른 곳에 나타나거나 요청 시간의 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request) 같은 다른 시간에 나타나면 그렇게 표시됩니다.
4536 4871
4537<h3 id="fullscreen-failed-start-notice">4872<h3 id="fullscreen-failed-start-notice">
4538 전체 화면 렌더러가 시작을 완료하지 못함4873 전체 화면 렌더러가 시작을 완료하지 못함
4541이 머신의 이전 [전체 화면](/docs/ko/fullscreen) 세션이 시작을 완료하기 전에 종료되었으므로 Claude Code는 이 세션을 클래식 렌더러에서 시작하고 다음 알림 중 하나를 출력합니다:4876이 머신의 이전 [전체 화면](/docs/ko/fullscreen) 세션이 시작을 완료하기 전에 종료되었으므로 Claude Code는 이 세션을 클래식 렌더러에서 시작하고 다음 알림 중 하나를 출력합니다:
4542 4877
4543```text theme={null}4878```text theme={null}
4544Claude Code의 전체 화면 렌더러가 지난번 이 머신에서 시작을 완료하지 못했으므로 이번 실행은 클래식 렌더러를 사용합니다. 다음 실행에서 전체 화면을 다시 시도할 것입니다. /tui default는 클래식 렌더러를 유지합니다.4879Claude Code의 전체 화면 렌더러가 이 머신에서 마지막으로 시작을 완료하지 못했으므로 이번 실행은 클래식 렌더러를 사용합니다. 다음 실행에서 전체 화면을 다시 시도할 것입니다. /tui default는 클래식 렌더러를 유지합니다.
4545 4880
4546Claude Code의 전체 화면 렌더러가 이 머신에서 반복적으로 시작에 실패했으므로 여기서 비활성화되었습니다. /tui fullscreen을 실행하여 다시 시도하세요(이는 업데이트 후에도 재설정됩니다).4881Claude Code의 전체 화면 렌더러가 이 머신에서 반복적으로 시작에 실패했으므로 여기서 비활성화되었습니다. /tui fullscreen을 실행하여 다시 시도하세요(이는 업데이트 후에도 재설정됩니다).
4547```4882```
4549**할 일:**4884**할 일:**
4550 4885
4551* [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting)을 따르세요. 어떤 알림을 받는지, Claude Code가 이후 세션에서 무엇을 하는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 설명합니다.4886* [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting)을 따르세요. 어떤 알림을 받는지, Claude Code가 이후 세션에서 무엇을 하는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 설명합니다.
4552* 종료된 세션이 종료 메시지를 출력했다면 [복구할 수 없는 인터페이스 오류 후 Claude Code 종료](#exited-after-an-unrecoverable-interface-error)를 참조하여 이름이 지정된 내용을 확인하세요.4887* 종료된 세션이 종료 메시지를 출력했다면 [Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨](#exited-after-an-unrecoverable-interface-error)을 참조하여 이름이 지정된 내용을 확인하세요.
4553 4888
4554v2.1.236 이전에는 Claude Code가 알림을 출력하지 않았고 실패한 시작 후에도 계속 전체 화면 렌더링에서 세션을 시작했습니다.4889v2.1.236 이전에는 Claude Code가 알림을 출력하지 않았고 실패한 시작 후에도 전체 화면 렌더링에서 세션을 계속 시작했습니다.
4555 4890
4556<h3 id="exited-after-an-unrecoverable-interface-error">4891<h3 id="exited-after-an-unrecoverable-interface-error">
4557 복구할 수 없는 인터페이스 오류 후 Claude Code 종료4892 Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨
4558</h3>4893</h3>
4559 4894
4560Claude Code는 터미널 인터페이스가 복구할 수 없는 오류에 부딪혔을 때 종료되며, 두 렌더러 중 하나에서 이 메시지를 출력합니다. 두 번째 문장은 [전체 화면](/docs/ko/fullscreen) 렌더러가 시작되는 동안 오류가 발생했을 때만 나타납니다:4895Claude Code는 터미널 인터페이스가 복구할 수 없는 오류에 부딪혔을 때 이 메시지를 출력하고 종료합니다(두 렌더러 모두). 두 번째 문장은 [전체 화면](/docs/ko/fullscreen) 렌더러가 시작되는 동안 오류가 발생했을 때만 나타납니다:
4561 4896
4562```text theme={null}4897```text theme={null}
4563Claude Code가 복구할 수 없는 인터페이스 오류(<error>)로 인해 종료되었습니다. 전체 화면 렌더러가 시작되는 동안 발생했으므로 다음 실행은 클래식 렌더러를 사용할 것입니다(CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1은 언제든지 이를 강제합니다).4898Claude Code가 복구 불가능한 인터페이스 오류(<error>)로 인해 종료되었습니다. 전체 화면 렌더러가 시작되는 동안 발생했으므로 다음 실행은 클래식 렌더러를 사용할 것입니다(CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1은 언제든지 이를 강제합니다).
4564```4899```
4565 4900
4566**할 일:**4901**할 일:**
4574 에이전트 설명이 15.0k 토큰 제한을 초과함4909 에이전트 설명이 15.0k 토큰 제한을 초과함
4575</h3>4910</h3>
4576 4911
4577Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다. 기본 제공 에이전트를 제외한 [서브에이전트](/docs/ko/sub-agents)의 결합된 설명이 Claude Code가 추정하는 15,000 토큰을 초과합니다. 각 에이전트는 이름과 `description` frontmatter를 계산합니다. Claude Code는 총합이 제한을 초과하는지 여부와 관계없이 모든 에이전트를 로드하므로 경고는 로드되는 내용을 변경하지 않습니다.4912Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다. 기본 제공 에이전트를 제외한 [서브에이전트](/docs/ko/sub-agents)의 결합된 설명이 Claude Code가 추정하는 15,000 토큰을 초과합니다. 각 에이전트는 이름과 `description` frontmatter를 계산합니다. Claude Code는 합계가 제한을 초과하는지 여부와 관계없이 모든 에이전트를 로드하므로 경고는 로드되는 내용을 변경하지 않습니다.
4578 4913
4579```text theme={null}4914```text theme={null}
4580에이전트 설명이 15.0k 토큰 제한을 초과함(~16.2k 토큰) · Claude에게 .claude/agents/의 에이전트 설명을 정리하도록 요청하세요4915에이전트 설명이 15.0k 토큰 제한을 초과함(~16.2k 토큰) · Claude에게 .claude/agents/의 에이전트 설명을 정리하도록 요청하세요
4585* 에이전트 파일의 `description` frontmatter를 단축하거나 Claude에게 정리하도록 요청하세요.4920* 에이전트 파일의 `description` frontmatter를 단축하거나 Claude에게 정리하도록 요청하세요.
4586* 더 이상 사용하지 않는 에이전트 파일을 제거하세요.4921* 더 이상 사용하지 않는 에이전트 파일을 제거하세요.
4587 4922
4923<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">
4924 스킬, 명령 또는 워크플로우가 로드되지 않았습니다(이름이 예약됨)
4925</h3>
4926
4927스킬 폴더, frontmatter `name`, `.claude/commands/`의 파일 또는 하위 폴더, 또는 [저장된 워크플로우](/docs/ko/workflows#save-the-workflow-for-reuse)가 `anthropic-skills` 이름을 사용하거나 `anthropic-skills:`로 시작하는 이름을 사용합니다. Claude Code는 [claude.ai에서 동기화된 스킬을 위해 해당 이름을 예약](/docs/ko/skills#names-reserved-for-synced-skills)하고 해당 항목을 로드하지 않습니다.
4928
4929Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다:
4930
4931```text theme={null}
4932로드되지 않음: .claude/skills/anthropic-skills의 이름을 바꾸고 다시 시작하세요 — 해당 이름은 "anthropic-skills"를 사용하며, 이는 claude.ai 계정에서 동기화된 스킬을 위해 예약된 이름입니다
4933```
4934
4935알림은 거부된 첫 번째 항목에 대해 변경할 내용을 이름으로 지정합니다: 이름을 바꿀 폴더 또는 파일, 편집할 `name:` 줄, 또는 이름을 바꿀 워크플로우. 둘 이상의 항목이 거부되면 알림은 `· 2 more` 같은 개수로 끝나고 [디버그 로그](/docs/ko/debug-your-config)가 각각을 이름으로 지정합니다.
4936
4937**할 일:**
4938
4939* 알림이 이름으로 지정한 항목의 이름을 바꾸거나 가리키는 `name:` 줄을 편집한 후 세션을 다시 시작하세요.
4940
4941v2.1.282 이전에는 Claude Code가 이러한 이름의 스킬과 명령을 로드했습니다.
4942
4588<h3 id="workspace-has-not-been-trusted">4943<h3 id="workspace-has-not-been-trusted">
4589 작업 공간이 신뢰되지 않음4944 작업 영역이 신뢰되지 않음
4590</h3>4945</h3>
4591 4946
4592Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `permissions.allow` 규칙 또는 `permissions.additionalDirectories` 항목을 찾았지만 [프로젝트 설정의 allow 규칙은 작업 공간 신뢰가 필요](/docs/ko/permissions#project-allow-rules-and-workspace-trust)하기 때문에 적용하지 않았습니다. 개수, 설정 이름, 메시지에 명시된 파일은 구성에 따라 다릅니다. `deny` 및 `ask` 규칙은 영향을 받지 않습니다.4947Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에서 `permissions.allow` 규칙 또는 `permissions.additionalDirectories` 항목을 찾았지만 [프로젝트 설정의 allow 규칙에는 작업 영역 신뢰가 필요](/docs/ko/permissions#project-allow-rules-and-workspace-trust)하기 때문에 적용하지 않았습니다. 개수, 설정 이름, 메시지에 이름이 지정된 파일은 구성에 따라 다릅니다. `deny` 및 `ask` 규칙은 영향을 받지 않습니다.
4593 4948
4594```text theme={null}4949```text theme={null}
4595.claude/settings.local.json의 2개 permissions.allow 항목을 무시합니다: 이 작업 공간이 신뢰되지 않았습니다. 여기서 Claude Code를 대화형으로 한 번 실행하고 신뢰 대화를 수락하거나 /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted: true를 설정하세요.4950.claude/settings.local.json의 2개 permissions.allow 항목을 무시합니다: 이 작업 영역이 신뢰되지 않았습니다. 여기서 Claude Code를 대화형으로 한 번 실행하고 신뢰 대화를 수락하거나, /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted: true를 설정하세요.
4596```4951```
4597 4952
4598**할 일:**4953**할 일:**
4599 4954
4600* 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락하세요. [프로젝트 allow 규칙 및 작업 공간 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)에서 해당 수락이 어느 폴더를 포함하는지 설명합니다.4955* 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락하세요. [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)는 해당 수락이 어느 폴더를 포함하는지 설명합니다.
4601* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 대화가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 설정하세요.4956* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 대화가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 설정하세요.
4602* 메시지가 `.claude/settings.local.json`을 언급하고 git 저장소 외부 또는 홈 디렉토리에서 Claude Code를 시작했다면 v2.1.200 이상으로 업데이트하세요. 버전 2.1.196부터 2.1.199까지는 해당 작업 공간에서 자신의 `.claude/settings.local.json`을 저장소 제공으로 취급했습니다. v2.1.207 이상에서는 git 저장소 외부에서 폴더를 신뢰하지 않은 경우 업데이트만으로는 충분하지 않습니다: 폴더가 저장소 내부에 있지 않은지 확인하면 git을 실행하고 Claude Code는 신뢰 대화를 수락한 후에만 해당 검사를 실행하므로 첫 번째 단계를 사용하세요. 홈 디렉토리 및 기타 [구성 홈](/docs/ko/permissions#project-allow-rules-and-workspace-trust)은 면제되며 대화를 기다리지 않습니다. [프로젝트 allow 규칙 및 작업 공간 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.4957* 메시지가 `.claude/settings.local.json`을 이름으로 지정하고 git 저장소 외부 또는 홈 디렉토리에서 Claude Code를 시작했다면 v2.1.200 이상으로 업데이트하세요. v2.1.196부터 v2.1.199까지의 버전은 이러한 작업 영역에서 자신의 `.claude/settings.local.json`을 저장소 제공으로 취급했습니다. v2.1.207 이상에서는 git 저장소 외부에서 업데이트하는 것만으로는 충분하지 않습니다(폴더를 신뢰하지 않은 경우): 폴더가 저장소 내부가 아님을 확인하면 git을 실행하고 Claude Code는 신뢰 대화를 수락한 후에만 해당 검사를 실행하므로 첫 번째 단계를 사용하세요. 홈 디렉토리 및 기타 [구성 홈](/docs/ko/permissions#project-allow-rules-and-workspace-trust)은 면제되며 대화를 기다리지 않습니다. [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.
4603 4958
4604<h3 id="working-directory-is-a-network-path">4959<h3 id="working-directory-is-a-network-path">
4605 작업 디렉토리가 네트워크 경로임4960 작업 디렉토리가 네트워크 경로임
4606</h3>4961</h3>
4607 4962
4608Claude Code는 네트워크 경로를 작업 디렉토리로 추가하지 않습니다. 네트워크 경로를 조회하면 이름이 지정된 호스트에 연결할 수 있으며, Windows에서는 해당 연결이 호스트에 자격 증명을 보낼 수 있으므로 Claude Code는 조회 없이 경로를 거부합니다. `/add-dir`을 이러한 경로로 실행할 때 또는 시작 시 경고로 이 메시지를 봅니다. 시작 시 나타나면 Claude Code는 해당 디렉토리 없이 시작합니다.4963Claude Code는 네트워크 경로를 작업 디렉토리로 추가하지 않습니다. 네트워크 경로를 조회하면 이름이 지정된 호스트에 연결할 수 있으며, Windows에서는 해당 연결이 호스트에 자격 증명을 보낼 수 있으므로 Claude Code는 조회하지 않고 경로를 거부합니다. `/add-dir`을 이러한 경로로 실행할 때 또는 시작 시 경고로 이 메시지를 봅니다. 시작 시 나타나면 Claude Code는 해당 디렉토리 없이 시작합니다.
4609 4964
4610```text theme={null}4965```text theme={null}
4611\\server\share는 네트워크 경로이므로 작업 디렉토리로 추가할 수 없습니다. Windows에서는 공유를 드라이브 문자로 매핑하고 --add-dir로 실행 시 전달하세요(세션 중간에 추가된 드라이브 문자는 아직 원격 읽기 신뢰를 수행하지 않습니다).4966\\server\share는 네트워크 경로이므로 작업 디렉토리로 추가할 수 없습니다. Windows에서는 공유를 드라이브 문자로 매핑하고 --add-dir로 실행 시 전달하세요(세션 중간에 추가된 드라이브 문자는 아직 원격 읽기 신뢰를 수행하지 않습니다).
4621 4976
4622**할 일:**4977**할 일:**
4623 4978
4624* Windows에서는 공유를 드라이브 문자로 매핑하세요(예: `net use Z: \\server\share`). 그리고 `claude --add-dir Z:\`로 실행 시 드라이브를 전달하세요.4979* Windows에서는 `net use Z: \\server\share` 같은 명령으로 공유를 드라이브 문자로 매핑하고 `claude --add-dir Z:\`로 실행 시 드라이브를 전달하세요.
4625* macOS 또는 Linux에서는 공유를 로컬 경로에 마운트하고 해당 경로를 대신 추가하세요.4980* macOS 또는 Linux에서는 공유를 로컬 경로에 마운트하고 대신 해당 경로를 추가하세요.
4626* 경로가 `permissions.additionalDirectories`에 있으면 이를 나열하는 설정 파일에서 제거하세요.4981* 경로가 `permissions.additionalDirectories`에 있으면 이를 나열하는 설정 파일에서 제거하세요.
4627 4982
4628v2.1.257 이전에는 Claude Code가 도달 가능한 네트워크 경로를 작업 디렉토리로 수락했습니다.4983v2.1.257 이전에는 Claude Code가 도달 가능한 네트워크 경로를 작업 디렉토리로 수락했습니다.
4631 원격 관리 설정을 로드하지 못함4986 원격 관리 설정을 로드하지 못함
4632</h3>4987</h3>
4633 4988
4634세션이 [서버 관리 설정](/docs/ko/server-managed-settings)에 적합하지만 Claude Code가 이를 가져올 수 없어서 대화형 세션에 이 경고를 표시합니다. 괄호로 묶인 원인은 `network error`, `request timed out`, 또는 `authentication rejected (401)` 같은 실패한 내용을 명시하고, 줄의 나머지는 세션이 실행되는 정책을 나타냅니다:4989세션이 [서버 관리 설정](/docs/ko/server-managed-settings)에 적합하지만 Claude Code가 설정을 가져올 수 없거나 서버가 반환한 내용을 적용할 수 없어서 대화형 세션에서 이 경고를 표시합니다.
4990
4991괄호로 묶인 원인은 `network error`, `request timed out`, 또는 `authentication rejected (401)` 같은 실패한 내용을 이름으로 지정합니다. `no setting in the server response could be applied as written` 원인은 서버가 응답했지만 반환된 설정 중 [검증](/docs/ko/server-managed-settings#invalid-entries-in-delivered-settings)을 통과한 것이 없음을 의미합니다. v2.1.282 이전에는 이 원인이 `server returned invalid settings`로 읽혔습니다.
4635 4992
4636* **이전 성공적인 가져오기에서 캐시된 설정**: Claude Code는 [제외된 환경 변수](/docs/ko/server-managed-settings#fetch-and-caching-behavior)를 제외하고 캐시된 정책에서 세션을 실행하며, 줄은 `using cached policy`를 읽습니다.4993줄의 나머지 부분은 세션이 실행되는 정책을 나타냅니다:
4637* **캐시 없음**: Claude Code는 서버 관리 설정 없이 세션을 실행하며, 줄은 `no remote policy applied`를 읽습니다.4994
4995* **이전 성공적인 가져오기에서 캐시된 설정**: Claude Code는 [보류된 환경 변수](/docs/ko/server-managed-settings#fetch-and-caching-behavior)를 제외한 해당 캐시된 정책에서 세션을 실행하며, 줄은 `using cached policy`로 읽습니다.
4996* **캐시 없음**: Claude Code는 서버 관리 설정 없이 세션을 실행하며, 줄은 `no remote policy applied`로 읽습니다.
4638 4997
4639**할 일:**4998**할 일:**
4640 4999
4641* 메시지가 명시하는 원인에 대해 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하세요. 인증 원인의 경우 `/status`로 로그인을 확인하세요.5000* 메시지가 이름으로 지정한 원인에 대해 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하세요. 인증 원인의 경우 `/status`로 로그인을 확인하세요.
5001* `no setting in the server response could be applied as written`의 경우 관리자에게 서버의 설정을 수정하도록 요청하세요.
4642* 전체 진단을 위해 `/status` 또는 `claude doctor`를 실행하세요.5002* 전체 진단을 위해 `/status` 또는 `claude doctor`를 실행하세요.
4643 5003
4644v2.1.248 이전에는 Claude Code가 실패한 설정 가져오기를 디버그 로그에만 보고했습니다.5004v2.1.248 이전에는 Claude Code가 실패한 설정 가져오기를 디버그 로그에서만 보고했습니다.
4645 5005
4646<h3 id="managed-settings-were-not-approved">5006<h3 id="managed-settings-were-not-approved">
4647 관리 설정이 승인되지 않음5007 관리 설정이 승인되지 않음
4648</h3>5008</h3>
4649 5009
4650조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 승인이 필요한 설정이 포함되어 있고 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부했으므로 Claude Code는 이를 적용하지 않고 종료됩니다:5010조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 승인이 필요한 설정이 포함되어 있고 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부했으므로 Claude Code는 이를 적용하지 않고 종료합니다:
4651 5011
4652```text theme={null}5012```text theme={null}
4653관리 설정이 승인되지 않았습니다. 이를 적용하지 않고 종료합니다.5013관리 설정이 승인되지 않았습니다. 이를 적용하지 않고 종료합니다.
4658* Claude Code를 다시 시작하고 대화를 승인하여 조직의 설정에서 계속하세요. 거부된 대화는 기억되지 않으므로 다음 시작 시 다시 나타납니다.5018* Claude Code를 다시 시작하고 대화를 승인하여 조직의 설정에서 계속하세요. 거부된 대화는 기억되지 않으므로 다음 시작 시 다시 나타납니다.
4659* 대화가 나열하는 설정에 대해 확실하지 않으면 승인하기 전에 조직의 관리 설정을 유지하는 사람에게 문의하세요.5019* 대화가 나열하는 설정에 대해 확실하지 않으면 승인하기 전에 조직의 관리 설정을 유지하는 사람에게 문의하세요.
4660 5020
5021<h3 id="managed-settings-block-the-default-model">
5022 관리 설정이 기본 모델을 차단함
5023</h3>
5024
5025조직의 [관리 설정](/docs/ko/managed-settings)이 기본 옵션이 해석되는 모델과 이를 단계적으로 낮출 수 있는 모든 모델을 차단합니다. 기본 옵션에서 시작할 세션은 차단된 모델을 실행하는 대신 시작 시 종료됩니다. 어떤 메시지를 보는지는 이를 차단하는 설정에 따라 다릅니다. [`deniedModels`](/docs/ko/model-config#block-specific-models-or-versions) 목록이 이를 차단하면 메시지는 다음과 같이 읽습니다:
5026
5027```text theme={null}
5028Claude Code를 시작할 수 없습니다: 조직의 관리 설정이 "deniedModels"에서 기본 모델(claude-opus-5-5)을 차단하고 있으며, 허용하는 모델 중 기본값으로 사용할 수 있는 모델이 없습니다. 관리자에게 "deniedModels" 또는 "availableModels"을 업데이트하도록 요청하세요.
5029```
5030
5031`availableModels` 목록이 [`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch)를 `"exact"`로 설정하여 이를 생략하면 메시지는 다음과 같이 읽습니다:
5032
5033```text theme={null}
5034Claude Code를 시작할 수 없습니다: 조직이 "availableModels"에 나열된 모델만 허용하며, 기본 모델로 사용할 수 있는 모델이 없습니다(claude-opus-5-5가 나열되지 않음). 관리자에게 "availableModels"을 업데이트하도록 요청하세요.
5035```
5036
5037**할 일:**
5038
5039* 설정을 관리하는 경우 사용자가 실행할 수 있는 모델을 `availableModels`에 추가하거나 모든 폴백을 차단하는 `deniedModels` 항목을 좁히세요. [특정 모델 또는 버전 차단](/docs/ko/model-config#block-specific-models-or-versions)은 기본 옵션이 어떻게 단계적으로 낮춰지는지 설명합니다.
5040* 설정을 관리하지 않으면 메시지를 관리자에게 보내세요. 자신의 설정 파일은 관리 `availableModels` 또는 `deniedModels` 목록을 확대할 수 없습니다.
5041
4661<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5042<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">
4662 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨5043 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨
4663</h3>5044</h3>
4664 5045
4665`/mcp`의 서버에서 **다시 연결**을 선택했거나 비활성화된 서버를 다시 켰는데, [MCP 서버를 제한](/docs/ko/managed-mcp)하는 설정이 해당 서버를 차단합니다. Claude Code는 이를 연결하기를 거부하고 다음을 표시합니다:5046`/mcp`의 서버에서 **다시 연결**을 선택했거나 비활성화된 서버를 다시 켰으며, [MCP 서버를 제한](/docs/ko/managed-mcp)하는 설정이 해당 서버를 차단합니다. Claude Code는 이를 연결하기를 거부하고 표시합니다:
4666 5047
4667```text theme={null}5048```text theme={null}
4668MCP 서버 <name>이(가) 엔터프라이즈 관리 정책에 의해 차단되었습니다5049MCP 서버 <name>이(가) 엔터프라이즈 관리 정책에 의해 차단되었습니다
4669```5050```
4670 5051
4671다음 설정 중 하나가 메시지를 생성할 수 있습니다:5052이러한 설정 중 하나가 메시지를 생성할 수 있습니다:
4672 5053
4673* 자신의 `~/.claude/settings.json` 또는 프로젝트의 `.claude/settings.json`에 있는 것을 포함하여 서버와 일치하는 [`deniedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 항목5054* 자신의 `~/.claude/settings.json` 또는 프로젝트의 `.claude/settings.json`에 있는 것을 포함하여 서버와 일치하는 [`deniedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 항목
4674* 서버가 일치하지 않는 [`allowedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 목록5055* 서버가 일치하지 않는 [`allowedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 목록
4675* `mcp` 잠금이 있는 [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization)으로, `~/.claude.json` 및 `.mcp.json`에서 구성된 서버를 차단합니다.5056* `mcp`가 잠긴 [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization)으로, `~/.claude.json` 및 `.mcp.json`에서 구성된 서버를 차단합니다.
4676* 서버가 claude.ai 커넥터일 때 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)5057* 서버가 claude.ai 커넥터일 때 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)
4677 5058
4678**할 일:**5059**할 일:**
4680* 자신의 사용자 및 프로젝트 설정 파일에서 이러한 설정 중 하나를 확인하고 변경하거나 제거하세요.5061* 자신의 사용자 및 프로젝트 설정 파일에서 이러한 설정 중 하나를 확인하고 변경하거나 제거하세요.
4681* 자신의 설정이 차단을 설명하지 않으면 관리자에게 어떤 관리 설정이 서버를 차단하는지 문의하세요.5062* 자신의 설정이 차단을 설명하지 않으면 관리자에게 어떤 관리 설정이 서버를 차단하는지 문의하세요.
4682 5063
4683v2.1.257 이전에는 `/mcp`의 **다시 연결** 및 다시 활성화가 중간 세션 정책 업데이트가 차단한 서버를 연결할 수 있었습니다.5064v2.1.257 이전에는 `/mcp`의 **다시 연결** 및 다시 활성화가 세션 중간 정책 업데이트가 차단한 서버를 연결할 수 있었습니다.
4684 5065
4685<h3 id="managed-settings-document-could-not-be-parsed">5066<h3 id="managed-settings-document-could-not-be-parsed">
4686 관리 설정 문서를 구문 분석할 수 없음5067 관리 설정 문서를 구문 분석할 수 없음
4687</h3>5068</h3>
4688 5069
4689조직이 [관리 설정](/docs/ko/managed-settings)을 배포하고, 배포된 문서 중 하나가 있지만 JSON 객체로 구문 분석할 수 없어서 Claude Code는 정책을 실행하지 않고 시작 시 코드 1로 종료됩니다. 줄은 메시지 앞에 실패한 소스를 명시합니다:5070조직이 [관리 설정](/docs/ko/managed-settings)을 배포하고 배포된 문서 중 하나가 있지만 JSON 객체로 구문 분석할 수 없어서 Claude Code는 문서가 수행하는 정책 없이 실행하는 대신 시작 시 코드 1로 종료됩니다. 줄은 메시지 앞에 실패한 소스를 이름으로 지정합니다:
4690 5071
4691```text theme={null}5072```text theme={null}
4692/Library/Application Support/ClaudeCode/managed-settings.json: 관리 설정 문서를 JSON 객체로 구문 분석할 수 없습니다. 해당 설정이 적용되지 않습니다. 수정하거나 제거하세요.5073/Library/Application Support/ClaudeCode/managed-settings.json: 관리 설정 문서를 JSON 객체로 구문 분석할 수 없습니다. 해당 설정이 적용되지 않습니다. 수정하거나 제거하세요.
4698* macOS 관리 기본 설정 프로필, `per-user managed preferences` 또는 `device-level managed preferences`5079* macOS 관리 기본 설정 프로필, `per-user managed preferences` 또는 `device-level managed preferences`
4699* Windows 레지스트리 값, `Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`5080* Windows 레지스트리 값, `Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`
4700 5081
4701[Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 각 소스를 구문 분석할 수 없게 만드는 것을 나열합니다.5082[Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 각 소스를 구문 분석할 수 없게 만드는 것을 나열합니다.
4702 5083
4703Claude Code는 다른 관리 소스가 유효한 정책을 제공하더라도 시작을 거부합니다. 대화형 세션, `claude -p`, Agent SDK 세션, [백그라운드 세션](/docs/ko/agent-view), 및 `claude doctor`를 포함한 대부분의 하위 명령에서 이 오류를 봅니다. 거부는 의도적으로 폐쇄됩니다: Claude Code가 구문 분석할 수 없는 문서의 설정은 적용될 수 없으며, 계속 진행하면 조직의 제어 없이 세션이 실행됩니다.5084Claude Code는 다른 관리 소스가 유효한 정책을 제공하더라도 시작을 거부합니다. 대화형 세션, `claude -p`, Agent SDK 세션, [백그라운드 세션](/docs/ko/agent-view), 및 대부분의 하위 명령(`claude doctor` 포함)에서 이 오류를 봅니다. 거부는 의도적으로 폐쇄됩니다: Claude Code가 구문 분석할 수 없는 문서의 설정은 적용될 수 없으며, 어쨌든 시작하면 조직의 제어 없이 세션이 실행됩니다.
4704 5085
4705구문 분석 가능한 문서의 스키마 문제는 이 오류를 생성하지 않습니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 Claude Code가 하나를 사용하는 것을 다룹니다.5086구문 분석 가능한 문서의 스키마 문제는 이 오류를 생성하지 않습니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 Claude Code가 하나를 사용하는 것을 다룹니다.
4706 5087
4707`managed-settings.d/` 디렉토리가 있지만 나열할 수 없으면 Claude Code는 `Managed settings drop-in directory could not be read:` 다음에 기본 오류를 보고합니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 읽기 실패가 시작 시 종료되는 경우를 다룹니다.5088`managed-settings.d/` 디렉토리가 있지만 나열할 수 없으면 Claude Code는 `Managed settings drop-in directory could not be read:` 다음에 기본 오류 대신 보고합니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 읽기 실패가 시작 시 종료되는 경우를 다룹니다.
4708 5089
4709**할 일:**5090**할 일:**
4710 5091
4711* 머신을 관리하면 명시된 문서를 JSON 객체로 구문 분석하도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 계산되며 실행을 차단하지 않습니다.5092* 머신을 관리하면 명명된 문서가 JSON 객체로 구문 분석되도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 계산되며 실행을 차단하지 않습니다.
4712* 그렇지 않으면 관리자에게 배포된 문서를 수정하도록 요청하세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.5093* 관리하지 않으면 관리자에게 배포된 문서를 수정하도록 요청하세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.
4713 5094
4714<h3 id="otelheadershelper-failed">5095<h3 id="otelheadershelper-failed">
4715 otelHeadersHelper 실패5096 otelHeadersHelper 실패
4716</h3>5097</h3>
4717 5098
4718Claude Code는 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper) 스크립트가 실패하거나 [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 충족하지 않는 출력을 출력할 때 대화형 세션당 한 번 터미널 인터페이스에 알림으로 이 경고를 표시합니다.5099Claude Code는 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper) 스크립트가 실패하거나 [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 충족하지 않는 출력을 출력할 때 대화형 세션당 한 번 터미널 인터페이스에서 알림으로 이 경고를 표시합니다.
4719 5100
4720스크립트가 계속 실패하는 동안 내보내기가 실패하고 원격 분석 백엔드는 세션에서 아무것도 받지 못합니다.5101스크립트가 계속 실패하는 동안 내보내기가 실패하고 원격 분석 백엔드는 세션에서 아무것도 받지 않습니다.
4721 5102
4722`See /status:` 뒤의 텍스트는 스크립트의 종료 코드 다음에 오류 출력 같은 실패한 내용을 명시합니다:5103`See /status:` 뒤의 텍스트는 스크립트의 종료 코드 다음에 오류 출력 같은 실패한 내용을 나타냅니다:
4723 5104
4724```text theme={null}5105```text theme={null}
4725otelHeadersHelper 실패. 원격 분석이 내보내지지 않습니다. /status 참조: exited 1: token service unreachable5106otelHeadersHelper 실패. 원격 분석을 내보내지 않습니다. /status 참조: exited 1: token service unreachable
4726```5107```
4727 5108
4728**할 일:**5109**할 일:**
4729 5110
4730* `/status`를 실행하여 실패 세부 정보를 읽으세요.5111* `/status`를 실행하여 실패 세부 정보를 읽으세요.
4731* 스크립트를 수정하여 30초 이내에 종료 0으로 종료하고 stdout에 문자열 헤더 값의 JSON 객체를 출력하도록 하세요. [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 참조하세요.5112* 스크립트가 30초 이내에 0으로 종료되고 stdout에 문자열 헤더 값의 JSON 객체를 출력하도록 수정하세요. [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 참조하세요.
4732* 조직이 [관리 설정](/docs/ko/managed-settings)을 통해 스크립트를 배포하면 이를 유지하는 사람에게 수정하도록 요청하세요.5113* 조직이 [관리 설정](/docs/ko/managed-settings)을 통해 스크립트를 배포하면 이를 유지하는 사람에게 수정하도록 요청하세요.
4733 5114
4734[비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 같은 실패가 stderr에 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>` 대신 나타납니다.5115[비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 동일한 실패가 stderr에 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>` 대신 나타납니다.
4735 5116
4736<h3 id="headershelper-not-run">5117<h3 id="headershelper-not-run">
4737 headersHelper가 실행되지 않음5118 headersHelper 실행되지 않음
4738</h3>5119</h3>
4739 5120
4740Claude Code는 정적 `headers`만으로 MCP 서버를 연결했고 서버의 [`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)를 건너뛰었습니다. 헬퍼는 셸 명령이고 폴더에 저장된 신뢰가 없기 때문입니다. 폴더는 `~/.claude.json`에서 항목을 손으로 설정하거나, 홈 디렉토리 외부에서 대화형 세션에서 신뢰 대화를 수락할 때 저장된 신뢰를 얻습니다. [headersHelper가 실행되기 전에 폴더 신뢰](/docs/ko/mcp#trust-a-folder-before-its-headershelper-runs)에서 이 검사가 적용되는 서버를 참조하세요.5121Claude Code는 MCP 서버를 정적 `headers`만으로 연결했으며 서버의 [`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)를 건너뛰었습니다. 헬퍼는 셸 명령이고 폴더에 저장된 신뢰가 없기 때문입니다. 폴더는 `~/.claude.json`에서 항목을 손으로 설정하거나 홈 디렉토리 외부에서 대화형 세션에서 신뢰 대화를 수락할 때 저장된 신뢰를 얻습니다. [headersHelper가 실행되기 전에 폴더 신뢰](/docs/ko/mcp#trust-a-folder-before-its-headershelper-runs)를 참조하여 이 검사가 어떤 서버에 적용되는지 확인하세요.
4741 5122
4742Claude Code는 [비대화형 모드](/docs/ko/headless)에서만 이 줄을 기록하며, 서버당 한 번입니다. 대화형 세션에서는 같은 거부를 디버그 로그에 기록합니다.5123Claude Code는 [비대화형 모드](/docs/ko/headless)에서만 이 줄을 서버당 한 번 기록합니다. 대화형 세션에서는 동일한 거부를 디버그 로그에 기록합니다.
4743 5124
4744```text theme={null}5125```text theme={null}
4745MCP 서버 'internal-api': headersHelper가 실행되지 않음 — 이 작업 공간에 지속된 신뢰가 없습니다. 여기서 대화형으로 신뢰 대화를 한 번 수락하거나 /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted를 설정하세요.5126MCP 서버 'internal-api': headersHelper 실행되지 않음 — 이 작업 영역에 저장된 신뢰가 없습니다. 여기서 한 번 대화형으로 신뢰 대화를 수락하거나 /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted를 설정하세요.
4746```5127```
4747 5128
4748메시지가 출력하는 `projects` 키는 [프로젝트 allow 규칙 및 작업 공간 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)가 Claude Code가 신뢰를 키하는 폴더입니다. 부모 폴더에 대한 신뢰 대화를 수락하는 것은 검사를 만족하지 않으며, `-p` 또는 SDK 세션도 만족하지 않습니다.5129메시지가 출력하는 `projects` 키는 [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)가 Claude Code가 신뢰를 키하는 폴더입니다. 부모 폴더에 대한 신뢰 대화를 수락하는 것은 검사를 만족하지 않으며, `-p` 또는 SDK 세션도 만족하지 않습니다.
4749 5130
4750**할 일:**5131**할 일:**
4751 5132
4752* 메시지가 명시하는 폴더에서 `claude`를 실행하고 신뢰 대화를 수락한 다음 `-p` 또는 SDK 명령을 다시 실행하세요.5133* 메시지가 이름으로 지정한 폴더에서 `claude`를 실행하고 신뢰 대화를 수락한 후 `-p` 또는 SDK 명령을 다시 실행하세요.
4753* 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 직접 설정하세요.5134* `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 직접 설정하고 메시지가 출력하는 정확한 `projects` 키를 사용하세요.
4754* 홈 디렉토리에서 세션을 시작했으면 신뢰한 프로젝트 디렉토리에서 작업하세요. 홈 디렉토리에서 신뢰 대화를 수락하면 Claude Code는 현재 세션에만 해당 신뢰를 유지합니다.5135* 홈 디렉토리에서 세션을 시작했으면 신뢰한 프로젝트 디렉토리에서 작업하세요. 홈 디렉토리에서 신뢰 대화를 수락하면 Claude Code는 현재 세션에만 해당 신뢰를 유지합니다.
4755 5136
4756<h3 id="malformed-tool-content-rule">5137<h3 id="malformed-tool-content-rule">
4757 잘못된 Tool(content) 규칙5138 잘못된 형식의 Tool(content) 규칙
4758</h3>5139</h3>
4759 5140
4760설정 파일의 [권한 규칙](/docs/ko/permissions#permission-rule-syntax)이 `Tool` 또는 `Tool(content)` 형태를 갖지 않습니다. 예를 들어 닫는 괄호 뒤에 텍스트가 있거나 괄호 중 하나가 누락되었습니다. Claude Code는 규칙을 건너뛰고 대화형 세션이 시작될 때 유효하지 않은 설정 대화에 나열하며, [`claude doctor`](/docs/ko/debug-your-config#check-resolved-settings) 출력에도 나열합니다:5141[권한 규칙](/docs/ko/permissions#permission-rule-syntax)이 설정 파일 중 하나에 `Tool` 또는 `Tool(content)` 형태가 아닙니다. 예를 들어 닫는 괄호 뒤에 텍스트가 있거나 괄호 중 하나가 누락되었습니다. Claude Code는 규칙을 건너뛰고 대화형 세션이 시작될 때 유효하지 않은 설정 대화에 나열하며, [`claude doctor`](/docs/ko/debug-your-config#check-resolved-settings) 출력에서:
4761 5142
4762```text theme={null}5143```text theme={null}
4763유효하지 않은 권한 규칙 "Bash(ls) x"가 건너뛰어졌습니다: 잘못된 Tool(content) 규칙. 규칙은 Tool 또는 Tool(content) 형태를 가지며 닫는 ")"에서 끝나야 합니다. 내용 내의 괄호는 리터럴입니다.5144유효하지 않은 권한 규칙 "Bash(ls) x"를 건너뛰었습니다: 잘못된 형식의 Tool(content) 규칙. 규칙은 Tool 또는 Tool(content) 형태이며 닫는 ")"에서 끝나야 합니다. 내용 내의 괄호는 리터럴입니다.
4764```5145```
4765 5146
4766**할 일:**5147**할 일:**
4767 5148
4768* 메시지와 함께 나열된 설정 파일에서 규칙을 다시 작성하여 닫는 괄호에서 끝나도록 하세요. 예를 들어 `Bash(ls) x` 대신 `Bash(ls *)`5149* 메시지와 함께 나열된 설정 파일에서 규칙을 다시 작성하여 닫는 괄호에서 끝나도록 하세요. 예를 들어 `Bash(ls) x` 대신 `Bash(ls *)`
4769* 내용 내의 괄호는 그대로 두세요. 이들은 리터럴이므로 `Edit(./Finance (2024)/*)`와 같은 규칙은 이스케이프 없이 유효합니다.5150* 내용 내의 괄호는 그대로 두세요. 이들은 리터럴이므로 `Edit(./Finance (2024)/**)` 같은 규칙은 이스케이프 없이 유효합니다.
4770 5151
4771v2.1.260 이전에는 Claude Code가 일치하지 않는 괄호가 있는 규칙을 `Mismatched parentheses`로 보고했습니다.5152v2.1.260 이전에는 Claude Code가 일치하지 않는 괄호가 있는 규칙을 `Mismatched parentheses`로 보고했습니다.
4772 5153
4774 파일 권한 검사와 일치하지 않음5155 파일 권한 검사와 일치하지 않음
4775</h3>5156</h3>
4776 5157
4777Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리 설정](/docs/ko/managed-settings), 또는 `--allowedTools`, `--disallowedTools`, 또는 `--settings` 플래그 값에서 경로가 있는 `Write`, `NotebookEdit`, `MultiEdit`, 또는 `Glob` [권한 규칙](/docs/ko/permissions#read-and-edit)을 찾았습니다. 파일 권한을 `Edit` 및 `Read` 규칙에 대해서만 검사하므로 다른 파일 도구 중 하나를 명시하는 경로 규칙을 절대 참조하지 않습니다. 규칙을 유지하고 다른 것은 변경하지 않습니다. 경고는 규칙, 괄호의 소스, 그리고 작성할 대체를 명시합니다:5158Claude Code는 [설정 파일](/docs/ko/settings#where-settings-live), [관리 설정](/docs/ko/managed-settings), 또는 `--allowedTools`, `--disallowedTools`, 또는 `--settings` 플래그 값에서 경로가 있는 `Write`, `NotebookEdit`, `MultiEdit`, 또는 `Glob` [권한 규칙](/docs/ko/permissions#read-and-edit)을 찾았습니다. 파일 권한을 `Edit` 및 `Read` 규칙에 대해서만 검사하므로 다른 파일 도구 중 하나를 이름으로 지정하는 경로 규칙을 절대 참조하지 않습니다. 규칙을 유지하고 다른 것은 변경하지 않습니다. 경고는 규칙, 괄호의 소스, 그리고 작성할 대체를 이름으로 지정합니다:
4778 5159
4779```text theme={null}5160```text theme={null}
4780권한 deny 규칙(.claude/settings.json): Write(docs/**)는 파일 권한 검사와 일치하지 않습니다 — Edit(path) 규칙만 사용됩니다. 대신 Edit(docs/**)를 사용하세요(Edit 규칙은 모든 파일 편집 도구를 포함합니다).5161권한 deny 규칙(.claude/settings.json): Write(docs/**)는 파일 권한 검사와 일치하지 않습니다 — Edit(path) 규칙만 있습니다. 대신 Edit(docs/**)를 사용하세요(Edit 규칙은 모든 파일 편집 도구를 포함합니다).
4781```5162```
4782 5163
4783**할 일:**5164**할 일:**
4784 5165
4785* `Write(path)`, `NotebookEdit(path)`, 및 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구를 포함합니다.5166* `Write(path)`, `NotebookEdit(path)`, 및 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구를 포함합니다.
4786* `--allowedTools`를 제외하고, Claude Code가 경고 없이 `Glob` 규칙을 수락하며, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.5167* `--allowedTools`를 제외하고, Claude Code가 경고 없이 `Glob` 규칙을 수락하며, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.
4787* 경고가 괄호에 명시하는 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는 `--allowed-tools` 및 `--disallowed-tools`의 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5168* 경고가 괄호에 이름으로 지정한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 및 `--disallowed-tools`의 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.
4788* `Write` 또는 `Glob` 같은 베어 도구 이름 규칙은 그대로 두세요. Claude Code는 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치시키고 이들에 대해 경고하지 않습니다.5169* `Write` 또는 `Glob` 같은 베어 도구 이름 규칙은 그대로 두세요. Claude Code는 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치하며 이에 대해 경고하지 않습니다.
4789* 소스가 `managed policy settings`를 읽으면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.5170* 소스가 `managed policy settings`로 읽히면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.
4790 5171
4791[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 stderr 대신 디버그 로그에 기록하므로 머신 읽기 출력이 깨끗합니다. `~/.claude/debug/<session-id>.txt`에서 캡처하려면 `--debug`로 실행하세요. v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5172[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록하므로 머신 읽기 출력이 깨끗합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요. v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.
4792 5173
4793<h3 id="has-a-wildcard-before-the-rest-of-the-command">5174<h3 id="has-a-wildcard-before-the-rest-of-the-command">
4794 명령의 나머지 부분 앞에 와일드카드가 있음5175 명령의 나머지 부분 앞에 와일드카드가 있음
4795</h3>5176</h3>
4796 5177
4797Claude Code는 `Bash(git * main)` 또는 `Bash(git -C * status *)`처럼 `*`가 명령을 결정하는 나중 단어 앞에 오는 `Bash` allow 규칙을 찾았습니다. 이는 [설정 파일](/docs/ko/settings#where-settings-live), [관리 설정](/docs/ko/managed-settings), 또는 `--allowedTools` 또는 `--settings` 플래그 값에 있습니다. `*`는 해당 위치에 삽입된 옵션을 포함한 모든 텍스트와 일치합니다: `Bash(git * main)`은 또한 `-c`가 명령이 명시하는 프로그램을 실행하게 하는 `git -c core.fsmonitor=<script> diff main`을 승인합니다. [와일드카드 패턴](/docs/ko/permissions#wildcard-patterns)은 일치 규칙을 보여줍니다.5178Claude Code는 `Bash(git * main)` 또는 `Bash(git -C * status *)` 같이 `*`가 명령을 결정하는 나중의 단어 앞에 오는 `Bash` allow 규칙을 찾았습니다. [설정 파일](/docs/ko/settings#where-settings-live), [관리 설정](/docs/ko/managed-settings), 또는 `--allowedTools` 또는 `--settings` 플래그 값에서. `*`는 해당 위치에 삽입된 옵션을 포함한 모든 텍스트와 일치합니다: `Bash(git * main)`은 또한 `git -c core.fsmonitor=<script> diff main`을 승인합니다. 여기서 `-c`는 git이 명령이 이름을 지정하는 프로그램을 실행하게 합니다. [와일드카드 패턴](/docs/ko/permissions#wildcard-patterns)은 일치 규칙을 보여줍니다.
4798 5179
4799경고는 의도한 것보다 와일드카드가 더 넓은 규칙을 좁힐 수 있도록 존재합니다. Claude Code는 규칙을 유지하고 일치 방식을 변경하지 않습니다. 경고는 규칙과 괄호의 소스를 명시합니다:5180경고는 의도한 것보다 와일드카드가 더 넓은 규칙을 좁힐 수 있도록 존재합니다. Claude Code는 규칙을 유지하고 일치 방식에 대해 아무것도 변경하지 않습니다. 경고는 규칙과 괄호의 소스를 이름으로 지정합니다:
4800 5181
4801```text theme={null}5182```text theme={null}
4802권한 allow 규칙(.claude/settings.json): Bash(git -C * status *)는 명령의 나머지 부분 앞에 와일드카드가 있으므로 해당 위치에 삽입된 모든 옵션과도 일치하고 프롬프트 없이 승인합니다. git의 경우 -c 및 --exec-path 같은 옵션은 임의의 명령을 실행할 수 있습니다. 해당 *를 의도한 정확한 값으로 바꾸거나 *를 하위 명령 뒤에만 사용하세요(예: Bash(git status *)).5183권한 allow 규칙(.claude/settings.json): Bash(git -C * status *)는 명령의 나머지 부분 앞에 와일드카드가 있으므로 해당 위치에 삽입된 모든 옵션과도 일치하며 프롬프트 없이 이를 승인합니다. git의 경우 -c 및 --exec-path 같은 옵션은 임의의 명령을 실행할 수 있습니다. 해당 *를 의도한 정확한 값으로 바꾸거나 부분 명령 뒤에만 *를 사용하세요(예: Bash(git status *)).
4803```5184```
4804 5185
4805**할 일:**5186**할 일:**
4806 5187
4807* 하위 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.5188* 부분 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.
4808* 모든 `*`를 하위 명령 뒤로 이동하세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 하위 명령당 하나의 규칙을 작성하세요.5189* 모든 `*`를 부분 명령 뒤로 이동하세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 부분 명령당 하나의 규칙을 작성하세요.
4809* 경고가 괄호에 명시하는 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는 `--allowed-tools` 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5190* 경고가 괄호에 이름으로 지정한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.
4810* 소스가 `managed policy settings`를 읽으면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.5191* 소스가 `managed policy settings`로 읽히면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.
4811 5192
4812Claude Code는 같은 형태의 deny 및 ask 규칙에 대해 경고하지 않습니다: 승인하는 대신 일치하는 추가 명령을 거부하거나 프롬프트합니다. 또한 `Bash(git commit *)`처럼 하위 명령이 첫 `*` 앞에 오는 규칙이나 `Bash(git *)`처럼 `*` 뒤에 옵션 이외의 단어가 없는 규칙, 또는 `Bash(git:*)`처럼 `:*` 접두사 규칙에 대해서도 경고하지 않습니다.5193Claude Code는 동일한 형태의 deny 및 ask 규칙에 대해 경고하지 않습니다: 이를 승인하는 대신 일치하는 추가 명령을 거부하거나 프롬프트합니다. 또한 부분 명령이 첫 번째 `*` 앞에 오는 규칙(예: `Bash(git commit *)`)이나 `*` 뒤에 옵션 이외의 단어가 없는 규칙(예: `Bash(git *)`)이나 `:*` 접두사 규칙(예: `Bash(git:*)`)에 대해서도 경고하지 않습니다.
4813 5194
4814[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 stderr 대신 디버그 로그에 기록하므로 머신 읽기 출력이 깨끗합니다. `~/.claude/debug/<session-id>.txt`에서 캡처하려면 `--debug`로 실행하세요. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5195[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록하므로 머신 읽기 출력이 깨끗합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.
4815 5196
4816<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5197<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">
4817 crossSessionInbound는 accept, hold, refuse 중 하나여야 함5198 crossSessionInbound는 accept, hold, refuse 중 하나여야 함
4818</h3>5199</h3>
4819 5200
4820설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 Claude Code가 인식하지 못하는 값(예: 오타 `"reject"`)으로 설정합니다. 경고의 두 번째 문장은 어느 파일이 값을 보유하는지에 따라 다릅니다. 사용자, 프로젝트, 로컬, 또는 `--settings` 파일에서는 다음을 읽습니다:5201설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 Claude Code가 인식하지 못하는 값(예: 오타 `"reject"`)으로 설정합니다. 경고의 두 번째 문장은 어떤 파일이 값을 보유하는지에 따라 다릅니다. 사용자, 프로젝트, 로컬 또는 `--settings` 파일에서 읽습니다:
4821 5202
4822```text theme={null}5203```text theme={null}
4823"crossSessionInbound"는 "accept", "hold", "refuse" 중 하나여야 합니다. "reject"를 받았습니다. 이 값은 무시되었습니다. 존재하는 동안 교차 세션 메시지는 전달되는 대신 승인을 위해 보류됩니다. 위의 값 중 하나로 설정하세요.5204"crossSessionInbound"는 "accept", "hold", "refuse" 중 하나여야 합니다. "reject"를 받았습니다. 이 값은 무시되었습니다. 존재하는 동안 교차 세션 메시지는 전달되는 대신 승인을 위해 보류됩니다. 위의 값 중 하나로 설정하세요.
4824```5205```
4825 5206
4826[관리 설정](/docs/ko/managed-settings)에서 Claude Code는 인식되지 않는 값을 가장 제한적인 값인 `refuse`로 취급하고 경고는 관리자가 수정할 때까지 교차 세션 메시지가 거부된다고 말합니다. hold가 다른 설정 파일의 값과 결합되는 방식은 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 참조하세요.5207[관리 설정](/docs/ko/managed-settings)에서 Claude Code는 인식되지 않는 값을 가장 제한적인 값인 `refuse`로 취급하며 경고는 관리자가 수정할 때까지 교차 세션 메시지가 거부된다고 말합니다. hold가 다른 설정 파일의 값과 결합되는 방식은 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 참조하세요.
4827 5208
4828**할 일:**5209**할 일:**
4829 5210
4830* 키를 `"accept"`, `"hold"`, 또는 `"refuse"`로 설정하거나 제거하세요.5211* 키를 `"accept"`, `"hold"`, 또는 `"refuse"`로 설정하거나 제거하세요.
4831* 경고가 관리 설정을 명시하면 관리자에게 값을 수정하도록 요청하세요.5212* 경고가 관리 설정을 이름으로 지정하면 관리자에게 값을 수정하도록 요청하세요.
4832 5213
4833v2.1.248 이전에는 Claude Code가 인식되지 않는 값을 경고 없이 무시했습니다.5214v2.1.248 이전에는 Claude Code가 인식되지 않는 값을 경고 없이 무시했습니다.
4834 5215
4836 200K 제한이 적용되지 않음5217 200K 제한이 적용되지 않음
4837</h3>5218</h3>
4838 5219
4839[`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정했으며, 이는 일반적으로 [자동 압축](/docs/ko/model-config#default-auto-compact-thresholds)이 1M 컨텍스트 모델의 세션을 200K 윈도우에 유지하게 하지만, 이 세션을 200K 이하로 제한하는 압축 임계값이 없어서 대화가 이를 초과할 수 있습니다.5220[`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정했습니다. 이는 일반적으로 [자동 압축](/docs/ko/model-config#default-auto-compact-thresholds)이 1M 컨텍스트 모델의 세션을 200K 윈도우에 유지하게 하지만, 이 세션을 200K 이하로 제한하는 압축 임계값이 없으므로 대화가 이를 초과하여 증가할 수 있습니다.
4840 5221
4841```text theme={null}5222```text theme={null}
4842CLAUDE_CODE_DISABLE_1M_CONTEXT가 설정되었지만 <model>에 대해 200K 제한이 적용되지 않으므로 이 세션은 이를 초과할 수 있습니다. 이를 적용하려면 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000(또는 autoCompactWindow 설정)을 설정하세요.5223CLAUDE_CODE_DISABLE_1M_CONTEXT가 설정되었지만 <model>에 대해 200K 제한이 적용되지 않으므로 이 세션은 이를 초과하여 증가할 수 있습니다. 이를 적용하려면 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000(또는 autoCompactWindow 설정)을 설정하세요.
4843```5224```
4844 5225
4845Claude Code는 네이티브 1M 윈도우를 가진 것으로 인식하는 모든 모델과 인식하지 못하는 모델 ID에 대해 가정하는 윈도우에서 압축하는 200K 제한을 자체적으로 적용합니다. 경고는 다른 구성이 해당 적용을 무효화할 때 나타납니다:5226Claude Code는 기본 1M 윈도우가 있는 것으로 인식하는 모든 모델과 인식하지 못하는 모델 ID에 대해 가정하는 윈도우에서 압축하는 200K 제한을 자체적으로 적용합니다. 경고는 다른 구성이 해당 적용을 무효화할 때 나타납니다:
4846 5227
4847* 모델 ID가 Claude Code가 인식하지 못하는 것입니다. 예를 들어 [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭이고, [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/ko/env-vars)을 설정했거나 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/ko/env-vars)로 가정 윈도우를 200K 이상으로 올렸습니다. 이 경우 메시지는 또한 `또는 <model>을(를) 인식하는 Claude Code 버전으로 업데이트`를 해결책으로 제공합니다.5228* 모델 ID가 Claude Code가 인식하지 못하는 것입니다(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭). [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/ko/env-vars)을 설정했거나 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/ko/env-vars)로 가정하는 윈도우를 200K 이상으로 올렸습니다. 이 경우 메시지는 또한 `or update to a Claude Code version that recognizes <model>`을 해결책으로 제공합니다.
4848* [`ANTHROPIC_BETAS`](/docs/ko/env-vars) 또는 [`--betas`](/docs/ko/cli-reference#cli-flags) 플래그를 통해 요청된 `context-1m` 베타는 여전히 해당 베타를 수락하는 모델에서 API에 1M 윈도우를 요청하는 동안 아무것도 200K에서 세션을 압축하지 않습니다.5229* `context-1m` 베타는 [`ANTHROPIC_BETAS`](/docs/ko/env-vars) 또는 [`--betas`](/docs/ko/cli-reference#cli-flags) 플래그를 통해 요청되며 여전히 해당 베타를 수락하는 모델에서 API에 1M 윈도우를 요청하는 동안 아무것도 200K에서 세션을 압축하지 않습니다.
4849 5230
4850**할 일:**5231**할 일:**
4851 5232
4852* [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하거나 [`autoCompactWindow`](/docs/ko/settings-reference#autocompactwindow) 설정을 `200000`으로 설정하여 자동 압축이 200K 경계에서 압축하도록 하세요.5233* [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하거나 [`autoCompactWindow`](/docs/ko/settings-reference#autocompactwindow) 설정을 `200000`으로 설정하여 자동 압축이 200K 경계에서 압축하도록 하세요.
4853* 메시지가 이 버전이 인식하지 못하는 모델 ID를 명시하면 `claude update`를 실행하세요. ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.5234* 메시지가 이 버전이 인식하지 못하는 모델 ID를 이름으로 지정하면 `claude update`를 실행하세요. ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.
4854* 세션이 모델의 전체 윈도우를 대신 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 경고는 200K 제한이 적용되지 않는다는 것만 보고합니다.5235* 세션이 모델의 전체 윈도우를 대신 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 경고는 200K 제한이 적용되지 않음을 보고합니다.
4855 5236
4856[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다.5237[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록합니다.
4857 5238
4858<h3 id="unrecognized-model-id-on-a-request">5239<h3 id="unrecognized-model-id-on-a-request">
4859 요청에서 인식되지 않은 모델 ID5240 요청에서 인식되지 않은 모델 ID
4860</h3>5241</h3>
4861 5242
4862Claude Code는 Claude Code 버전이 인식하지 못하는 모델 ID에 대한 요청을 보냈고, 해당 ID를 인식하는 모델로 매핑하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 찾지 못했습니다. Claude Code는 여전히 구성한 대로 ID를 사용하여 요청을 보내며, 종료하거나 모델을 전환하지 않습니다.5243Claude Code는 Claude Code 버전이 인식하지 못하는 모델 ID에 대한 요청을 보냈으며, 해당 ID를 인식하는 모델에 매핑하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 찾지 못했습니다. Claude Code는 여전히 구성한 대로 ID를 사용하여 요청을 보내며 종료하거나 모델을 전환하지 않습니다.
4863 5244
4864```text theme={null}5245```text theme={null}
4865[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}5246[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}
4866```5247```
4867 5248
4868stderr를 읽는 스크립트 또는 하네스에서 `[claude-code:unrecognized_model]` 접두사와 일치하세요. 접두사와 한 공백 뒤에 Claude Code는 한 줄 JSON 객체를 기록합니다. Claude Code는 나중 버전에서 필드를 추가할 수 있으므로 예상하지 못한 필드는 무시하세요. 최소한 다음 두 가지를 기록합니다:5249stderr를 읽는 스크립트 또는 하네스에서 `[claude-code:unrecognized_model]` 접두사와 일치합니다. 접두사와 한 칸 뒤에 Claude Code는 한 줄 JSON 객체를 기록합니다. Claude Code는 나중 버전에서 필드를 추가할 수 있으므로 예상하지 못한 필드는 무시하세요. 최소한 이 두 가지를 기록합니다:
4869 5250
4870* `model`: 구성한 대로 모델 문자열5251* `model`: 구성한 대로 모델 문자열
4871* `query_source`: 모델을 사용한 요청 경로. Claude Code는 `-p` 실행에 대해 `sdk`를 보고하고 서브에이전트에 대해 `agent:`로 시작하는 값을 보고합니다.5252* `query_source`: 모델을 사용한 요청 경로. Claude Code는 `-p` 실행에 대해 `sdk`를 보고하고 `agent:`로 시작하는 값을 서브에이전트에 대해 보고합니다.
4872 5253
4873Claude Code는 실행 방식에 따라 두 곳 중 하나에 줄을 기록합니다:5254Claude Code는 실행 방식에 따라 두 곳 중 하나에 줄을 기록합니다:
4874 5255
4875* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 Claude Code는 모든 `--output-format` 아래 stderr에 기록하므로 줄을 필터링하지 않고 stdout을 구문 분석할 수 있습니다.5256* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 Claude Code는 모든 `--output-format` 아래 stderr에 기록하므로 줄을 필터링하지 않고 stdout을 구문 분석할 수 있습니다.
4876* 대화형 세션 또는 [백그라운드 세션](/docs/ko/agent-view)에서 Claude Code는 디버그 로그에 기록합니다. `~/.claude/debug/<session-id>.txt`에서 캡처하려면 `--debug`로 실행하세요.5257* 대화형 세션 또는 [백그라운드 세션](/docs/ko/agent-view)에서 Claude Code는 디버그 로그에 기록합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요.
4877 5258
4878Claude Code는 프로세스당 모델 문자열당 한 번 줄을 기록합니다. [서브에이전트](/docs/ko/sub-agents#choose-a-model) 또는 [백그라운드 기능](/docs/ko/costs#background-token-usage)이 사용하는 것처럼 각 추가 인식되지 않은 ID에 대해 별도의 줄을 기록합니다.5259Claude Code는 프로세스당 모델 문자열당 한 번 줄을 기록합니다. [서브에이전트](/docs/ko/sub-agents#choose-a-model) 또는 [백그라운드 기능](/docs/ko/costs#background-token-usage)이 사용하는 것 같은 추가 인식되지 않은 ID에 대해 별도의 줄을 기록합니다.
4879 5260
4880Claude Code는 인식하는 모델로 해석하는 공급자 ID에 대해 줄을 기록하지 않습니다. 예를 들어 Amazon Bedrock `us.anthropic.claude-...` ID, Google Cloud의 `@` 버전 접미사가 있는 Agent Platform ID, Claude 모델 ID를 포함하는 Microsoft Foundry 배포 이름입니다. Claude Code는 ARN 자체가 아닌 Amazon Bedrock [애플리케이션 추론 프로필 ARN](/docs/ko/amazon-bedrock#map-each-model-version-to-an-inference-profile) 뒤의 모델을 확인합니다. 잘못된 것처럼 해석할 수 없는 ARN에 대해 줄을 기록하지 않습니다.5261Claude Code는 인식하는 모델로 해석하는 공급자 ID에 대해 줄을 기록하지 않습니다. Amazon Bedrock `us.anthropic.claude-...` ID, Google Cloud의 `@` 버전 접미사가 있는 Agent Platform ID, Claude 모델 ID를 포함하는 Microsoft Foundry 배포 이름. Claude Code는 ARN 자체가 아닌 Amazon Bedrock [애플리케이션 추론 프로필 ARN](/docs/ko/amazon-bedrock#map-each-model-version-to-an-inference-profile) 뒤의 모델을 확인합니다. 잘못된 것 같은 해석할 수 없는 ARN에 대해 줄을 기록하지 않습니다.
4881 5262
4882**할 일:**5263**할 일:**
4883 5264
4884* 의도적으로 ID를 설정한 경우(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭), ID를 값으로 하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 [설정 파일](/docs/ko/settings#where-settings-live)에 추가하세요. 키로 `opus` 같은 패밀리 별칭이 아닌 Anthropic 모델 ID를 사용하세요. 예제 줄의 `my-proxy-model`에 대해 이 항목을 추가하세요:5265* ID를 의도적으로 설정한 경우(예: [LLM 게이트웨이](/docs/ko/llm-gateway) 별칭) [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 [설정 파일](/docs/ko/settings#where-settings-live)에 추가하고 ID를 값으로 사용하세요. `opus` 같은 패밀리 별칭이 아닌 Anthropic 모델 ID를 키로 사용하세요. 예제 줄의 `my-proxy-model`에 대해 이 항목을 추가하세요:
4885 5266
4886 ```json theme={null}5267 ```json theme={null}
4887 {5268 {
4893 5274
4894 Claude Code는 `my-proxy-model`을 `claude-opus-4-6`으로 취급하고 줄 기록을 중지합니다.5275 Claude Code는 `my-proxy-model`을 `claude-opus-4-6`으로 취급하고 줄 기록을 중지합니다.
4895 5276
4896* ID가 Claude Code 버전보다 새로운 모델을 명시하면 `claude update`를 실행하세요.5277* ID가 Claude Code 버전보다 최신 모델을 이름으로 지정하면 `claude update`를 실행하세요.
4897 5278
4898* ID가 오타이면 [모델을 설정할 수 있는 위치](/docs/ko/model-config#setting-your-model) 또는 [별칭 변수](/docs/ko/model-config#environment-variables) 중 이를 보유하는 곳에서 수정하세요. `query_source`가 `agent:`로 시작하면 [서브에이전트의 모델](/docs/ko/sub-agents#choose-a-model)을 설정하는 곳에서 대신 수정하세요.5279* ID가 오타이면 [모델을 설정할 수 있는 위치](/docs/ko/model-config#setting-your-model) 또는 [별칭 변수](/docs/ko/model-config#environment-variables) 중 이를 보유한 곳에서 수정하세요. `query_source`가 `agent:`로 시작하면 [서브에이전트의 모델을 설정](/docs/ko/sub-agents#choose-a-model)한 곳에서 대신 수정하세요.
4899 5280
4900v2.1.233 이전에는 Claude Code가 인식하지 못하는 모델 ID에 대한 요청을 보낼 때 줄을 기록하지 않았습니다.5281v2.1.233 이전에는 Claude Code가 인식하지 못하는 모델 ID에 대한 요청을 보낼 때 줄을 기록하지 않았습니다.
4901 5282
4903 종료된 세션이 남긴 오래된 샌드박스 마스크 파일5284 종료된 세션이 남긴 오래된 샌드박스 마스크 파일
4904</h3>5285</h3>
4905 5286
4906`claude doctor`는 진단에서 이 경고를 출력하고 `/status`는 같은 줄을 나열합니다. [샌드박싱](/docs/ko/sandboxing)이 파일 시스템 격리를 켜서 활성화되면 Linux 및 WSL2에 나타납니다.5287`claude doctor`는 진단에서 이 경고를 출력하며 `/status`는 동일한 줄을 나열합니다. [샌드박싱](/docs/ko/sandboxing)이 파일 시스템 격리를 켜서 활성화되면 Linux 및 WSL2에 나타납니다.
4907 5288
4908샌드박스된 명령이 실행되는 동안 샌드박스는 아직 존재하지 않는 파일에 대한 쓰기 거부를 0바이트 읽기 전용 자리 표시자를 만들어 유지하고 나중에 제거합니다. SIGKILL 같은 것으로 정리 실행 전에 종료된 세션은 자리 표시자를 남깁니다. 이후 세션은 모든 시작에서 읽기 전용으로 다시 바인드하므로 "Yes, and don't ask again" 저장 같은 설정 쓰기가 하나가 있는 곳에서 실패합니다.5289샌드박스된 명령이 실행되는 동안 샌드박스는 아직 존재하지 않는 파일에 대한 쓰기 거부를 0바이트 읽기 전용 자리 표시자를 만들어 유지하고 나중에 제거합니다. SIGKILL로 종료된 세션 같은 정리 전에 세션이 종료되면 자리 표시자가 남습니다. 이후 세션은 모든 시작에서 읽기 전용으로 다시 바인드하므로 "Yes, and don't ask again" 저장 같은 설정 쓰기가 하나가 있는 곳에서 실패합니다.
4909 5290
4910```text theme={null}5291```text theme={null}
4911- 종료된 세션이 남긴 오래된 샌드박스 마스크 파일: /home/you/project/.claude/settings.local.json5292- 종료된 세션이 남긴 오래된 샌드박스 마스크 파일: /home/you/project/.claude/settings.local.json
4912 수정: 해당 프로젝트에서 다른 Claude Code 세션이 실행되지 않는 동안 각각을 `rm <path>`로 제거하세요 — 설정 파일이 속한 곳의 0바이트 읽기 전용 파일은 "Yes, and don't ask again" 저장을 실패하게 하고 샌드박스는 모든 시작에서 읽기 전용으로 다시 바인드합니다.5293 수정: 다른 Claude Code 세션이 해당 프로젝트에서 실행되지 않는 동안 각각을 `rm <path>`로 제거하세요 — 설정 파일이 속한 곳의 0바이트 읽기 전용 파일은 "Yes, and don't ask again" 저장을 실패하게 하며 샌드박스는 모든 시작에서 읽기 전용으로 다시 바인드합니다.
4913```5294```
4914 5295
4915**할 일:**5296**할 일:**
4916 5297
4917* 해당 프로젝트에서 실행 중인 다른 Claude Code 세션을 종료한 다음 `rm`으로 각 나열된 파일을 삭제하세요. 경고는 최대 3개 파일을 명시하고 나머지를 계산하므로 경고가 더 이상 나타나지 않을 때까지 삭제 후 `claude doctor`를 다시 실행하세요. 다른 세션의 샌드박스가 여전히 사용 중인 자리 표시자는 해당 세션의 쓰기 보호의 라이브 부분입니다.5298* 해당 프로젝트에서 실행 중인 다른 Claude Code 세션을 종료한 후 `rm`으로 각 나열된 파일을 삭제하세요. 경고는 최대 3개 파일을 이름으로 지정하고 나머지를 계산하므로 경고가 더 이상 나타나지 않을 때까지 삭제 후 `claude doctor`를 다시 실행하세요. 다른 세션의 샌드박스가 여전히 사용 중인 자리 표시자는 해당 세션의 쓰기 보호의 라이브 부분입니다.
4918* "Yes, and don't ask again"으로 저장한 권한 선택이 고정되지 않았으면 자리 표시자를 삭제한 후 다시 저장하세요.5299* "Yes, and don't ask again"으로 저장한 권한 선택이 고착되지 않으면 자리 표시자를 삭제한 후 다시 저장하세요.
4919 5300
4920v2.1.257 이전에는 `claude doctor`가 이러한 파일을 플래그하지 않았습니다. 이전 버전은 세션이 종료될 때 같은 자리 표시자를 남깁니다.5301v2.1.257 이전에는 `claude doctor`가 이러한 파일을 플래그하지 않았습니다. 이전 버전은 세션이 종료될 때 동일한 자리 표시자를 남깁니다.
4921 5302
4922<h2 id="responses-seem-lower-quality-than-usual">5303<h2 id="responses-seem-lower-quality-than-usual">
4923 응답 품질이 평소보다 낮아 보입니다5304 응답 품질이 평소보다 낮아 보입니다
4927 5308
4928* 구성된 [`--fallback-model`](/docs/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 제어를 인수받으며, 트랜스크립트에 공지가 표시됩니다5309* 구성된 [`--fallback-model`](/docs/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 제어를 인수받으며, 트랜스크립트에 공지가 표시됩니다
4929* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다5310* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다
4930* [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 Fable 5.1, Fable 5, Opus 5.5, Opus 5에서 세션을 플래그된 카테고리의 폴백 모델로 이동하며, 해당 카테고리에 폴백 모델이 있을 때 트랜스크립트에 공지를 표시합니다5311* [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5, Opus 5에서 세션을 플래그된 카테고리의 폴백 모델로 이동하며, 해당 카테고리에 폴백 모델이 있을 때 트랜스크립트에 공지를 표시합니다
4931 5312
4932아래의 모델 선택 확인은 두 번째와 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아니라 트랜스크립트 공지로 나타납니다. [모델 구성](/docs/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.5313아래의 모델 선택 확인은 두 번째와 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아니라 트랜스크립트 공지로 나타납니다. [모델 구성](/docs/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.
4933 5314
