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) |
81| `Failed to start OAuth callback server` | [인증](#failed-to-start-oauth-callback-server) |
75| `Claude login not accepted · Run /login, then try again` | [인증](#claude-login-not-accepted) |82| `Claude login not accepted · Run /login, then try again` | [인증](#claude-login-not-accepted) |
76| `Artifacts need a claude.ai login` | [인증](#artifacts-need-a-claude-ai-login) |83| `Artifacts need a claude.ai login` | [인증](#artifacts-need-a-claude-ai-login) |
77| `Not signed in to the Cloud gateway — run /login.` | [인증](#administrator-policy-requires-a-cloud-gateway-sign-in) |84| `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) |85| `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) |86| `Failed to authenticate: OAuth session expired and could not be refreshed` | [인증](#login-expired) |
87| `Could not refresh your login because another Claude Code process is refreshing it` | [인증](#could-not-refresh-your-login) |
88| `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) |89| `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) |90| `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) |91| `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) |129| `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) |130| `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) |131| `Couldn't share the transcript.` | [네트워크](#couldnt-share-the-transcript) |
132| `Couldn't send feedback` | [네트워크](#couldnt-send-feedback) |
123| `Prompt is too long` / `Input is too long for requested model` | [요청 오류](#prompt-is-too-long) |133| `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) |134| `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) |135| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [요청 오류](#prompt-is-too-long) |
131| `all upstreams failed (N attempted)` on a Claude apps gateway session | [업스트림 오류 메시지](/docs/ko/claude-apps-gateway-config#upstream-error-messages) |141| `all upstreams failed (N attempted)` on a Claude apps gateway session | [업스트림 오류 메시지](/docs/ko/claude-apps-gateway-config#upstream-error-messages) |
132| `Claude Code may not be enabled for your organization` after a Claude apps gateway sign-in | [Claude apps gateway 문제 해결](/docs/ko/claude-apps-gateway-deploy#troubleshooting) |142| `Claude Code may not be enabled for your organization` after a Claude apps gateway sign-in | [Claude apps gateway 문제 해결](/docs/ko/claude-apps-gateway-deploy#troubleshooting) |
133| `Context exceeds the ...-token limit by ... tokens` in `/context` output | [요청 오류](#context-exceeds-the-token-limit) |143| `Context exceeds the ...-token limit by ... tokens` in `/context` output | [요청 오류](#context-exceeds-the-token-limit) |
134| `Error during compaction: Conversation too long` | [요청 오류](#error-during-compaction-conversation-too-long) |
135| `Request too large` | [요청 오류](#request-too-large) |144| `Request too large` | [요청 오류](#request-too-large) |
136| `Request too large for the API's 32MB request limit` | [요청 오류](#request-too-large) |145| `Request too large for the API's 32MB request limit` | [요청 오류](#request-too-large) |
137| `Image was too large` | [요청 오류](#image-was-too-large) |146| `Image was too large` | [요청 오류](#image-was-too-large) |
138| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |147| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |
139| `PDF too large` / `PDF is password protected` | [요청 오류](#pdf-errors) |148| `PDF too large` / `PDF is password protected` / `pdftoppm is not installed` | [요청 오류](#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) |
169| `Download timed out: exceeded the total deadline` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |183| `Download timed out: exceeded the total deadline` | [설치 오류](#the-connection-dropped-while-downloading-the-update) |
170| `--bg and --print conflict` | [명령줄 오류](#command-line-errors) |184| `--bg and --print conflict` | [명령줄 오류](#conflict-between-bg-and-print) |
171| `Cloud sessions cannot be created from a --restricted session` | [명령줄 오류](#cloud-sessions-cannot-be-created-from-a-restricted-session) |185| `Cloud sessions cannot be created from a --restricted session` | [명령줄 오류](#cloud-sessions-cannot-be-created-from-a-restricted-session) |
172| `Cloud sessions are disabled by your organization's policy` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |186| `Cloud sessions are disabled by your organization's policy` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |
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` | [명령줄 오류](#the-json-schema-value-is-not-a-valid-json-schema) |
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) |
241| `Its agent definition was not restored: the folder its definition file came from is not trusted` | [도구 오류](#teammate-agent-definition-not-restored) |264| `Its agent definition was not restored: the folder its definition file came from is not trusted` | [도구 오류](#teammate-agent-definition-not-restored) |
242| `Message too large for cross-session delivery` | [도구 오류](#message-too-large-for-cross-session-delivery) |265| `Message too large for cross-session delivery` | [도구 오류](#message-too-large-for-cross-session-delivery) |
243| `Too many messages to this session just now` | [도구 오류](#too-many-messages-to-this-session-just-now) |266| `Too many messages to this session just now` | [도구 오류](#too-many-messages-to-this-session-just-now) |
267| `Cross-session message was dropped at the recipient session's inbox` | [도구 오류](#cross-session-message-dropped-at-the-inbox) |
244| `Refusing to send: reply target is a symlink` / `Refusing to send: cannot vet reply target` | [도구 오류](#refusing-to-send-a-cross-session-message) |268| `Refusing to send: reply target is a symlink` / `Refusing to send: cannot vet reply target` | [도구 오류](#refusing-to-send-a-cross-session-message) |
245| `Refusing to send: connected endpoint is not the expected process` / `Refusing to send: connected endpoint identity could not be read` | [도구 오류](#refusing-to-send-a-cross-session-message) |
246| `Refusing to send: connected endpoint is not owned by this user` / `Refusing to send: connected endpoint owner could not be read` | [도구 오류](#refusing-to-send-a-cross-session-message) |
247| `Refusing to send: connected endpoint is a different process with the expected pid` | [도구 오류](#refusing-to-send-a-cross-session-message) |
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) |269| `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) |270| `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) |271| `Refusing to write through symlink: <path>` / `Refusing to write into symlinked directory: <path>` | [도구 오류](#refusing-after-a-symlink-changed) |
272| `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) |273| `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) |274| `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) |275| `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) |276| `Command killed: its output file was replaced or could no longer be verified` | [도구 오류](#task-output-swap-refused) |
277| `Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)` | [도구 오류](#disk-quota-or-temp-filesystem-is-full) |
278| `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) |
279| `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) |280| `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) |281| `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) |282| `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) |304| `EACCES: permission denied, posix_spawn` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |
280| `exited before it became reachable` | [백그라운드 세션 오류](#background-service-exited-before-it-became-reachable) |305| `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) |306| `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) |
307| `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) |308| `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) |309| `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) |310| `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) |317| `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) |318| `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) |319| `Agent descriptions are over the 15.0k-token limit` | [구성 경고](#agent-descriptions-are-over-the-15000-token-limit) |
320| `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) |321| `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) |322| `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) |323| `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) |324| `Managed settings were not approved; exiting without applying them.` | [구성 경고](#managed-settings-were-not-approved) |
325| `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) |326| `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) |327| `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) |328| `Managed settings drop-in directory could not be read` | [구성 경고](#managed-settings-document-could-not-be-parsed) |
313 자동 재시도341 자동 재시도
314</h2>342</h2>
315 343
316Claude Code는 오류를 표시하기 전에 지수 백오프를 사용하여 일시적 오류를 최대 10회까지 재시도합니다. Claude의 응답 중간에 도착한 오류는 항상 재시도하지 않습니다. 이 페이지의 오류 중 하나를 보면 Claude Code는 이미 해당 오류에 적용되는 모든 재시도를 수행했습니다. 아래 목록은 어떤 오류가 전체 예산을 받는지, 어떤 오류가 더 작은 예산을 받는지, 어떤 오류가 재시도되지 않는지를 나타냅니다.344Claude Code는 오류를 표시하기 전에 지수 백오프를 사용하여 일시적 오류를 최대 10회까지 재시도합니다. Claude의 응답 중간에 도착한 오류는 항상 재시도하지 않습니다. 이 페이지의 오류 중 하나를 보면 Claude Code는 이미 해당 오류에 적용되는 모든 재시도를 수행했습니다.
317 345
318Claude Code는 다음 오류를 재시도합니다:346Claude Code는 다음 오류를 재시도합니다:
319 347
390 418
391뒤따르는 문장은 서비스 상태를 확인할 위치를 명시하며 제공자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 구성은 해당 제공자의 서비스 상태를 명시합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 명시합니다.419뒤따르는 문장은 서비스 상태를 확인할 위치를 명시하며 제공자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 구성은 해당 제공자의 서비스 상태를 명시합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 명시합니다.
392 420
393이는 API 내부의 예상치 못한 실패를 나타냅니다. 이는 사용자의 프롬프트, 설정 또는 계정으로 인해 발생하지 않습니다.421API 자체의 5xx는 API 내부의 예상치 못한 실패를 나타냅니다. 이는 사용자의 프롬프트, 설정 또는 계정으로 인해 발생하지 않습니다.
422
423프록시, 로드 밸런서 또는 게이트웨이가 HTML 오류 페이지로 응답할 때 메시지는 상태 코드와 페이지의 제목(예: `API Error: 502 Bad Gateway`)을 표시합니다. 제목이 없는 페이지의 경우 메시지는 상태 코드와 표준 이름을 대신 표시합니다. v2.1.281 이전에는 페이지에 제목이 있을 때 상태 코드가 삭제되었고 제목이 없을 때 페이지의 원본 마크업이 인쇄되었습니다.
394 424
395**수행할 작업:**425**수행할 작업:**
396 426
416 446
417* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다447* [status.claude.com](https://status.claude.com) 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다
418* 몇 분 후에 다시 시도합니다448* 몇 분 후에 다시 시도합니다
419* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`입니다.449* `/model`을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 이를 수행하도록 프롬프트합니다. 예를 들어 `Opus is experiencing high load, please use /model to switch to Sonnet`입니다. Fable 모델에서 메시지는 Fable을 명시합니다.
450
451 Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는 `Opus is experiencing high load. Switch to Sonnet.`으로 읽히며 앱의 모델 선택기로 모델을 전환합니다.
420 452
421<h3 id="request-timed-out">453<h3 id="request-timed-out">
422 요청 시간 초과454 요청 시간 초과
433**수행할 작업:**465**수행할 작업:**
434 466
435* 요청을 다시 시도합니다467* 요청을 다시 시도합니다
436* 장기 실행 작업의 경우 작업을 더 작은 프롬프트로 나눕니다
437* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다468* 느린 네트워크 또는 프록시가 원인인 경우 [자동 재시도](#automatic-retries)에 설명된 대로 `API_TIMEOUT_MS`를 높입니다
438* 시간 초과가 빈번하고 네트워크가 정상인 경우 아래의 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하세요469* 시간 초과가 빈번하고 네트워크가 정상인 경우 아래의 [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하세요
439 470
457**수행할 작업:**488**수행할 작업:**
458 489
459* 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신 `try again`을 입력할 수 있습니다.490* 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신 `try again`을 입력할 수 있습니다.
460* 반복되면 [네트워크 또는 프록시 문제](#unable-to-connect-to-api)로 취급합니다. 연결을 수락하고 요청을 절대 전달하지 않는 프록시는 모든 시도에서 이 오류를 생성합니다.491* 반복되면 [네트워크 또는 프록시 문제](#unable-to-connect-to-api)로 취급합니다.
461* 네트워크의 프록시 또는 게이트웨이가 응답을 생성이 완료될 때까지 보유하는 경우 `API_TIMEOUT_MS`를 높여 재시도가 더 오래 대기하도록 합니다. Amazon Bedrock에서 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`도 높입니다.492* 네트워크의 프록시 또는 게이트웨이가 응답을 생성이 완료될 때까지 보유하는 경우 `API_TIMEOUT_MS`를 높여 재시도가 더 오래 대기하도록 합니다. Amazon Bedrock에서 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`도 높입니다.
462* 첫 시도가 계속 시간 초과되고 재시도가 성공하면 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`를 높여 첫 시도도 충분히 오래 대기하도록 합니다.493* 첫 시도가 계속 시간 초과되고 재시도가 성공하면 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`를 높여 첫 시도도 충분히 오래 대기하도록 합니다.
463 494
474API Error: Connection lost mid-response. The response above may be incomplete.505API 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.506API 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.507API Error: The response stopped arriving. The response above may be incomplete.
508API Error: Part of the response never arrived. The response above may be incomplete.
509API Error: The response stream was malformed. The response above may be incomplete.
477```510```
478 511
479* `Server error mid-response`: 스트림 중간 오버로드 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.512* `Server error mid-response`: 스트림 중간 오버로드 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.
480* `Connection lost mid-response`: 연결이 끊어졌습니다.513* `Connection lost mid-response`: 연결이 끊어졌습니다. 프록시 또는 게이트웨이가 응답이 완료되기 전에 응답 본문을 깔끔하게 종료할 때도 이 변형이 표시됩니다.
481* `Your computer went to sleep mid-response`: Claude Code가 응답이 스트리밍되는 동안 컴퓨터가 절전 모드로 전환되었음을 감지했습니다. 컴퓨터가 깨어나면 Claude Code는 연결을 끊어진 것으로 취급하고 읽기를 중지합니다.514* `Your computer went to sleep mid-response`: Claude Code가 응답이 스트리밍되는 동안 컴퓨터가 절전 모드로 전환되었음을 감지했습니다. 컴퓨터가 깨어나면 Claude Code는 연결을 끊어진 것으로 취급하고 읽기를 중지합니다.
515* `Part of the response never arrived`: 스트림 이벤트가 API와 Claude Code 사이에서 손실되어 나중 이벤트가 도착하지 않은 콘텐츠를 참조했습니다. v2.1.281 이전에는 이 경우 턴이 `API Error: Content block not found`로 종료되었습니다.
516* `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)를 참조하세요.517* `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 518
484v2.1.227 이전에는 `Connection lost mid-response`가 `Connection closed mid-response`로 읽혔고 `The response stopped arriving`이 `Response stalled mid-stream`으로 읽혔습니다.519v2.1.227 이전에는 `Connection lost mid-response`가 `Connection closed mid-response`로 읽혔고 `The response stopped arriving`이 `Response stalled mid-stream`으로 읽혔습니다.
485 520
521Claude가 텍스트 또는 도구 호출을 시작하기 전에 손실되거나 중복된 스트림 이벤트가 도착하면 이 공지가 표시되지 않습니다:
522
523* 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.`으로 끝납니다.
524* 아무것도 완료되지 않았으면 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` 또는 파서의 원본 오류로 끝납니다.
525
4864가지 경우에 Claude Code는 이 공지를 즉시 표시하지 않고 실패를 처리합니다:5264가지 경우에 Claude Code는 이 공지를 즉시 표시하지 않고 실패를 처리합니다:
487 527
488* 응답의 앞부분에서 Claude Code는 실패를 재시도하거나 다른 오류로 턴을 종료합니다. [자동 재시도](#automatic-retries)를 참조하세요.528* 응답의 앞부분에서 Claude Code는 실패를 재시도하거나 다른 오류로 턴을 종료합니다. [자동 재시도](#automatic-retries)를 참조하세요.
512<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.552<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.
513```553```
514 554
515Claude Code가 실패 범주를 결정할 수 있을 때 `temporarily unavailable` 뒤의 괄호에 범주를 명시합니다. 예를 들어 `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`입니다. 범주는 `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)` 및 `(connection failed)`입니다. 속도 제한, 오버로드 및 서버 오류는 일시적이며 재시도가 작동합니다. `(timed out)` 또는 `(connection failed)`가 반복되면 연결을 확인하세요. [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조하세요. v2.1.229 이전에는 메시지가 범주를 명시하지 않았고 `Wait briefly and then try this action again`으로 읽혔습니다.555Claude Code가 실패 범주를 결정할 수 있을 때 `temporarily unavailable` 뒤의 괄호에 범주를 명시합니다. 예를 들어 `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`입니다. 범주는 `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)` 및 `(connection failed)`입니다. `(timed out)` 또는 `(connection failed)`가 반복되면 연결을 확인하세요. [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조하세요. v2.1.229 이전에는 메시지가 범주를 명시하지 않았고 `Wait briefly and then try this action again`으로 읽혔습니다.
516 556
517범주가 맞지 않으면 메시지는 괄호에 범주 없이 나타납니다. 둘 이상의 실패가 해당 형식을 생성합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)에서, [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint) 포함, AWS 계정이 메시지에 명시된 모델을 호출할 수 없을 때도 나타나며, 계정에 모델에 대한 액세스 권한이 부여될 때까지 모든 재시도에서 해당 실패가 반복됩니다.557범주가 맞지 않으면 메시지는 괄호에 범주 없이 나타납니다. 둘 이상의 실패가 해당 형식을 생성합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)에서, [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint) 포함, AWS 계정이 메시지에 명시된 모델을 호출할 수 없을 때도 나타나며, 계정에 모델에 대한 액세스 권한이 부여될 때까지 모든 재시도에서 해당 실패가 반복됩니다.
518 558
533**수행할 작업:**573**수행할 작업:**
534 574
535* 작업을 재시도합니다. 이는 일반적으로 다음 시도에서 성공합니다575* 작업을 재시도합니다. 이는 일반적으로 다음 시도에서 성공합니다
536* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 기본 분류자 응답을 확인합니다576* `claude --debug`를 실행하고 작업을 반복하여 디버그 로그에서 세부 정보를 확인합니다
537 577
538별도의 API 안전 검사가 이전 대화 내용으로 인해 분류자 요청을 차단했을 때:578별도의 API 안전 검사가 이전 대화 내용으로 인해 분류자 요청을 차단했을 때:
539 579
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 context708API 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```709```
670 710
671이는 할당량 소진이 아닌 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. 1M 컨텍스트를 직접 포함하는 플랜과 사용 크레딧이 필요한 플랜은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하십시오. Claude Code는 `/model`로 모델을 선택할 때 이 확인을 실행하며 Anthropic API에 대한 직접 연결에서만 실행됩니다. `ANTHROPIC_BASE_URL`을 [LLM gateway](/docs/ko/llm-gateway)로 지정하면 `/model`은 `[1m]` 선택을 허용하고 게이트웨이가 요청 성공 여부를 결정합니다.711Claude Desktop app이 실행하는 세션에서 힌트는 명령을 지정하지 않습니다: claude.ai 사용 설정 페이지를 가리키거나 Team 및 Enterprise 플랜에서는 claude.ai/admin-settings/usage에서 사용 크레딧을 켜거나 관리자에게 요청하도록 지시합니다.
712
713이는 할당량 소진이 아닌 자격 확인입니다. 세션 및 주간 허용량에 용량이 남아 있어도 발생합니다. 1M 컨텍스트를 직접 포함하는 플랜과 사용 크레딧이 필요한 플랜은 [확장 컨텍스트](/docs/ko/model-config#extended-context)를 참조하십시오.
672 714
673이 오류가 컨텍스트가 200K 토큰을 초과하여 대화 중간에 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 한도 아래로 압축하고 이후 세션을 해당 한도로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서 복구하려면 `/clear`를 실행합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.715이 오류가 컨텍스트가 200K 토큰을 초과하여 대화 중간에 나타나면 Claude Code는 자동으로 대화를 표준 컨텍스트 한도 아래로 압축하고 이후 세션을 해당 한도로 유지하므로 조치가 필요하지 않습니다. v2.1.172 이전 버전에서는 `/compact`를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서 복구하려면 `/clear`를 실행합니다. 아래 단계는 명시적으로 `[1m]` 모델을 선택한 경우에 적용됩니다.
674 716
733 775
734뒤따르는 문장은 서비스 상태를 확인할 위치를 지정하며 공급자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 구성은 Anthropic 상태 페이지 대신 해당 공급자의 서비스 상태를 지정합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 지정합니다.776뒤따르는 문장은 서비스 상태를 확인할 위치를 지정하며 공급자에 따라 다릅니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 구성은 Anthropic 상태 페이지 대신 해당 공급자의 서비스 상태를 지정합니다. 사용자 정의 `ANTHROPIC_BASE_URL`은 게이트웨이 호스트를 지정합니다.
735 777
778Claude Code와 API 사이의 프록시, 로드 밸런서 또는 게이트웨이가 자체 HTML 429 페이지로 응답할 때 `·` 뒤의 텍스트는 해당 페이지의 제목(있는 경우)입니다(예: `Too Many Requests`). v2.1.281 이전에는 전체 페이지의 마크업이 `·` 뒤에 인쇄되었습니다.
779
736**수행할 작업:**780**수행할 작업:**
737 781
738* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경의 잘못된 `ANTHROPIC_API_KEY`는 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.782* `/status`를 실행하고 활성 자격 증명이 예상한 것인지 확인합니다. 환경의 잘못된 `ANTHROPIC_API_KEY`는 구독 대신 저가형 키를 통해 요청을 라우팅할 수 있습니다.
839Not logged in · Please run /login883Not logged in · Please run /login
840```884```
841 885
886Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는 `Authentication required · Sign in again to continue`로 읽으며, 앱에서 다시 로그인합니다.
887
842**수행할 작업:**888**수행할 작업:**
843 889
844* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다.890* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다.
846* CI 또는 자동화에서 대화형 로그인이 불가능한 경우, 시작 시 키를 가져오는 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다.892* CI 또는 자동화에서 대화형 로그인이 불가능한 경우, 시작 시 키를 가져오는 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다.
847* [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하여 여러 자격증명이 있을 때 Claude Code가 어떤 자격증명을 사용하는지 이해합니다.893* [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하여 여러 자격증명이 있을 때 Claude Code가 어떤 자격증명을 사용하는지 이해합니다.
848 894
849반복적으로 로그인하라는 메시지가 표시되면, 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계에 대해 [로그인하지 않음 또는 토큰 만료](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)를 참조하십시오.895반복적으로 로그인하라는 메시지가 표시되면, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)에서 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조하십시오.
850 896
851<h3 id="could-not-resolve-authentication-method">897<h3 id="could-not-resolve-authentication-method">
852 인증 방법을 확인할 수 없음898 인증 방법을 확인할 수 없음
862 908
863**수행할 작업:**909**수행할 작업:**
864 910
865* 백그라운드 또는 클라우드 세션에 이것이 나타나고 자격증명이 이미 구성되어 있으면 v2.1.176 이상으로 업그레이드합니다.911* 백그라운드 또는 클라우드 세션에서 이것이 나타나고 자격증명이 이미 구성되어 있으면 v2.1.176 이상으로 업그레이드합니다.
866* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격증명이 대화형 셸뿐만 아니라 워커를 실행하는 환경에 설정되어 있는지 확인합니다.912* `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` 또는 클라우드 공급자 자격증명이 대화형 셸이 아닌 워커를 실행하는 환경에서 설정되어 있는지 확인합니다.
867* Agent SDK의 경우, [빠른 시작의 인증 설정](/docs/ko/agent-sdk/quickstart#setup)을 참조하십시오.913* Agent SDK의 경우, [빠른 시작의 인증 설정](/docs/ko/agent-sdk/quickstart#setup)을 참조합니다.
868* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어떤 자격증명 소스가 확인되는지 확인합니다.914* 동일한 환경의 대화형 세션에서 `/status`를 실행하여 어떤 자격증명 소스가 확인되는지 확인합니다.
869 915
870<h3 id="invalid-api-key">916<h3 id="invalid-api-key">
877Invalid API key · Fix external API key923Invalid API key · Fix external API key
878```924```
879 925
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)을 참조하십시오.926메시지가 `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 927
882**수행할 작업:**928**수행할 작업:**
883 929
888* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.934* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.
889 935
890<h3 id="your-apikeyhelper-script-is-failing">936<h3 id="your-apikeyhelper-script-is-failing">
891 apiKeyHelper 스크립트가 실패함937 apiKeyHelper 스크립트가 실패 중입니다
892</h3>938</h3>
893 939
894Claude Code가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정의 명령을 실행했지만 키를 다시 받지 못했습니다. 키 없이는 요청이 자리 표시자 자격증명으로 API에 도달하고, API가 `401`로 거부합니다. 터미널의 `Authentication` 패널은 다음 중 어떤 일이 발생했는지 보여줍니다:940Claude Code가 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정에서 명령을 실행했지만 키를 다시 받지 못했습니다. 키 없이 요청이 자리 표시자 자격증명으로 API에 도달하고, API가 `401`로 거부합니다. 터미널의 `Authentication` 패널은 다음 중 어떤 일이 발생했는지 보여줍니다:
895 941
896* 명령이 오류로 종료되었거나 시간 초과됨942* 명령이 오류로 종료되었거나 시간 초과되었습니다.
897* 명령이 stdout에 아무것도 인쇄하지 않음943* 명령이 stdout에 아무것도 인쇄하지 않았습니다.
898* 명령이 로그인 배너 또는 로그 라인과 같은 키 이외의 것을 인쇄했습니다. 패널은 `returned output that cannot be used as an API key`를 표시하고 무엇이 잘못되었는지 말하며, 출력을 반복하지 않습니다. v2.1.227 이전에는 Claude Code가 주변 공백을 자른 후 명령이 인쇄한 모든 것을 전송했습니다.944* 명령이 로그인 배너 또는 로그 라인과 같이 키 이외의 것을 인쇄했습니다. 패널은 `returned output that cannot be used as an API key`를 표시하고 무엇이 잘못되었는지 말하며, 출력을 반복하지 않습니다. v2.1.227 이전에는 Claude Code가 주변 공백을 자른 후 명령이 인쇄한 모든 것을 전송했습니다.
899 945
900```text theme={null}946```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 output947Your 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 951
906Claude Code는 스크립트를 다시 실행하고 이 메시지를 표시하기 전에 요청을 최대 2회 더 재시도하므로, 실패는 3번의 시도 내에 표시됩니다. v2.1.208 이전에는 Claude Code가 전체 [재시도 예산](#automatic-retries)을 자리 표시자 자격증명으로 요청을 재전송하는 데 사용한 후 일반적인 `401` 인증 오류 대신 스크립트 실패를 보고했습니다.952Claude Code는 스크립트를 다시 실행하고 이 메시지를 표시하기 전에 요청을 최대 2회 더 재시도하므로, 실패는 3번의 시도 내에 표시됩니다. v2.1.208 이전에는 Claude Code가 전체 [재시도 예산](#automatic-retries)을 자리 표시자 자격증명으로 요청을 재전송하는 데 사용한 후 일반적인 `401` 인증 오류 대신 스크립트 실패를 보고했습니다.
907 953
908`/login`을 실행하는 것은 여기서 도움이 되지 않습니다: 헬퍼의 출력은 설정이 있는 한 저장된 로그인보다 [우선합니다](/docs/ko/authentication#authentication-precedence).954`/login`을 실행하는 것은 여기서 도움이 되지 않습니다: 헬퍼의 출력은 설정이 있는 한 저장된 로그인보다 [우선순위](/docs/ko/authentication#authentication-precedence)를 갖습니다.
909 955
910**수행할 작업:**956**수행할 작업:**
911 957
912* `apiKeyHelper`에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다.958* `apiKeyHelper`에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다.
913* 명령이 만료된 세션을 보고하면, 예를 들어 SSO 또는 비밀 자격증명 모음에 다시 로그인하여 자격증명 공급자로 다시 인증합니다.959* 명령이 만료된 세션을 보고하면, 예를 들어 SSO 또는 비밀 자격증명 모음에 다시 로그인하여 자격증명 공급자로 다시 인증합니다.
914* 명령이 stdout에만 키를 인쇄하도록 수정합니다. 최대 16,384자의 인쇄 가능한 ASCII의 단일 토큰으로, 종료 코드 0으로 종료합니다. 작동하는 설정은 [apiKeyHelper로 자격증명 회전](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper)을 참조하십시오.960* 명령이 stdout에만 키를 인쇄하도록 수정합니다. 단일 인쇄 가능한 ASCII 토큰으로 최대 16,384자이며 종료 코드 0으로 종료합니다. 작동하는 설정은 [apiKeyHelper로 자격증명 회전](/docs/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper)을 참조합니다.
915* `/status`를 실행하여 `apiKeyHelper`가 활성 자격증명 소스인지 확인합니다. `apiKeyHelper` 행은 `Failing`을 표시하며 마지막 실패의 세부 정보(예: 종료 코드 및 명령의 오류 출력)를 표시하고, 다음 성공적인 실행 후 사라집니다. v2.1.274 이전에는 `/status`가 자격증명 소스만 표시했고 실패를 표시하지 않았습니다.961* `/status`를 실행하여 실패를 확인하고 `apiKeyHelper`가 활성 자격증명 소스인지 확인합니다. `apiKeyHelper` 행은 종료 코드 및 명령의 오류 출력과 같은 마지막 실패의 세부 정보와 함께 `Failing`을 표시하며, 다음 성공적인 실행 후 사라집니다. v2.1.274 이전에는 `/status`가 실패가 아닌 자격증명 소스만 표시했습니다.
916* 명령이 실패할 때마다 종료 코드와 오류 출력이 터미널의 `Authentication` 패널에 나타납니다. v2.1.212 이전에는 패널의 제목이 `Cloud authentication`이었습니다.962* 명령이 실패할 때마다 종료 코드와 오류 출력도 터미널의 `Authentication` 패널에 나타납니다. v2.1.212 이전에는 패널의 제목이 `Cloud authentication`이었습니다.
917 963
918<h3 id="invalid-request-header-value">964<h3 id="invalid-request-header-value">
919 잘못된 요청 헤더 값965 잘못된 요청 헤더 값
921 967
922Claude Code가 요청 헤더로 전송하려던 값에 HTTP 헤더가 전달할 수 없는 문자가 포함되어 있습니다: 줄 바꿈, NUL 바이트 또는 `U+00FF` 위의 문자(예: 곡선 따옴표 또는 너비가 0인 공백). Claude Code는 아무것도 전송되기 전에 요청을 중지하고 수정할 변수 또는 설정의 이름을 지정합니다. 일반적인 원인은 보이지 않는 문자 또는 잘못된 줄 바꿈을 전달한 문서 또는 채팅에서 붙여넣은 자격증명입니다.968Claude Code가 요청 헤더로 전송하려던 값에 HTTP 헤더가 전달할 수 없는 문자가 포함되어 있습니다: 줄 바꿈, NUL 바이트 또는 `U+00FF` 위의 문자(예: 곡선 따옴표 또는 너비가 0인 공백). Claude Code는 아무것도 전송되기 전에 요청을 중지하고 수정할 변수 또는 설정의 이름을 지정합니다. 일반적인 원인은 보이지 않는 문자 또는 잘못된 줄 바꿈을 전달한 문서 또는 채팅에서 붙여넣은 자격증명입니다.
923 969
924Claude Code는 Claude API에 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 요청을 전송할 때 이 확인을 실행합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같은 타사 클라우드 공급자에서 Claude Code는 전송하기 전에 실행하지 않습니다.970Claude Code는 Claude API에 직접 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 요청을 전송할 때 이 확인을 실행합니다. [Amazon Bedrock](/docs/ko/amazon-bedrock)과 같은 타사 클라우드 공급자에서는 Claude Code가 전송하기 전에 실행하지 않습니다.
925 971
926```text theme={null}972```text theme={null}
927Invalid auth token · Fix external auth token973Invalid auth token · Fix external auth token
932메시지의 첫 번째 부분은 잘못된 값이 어디에서 왔는지에 따라 달라집니다:978메시지의 첫 번째 부분은 잘못된 값이 어디에서 왔는지에 따라 달라집니다:
933 979
934* `Invalid auth token`: [`ANTHROPIC_AUTH_TOKEN`](/docs/ko/env-vars) 또는 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 베어러 토큰980* `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` 쌍이 잘못되었는지 세지만, 이름이나 값을 반복하지 않습니다.981* `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`과 같은 다른 환경 변수에서 요청 헤더로 복사하는 값입니다. 설명은 수정할 변수의 이름을 지정합니다.982* `Invalid request header from the environment`: Claude Code가 `CLAUDE_AGENT_SDK_CLIENT_APP`과 같은 다른 환경 변수에서 요청 헤더로 복사하는 값입니다. 설명은 수정할 변수의 이름을 지정합니다.
937 983
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)으로 실패합니다.984Claude 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 985
940두 번째 `·` 이후에 메시지는 다음과 같은 전체 예제에서 문제를 설명합니다:986두 번째 `·` 이후에 메시지는 다음과 같은 전체 예제에서 문제를 설명합니다:
941 987
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).989Invalid 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```990```
945 991
946위치는 1부터 시작하는 문자를 세십시오. 설명은 고정된 구문과 문자 수로 구성되므로 값 자체를 포함하지 않습니다. 바이트 순서 표시, 너비가 0인 공백 또는 곡선 따옴표와 같은 잘 알려진 보이지 않는 또는 인쇄 문자인 경우에만 잘못된 문자의 이름을 지정하고, 다른 모든 것을 `a non-ASCII character`로 보고합니다.992위치는 1부터 시작하는 문자를 계산합니다. 설명은 고정된 구문과 문자 수로 구성되므로 값 자체를 포함하지 않습니다. 바이트 순서 표시, 너비가 0인 공백 또는 곡선 따옴표와 같이 잘 알려진 보이지 않는 또는 인쇄 문자인 경우에만 잘못된 문자의 이름을 지정하며, 다른 모든 것을 `a non-ASCII character`로 보고합니다.
947 993
948**수행할 작업:**994**수행할 작업:**
949 995
950* 메시지가 이름을 지정한 변수 또는 설정을 다시 설정하고, 동일한 소스에서 붙여넣지 않고 보고된 위치 주변의 문자를 다시 입력합니다.996* 메시지가 이름을 지정한 변수 또는 설정을 다시 설정하고, 동일한 소스에서 붙여넣는 대신 보고된 위치 주변의 문자를 다시 입력합니다.
951* `ANTHROPIC_CUSTOM_HEADERS`의 경우, 한 줄에 하나의 `Name: Value` 쌍을 유지하고 메시지가 세는 쌍을 다시 작성합니다.997* `ANTHROPIC_CUSTOM_HEADERS`의 경우, 한 줄에 하나의 `Name: Value` 쌍을 유지하고 메시지가 계산하는 쌍을 다시 작성합니다.
952* `/status`를 실행하여 어떤 자격증명 소스가 활성인지 확인합니다.998* `/status`를 실행하여 어떤 자격증명 소스가 활성화되어 있는지 확인합니다.
953 999
954<h3 id="this-organization-has-been-disabled">1000<h3 id="this-organization-has-been-disabled">
955 이 조직이 비활성화됨1001 이 조직이 비활성화되었습니다
956</h3>1002</h3>
957 1003
958Claude Code가 비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`를 사용하고 있습니다. 저장된 구독 로그인이 있으면 키가 이를 재정의합니다.1004Claude Code가 비활성화된 Console 조직의 오래된 `ANTHROPIC_API_KEY`를 사용 중입니다. 저장된 구독 로그인이 있으면 키가 이를 재정의합니다.
959 1005
960```text theme={null}1006```text theme={null}
961Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead1007Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
965 1011
966`·` 이후의 힌트는 저장된 자격증명에 따라 달라집니다: 첫 번째 형식은 저장된 `/login`이 키를 설정 해제한 후 인수할 수 있을 때 나타나고, 두 번째는 키가 유일한 자격증명일 때 나타납니다.1012`·` 이후의 힌트는 저장된 자격증명에 따라 달라집니다: 첫 번째 형식은 저장된 `/login`이 키를 설정 해제한 후 인수할 수 있을 때 나타나고, 두 번째는 키가 유일한 자격증명일 때 나타납니다.
967 1013
968환경 변수는 `/login`보다 우선하므로, 셸 프로필에서 내보낸 키 또는 `.env` 파일에서 로드된 키는 작동하는 Pro 또는 Max 구독이 있어도 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.1014환경 변수는 `/login`보다 우선순위를 가지므로, 셸 프로필에서 내보낸 키 또는 `.env` 파일에서 로드된 키는 작동하는 Pro 또는 Max 구독이 있어도 사용됩니다. 비대화형 모드(`-p`)에서는 키가 있을 때 항상 사용됩니다.
969 1015
970**수행할 작업:**1016**수행할 작업:**
971 1017
972* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 후 `claude`를 다시 실행합니다.1018* 현재 셸에서 `ANTHROPIC_API_KEY`를 설정 해제하고 셸 프로필에서 제거한 후 `claude`를 다시 실행합니다.
973* 메시지가 `Update or unset`이라고 말하면, 폴백할 저장된 로그인이 없습니다. 키를 설정 해제하고 `/login`을 실행하거나, 활성 Console 조직의 키로 바꿉니다.1019* 메시지가 `Update or unset`이라고 하면, 폴백할 저장된 로그인이 없습니다. 키를 설정 해제하고 `/login`을 실행하거나, 활성 Console 조직의 키로 바꿉니다.
974* 그 후 `/status`를 실행하여 활성 자격증명이 구독인지 확인합니다.1020* 그 후 `/status`를 실행하여 활성 자격증명이 구독인지 확인합니다.
975* 환경 변수가 설정되지 않았고 오류가 지속되면, 비활성화된 조직은 `/login`에 연결된 조직입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.1021* 환경 변수가 설정되지 않았고 오류가 지속되면, 비활성화된 조직은 `/login`에 연결된 조직입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.
976 1022
977<h3 id="your-organization-has-disabled-api-key-authentication">1023<h3 id="your-organization-has-disabled-api-key-authentication">
978 조직이 API 키 인증을 비활성화함1024 조직이 API 키 인증을 비활성화했습니다
979</h3>1025</h3>
980 1026
981이 메시지에는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 끄었으므로 API가 Claude Code가 전송하는 키를 거부합니다. 복구 힌트는 `·` 이후에 키가 어디에서 왔는지에 따라 달라집니다:1027이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 전송 중인 키를 거부합니다. 복구 힌트는 키가 어디에서 왔는지에 따라 `·` 이후에 달라집니다:
982 1028
983```text theme={null}1029```text theme={null}
984Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account1030Your 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 instead1031Your 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 account1032Your 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 account1033Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account
1034Your organization has disabled API key authentication · Sign in again with your claude.ai account
988```1035```
989 1036
990환경 변수와 `apiKeyHelper`는 `/login`보다 우선하므로, `/login`을 단독으로 실행하는 것은 둘 중 하나가 여전히 키를 공급하는 동안 도움이 되지 않습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조하십시오.1037마지막 형식은 Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에 나타나며, 앱에서 다시 로그인합니다.
1038
1039환경 변수와 `apiKeyHelper`는 `/login`보다 우선순위를 가지므로, 둘 중 하나가 여전히 키를 제공하는 동안 `/login`을 실행하는 것만으로는 도움이 되지 않습니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)를 참조합니다.
991 1040
992**수행할 작업:**1041**수행할 작업:**
993 1042
995* 메시지가 `apiKeyHelper`의 이름을 지정하면, `settings.json`에서 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정을 제거합니다.1044* 메시지가 `apiKeyHelper`의 이름을 지정하면, `settings.json`에서 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 설정을 제거합니다.
996* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.1045* `/login`을 실행하여 claude.ai 계정으로 로그인합니다.
997* 그 후 `/status`를 실행하여 활성 자격증명이 API 키가 아닌 구독인지 확인합니다.1046* 그 후 `/status`를 실행하여 활성 자격증명이 API 키가 아닌 구독인지 확인합니다.
998* 자동화를 위해 API 키 인증이 필요한 경우, 조직 관리자에게 Console에서 다시 활성화하도록 요청합니다.1047* 자동화를 위해 API 키 인증이 필요하면, 조직 관리자에게 Console에서 이를 다시 활성화하도록 요청합니다.
999 1048
1000<h3 id="your-organization-has-disabled-claude-subscription-access">1049<h3 id="your-organization-has-disabled-claude-subscription-access">
1001 조직이 Claude 구독 액세스를 비활성화함1050 조직이 Claude 구독 액세스를 비활성화했습니다
1002</h3>1051</h3>
1003 1052
1004Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.1053Claude 조직이 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 동일한 계정으로 `/login`을 다시 실행하면 동일한 오류가 반환됩니다.
1013 1062
1014**수행할 작업:**1063**수행할 작업:**
1015 1064
1016* 조직의 관리자에게 조직에 대한 Claude Code 액세스를 활성화하도록 요청합니다.1065* 조직 관리자에게 조직에 대한 Claude Code 액세스를 활성화하도록 요청합니다.
1017* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/docs/ko/authentication#claude-console-authentication)을 참조하십시오.1066* 구독 대신 Console API 키로 인증합니다. 설정은 [Claude Console 인증](/docs/ko/authentication#claude-console-authentication)을 참조합니다.
1018* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면, [Anthropic 지원](https://support.claude.com)에 문의합니다.1067* 관리자이고 액세스를 활성화하는 옵션이 보이지 않으면, [Anthropic 지원](https://support.claude.com)에 문의합니다.
1019 1068
1020<h3 id="routines-are-disabled-by-your-organizations-policy">1069<h3 id="routines-are-disabled-by-your-organizations-policy">
1021 루틴이 조직의 정책에 의해 비활성화됨1070 루틴이 조직의 정책에 의해 비활성화되었습니다
1022</h3>1071</h3>
1023 1072
1024Team 또는 Enterprise 조직의 Owner가 조직 수준에서 루틴을 끄었습니다. 오류는 예를 들어 claude.ai/code의 [루틴](/docs/ko/routines) UI에서 루틴을 만들거나 실행하려고 할 때 나타납니다. Claude Code v2.1.227 이상에서는 동일한 설정이 CLI에서 [`/schedule`도 숨깁니다](/docs/ko/routines#troubleshooting).1073Team 또는 Enterprise 조직의 Owner가 조직 수준에서 루틴을 비활성화했습니다. 오류는 예를 들어 claude.ai/code의 [루틴](/docs/ko/routines) UI에서 루틴을 생성하거나 실행하려고 할 때 나타납니다. Claude Code v2.1.227 이상에서는 동일한 설정이 CLI에서 [`/schedule`도 숨깁니다](/docs/ko/routines#troubleshooting).
1025 1074
1026```text theme={null}1075```text theme={null}
1027Routines are disabled by your organization's policy.1076Routines are disabled by your organization's policy.
1032**수행할 작업:**1081**수행할 작업:**
1033 1082
1034* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **루틴** 토글을 활성화하도록 요청합니다.1083* 조직의 Owner에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **루틴** 토글을 활성화하도록 요청합니다.
1035* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우, [예약된 작업](/docs/ko/scheduled-tasks)을 참조하십시오.1084* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우, [예약된 작업](/docs/ko/scheduled-tasks)을 참조합니다.
1036 1085
1037<h3 id="remote-control-requires-the-anthropic-api">1086<h3 id="remote-control-requires-the-anthropic-api">
1038 원격 제어에는 Anthropic API가 필요함1087 Remote Control에는 Anthropic API가 필요합니다
1039</h3>1088</h3>
1040 1089
1041세션이 Anthropic API와 직접 통신하지 않으므로 [원격 제어](/docs/ko/remote-control)가 쌍을 이룰 claude.ai 백엔드가 없습니다.1090세션이 Anthropic API와 직접 통신하지 않으므로 [Remote Control](/docs/ko/remote-control)이 필요로 하는 것입니다.
1042 1091
1043```text theme={null}1092```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.1093Remote 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 1095
1047두 번째 문장은 세션을 Anthropic API에서 멀어지게 한 것을 설명합니다. v2.1.219 이전에는 메시지가 첫 번째 문장만 있었습니다. 원인에 따라 메시지는 다음의 이름을 지정합니다:1096두 번째 문장은 세션을 Anthropic API에서 멀어지게 한 것을 설명합니다. v2.1.219 이전에는 메시지가 첫 번째 문장만 있었습니다. 원인에 따라 메시지는 다음의 이름을 지정합니다:
1048 1097
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_*` 공급자 변수1098* `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이 원격 제어를 차단하지 않았습니다.1099* [`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`이 아닌 로컬 소켓을 통해 요청을 전송합니다.1100* `ANTHROPIC_UNIX_SOCKET`이 설정되어 있으므로 세션이 `api.anthropic.com`이 아닌 로컬 소켓을 통해 요청을 전송합니다.
1052* `/login`을 통한 엔터프라이즈 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인으로, 원격 제어를 지원하지 않으며 설정 해제할 변수가 없습니다.1101* `/login`을 통한 엔터프라이즈 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway) 로그인으로, Remote Control을 지원하지 않으며 설정 해제할 변수가 없습니다.
1053 1102
1054**수행할 작업:**1103**수행할 작업:**
1055 1104
1056* 메시지가 이름을 지정한 변수(예: `CLAUDE_CODE_USE_BEDROCK` 또는 `ANTHROPIC_BASE_URL`)를 설정 해제하고 세션을 다시 시작하거나, Anthropic API와 직접 통신하는 세션에서 원격 제어를 시작합니다.1105* 메시지가 이름을 지정한 변수(예: `CLAUDE_CODE_USE_BEDROCK` 또는 `ANTHROPIC_BASE_URL`)를 설정 해제하고 세션을 다시 시작하거나, Anthropic API와 직접 통신하는 세션에서 Remote Control을 시작합니다.
1057* 변수가 셸에 설정되지 않았으면, [설정 파일](/docs/ko/settings#where-settings-live)의 `env` 키를 확인하십시오. 이는 모든 세션에 환경 변수를 적용합니다.1106* 변수가 셸에 설정되지 않았으면, [설정 파일](/docs/ko/settings#where-settings-live)의 `env` 키를 확인합니다. 이는 모든 세션에 환경 변수를 적용합니다.
1058* 이 및 다른 원격 제어 시작 메시지의 경우, [원격 제어 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조하십시오.1107* 이 및 다른 Remote Control 시작 메시지의 경우, [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조합니다.
1059 1108
1060<h3 id="remote-control-couldnt-refresh-your-login">1109<h3 id="remote-control-couldnt-refresh-your-login">
1061 원격 제어가 로그인을 새로 고칠 수 없음1110 Remote Control이 로그인을 새로 고칠 수 없습니다
1062</h3>1111</h3>
1063 1112
1064Claude Code는 저장된 claude.ai 로그인을 사용하여 얻고 갱신하는 단기 자격증명에서 라이브 [원격 제어](/docs/ko/remote-control) 연결을 실행합니다. claude.ai가 해당 로그인을 더 이상 수락하지 않거나 Claude Code에 저장된 로그인이 남아 있지 않으면, Claude Code는 원격 제어를 중지하고 다시 로그인하도록 요청합니다. 두 실패 모두 Claude Code가 여전히 연결 중이거나 나중에 자격증명을 갱신할 때 발생할 수 있습니다.1113Claude Code는 저장된 claude.ai 로그인을 사용하여 얻고 갱신하는 단기 자격증명에서 라이브 [Remote Control](/docs/ko/remote-control) 연결을 실행합니다. claude.ai가 해당 로그인을 더 이상 수락하지 않거나 Claude Code에 저장된 로그인이 남아 있지 않으면, Claude Code는 Remote Control을 중지하고 다시 로그인하도록 요청합니다. 두 실패 모두 Claude Code가 여전히 연결 중이거나 나중에 자격증명을 갱신할 때 발생할 수 있습니다.
1065 1114
1066Claude Code가 로그인 서비스에 저장된 로그인을 새로 고치도록 요청하고 응답을 받지 못하면, 원격 제어를 계속 실행하고 연결의 현재 자격증명이 여전히 유효한 동안 새로 고침을 다시 시도합니다. 새로 고침이 응답을 받지 못하는 경우는 Claude Code가 로그인 서비스에 도달할 수 없거나, 요청이 시간 초과되거나, 서비스가 로그인을 거부하지 않고 실패할 때입니다. 로그인 서비스가 해당 자격증명이 만료될 때까지 여전히 응답하지 않으면, Claude Code는 원격 제어를 중지하고 `OAuth token refresh failed`를 보고합니다.1115Claude Code가 로그인 서비스에 저장된 로그인을 새로 고치도록 요청하고 응답을 받지 못하면, Remote Control을 계속 실행하고 연결의 현재 자격증명이 여전히 유효한 동안 새로 고침을 다시 시도합니다. 새로 고침이 응답을 받지 못하는 경우는 Claude Code가 로그인 서비스에 도달할 수 없거나, 요청이 시간 초과되거나, 서비스가 로그인을 거부하지 않고 실패할 때입니다. 해당 자격증명이 만료될 때 로그인 서비스가 여전히 응답하지 않으면, Claude Code는 Remote Control을 중지하고 `OAuth token refresh failed`를 보고합니다.
1067 1116
1068Claude Code가 원격 제어를 중지하면, 경고 및 `Remote Control disconnected`로 시작하는 기록 라인에 이유를 표시합니다. 로컬 세션은 원격 제어 없이 계속 실행됩니다. 이 섹션은 다음 라인을 다룹니다:1117Claude Code가 Remote Control을 중지하면, 경고 및 `Remote Control disconnected`로 시작하는 기록 라인에 이유를 표시합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다. 이 섹션은 다음 라인을 다룹니다:
1069 1118
1070```text theme={null}1119```text theme={null}
1071Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control1120Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
1081 1130
1082* ` Claude.ai login expired` 및 `Claude.ai login was rejected`: claude.ai가 더 이상 저장된 로그인 토큰을 수락하지 않습니다. 만료되었거나 취소되었기 때문입니다.1131* ` Claude.ai login expired` 및 `Claude.ai login was rejected`: claude.ai가 더 이상 저장된 로그인 토큰을 수락하지 않습니다. 만료되었거나 취소되었기 때문입니다.
1083* ` OAuth token unavailable`: Claude Code가 연결의 자격증명이 갱신될 때 저장된 로그인 토큰이 없었습니다.1132* ` OAuth token unavailable`: Claude Code가 연결의 자격증명이 갱신될 때 저장된 로그인 토큰이 없었습니다.
1084* `OAuth token refresh failed`: claude.ai가 Claude Code가 다시 연결할 때 저장된 로그인 토큰을 거부했고, 토큰을 새로 고치면 새 토큰이 생성되지 않았습니다.1133* `OAuth token refresh failed`: Claude Code가 다시 연결할 때 claude.ai가 저장된 로그인 토큰을 거부했으며, 토큰을 새로 고치면 새 토큰이 생성되지 않았습니다.
1085* `JWT refresh failed: no OAuth token`: Claude Code가 갱신할 저장된 로그인 토큰을 찾지 못했습니다.1134* `JWT refresh failed: no OAuth token`: Claude Code가 갱신할 저장된 로그인 토큰을 찾지 못했습니다.
1086* ` Signed out of Claude`: 예를 들어 다른 터미널에서 `/logout`을 실행하여 이 머신에서 로그아웃했으므로 Claude Code가 연결을 갱신할 저장된 로그인이 없습니다.1135* ` Signed out of Claude`: 예를 들어 다른 터미널에서 `/logout`을 실행하여 이 머신에서 로그아웃했으므로 Claude Code가 연결을 갱신할 저장된 로그인이 없습니다.
1087 1136
1090* `/login`을 실행하여 다시 로그인합니다.1139* `/login`을 실행하여 다시 로그인합니다.
1091* `/remote-control`을 실행하여 세션을 다시 연결합니다. ` run /login to restore Remote Control`으로 끝나는 메시지는 이 단계가 필요하지 않습니다: Claude Code는 로그인하면 자동으로 다시 연결됩니다.1140* `/remote-control`을 실행하여 세션을 다시 연결합니다. ` run /login to restore Remote Control`으로 끝나는 메시지는 이 단계가 필요하지 않습니다: Claude Code는 로그인하면 자동으로 다시 연결됩니다.
1092 1141
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에서 추가되었습니다.1142v2.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 1143
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`으로 원격 제어를 중지했습니다.1144v2.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 1145
1097<h3 id="remote-control-stopped-because-the-signed-in-account-changed">1146<h3 id="remote-control-stopped-because-the-signed-in-account-changed">
1098 원격 제어가 로그인한 계정이 변경되어 중지됨1147 Remote Control이 로그인한 계정이 변경되어 중지되었습니다
1099</h3>1148</h3>
1100 1149
1101Claude Code는 [원격 제어](/docs/ko/remote-control) 세션 중에 이 라인을 표시합니다. 이 머신에서 다른 claude.ai 계정 또는 조직으로 로그인합니다. 예를 들어 다른 터미널에서 `/login`을 실행하여 Claude Code 세션 외부에서 전환했습니다.1150Claude Code는 이 머신에서 다른 claude.ai 계정 또는 조직으로 로그인할 때 [Remote Control](/docs/ko/remote-control) 세션 중에 이 라인을 표시합니다. 예를 들어 다른 터미널에서 `/login`을 실행하여 Claude Code 세션 외부에서 전환했습니다.
1102 1151
1103`/login`을 통해 로그인하는 동안 시작한 원격 제어 세션은 당시에 로그인한 claude.ai 계정 및 조직에 속합니다.1152`/login`을 통해 로그인하는 동안 시작한 Remote Control 세션은 당시 로그인한 claude.ai 계정 및 조직에 속합니다.
1104 1153
1105```text theme={null}1154```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-control1155Remote 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```1156```
1108 1157
1109Claude Code는 claude.ai가 계정 또는 조직이 변경되었음을 확인하는 즉시 원격 제어 세션을 중지합니다. 로컬 세션은 원격 제어 없이 계속 실행됩니다.1158Claude Code는 claude.ai가 계정 또는 조직이 변경되었음을 확인하자마자 Remote Control 세션을 중지합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다.
1110 1159
1111**수행할 작업:**1160**수행할 작업:**
1112 1161
1113* `/remote-control`을 실행하여 현재 계정 또는 조직에서 새 원격 제어 세션을 시작합니다.1162* `/remote-control`을 실행하여 현재 계정 또는 조직에서 새 Remote Control 세션을 시작합니다.
1114* 다시 전환하려면 `/login`을 실행하고 이전 계정 또는 조직으로 다시 로그인합니다. 그런 다음 `/remote-control`을 실행합니다.1163* 다시 전환하려면, `/login`을 실행하고 이전 계정 또는 조직으로 다시 로그인합니다. 그런 다음 `/remote-control`을 실행합니다.
1115 1164
1116v2.1.234 이전에는 Claude Code가 Claude Code 세션 외부에서 다른 계정 또는 조직으로 전환할 때 알아차리지 못했습니다. Claude Code는 원격 제어 서버에 대한 나중의 요청이 `Remote Control server rejected the request (HTTP 404)`로 실패할 때까지 원격 제어 세션을 연결된 상태로 유지했습니다. 이 실패는 전환 후 몇 시간 후에 올 수 있습니다.1165v2.1.234 이전에는 Claude Code가 Claude Code 세션 외부에서 다른 계정 또는 조직으로 전환할 때 알아차리지 못했습니다. Claude Code는 Remote Control 서버에 대한 나중의 요청이 `Remote Control server rejected the request (HTTP 404)`로 실패할 때까지 Remote Control 세션을 연결된 상태로 유지했습니다. 해당 실패는 전환 후 몇 시간이 지날 수 있습니다.
1117 1166
1118<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">1167<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">
1119 원격 제어가 세션을 실행하는 앱이 로그아웃하거나 계정을 전환했기 때문에 중지됨1168 Remote Control이 세션을 실행 중인 앱이 로그아웃하거나 계정을 전환하여 중지되었습니다
1120</h3>1169</h3>
1121 1170
1122Claude 데스크톱 앱 또는 IDE가 세션을 호스팅할 때, Claude Code는 `/login` 대신 해당 앱에서 로그인 토큰을 가져옵니다. claude.ai가 해당 토큰을 거부할 때, Claude Code는 앱에 새 토큰을 요청합니다. 앱이 로그아웃했거나 이제 다른 Claude 계정으로 로그인했다고 응답하면, Claude Code는 [원격 제어](/docs/ko/remote-control) 세션을 종료하고 앱에 다음 라인 중 하나를 보냅니다:1171Claude 데스크톱 앱 또는 IDE가 세션을 호스팅할 때, Claude Code는 `/login`이 아닌 해당 앱에서 로그인 토큰을 가져옵니다. claude.ai가 해당 토큰을 거부할 때, Claude Code는 앱에 새 토큰을 요청합니다. 앱이 로그아웃했거나 이제 다른 Claude 계정으로 로그인했다고 응답하면, Claude Code는 [Remote Control](/docs/ko/remote-control) 세션을 종료하고 앱에 다음 라인 중 하나를 보냅니다:
1123 1172
1124```text theme={null}1173```text theme={null}
1125Remote Control stopped — the app running this session is now signed in to a different Claude account1174Remote 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 on1175Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on
1127```1176```
1128 1177
1129로컬 세션은 원격 제어 없이 계속 실행됩니다.1178로컬 세션은 Remote Control 없이 계속 실행됩니다.
1130 1179
1131**수행할 작업:**1180**수행할 작업:**
1132 1181
1133* 앱이 로그아웃되면, 다시 로그인한 후 앱에서 원격 제어를 다시 켭니다.1182* 앱이 로그아웃했으면, 다시 로그인한 후 앱에서 Remote Control을 다시 켭니다.
1134* 앱이 계정을 전환하면, Claude Code는 새 계정에서 종료된 세션을 계속할 수 없습니다. 해당 계정에서 새 원격 제어 세션을 시작합니다.1183* 앱이 계정을 전환했으면, Claude Code는 새 계정에서 종료된 세션을 계속할 수 없습니다. 해당 계정에서 새 Remote Control 세션을 시작합니다.
1135 1184
1136v2.1.238 이전에는 Claude Code가 두 경우 모두에서 [원격 제어가 로그인을 새로 고칠 수 없음](#remote-control-couldnt-refresh-your-login)에 나열된 `run /login` 메시지를 앱에 보냈습니다.1185v2.1.238 이전에는 Claude Code가 두 경우 모두에서 앱에 [Remote Control이 로그인을 새로 고칠 수 없습니다](#remote-control-couldnt-refresh-your-login)에 나열된 `run /login` 메시지를 보냈습니다.
1137 1186
1138<h3 id="oauth-token-revoked-or-expired">1187<h3 id="oauth-token-revoked-or-expired">
1139 OAuth 토큰이 취소되었거나 만료됨1188 OAuth 토큰이 취소되었거나 만료되었습니다
1140</h3>1189</h3>
1141 1190
1142저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.1191저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.
1143 1192
1144두 메시지 모두 Claude Code가 전송한 요청에 대해 API가 반환한 거부를 보고합니다. 저장된 로그인이 실패한 새로 고침 후 이미 지워진 경우, 대신 [로그인 만료됨](#login-expired)을 참조하십시오. [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)의 장기 토큰으로 인증하면, 해당 토큰이 만료되거나 취소될 때 동일한 메시지가 표시됩니다.1193두 메시지 모두 Claude Code가 전송한 요청에 대해 API가 반환한 거부를 보고합니다. 저장된 로그인이 실패한 새로 고침 후 이미 지워진 경우, 대신 [로그인 만료됨](#login-expired)을 봅니다. [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars)에서 장기 토큰으로 인증하면, 해당 토큰이 만료되거나 취소될 때 동일한 메시지가 표시됩니다.
1145 1194
1146```text theme={null}1195```text theme={null}
1147OAuth token revoked · Please run /login1196OAuth token revoked · Please run /login
1151**수행할 작업:**1200**수행할 작업:**
1152 1201
1153* `/login`을 실행하여 다시 로그인합니다.1202* `/login`을 실행하여 다시 로그인합니다.
1154* 오류가 다시 인증한 후 동일한 세션 내에서 반환되면, 먼저 `/logout`을 실행하여 저장된 토큰을 완전히 지운 후 `/login`을 실행합니다.1203* ` 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 오류로 실패했습니다.
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 오류로 실패했습니다.1204* 시작 간 반복적인 로그인 프롬프트의 경우, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조합니다.
1156* 시작 간 반복되는 로그인 프롬프트의 경우, [문제 해결](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 확인 및 macOS 자격증명 저장소 복구 단계를 참조하십시오.1205* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조합니다.
1157* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하십시오.
1158 1206
1159<h3 id="api-error-401-invalid-authentication-credentials">1207<h3 id="api-error-401-invalid-authentication-credentials">
1160 API 오류: 401 잘못된 인증 자격증명1208 API 오류: 401 잘못된 인증 자격증명
1161</h3>1209</h3>
1162 1210
1163API가 자격증명의 형식을 인식했지만 뒤에 있는 계정 또는 조직을 거부했습니다. Anthropic은 자격증명이 최근에 취소되었을 때, 조직이 비활성화되었거나 액세스를 제거했을 때, 또는 계정 자체가 비활성화되었을 때 이 메시지를 반환하므로, 만료된 토큰이 원인이 아닙니다. 자격증명은 저장된 로그인 또는 승인된 `ANTHROPIC_API_KEY`일 수 있으며, 수정이 다르므로 `/status`를 실행하여 어떤 것이 활성인지 확인하여 시작합니다.1211API가 자격증명의 형식을 인식했지만 뒤에 있는 계정 또는 조직을 거부했습니다. Anthropic은 자격증명이 최근에 취소되었거나, 조직이 비활성화되었거나 액세스를 제거했거나, 계정 자체가 비활성화되었을 때 이 메시지를 반환하므로, 만료된 토큰이 원인이 아닙니다. 자격증명은 저장된 로그인 또는 승인된 `ANTHROPIC_API_KEY`일 수 있으며, 수정이 다르므로 `/status`를 실행하여 어떤 것이 활성화되어 있는지 확인하여 시작합니다.
1164 1212
1165```text theme={null}1213```text theme={null}
1166Please run /login · API Error: 401 Invalid authentication credentials1214Please run /login · API Error: 401 Invalid authentication credentials
1168 1216
1169**수행할 작업:**1217**수행할 작업:**
1170 1218
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`를 실행하여 구독으로 폴백합니다.1219* `/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`을 한 번 실행합니다. 자격증명이 취소되었으면, 새 로그인이 이를 바꿉니다.1220* `/status`가 로그인만 표시하면, `/login`을 한 번 실행합니다. 자격증명이 취소되었으면, 새 로그인이 이를 바꿉니다.
1173* 동일한 로그인 계정에 대해 동일한 메시지가 반환되면, 계정 또는 조직이 더 이상 활성화되지 않습니다. `/status`가 보고하는 계정 및 조직을 확인하고, 조직 관리자에게 액세스를 복구하도록 요청합니다.1221* 동일한 로그인 계정에 대해 동일한 메시지가 반환되면, 계정 또는 조직이 더 이상 활성화되지 않습니다. `/status`가 보고하는 계정 및 조직을 확인하고, 조직 관리자에게 액세스를 복구하도록 요청합니다.
1174* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키면, `401` 이후의 텍스트는 Anthropic의 메시지가 아닌 게이트웨이의 메시지이고, `/login`이 이를 변경하지 않습니다. 대신 게이트웨이가 예상하는 자격증명을 수정합니다.1222* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)이 [LLM 게이트웨이](/docs/ko/llm-gateway)를 가리키면, `401` 이후의 텍스트는 Anthropic의 메시지가 아닌 게이트웨이의 메시지이며, `/login`이 이를 변경하지 않습니다. 게이트웨이가 예상하는 자격증명을 대신 수정합니다.
1175 1223
1176<h3 id="login-expired">1224<h3 id="login-expired">
1177 로그인 만료됨1225 로그인 만료됨
1178</h3>1226</h3>
1179 1227
1180Claude Code가 저장된 claude.ai 또는 Claude Console 로그인을 갱신하려고 시도했고 OAuth 서비스가 저장된 새로 고침 토큰을 거부했으므로, Claude Code가 저장된 자격증명을 지웠습니다. 그 후, 각 모델 요청은 API에 도달하기 전에 로컬에서 이 메시지로 중지됩니다. `/login`만 새 자격증명을 만들 수 있기 때문입니다.1228Claude Code가 저장된 claude.ai 또는 Claude Console 로그인을 갱신하려고 했으며 OAuth 서비스가 저장된 새로 고침 토큰을 거부했으므로, Claude Code가 저장된 자격증명을 지웠습니다. 그 후, 각 모델 요청은 `/login`만 새 자격증명을 만들 수 있으므로 API에 도달하기 전에 로컬에서 이 메시지로 중지됩니다.
1181 1229
1182v2.1.206 이전에는 Claude Code가 환경에 남아 있는 모든 자격증명으로 모델 요청을 어쨌든 전송했고, 모든 모델이 로그인하라는 프롬프트 대신 [선택한 모델에 문제가 있음](#theres-an-issue-with-the-selected-model) 또는 401로 실패했습니다.1230v2.1.206 이전에는 Claude Code가 환경에 남아 있는 모든 자격증명으로 모델 요청을 어쨌든 전송했으며, 모든 모델이 로그인하라는 프롬프트 대신 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model) 또는 401로 실패했습니다.
1183 1231
1184```text theme={null}1232```text theme={null}
1185Login expired · Please run /login1233Login expired · Please run /login
1191Failed to authenticate: OAuth session expired and could not be refreshed1239Failed to authenticate: OAuth session expired and could not be refreshed
1192```1240```
1193 1241
1194이것은 [OAuth 토큰이 취소되었거나 만료됨](#oauth-token-revoked-or-expired)과 동일한 상태가 아닙니다. 이러한 메시지는 API가 반환한 거부를 보고합니다. Claude Code 자체는 이미 갱신하지 못한 로그인에 대해 `Login expired`를 생성하므로, 요청을 전송하지 않습니다. 갱신이 로그인이 오래되었기 때문이 아니라 계정 자체가 일시 중지되었기 때문에 실패하면, Claude Code는 대신 [계정이 보류 중임](#your-account-is-on-hold)을 표시합니다.1242이것은 [OAuth 토큰이 취소되었거나 만료되었습니다](#oauth-token-revoked-or-expired)와 동일한 상태가 아닙니다. 이러한 메시지는 API가 반환한 거부를 보고합니다. Claude Code 자체는 이미 갱신하지 못한 로그인에 대해 `Login expired`를 생성하므로, 요청을 전송하지 않습니다. 계정 자체가 일시 중단되었기 때문에 갱신이 실패하면, Claude Code는 대신 [계정이 보류 중입니다](#your-account-is-on-hold)를 표시합니다.
1195 1243
1196API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.1244API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.
1197 1245
1198` /status`를 실행하여 요청이 실패하기 전에 이 상태를 확인할 수 있습니다: 로그인 행을 표시하며 `Expired — log in again`을 읽고, 만료된 로그인에 대해 저장한 조직 및 이메일을 표시합니다. 행은 저장된 로그인이 활성 자격증명이고 더 이상 갱신할 수 없을 때만 나타납니다. 다른 방식으로 인증된 세션은 만료된 로그인이 남아 있어도 행을 표시하지 않습니다. v2.1.210 이전에는 `/status`가 이 상태에서 로그인이 존재했던 적이 있다는 표시를 주지 않았습니다. 지워진 자격증명이 보고할 것이 없었기 때문입니다.1246요청이 실패하기 전에 이 상태를 확인할 수 있습니다: [`/status`](/docs/ko/commands)는 `Login` 행을 표시하며 `Expired — log in again`을 읽고, 만료된 로그인에 대해 저장한 조직 및 이메일을 표시합니다. 행은 저장된 로그인이 활성 자격증명이고 더 이상 갱신할 수 없을 때만 나타납니다. 다른 방식으로 인증된 세션은 만료된 로그인이 저장되어 있어도 행을 표시하지 않습니다. v2.1.210 이전에는 `/status`가 이 상태에서 로그인이 존재했던 적이 있다는 표시를 주지 않았습니다. 지워진 자격증명이 보고할 것이 없었기 때문입니다.
1199 1247
1200**수행할 작업:**1248**수행할 작업:**
1201 1249
1202* `/login`을 실행하여 다시 로그인합니다. 로그인하지 않고 재시도하면 모든 요청에서 동일한 메시지가 표시됩니다.1250* `/login`을 실행하여 다시 로그인합니다. 로그인하지 않고 재시도하면 모든 요청에서 동일한 메시지가 표시됩니다.
1203* 비대화형 모드에서 동일한 환경에서 `claude`를 실행하고, `/login`을 완료한 후 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우, `ANTHROPIC_API_KEY` 또는 [`claude setup-token`으로 장기 토큰 생성](/docs/ko/authentication#generate-a-long-lived-token)으로 인증합니다.1251* 비대화형 모드에서는 동일한 환경에서 `claude`를 실행하고, `/login`을 완료한 후 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우, `ANTHROPIC_API_KEY`로 인증하거나 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)으로 장기 토큰을 생성합니다.
1204* 로그인이 계속 실패하면, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하십시오.1252* 로그인이 계속 실패하면, [로그인 및 인증](/docs/ko/troubleshoot-install#login-and-authentication)을 참조합니다.
1253
1254<h3 id="could-not-refresh-your-login">
1255 다른 Claude Code 프로세스가 로그인을 새로 고치고 있어서 로그인을 새로 고칠 수 없습니다
1256</h3>
1257
1258이 메시지는 로그인이 거부되었다는 의미가 아닙니다. 저장된 claude.ai 로그인이 만료되었으며 갱신이 필요했습니다. 동일한 머신의 다른 Claude Code 프로세스가 공유 새로 고침 잠금을 보유했거나, 종료되고 뒤에 남겨두었으며, 이 세션이 기다리는 동안 새로 고침이 진행되지 않았습니다. Claude Code는 전송하기 전에 요청을 중지합니다:
1259
1260```text theme={null}
1261Could 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
1262```
1263
1264[비대화형 모드](/docs/ko/headless)(`-p`) 및 [Agent SDK](/docs/ko/agent-sdk/overview)에서 메시지는 다음과 같이 읽으며, 구조화된 오류 코드는 `server_error`입니다:
1265
1266```text theme={null}
1267Failed 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
1268```
1269
1270API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.
1271
1272**수행할 작업:**
1273
1274* 1분 후에 다시 시도합니다. 다른 프로세스가 먼저 새로 고침을 완료하면, 이 세션이 갱신된 로그인을 사용합니다.
1275* 메시지가 계속 반환되면, 다른 Claude Code 창과 프로세스를 닫은 후 재시도합니다.
1276* 다른 Claude Code 프로세스가 실행 중이지 않은 상태에서 반환되면, `/login`을 실행합니다. 다시 로그인하면 새로 고침 잠금을 기다리지 않습니다.
1277
1278<h3 id="couldnt-save-your-login">
1279 로그인을 저장할 수 없습니다
1280</h3>
1281
1282claude.ai로 로그인했지만 Claude Code가 로그인을 자격증명 저장소에 저장할 수 없어서, 로그인이 완료되지 않았습니다. macOS에서는 예를 들어 절전 또는 유휴 후 로그인 키체인이 잠길 때 발생할 수 있으며, Claude Code가 동일한 세션 중에 이미 자격증명을 읽거나 저장한 후입니다.
1283
1284```text theme={null}
1285Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.
1286Couldn't save your login. Try logging in again.
1287```
1288
1289첫 번째 형식은 macOS에 나타나고 두 번째는 다른 곳에 나타납니다. 시간 초과 또는 읽을 수 없는 저장소와 같은 일시적인 자격증명 저장소 실패는 동일한 메시지를 생성합니다.
1290
1291**수행할 작업:**
1292
1293* macOS에서 로그인 키체인을 잠금 해제한 후 `/login`을 다시 실행합니다.
1294* 다른 플랫폼에서 `/login`을 다시 실행합니다.
1295* 로그인이 여전히 저장되지 않으면, [로그인하지 않음 또는 토큰 만료됨](/docs/ko/troubleshoot-install#not-logged-in-or-token-expired)에서 키체인 잠금 해제 명령 및 기타 자격증명 저장소 복구 단계를 참조합니다.
1296
1297<h3 id="failed-to-start-oauth-callback-server">
1298 Failed to start OAuth callback server
1299</h3>
1300
1301`/login`, `claude auth login` 또는 `claude setup-token`이 브라우저를 통해 로그인할 때, Claude Code는 `127.0.0.1`에서 수신 포트를 열어서 브라우저가 로그인 결과를 반환할 수 있도록 합니다. 이 메시지는 Claude Code가 해당 포트를 열 수 없었으며, 로그인이 브라우저 창 또는 로그인 URL이 나타나기 전에 중지됨을 의미합니다:
1302
1303```text theme={null}
1304Failed to start OAuth callback server: Failed to start server. Is port 0 in use?
1305```
1306
1307메시지가 `Is port 0 in use?`로 끝나면, IPv4 루프백 주소 `127.0.0.1`에서 수신하려는 시도가 완전히 실패했습니다. 실패가 로그인 URL이 존재하기 전에 발생하므로, `Paste code here if prompted` 흐름은 해결책으로 사용할 수 없습니다.
1308
1309**수행할 작업:**
1310
1311* 로컬 리스너 없이 지금 바로 로그인하려면: claude.ai 구독을 사용하면, 로그인이 작동하는 머신에서 [`claude setup-token`](/docs/ko/authentication#generate-a-long-lived-token)을 실행하고 인쇄하는 토큰을 이 머신에서 `CLAUDE_CODE_OAUTH_TOKEN`으로 설정합니다. 그렇지 않으면 [Claude Console](https://platform.claude.com/settings/keys)의 키로 `ANTHROPIC_API_KEY`를 설정합니다. [인증 우선순위](/docs/ko/authentication#authentication-precedence)는 Claude Code가 여러 자격증명 중에서 선택하는 방식을 설명합니다.
1312* 대신 이 머신에서 브라우저 로그인을 사용하려면, Claude Code가 `127.0.0.1`에서 수신할 수 있어야 합니다. 샌드박스 내에서 실행되면, 샌드박스의 정책이 로컬 포트에서 수신하도록 허용하는지 확인한 후 `/login`을 다시 실행합니다. 할 수 있어야 하는데도 여전히 실패하면, `/feedback`을 실행하여 보고서에 환경 세부 정보가 포함되도록 합니다.
1205 1313
1206<h3 id="claude-login-not-accepted">1314<h3 id="claude-login-not-accepted">
1207 Claude 로그인이 수락되지 않음1315 Claude login not accepted
1208</h3>1316</h3>
1209 1317
1210[클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작하려고 시도했고, 서버가 401로 생성을 거부했습니다: 이 머신이 보낸 Claude 로그인을 수락하지 않았습니다. 일반적으로 로그인이 만료되었거나 취소되었기 때문입니다.1318[클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작하려고 했으며, 서버가 401로 생성을 거부했습니다: 이 머신이 전송한 Claude 로그인을 수락하지 않았습니다. 일반적으로 로그인이 만료되었거나 취소되었기 때문입니다.
1211 1319
1212라인의 첫 번째 부분은 서버가 제공할 때 서버의 자체 이유입니다. 그렇지 않으면 라인은 다음과 같이 읽습니다:1320라인의 첫 번째 부분은 서버가 제공할 때 서버 자신의 이유입니다. 그렇지 않으면 라인은 다음과 같이 읽습니다:
1213 1321
1214```text theme={null}1322```text theme={null}
1215Claude login not accepted · Run /login, then try again1323Claude login not accepted · Run /login, then try again
1220* `/login`을 실행하고, 로그인을 완료한 후 세션을 다시 시작합니다.1328* `/login`을 실행하고, 로그인을 완료한 후 세션을 다시 시작합니다.
1221 1329
1222<h3 id="artifacts-need-a-claude-ai-login">1330<h3 id="artifacts-need-a-claude-ai-login">
1223 아티팩트에 claude.ai 로그인이 필요함1331 아티팩트에 claude.ai 로그인이 필요합니다
1224</h3>1332</h3>
1225 1333
1226Claude Code가 [아티팩트](/docs/ko/artifacts) 게시 또는 읽기를 거부했습니다. 세션에 아티팩트에 사용할 수 있는 claude.ai 로그인이 없기 때문입니다.1334Claude Code가 세션에 아티팩트에 사용할 수 있는 claude.ai 로그인이 없어서 [아티팩트](/docs/ko/artifacts) 게시 또는 읽기를 거부했습니다.
1227 1335
1228메시지의 모든 형식은 동일한 단어로 시작하고, 세션이 인증하는 방식에 따라 달라지는 해결책이 뒤따릅니다. 경쟁하는 자격증명이 없으면 다음과 같이 읽습니다:1336메시지의 모든 형식은 동일한 단어로 시작하며, 그 뒤에 세션이 인증하는 방식에 따라 달라지는 해결책이 있습니다. 경쟁하는 자격증명이 없으면 다음과 같이 읽습니다:
1229 1337
1230```text theme={null}1338```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.1339Artifacts 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**수행할 작업:**1342**수행할 작업:**
1235 1343
1236* `/login`을 실행하고 **Claude account with subscription**을 선택합니다. **Anthropic Console account** 옵션은 claude.ai 자격증명을 제공하지 않습니다.1344* `/login`을 실행하고 **Claude account with subscription**을 선택합니다. **Anthropic Console account** 옵션은 claude.ai 자격증명을 제공하지 않습니다.
1237* 메시지가 `ANTHROPIC_API_KEY`, `apiKeyHelper` 설정 또는 이전 `/login`으로 저장된 Console 키와 같이 우선하는 자격증명의 이름을 지정하면, 메시지가 말하는 방식으로 제거한 후 `/login`을 실행합니다.1345* 메시지가 `ANTHROPIC_API_KEY`, `apiKeyHelper` 설정 또는 이전 `/login`으로 저장된 Console 키와 같이 우선순위를 갖는 자격증명의 이름을 지정하면, 메시지가 말하는 방식으로 제거한 후 `/login`을 실행합니다.
1238* 메시지가 이 원격 세션이 이를 실행한 머신을 통해 인증된다고 말하면, 해당 머신에서 claude.ai에 로그인한 후 세션을 다시 연결합니다.1346* 메시지가 이 원격 세션이 이를 실행한 머신을 통해 인증한다고 하면, 해당 머신에서 claude.ai에 로그인한 후 세션을 다시 연결합니다.
1239* 메시지가 자격증명이 세션의 호스트 환경에 의해 주입된다고 말하면, 해당 세션에서 변경할 수 없습니다. claude.ai에 로그인한 세션을 시작합니다.1347* 메시지가 자격증명이 세션의 호스트 환경에 의해 주입된다고 하면, 해당 세션에서 이를 변경할 수 없습니다. claude.ai에 로그인한 세션을 시작합니다.
1240* [가용성](/docs/ko/artifacts#availability)에서 계획, 모델 공급자 및 조직 정책과 같은 아티팩트가 가진 다른 요구 사항을 참조하십시오.1348* 계획, 모델 공급자 및 조직 정책과 같은 아티팩트가 가진 다른 요구 사항은 [가용성](/docs/ko/artifacts#availability)을 참조합니다.
1241 1349
1242<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">1350<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">
1243 관리자 정책에 클라우드 게이트웨이 로그인이 필요함1351 관리자 정책에 Cloud 게이트웨이 로그인이 필요합니다
1244</h3>1352</h3>
1245 1353
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) 로그인만 수락합니다. 두 메시지 중 하나가 표시됩니다:1354관리자의 [관리 설정](/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 1355
1248```text theme={null}1356```text theme={null}
1249Not signed in to the Cloud gateway — run /login.1357Not signed in to the Cloud gateway — run /login.
1251 1359
1252세션에 게이트웨이 로그인이 없을 때 모델 요청이 이 메시지로 실패합니다. 예를 들어 정책이 머신에 도달한 이후 `/login`을 실행하지 않았기 때문입니다.1360세션에 게이트웨이 로그인이 없을 때 모델 요청이 이 메시지로 실패합니다. 예를 들어 정책이 머신에 도달한 이후 `/login`을 실행하지 않았기 때문입니다.
1253 1361
1254`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격증명이 구성되어 있고 관리 설정이 `forceLoginMethod`를 설정하면, Claude Code는 대신 시작 시 다음과 같이 시작하는 메시지로 종료됩니다:1362또한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 자격증명이 구성되어 있고 관리 설정이 `forceLoginMethod`를 설정하면, Claude Code는 대신 시작 시 다음과 같이 시작하는 메시지로 종료됩니다:
1255 1363
1256```text theme={null}1364```text theme={null}
1257Administrator policy requires a Cloud gateway sign-in on this machine; the1365Administrator policy requires a Cloud gateway sign-in on this machine; the
1261 1369
1262**수행할 작업:**1370**수행할 작업:**
1263 1371
1264* `/login`을 실행하고 **클라우드 게이트웨이** 화면에서 로그인을 완료합니다.1372* `/login`을 실행하고 **Cloud gateway** 화면에서 로그인을 완료합니다.
1265* 시작 메시지의 경우, 구성한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 설정을 제거한 후 `claude`를 시작하고 `/login`을 실행합니다.1373* 시작 메시지의 경우, 구성한 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper` 설정을 제거한 후 `claude`를 시작하고 `/login`을 실행합니다.
1266* 머신이 게이트웨이를 요구하지 않아야 한다고 생각하면, 관리자에게 관리 설정에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 제거하도록 요청합니다.1374* 머신이 게이트웨이를 요구하지 않아야 한다고 생각하면, 관리 설정에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 제거하도록 머신을 관리하는 관리자에게 요청합니다.
1267 1375
1268v2.1.265에서는 회귀로 인해 API 키, `apiKeyHelper` 또는 사용자 정의 헤더로 인증하는 일부 LLM 게이트웨이 및 프록시 구성에서도 첫 번째 메시지가 표시되었습니다. 머신에 관리자 요구 사항이 없어도 마찬가지입니다. v2.1.266 이상으로 업그레이드합니다. 구성을 변경할 필요가 없습니다.1376v2.1.265에서는 회귀가 API 키, `apiKeyHelper` 또는 사용자 정의 헤더로 인증하는 일부 LLM 게이트웨이 및 프록시 구성에서도 첫 번째 메시지를 표시했으며, 머신에 관리자 요구 사항이 없었습니다. v2.1.266 이상으로 업데이트합니다. 구성을 변경할 필요가 없습니다.
1269 1377
1270v2.1.261 이전에는 `forceLoginMethod`를 `"gateway"`로 설정한 머신에서 Claude Code가 모델 요청을 실패하는 대신 남은 저장된 로그인을 사용했고, 구성된 환경 자격증명을 시작 메시지 대신 `This machine's managed settings require a first-party login`으로 보고했습니다. v2.1.265 이전에는 관리 설정이 `forceLoginGatewayUrl`만 설정한 머신이 게이트웨이 로그인을 요구하지 않았고, Claude Code가 거기서 남은 자격증명을 사용했습니다.1378v2.1.261 이전에는 `forceLoginMethod`를 `"gateway"`로 설정한 머신에서 Claude Code가 모델 요청을 실패하는 대신 남은 저장된 로그인을 사용했으며, 구성된 환경 자격증명을 `This machine's managed settings require a first-party login` 대신 시작 메시지로 보고했습니다. v2.1.265 이전에는 관리 설정이 `forceLoginGatewayUrl`만 설정한 머신이 게이트웨이 로그인을 요구하지 않았으며, Claude Code가 거기서 남은 자격증명을 사용했습니다.
1271 1379
1272<h3 id="your-account-is-on-hold">1380<h3 id="your-account-is-on-hold">
1273 계정이 보류 중임1381 계정이 보류 중입니다
1274</h3>1382</h3>
1275 1383
1276Claude 계정이 로그인 뒤에 일시 중지되었습니다. Claude Code는 저장된 로그인을 갱신하려고 시도할 때 보류를 알게 되면 첫 번째 메시지를 표시하고, 브라우저에서 완료한 로그인이 이를 보고하면 두 번째 메시지를 표시합니다:1384로그인 뒤의 Claude 계정이 일시 중단되었습니다. Claude Code는 저장된 로그인을 갱신하려고 할 때 보류를 알게 되면 첫 번째 메시지를 표시하고, 브라우저에서 완료한 로그인이 이를 보고하면 두 번째 메시지를 표시합니다:
1277 1385
1278```text theme={null}1386```text theme={null}
1279Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted1387Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
1291 Anthropic 프로필 로그인 만료됨1399 Anthropic 프로필 로그인 만료됨
1292</h3>1400</h3>
1293 1401
1294Claude Code가 저장된 로그인 자격증명이 만료된 Anthropic 자격증명 프로필을 통해 인증하고 있으며, 프로필이 갱신하는 데 사용할 수 있는 새로 고침 자격증명을 보유하지 않습니다. Claude Code는 동일한 만료된 자격증명을 읽을 재시도가 하므로 각 요청을 로컬에서 중지합니다.1402Claude Code가 저장된 로그인 자격증명이 만료된 Anthropic 자격증명 프로필을 통해 인증 중이며, 프로필이 Claude Code가 갱신하는 데 사용할 수 있는 새로 고침 자격증명을 보유하지 않습니다. Claude Code는 동일한 만료된 자격증명을 읽을 재시도가 있으므로 각 요청을 로컬에서 중지합니다.
1295 1403
1296```text theme={null}1404```text theme={null}
1297Anthropic profile login expired · Re-authenticate your Anthropic profile1405Anthropic 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 profile1406Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile
1299```1407```
1300 1408
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`과 같은 베어러 토큰 또는 타사 공급자로 인증된 세션은 이 메시지를 절대 보지 않습니다.1409이것은 활성 자격증명이 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 1410
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가 발견했는지에 따라 달라집니다:1411[키 없는 로그인을 제공](/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 1412
1305* `ANTHROPIC_PROFILE`을 명시적으로 설정하면, 메시지는 `Re-authenticate your Anthropic profile`로 끝납니다.1413* `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` 형식을 표시했습니다.1414* Claude Code가 구성 디렉토리에서 프로필을 발견했으면, 메시지는 `/login`을 제공합니다. Claude Code가 작동하는 `/login`을 발견된 프로필보다 우선순위를 주고 대신 claude.ai 또는 Console 계정으로 인증하기 때문입니다. v2.1.234 이전에는 Claude Code가 이 경우에도 `Re-authenticate your Anthropic profile` 형식을 표시했습니다.
1307 1415
1308**수행할 작업:**1416**수행할 작업:**
1309 1417
1310* 프로필을 다시 인증한 후 재시도합니다: [키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서, 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필의 경우 `/login`을 실행하고 Anthropic Console 계정을 선택합니다. 다른 프로필의 경우, 프로필을 만든 도구를 사용합니다.1418* 프로필에 다시 로그인한 후 재시도합니다: [키 없는 로그인을 제공](/docs/ko/authentication#sign-in-without-an-api-key)하는 머신에서는 키 없는 Console 로그인 또는 Claude Platform CLI의 `ant auth login`이 작성한 프로필의 경우 `/login`을 실행하고 Anthropic Console 계정을 선택합니다. 다른 프로필의 경우, 프로필을 만든 도구를 사용합니다.
1311* 관리자가 프로필의 자격증명을 프로비저닝했으면, 새 자격증명을 발급하도록 요청합니다.1419* 관리자가 프로필의 자격증명을 프로비저닝했으면, 새 자격증명을 발급하도록 요청합니다.
1312* `/status`를 실행하여 활성 자격증명 소스 및 프로필 이름을 확인합니다.1420* `/status`를 실행하여 활성 자격증명 소스 및 프로필 이름을 확인합니다.
1313* 프로필 사용을 중지하려면, 설정했으면 `ANTHROPIC_PROFILE`을 설정 해제한 후 `/login` 또는 `ANTHROPIC_API_KEY`와 같은 다른 방식으로 인증합니다.1421* 프로필 사용을 중지하려면, 설정했으면 `ANTHROPIC_PROFILE`을 설정 해제한 후 `/login` 또는 `ANTHROPIC_API_KEY`와 같은 다른 방식으로 인증합니다.
1316 OAuth 범위 요구 사항1424 OAuth 범위 요구 사항
1317</h3>1425</h3>
1318 1426
1319저장된 토큰이 최신 기능이 필요한 권한 범위보다 앞서 있습니다. 이것은 `/usage` 및 상태 라인 사용 표시기에서 가장 자주 표시됩니다:1427저장된 토큰이 최신 기능이 필요로 하는 권한 범위보다 앞서 있습니다:
1320 1428
1321```text theme={null}1429```text theme={null}
1322OAuth token does not meet scope requirement: user:profile1430OAuth token does not meet scope requirement: user:profile
1327* `/login`을 실행하여 현재 범위가 있는 새 토큰을 가져옵니다. 먼저 로그아웃할 필요가 없습니다.1435* `/login`을 실행하여 현재 범위가 있는 새 토큰을 가져옵니다. 먼저 로그아웃할 필요가 없습니다.
1328 1436
1329<h3 id="claude-ai-rejected-the-session-token">1437<h3 id="claude-ai-rejected-the-session-token">
1330 claude.ai가 세션 토큰을 거부함1438 claude.ai가 세션 토큰을 거부했습니다
1331</h3>1439</h3>
1332 1440
1333[claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) 요청이 실패했습니다. claude.ai가 Claude Code 로그인의 토큰을 거부했습니다. 일반적으로 만료되었고 새로 고칠 수 없는 로그인입니다. 거부된 토큰은 로그인이지, 커넥터의 자체 claude.ai 인증이 아니므로, 커넥터를 다시 인증해도 해결되지 않습니다. `/mcp`에서 커넥터는 `connected · session token rejected`로 표시되고 세부 정보 보기는 다음과 같이 읽습니다:1441[claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) 요청이 실패했습니다. claude.ai가 Claude Code 로그인의 토큰을 거부했습니다. 일반적으로 만료되었거나 새로 고칠 수 없는 로그인입니다. 거부된 토큰은 로그인이며, 커넥터 자신의 claude.ai 인증이 아니므로, 커넥터를 다시 인증해도 해결되지 않습니다. `/mcp`에서 커넥터는 `session token rejected`로 표시되며 세부 정보 보기는 다음과 같이 읽습니다:
1334 1442
1335```text theme={null}1443```text theme={null}
1336claude.ai rejected the session token. Run /login, then reconnect.1444claude.ai rejected the session token. Run /login, then reconnect.
1339**수행할 작업:**1447**수행할 작업:**
1340 1448
1341* `/login`을 실행하여 다시 로그인합니다.1449* `/login`을 실행하여 다시 로그인합니다.
1342* `/mcp`에서 커넥터를 다시 연결하거나, `/mcp reconnect <server>`를 실행합니다. 다시 로그인하기 전에 다시 연결하면 커넥터가 동일한 상태로 유지됩니다. `/mcp` 패널의 **다시 연결** 옵션은 `your claude.ai session token was rejected`를 보고합니다. 입력된 `/mcp reconnect <server>` 형식은 토큰이 여전히 거부되었음에도 불구하고 성공적인 다시 연결을 보고합니다.1450* `/mcp`에서 커넥터를 다시 연결하거나, `/mcp reconnect <server>`를 실행합니다. 다시 로그인하기 전에 다시 연결하면 커넥터가 동일한 상태로 유지됩니다. `/mcp` 패널의 **Reconnect** 옵션은 `your claude.ai session token was rejected`를 보고합니다. 입력된 `/mcp reconnect <server>` 형식은 토큰이 여전히 거부되었음에도 불구하고 성공적인 다시 연결을 보고합니다.
1343 1451
1344v2.1.222 이전에는 Claude Code가 커넥터를 인증이 필요한 것으로 표시했으며, 이는 완료해도 상태를 해결하지 않는 커넥터의 인증 흐름을 가리켰습니다.1452v2.1.222 이전에는 Claude Code가 커넥터를 인증이 필요한 것으로 표시했으며, 이는 완료해도 상태를 해결하지 못하는 커넥터의 인증 흐름을 가리켰습니다.
1345 1453
1346<h3 id="mcp-server-needs-you-to-sign-in-again">1454<h3 id="mcp-server-needs-you-to-sign-in-again">
1347 MCP 서버가 다시 로그인하도록 요청함1455 MCP 서버가 다시 로그인하도록 요청합니다
1348</h3>1456</h3>
1349 1457
1350원격 [MCP 서버](/docs/ko/mcp)가 세션 중에 도구 호출에 대한 자격증명을 거부했습니다. 일반적으로 로그인 또는 토큰이 만료되었거나 취소되었거나 토큰이 도구가 필요한 권한이 부족하기 때문입니다. 도구 호출이 실패하고 `/mcp`는 서버를 [인증이 필요한 것](/docs/ko/mcp#authenticate-with-remote-mcp-servers)으로 표시합니다.1458원격 [MCP 서버](/docs/ko/mcp)가 세션 중에 도구 호출에서 자격증명을 거부했습니다. 일반적으로 로그인 또는 토큰이 만료되었거나 취소되었거나 토큰이 도구가 필요로 하는 권한이 부족합니다. 도구 호출이 실패하고 `/mcp`가 서버를 [인증이 필요한 것](/docs/ko/mcp#authenticate-with-remote-mcp-servers)으로 표시합니다.
1351 1459
1352Claude Code에서 로그인하는 서버(claude.ai 커넥터 포함)의 경우, 로그인이 만료되었거나 취소되었습니다:1460Claude Code에서 로그인하는 서버(claude.ai 커넥터 포함)의 경우, 로그인이 만료되었거나 취소되었습니다:
1353 1461
1357 1465
1358`/mcp`를 실행하고, 서버를 선택하고, 메뉴에서 다시 로그인합니다.1466`/mcp`를 실행하고, 서버를 선택하고, 메뉴에서 다시 로그인합니다.
1359 1467
1360[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 스크립트로 구성된 서버의 경우, Claude Code가 이미 헬퍼를 다시 실행하고 호출을 한 번 재시도한 후 이것을 표시합니다:1468[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication) 스크립트로 구성된 서버의 경우, Claude Code가 이미 헬퍼를 다시 실행하고 표시하기 전에 호출을 한 번 재시도했습니다:
1361 1469
1362```text theme={null}1470```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)1471MCP 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 1473
1366헬퍼가 서버가 수락하는 자격증명을 반환하는지 확인한 후, `/mcp`에서 다시 연결합니다. 이는 헬퍼를 다시 실행합니다.1474헬퍼가 서버가 수락하는 자격증명을 반환하는지 확인한 후, `/mcp`에서 다시 연결합니다. 이는 헬퍼를 다시 실행합니다.
1367 1475
1368구성에 정적 `Authorization` 헤더가 있는 서버의 경우:1476정적 `Authorization` 헤더가 있는 서버의 경우:
1369 1477
1370```text theme={null}1478```text theme={null}
1371MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)1479MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)
1375 1483
1376v2.1.273 이전에는 만료된 로그인, `headersHelper` 및 `Authorization` 헤더 경우가 모두 `MCP server "<name>" requires re-authorization (token expired)`를 표시했습니다.1484v2.1.273 이전에는 만료된 로그인, `headersHelper` 및 `Authorization` 헤더 경우가 모두 `MCP server "<name>" requires re-authorization (token expired)`를 표시했습니다.
1377 1485
1378서버는 HTTP 403 `insufficient_scope`로 도구 호출을 거부하여 범위를 인증하도록 요청할 수도 있습니다. 때로는 토큰이 이미 나열한 범위입니다. 메시지는 해당 범위의 이름을 지정합니다:1486서버는 HTTP 403 `insufficient_scope`로 도구 호출을 거부하여 범위를 요청할 수도 있습니다. 때로는 토큰이 이미 나열한 범위입니다. 메시지는 해당 범위의 이름을 지정합니다:
1379 1487
1380```text theme={null}1488```text theme={null}
1381MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate1489MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate
1385 1493
1386서버의 구성이 [`oauth.scopes`](/docs/ko/mcp#restrict-oauth-scopes) 또는 [`authServerMetadataUrl`](/docs/ko/mcp#override-oauth-metadata-discovery)을 설정하지 않으면, Claude Code가 서버가 이름을 지정한 범위를 요청합니다. 어느 설정이든 Claude Code가 해당 설정의 범위를 요청합니다. `oauth.scopes`를 고정했으면, 다시 인증하기 전에 누락된 범위를 해당 목록에 추가합니다.1494서버의 구성이 [`oauth.scopes`](/docs/ko/mcp#restrict-oauth-scopes) 또는 [`authServerMetadataUrl`](/docs/ko/mcp#override-oauth-metadata-discovery)을 설정하지 않으면, Claude Code가 서버가 이름을 지정한 범위를 요청합니다. 어느 설정이든 Claude Code가 해당 설정의 범위를 요청합니다. `oauth.scopes`를 고정했으면, 다시 인증하기 전에 누락된 범위를 해당 목록에 추가합니다.
1387 1495
1388v2.1.274 이전에는 이 경우가 `needs you to sign in again` 메시지를 표시했고, v2.1.273 이전에는 다른 경우처럼 `requires re-authorization (token expired)`를 표시했습니다.1496v2.1.274 이전에는 이 경우가 `needs you to sign in again` 메시지를 표시했으며, v2.1.273 이전에는 다른 경우처럼 `requires re-authorization (token expired)`를 표시했습니다.
1389 1497
1390<h3 id="issuer-mismatch-in-authorization-response">1498<h3 id="issuer-mismatch-in-authorization-response">
1391 인증 응답의 발급자 불일치1499 인증 응답의 발급자 불일치
1397Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"1505Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"
1398```1506```
1399 1507
1400`expected`는 서버의 OAuth 메타데이터의 발급자이고, `received`는 리디렉션이 전달한 `iss` 값입니다. 리디렉션이 `iss` 매개변수를 전달하지 않는 로그인은 확인을 통과합니다. 서버의 메타데이터가 `authorization_response_iss_parameter_supported`를 설정하지 않으면, 이 경우 Claude Code는 로그인을 실패합니다.1508`expected`는 서버의 OAuth 메타데이터의 발급자이며, `received`는 리디렉션이 전달한 `iss` 값입니다. `iss` 매개변수를 전달하지 않는 로그인은 확인을 통과합니다. 서버의 메타데이터가 `authorization_response_iss_parameter_supported`를 설정하지 않으면, 이 경우 Claude Code는 로그인을 실패합니다.
1401 1509
1402**수행할 작업:**1510**수행할 작업:**
1403 1511
1404* `/mcp`에서 로그인을 다시 시도합니다.1512* `/mcp`에서 로그인을 다시 시도합니다.
1405* 오류가 반복되면, 서버 운영자에게 보고합니다. 수정은 서버 측입니다: 인증 서버는 메타데이터에서 광고하는 것과 동일한 발급자를 `iss` 매개변수에서 반환해야 합니다.1513* 오류가 반복되면, 서버 운영자에게 보고합니다. 수정은 서버 측입니다: 인증 서버는 메타데이터에서 광고하는 것과 동일한 발급자를 `iss` 매개변수에서 반환해야 합니다.
1406* 서버가 수정되는 동안 연결하려면, [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 이 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 확인을 실행하지 않습니다. 이는 혼합 공격에 대한 보호를 제거하므로 서버 측 수정을 선호합니다.1514* 서버가 수정되는 동안 연결하려면, [`MCP_SDK_GENERATION=v1`](/docs/ko/env-vars)로 Claude Code를 시작합니다. 해당 [런타임](/docs/ko/mcp#mcp-client-runtimes)은 이 확인을 실행하지 않습니다. 이것은 혼합 공격에 대한 보호를 제거하므로 서버 측 수정을 선호합니다.
1407 1515
1408v2.1.232 이전에는 Claude Code가 점진적 롤아웃에서만 또는 `MCP_SDK_GENERATION=v2`를 설정할 때 v2 런타임을 사용했습니다.1516v2.1.232 이전에는 Claude Code가 점진적 롤아웃에서만 v2 런타임을 사용했거나 `MCP_SDK_GENERATION=v2`를 설정했을 때 사용했습니다.
1409 1517
1410<h3 id="aws-credentials-expired-or-invalid">1518<h3 id="aws-credentials-expired-or-invalid">
1411 AWS 자격증명이 만료되었거나 유효하지 않음1519 AWS 자격증명이 만료되었거나 유효하지 않습니다
1412</h3>1520</h3>
1413 1521
1414AWS 세션 토큰이 만료되었거나 거부되었습니다. 이 메시지는 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)의 401에 나타나며, 이는 해당 공급자가 만료된 보안 토큰을 보고하는 방법입니다.1522AWS 세션 토큰이 만료되었거나 거부되었습니다. 이 메시지는 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)에서 401로 나타나며, 이는 해당 공급자가 만료된 보안 토큰을 보고하는 방식입니다.
1415 1523
1416중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `AWS credentials expired or invalid`입니다:1524중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `AWS credentials expired or invalid`입니다:
1417 1525
1423 1531
1424**수행할 작업:**1532**수행할 작업:**
1425 1533
1426* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1534* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1427* [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)가 설정되면, 메시지에서 이름을 지정한 명령(예: `aws sso login --profile myprofile`)을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 후 재시도합니다. 그렇지 않으면 직접 사용하는 AWS 자격증명을 새로 고칩니다: SSO 로그인, 액세스 키, API 키 또는 프록시 토큰1535* [`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)을 참조하십시오.1536* `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가 유효한지 확인합니다.1537* 새로 고침 명령이 성공한 후에도 오류가 반복되면, 동일한 셸 및 프로필에서 `aws sts get-caller-identity`로 Claude Code 외부에서 ID가 유효한지 확인합니다.
1430 1538
1431<h3 id="aws-authentication-failed">1539<h3 id="aws-authentication-failed">
1432 AWS 인증 실패1540 AWS 인증 실패
1434 1542
1435AWS 공급자가 403을 반환했거나, [Amazon Bedrock](/docs/ko/amazon-bedrock)이 401을 반환했습니다.1543AWS 공급자가 403을 반환했거나, [Amazon Bedrock](/docs/ko/amazon-bedrock)이 401을 반환했습니다.
1436 1544
1437Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 403은 또한 누락된 IAM 권한과 같은 `AccessDeniedException`의 인증 거부를 보고하는 방법입니다. Claude Code는 이 두 원인을 구분할 수 없습니다.1545Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 403은 또한 누락된 IAM 권한과 같은 `AccessDeniedException`의 인증 거부를 보고하는 방식입니다. Claude Code는 이 두 원인을 구분할 수 없습니다.
1438 1546
1439Amazon Bedrock의 401은 또한 [AWS 자격증명이 만료되었거나 유효하지 않음](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. Amazon Bedrock이 만료된 토큰을 401로 보고하지 않기 때문입니다. 해당 엔드포인트의 401은 일반적으로 요청 경로의 다른 것(예: 회사 프록시)에서 옵니다.1547Amazon Bedrock의 401은 [AWS 자격증명이 만료되었거나 유효하지 않습니다](#aws-credentials-expired-or-invalid) 아래가 아닌 여기에 도달합니다. 해당 엔드포인트의 401은 일반적으로 요청 경로의 다른 것(예: 회사 프록시)에서 옵니다.
1440 1548
1441자격증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로, 메시지는 둘 다 제공합니다:1549자격증명 새로 고침은 만료된 토큰을 수정하고 다른 원인을 수정할 수 없으므로, 메시지는 둘 다 제공합니다:
1442 1550
1452 1560
1453**수행할 작업:**1561**수행할 작업:**
1454 1562
1455* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1563* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1456* 만료된 자격증명이 원인일 수 있으므로 AWS 자격증명을 새로 고칩니다: 설정되면 [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)에서 이름을 지정한 명령을 실행하거나, SSO 로그인, 액세스 키, API 키 또는 프록시 토큰을 직접 새로 고칩니다.1564* 만료된 자격증명이 원인일 수 있으므로 AWS 자격증명을 새로 고칩니다: 설정되면 [`awsAuthRefresh`](/docs/ko/amazon-bedrock#advanced-credential-configuration)에서 이름을 지정한 명령을 실행하거나, SSO 로그인, 액세스 키, API 키 또는 프록시 토큰을 직접 새로 고칩니다.
1457* 자격증명이 최신이면, [IAM 구성](/docs/ko/amazon-bedrock#iam-configuration)의 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.1565* 자격증명이 현재이면, [IAM 구성](/docs/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.
1458* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.1566* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다.
1459 1567
1460<h3 id="google-cloud-credentials-expired-or-invalid">1568<h3 id="google-cloud-credentials-expired-or-invalid">
1461 Google Cloud 자격증명이 만료되었거나 유효하지 않음1569 Google Cloud 자격증명이 만료되었거나 유효하지 않습니다
1462</h3>1570</h3>
1463 1571
1464[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)의 Google Cloud 자격증명이 만료되었거나 거부되었습니다: 요청이 401을 반환했으며, 이는 Agent Platform이 자격증명 만료를 보고하는 방법입니다.1572[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)에 대한 Google Cloud 자격증명이 만료되었거나 거부되었습니다: 요청이 401을 반환했으며, 이는 Agent Platform이 자격증명 만료를 보고하는 방식입니다.
1465 1573
1466중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud credentials expired or invalid`입니다:1574중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud credentials expired or invalid`입니다:
1467 1575
1471 1579
1472**수행할 작업:**1580**수행할 작업:**
1473 1581
1474* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1582* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1475* 애플리케이션 기본 자격증명으로 인증하면, 메시지에서 이름을 지정한 [`gcpAuthRefresh`](/docs/ko/google-vertex-ai#advanced-credential-configuration) 명령 또는 `gcloud auth application-default login`을 실행하고 로그인을 완료한 후 재시도합니다.1583* 애플리케이션 기본 자격증명으로 인증하면, 메시지에서 이름을 지정한 [`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`의 게이트웨이 토큰을 새로 고친 후 재시도합니다.1584* `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)을 참조하십시오.1585* 서비스 계정 키 파일로 인증하면, `GOOGLE_APPLICATION_CREDENTIALS`가 유효한 키를 가리키는지 확인합니다. [GCP 자격증명 구성](/docs/ko/google-vertex-ai#3-configure-gcp-credentials)을 참조합니다.
1478* 새로 고침 후 오류가 반복되면, 동일한 셸에서 `gcloud auth application-default print-access-token`으로 Claude Code 외부에서 ID가 작동하는지 확인합니다.1586* 새로 고침 후에도 오류가 반복되면, 동일한 셸에서 `gcloud auth application-default print-access-token`으로 Claude Code 외부에서 ID가 작동하는지 확인합니다.
1479 1587
1480v2.1.273 이전에는 Agent Platform의 401이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, Google Cloud 자격증명을 새로 고칠 수 없습니다.1588v2.1.273 이전에는 Agent Platform의 401이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.
1481 1589
1482<h3 id="google-cloud-authentication-failed">1590<h3 id="google-cloud-authentication-failed">
1483 Google Cloud 인증 실패1591 Google Cloud 인증 실패
1484</h3>1592</h3>
1485 1593
1486[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)이 403을 반환했으며, 이는 만료된 자격증명이 아닌 인증 거부에 사용합니다. 일반적으로 인증하는 ID에 IAM 권한이 누락되었거나 모델이 프로젝트에 대해 활성화되지 않았습니다.1594[Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai)이 403을 반환했으며, 이는 만료된 자격증명이 아닌 인증 거부에 사용합니다. 일반적으로 인증하는 ID에 IAM 권한이 부족하거나, 모델이 프로젝트에 대해 활성화되지 않았습니다.
1487 1595
1488중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud authentication failed`입니다:1596중간의 작업 힌트는 설정에 따라 달라집니다. 안정적인 부분은 선행 `Google Cloud authentication failed`입니다:
1489 1597
1493 1601
1494**수행할 작업:**1602**수행할 작업:**
1495 1603
1496* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1604* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1497* [IAM 구성](/docs/ko/google-vertex-ai#iam-configuration)의 역할이 인증하는 ID에 부여되었는지 확인합니다.1605* [IAM 구성](/docs/ko/google-vertex-ai#iam-configuration)의 역할이 인증하는 ID에 부여되어 있는지 확인합니다.
1498* 모델이 프로젝트에 대해 활성화되었는지 확인합니다. [모델 액세스 요청](/docs/ko/google-vertex-ai#2-request-model-access)을 참조하십시오.1606* 모델이 프로젝트에 대해 활성화되어 있는지 확인합니다. [모델 액세스 요청](/docs/ko/google-vertex-ai#2-request-model-access)을 참조합니다.
1499 1607
1500v2.1.273 이전에는 Agent Platform의 403이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, Google Cloud 자격증명을 새로 고칠 수 없습니다.1608v2.1.273 이전에는 Agent Platform의 403이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.
1501 1609
1502<h3 id="microsoft-foundry-authentication-failed">1610<h3 id="microsoft-foundry-authentication-failed">
1503 Microsoft Foundry 인증 실패1611 Microsoft Foundry 인증 실패
1511 1619
1512**수행할 작업:**1620**수행할 작업:**
1513 1621
1514* 힌트가 자격증명이 이 환경에서 관리된다고 말하면, 앱이 Claude Code를 실행하고 여기의 다른 단계가 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.1622* 힌트가 자격증명이 이 환경에서 관리된다고 하면, 이를 실행한 앱이 자격증명을 소유하며 여기의 다른 단계는 적용되지 않습니다: 재시도하거나, 관리자에게 문의합니다.
1515* [Azure 자격증명 구성](/docs/ko/microsoft-foundry#2-configure-azure-credentials)에서 구성한 자격증명을 새로 고칩니다: `ANTHROPIC_FOUNDRY_API_KEY`를 회전하거나, 새 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`을 발급하거나, `az login`을 실행하여 기본 Microsoft Entra 자격증명 체인이 다시 로그인할 수 있도록 합니다.1623* [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)을 참조하십시오.1624* 자격증명이 현재이면, ID가 Foundry 리소스에 액세스할 수 있는지 확인합니다. [Azure RBAC 구성](/docs/ko/microsoft-foundry#azure-rbac-configuration)을 참조합니다.
1517 1625
1518v2.1.273 이전에는 Microsoft Foundry의 401 또는 403이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, Azure 자격증명을 새로 고칠 수 없습니다.1626v2.1.273 이전에는 Microsoft Foundry의 401 또는 403이 자격증명을 새로 고칠 수 없는 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했습니다.
1519 1627
1520<h3 id="could-not-load-aws-or-google-cloud-credentials">1628<h3 id="could-not-load-aws-or-google-cloud-credentials">
1521 AWS 또는 Google Cloud 자격증명을 로드할 수 없음1629 AWS 또는 Google Cloud 자격증명을 로드할 수 없습니다
1522</h3>1630</h3>
1523 1631
1524Claude Code가 실행되는 머신의 AWS 자격증명 공급자 체인 또는 Google 애플리케이션 기본 자격증명에서 사용 가능한 자격증명을 얻을 수 없으므로, 클라우드 공급자에 도달한 요청이 없습니다. Claude Code는 캐시된 자격증명을 지우고 이 메시지를 표시하기 전에 두 번 재시도합니다. `·` 이후의 세부 정보는 만료된 SSO 세션, `Could not load the default credentials`로 보고된 누락된 애플리케이션 기본 자격증명 또는 `invalid_grant`로 보고된 취소된 로그인과 같은 특정 원인의 이름을 지정합니다:1632Claude Code가 AWS 자격증명 공급자 체인 또는 머신의 Google 애플리케이션 기본 자격증명에서 사용 가능한 자격증명을 얻을 수 없어서, 요청이 클라우드 공급자에 도달하지 않았습니다. Claude Code는 캐시된 자격증명을 지우고 표시하기 전에 두 번 재시도합니다. `·` 이후의 세부 정보는 만료된 SSO 세션, `Could not load the default credentials`로 보고된 누락된 애플리케이션 기본 자격증명 또는 `invalid_grant`로 보고된 취소된 로그인과 같은 특정 원인의 이름을 지정합니다:
1525 1633
1526```text theme={null}1634```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.1635API 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.1636API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.
1529```1637```
1530 1638
1531[비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하고 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `cloud_credential_error`입니다. v2.1.267 이전에는 메시지가 `API Error:` 이후의 세부 정보 텍스트만 표시했고, 구조화된 코드는 `server_error` 또는 `unknown`이었습니다.1639[비대화형 모드](/docs/ko/headless)에서 `-p`와 [Agent SDK](/docs/ko/agent-sdk/overview)에서 구조화된 오류 코드는 `cloud_credential_error`입니다. v2.1.267 이전에는 메시지가 `API Error:` 이후의 세부 정보만 표시했으며, 구조화된 코드는 `server_error` 또는 `unknown`이었습니다.
1532 1640
1533**수행할 작업:**1641**수행할 작업:**
1534 1642
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 외부에서 자격증명을 확인하는 방법을 보여줍니다.1643* `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)를 따릅니다.1644* 세부 정보가 `AWS default-chain credential resolve timed out`을 읽으면, 체인이 실패하지 않고 중단되었으므로, 대신 [AWS default-chain credential resolve timed out](#aws-default-chain-credential-resolve-timed-out)을 따릅니다.
1537 1645
1538<h3 id="aws-default-chain-credential-resolve-timed-out">1646<h3 id="aws-default-chain-credential-resolve-timed-out">
1539 AWS 기본 체인 자격증명 확인 시간 초과1647 AWS default-chain credential resolve timed out
1540</h3>1648</h3>
1541 1649
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)를 지우고 재시도하므로, 이 시점에서 체인이 반복된 시도에서 중단되었습니다.1650AWS 기본 자격증명 공급자 체인이 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 1651
1544```text theme={null}1652```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.1653API 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)가 체인의 프로브에 응답하지 않습니다.1656일반적인 원인은 AWS 프로필의 `credential_process` 명령이 받을 수 없는 입력을 기다리고 있으며, 컨테이너 또는 VM의 인스턴스 메타데이터 서비스(IMDS)가 체인의 프로브에 응답하지 않습니다.
1549 1657
1550v2.1.267 이전에는 메시지가 `API Error: AWS default-chain credential resolve timed out`을 읽었습니다.1658v2.1.267 이전에는 메시지가 `API Error: AWS default-chain credential resolve timed out`을 읽었습니다.
1551v2.1.207 이전에는 중단된 체인이 요청을 무한정 기다리게 했습니다.1659v2.1.207 이전에는 중단된 체인이 실패하는 대신 요청을 무한정 기다리게 했습니다.
1552 1660
1553**수행할 작업:**1661**수행할 작업:**
1554 1662
1555* 동일한 셸에서 동일한 `AWS_PROFILE`로 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 프로필을 수정합니다. 대화형으로 프롬프트하는 `credential_process` 명령이 일반적인 원인입니다.1663* 동일한 셸에서 동일한 `AWS_PROFILE`로 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 프로필을 수정합니다. 대화형으로 프롬프트하는 `credential_process` 명령이 일반적인 원인입니다.
1556* Claude Code를 시작하기 전에 로그인 단계를 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행하여 체인이 로컬 SSO 캐시에서 확인되도록 합니다.1664* 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)에서 밀리초 단위로 제한을 높입니다.1665* 체인이 `aws-vault`와 같은 래퍼를 통해 MFA가 있는 SSO와 같이 60초 이상 필요로 하는 대화형 로그인을 실행하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.
1558 1666
1559<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">1667<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">
1560 Bedrock 설정 확인이 AWS를 기다리다가 시간 초과됨1668 Bedrock 설정 확인이 AWS를 기다리다가 시간 초과되었습니다
1561</h3>1669</h3>
1562 1670
1563[Bedrock 설정 마법사](/docs/ko/amazon-bedrock#sign-in-with-bedrock)의 자격증명 확인 중 AWS 호출(예: 자격증명 조회 또는 ID 확인)이 60초 제한 내에 완료되지 않았습니다. 마법사가 기다리기를 중지하고 확인 단계를 실패합니다:1671[Bedrock 설정 마법사](/docs/ko/amazon-bedrock#sign-in-with-bedrock)의 자격증명 확인 중 AWS에 대한 호출(예: 자격증명 조회 또는 ID 확인)이 60초 제한 내에 완료되지 않았습니다. 마법사가 기다리기를 중지하고 확인 단계를 실패합니다:
1564 1672
1565```text theme={null}1673```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.1674Timed 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 1676
1569숫자는 제한을 반영합니다: 기본적으로 60초 또는 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 설정한 값입니다.1677숫자는 제한을 반영합니다: 기본적으로 60초 또는 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 설정한 값입니다.
1570 1678
1571일반적인 원인은 AWS에 대한 요청을 중단하는 네트워크 또는 프록시(SSO 토큰 새로 고침 포함) 및 입력을 기다리는 자격증명 헬퍼입니다. 헬퍼가 합법적으로 더 많은 시간이 필요한 경우에만 제한을 높입니다.1679일반적인 원인은 SSO 토큰 새로 고침을 포함하여 AWS에 대한 요청을 중단하는 네트워크 또는 프록시이며, 자격증명 헬퍼가 볼 수 없는 입력을 기다리고 있습니다. 헬퍼가 합법적으로 더 많은 시간이 필요할 때만 제한을 높입니다.
1572 1680
1573AWS에 대한 단일 중단된 요청도 자체 요청별 시간 초과에서 실패할 수 있으며, 동일한 단계에서 더 짧은 메시지를 표시합니다:1681AWS에 대한 단일 중단된 요청도 자체 요청별 시간 초과로 실패할 수 있으며, 동일한 단계에서 더 짧은 메시지를 표시합니다:
1574 1682
1575```text theme={null}1683```text theme={null}
1576A request to AWS timed out. Check your network and proxy settings, then try again.1684A request to AWS timed out. Check your network and proxy settings, then try again.
1577```1685```
1578 1686
1579동일한 시간 초과가 모델 핀 단계에서 발생하면, 마법사는 모델을 `unreachable`로 표시하는 대신 두 메시지 중 하나를 표시합니다.1687동일한 시간 초과가 모델 핀 단계에서 발생하면, 마법사가 메시지를 표시하는 대신 모델을 `unreachable`로 표시합니다.
1580 1688
1581**수행할 작업:**1689**수행할 작업:**
1582 1690
1583* 동일한 셸에서 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 중단이 Claude Code 외부에 있습니다. 네트워크, 프록시 또는 AWS 프로필의 자격증명 헬퍼에서 먼저 수정합니다.1691* 동일한 셸에서 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면, 중단이 Claude Code 외부에 있습니다. 네트워크, 프록시 또는 AWS 프로필의 자격증명 헬퍼에서 먼저 수정합니다.
1584* 마법사를 열기 전에 대화형 로그인을 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행합니다.1692* 마법사를 열기 전에 대화형 로그인을 완료합니다. 예를 들어 `aws sso login --profile myprofile`을 실행합니다.
1585* AWS 프로필의 자격증명 헬퍼가 합법적으로 60초 이상 필요하여 프롬프트하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.1693* AWS 프로필의 자격증명 헬퍼가 합법적으로 60초 이상 프롬프트를 기다려야 하면, [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ko/env-vars)에서 밀리초 단위로 제한을 높입니다.
1586 1694
1587<h3 id="cloud-gateway-session-expired">1695<h3 id="cloud-gateway-session-expired">
1588 클라우드 게이트웨이 세션 만료됨1696 클라우드 게이트웨이 세션 만료됨
1589</h3>1697</h3>
1590 1698
1591[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했고, 이 머신에 저장된 게이트웨이 세션이 만료되었고 갱신할 수 없거나, 게이트웨이가 더 이상 수락하지 않습니다. 예를 들어 게이트웨이의 [JWT 비밀이 교체된](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation) 후입니다. 대화형으로 `claude`를 시작할 때 이 라인이 표시되면, 세션이 게이트웨이에서 로그아웃된 상태로 열렸습니다:1699[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했으며, 이 머신에 저장된 게이트웨이 세션이 만료되었으며 갱신할 수 없거나, 게이트웨이가 더 이상 수락하지 않습니다. 예를 들어 게이트웨이의 [JWT 비밀이 교체된](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation) 후입니다. 대화형으로 `claude`를 시작할 때 이 라인을 보면, 세션이 게이트웨이에서 로그아웃된 상태로 열렸습니다:
1592 1700
1593```text theme={null}1701```text theme={null}
1594Cloud gateway session expired — run /login to reconnect.1702Cloud gateway session expired — run /login to reconnect.
1595```1703```
1596 1704
1597동일한 라인은 게이트웨이 자격증명이 만료되고 Claude Code가 갱신할 수 없을 때 세션 중에 나타날 수 있습니다.1705동일한 라인이 게이트웨이 자격증명이 만료되고 Claude Code가 갱신할 수 없을 때 세션 중에 나타날 수 있습니다.
1598 1706
1599[비대화형](/docs/ko/headless) 실행, 백그라운드 또는 기타 무인 세션 또는 `claude auth` 이외의 `claude` 하위 명령에서, 게이트웨이가 더 이상 세션을 수락하지 않으면 Claude Code는 대신 이 메시지로 종료됩니다:1707[비대화형](/docs/ko/headless) 실행, 백그라운드 또는 기타 무인 세션 또는 `claude auth` 이외의 `claude` 하위 명령에서, Claude Code는 게이트웨이가 더 이상 세션을 수락하지 않을 때 대신 이 메시지로 종료됩니다:
1600 1708
1601```text theme={null}1709```text theme={null}
1602Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.1710Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.
1608* 비대화형 실행의 경우, 동일한 환경에서 `claude`를 시작하고, `/login`을 실행한 후 명령을 다시 실행합니다.1716* 비대화형 실행의 경우, 동일한 환경에서 `claude`를 시작하고, `/login`을 실행한 후 명령을 다시 실행합니다.
1609 1717
1610<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">1718<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">
1611 로그인 시간 초과 중 계속 대기1719 로그인이 계속하기를 기다리다가 시간 초과되었습니다
1612</h3>1720</h3>
1613 1721
1614[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 로그인 중에 게이트웨이가 로그인한 계정의 이름을 지정했고, Claude Code가 저장하기 전에 확인하도록 요청했습니다. 로그인의 자체 만료를 지나 확인을 열어 두었고, 게이트웨이가 새로 고침 토큰을 발급하지 않았으므로, Claude Code는 계속할 때 아무것도 저장하지 않았습니다:1722[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway) 로그인 중에 게이트웨이가 로그인한 계정의 이름을 지정했으며, Claude Code가 자격증명을 저장하기 전에 확인하도록 요청했습니다. 로그인 자신의 만료를 지나 확인을 열어 두었으며, 게이트웨이가 갱신할 수 있는 새로 고침 토큰을 발급하지 않았으므로, Claude Code가 계속할 때 아무것도 저장하지 않았습니다:
1615 1723
1616```text theme={null}1724```text theme={null}
1617Sign-in timed out while waiting for you to continue. Try again.1725Sign-in timed out while waiting for you to continue. Try again.
1622* `/login`을 다시 실행하고 로그인이 만료되기 전에 계정을 확인합니다.1730* `/login`을 다시 실행하고 로그인이 만료되기 전에 계정을 확인합니다.
1623 1731
1624<h3 id="gateway-refused-the-request">1732<h3 id="gateway-refused-the-request">
1625 게이트웨이가 요청을 거부함1733 게이트웨이가 요청을 거부했습니다
1626</h3>1734</h3>
1627 1735
1628[Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했고, 요청이 403을 반환했습니다: 게이트웨이 또는 뒤의 업스트림이 거부했습니다. 다시 로그인하면 거부가 변경되지 않으므로, 메시지는 게이트웨이 관리자를 가리킵니다:1736[Claude apps 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인했으며, 요청이 403을 반환했습니다: 게이트웨이 또는 뒤의 업스트림이 거부했습니다. 다시 로그인하면 거부가 변경되지 않으므로, 메시지는 게이트웨이 관리자를 가리킵니다:
1629 1737
1630```text theme={null}1738```text theme={null}
1631Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...1739Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...
1634**수행할 작업:**1742**수행할 작업:**
1635 1743
1636* 게이트웨이 관리자에게 요청을 조회하도록 요청합니다. `API Error:` 꼬리는 게이트웨이가 반환한 거부를 전달합니다.1744* 게이트웨이 관리자에게 요청을 조회하도록 요청합니다. `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)에 따라 통과합니다.1745* 관리자의 경우: 게이트웨이의 [액세스 제어 규칙](/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 1746
1639v2.1.273 이전에는 게이트웨이 세션의 403이 대신 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했고, 다시 로그인해도 거부가 지워지지 않았습니다.1747v2.1.273 이전에는 게이트웨이 세션의 403이 일반적인 `Please run /login` 또는 `Failed to authenticate` 메시지를 표시했으며, 다시 로그인해도 거부가 지워지지 않았습니다.
1640 1748
1641<h2 id="network-and-connection-errors">1749<h2 id="network-and-connection-errors">
1642 네트워크 및 연결 오류1750 네트워크 및 연결 오류
1657No internet route — check your connection or VPN (EHOSTUNREACH)1765No internet route — check your connection or VPN (EHOSTUNREACH)
1658Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host1766Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
1659Connection dropped (ECONNRESET)1767Connection dropped (ECONNRESET)
1660fetch failed
1661Request timed out. Check your internet connection and proxy settings1768Request timed out. Check your internet connection and proxy settings
1662```1769```
1663 1770
1677 1784
1678`curl`이 성공하지만 Claude Code가 여전히 실패하는 경우, 원인은 일반적으로 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다:1785`curl`이 성공하지만 Claude Code가 여전히 실패하는 경우, 원인은 일반적으로 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다:
1679 1786
1787* `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은 호스트에서 손상된 리졸버를 상속할 수 있습니다.1788* Linux 및 WSL에서 `/etc/resolv.conf`에서 도달할 수 없는 네임서버를 확인합니다. 특히 WSL은 호스트에서 손상된 리졸버를 상속할 수 있습니다.
1681* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.1789* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.
1682* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 배제하기 위해 종료하고 다시 시도합니다.1790* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 배제하기 위해 종료하고 다시 시도합니다.
1702 1810
1703* 메시지가 프록시 변수의 이름을 지정하는 경우, 해당 값이 올바른 프록시를 가리키는지 확인하고 네트워크 팀에 메시지의 호스트에 대한 HTTPS 연결을 허용하도록 요청합니다. [네트워크 구성](/docs/ko/network-config)을 참조합니다.1811* 메시지가 프록시 변수의 이름을 지정하는 경우, 해당 값이 올바른 프록시를 가리키는지 확인하고 네트워크 팀에 메시지의 호스트에 대한 HTTPS 연결을 허용하도록 요청합니다. [네트워크 구성](/docs/ko/network-config)을 참조합니다.
1704* [API에 연결할 수 없음](#unable-to-connect-to-api)의 확인을 진행합니다. 거기의 `curl` 테스트 및 방화벽 지침이 이 확인에도 적용됩니다.1812* [API에 연결할 수 없음](#unable-to-connect-to-api)의 확인을 진행합니다. 거기의 `curl` 테스트 및 방화벽 지침이 이 확인에도 적용됩니다.
1705* 조직이 [클라우드 게이트웨이](/docs/ko/claude-apps-gateway)를 통해 로그인하고 이 오류가 첫 실행에 나타나는 경우, Claude Code v2.1.247 이상으로 업데이트합니다.
1706* 네트워크가 열려 있고 실패가 지속되는 경우, Claude Code가 [귀국에서 사용 가능하지 않을 수 있습니다](https://www.anthropic.com/supported-countries).1813* 네트워크가 열려 있고 실패가 지속되는 경우, Claude Code가 [귀국에서 사용 가능하지 않을 수 있습니다](https://www.anthropic.com/supported-countries).
1707 1814
1708<h3 id="socket-is-closed">1815<h3 id="socket-is-closed">
1744* `Response:` 절을 읽어 어느 시스템이 응답했는지 확인합니다. HTML 본문, Anthropic 요청 ID 없음, 또는 `nginx` 또는 `cloudflare`와 같은 명명된 서버는 Claude Code와 API 사이의 무언가가 대신 응답했음을 의미합니다.1851* `Response:` 절을 읽어 어느 시스템이 응답했는지 확인합니다. HTML 본문, Anthropic 요청 ID 없음, 또는 `nginx` 또는 `cloudflare`와 같은 명명된 서버는 Claude Code와 API 사이의 무언가가 대신 응답했음을 의미합니다.
1745* [LLM 게이트웨이](/docs/ko/llm-gateway-connect#troubleshoot-gateway-errors)를 통해 라우팅하는 경우, 직접 요청으로 경로를 테스트하고 비 API 응답을 반환하는 홉을 수정합니다.1852* [LLM 게이트웨이](/docs/ko/llm-gateway-connect#troubleshoot-gateway-errors)를 통해 라우팅하는 경우, 직접 요청으로 경로를 테스트하고 비 API 응답을 반환하는 홉을 수정합니다.
1746* 게스트 Wi-Fi와 같은 로그인 페이지가 있는 네트워크에서 브라우저에서 로그인을 완료한 다음 다시 시도합니다.1853* 게스트 Wi-Fi와 같은 로그인 페이지가 있는 네트워크에서 브라우저에서 로그인을 완료한 다음 다시 시도합니다.
1747* 게이트웨이를 통한 비스트리밍 경로만 손상된 경우, [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`](/docs/ko/env-vars#variables)을 설정하여 스트림 중간에 실패한 요청이 스트리밍 엔드포인트 자체가 `404`를 반환할 때를 제외하고 일반 재시도 경로로 이동하도록 합니다. 여기서 Claude Code는 여전히 폴백합니다.1854* 게이트웨이를 통한 비스트리밍 경로만 손상된 경우, [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`](/docs/ko/env-vars#variables)을 설정하여 스트리밍 엔드포인트 자체가 `404`를 반환할 때를 제외하고 이 폴백을 끕니다. 여기서 Claude Code는 여전히 폴백합니다.
1748 1855
1749<h3 id="streaming-response-ended-before-any-complete-data-was-received">1856<h3 id="streaming-response-ended-before-any-complete-data-was-received">
1750 스트리밍 응답이 완전한 데이터를 받기 전에 종료됨1857 스트리밍 응답이 완전한 데이터를 받기 전에 종료됨
1897* `claude --remote-control`로 새 세션을 시작하여 새 Remote Control 세션을 만듭니다.2004* `claude --remote-control`로 새 세션을 시작하여 새 Remote Control 세션을 만듭니다.
1898* 다른 Remote Control 시작 메시지는 [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조합니다.2005* 다른 Remote Control 시작 메시지는 [Remote Control 문제 해결](/docs/ko/remote-control#troubleshooting)을 참조합니다.
1899 2006
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).2007서버가 대신 이전 세션이 없다고 보고하면 이 메시지가 표시되지 않습니다. Claude Code는 새 세션을 시작하거나 [`Previous session is unavailable — run /remote-control to start a new one`](/docs/ko/remote-control#previous-session-is-unavailable)을 표시합니다.
1901 2008
1902<h3 id="sessions-ended-while-this-machine-was-offline">2009<h3 id="sessions-ended-while-this-machine-was-offline">
1903 이 머신이 오프라인 상태인 동안 세션이 종료됨2010 이 머신이 오프라인 상태인 동안 세션이 종료됨
1931* `/feedback`을 실행하여 발생한 상황에 대한 설명과 함께 트랜스크립트를 보냅니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조합니다.2038* `/feedback`을 실행하여 발생한 상황에 대한 설명과 함께 트랜스크립트를 보냅니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조합니다.
1932* 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.2039* 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.
1933 2040
2041<h3 id="couldnt-send-feedback">
2042 피드백을 보낼 수 없습니다
2043</h3>
2044
2045[`/feedback`, `/bug`, 또는 `/share` 대화](/docs/ko/commands#all-commands)에서 보고서를 보냈고 Anthropic으로의 업로드가 실패했습니다. 대화는 텍스트를 유지하므로 다시 시도할 수 있습니다.
2046
2047```text theme={null}
2048Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.
2049```
2050
2051접두사 뒤의 텍스트는 실패한 것을 명시합니다:
2052
2053* **`: not signed in. Run /login, then retry.`**: 대화는 Claude Code가 열릴 때 Anthropic 자격 증명을 찾았을 때만 업로드되며, 보낼 때까지 사용 가능한 것이 없었습니다. 예를 들어, 그 사이에 이 머신에서 로그아웃했거나, 로그인을 더 이상 새로 고칠 수 없었습니다.
2054* **괄호 안의 내용**: `(server returned <status>)`는 서비스의 응답 코드입니다. `(request timed out)` 및 `(couldn't reach the service)`는 네트워크 실패입니다. Claude Code가 이유를 명시할 수 없으면 괄호 안의 내용이 없습니다.
2055
2056[피드백 초안 큐](/docs/ko/tools-reference#sendfeedback-tool-behavior)에서 동일한 실패는 `The draft is still queued. Try again later.`로 끝나며, 초안은 다른 시도를 위해 큐에 남아 있습니다.
2057
2058**수행할 작업:**
2059
2060* 서명되지 않은 표현의 경우, `/login`을 실행하고 다시 보냅니다.
2061* 그 외의 경우, 다시 보냅니다. 다른 요청도 실패하는 경우, 네트워크 연결을 확인하고 [API에 연결할 수 없음](#unable-to-connect-to-api)을 참조합니다.
2062* 계속 실패하면 메시지가 말하는 대로 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 보고서를 제출합니다.
2063
2064v2.1.281 이전에는 Remote Control **중지** 또는 긴급 교차 세션 메시지가 대화가 열려 있는 동안 도착했을 때 모든 전송이 이 메시지로 실패했습니다. 이러한 버전에서는 대화를 닫고, 다시 열고, 다시 보냅니다.
2065
1934<h2 id="request-errors">2066<h2 id="request-errors">
1935 요청 오류2067 요청 오류
1936</h2>2068</h2>
1953Context limit reached · /compact or /clear to continue2085Context limit reached · /compact or /clear to continue
1954```2086```
1955 2087
1956[`DISABLE_COMPACT`](/docs/ko/env-vars)가 설정된 경우에만 줄에 `/clear`만 표시됩니다. 아래의 압축 실패 형식과 같은 더 긴 오류 형식은 `Prompt is too long ·` 표현을 유지합니다. `-p` 출력 및 기록에서 텍스트는 `Prompt is too long`으로 유지됩니다.2088[`DISABLE_COMPACT`](/docs/ko/env-vars)가 설정된 경우에만 `/clear`를 표시합니다. 아래의 압축 실패 형식과 같은 더 긴 오류 형식은 `Prompt is too long ·` 표현을 유지합니다. `-p` 출력 및 기록에서 텍스트는 `Prompt is too long`으로 유지됩니다.
1957 2089
1958[사용자 설정](/docs/ko/settings-reference#autocompactenabled)에서 자동 압축을 끈 경우, 줄에도 다음과 같이 표시됩니다:2090[사용자 설정](/docs/ko/settings-reference#autocompactenabled)에서 자동 압축을 끈 경우, 이 줄은 다음과 같이 표시됩니다:
1959 2091
1960```text theme={null}2092```text theme={null}
1961Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on2093Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on
1962```2094```
1963 2095
1964`/config`의 **Auto-compact** 토글은 사용자 설정에 `autoCompactEnabled`를 씁니다. 힌트는 `/config` 변경이 적용될 때만 나타납니다. 예를 들어, [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](/docs/ko/env-vars)가 자동 압축을 끈 경우에는 나타나지 않습니다. 또한 프로젝트 또는 관리 설정과 같은 더 높은 우선순위 범위가 `autoCompactEnabled`를 `false`로 설정한 경우에도 나타나지 않습니다. v2.1.235 이전에는 줄에 자동 압축 힌트가 없었습니다.2096`/config`의 **자동 압축** 토글은 사용자 설정에 `autoCompactEnabled`를 씁니다. 이 힌트는 `/config` 변경이 적용될 때만 나타납니다. 예를 들어, [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](/docs/ko/env-vars)가 자동 압축을 끈 경우에는 나타나지 않습니다. 또한 프로젝트 또는 관리 설정과 같은 더 높은 우선순위 범위가 `autoCompactEnabled`를 `false`로 설정한 경우에도 나타나지 않습니다. v2.1.235 이전에는 이 줄에 자동 압축 힌트가 없었습니다.
1965 2097
1966Amazon Bedrock은 이 조건을 `Input is too long for requested model.`로 보고하며, Claude Code는 동일한 방식으로 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock 표현을 인식하지 못했으므로 자동 압축이 트리거되지 않았고 `/compact`는 동일한 오류로 실패했습니다.2098Amazon Bedrock은 이 조건을 `Input is too long for requested model.`로 보고하며, Claude Code는 동일한 방식으로 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock 표현을 인식하지 못했으므로 자동 압축이 트리거되지 않았고 `/compact`는 동일한 오류로 실패했습니다.
1967 2099
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가 토큰을 인식하지 못했으므로 자동 압축이 트리거되지 않았습니다.2100[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 2101
1970자동 압축이 이 턴에서 실행되었지만 사용할 수 없는 모델 또는 인증 실패와 같은 기본 오류에서 실패한 경우, 메시지는 구분 기호 뒤에 해당 오류를 이름으로 지정합니다:2102자동 압축이 이 턴에서 실행되었지만 사용할 수 없는 모델 또는 인증 실패와 같은 기본 오류로 실패한 경우, 메시지는 구분자 뒤에 해당 오류를 표시합니다:
1971 2103
1972```text theme={null}2104```text theme={null}
1973Prompt is too long · automatic compaction failed: <the underlying error>2105Prompt is too long · automatic compaction failed: <the underlying error>
1974```2106```
1975 2107
1976명명된 오류를 먼저 해결하십시오. `/compact`는 해결할 때까지 동일한 오류로 실패합니다. v2.1.229 이전에는 실패한 자동 압축이 원인 없이 `Prompt is too long`을 표시했습니다.2108명명된 오류를 먼저 해결하십시오. 해결할 때까지 `/compact`는 동일한 오류로 실패합니다. v2.1.229 이전에는 실패한 자동 압축이 원인 없이 `Prompt is too long`을 표시했습니다.
1977 2109
1978자동 압축이 이 오류에서 실행될 때, 일반적으로 가장 오래된 교환을 요약하고 가장 최신의 것을 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다:2110자동 압축이 이 오류에서 실행될 때, 일반적으로 가장 오래된 교환을 요약하고 가장 최신 교환을 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다:
1979 2111
1980* 전체 교환을 요약할 수 없을 때, Claude Code는 가장 최신 프롬프트를 그대로 유지하고 그 이전의 모든 것을 요약합니다.2112* 전체 교환을 요약할 수 없는 경우, Claude Code는 가장 최신 프롬프트를 그대로 유지하고 그 이전의 모든 것을 요약합니다.
1981* 그 경우, 대화가 프롬프트로 끝나지 않으면 Claude Code는 전체 대화를 대신 요약합니다.2113* 이 경우, 대화가 프롬프트로 끝나지 않으면 Claude Code는 전체 대화를 대신 요약합니다.
1982 2114
1983Claude Code는 전달할 내용이 모델 응답을 보유하지 않고 짧은 재시도와 같은 약 1,000개 토큰 미만의 자신의 텍스트를 보유할 때 이 복구를 건너뜁니다. `/clear`를 실행하여 새로 시작합니다. v2.1.269 이전에는 전체 교환을 요약할 수 없을 때마다 압축이 실패했으므로 이 상태의 세션은 모든 턴에서 이 오류를 다시 맞았습니다.2115Claude Code는 전달할 내용이 모델 응답을 포함하지 않고 짧은 재시도와 같은 약 1,000개 토큰 미만의 자신의 텍스트를 포함하는 경우 이 복구를 건너뜁니다. `/clear`를 실행하여 새로 시작하십시오. v2.1.269 이전에는 전체 교환을 요약할 수 없을 때마다 압축이 실패했으므로 이 상태의 세션은 매 턴마다 이 오류를 다시 만났습니다.
1984 2116
1985단일 교환 대화에는 요약할 이전 턴이 없습니다. 자동 압축이 하나에서 실행되었을 때, Claude Code는 시도를 건너뛰고 요청을 채우는 것을 설명합니다. API가 오류에서 토큰 수를 보고하지 않으면 메시지는 다음과 같이 읽힙니다:2117단일 교환 대화에는 요약할 이전 턴이 없습니다. 자동 압축이 하나에서 실행되었을 때, Claude Code는 시도를 건너뛰고 요청을 채우는 것을 설명합니다. API가 오류에서 토큰 수를 보고하지 않으면 메시지는 다음과 같이 읽습니다:
1986 2118
1987```text theme={null}2119```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.2120Prompt 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```2121```
1990 2122
1991API가 오류에서 토큰 수를 보고하면 Claude Code는 이를 대화 크기의 자체 추정치와 비교하여 요청의 대부분을 차지하는 것이 무엇인지 알려줍니다: 대화 자체의 내용, 또는 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의 및 첨부 내용입니다. 대화 자체의 내용이 요청의 대부분인 경우 메시지는 다음과 같이 읽힙니다:2123API가 오류에서 토큰 수를 보고하면 Claude Code는 이를 자신의 대화 크기 추정치와 비교하여 요청의 대부분이 무엇인지 알려줍니다: 대화 자체의 내용, 또는 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의 및 첨부 내용. 대화 자체의 내용이 요청의 대부분인 경우 메시지는 다음과 같이 읽습니다:
1992 2124
1993```text theme={null}2125```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).2126Prompt 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```2127```
1996 2128
1997요청의 대부분이 대화 외부에 있으면 메시지는 다음과 같이 읽힙니다:2129요청의 대부분이 대화 외부에 있으면 메시지는 다음과 같이 읽습니다:
1998 2130
1999```text theme={null}2131```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.2132Prompt 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```2133```
2002 2134
2003v2.1.162 이전에는 Claude Code가 압축을 시도했으며 실패했을 때 기본 `Prompt is too long`을 표시했습니다.2135v2.1.162 이전에는 Claude Code가 압축을 시도했고 실패했을 때 기본 `Prompt is too long`을 표시했습니다.
2004 2136
2005**할 일:**2137**할 일:**
2006 2138
2007* 다중 턴 대화에서 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다. `/compact`가 `Not enough messages to compact.`로 응답하면, 대화는 요약할 이전 내용이 없는 단일 교환이므로 공간은 해당 프롬프트와 Claude Code가 모든 요청과 함께 보내는 것으로 차지됩니다: `/clear`를 실행하고 붙여넣은 텍스트가 적거나 첨부 파일이 작은 상태로 다시 보내거나, 아래 단계를 사용하여 도구 정의 및 메모리 파일을 줄입니다2139* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다. `/compact`가 `Not enough messages to compact.`로 응답하면 대화는 요약할 이전 내용이 없는 단일 교환이므로 공간은 해당 프롬프트와 Claude Code가 모든 요청과 함께 보내는 것으로 채워집니다: `/clear`를 실행하고 더 적은 붙여넣은 텍스트 또는 더 작은 첨부 파일로 다시 보내거나, 아래 단계를 사용하여 도구 정의 및 메모리 파일을 줄입니다.
2008* `/context`를 실행하여 윈도우를 소비하는 것의 분석을 확인합니다: 시스템 프롬프트, 도구, 메모리 파일 및 메시지2140* `/context`를 실행하여 윈도우를 소비하는 것의 분석을 확인합니다: 시스템 프롬프트, 도구, 메모리 파일 및 메시지
2009* `/mcp disable <name>`으로 사용하지 않는 MCP 서버를 비활성화하여 컨텍스트에서 도구 정의를 제거합니다2141* `/mcp disable <name>`으로 사용하지 않는 MCP 서버를 비활성화하여 컨텍스트에서 도구 정의를 제거합니다.
2010* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 지침을 관련이 있을 때만 로드되는 [경로 범위 규칙](/docs/ko/memory#path-specific-rules)으로 이동합니다2142* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 지시사항을 관련이 있을 때만 로드되는 [경로 범위 규칙](/docs/ko/memory#path-specific-rules)으로 이동합니다.
2011* 서브에이전트는 부모 세션에서 모든 MCP 도구 정의를 상속하므로 첫 번째 턴 전에 컨텍스트 윈도우를 채울 수 있습니다. 서브에이전트를 생성하기 전에 사용하지 않는 MCP 서버를 비활성화합니다
2012* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config`에서 또는 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars)로 끈 경우 다시 켭니다. 끈 상태로 유지하면 윈도우가 채워지기 전에 `/compact`를 직접 실행합니다.2143* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config`에서 또는 [`DISABLE_AUTO_COMPACT`](/docs/ko/env-vars)로 끈 경우 다시 켭니다. 끈 상태로 유지하면 윈도우가 채워지기 전에 `/compact`를 직접 실행합니다.
2013 2144
2014[컨텍스트 윈도우 탐색](/docs/ko/context-window)에서 컨텍스트가 어떻게 채워지는지에 대한 대화형 보기를 참조하십시오.2145[컨텍스트 윈도우 탐색](/docs/ko/context-window)에서 컨텍스트가 어떻게 채워지는지에 대한 대화형 보기를 참조하십시오.
2017 컨텍스트가 토큰 제한을 초과합니다2148 컨텍스트가 토큰 제한을 초과합니다
2018</h3>2149</h3>
2019 2150
2020`/context`는 대화가 모델의 컨텍스트 윈도우를 초과했을 때 출력 상단에 이 경고를 표시합니다. [`Prompt is too long`](#prompt-is-too-long)을 해제할 때까지 요청이 실패합니다. 대화형 세션은 해당 오류를 `Context limit reached` 줄로 표시합니다.2151`/context`는 대화가 모델의 컨텍스트 윈도우를 초과했을 때 출력 상단에 이 경고를 표시합니다. [`Prompt is too long`](#prompt-is-too-long)으로 공간을 확보할 때까지 요청이 실패합니다. 대화형 세션은 해당 오류를 `Context limit reached` 줄로 표시합니다.
2021 2152
2022```text theme={null}2153```text theme={null}
2023Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2154Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
2024```2155```
2025 2156
2026초과한 제한이 1M 컨텍스트 모델의 200K 경계와 같은 모델의 컨텍스트 윈도우보다 작은 압축 윈도우인 경우, 경고는 다르게 읽힙니다. 압축 윈도우는 모델의 컨텍스트 윈도우 아래에 있을 수 있으므로 그것을 지난 요청은 여전히 성공할 수 있습니다.2157초과한 제한이 1M 컨텍스트 모델의 200K 경계와 같은 압축 윈도우인 경우 경고는 다르게 읽힙니다. 압축 윈도우는 모델의 컨텍스트 윈도우 아래에 있을 수 있으므로 그 이후의 요청은 여전히 성공할 수 있습니다.
2027 2158
2028```text theme={null}2159```text theme={null}
2029Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.2160Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.
2030```2161```
2031 2162
2032두 형식 모두 [`DISABLE_COMPACT`](/docs/ko/env-vars)를 설정한 경우 `/compact` 대신 `/clear`를 이름으로 지정합니다.2163두 형식 모두 [`DISABLE_COMPACT`](/docs/ko/env-vars)를 설정한 경우 `/compact` 대신 `/clear`를 표시합니다.
2033 2164
2034**할 일:**2165**할 일:**
2035 2166
2036* 다중 턴 대화에서 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보합니다. 대신 새로 시작하려면 `/clear`를 실행합니다2167* 다중 턴 대화에서 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보합니다. 대신 새로 시작하려면 `/clear`를 실행합니다.
2037* 사용량을 줄이는 더 많은 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오2168* 사용량을 줄이는 더 많은 방법은 [프롬프트가 너무 깁니다](#prompt-is-too-long)를 참조하십시오.
2038 2169
2039v2.1.216 이전에는 `/context`가 100% 이상의 사용량을 표시했으며 그것이 의미하는 바 또는 복구 방법을 설명하는 경고 줄이 없었습니다.2170v2.1.216 이전에는 `/context`가 100% 이상의 사용량을 표시했으며 그것이 의미하는 바 또는 복구 방법을 설명하는 경고 줄이 없었습니다.
2040 2171
2041<h3 id="error-during-compaction-conversation-too-long">
2042 압축 중 오류: 대화가 너무 깁니다
2043</h3>
2044
2045`/compact` 자체가 실패했습니다. 생성하는 요약을 보유할 충분한 여유 컨텍스트가 없기 때문입니다.
2046
2047```text theme={null}
2048Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.
2049```
2050
2051이는 윈도우가 자동 압축이 트리거되는 순간 이미 가득 찬 경우 또는 [`Prompt is too long`](#prompt-is-too-long)을 본 후 `/compact`를 실행할 때 발생할 수 있습니다. 대화형 세션에서 해당 오류는 `Context limit reached` 줄입니다.
2052
2053**할 일:**
2054
2055* Esc를 두 번 눌러 메시지 목록을 열고 여러 턴을 뒤로 이동합니다. 이렇게 하면 컨텍스트에서 가장 최근 메시지가 제거됩니다. 그런 다음 `/compact`를 다시 실행합니다.
2056* 뒤로 이동해도 충분한 공간이 확보되지 않으면 `/clear`를 실행하여 새 세션을 시작합니다. 이전 대화는 보존되며 `/resume`으로 다시 열 수 있습니다.
2057
2058이 메시지 및 기타 `/compact` 실패는 오류 스타일로 표시됩니다. v2.1.216 이전에는 성공한 명령 출력과 동일한 흐릿한 스타일로 렌더링되었으므로 실패한 압축을 성공으로 읽을 수 있었습니다.
2059
2060<h3 id="request-too-large">2172<h3 id="request-too-large">
2061 요청이 너무 큽니다2173 요청이 너무 큽니다
2062</h3>2174</h3>
2069 2181
2070요청이 Claude API로 직접 이동했고 API 자체가 거부한 경우, Claude Code는 대화를 측정하고 복구가 작동할 수 있는지 여부에 따라 메시지를 표현합니다. 프록시, 게이트웨이 또는 클라우드 제공자를 통해 일반 메시지를 받습니다. 측정된 형식:2182요청이 Claude API로 직접 이동했고 API 자체가 거부한 경우, Claude Code는 대화를 측정하고 복구가 작동할 수 있는지 여부에 따라 메시지를 표현합니다. 프록시, 게이트웨이 또는 클라우드 제공자를 통해 일반 메시지를 받습니다. 측정된 형식:
2071 2183
2072* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지 또는 문서가 요청을 초과했습니다. Claude Code는 이를 제거하고 다시 시도합니다.2184* `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)에서 메시지는 입력을 줄이거나 대신 새 세션을 시작하도록 알려줍니다.2185* `Request too large for the API's 32MB request limit`: 메시지만 제한을 초과하므로 메시지는 `compacting cannot make it fit`이라고 말하고 Claude Code는 다시 시도하지 않습니다. [비대화형 모드](/docs/ko/headless)에서 메시지는 입력을 줄이거나 대신 새 세션을 시작하도록 알려줍니다.
2074 2186
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가 압축이 도움이 될 수 없을 때도 모든 거부에 대해 첨부 조언을 표시했습니다.2187v2.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 2188
2077**할 일:**2189**할 일:**
2078 2190
2079* 메시지가 `compacting cannot make it fit`이라고 말하면 큰 내용을 추가한 턴을 지나 Esc를 두 번 눌러 뒤로 이동하거나 `/clear`를 실행하여 새로 시작합니다2191* 메시지가 `compacting cannot make it fit`이라고 말하면 Esc를 두 번 눌러 큰 내용을 추가한 턴을 지나 뒤로 이동하거나 `/clear`를 실행하여 새로 시작합니다.
2080* 그렇지 않으면 `/compact`를 실행하여 누적된 이미지 및 첨부 파일을 제거합니다2192* 그렇지 않으면 `/compact`를 실행합니다. 이는 누적된 이미지 및 첨부 파일을 제거합니다.
2081* 내용을 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다2193* 내용을 붙여넣는 대신 경로로 큰 파일을 참조하여 Claude가 청크 단위로 읽을 수 있도록 합니다.
2082* 이미지의 경우 아래의 [Image was too large](#image-was-too-large)를 참조하십시오2194* 이미지의 경우 아래의 [이미지가 너무 컸습니다](#image-was-too-large)를 참조하십시오.
2083 2195
2084<h3 id="image-was-too-large">2196<h3 id="image-was-too-large">
2085 이미지가 너무 큽니다2197 이미지가 너무 컸습니다
2086</h3>2198</h3>
2087 2199
2088붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.2200붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 제한을 초과합니다.
2092API Error: 400 ... image dimensions exceed max allowed size2204API Error: 400 ... image dimensions exceed max allowed size
2093```2205```
2094 2206
2095Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지가 성공합니다. 2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 모든 메시지에서 동일한 오류를 반복합니다. 이러한 버전에서 복구하려면 Esc를 두 번 눌러 이미지가 추가된 턴을 지나 뒤로 이동합니다.2207Claude Code는 처리할 수 없는 이미지를 텍스트 자리 표시자로 바꾸고 다시 시도하므로 후속 메시지는 성공합니다. v2.1.142 이전 버전에서는 붙여넣은 이미지가 대화에 남아 있을 수 있으며 후속 모든 메시지에서 동일한 오류를 반복했습니다. 이러한 버전에서 복구하려면 Esc를 두 번 누르고 이미지가 추가된 턴을 지나 뒤로 이동합니다.
2096 2208
2097**할 일:**2209**할 일:**
2098 2210
2099* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀을 허용하거나 많은 이미지가 컨텍스트에 있을 때 2000픽셀을 허용합니다.2211* 붙여넣기 전에 이미지 크기를 조정합니다. API는 단일 이미지의 경우 가장 긴 가장자리에서 최대 8000픽셀, 또는 많은 이미지가 컨텍스트에 있을 때 2000픽셀까지의 이미지를 허용합니다.
2100* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다2212* 전체 화면 대신 관련 영역의 더 타이트한 스크린샷을 찍습니다.
2101 2213
2102<h3 id="unable-to-resize-image">2214<h3 id="unable-to-resize-image">
2103 이미지 크기를 조정할 수 없습니다2215 이미지 크기를 조정할 수 없습니다
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.2227Unable 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```2228```
2117 2229
2118Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이러한 오류는 이미지를 디코딩하거나 API 제한 내에 맞게 크기 조정할 수 없음을 의미합니다.2230Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이러한 오류는 이미지를 디코딩하거나 API 제한 내에 맞게 크기를 조정할 수 없음을 의미합니다.
2119 2231
2120**할 일:**2232**할 일:**
2121 2233
2122* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지를 디코딩하지 않고 파일 헤더에서 이러한 형식의 치수를 확인할 수 있습니다.2234* 메시지가 이미지를 변환하도록 요청하면 PNG, JPEG, GIF 또는 WebP로 변환하고 다시 첨부합니다. Claude Code는 이미지를 디코딩하지 않고 파일 헤더에서 이러한 형식의 치수를 확인할 수 있습니다.
2123* 메시지가 치수 또는 크기 제한을 보고하면 해당 제한 아래로 이미지 크기를 조정하거나 다시 압축한 후 첨부합니다.2235* 메시지가 치수 또는 크기 제한을 보고하면 해당 제한 아래로 이미지 크기를 조정하거나 다시 압축한 후 첨부합니다.
2124* 메시지가 CMYK JPEG, 애니메이션 WebP 또는 손상된 파일과 같은 원인을 이름으로 지정하면 메시지가 제안하는 형식으로 이미지를 다시 저장하고 첨부합니다.2236* 메시지가 CMYK JPEG, 애니메이션 WebP 또는 손상된 파일 가능성과 같은 원인을 표시하면 메시지가 제안하는 형식으로 이미지를 다시 저장하고 첨부합니다.
2125 2237
2126<h3 id="pdf-errors">2238<h3 id="pdf-errors">
2127 PDF 오류2239 PDF 오류
2128</h3>2240</h3>
2129 2241
2130첨부한 PDF를 처리할 수 없었습니다. 메시지는 비대화형 형식으로 표시됩니다. 대화형 세션에서는 대신 Esc를 두 번 눌러 다시 시도하도록 요청합니다.2242첨부한 PDF를 처리할 수 없었습니다. 메시지는 여기에 비대화형 형식으로 표시됩니다. 대화형 세션에서는 대신 Esc를 두 번 누르고 다시 시도하도록 요청합니다.
2131 2243
2132```text theme={null}2244```text theme={null}
2133PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).2245PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
2137 2249
2138**할 일:**2250**할 일:**
2139 2251
2140* 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Read 도구로 Claude에게 페이지 범위를 읽도록 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 출력 파일을 경로로 참조합니다2252* 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Read 도구로 페이지 범위를 읽도록 Claude에 요청하거나 `pdftotext`와 같은 도구로 텍스트를 추출하고 출력 파일을 경로로 참조합니다.
2141* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다2253* 보호되거나 유효하지 않은 PDF의 경우 암호를 제거하거나 소스 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다.
2254
2255Claude가 Read 도구로 PDF에서 페이지 범위를 읽을 때, 읽기는 다른 메시지로 실패할 수 있습니다:
2256
2257```text theme={null}
2258pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.
2259```
2260
2261페이지 범위 읽기는 `pdftoppm`으로 페이지를 렌더링합니다. 메시지가 제공하는 명령으로 poppler-utils를 설치하거나 다른 플랫폼에서 `pdftoppm`을 `PATH`에 배치하는 poppler 빌드를 설치합니다. [Read 도구 동작](/docs/ko/tools-reference#read-tool-behavior)에서 어떤 PDF가 페이지 범위로 읽히는지 참조하십시오.
2142 2262
2143<h3 id="extra-inputs-are-not-permitted">2263<h3 id="extra-inputs-are-not-permitted">
2144 추가 입력은 허용되지 않습니다2264 추가 입력은 허용되지 않습니다
2148 2268
2149```text theme={null}2269```text theme={null}
2150API Error: 400 ... Extra inputs are not permitted ... context_management2270API Error: 400 ... Extra inputs are not permitted ... context_management
2151API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header
2152```2271```
2153 2272
2154Claude Code는 `context_management` 및 `effort`와 같은 베타 전용 필드를 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문을 전달하지만 헤더를 제거하면 API는 인식하지 못하는 필드를 봅니다.2273Claude Code는 `context_management` 및 `effort`와 같은 베타 전용 필드를 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문을 전달하지만 헤더를 제거하면 API는 인식하지 못하는 필드를 봅니다.
2155 2274
2156**할 일:**2275**할 일:**
2157 2276
2158* `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성합니다. 게이트웨이가 전달해야 하는 것은 [기능 통과](/docs/ko/llm-gateway-protocol#feature-pass-through)를 참조하십시오.2277* `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)는 정확한 범위를 다룹니다.2278* 대체로 시작하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/ko/env-vars)을 설정합니다. [사전 릴리스 기능 비활성화](/docs/ko/llm-gateway-protocol#disable-pre-release-capabilities)는 정확한 범위를 다룹니다.
2160 2279
2161<h3 id="tool-input-schema-is-invalid">2280<h3 id="tool-input-schema-is-invalid">
2162 도구 입력 스키마가 유효하지 않습니다2281 도구 입력 스키마가 유효하지 않습니다
2163</h3>2282</h3>
2164 2283
2165요청의 도구가 API의 JSON Schema 검증에 실패하는 `input_schema`를 선언했으므로 API가 전체 요청을 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.2284요청의 도구가 API의 JSON Schema 검증에 실패하는 `input_schema`를 선언했으므로 API가 전체 요청을 거부했습니다. `tools.` 뒤의 숫자는 실패한 도구의 위치이며 조회할 수 있는 이름이 아닙니다.
2166 2285
2167```text theme={null}2286```text theme={null}
2168API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid2287API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
2171 2290
2172첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아님을 의미합니다. 두 번째는 최상위 속성 이름이 메시지가 인용하는 패턴과 일치하지 않음을 의미합니다.2291첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아님을 의미합니다. 두 번째는 최상위 속성 이름이 메시지가 인용하는 패턴과 일치하지 않음을 의미합니다.
2173 2292
2174Claude Code는 로드할 때 [이 검증에 실패할 입력 스키마가 있는 MCP 도구를 제외](/docs/ko/mcp#tools-with-invalid-input-schemas)하므로 요청은 일반적으로 하나를 포함하지 않습니다.2293Claude Code는 [이 검증에 실패할 입력 스키마를 가진 MCP 도구를 제외합니다](/docs/ko/mcp#tools-with-invalid-input-schemas). 서버의 도구를 로드할 때 요청은 일반적으로 하나를 포함하지 않습니다.
2175 2294
2176[플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서 또는 플래그가 도착한 적이 없는 머신에서 Claude Code는 서버의 로그에 거부될 도구를 기록하지만 어쨌든 보내므로 이 오류가 여전히 발생할 수 있습니다.2295[플래그 가져오기가 꺼진 배포](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서 또는 플래그가 도착한 적이 없는 머신에서 Claude Code는 서버의 로그에 거부될 도구를 기록하지만 어쨌든 보내므로 이 오류가 여전히 발생할 수 있습니다.
2177 2296
2178오류는 또한 스키마가 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언하는 도구에 대해 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마에 대해 확인하지 않지만 최상위 속성 이름 확인은 여전히 적용됩니다.2297오류는 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언하는 도구의 스키마에서도 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마에 대해 확인하지 않지만 최상위 속성 이름 확인은 여전히 적용됩니다.
2179 2298
2180v2.1.216 이전에는 배포가 제외 확인을 실행하지 않았습니다.2299v2.1.216 이전에는 배포가 제외 확인을 실행하지 않았습니다.
2181 2300
2182**할 일:**2301**할 일:**
2183 2302
2184* Claude Code 버전이 v2.1.216보다 이전이면 `claude update`를 실행합니다.2303* Claude Code 버전이 v2.1.216보다 이전이면 `claude update`를 실행합니다.
2185* 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 [비활성화](/docs/ko/mcp#disable-a-server-without-removing-it)합니다. 오류는 도구를 위치로만 이름으로 지정합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 이름으로 지정하는 줄을 확인합니다. 로그가 하나를 이름으로 지정하지 않으면 서버를 하나씩 비활성화합니다.2304* 유효하지 않은 스키마를 선언하는 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)를 참조하십시오.2305* 서버를 유지 관리하면 도구의 `input_schema`를 수정합니다. 스키마는 유효한 JSON Schema여야 하며 최상위 속성 이름은 1\~64자 길이여야 하고 ASCII 문자와 숫자, `_`, `.` 및 `-`만 사용해야 합니다. [유효하지 않은 입력 스키마를 가진 도구](/docs/ko/mcp#tools-with-invalid-input-schemas)를 참조하십시오.
2306
2307<h3 id="tool-use-name-over-200-characters">
2308 tool\_use.name이 200자를 초과합니다
2309</h3>
2310
2311대화 기록의 도구 호출이 API가 요청에서 허용하는 200자보다 긴 이름을 포함합니다:
2312
2313```text theme={null}
2314API Error: 400 ... tool_use.name: String should have at most 200 characters
2315```
2316
2317Claude Code는 응답이 도착할 때와 저장된 대화를 로드할 때 이러한 이름을 200자로 자릅니다. 따라서 호출은 일반적인 `No such tool available` 도구 오류로 실패하고 대화는 이 API 오류 없이 계속됩니다.
2318
2319**할 일:**
2320
2321* `claude update`를 실행한 다음 대화를 재개합니다. 업데이트된 버전은 기록을 로드할 때 과도하게 긴 이름을 복구하므로 막힌 대화가 다시 작동합니다.
2322
2323v2.1.281 이전에는 과도하게 긴 이름이 기록에 남아 있었고 API는 `/compact` 및 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했으므로 이 오류가 반복되고 대화가 막혔습니다.
2187 2324
2188<h3 id="theres-an-issue-with-the-selected-model">2325<h3 id="theres-an-issue-with-the-selected-model">
2189 선택한 모델에 문제가 있습니다2326 선택한 모델에 문제가 있습니다
2190</h3>2327</h3>
2191 2328
2192구성된 모델 이름이 인식되지 않았거나 계정에 액세스 권한이 없습니다. v2.1.160부터 뒤따르는 힌트는 표시 표면에 따라 다르며 여기에 대화형 형식으로 표시됩니다.2329구성된 모델 이름을 인식하지 못했거나 계정이 이에 대한 액세스 권한이 없습니다. v2.1.160부터 뒤따르는 힌트는 표시 표면에 따라 다릅니다.
2193 2330
2194```text theme={null}2331```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.2332There'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`을 실행하여 계정에서 사용 가능한 모델 중에서 선택합니다.2337* **대화형 CLI**: `/model`을 실행하여 계정에서 사용 가능한 모델 중에서 선택합니다.
2201* **비대화형 모드(`-p`)**: 유효한 별칭 또는 ID로 `--model`을 전달하거나 [`ANTHROPIC_MODEL`](/docs/ko/env-vars)을 설정합니다. 오류 텍스트는 이 표면에서 `Run --model`을 표시합니다.2338* **비대화형 모드(`-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` 오류를 처리하여 자신의 재시도 또는 모델 선택기를 표시합니다.2339* **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)을 참조하십시오.2340* `sonnet` 또는 `opus`와 같은 별칭을 전체 버전 ID 대신 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래되지 않습니다. [모델 구성](/docs/ko/model-config)을 참조하십시오.
2204* CLI에서 잘못된 모델이 계속 돌아오면 어딘가에 오래된 ID가 설정되어 있습니다. [우선순위 순서](/docs/ko/model-config#setting-your-model)로 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거합니다.2341* 잘못된 모델이 CLI에서 계속 돌아오면 어딘가에 오래된 ID가 설정되어 있습니다. [우선순위 순서](/docs/ko/model-config#setting-your-model)로 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거합니다.
2205* 새로 출시된 모델은 Anthropic API에서 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry가 제공하기 전에 사용 가능할 수 있습니다. 이러한 제공자 중 하나에서 새 모델 ID를 고정했고 이 오류가 표시되면 제공자의 모델 카탈로그에서 지역의 가용성을 확인하고 새 모델이 나타날 때까지 이전 버전을 고정된 상태로 유지합니다.2342* Claude Code는 만료된 claude.ai 로그인을 [로그인 만료됨](#login-expired)으로 보고하며, 이 오류로는 보고하지 않습니다. v2.1.206 이전에는 더 이상 새로 고칠 수 없는 만료된 로그인이 모든 모델에서 실패했습니다. 이전 버전에서 이를 보면 `/login`을 실행합니다.
2206* Claude Code는 만료된 claude.ai 로그인을 [Login expired](#login-expired)로 보고하며, 이 오류로는 보고하지 않습니다. v2.1.206 이전에는 더 이상 새로 고칠 수 없는 만료된 로그인이 모든 모델에서 실패했습니다. 이전 버전에서 이를 보면 `/login`을 실행합니다.
2207* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/docs/ko/google-vertex-ai#troubleshooting)을 참조하십시오.2343* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/docs/ko/google-vertex-ai#troubleshooting)을 참조하십시오.
2208 2344
2209<h3 id="model-is-not-a-recognized-model-id">2345<h3 id="model-is-not-a-recognized-model-id">
2210 모델이 인식된 모델 ID가 아닙니다2346 모델이 인식된 모델 ID가 아닙니다
2211</h3>2347</h3>
2212 2348
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)로 다음 요청에서 실패했습니다.2349모델 전환에 전달한 모델 문자열이 모델 별칭, 이 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 2350
2215```text theme={null}2351```text theme={null}
2216Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?2352Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?
2217```2353```
2218 2354
2219뒤따르는 힌트는 가장 가까운 일치하는 별칭 또는 모델 ID를 이름으로 지정합니다. 충분히 가까운 것이 없으면 `Run /model to see available models.`로 읽힙니다.2355뒤따르는 힌트는 가장 가까운 일치하는 별칭 또는 모델 ID를 표시합니다. 충분히 가까운 것이 없으면 `Run /model to see available models.`로 읽습니다. [Desktop 앱](/docs/ko/desktop)이 시작하는 세션에서 일치하지 않는 힌트는 `Switch to a different model.`로 읽습니다.
2220 2356
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)로 실패했습니다.2357Claude 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 2358
2223**할 일:**2359**할 일:**
2224 2360
2225* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용 가능한 모델 중에서 선택한 다음 거기에 표시된 별칭 또는 ID를 전달합니다2361* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용 가능한 모델 중에서 선택한 다음 거기에 표시된 별칭 또는 ID를 전달합니다.
2226* 최신 Claude Code 버전이 지원하는 별칭을 사용한 경우 `claude update`를 실행합니다. `claude-`로 시작하는 전체 ID는 모델이 Claude Code 버전보다 최신이어도 이 로컬 확인을 통과합니다. 서버는 여전히 해당 모델에 대한 최소 버전을 요구할 수 있습니다. [Claude Code가 이 모델을 지원하지 않습니다](#claude-code-does-not-support-this-model)를 참조하십시오.2362* 최신 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) 아래에 나열된 위치에서 제거합니다.2363* 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)을 쓸 수 있습니다.2364* 확인은 Anthropic API에서만 실행됩니다. 사용자 정의 `ANTHROPIC_BASE_URL`을 포함한 다른 제공자 또는 게이트웨이에서 제공자는 모델 이름을 정의하므로 Claude Code는 모든 문자열을 허용하고 통과합니다. Claude Code는 여전히 요청 시간에 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)을 모든 제공자에서 쓸 수 있습니다.
2229 2365
2230<h3 id="model-not-found">2366<h3 id="model-not-found">
2231 모델을 찾을 수 없습니다2367 모델을 찾을 수 없습니다
2232</h3>2368</h3>
2233 2369
2234`/model <name>`으로 모델을 선택했고 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 Claude Code가 로컬에서 수락하는 다른 철자가 아닌 경우 `/model`은 최소 API 요청으로 확인하고 이 오류는 일반적으로 API 엔드포인트의 답변입니다. 공백을 포함하는 것과 같이 모델 ID가 될 수 없는 이름은 동일한 메시지를 받습니다.2370`/model <name>`으로 모델을 선택했고 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 Claude Code가 로컬로 허용하는 다른 철자가 아닌 경우 `/model`은 최소 API 요청으로 이를 확인하고 이 오류는 일반적으로 API 엔드포인트의 응답입니다. 공백을 포함하는 것과 같이 모델 ID가 될 수 없는 이름은 동일한 메시지를 받습니다.
2235 2371
2236```text theme={null}2372```text theme={null}
2237Model 'claude-opus-9' not found2373Model 'claude-opus-9' not found
2238```2374```
2239 2375
2240제공자별 모델 ID가 있는 제공자에서 메시지는 대체 모델에 대한 제공자의 ID를 이름으로 지정하는 `Try '...' instead` 제안을 추가할 수 있습니다.2376제공자별 모델 ID를 가진 제공자에서 메시지는 대체 모델에 대한 제공자의 ID를 표시하는 `Try '...' instead` 제안을 추가할 수 있습니다.
2241 2377
2242**할 일:**2378**할 일:**
2243 2379
2244* 인수 없이 `/model`을 실행하고 계정에서 사용 가능한 모델 중에서 선택하거나 `sonnet`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases)을 사용합니다. 이는 유지 관리되는 기본값으로 확인됩니다2380* 인수 없이 `/model`을 실행하고 계정에서 사용 가능한 모델 중에서 선택하거나 `sonnet`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases)을 사용합니다. 이는 유지 관리되는 기본값으로 확인됩니다.
2245* 전체 ID를 입력한 경우 제공자의 모델 카탈로그에 대해 확인합니다. 새로 출시된 모델은 제공자 또는 지역이 제공하기 전에 Anthropic API에서 사용 가능할 수 있습니다.2381* 전체 ID를 입력한 경우 제공자의 모델 카탈로그에 대해 확인합니다. 새로 출시된 모델은 제공자 또는 지역이 제공하기 전에 Anthropic API에서 사용 가능할 수 있습니다.
2246* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 철자를 이 오류로 거부했습니다. 이러한 버전에서는 Claude Code를 업데이트하거나 [설정](/docs/ko/model-config#setting-your-model) 또는 `--model`에서 모델을 설정합니다.2382* v2.1.265 이전에는 `/model`도 `opusplan[1m]` 별칭 철자를 이 오류로 거부했습니다. 이러한 버전에서는 Claude Code를 업데이트하거나 [설정](/docs/ko/model-config#setting-your-model)에서 또는 `--model` 대신 모델을 설정합니다.
2383
2384<h3 id="api-error-model-not-changed">
2385 선택한 모델을 확인할 때 API 오류
2386</h3>
2387
2388`/model <name>`으로 모델을 선택했거나 앱이 세션에 연결되어 전환을 요청했습니다. API가 Claude Code가 모델을 확인하기 위해 보내는 최소 요청을 거부했습니다. 이유가 없는 이유(예: 속도 제한 또는 서버 오류)로 인해. 세션은 현재 모델을 유지하고 메시지는 그렇게 말하면서 끝납니다:
2389
2390```text theme={null}
2391API error: 429 <the server's explanation> · model not changed
2392```
2393
2394메시지의 중간은 HTTP 상태 및 서버의 자체 설명입니다.
2395
2396**할 일:**
2397
2398* 서버의 설명에 따라 행동합니다. 속도 제한 또는 5xx 상태의 경우 기다렸다가 모델을 다시 선택합니다.
2399* 자신의 표현이 있는 거부는 [모델을 찾을 수 없습니다](#model-not-found) 및 [모델이 조직의 설정으로 제한됩니다](#model-is-restricted-by-your-organizations-settings)와 같은 주변 항목으로 다룹니다.
2247 2400
2248<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">2401<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">
2249 Claude Opus는 Claude Pro 플랜에서 사용할 수 없습니다2402 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.2408Claude 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```2409```
2257 2410
2411Claude Desktop 앱이 실행하는 세션에서 메시지는 명령을 표시하는 대신 `sign out and sign in again`이라고 말합니다.
2412
2258**할 일:**2413**할 일:**
2259 2414
2260* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다2415* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다.
2261* 최근에 플랜을 업그레이드했는데도 여전히 이를 보면 `/logout`을 실행한 다음 `/login`을 실행합니다. 저장된 토큰은 로그인 시 플랜을 반영하므로 웹에서 업그레이드해도 기존 세션에서 다시 인증할 때까지 적용되지 않습니다.2416* 최근에 플랜을 업그레이드했는데도 여전히 이를 보면 `/logout`을 실행한 다음 `/login`을 실행합니다. 저장된 토큰은 로그인 시점의 플랜을 반영하므로 claude.ai에서 업그레이드하면 다시 인증할 때까지 기존 세션에서 적용되지 않습니다.
2262* [claude.com/pricing](https://claude.com/pricing)에서 각 플랜에 포함된 모델을 참조하십시오2417* 각 플랜에 포함된 모델에 대해서는 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오.
2263 2418
2264<h3 id="claude-code-does-not-support-this-model">2419<h3 id="claude-code-does-not-support-this-model">
2265 Claude Code가 이 모델을 지원하지 않습니다2420 Claude Code가 이 모델을 지원하지 않습니다
2266</h3>2421</h3>
2267 2422
2268API가 Claude Code 버전이 필요한 최소값 아래에 있기 때문에 400으로 요청을 거부했습니다. 선택한 모델이 최신 버전을 요구하거나(서버가 모델별로 확인) 조직의 정책이 하나를 요구합니다. 400은 오류 코드 `claude_code_version_too_old`를 전달하고 메시지는 어느 최소값이 적용되는지 말합니다.2423API가 Claude Code 버전이 필요한 최소값 아래에 있기 때문에 400으로 요청을 거부했습니다. 선택한 모델이 최신 버전을 요구하거나(서버가 모델별로 확인) 조직의 정책이 하나를 요구합니다. 400은 오류 코드 `claude_code_version_too_old`를 포함하고 메시지는 어떤 최소값이 적용되는지 말합니다.
2269 2424
2270```text theme={null}2425```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.2426API 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```2427```
2273 2428
2274조직 정책 표현은 다음과 같이 읽힙니다:2429조직 정책 표현은 다음과 같이 읽습니다:
2275 2430
2276```text theme={null}2431```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.2432API 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 2434
2280**할 일:**2435**할 일:**
2281 2436
2282* `claude update`를 실행하거나 Claude 데스크톱 앱을 업데이트한 다음 새 세션을 시작합니다2437* `claude update`를 실행하거나 Claude Desktop 앱을 업데이트한 다음 새 세션을 시작합니다.
2283* 모델별 표현의 경우 `/model`로 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다2438* 모델별 표현의 경우 `/model`로 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다.
2284* 조직 정책 표현의 경우 계속하기 전에 업데이트합니다2439* 조직 정책 표현의 경우 계속하기 전에 업데이트합니다.
2285 2440
2286<h3 id="model-is-restricted-by-your-organizations-settings">2441<h3 id="model-is-restricted-by-your-organizations-settings">
2287 모델이 조직의 설정으로 제한됩니다2442 모델이 조직의 설정으로 제한됩니다
2288</h3>2443</h3>
2289 2444
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 관리 콘솔에서 비활성화한 후 세션 중간에 나타날 수도 있습니다.2445조직 관리자가 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 2446
2292```text theme={null}2447```text theme={null}
2293Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.2448Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.
2294```2449```
2295 2450
2296에이전트, 스킬 또는 명령 이름이 앞에 붙은 공지는 제한이 해당 [서브에이전트의 요청된 모델](/docs/ko/sub-agents#choose-a-model)에 적용되었음을 의미합니다: 서브에이전트는 대체 모델에서 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 시작된 서브에이전트에 대해서만 공지를 표시했습니다.2451제한된 모델에 대해 `/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.`로 읽습니다.
2452
2453에이전트, 스킬 또는 명령 이름이 앞에 붙은 알림은 제한이 해당 [하위 에이전트의 요청된 모델](/docs/ko/sub-agents#choose-a-model)에 적용되었음을 의미합니다: 하위 에이전트는 대체 모델에서 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 시작된 하위 에이전트에 대해서만 알림을 표시했습니다.
2297 2454
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 이전에는 패밀리 별칭이 같은 패밀리의 이전 버전이 허용된 경우에도 최신 버전만을 기반으로 대체되거나 거부되었습니다.2455Claude 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 2456
2300**할 일:**2457**할 일:**
2301 2458
2302* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에서 숨겨집니다.2459* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에서 숨겨집니다.
2303* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드 또는 [서브에이전트](/docs/ko/sub-agents#choose-a-model), 스킬 또는 명령의 `model` 프론트매터에 설정된 경우 해당 값을 제거하거나 업데이트하여 공지가 다시 나타나지 않도록 합니다2460* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드 또는 [하위 에이전트](/docs/ko/sub-agents#choose-a-model), 스킬 또는 명령의 `model` frontmatter에 설정된 경우 해당 값을 제거하거나 업데이트하여 알림이 반복되지 않도록 합니다.
2304* 제한된 모델에 액세스해야 하면 조직 관리자에게 활성화를 요청합니다. [조직 모델 제한](/docs/ko/model-config#organization-model-restrictions)을 참조하십시오.2461* 제한된 모델에 액세스해야 하면 조직 관리자에게 활성화를 요청합니다. [조직 모델 제한](/docs/ko/model-config#organization-model-restrictions)을 참조하십시오.
2305 2462
2306<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">2463<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">
2307 모델 스위치가 PreModelSwitch 훅으로 차단되었습니다2464 모델 전환이 PreModelSwitch 훅에 의해 차단되었습니다
2308</h3>2465</h3>
2309 2466
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`을 읽습니다.2467[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 2468
2312```text theme={null}2469```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.2470Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.
2314```2471```
2315 2472
2316콜론 뒤의 이유는 스위치를 거부한 것을 말합니다:2473콜론 뒤의 이유는 전환을 거부한 것을 말합니다:
2317 2474
2318* **훅이 작성한 이유**: PreModelSwitch 훅이 [스위치를 거부하거나 확인을 요청](/docs/ko/hooks#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청하는 것을 해결하거나 훅이 허용하는 모델을 선택합니다.2475* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](/docs/ko/hooks#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청하는 것을 해결하거나 훅이 허용하는 모델을 선택합니다.
2319* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](/docs/ko/hooks#timeouts) 전에 응답하지 않는 훅이 스위치를 차단합니다. 행(hung) 명령을 수정하거나 해당 훅의 `timeout`을 높인 다음 다시 전환합니다.2476* **`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)`으로 동일한 조건을 보고합니다. 대화형 세션에서 스위치를 만들거나 이 모델에 대한 훅의 결정을 변경합니다.2477* **`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`를 실행하고 다시 전환하여 세부 정보를 캡처한 다음 플러그인을 수정하거나 관리자에게 수정을 요청합니다.2478* **`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`를 실행하여 실패한 것을 확인한 다음 다시 전환합니다.2479* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 판정 없이 끝났고 Claude Code는 이를 승인으로 취급하지 않습니다. `claude --debug`를 실행하여 실패한 것을 확인한 다음 다시 전환합니다.
2323 2480
2324v2.1.260 이전에는 관리 플러그인 거부가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`로 읽혔습니다. Claude Code는 플러그인 로드를 한 번 재시도한 다음 조직이 플러그인을 관리하지 않은 경우에도 세션의 이후 스위치를 거부했습니다. 이러한 버전에서 플러그인 로드를 다시 실행하려면 세션을 다시 시작합니다.2481v2.1.260 이전에는 관리 플러그인 거부가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`로 읽었습니다. Claude Code는 플러그인 로드를 한 번 재시도한 다음 세션의 이후 전환을 거부했습니다. 조직이 플러그인을 관리하지 않은 경우에도 마찬가지였습니다. 이러한 버전에서 세션을 다시 시작하여 플러그인 로드를 다시 실행합니다.
2325 2482
2326<h3 id="couldnt-save-it-as-your-default">2483<h3 id="couldnt-save-it-as-your-default">
2327 기본값으로 저장할 수 없습니다2484 기본값으로 저장할 수 없었습니다
2328</h3>2485</h3>
2329 2486
2330모델을 선택하여 기본값으로 저장했습니다. 예를 들어 `/model <name>` 또는 `/model` 선택기의 `Enter`를 사용하고 Claude Code가 사용자 설정 파일 `~/.claude/settings.json`에 선택을 쓸 수 없었습니다. 스위치 자체가 적용되었으므로 현재 세션은 선택한 모델에서 실행되지만 기본값은 변경되지 않으며 다음 세션은 이전 값에서 시작됩니다.2487모델을 기본값으로 저장하도록 선택했습니다. 예를 들어 `/model <name>` 또는 `/model` 선택기에서 `Enter`를 사용하고 Claude Code가 사용자 설정 파일 `~/.claude/settings.json`에 선택을 쓸 수 없었습니다. 전환 자체가 적용되었으므로 현재 세션은 선택한 모델에서 실행되지만 기본값은 변경되지 않으며 다음 세션은 이전 값에서 시작됩니다.
2331 2488
2332```text theme={null}2489```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)2490Set 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 2492
2336파일 경로 뒤의 이유는 실패한 것을 말합니다:2493파일 경로 뒤의 이유는 실패한 것을 말합니다:
2337 2494
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)을 참조하십시오.2495* **`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)을 참조하십시오.2496* **`isn't valid JSON`**: 디스크의 파일이 구문 분석되지 않으며 Claude Code는 읽을 수 없는 내용을 덮어쓰지 않고 그대로 둡니다. 구문 오류를 수정한 다음 다시 전환합니다. [손상된 설정 파일 수정](/docs/ko/settings#fix-a-broken-settings-file)을 참조하십시오.
2340 2497
2341`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 공지는 3초 후에 쓰기가 완료되지 않았음을 의미합니다. 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 시작되는 모델을 확인하거나 `/model <name>`을 다시 실행합니다.2498`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)` 끝나는 알림은 쓰기가 3초 후에 완료되지 않았음을 의미합니다. 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델에서 시작되는지 확인하거나 `/model <name>`을 다시 실행합니다.
2342 2499
2343v2.1.265 이전에는 공지가 쓰기가 실패했을 때도 모델이 `saved as your default for new sessions`이라고 말했습니다.2500v2.1.265 이전에는 알림이 쓰기가 실패했을 때도 모델이 `saved as your default for new sessions`이라고 말했습니다.
2344 2501
2345<h3 id="thinking-type-enabled-is-not-supported-for-this-model">2502<h3 id="thinking-type-enabled-is-not-supported-for-this-model">
2346 thinking.type.enabled는 이 모델에서 지원되지 않습니다2503 thinking.type.enabled은 이 모델에서 지원되지 않습니다
2347</h3>2504</h3>
2348 2505
2349Claude Code 버전이 선택한 모델에 필요한 최소값보다 오래되었습니다. CLI가 모델이 더 이상 수락하지 않는 사고 구성을 보냈습니다.2506Claude Code 버전이 선택한 모델의 최소값보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 생각 구성을 보냈습니다.
2350 2507
2351```text theme={null}2508```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.2509API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
2354 2511
2355**할 일:**2512**할 일:**
2356 2513
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 이상이 필요합니다2514* `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을 선택합니다2515* 업그레이드할 수 없으면 `/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 이상이 필요합니다2516* [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 2517
2361<h3 id="effort-isnt-available-with-thinking-turned-off">2518<h3 id="effort-isnt-available-with-thinking-turned-off">
2362 사고가 꺼져 있을 때 노력을 사용할 수 없습니다2519 생각이 꺼져 있으면 노력을 사용할 수 없습니다
2363</h3>2520</h3>
2364 2521
2365[확장 사고](/docs/ko/model-config#extended-thinking)를 끄고 `high` 이상의 [노력 수준](/docs/ko/model-config#adjust-effort-level)에서 실행했습니다. 모델이 해당 조합을 수락하지 않으므로 API가 요청을 거부했습니다.2522[확장 생각](/docs/ko/model-config#extended-thinking)을 끄고 `high` 이상의 [노력 수준](/docs/ko/model-config#adjust-effort-level)에서 실행했습니다. 모델이 해당 조합을 허용하지 않으므로 API가 요청을 거부했습니다.
2366 2523
2367```text theme={null}2524```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)2525API 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```2526```
2370 2527
2528`·` 뒤의 힌트는 세션에 따라 다릅니다: 비대화형 세션에서는 `use --effort high (or the effortLevel setting)`로 읽고 Claude Desktop 앱이 실행하는 세션에서는 `you can lower effort to High`로 읽습니다.
2529
2371**할 일:**2530**할 일:**
2372 2531
2373* [노력 수준을 낮춥니다](/docs/ko/model-config#set-the-effort-level) `high` 이하로.2532* [노력 수준](/docs/ko/model-config#set-the-effort-level)을 `high` 이하로 낮춥니다.
2374* 사고를 다시 켭니다. 예를 들어 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars)을 설정 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](/docs/ko/settings-reference#alwaysthinkingenabled)를 제거합니다.2533* 생각을 다시 켭니다. 예를 들어 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars)을 설정 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](/docs/ko/settings-reference#alwaysthinkingenabled)를 제거합니다.
2375 2534
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가 거부하는 것을 알지 못하는 모델에서만 도달합니다.2535v2.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`를 대신 보냅니다.
2377 2536
2378<h3 id="thinking-budget-exceeds-output-limit">2537<h3 id="thinking-budget-exceeds-output-limit">
2379 사고 예산이 출력 제한을 초과합니다2538 생각 예산이 출력 제한을 초과합니다
2380</h3>2539</h3>
2381 2540
2382구성된 확장 사고 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.2541구성된 확장 생각 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다.
2383 2542
2384```text theme={null}2543```text theme={null}
2385API Error: 400 ... max_tokens must be greater than thinking.budget_tokens2544API Error: 400 ... max_tokens must be greater than thinking.budget_tokens
2386```2545```
2387 2546
2388Claude Code는 Anthropic API에서 이러한 값을 자동으로 조정합니다. 일반적으로 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars)이 제공자의 출력 제한보다 높게 설정되었거나 계획 모드가 사고 예산을 높일 때 Amazon Bedrock 또는 Google Cloud의 Agent Platform에서 이 오류를 봅니다.
2389
2390**할 일:**2547**할 일:**
2391 2548
2392* `MAX_THINKING_TOKENS`를 낮추거나 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를 사고 예산 이상으로 높입니다2549* [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를 생각 예산 이상으로 높입니다.
2393* [확장 사고](/docs/ko/model-config#extended-thinking)에서 예산이 출력 길이와 상호 작용하는 방식을 참조하십시오2550* [확장 생각](/docs/ko/model-config#extended-thinking)에서 예산이 출력 길이와 상호 작용하는 방식을 참조하십시오.
2394 2551
2395<h3 id="tool-use-or-thinking-block-mismatch">2552<h3 id="tool-use-or-thinking-block-mismatch">
2396 도구 사용 또는 사고 블록 불일치2553 도구 사용 또는 생각 블록 불일치
2397</h3>2554</h3>
2398 2555
2399대화 기록이 일관성 없는 상태로 API에 도달했습니다. 일반적으로 도구 호출이 중단되거나 턴이 스트림 중간에 편집된 후입니다.2556대화 기록이 일관성 없는 상태로 API에 도달했습니다.
2400 2557
2401```text theme={null}2558```text theme={null}
2402API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.2559API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
2413* Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.2570* Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`는 이를 지우지 않습니다.
2414* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/docs/ko/checkpointing)에서 체크포인트가 생성되고 복원되는 방식을 참조하십시오.2571* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 전의 체크포인트로 뒤로 이동하고 거기서 계속합니다. [체크포인팅](/docs/ko/checkpointing)에서 체크포인트가 생성되고 복원되는 방식을 참조하십시오.
2415 2572
2573<h3 id="invalid-data-in-redacted-thinking-block">
2574 redacted\_thinking 블록의 유효하지 않은 데이터
2575</h3>
2576
2577API가 대화 기록의 이전 턴이 포함하는 `redacted_thinking` 블록을 허용할 수 없기 때문에 400으로 요청을 거부했습니다.
2578
2579```text theme={null}
2580API Error: 400 ... Invalid `data` in `redacted_thinking` block
2581```
2582
2583Claude Code는 대화의 이전 생각을 요청에서 제외하고 한 번 다시 시도하므로 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했고 모든 이후 턴이 동일한 오류로 실패했습니다.
2584
2585**할 일:**
2586
2587* v2.1.281 이상에 있고 모든 턴이 이 오류로 실패하면 `claude update`를 실행하고 세션을 재개합니다.
2588* 오류가 지속되면 `/clear`를 실행하여 블록을 포함하지 않는 대화를 시작합니다.
2589
2416<h3 id="unsupported-tool-content-removed">2590<h3 id="unsupported-tool-content-removed">
2417 지원되지 않는 도구 내용이 제거되었습니다2591 지원되지 않는 도구 내용이 제거되었습니다
2418</h3>2592</h3>
2419 2593
2420Claude Code가 Anthropic API에 직접 연결되고 저장된 세션을 로드하거나 미리 볼 때 Anthropic API가 수락하지 않는 도구 내용을 제거하고 두 사고 블록 사이에 제거된 내용이 있던 위치에 이 줄을 남깁니다:2594Claude Code가 Anthropic API에 직접 연결되고 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 내용을 제거하고 제거된 내용이 두 생각 블록 사이에 있던 위치에 이 줄을 남깁니다:
2421 2595
2422```text theme={null}2596```text theme={null}
2423[Unsupported tool content removed]2597[Unsupported tool content removed]
2424```2598```
2425 2599
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 오류로 실패했습니다.2600이러한 내용은 일반적으로 다른 제공자의 도구 호출을 변환하는 [`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 2601
2428**할 일:**2602**할 일:**
2429 2603
2431* 재개된 세션의 모든 턴이 대신 400 오류로 실패하면 `claude update`를 실행하고 세션을 다시 재개합니다. v2.1.246 이전 버전은 내용을 제거하지 않습니다.2605* 재개된 세션의 모든 턴이 대신 400 오류로 실패하면 `claude update`를 실행하고 세션을 다시 재개합니다. v2.1.246 이전 버전은 내용을 제거하지 않습니다.
2432 2606
2433<h3 id="role-system-must-precede-an-assistant-message">2607<h3 id="role-system-must-precede-an-assistant-message">
2434 role 'system' must precede an 'assistant' message2608 역할 'system'은 'assistant' 메시지 앞에 와야 합니다
2435</h3>2609</h3>
2436 2610
2437API가 대화에서 수락하지 않는 위치에 시스템 메시지가 있기 때문에 400으로 요청을 거부했습니다:2611API가 대화에서 허용하지 않는 위치에 시스템 메시지가 있기 때문에 400으로 요청을 거부했습니다:
2438 2612
2439```text theme={null}2613```text theme={null}
2440API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...2614API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...
2441```2615```
2442 2616
2443Claude Code는 일부 미리 알림 및 첨부 텍스트를 대화 내 시스템 메시지로 보냅니다. API가 하나의 위치를 거부하면 Claude Code는 요청을 한 번 다시 시도하고 해당 텍스트를 일반 사용자 메시지로 대신 보냅니다. `top-level 'system' parameter for the initial system prompt` 사용과 같은 API의 형제 배치 표현은 동일한 복구를 받습니다.2617Claude Code는 일부 미리 알림 및 첨부 텍스트를 대화 내 시스템 메시지로 보냅니다. API가 하나의 위치를 거부하면 Claude Code는 해당 텍스트를 대신 일반 사용자 메시지로 보내는 요청을 한 번 다시 시도합니다. API의 형제 배치 표현(예: `use the top-level 'system' parameter for the initial system prompt`)은 동일한 복구를 받습니다.
2444 2618
2445오류가 나타나면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 일반적으로 Claude Code와 API 사이의 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)가 시스템 메시지를 추가했거나 대화를 재정렬했음을 의미합니다.2619오류가 나타나면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 일반적으로 Claude Code와 API 사이의 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했거나 대화를 재정렬했음을 의미합니다.
2446 2620
2447**할 일:**2621**할 일:**
2448 2622
2449* `/clear`를 실행하여 새 대화를 시작합니다. 오류가 거기서도 돌아오면 원인은 저장된 대화가 아닌 요청 경로에 있습니다.2623* `/clear`를 실행하여 새 대화를 시작합니다. 오류가 거기서도 반환되면 원인은 저장된 대화가 아닌 요청 경로에 있습니다.
2450* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 통해 구성된 프록시 또는 게이트웨이 뒤에서 오류가 모든 턴에서 반복되면 프록시 없이 연결하여 원인을 확인하고 오류를 운영하는 사람에게 보고합니다2624* [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)을 통해 구성된 프록시 또는 게이트웨이 뒤에서 오류가 모든 턴에서 반복되면 프록시 없이 연결하여 소스를 확인하고 오류를 운영하는 사람에게 보고합니다.
2451 2625
2452v2.1.280 이전에는 Claude Code가 이 표현을 인식하지 못했으므로 거부된 시스템 메시지가 Claude Code 자체가 보낸 것일 때도 오류가 나타났고 대화의 모든 이후 턴이 동일한 방식으로 실패했습니다.2626v2.1.280 이전에는 Claude Code가 이 표현을 인식하지 못했으므로 거부된 시스템 메시지가 Claude Code 자체가 보낸 것일 때도 오류가 나타났고 대화의 모든 이후 턴이 동일한 방식으로 실패했습니다.
2453 2627
2454<h3 id="invalid-encrypted-content-in-search-result-block">2628<h3 id="invalid-encrypted-content-in-search-result-block">
2455 Invalid encrypted\_content in search\_result block2629 search\_result 블록의 유효하지 않은 encrypted\_content
2456</h3>2630</h3>
2457 2631
2458API가 대화 기록이 해독할 수 없는 호스팅된 웹 검색 내용을 보유하고 있기 때문에 400으로 요청을 거부했습니다. 표현은 읽을 수 없는 필드를 이름으로 지정합니다:2632API가 대화 기록이 보유한 호스팅된 웹 검색 내용을 해독할 수 없기 때문에 400으로 요청을 거부했습니다. 표현은 읽을 수 없는 필드를 표시합니다:
2459 2633
2460```text theme={null}2634```text theme={null}
2461API Error: 400 messages.21.content.0: Invalid `encrypted_content` in `search_result` block2635API Error: 400 ... Invalid `encrypted_content` in `search_result` block
2462API Error: 400 messages.21.content.3.citations.0: Invalid `encrypted_index` in `text` block2636API Error: 400 ... Invalid `encrypted_index` in `text` block
2463API Error: 400 Failed to decrypt web search result content2637API Error: 400 ... Failed to decrypt web search result content
2638API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block
2464```2639```
2465 2640
2466API의 호스팅된 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)의 결과는 API만 읽을 수 있는 암호화된 필드를 전달합니다. API는 다른 조직을 위해 생성된 내용과 같이 해독할 수 없는 내용을 재생하는 요청을 거부합니다.2641API의 호스팅된 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)의 결과는 API만 읽을 수 있는 암호화된 필드를 포함합니다. `encrypted_stdout` 표현은 이러한 결과를 읽은 호스팅된 코드 실행 프로그램의 출력을 표시하며, API는 이를 암호화합니다. API는 해독할 수 없는 내용(예: 다른 조직을 위해 생성된 내용)을 재생하는 요청을 거부합니다.
2467 2642
2468Claude Code의 자체 [WebSearch 도구](/docs/ko/tools-reference#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로 이러한 블록은 일반적으로 호스팅된 웹 검색을 자체적으로 실행한 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 대화에 도달합니다.2643Claude Code의 자체 [WebSearch 도구](/docs/ko/tools-reference#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로 이러한 블록은 일반적으로 호스팅된 웹 검색을 자체적으로 실행한 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 대화에 도달합니다.
2469 2644
2470거부된 블록은 대화 기록에 남아 있으므로 모든 이후 턴과 `/compact`는 동일한 방식으로 실패합니다.2645세 가지 웹 검색 표현의 경우 Claude Code는 검색 호출, 결과 및 인용을 보내는 것에서 제외하고 요청을 한 번 다시 시도하므로 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 표현에는 그러한 복구가 없으므로 해당 메시지는 여전히 도달합니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했고 모든 이후 턴 및 `/compact`가 동일한 방식으로 실패했습니다.
2471 2646
2472**할 일:**2647**할 일:**
2473 2648
2474* `/clear`를 실행하거나 새 세션을 시작합니다. 새 대화는 거부된 블록을 전달하지 않습니다2649* v2.1.281 이상에 있고 모든 턴이 웹 검색 표현 중 하나로 실패하면 `claude update`를 실행하고 세션을 재개합니다.
2475* Claude Code를 프록시 또는 게이트웨이 뒤에서 실행하면 오류를 운영하는 사람에게 보고합니다2650* 오류가 지속되거나 메시지가 `encrypted_stdout`을 표시하면 `/rewind`를 실행하여 내용을 추가한 턴 전의 체크포인트로 뒤로 이동하거나 `/clear`를 실행하여 이를 포함하지 않는 대화를 시작합니다.
2651* Claude Code를 프록시 또는 게이트웨이 뒤에서 실행하면 오류를 운영하는 사람에게 보고합니다.
2476 2652
2477<h3 id="usage-policy-refusal">2653<h3 id="usage-policy-refusal">
2478 사용 정책 거부2654 사용 정책 거부
2479</h3>2655</h3>
2480 2656
2481API가 대화의 내용이 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 응답을 거부했습니다. 메시지에는 거부가 잘못되었다고 생각하면 지원팀에 인용할 수 있는 요청 ID가 포함됩니다.2657API가 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거한 대화의 내용 때문에 응답을 거부했습니다.
2658
2659메시지에는 정책 거부가 잘못되었다고 생각하는 경우 지원팀에 인용할 수 있는 요청 ID 및 메시지 ID가 포함됩니다.
2482 2660
2483```text theme={null}2661```text theme={null}
2484API Error: Opus 4.6 can't help with this. Start a new session to continue.2662API 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/aup2664Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup
2487```2665```
2488 2666
2489메시지는 거부한 모델을 이름으로 지정하거나 모델이 기록되지 않으면 `Claude`를 이름으로 지정합니다.2667메시지는 거부한 모델을 표시하거나 모델이 기록되지 않은 경우 `Claude`를 표시합니다.
2490 2668
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)를 참조하십시오.2669확인은 전체 대화를 평가하므로 같은 세션에서 새 메시지를 보내면 일반적으로 동일한 거부를 다시 트리거합니다. 동일한 내용이 디스크의 기록에 여전히 포함되어 있으므로 `--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 2670
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.`로 읽혔습니다.2671v2.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 2672
2495**할 일:**2673**할 일:**
2496 2674
2497* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다시 표현하거나 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.2675* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다시 표현하거나 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.
2498* 어느 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 동일한 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.2676* 어떤 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 사용 가능합니다.
2499* [비대화형 모드](/docs/ko/headless)(`-p`)에서 되감기를 사용할 수 없으므로 `--continue` 없이 새 세션에서 다시 표현된 프롬프트로 다시 시도합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.2677* [비대화형 모드](/docs/ko/headless)(`-p`)에서 되감기를 사용할 수 없으므로 새 세션에서 `--continue` 없이 다시 표현된 프롬프트로 다시 시도합니다. 정책 확인은 모델에 따라 다르므로 `/model`로 다른 모델로 전환하면 일부 경우에 거부를 해결할 수도 있습니다.
2500 2678
2501<h3 id="safety-measures-flagged-a-cybersecurity-topic">2679<h3 id="safety-measures-flagged-a-cybersecurity-topic">
2502 안전 조치가 사이버 보안 주제를 플래그했습니다2680 안전 조치가 사이버 보안 주제를 플래그했습니다
2503</h3>2681</h3>
2504 2682
2505모델의 안전 조치가 대화의 내용을 사이버 보안 주제로 플래그했습니다. 메시지는 요청을 플래그한 모델을 이름으로 지정합니다:2683모델의 안전 조치가 대화의 내용을 사이버 보안 주제로 플래그했습니다. 메시지는 요청을 플래그한 모델을 표시합니다:
2506 2684
2507```text theme={null}2685```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-claude2686API 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```2687```
2510 2688
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)합니다.2689메시지는 정당한 사이버 보안 작업에 대한 액세스를 부여하는 [사이버 검증 프로그램](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 2690
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) 메시지를 생성합니다.2691[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 2692
2515안전 조치 자체는 서버 측이며 v2.1.203보다 앞서 있습니다. 이후 클라이언트 릴리스는 메시지의 표현만 변경했습니다.2693안전 조치 자체는 서버 측이며 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.`를 추가했습니다.2694v2.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:`로 읽혔고 면제 양식 링크가 뒤따랐습니다.2695v2.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 2696
2519**할 일:**2697**할 일:**
2520 2698
2521* 작업에 이 내용이 필요하면 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다2699* 작업에 이 내용이 필요하면 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다.
2522* 요청이 사이버 보안 주제가 아닌 경우 `/feedback`을 실행하여 거짓 양성을 보고합니다2700* 요청이 사이버 보안 주제가 아니었으면 `/feedback`을 실행하여 거짓 양성을 보고합니다.
2523* 동일한 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.2701* 같은 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 전의 체크포인트로 뒤로 이동한 다음 다른 접근 방식을 취합니다. [체크포인팅](/docs/ko/checkpointing)을 참조하십시오.
2524 2702
2525<h2 id="installation-errors">2703<h2 id="installation-errors">
2526 설치 오류2704 설치 오류
2550 업데이트를 다운로드하는 동안 연결이 끊어졌습니다2728 업데이트를 다운로드하는 동안 연결이 끊어졌습니다
2551</h3>2729</h3>
2552 2730
2553`claude install`, `claude update` 또는 [자동 업데이터](/docs/ko/setup#auto-updates)가 Claude Code 바이너리를 가져오는 동안 다운로드 서버로의 연결이 끊어졌으며, 재시도로 복구되지 않았습니다. Claude Code는 연결이 끊어지거나, 전송이 중단되거나, 다운로드된 파일이 체크섬에 실패할 때 다운로드를 재시도하며, 총 3번까지 시도합니다. 404와 같은 완료된 HTTP 오류는 서버가 이미 응답했기 때문에 재시도되지 않습니다. v2.1.202 이전에는 단일 연결 끊김이 재시도 대신 단순한 오류 `aborted`로 다운로드를 즉시 실패했습니다.2731다운로드 서버로의 연결이 `claude install` 또는 `claude update`가 Claude Code 바이너리를 가져오는 동안 끊어졌으며, 재시도로 복구되지 않았습니다. Claude Code는 연결이 끊어지거나, 전송이 중단되거나, 다운로드된 파일이 체크섬에 실패할 때 다운로드를 재시도하며, 총 3번까지 시도합니다. 404와 같은 완료된 HTTP 오류는 서버가 이미 응답했기 때문에 재시도되지 않습니다. v2.1.202 이전에는 단일 연결 끊김이 재시도 대신 단순한 오류 `aborted`로 다운로드를 즉시 실패했습니다.
2554 2732
2555```text theme={null}2733```text theme={null}
2556The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.2734The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.
2560 2738
2561연결된 상태이지만 10분 이내에 완료되지 않는 다운로드는 `Download timed out: exceeded the total deadline` 메시지로 실패합니다. Claude Code는 시간 초과된 다운로드를 재시도하지 않습니다. 왜냐하면 기한 내에 완료할 수 없을 정도로 느린 연결은 즉시 재시도에서도 완료되지 않기 때문입니다. 아래 단계는 두 메시지 모두에 적용됩니다.2739연결된 상태이지만 10분 이내에 완료되지 않는 다운로드는 `Download timed out: exceeded the total deadline` 메시지로 실패합니다. Claude Code는 시간 초과된 다운로드를 재시도하지 않습니다. 왜냐하면 기한 내에 완료할 수 없을 정도로 느린 연결은 즉시 재시도에서도 완료되지 않기 때문입니다. 아래 단계는 두 메시지 모두에 적용됩니다.
2562 2740
2563일반적인 원인은 긴 전송을 완료하기 전에 닫는 프록시 또는 게이트웨이입니다. Claude Code 바이너리는 큰 다운로드이므로, 일반 API 트래픽에는 영향을 주지 않는 프록시 연결 제한이 여전히 이를 중단할 수 있습니다.2741프록시 또는 게이트웨이는 완료되기 전에 긴 전송을 닫을 수 있으며, Claude Code 바이너리는 큰 다운로드입니다.
2564 2742
2565**수행할 작업:**2743**수행할 작업:**
2566 2744
2573 명령줄 오류2751 명령줄 오류
2574</h2>2752</h2>
2575 2753
2576이러한 오류는 `claude` 명령줄과 그 하위 명령어에서 발생하며, 프롬프트에서 제출한 명령어 이름에서도 발생합니다. 또한 셸 명령어를 실행하여 컨텍스트를 수집한 후 프롬프트를 실행하는 `/security-review` 같은 명령어에서도 발생합니다. 이들은 CLI를 다시 시작하는 `/tui`에서도 발생합니다.2754이러한 오류는 `claude` 명령줄과 그 하위 명령어, 프롬프트에서 제출하는 명령어 이름, 그리고 셸 명령어를 실행하여 컨텍스트를 수집한 후 프롬프트를 실행하는 `/security-review` 같은 명령어에서 발생합니다. 또한 CLI를 다시 시작하는 `/tui`에서도 발생합니다.
2577 2755
2578<h3 id="conflict-between-bg-and-print">2756<h3 id="conflict-between-bg-and-print">
2579 \--bg와 --print 간의 충돌2757 \--bg와 --print 간의 충돌
2580</h3>2758</h3>
2581 2759
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 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 조용히 생성했습니다.2760이 메시지는 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 2761
2584```text theme={null}2762```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>'`.2763--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 2765
2588**해야 할 일:**2766**해야 할 일:**
2589 2767
2590* `-p` 또는 `--print`를 제거하세요. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령어입니다. [셸에서 새 에이전트 디스패치](/docs/ko/agent-view#from-your-shell)를 참조하세요.2768* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령어입니다. [셸에서 새 에이전트 디스패치](/docs/ko/agent-view#from-your-shell)를 참조하세요.
2591* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 생성하는 대신 결과를 인쇄하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행하세요.2769* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 만드는 대신 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다.
2592 2770
2593<h3 id="invalid-agents-configuration">2771<h3 id="invalid-agents-configuration">
2594 잘못된 --agents 구성2772 잘못된 --agents 구성
2595</h3>2773</h3>
2596 2774
2597`--agents`에 전달한 값이 유효하지 않아서 `claude`가 세션을 시작하는 대신 코드 1로 종료됩니다. `--safe-mode`, `--resume`, 또는 `--continue`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars#variables)를 설정하면 Claude Code는 값을 확인하지 않고 세션을 시작합니다. v2.1.242 이전에는 Claude Code가 어쨌든 세션을 시작했고 로드할 수 없는 정의를 생략했습니다.2775`--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 2776
2599```text theme={null}2777```text theme={null}
2600Error: Invalid --agents configuration:2778Error: Invalid --agents configuration:
2601<what failed>2779<what failed>
2602```2780```
2603 2781
2604첫 번째 줄 다음에 오는 내용은 값이 어떻게 실패했는지에 따라 다릅니다. Claude Code는 이러한 확인을 순서대로 실행하고 실패하는 첫 번째 확인에서 중지합니다. 값에 두 가지 문제가 있으면 첫 번째를 수정한 후에만 두 번째를 볼 수 있습니다:2782첫 번째 줄 다음에 오는 내용은 값이 어떻게 실패했는지에 따라 달라집니다. Claude Code는 이러한 확인을 순서대로 실행하고 실패하는 첫 번째 확인에서 중지합니다. 값에 두 가지 문제가 있으면 첫 번째를 수정한 후에만 두 번째를 볼 수 있습니다:
2783
27841. 값이 `{`로 시작하지만 JSON으로 파싱되지 않거나 `--agents` 파일의 내용이 파싱되지 않으면 Claude Code는 JSON 파서의 메시지를 포함하는 `invalid JSON:` 줄 하나를 출력합니다.
27852. 파싱되지만 에이전트 정의가 [CLI 정의 하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)의 스키마와 일치하지 않으면 Claude Code는 문제당 한 줄을 출력합니다.
27863. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다.
2605 2787
26061. 값이 JSON으로 파싱되지 않으면 Claude Code는 JSON 파서의 메시지를 포함하는 `invalid JSON:` 줄 하나를 인쇄합니다.2788문제 줄이 20개를 초과하면 Claude Code는 처음 20개를 출력하고 나머지를 `…and N more`로 바꿉니다.
26072. 파싱되지만 에이전트 정의가 [CLI 정의 하위 에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)의 스키마와 일치하지 않으면 Claude Code는 문제당 한 줄을 인쇄합니다.
26083. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 인쇄합니다.
2609 2789
2610문제 줄이 20개를 초과하면 Claude Code는 처음 20개를 인쇄하고 나머지를 `…and N more`로 바꿉니다.2790`--print`를 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일의 경로](/docs/ko/sub-agents#choose-the-subagent-scope)도 허용합니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 허용했고 파일 경로를 유효하지 않은 JSON으로 취급했습니다. 파일 형식에는 이 메시지 대신 출력되는 자체 거부가 있습니다:
2791
2792* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: Claude Code가 대화형 세션에서 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나 `-p`를 추가하여 파일에서 읽습니다.
2793* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽혀지므로 셸이 손상시킨 인라인 JSON도 이런 식으로 실패할 수 있습니다. 경로 또는 인용을 확인하고 명령어를 다시 실행합니다.
2611 2794
2612**해야 할 일:**2795**해야 할 일:**
2613 2796
2614* 메시지가 나열한 각 문제를 수정한 후 명령어를 다시 실행하세요. [CLI 정의 하위 에이전트가 사용하는 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.2797* 메시지가 나열한 각 문제를 수정한 후 명령어를 다시 실행합니다. [CLI 정의 하위 에이전트가 사용하는 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 참조하세요.
2615 2798
2616<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">2799<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">
2617 클라우드 세션을 --restricted 세션에서 생성할 수 없음2800 클라우드 세션을 --restricted 세션에서 만들 수 없음
2618</h3>2801</h3>
2619 2802
2620[`--restricted`](/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 이 세션에서 [클라우드 세션](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)을 생성하기를 거부합니다. 새 세션이 제한된 프로세스 외부에서 실행되고 제한된 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:2803[`--restricted`](/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 이 세션에서 [클라우드 세션](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션이 제한된 프로세스 외부에서 실행되고 제한된 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:
2621 2804
2622```text theme={null}2805```text theme={null}
2623Cloud sessions cannot be created from a --restricted session: they would not enforce it.2806Cloud sessions cannot be created from a --restricted session: they would not enforce it.
2625 2808
2626**해야 할 일:**2809**해야 할 일:**
2627 2810
2628* 제한된 세션에서 로컬로 작업을 실행하세요.2811* 제한된 세션에서 로컬로 작업을 실행합니다.
2629* 세션이 어떻게 시작되었는지 제어할 수 있으면 `--restricted` 없이 새 `claude` 세션을 시작하고 거기서 클라우드 세션을 생성하세요.2812* 세션이 어떻게 시작되었는지 제어할 수 있으면 `--restricted` 없이 새 `claude` 세션을 시작하고 거기서 클라우드 세션을 만듭니다.
2630 2813
2631v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.2814v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었고 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부했습니다.
2632 2815
2633<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">2816<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">
2634 조직의 정책에 의해 클라우드 세션이 비활성화됨2817 조직의 정책에 의해 클라우드 세션이 비활성화됨
2640Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.2823Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.
2641```2824```
2642 2825
2643이 메시지는 [터미널에서 클라우드 세션을 생성](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)할 때 나타나며 `/teleport`, `/remote-env`, 또는 `/web-setup` 같은 클라우드 세션이 필요한 명령어를 제출할 때도 나타납니다. v2.1.268 이전에는 이러한 명령어 중 하나를 제출하면 대신 [`Unknown command`](#unknown-command)를 반환했습니다.2826메시지는 [터미널에서 클라우드 세션을 만들](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud) 때 나타나고 `/teleport`, `/remote-env`, 또는 `/web-setup` 같은 클라우드 세션이 필요한 명령어를 제출할 때 나타납니다. v2.1.268 이전에는 이러한 명령어 중 하나를 제출하면 대신 [`Unknown command`](#unknown-command)를 반환했습니다.
2644 2827
2645이것은 서버 측 조직 정책이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.2828이것은 서버 측 조직 정책이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.
2646 2829
2648 2831
2649**해야 할 일:**2832**해야 할 일:**
2650 2833
2651* 조직의 [Owner](/docs/ko/server-managed-settings#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청하세요.2834* 조직의 [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를 다시 시작하고 다시 시도하세요.2835* 메시지에서 정책을 확인할 수 없다고 하면 네트워크 연결을 확인한 후 Claude Code를 다시 시작하고 다시 시도합니다.
2653 2836
2654<h3 id="the-json-schema-value-is-not-a-valid-json-schema">2837<h3 id="the-json-schema-value-is-not-a-valid-json-schema">
2655 \--json-schema 값이 유효한 JSON Schema가 아님2838 \--json-schema 값이 유효한 JSON Schema가 아님
2656</h3>2839</h3>
2657 2840
2658[비대화형 모드](/docs/ko/headless#get-structured-output)에서 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하는 대신 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용한 모든 스키마는 유효하지 않은 것으로 처리되었습니다.2841[비대화형 모드](/docs/ko/headless#get-structured-output)에서 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하는 대신 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했고 `format` 키워드를 사용하는 모든 스키마는 유효하지 않은 것으로 처리되었습니다.
2659 2842
2660```text theme={null}2843```text theme={null}
2661Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values2844Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values
2662```2845```
2663 2846
2664두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 이름 지정합니다. `"format": "email"` 같은 `format` 키워드를 사용하는 스키마는 유효합니다: Claude Code는 `format`을 주석으로 수용하고 적용하지 않습니다.2847두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 이름 지정합니다. `"format": "email"` 같은 `format` 키워드를 사용하는 스키마는 유효합니다: Claude Code는 `format`을 주석으로 허용하고 적용하지 않습니다.
2665 2848
2666Claude Code는 스키마 컴파일 전에 두 가지 확인을 실행합니다: 파싱 불가능한 JSON 값을 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON을 `Error: --json-schema must be a JSON object`로 거부합니다.2849Claude Code는 스키마 컴파일 전에 두 가지 확인을 실행합니다: 파싱할 수 없는 JSON 값을 `Error: --json-schema is not valid JSON`으로 거부하고 유효한 JSON이지만 객체가 아닌 것을 `Error: --json-schema must be a JSON object`로 거부합니다.
2667 2850
2668**해야 할 일:**2851**해야 할 일:**
2669 2852
2670* 진단이 이름 지정한 스키마 부분을 수정한 후 명령어를 다시 실행하세요.2853* 진단이 이름 지정한 스키마 부분을 수정한 후 명령어를 다시 실행합니다.
2671* 진단이 `schema too large`이면 스키마의 중첩과 `$ref` 재사용을 줄이세요.
2672* [구조화된 출력 가져오기](/docs/ko/headless#get-structured-output)에서 작동하는 스키마와 명령어를 참조하세요.2854* [구조화된 출력 가져오기](/docs/ko/headless#get-structured-output)에서 작동하는 스키마와 명령어를 참조하세요.
2673 2855
2674<h3 id="settings-file-exceeds-the-2mib-limit">2856<h3 id="settings-file-exceeds-the-2mib-limit">
2675 설정 파일이 2MiB 제한을 초과함2857 설정 파일이 2MiB 제한을 초과함
2676</h3>2858</h3>
2677 2859
2678[`--settings`](/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 크므로 `claude`가 로드하는 대신 시작 시 코드 1로 종료됩니다. 설정 파일은 작은 JSON 문서이므로 이 크기의 파일은 보통 경로가 잘못된 파일을 가리킵니다. v2.1.214 이전에는 Claude Code가 크기 확인 없이 파일을 읽었으며, 수 기가바이트 파일이나 `/dev/zero` 같은 장치 파일이 메모리를 무한정 증가시켰습니다.2860[`--settings`](/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 크므로 `claude`가 시작 시 코드 1로 종료되고 로드하지 않습니다. v2.1.214 이전에는 Claude Code가 크기 확인 없이 파일을 읽었고 수 기가바이트 파일이나 `/dev/zero` 같은 장치 파일이 메모리를 무한정 증가시켰습니다.
2679 2861
2680```text theme={null}2862```text theme={null}
2681Error: Settings file exceeds the 2MiB limit: /path/to/settings.json2863Error: Settings file exceeds the 2MiB limit: /path/to/settings.json
2682```2864```
2683 2865
2684Claude Code는 일반 파일이 아닌 `--settings` 경로를 같은 방식으로 거부합니다: 장치, FIFO 또는 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`을 보고하고 경로를 따르며, 디렉토리는 `EISDIR` 이유를 보고합니다.2866Claude Code는 일반 파일이 아닌 `--settings` 경로를 같은 방식으로 거부합니다: 장치, FIFO 또는 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`을 보고하고 경로를 따르며 디렉토리는 `EISDIR` 이유를 보고합니다.
2685 2867
2686**해야 할 일:**2868**해야 할 일:**
2687 2869
2688* `--settings`를 2MiB 미만의 일반 JSON 설정 파일로 지정하세요. 형식은 [설정](/docs/ko/settings)을 참조하세요.2870* `--settings`를 2MiB 미만의 일반 JSON 설정 파일로 지정합니다. 형식은 [설정](/docs/ko/settings)을 참조하세요.
2689 2871
2690<h3 id="the-current-directory-no-longer-exists">2872<h3 id="the-current-directory-no-longer-exists">
2691 현재 디렉토리가 더 이상 존재하지 않음2873 현재 디렉토리가 더 이상 존재하지 않음
2692</h3>2874</h3>
2693 2875
2694셸이 디렉토리에 들어간 후 삭제되거나 이동된 디렉토리에서 `claude`를 시작했습니다. 예를 들어 worktree 또는 다른 셸이 제거한 임시 디렉토리입니다. Claude Code가 작업 디렉토리를 읽을 수 없어서 대화형 및 [비대화형](/docs/ko/headless) 모드 모두에서 세션을 시작하기 전에 코드 1로 종료됩니다. v2.1.239 이전에는 Claude Code가 축소된 번들 소스와 stderr의 원본 `ENOENT ... uv_cwd` 스택으로 충돌했습니다.2876셸이 디렉토리에 들어간 후 삭제되거나 이동된 디렉토리에서 `claude`를 시작했습니다. 예를 들어 다른 셸이 제거한 worktree 또는 임시 디렉토리입니다. Claude Code가 작업 디렉토리를 읽을 수 없으므로 대화형 및 [비대화형](/docs/ko/headless) 모드 모두에서 세션을 시작하기 전에 코드 1로 종료됩니다. v2.1.239 이전에는 Claude Code가 축소된 번들 소스와 stderr의 원시 `ENOENT ... uv_cwd` 스택으로 충돌했습니다.
2695 2877
2696```text theme={null}2878```text theme={null}
2697The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.2879The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
2700 2882
2701원인과 해결책은 두 형식 모두 동일합니다.2883원인과 해결책은 두 형식 모두 동일합니다.
2702 2884
2703Claude Code가 다른 이유(예: 권한 변경)로 작업 디렉토리를 읽을 수 없으면 메시지가 오류 코드를 이름 지정합니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`2885Claude Code가 권한 변경 같은 다른 이유로 작업 디렉토리를 읽을 수 없으면 메시지는 오류 코드를 이름 지정합니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`
2704 2886
2705macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive의 디렉토리에 대한 `EPERM`은 보통 macOS가 터미널 앱을 해당 폴더에서 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령어도 같은 방식으로 실패합니다: `ls`는 `sudo`를 사용해도 `Operation not permitted`를 보고합니다.2887macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive의 디렉토리에 대한 `EPERM`은 보통 macOS가 터미널 앱을 해당 폴더에서 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령어도 같은 방식으로 실패합니다: `ls`는 `sudo`를 사용해도 `Operation not permitted`를 보고합니다.
2706 2888
2707**해야 할 일:**2889**해야 할 일:**
2708 2890
2709* 홈 또는 프로젝트 디렉토리 같은 존재하는 디렉토리로 변경한 후 `claude`를 다시 실행하세요.2891* 홈 또는 프로젝트 디렉토리 같은 존재하는 디렉토리로 변경한 후 `claude`를 다시 실행합니다.
2710* 디렉토리가 같은 경로에서 다시 생성되었으면 셸이 여전히 삭제된 디렉토리를 보유하고 있습니다. `cd "$PWD"`를 실행하거나 디렉토리를 나갔다가 다시 들어간 후 `claude`를 실행하세요.2892* 디렉토리가 같은 경로에서 다시 생성되었으면 셸이 여전히 삭제된 것을 보유합니다. `cd "$PWD"`를 실행하거나 디렉토리를 나갔다가 다시 들어간 후 `claude`를 다시 실행합니다.
2711* macOS에서 `EPERM`의 경우 Cmd+Q로 터미널 앱을 종료하고 다시 열어서 해당 폴더로 돌아가 `claude`를 실행하세요. 해당 폴더의 `ls`가 여전히 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대한 폴더를 켠 후 터미널을 다시 열어세요.2893* macOS의 `EPERM`의 경우 Cmd+Q로 터미널 앱을 종료하고 다시 열고 해당 폴더로 돌아가 `claude`를 실행합니다. 해당 폴더의 `ls`가 여전히 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대한 폴더를 켠 후 터미널을 다시 엽니다.
2712 2894
2713<h3 id="temp-directory-refused-or-cannot-be-created">2895<h3 id="temp-directory-refused-or-cannot-be-created">
2714 임시 디렉토리가 거부되었거나 생성할 수 없음2896 임시 디렉토리가 거부되었거나 만들 수 없음
2715</h3>2897</h3>
2716 2898
2717macOS 및 Linux에서 Claude Code는 시작 시 개인 임시 디렉토리를 생성합니다. 시스템 임시 디렉토리 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars) 재정의 아래의 `claude-<uid>`입니다. 디렉토리를 생성할 수 없거나 해당 경로의 항목이 안전 확인에 실패하면 Claude Code는 실패를 stderr에 인쇄하고 세션을 시작하는 대신 코드 1로 종료됩니다:2899macOS 및 Linux에서 Claude Code는 시작 시 시스템 임시 디렉토리 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars) 재정의 아래에 `claude-<uid>` 개인 임시 디렉토리를 만듭니다. 디렉토리를 만들 수 없거나 해당 경로의 항목이 안전 확인에 실패하면 Claude Code는 세션을 시작하는 대신 실패를 stderr에 출력하고 코드 1로 종료됩니다:
2718 2900
2719```text wrap theme={null}2901```text wrap theme={null}
2720ENOSPC: no space left on device, mkdir '/tmp/claude-501'2902ENOSPC: no space left on device, mkdir '/tmp/claude-501'
2728 2910
2729**해야 할 일:**2911**해야 할 일:**
2730 2912
2731* `ENOSPC`의 경우 임시 디렉토리를 보유한 볼륨의 디스크 공간을 확보하세요.2913* `ENOSPC`의 경우 임시 디렉토리를 보유하는 볼륨의 디스크 공간을 확보합니다.
2732* `Refusing to use it` 형식의 경우 링크가 가리키는 것이 아닌 이름 지정된 항목 자체를 제거하고 Claude Code를 다시 시작하세요. `owned by uid` 형식의 경우 관리자 또는 해당 사용자만 제거할 수 있습니다.2914* `Refusing to use it` 형식의 경우 링크가 가리키는 것이 아니라 이름 지정된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자 또는 해당 사용자만 제거할 수 있습니다.
2733* `is not readable`의 경우 이름 지정된 디렉토리에서 `chmod 0700`을 실행하거나 제거한 후 다시 시작하세요.2915* `is not readable`의 경우 이름 지정된 디렉토리에서 `chmod 0700`을 실행하거나 제거하고 다시 시작합니다.
2734* 이러한 경우 중 하나에서 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 제어하는 디렉토리로 설정하고 Claude Code를 시작하세요. 거부된 경로는 그대로 두세요.2916* 이러한 경우 중 하나에서 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 제어하는 디렉토리로 설정하고 Claude Code를 시작하여 거부된 경로를 그대로 둡니다.
2735 2917
2736<h3 id="directory-couldnt-be-resolved-to-a-real-location">2918<h3 id="directory-couldnt-be-resolved-to-a-real-location">
2737 디렉토리를 실제 위치로 확인할 수 없음2919 디렉토리를 실제 위치로 확인할 수 없음
2738</h3>2920</h3>
2739 2921
2740작업 디렉토리의 하위 디렉토리에 대해 `/add-dir`을 실행했는데 Claude Code가 디렉토리를 실제 위치로 확인할 수 없습니다.2922작업 디렉토리의 하위 디렉토리에 대해 `/add-dir`을 실행했고 Claude Code가 디렉토리를 실제 위치로 확인할 수 없습니다.
2741 2923
2742작업 디렉토리의 하위 디렉토리에 대한 파일 액세스가 이미 있으므로 `/add-dir`은 해당 스킬, 명령어 및 에이전트만 로드합니다. 로드하기 전에 Claude Code는 심볼릭 링크가 확인된 디렉토리의 실제 위치가 작업 디렉토리 내부에 있는지 확인합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 로드하지 않고 이 메시지를 표시합니다:2924작업 디렉토리의 하위 디렉토리에 이미 파일 액세스 권한이 있으므로 `/add-dir`은 해당 스킬, 명령어 및 에이전트만 로드합니다. 로드하기 전에 Claude Code는 심볼릭 링크가 확인된 디렉토리의 실제 위치가 작업 디렉토리 내부에 있는지 확인합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 로드하지 않고 이 메시지를 표시합니다:
2743 2925
2744```text theme={null}2926```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.2927packages/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 2929
2748**해야 할 일:**2930**해야 할 일:**
2749 2931
2750* 경로가 작업 디렉토리 내부의 실제 디렉토리를 이름 지정하는지 확인한 후 `/add-dir`을 다시 실행하세요.2932* 경로가 작업 디렉토리 내부의 실제 디렉토리를 이름 지정하는지 확인한 후 `/add-dir`을 다시 실행합니다.
2751* 메시지는 파일 액세스를 변경하지 않습니다. 디렉토리의 `.claude/` 콘텐츠가 로드되지 않았음을 보고할 뿐입니다.2933* 메시지는 파일 액세스를 변경하지 않습니다. 디렉토리의 `.claude/` 콘텐츠가 로드되지 않았음을 보고할 뿐입니다.
2752 2934
2753v2.1.261 이전에는 작업 디렉토리가 `/net/<host>` 자동 마운트에 있을 때마다 이 메시지가 모든 `/add-dir <subdirectory>`에 대해 나타났습니다. Claude Code는 설계상 경로를 확인하기를 거부합니다. 디렉토리는 정상이었고 재시도할 수 없었습니다.2935v2.1.261 이전에는 작업 디렉토리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해 이 메시지가 나타났습니다. Claude Code는 설계상 경로를 확인하기를 거부합니다. 디렉토리는 정상이었고 재시도할 수 없었습니다.
2754 2936
2755<h3 id="workspace-not-trusted-when-starting-remote-control">2937<h3 id="workspace-not-trusted-when-starting-remote-control">
2756 Remote Control 시작 시 작업 공간을 신뢰하지 않음2938 Remote Control 시작 시 작업 영역을 신뢰하지 않음
2757</h3>2939</h3>
2758 2940
2759신뢰하지 않은 디렉토리에서 `claude remote-control` 또는 그 `claude rc` 별칭으로 [Remote Control](/docs/ko/remote-control) 서버 모드를 시작했습니다. 명령어는 작업 공간 신뢰 대화를 표시하지 않으므로 코드 1로 종료되고 수정 사항을 이름 지정합니다:2941신뢰하지 않은 디렉토리에서 `claude remote-control` 또는 그 `claude rc` 별칭으로 [Remote Control](/docs/ko/remote-control) 서버 모드를 시작했습니다. 명령어의 표준 입력 또는 표준 출력이 터미널이 아닐 때 이 메시지가 나타납니다. 예를 들어 하나가 리디렉션되거나 파이프되었을 때입니다. 명령어는 코드 1로 종료됩니다:
2760 2942
2761```text theme={null}2943```text theme={null}
2762Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.2944Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.
2763```2945```
2764 2946
2765홈 디렉토리에서 메시지가 다릅니다. 작업 공간 신뢰 대화가 홈 디렉토리에 대한 신뢰를 저장하지 않기 때문입니다. v2.1.214 이전에는 홈 디렉토리가 위의 메시지를 표시했으며, 그 조언은 거기서 성공할 수 없습니다.2947터미널에 나타나는 두 가지 변형도 신뢰 디렉토리를 켜는 것을 표시하기에 너무 작은 터미널이나 크기를 보고하지 않은 터미널에서 시작됩니다. 창을 확대하거나 일반 터미널 창으로 전환한 후 `claude rc`를 다시 실행합니다.
2948
2949홈 디렉토리에서 메시지는 다릅니다. 작업 영역 신뢰 대화가 홈 디렉토리에 대한 신뢰를 저장하지 않기 때문입니다. v2.1.214 이전에는 홈 디렉토리가 위의 메시지를 표시했고 그 조언은 거기서 성공할 수 없었습니다.
2766 2950
2767```text theme={null}2951```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).2952Error: 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```2953```
2770 2954
2955[`Trust <directory>?` 질문](/docs/ko/remote-control#requirements)에서 `n`을 답하거나 Enter를 누르면 명령어는 디렉토리를 이름 지정하는 `Remote Control did not start` 메시지를 출력하고 코드 1로 종료됩니다. `claude rc`를 다시 실행하여 `y`를 답합니다.
2956
2771**해야 할 일:**2957**해야 할 일:**
2772 2958
2773* 디렉토리에서 `claude`를 실행하고 [작업 공간 신뢰 대화](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 수락한 후 `claude remote-control`을 다시 실행하세요.2959* 먼저 터미널에서 디렉토리를 신뢰합니다: 거기서 `claude rc`를 실행하고 `y`를 답하거나 거기서 `claude`를 실행하고 [작업 영역 신뢰 대화](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 수락한 후 원래 명령어를 다시 실행합니다.
2774* 홈 디렉토리에서 프로젝트 디렉토리로 변경하고 거기서 Remote Control을 시작하세요.2960* 홈 디렉토리에서 프로젝트 디렉토리로 변경하고 거기서 Remote Control을 시작합니다.
2961
2962v2.1.284 이전에는 명령어가 터미널에서도 묻지 않았습니다.
2775 2963
2776<h3 id="not-carried-over-to-the-sessions-remote-control-starts">2964<h3 id="not-carried-over-to-the-sessions-remote-control-starts">
2777 Remote Control이 시작하는 세션으로 이월되지 않음2965 Remote Control이 시작하는 세션으로 이월되지 않음
2778</h3>2966</h3>
2779 2967
2780`remote-control` 동사 앞에 전역 `claude` 플래그로 [Remote Control](/docs/ko/remote-control)을 시작했습니다. Remote Control이 시작하는 세션을 제한하거나 구성할 플래그입니다. 예를 들어 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools` 또는 `--mcp-config`입니다. 동사 앞에 배치된 플래그는 절대 이러한 세션에 도달하지 않습니다. Claude Code는 플래그를 이름 지정하는 대신 시작을 거부합니다:2968[Remote Control](/docs/ko/remote-control)을 `remote-control` 동사 앞의 전역 `claude` 플래그로 시작했습니다. Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 예를 들어 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools` 또는 `--mcp-config`입니다. 동사 앞에 배치된 플래그는 절대 이러한 세션에 도달하지 않습니다. Claude Code는 대신 시작을 거부하고 플래그를 이름 지정합니다:
2781 2969
2782```text theme={null}2970```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`).2971Error: `--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```2972```
2785 2973
2786Claude Code는 `--verbose`, `--model` 또는 래퍼 주입 `--session-id` 또는 `--plugin-dir` 같은 드롭하기에 무해한 전역 플래그를 거부하지 않습니다: 이를 무시하고 Remote Control이 시작됩니다.2974Claude Code는 `--verbose`, `--model` 또는 래퍼 주입 `--session-id` 또는 `--plugin-dir` 같은 드롭하기에 무해한 전역 플래그를 거부하지 않습니다: 무시하고 Remote Control이 시작됩니다.
2787 2975
2788Claude Code는 또한 아직 무해한 것으로 인식하지 못하는 전역 플래그를 거부하므로 최신 릴리스에 추가된 플래그는 이후 릴리스가 이를 무해한 것으로 표시할 때까지 이 메시지에 나타날 수 있습니다.2976Claude Code는 또한 아직 무해한 것으로 인식하지 못하는 전역 플래그를 거부하므로 최신 릴리스에 추가된 플래그는 나중 릴리스가 무해한 것으로 표시할 때까지 이 메시지에 나타날 수 있습니다.
2789 2977
2790**해야 할 일:**2978**해야 할 일:**
2791 2979
2792* 동사 앞에서 플래그를 제거하고 [Remote Control의 자체 옵션](/docs/ko/remote-control#start-a-remote-control-session)을 그 뒤에 전달하세요. `claude remote-control --help`가 이를 나열합니다.2980* 동사 앞에서 플래그를 제거하고 [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이 시작하는 세션의 권한 모드를 설정하세요.2981* 거부된 플래그가 `--permission-mode`이면 `claude remote-control --permission-mode <mode>`를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다.
2794 2982
2795v2.1.248 이전에는 `claude remote-control`이 전역 플래그가 먼저 올 때 자체 플래그를 수용하지 않았으며, 명령어가 알 수 없는 옵션 오류로 실패했습니다.2983v2.1.248 이전에는 `claude remote-control`이 전역 플래그가 먼저 올 때 자체 플래그를 허용하지 않았고 명령어가 알 수 없는 옵션 오류로 실패했습니다.
2796 2984
2797<h3 id="claude-import-is-not-yet-available-in-this-build">2985<h3 id="claude-import-is-not-yet-available-in-this-build">
2798 claude import는 이 빌드에서 아직 사용할 수 없음2986 claude import는 이 빌드에서 아직 사용할 수 없음
2799</h3>2987</h3>
2800 2988
2801[`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했는데 Claude Code가 가져오기 흐름이 꺼져 있음을 발견했으므로 명령어가 이 메시지를 인쇄하는 대신 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드가 `import`를 프롬프트로 취급하고 이 메시지를 인쇄하는 대신 대화형 세션을 시작했습니다.2989[`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했고 Claude Code가 가져오기 흐름이 꺼져 있음을 발견했으므로 명령어가 이 메시지를 출력하는 대신 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드가 `import`를 프롬프트로 취급하고 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.
2802 2990
2803```text theme={null}2991```text theme={null}
2804`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.2992`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.
2805```2993```
2806 2994
2807Claude Code는 Anthropic에서 가져오고 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 보통 다음 중 하나입니다:2995Claude Code는 Anthropic에서 가져온 기능 플래그를 통해 `claude import`를 켜고 디스크에 캐시합니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 보통 다음 중 하나입니다:
2808 2996
2809* 설치 후 세션을 시작하지 않았으므로 Claude Code가 플래그를 아직 가져오지 않았습니다. 첫 번째 `claude import`는 기능을 사용할 수 있을 때도 이를 인쇄할 수 있습니다.2997* 설치 후 세션을 시작하지 않았으므로 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`는 사용할 수 없습니다.2998* 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`는 사용할 수 없습니다.2999* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)를 설정했습니다. 이는 기능 플래그 가져오기를 끕니다. 따라서 `claude import`는 사용할 수 없습니다.
2812 3000
2813**해야 할 일:**3001**해야 할 일:**
2814 3002
2815* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 후 종료하고 `claude import`를 다시 실행하세요.3003* 새로 설치한 경우 `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 서버를 읽지 않습니다.3004* 기능 플래그 가져오기가 꺼진 경우 구성을 직접 설정합니다: [`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 3005
2818<h3 id="could-not-read-claude-code-config">3006<h3 id="could-not-read-claude-code-config">
2819 Claude Code 구성을 읽을 수 없음3007 Claude Code 구성을 읽을 수 없음
2820</h3>3008</h3>
2821 3009
2822Claude Code가 로그인 및 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 동안 [`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했습니다. 하위 명령어는 가용성을 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화를 표시하지 않으므로 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 구성 파일이 있는 `claude import`가 대화형 세션을 시작했으며, 복구 대화가 파일을 처리했습니다.3010로그인 및 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 동안 [`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했습니다. 하위 명령어는 가용성을 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화를 표시하지 않으므로 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 구성 파일이 있는 `claude import`가 대화형 세션을 시작했고 복구 대화가 파일을 처리했습니다.
2823 3011
2824```text theme={null}3012```text theme={null}
2825Could not read Claude Code config — run `claude` with no arguments to recover it.3013Could not read Claude Code config — run `claude` with no arguments to recover it.
2827 3015
2828**해야 할 일:**3016**해야 할 일:**
2829 3017
2830* 인수 없이 `claude`를 실행하세요. Claude Code가 유효하지 않은 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행하세요.3018* 인수 없이 `claude`를 실행합니다. Claude Code가 유효하지 않은 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.
2831* 수동으로 편집한 내용을 유지하려면 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 후 `claude import`를 다시 실행하세요.3019* 수동으로 편집한 내용을 유지하려면 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 후 `claude import`를 다시 실행합니다.
2832 3020
2833<h3 id="could-not-import-a-server-from-claude-desktop">3021<h3 id="could-not-import-a-server-from-claude-desktop">
2834 Claude Desktop에서 서버를 가져올 수 없음3022 Claude Desktop에서 서버를 가져올 수 없음
2835</h3>3023</h3>
2836 3024
2837Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령어는 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버당 한 줄을 인쇄합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했고 선택된 서버 중 어느 것도 추가되지 않았습니다.3025Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령어는 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버당 한 줄을 출력합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했고 선택된 서버 중 어느 것도 추가되지 않았습니다.
2838 3026
2839```text theme={null}3027```text theme={null}
2840Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3028Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
2841```3029```
2842 3030
2843서버 이름 뒤의 텍스트가 이유입니다. 가장 일반적인 것은 이름 확인입니다: Claude Desktop은 서버 이름에 공백과 마침표 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈 및 밑줄로 제한합니다. 다른 이유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](/docs/ko/managed-mcp)에 의해 차단된 서버가 있습니다.3031서버 이름 뒤의 텍스트는 이유입니다. 가장 일반적인 것은 이름 확인입니다: Claude Desktop은 서버 이름에 공백 및 마침표 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈 및 밑줄로 제한합니다. 다른 이유로는 검증에 실패하는 서버 구성과 조직의 [MCP 정책](/docs/ko/managed-mcp)에 의해 차단된 서버가 있습니다.
2844 3032
2845**해야 할 일:**3033**해야 할 일:**
2846 3034
2847* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈 및 밑줄만 사용하도록 변경한 후 `claude mcp add-from-claude-desktop`을 다시 실행하세요.3035* `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)를 참조하세요.3036* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/docs/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.
2849 3037
2850<h3 id="cannot-add-mcp-server-to-the-managed-scope">3038<h3 id="cannot-add-mcp-server-to-the-managed-scope">
2851 MCP 서버를 관리 범위에 추가할 수 없음3039 MCP 서버를 관리 범위에 추가할 수 없음
2852</h3>3040</h3>
2853 3041
2854`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 해당 범위는 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 관리 설정을 통해 제공하는 서버를 보유합니다. Claude Code는 관리 설정에서만 이를 읽으므로 명령어가 해당 범위에 서버를 쓸 수 없습니다.3042`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 해당 범위는 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 관리 설정을 통해 제공하는 서버를 보유합니다. Claude Code는 관리 설정에서만 읽으므로 명령어가 해당 범위에 서버를 쓸 수 없습니다.
2855 3043
2856```text theme={null}3044```text theme={null}
2857Cannot add MCP server to scope: managed3045Cannot add MCP server to scope: managed
2859 3047
2860**해야 할 일:**3048**해야 할 일:**
2861 3049
2862* 쓸 수 있는 범위에 서버를 추가하세요: `local`, `user` 또는 `project`. `--scope` 없이 명령어는 `local`을 사용합니다. [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)를 참조하세요.3050* 쓸 수 있는 범위에 서버를 추가합니다: `local`, `user` 또는 `project`. `--scope` 없이 명령어는 `local`을 사용합니다. [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)를 참조하세요.
2863* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리 설정의 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)에 추가하세요.3051* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리 설정의 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)에 추가합니다.
2864 3052
2865<h3 id="cant-read-mcp-json">3053<h3 id="cant-read-mcp-json">
2866 .mcp.json을 읽을 수 없음3054 .mcp.json을 읽을 수 없음
2867</h3>3055</h3>
2868 3056
2869프로젝트의 [`.mcp.json`](/docs/ko/mcp#project-scope)을 읽는 명령어(예: `--scope project`로 `claude mcp add` 또는 `claude mcp add-json`, 또는 `claude mcp remove`)가 현재 디렉토리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 발견했으므로 파일을 읽는 대신 이 오류로 종료됩니다.3057프로젝트의 [`.mcp.json`](/docs/ko/mcp#project-scope)을 읽는 명령어(예: `--scope project`로 `claude mcp add` 또는 `claude mcp add-json` 또는 `claude mcp remove`)가 현재 디렉토리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 발견했으므로 파일을 읽는 대신 이 오류로 종료됩니다.
2870 3058
2871```text theme={null}3059```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.3060Can'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```3061```
2874 3062
2875v2.1.257 이전에는 `.mcp.json`의 FIFO가 명령어를 출력 없이 영원히 기다리게 했으며, `/dev/zero` 같은 장치 파일로의 심볼릭 링크가 프로세스가 종료될 때까지 메모리를 증가시켰습니다.3063v2.1.257 이전에는 `.mcp.json`의 FIFO가 명령어를 출력 없이 영원히 기다리게 했고 `/dev/zero` 같은 장치 파일에 대한 심볼릭 링크가 프로세스가 종료될 때까지 메모리를 증가시켰습니다.
2876 3064
2877**해야 할 일:**3065**해야 할 일:**
2878 3066
2879* 현재 디렉토리의 `.mcp.json`에 무엇이 있는지 확인하세요. [프로젝트 범위 형식](/docs/ko/mcp#project-scope)의 일반 JSON 파일로 바꾸거나 삭제한 후 명령어를 다시 실행하세요.3067* 현재 디렉토리의 `.mcp.json`에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](/docs/ko/mcp#project-scope)의 일반 JSON 파일로 바꾸거나 삭제한 후 명령어를 다시 실행합니다.
2880 3068
2881<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">3069<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">
2882 서버는 Anthropic 호스팅이며 로컬 OAuth를 지원하지 않음3070 서버는 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.3076"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```3077```
2890 3078
2891Claude Code는 URL로 이러한 호스트를 일치시키므로 `claude mcp add` 또는 `.mcp.json`에 추가한 서버가 이 중 하나를 가리킬 때 메시지가 나타납니다.3079Claude Code는 URL로 이러한 호스트를 일치시키므로 `claude mcp add` 또는 `.mcp.json`으로 추가한 서버가 이 중 하나를 가리킬 때 메시지가 나타납니다.
2892 3080
2893**해야 할 일:**3081**해야 할 일:**
2894 3082
2895* `claude mcp remove <name>`으로 항목을 제거하여 같은 URL의 claude.ai 커넥터를 숨길 수 없도록 하세요.3083* `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).3084* 제거한 후 [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 3085
2898<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">3086<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">
2899 서버가 구성된 headersHelper에 의해 발행된 Authorization 헤더를 거부함3087 서버가 구성된 headersHelper에 의해 발행된 Authorization 헤더를 거부함
2900</h3>3088</h3>
2901 3089
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):3090[`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 3091
2904```text theme={null}3092```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.3093Server 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```3094```
2907 3095
2908Claude Code는 각 연결 시도에서 헬퍼를 다시 실행하므로 토큰 회전 경쟁 같은 일시적 거부 후 재시도가 새로운 자격 증명으로 성공할 수 있습니다.3096Claude Code는 각 연결 시도에서 헬퍼를 다시 실행하므로 토큰 회전 경쟁 같은 일시적 거부 후 재시도가 새 자격 증명으로 성공할 수 있습니다.
2909 3097
2910**해야 할 일:**3098**해야 할 일:**
2911 3099
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` 값을 인쇄하는지 확인하세요.3100* 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**를 선택하세요.3101* 헬퍼 또는 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다.
2914 3102
2915v2.1.248 이전에는 Claude Code가 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해 OAuth 검색을 실행했습니다. 해당 검색이 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있습니다.3103v2.1.248 이전에는 Claude Code가 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해 OAuth 검색을 실행했습니다. 해당 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있습니다.
2916 3104
2917<h3 id="mcp-permission-prompt-tool-not-found">3105<h3 id="mcp-permission-prompt-tool-not-found">
2918 MCP 권한 프롬프트 도구를 찾을 수 없음3106 MCP 권한 프롬프트 도구를 찾을 수 없음
2919</h3>3107</h3>
2920 3108
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 이전에는 시작이 서버가 연결을 마칠 때까지 기다리지 않았으므로 느리게 시작하지만 정상인 서버가 이 오류를 생성했습니다.3109[`--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 3110
2923```text theme={null}3111```text theme={null}
2924Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3112Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none
2928 3116
2929**해야 할 일:**3117**해야 할 일:**
2930 3118
2931* 서버가 시작되고 연결된 상태를 유지하는지 확인하세요: 같은 디렉토리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 나열되는지 확인하세요.3119* 서버가 시작되고 연결된 상태로 유지되는지 확인합니다: 같은 디렉토리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 나열되는지 확인합니다.
2932* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인하세요.3120* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다.
2933* 서버가 시작하는 데 30초 이상 필요하면 [`MCP_TIMEOUT`](/docs/ko/env-vars)을 높이세요.3121* 서버가 시작하는 데 30초 이상 필요하면 [`MCP_TIMEOUT`](/docs/ko/env-vars)을 높입니다.
2934 3122
2935<h3 id="oauth-callback-port-is-already-in-use">3123<h3 id="oauth-callback-port-is-already-in-use">
2936 OAuth 콜백 포트가 이미 사용 중3124 OAuth 콜백 포트가 이미 사용 중
2937</h3>3125</h3>
2938 3126
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가 사용 가능한 포트를 선택하기 때문입니다.3127OAuth를 사용하여 원격 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 3128
2941```text theme={null}3129```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.3130OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.
2946 3134
2947**해야 할 일:**3135**해야 할 일:**
2948 3136
2949* 메시지의 명령어를 실행하여 포트를 보유한 프로세스를 찾고 중지하거나 완료될 때까지 기다리세요.3137* 메시지의 명령어를 실행하여 포트를 보유하는 프로세스를 찾고 중지하거나 완료될 때까지 기다립니다.
2950* 다른 프로그램이 해당 포트를 영구적으로 필요로 하면 서버에 다른 리디렉션 URI를 등록하고 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`(사용하는 것)로 포트를 설정하세요.3138* 다른 프로그램이 해당 포트를 영구적으로 필요로 하면 서버에 다른 리디렉션 URI를 등록하고 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`(사용하는 것)로 포트를 설정합니다.
2951* 그런 다음 로그인을 다시 시작하세요. 예를 들어 `/mcp`에서 서버를 선택하세요.3139* 그런 다음 로그인을 다시 시작합니다. 예를 들어 `/mcp`에서 서버를 선택합니다.
2952 3140
2953<h3 id="no-available-ports-for-oauth-redirect">3141<h3 id="no-available-ports-for-oauth-redirect">
2954 OAuth 리디렉션에 사용 가능한 포트 없음3142 OAuth 리디렉션에 사용 가능한 포트 없음
2964 3152
2965**해야 할 일:**3153**해야 할 일:**
2966 3154
2967* 보안 소프트웨어 또는 샌드박스 정책이 프로세스가 `127.0.0.1`에서 수신 대기하는 것을 차단하는지 확인하고 Claude Code가 로컬 포트를 바인드하도록 허용하세요.3155* 보안 소프트웨어 또는 샌드박스 정책이 프로세스가 `127.0.0.1`에서 수신 대기하는 것을 차단하는지 확인하고 Claude Code가 로컬 포트를 바인드하도록 허용합니다.
2968* 그런 다음 로그인을 다시 시작하세요. 예를 들어 `/mcp`에서 서버를 선택하세요.3156* 그런 다음 로그인을 다시 시작합니다. 예를 들어 `/mcp`에서 서버를 선택합니다.
2969 3157
2970<h3 id="security-review-fails-without-origin-head">3158<h3 id="security-review-fails-without-origin-head">
2971 /security-review가 origin/HEAD 없이 실패함3159 /security-review가 origin/HEAD 없이 실패함
2980'git <command> [<revision>...] -- [<file>...]'3168'git <command> [<revision>...] -- [<file>...]'
2981```3169```
2982 3170
2983메시지는 `git log` 또는 다른 `git diff`를 인용할 수 있습니다. Git은 원격이 기본 분기를 광고하고 fetch refspec이 이를 포함할 때만 `origin/HEAD`를 생성합니다. 전체 `git clone`이 커밋이 있는 원격을 수행합니다. ref는 이러한 설정에서 누락됩니다:3171메시지는 대신 `git log` 또는 다른 `git diff`를 인용할 수 있습니다. Git은 원격이 기본 분기를 광고하고 fetch refspec이 이를 포함할 때만 `origin/HEAD`를 만듭니다. 전체 `git clone`이 커밋이 있는 원격을 수행합니다. ref는 이러한 설정에서 누락됩니다:
2984 3172
2985* 단일 분기 또는 CI 체크아웃(너무 좁은 refspec을 가져옴)3173* 단일 분기 또는 CI 체크아웃(너무 좁은 refspec을 가져옴)
2986* 서버 측 HEAD가 아무도 푸시하지 않은 분기를 가리키는 원격3174* 서버 측 HEAD가 아무도 푸시하지 않은 분기를 가리키는 원격
2987* `origin` 원격이 없거나 절대 가져오지 않은 저장소3175* `origin` 원격이 없거나 가져온 적이 없는 저장소
2988 3176
2989Claude Code는 [동적 컨텍스트를 주입](/docs/ko/skills#when-an-injected-command-fails)하는 모든 스킬에 대해 같은 오류를 표시하며, 실패한 주입 명령어는 해당 스킬의 호출을 중단합니다. 명령어가 실행되기 전에 두 개의 형제 문자열이 발생합니다:3177Claude Code는 [동적 컨텍스트를 주입](/docs/ko/skills#when-an-injected-command-fails)하는 모든 스킬에 대해 동일한 오류를 표시하고 실패한 주입 명령어는 해당 스킬의 호출을 중단합니다. 명령어가 실행되기 전에 두 개의 형제 문자열이 발생합니다:
2990 3178
2991* `Shell command permission check failed for pattern "..."`: 명령어의 권한 확인이 이를 허용하지 않았습니다. [주입 명령어의 권한 확인](/docs/ko/skills#permission-checks-on-injected-commands)은 각 권한 모드에서 어떤 결과가 중단되는지 그리고 `allowed-tools`로 명령어를 사전 승인하는 방법을 다룹니다.3179* `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)을 참조하세요.3180* ``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 3181
2994**해야 할 일:**3182**해야 할 일:**
2995 3183
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`를 다시 실행하세요.3184* 원격의 기본 분기를 이름 지정하여 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을 확대하세요.3185* 분기를 이름 지정하지 않으려면 `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를 봅니다.3186* 저장소에 원격이 없으면 `git remote add origin <url>`로 추가하고 ref를 만들기 전에 가져옵니다. 원격이 비어 있으면 `git push -u origin HEAD`로 분기를 먼저 푸시하고 set-head 명령어에서 해당 분기를 이름 지정합니다. `origin/HEAD`는 방금 푸시한 분기를 가리키므로 분기가 이와 달라질 때까지 `/security-review`는 빈 diff를 봅니다.
2999 3187
3000<h3 id="input-must-be-provided-when-using-print">3188<h3 id="input-must-be-provided-when-using-print">
3001 \--print 사용 시 입력을 제공해야 함3189 \--print 사용 시 입력을 제공해야 함
3002</h3>3190</h3>
3003 3191
3004베어 `claude`는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되거나 PowerShell ISE 및 일부 IDE 출력 창 같은 실제 터미널이 아닐 때 `claude`는 [비대화형](/docs/ko/headless) 모드로 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로 메시지는 플래그를 전달하지 않았을 때도 `--print`를 이름 지정합니다. 프롬프트 없이 `-p`/`--print`를 전달하고 stdin에 파이프된 것이 없으면 어디서나 같은 오류를 생성합니다.3192베어 `claude`는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되거나 PowerShell ISE 및 일부 IDE 출력 창 같은 실제 터미널이 아닐 때 `claude`는 대신 [비대화형](/docs/ko/headless)으로 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 동일한 모드이므로 메시지는 플래그를 전달하지 않았을 때도 `--print`를 이름 지정합니다. `-p`/`--print`를 프롬프트 없이 전달하고 stdin에 파이프된 것이 없으면 어디서나 동일한 오류를 생성합니다.
3005 3193
3006```text theme={null}3194```text theme={null}
3007Error: Input must be provided either through stdin or as a prompt argument when using --print3195Error: Input must be provided either through stdin or as a prompt argument when using --print
3009 3197
3010**해야 할 일:**3198**해야 할 일:**
3011 3199
3012* 대화형 사용의 경우 실제 터미널에서 `claude`를 실행하세요: PowerShell ISE가 아닌 Windows Terminal 또는 PowerShell 콘솔, IDE의 출력 창이 아닌 통합 터미널.3200* 대화형 사용의 경우 실제 터미널에서 `claude`를 실행합니다: ISE가 아닌 Windows Terminal 또는 PowerShell 콘솔, IDE의 통합 터미널이 아닌 출력 창.
3013* 일회용 사용의 경우 프롬프트를 전달하세요: `claude -p "your question"`, 또는 `echo "your question" | claude -p`로 파이프하세요.3201* 일회용 사용의 경우 프롬프트를 전달합니다: `claude -p "your question"` 또는 `echo "your question" | claude -p`로 파이프합니다.
3014 3202
3015<h3 id="input-contained-only-whitespace">3203<h3 id="input-contained-only-whitespace">
3016 입력에 공백만 포함됨3204 입력에 공백만 포함됨
3017</h3>3205</h3>
3018 3206
3019[비대화형 모드](/docs/ko/headless)에서 Claude Code는 API가 보이는 텍스트가 없는 메시지를 거부하기 때문에 공백, 탭 또는 줄 바꿈으로만 구성된 프롬프트를 보내는 대신 거부합니다. 어떤 메시지를 보는지는 빈 프롬프트가 어디서 왔는지에 따라 다릅니다:3207[비대화형 모드](/docs/ko/headless)에서 Claude Code는 API가 보이는 텍스트가 없는 메시지를 거부하기 때문에 공백, 탭 또는 줄 바꿈으로만 구성된 프롬프트를 보내는 대신 거부합니다. 어떤 메시지를 보는지는 빈 프롬프트가 어디서 왔는지에 따라 달라집니다:
3020 3208
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`로 종료됩니다.3209* **`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.`3210* **실행 중인 `--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 3211
3024v2.1.229 이전에는 Claude Code가 공백 전용 메시지를 API로 보냈으며, API가 400 오류로 요청을 거부했습니다.3212v2.1.229 이전에는 Claude Code가 공백 전용 메시지를 API로 보냈고 API는 400 오류로 요청을 거부했습니다.
3025 3213
3026**해야 할 일:**3214**해야 할 일:**
3027 3215
3028* 프롬프트에 보이는 텍스트를 포함하세요. 스크립트가 변수 또는 파일에서 프롬프트를 구축하면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인하세요.3216* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수 또는 파일에서 프롬프트를 구축하면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.
3029 3217
3030<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">3218<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">
3031 stream-json 입력이 줄 바꿈 없이 256M 문자를 초과함3219 stream-json 입력이 줄 바꿈 없이 256M 문자를 초과함
3032</h3>3220</h3>
3033 3221
3034프로그램이 `claude -p --input-format stream-json` 실행에 stdin으로 줄 바꿈 없이 268,435,456자 이상을 보냈으므로 Claude Code는 이 오류를 stderr에 인쇄하고 더 많은 입력을 버퍼링하는 대신 코드 1로 종료됩니다. 메시지는 해당 예산을 `256M`으로 명시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링했으며, 프로세스가 충돌하거나 종료될 때까지 메모리를 증가시켰습니다.3222프로그램이 `claude -p --input-format stream-json` 실행에 stdin으로 줄 바꿈 없이 268,435,456자 이상을 보냈으므로 Claude Code는 이 오류를 stderr에 출력하고 더 많은 입력을 버퍼링하는 대신 코드 1로 종료됩니다. 메시지는 해당 예산을 `256M`으로 명시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링했고 프로세스가 충돌하거나 종료될 때까지 메모리를 증가시켰습니다.
3035 3223
3036```text theme={null}3224```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.3225Error: 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```3226```
3039 3227
3040줄 바꿈 없이 이 정도로 긴 입력은 보통 생산자가 stream-json 생산자가 아니라는 의미입니다. 예를 들어 실수로 파이프된 바이너리 파일 또는 일반 로그 출력입니다. 예산을 초과하는 단일 메시지가 같은 확인에 실패합니다.3228줄 바꿈 없이 이 정도로 긴 입력은 보통 생산자가 stream-json 생산자가 아니라는 의미입니다. 예를 들어 실수로 파이프된 바이너리 파일 또는 일반 로그 출력입니다. 예산을 초과하는 단일 메시지는 동일한 확인에 실패합니다.
3041 3229
3042**해야 할 일:**3230**해야 할 일:**
3043 3231
3044* stdin으로 파이프되는 것을 확인하세요. [`--input-format stream-json`](/docs/ko/cli-reference#cli-flags)을 사용하면 모든 메시지는 하나의 줄 바꿈으로 끝나는 JSON 줄이어야 합니다.3232* stdin으로 파이프되는 것을 확인합니다. [`--input-format stream-json`](/docs/ko/cli-reference#cli-flags)을 사용하면 모든 메시지는 줄 바꿈으로 종료된 JSON 줄 하나여야 합니다.
3045* 일반 텍스트를 대신 보내려면 `--input-format stream-json`을 제거하세요. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다.3233* 일반 텍스트를 대신 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다.
3046 3234
3047<h3 id="unknown-command">3235<h3 id="unknown-command">
3048 알 수 없는 명령어3236 알 수 없는 명령어
3054Unknown command: /hepl. Did you mean /help?3242Unknown command: /hepl. Did you mean /help?
3055```3243```
3056 3244
3057Claude Code는 이 세션의 메뉴가 나열하는 가장 가까운 명령어 이름 또는 별칭을 제안합니다. 가까운 것이 없으면 메시지가 이름 뒤에서 끝납니다. 원인은 보통 다음 중 하나입니다:3245Claude Code는 이 세션의 메뉴가 나열하는 가장 가까운 명령어 이름 또는 별칭을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에 끝납니다. 원인은 보통 다음 중 하나입니다:
3058 3246
3059* `/hepl`을 `/help`로 오타. [명령어 메뉴가 입력과 일치하는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)은 제출하기 전에 가까운 일치를 선택하는 것을 다룹니다.3247* `/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) 같은 자체 메시지로 응답합니다.3248* 플랫폼, 계획 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령어입니다. [`/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)의 명령어가 이 세션에 설치되거나 연결되지 않음.3249* [플러그인](/docs/ko/plugins/overview) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령어가 이 세션에 설치되거나 연결되지 않았습니다.
3062 3250
3063Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이 방식으로 응답합니다. 다른 모든 세션에서는 프롬프트를 Claude에 일반 메시지로 보냅니다. 명령어가 실행되지 않았고 Claude가 세션에서 실행할 수 있는 명령어 목록이 있다는 참고 사항이 포함됩니다. 이러한 세션에는 다음이 포함됩니다:3251Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이 방식으로 응답합니다. 다른 모든 세션에서는 대신 프롬프트를 Claude에 일반 메시지로 보냅니다. 명령어가 실행되지 않았고 Claude가 세션에서 실행할 수 있는 명령어 목록이 있다는 메모가 포함됩니다. 이러한 세션에는 다음이 포함됩니다:
3064 3252
3065* `-p` 실행3253* `-p` 실행
3066* [Agent SDK](/docs/ko/agent-sdk/overview) 애플리케이션3254* [Agent SDK](/docs/ko/agent-sdk/overview) 애플리케이션
3067* [Desktop app](/docs/ko/desktop)의 Code 탭3255* [Desktop 앱](/docs/ko/desktop)의 Code 탭
3068* [VS Code extension](/docs/ko/vs-code)의 채팅 패널3256* [VS Code 확장](/docs/ko/vs-code)의 채팅 패널
3069* [클라우드 세션](/docs/ko/claude-code-on-the-web) 및 [루틴](/docs/ko/routines)3257* [클라우드 세션](/docs/ko/claude-code-on-the-web) 및 [루틴](/docs/ko/routines)
3070 3258
3071이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령어의 경우 Claude Code는 여전히 명령어를 Claude로 보내는 대신 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 루틴만 일치하지 않는 이름을 Claude로 보냈습니다. v2.1.273 이전에는 `Unknown command`로도 응답했습니다.3259이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령어의 경우 Claude Code는 여전히 명령어를 Claude로 보내는 대신 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 루틴만 일치하지 않는 이름을 Claude로 보냈습니다. v2.1.273 이전에는 `Unknown command`로도 응답했습니다.
3072 3260
3073Claude Code는 `/`로 시작하는 모든 프롬프트를 명령어로 취급하지 않습니다. `/` 뒤의 첫 번째 단어가 Lean doc 주석을 여는 `/--` 같은 구두점으로 시작하거나 `/var/log/syslog` 같은 경로일 때 프롬프트를 Claude에 일반 메시지로 보냅니다.3261Claude Code는 `/`로 시작하는 모든 프롬프트를 명령어로 취급하지 않습니다. `/` 뒤의 첫 번째 단어가 Lean doc 주석을 여는 `/-` 같은 구두점으로 시작하거나 `/var/log/syslog` 같은 경로일 때 프롬프트를 Claude에 일반 메시지로 보냅니다.
3074 3262
3075v2.1.236 이전에는 입력한 이름에 대해 명령어 메뉴가 가까운 일치를 나열하는 동안 Enter를 누르면 Claude Code가 해당 일치를 실행했으므로 `/hepl` 같은 오타가 이 메시지를 생성하는 대신 `/help`를 실행했습니다.3263v2.1.236 이전에는 명령어 메뉴가 입력한 이름에 대한 가까운 일치를 나열하는 동안 Enter를 누르면 Claude Code가 일치를 실행했으므로 `/hepl` 같은 오타가 이 메시지를 생성하는 대신 `/help`를 실행했습니다.
3076 3264
3077**해야 할 일:**3265**해야 할 일:**
3078 3266
3079* 제안된 이름을 실행하거나 `/`를 입력한 후 이름의 일부를 입력하여 이 세션에서 사용 가능한 것을 확인하세요.3267* 제안된 이름을 실행하거나 `/` 뒤에 이름의 일부를 입력하여 이 세션에서 사용 가능한 것을 확인합니다.
3080* Claude Code가 문서화된 명령어를 알 수 없는 것으로 보고하면 [명령어 참조](/docs/ko/commands)의 행에서 이름 지정하는 요구 사항을 확인하세요.3268* Claude Code가 문서화된 명령어를 알 수 없는 것으로 보고하면 [명령어 참조](/docs/ko/commands)의 행에서 이름 지정하는 요구 사항을 확인합니다.
3081 3269
3082<h3 id="diff-is-too-large-for-ultrareview">3270<h3 id="diff-is-too-large-for-ultrareview">
3083 Diff가 ultrareview에 너무 큼3271 Diff가 ultrareview에 너무 큼
3084</h3>3272</h3>
3085 3273
3086분기와 기본 분기 간의 diff(커밋되지 않은 변경 사항 및 스테이징된 변경 사항 포함)가 [ultrareview](/docs/ko/ultrareview)의 크기 제한을 초과하므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어가 클라우드 세션이 시작되기 전에 검토를 거부합니다. 거부된 검토는 무료 실행을 사용하지 않으며 사용 크레딧을 청구하지 않습니다. 메시지는 적용 중인 제한, diff의 크기 및 가장 많은 변경된 줄에 기여하는 파일을 이름 지정합니다. v2.1.216 이전에는 메시지가 원본 diff 통계만 표시했습니다.3274분기와 기본 분기 간의 diff(커밋되지 않은 변경 사항 및 스테이징된 변경 사항 포함)가 [ultrareview](/docs/ko/ultrareview)의 크기 제한을 초과하므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어는 클라우드 세션이 시작되기 전에 검토를 거부합니다. 거부된 검토는 무료 실행을 사용하지 않으며 사용 크레딧을 청구하지 않습니다. 메시지는 적용 중인 제한, diff의 크기 및 가장 많은 변경된 줄에 기여하는 파일을 이름 지정합니다. v2.1.216 이전에는 메시지가 원시 diff 통계만 표시했습니다.
3087 3275
3088```text theme={null}3276```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.3277Diff 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```3278```
3091 3279
3092풀 요청을 검토하면 같은 제한이 적용됩니다. 해당 형식의 메시지는 `PR #<N> is too large for ultrareview`로 시작하고 PR의 파일 및 줄 수를 이름 지정합니다.3280풀 요청을 검토하면 동일한 제한이 적용됩니다. 해당 형식의 메시지는 `PR #<N> is too large for ultrareview`로 시작하고 PR의 파일 및 줄 수를 이름 지정합니다.
3093 3281
3094**해야 할 일:**3282**해야 할 일:**
3095 3283
3096* 기본 분기를 더 가깝게 전달하세요. 예를 들어 `/code-review ultra develop`이므로 검토가 해당 분기에 대한 diff만 포함합니다.3284* 기본 분기를 더 가깝게 전달합니다. 예를 들어 `/code-review ultra develop`이므로 검토는 해당 분기에 대한 diff만 포함합니다.
3097* 변경을 더 작은 분기로 분할하고 각각을 검토하세요. 메시지가 이름 지정한 파일이 가장 많은 변경된 줄에 기여하므로 이를 자체 분기로 이동하여 시작하세요.3285* 변경을 더 작은 분기로 분할하고 각각을 검토합니다. 메시지가 이름 지정하는 파일은 가장 많은 변경된 줄에 기여하므로 이들을 자신의 분기로 이동하여 시작합니다.
3098 3286
3099<h3 id="could-not-find-merge-base-with-the-base-branch">3287<h3 id="could-not-find-merge-base-with-the-base-branch">
3100 기본 분기와의 병합 기반을 찾을 수 없음3288 기본 분기와의 병합 기반을 찾을 수 없음
3101</h3>3289</h3>
3102 3290
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가 불가능할 때 이 거부를 봅니다.3291`/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 3292
3105```text theme={null}3293```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.3294Could 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```3295```
3108 3296
3109첫 번째 문장 뒤의 힌트는 Claude Code가 관찰한 것에 따라 다릅니다:3297첫 번째 문장 뒤의 힌트는 Claude Code가 관찰한 것에 따라 달라집니다:
3110 3298
3111* **기본 분기를 전달하지 않음**: Claude Code가 저장소의 기본 분기와 비교했으며 위의 예처럼 기본을 명시적으로 전달하도록 제안합니다.3299* **기본 분기를 전달하지 않았습니다**: Claude Code는 저장소의 기본 분기와 비교했고 위의 예와 같이 기본을 명시적으로 전달하도록 제안합니다.
3112* **이미 클론에 있는 기본 분기를 전달함**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``를 읽습니다.3300* **클론에 이미 있는 기본 분기를 전달했습니다**: 힌트는 ``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`로 실패합니다.3301* **클론에 없는 기본 분기를 전달했습니다**: 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 3302
3115**해야 할 일:**3303**해야 할 일:**
3116 3304
3117* 다른 분기가 실제 기본이면 명시적으로 전달하세요: `/code-review ultra <branch>`3305* 다른 분기가 실제 기본이면 명시적으로 전달합니다: `/code-review ultra <branch>`
3118* 클론이 전체 기록을 갖지 않을 수 있으면 `git fetch --unshallow origin`을 실행하고 검토를 다시 실행하세요.3306* 클론이 전체 기록을 갖지 않을 수 있으면 `git fetch --unshallow origin`을 실행하고 검토를 다시 실행합니다.
3119 3307
3120<h3 id="your-checkout-has-no-branches">3308<h3 id="your-checkout-has-no-branches">
3121 체크아웃에 분기가 없음3309 체크아웃에 분기가 없음
3122</h3>3310</h3>
3123 3311
3124체크아웃은 커밋을 가질 수 있지만 분기는 없습니다: `git init` 다음 `git fetch <url>` 및 `git checkout FETCH_HEAD`를 실행하면 분기가 없는 분리된 HEAD를 얻습니다. Claude Code는 저장소를 git 번들로 패키징하여 [ultrareview](/docs/ko/ultrareview)를 위해 업로드하며, 분기나 다른 ref가 없는 저장소를 번들할 수 없으므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어가 클라우드 세션이 시작되기 전에 검토를 거부합니다.3312체크아웃은 커밋을 가질 수 있지만 분기는 없습니다: `git init` 뒤에 `git fetch <url>` 및 `git checkout FETCH_HEAD`를 실행하면 분기가 없는 분리된 HEAD를 얻습니다. Claude Code는 저장소를 git 번들로 패키징하여 [ultrareview](/docs/ko/ultrareview)를 위해 업로드하고 분기나 다른 ref가 없는 저장소를 번들할 수 없으므로 `/code-review ultra` 및 `claude ultrareview` 하위 명령어는 클라우드 세션이 시작되기 전에 검토를 거부합니다.
3125 3313
3126```text theme={null}3314```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.3315Your 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```3316```
3129 3317
3130v2.1.221 이전에는 Claude Code가 이 체크아웃에서 모든 추적된 파일을 검토하려고 시도했으며, 업로드가 실패했습니다.3318v2.1.221 이전에는 Claude Code가 이 체크아웃의 모든 추적된 파일을 검토하려고 시도했고 업로드가 실패했습니다.
3131 3319
3132**해야 할 일:**3320**해야 할 일:**
3133 3321
3134* 현재 커밋에서 `git checkout -b <name>`으로 분기를 생성한 후 검토를 다시 실행하세요.3322* 현재 커밋에서 `git checkout -b <name>`으로 분기를 만든 후 검토를 다시 실행합니다.
3135 3323
3136<h3 id="no-github-account-is-connected-to-your-claude-account">3324<h3 id="no-github-account-is-connected-to-your-claude-account">
3137 Claude 계정에 연결된 GitHub 계정이 없음3325 GitHub 계정이 Claude 계정에 연결되지 않음
3138</h3>3326</h3>
3139 3327
3140`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했으며, 클라우드 세션을 생성하기 전에 Claude Code는 서버에 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소에 도달할 수 있는지 묻습니다. 계정이 연결되지 않았거나 연결이 만료되었으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.3328`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했고 클라우드 세션을 만들기 전에 Claude Code는 서버에 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소에 도달할 수 있는지 묻습니다. 계정이 연결되지 않았거나 연결이 만료되었으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.
3141 3329
3142```text theme={null}3330```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).3331Ultrareview 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```3332```
3145 3333
3146[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 세션에서 사용할 수 없으면 메시지는 claude.ai 링크만 이름 지정합니다.3334[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)이 세션에서 사용할 수 없으면 메시지는 claude.ai 링크만 이름 지정합니다.
3147 3335
3148**해야 할 일:**3336**해야 할 일:**
3149 3337
3150* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결하세요.3338* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나 [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다.
3151* 연결 1분 후 검토를 다시 실행하세요.3339* 연결 후 1분 후 검토를 다시 실행합니다.
3152 3340
3153v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.3341v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.
3154 3342
3156 연결된 GitHub 계정이 저장소를 볼 수 없음3344 연결된 GitHub 계정이 저장소를 볼 수 없음
3157</h3>3345</h3>
3158 3346
3159`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했으며, [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.3347`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했고 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로 클라우드 클론이 실패하고 Claude Code는 시작을 거부합니다. Claude Code는 거부된 시작에 대해 무료 실행을 사용하거나 사용 크레딧을 청구하지 않습니다.
3160 3348
3161```text theme={null}3349```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.3350Your 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```3351```
3164 3352
3165[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 세션에서 사용할 수 없으면 메시지는 앱 설치만 이름 지정합니다.3353[`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)이 세션에서 사용할 수 없으면 메시지는 앱 설치만 이름 지정합니다.
3166 3354
3167**해야 할 일:**3355**해야 할 일:**
3168 3356
3169* 로컬 `gh` CLI가 저장소를 읽을 수 있으면 `/web-setup`을 실행하여 해당 로그인을 Claude 계정에 연결하세요.3357* 로컬 `gh` CLI가 저장소를 읽을 수 있으면 `/web-setup`을 실행하여 해당 로그인을 Claude 계정에 연결합니다.
3170* 변경 후 검토를 다시 실행하세요.3358* 변경 후 검토를 다시 실행합니다.
3171 3359
3172v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.3360v2.1.248 이전에는 Claude Code가 시작 전에 이를 확인하지 않았습니다.
3173 3361
3174<h3 id="the-github-app-preflight-failed-transiently">3362<h3 id="the-github-app-preflight-failed-transiently">
3175 GitHub App 사전 점검이 일시적으로 실패함3363 GitHub 앱 사전 점검이 일시적으로 실패함
3176</h3>3364</h3>
3177 3365
3178로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했으며, 두 단계가 함께 실패했습니다. Claude Code가 저장소 번들을 구축하거나 업로드할 수 없습니다. 업로드 전에 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했으며, 명확한 답변 대신 재시도가 지울 수 있는 오류로 끝났습니다. 예를 들어 네트워크 오류, 타임아웃 또는 임시 서버 오류입니다. 전체 메시지는 번들을 중지한 것으로 시작합니다. 예를 들어 `Could not upload repo bundle (<error>)`이고 사전 점검 문장으로 끝납니다:3366로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했고 두 단계가 함께 실패했습니다. Claude Code가 저장소 번들을 구축하거나 업로드할 수 없습니다. 업로드 전에 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했고 명확한 답변 대신 재시도가 지울 수 있는 오류로 끝났습니다. 예를 들어 네트워크 오류, 타임아웃 또는 임시 서버 오류입니다. 전체 메시지는 번들을 중지한 것으로 시작합니다. 예를 들어 `Could not upload repo bundle (<error>)`이고 사전 점검 문장으로 끝납니다:
3179 3367
3180```text theme={null}3368```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 instead3369Could 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 3371
3184**해야 할 일:**3372**해야 할 일:**
3185 3373
3186* 잠시 후 명령어를 다시 실행하세요. GitHub 확인이 통과하면 Claude Code가 GitHub 클론에서 시작할 수 있으므로 실패한 업로드가 더 이상 시작을 차단하지 않습니다.3374* 잠시 후 명령어를 다시 실행합니다. GitHub 확인이 통과하면 Claude Code는 GitHub 클론에서 세션을 시작할 수 있으므로 실패한 업로드가 더 이상 시작을 차단하지 않습니다.
3187* 재시도가 계속 실패하면 메시지의 시작이 업로드를 중지한 것을 이름 지정합니다. 해당 원인이 수정할 수 있는 것이면 수정하여 세션이 로컬 저장소에서 시작할 수 있도록 하세요.3375* 재시도가 계속 실패하면 메시지의 시작이 업로드를 중지한 것을 이름 지정합니다. 수정할 수 있는 원인이 있으면 수정하여 세션이 대신 로컬 저장소에서 시작할 수 있습니다.
3188 3376
3189v2.1.251 이전에는 Claude Code가 GitHub 확인이 일시적으로만 실패했을 때도 `Please set up GitHub on https://claude.ai/code`로 메시지를 끝냈으며, 설정 조언은 일시적 실패를 지울 수 없습니다.3377v2.1.251 이전에는 Claude Code가 GitHub 확인이 일시적으로만 실패했을 때도 `Please set up GitHub on https://claude.ai/code`로 메시지를 끝냈고 설정 조언은 일시적 실패를 지울 수 없습니다.
3190 3378
3191<h3 id="github-isnt-connected-to-your-claude-account">3379<h3 id="github-isnt-connected-to-your-claude-account">
3192 GitHub가 Claude 계정에 연결되지 않음3380 GitHub가 Claude 계정에 연결되지 않음
3193</h3>3381</h3>
3194 3382
3195로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했습니다. 예를 들어 `/autofix-pr`을 사용합니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code는 시작을 거부합니다:3383로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했습니다. 예를 들어 `/autofix-pr`을 사용합니다. GitHub 계정이 Claude 계정에 연결되지 않았거나 연결이 만료되었으므로 Claude Code는 시작을 거부합니다:
3196 3384
3197```text theme={null}3385```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-github3386GitHub 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```3387```
3200 3388
3201[`/schedule`](/docs/ko/routines)로 루틴을 생성할 때 같은 메시지가 저장소를 이름 지정하는 설정 참고로 나타납니다. 참고는 루틴 생성을 차단하지 않습니다.3389[`/schedule`](/docs/ko/routines)로 루틴을 만들 때 동일한 메시지가 저장소를 이름 지정하는 설정 메모로 나타납니다. 메모는 루틴 만들기를 차단하지 않습니다.
3202 3390
3203**해야 할 일:**3391**해야 할 일:**
3204 3392
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)을 참조하여 두 가지가 어떻게 다른지 확인하세요.3393* `/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분 후 명령어를 다시 실행하세요.3394* 연결 후 1분 후 명령어를 다시 실행합니다.
3207 3395
3208v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 임시 실패로 보고했으며 재시도하거나 앱을 설치하도록 제안했습니다. 둘 다 GitHub 계정을 연결하지 않습니다.3396v2.1.268 이전에는 Claude Code가 이를 Claude GitHub 앱 확인의 임시 실패로 보고했고 재시도하거나 앱을 설치하도록 제안했습니다. 둘 다 GitHub 계정을 연결하지 않습니다.
3209 3397
3210<h3 id="single-sign-on-authorization-needed">3398<h3 id="single-sign-on-authorization-needed">
3211 단일 로그인 인증 필요3399 싱글 사인온 인증 필요
3212</h3>3400</h3>
3213 3401
3214[`/install-github-app`](/docs/ko/github-actions#quick-setup)을 실행했으며 SAML 단일 로그인을 적용하는 조직의 저장소를 선택했습니다. 설정 전에 Claude Code는 GitHub CLI로 저장소에 대한 액세스를 확인하며, GitHub는 `gh` 토큰이 아직 조직에 대해 인증되지 않았기 때문에 해당 확인을 거부했습니다. 마법사는 단계와 함께 경고를 표시합니다:3402[`/install-github-app`](/docs/ko/github-actions#quick-setup)을 실행했고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. 설정 전에 Claude Code는 GitHub CLI로 저장소에 대한 액세스를 확인하고 GitHub는 `gh` 토큰이 아직 조직에 대해 인증되지 않았기 때문에 해당 확인을 거부했습니다. 마법사는 인증 단계와 함께 경고를 표시합니다:
3215 3403
3216```text theme={null}3404```text theme={null}
3217Single sign-on authorization needed3405Single sign-on authorization needed
3220 3408
3221**해야 할 일:**3409**해야 할 일:**
3222 3410
3223* `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 인증하세요. `gh auth refresh -h github.com -s repo,workflow`를 실행하고 GitHub가 단일 로그인을 요청할 때 조직을 인증하세요.3411* `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**를 선택한 후 조직을 인증하세요.3412* `GH_TOKEN`에서 개인 액세스 토큰으로 인증하면 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택하고 조직을 인증합니다.
3225* `/install-github-app`을 다시 실행하세요.3413* `/install-github-app`을 다시 실행합니다.
3226 3414
3227v2.1.273 이전에는 Claude Code가 이 조건에 대해 `Admin permissions required` 경고를 표시했습니다.3415v2.1.273 이전에는 Claude Code가 이 조건에 대해 `Admin permissions required` 경고를 표시했습니다.
3228 3416
3229<h3 id="failed-to-resume-the-conversation">3417<h3 id="failed-to-resume-the-conversation">
3230 대화를 재개할 수 없음3418 대화를 재개하지 못함
3231</h3>3419</h3>
3232 3420
3233Claude Code가 [`claude --resume` 선택기](/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 기록을 읽거나 처리할 수 없어서 부분적으로 로드된 상태에서 계속하는 대신 프로세스를 종료합니다. 메시지는 재시도 명령어를 포함합니다:3421Claude Code가 [`claude --resume` 선택기](/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 기록을 읽거나 처리할 수 없으므로 부분적으로 로드된 상태에서 계속하는 대신 프로세스를 종료합니다. 메시지는 재시도 명령어를 포함합니다:
3234 3422
3235```text theme={null}3423```text theme={null}
3236Failed to resume the conversation.3424Failed to resume the conversation.
3237Run claude --resume <session-id> to retry, or claude to start a new session.3425Run claude --resume <session-id> to retry, or claude to start a new session.
3238```3426```
3239 3427
3240Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대화에서 `Failed to resume conversation`을 보고하며 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 실패한 재개가 `Resuming conversation…` 스피너에 무한정 머물렀습니다.3428Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대화에서 `Failed to resume conversation`을 보고하고 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 실패한 재개가 `Resuming conversation…` 스피너에 무한정 머물렀습니다.
3241 3429
3242**해야 할 일:**3430**해야 할 일:**
3243 3431
3244* 메시지의 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도하세요.3432* 메시지의 세션 ID로 `claude --resume <session-id>`를 실행하여 재시도합니다.
3245* 재시도가 다시 실패하면 `claude update`를 실행하고 다시 재개하세요. v2.1.275 이전 버전은 저장된 기록에 읽을 수 없는 항목이 포함되어 있으면 재개에 실패합니다.3433* 모든 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. v2.1.275 이전의 버전은 저장된 기록에 읽을 수 없는 항목이 포함되어 있을 때 재개에 실패합니다.
3246* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작하세요.3434* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다.
3247 3435
3248<h3 id="no-conversation-found-with-the-session-id">3436<h3 id="no-conversation-found-with-the-session-id">
3249 세션 ID와 일치하는 대화를 찾을 수 없음3437 세션 ID와 일치하는 대화를 찾을 수 없음
3250</h3>3438</h3>
3251 3439
3252세션 ID를 `claude --resume <session-id>`에 전달했는데 저장된 기록이 일치하지 않습니다:3440`claude --resume <session-id>`에 세션 ID를 전달했고 저장된 기록이 일치하지 않습니다:
3253 3441
3254```text theme={null}3442```text theme={null}
3255No conversation found with session ID: <session-id>3443No conversation found with session ID: <session-id>
3256```3444```
3257 3445
3258Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. Claude Code는 [현재 프로젝트를 먼저 검색한 후 이 머신의 다른 모든 프로젝트를 검색](/docs/ko/sessions#resume-a-session)합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉토리와 git worktree에서 중지되었으므로 세션이 마지막으로 작동한 디렉토리에서 재개하세요.3446Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. Claude Code는 [현재 프로젝트를 먼저 검색한 후 이 머신의 다른 모든 프로젝트를 검색](/docs/ko/sessions#resume-a-session)합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉토리와 git worktree에서 중지되었으므로 세션이 마지막으로 작동한 디렉토리에서 재개합니다.
3259 3447
3260일반적인 원인:3448일반적인 원인:
3261 3449
3262* **잘못된 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다.3450* **잘못된 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)을 따릅니다.3451* **삭제된 기록**: Claude Code는 [보존 기간](/docs/ko/sessions#where-transcripts-are-stored) 후 기록을 제거합니다. 기본값은 30일이며 [보존 스윕 규칙](/docs/ko/claude-directory#cleaned-up-automatically)을 따릅니다.
3264* **다른 머신**: Claude Code는 기록을 로컬로 저장하므로 세션이 실행된 머신에서 재개하세요.3452* **다른 머신**: Claude Code는 기록을 로컬로 저장하므로 세션이 실행된 머신에서 재개합니다.
3265* **중복 복사본**: 프로젝트 디렉토리를 `~/.claude/projects` 아래로 복사했으므로 두 기록이 같은 ID를 가지면 Claude Code는 이 메시지를 보고하는 대신 임의로 하나의 복사본을 재개합니다.3453* **중복 복사본**: `~/.claude/projects` 아래에 프로젝트 디렉토리를 복사했으므로 두 기록이 동일한 ID를 가지면 Claude Code는 이 메시지를 보고하고 임의로 하나의 복사본을 재개하지 않습니다.
3266 3454
3267**해야 할 일:**3455**해야 할 일:**
3268 3456
3269* 대화형 세션의 경우 [`claude --resume`](/docs/ko/sessions#use-the-session-picker)으로 [세션 선택기](/docs/ko/sessions#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 확대한 후 세션을 선택하세요.3457* 대화형 세션의 경우 `claude --resume`으로 [세션 선택기](/docs/ko/sessions#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 확장한 후 세션을 선택합니다.
3270* `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 생성된 세션은 선택기에 나타나지 않으므로 원본 실행이 인쇄한 `session_id`에 대해 ID를 다시 확인하세요.3458* `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 만든 세션은 선택기에 나타나지 않으므로 원래 실행이 출력한 `session_id`에 대해 ID를 다시 확인합니다.
3459
3460<h3 id="windows-reported-an-error-ebadf">
3461 Windows가 이 세션의 기록 파일을 읽을 때 오류를 보고함 (EBADF)
3462</h3>
3463
3464Windows에서 세션을 재개했고 저장된 [기록 파일](/docs/ko/sessions#where-transcripts-are-stored)이 정상적으로 열렸으며 읽기가 EBADF 시스템 오류로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 말하지 않으므로 메시지는 가능한 원인과 시도할 것을 제안합니다:
3465
3466```text theme={null}
3467Windows 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.
3468```
3469
3470메시지는 명령어의 자체 실패 줄을 따릅니다. 예를 들어 `Failed to resume session <session-id>`. `claude --resume` 또는 [`claude -p`](/docs/ko/headless) 명령어는 메시지를 표시한 후 코드 1로 종료됩니다. `/resume` 후 실행 중인 세션 내에서 현재 세션은 계속 실행됩니다.
3471
3472**해야 할 일:**
3473
3474* 보안, 암호화 또는 엔드포인트 관리 도구 같은 파일 읽기를 스캔하거나 가로채는 소프트웨어에서 기록을 보유하는 폴더를 제외합니다. 기록은 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있거나 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)이 이름 지정하는 디렉토리 아래에 있습니다.
3475* 제외를 추가할 수 없으면 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다.
3476* 세션을 다시 재개합니다.
3477
3478v2.1.282 이전에는 실패가 설명 없이 나타났습니다: `claude --resume <session-id>`는 `Failed to resume session <session-id>`에서 끝났고 `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read` 같은 시스템 오류 텍스트만 출력했습니다.
3271 3479
3272<h3 id="cannot-switch-renderers-in-this-session">3480<h3 id="cannot-switch-renderers-in-this-session">
3273 이 세션에서 렌더러를 전환할 수 없음3481 이 세션에서 렌더러를 전환할 수 없음
3274</h3>3482</h3>
3275 3483
3276렌더러를 전환하면 Claude Code가 프로세스를 다시 시작합니다. Claude Code가 다시 시작하기를 거부하는 세션에서 [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했으므로 전환되지 않고 아무것도 저장되지 않습니다. 어떤 메시지를 보는지는 원인을 알려줍니다:3484렌더러를 전환하면 Claude Code가 프로세스를 다시 시작합니다. [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 Claude Code가 다시 시작하기를 거부하는 세션에서 실행했으므로 전환하지 않고 아무것도 저장하지 않습니다. 어떤 메시지를 보는지는 원인을 알려줍니다:
3277 3485
3278* `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 하위 에이전트 같은 백그라운드에서 실행 중인 작업이 있습니다. 재시작이 이를 중단할 것입니다. 작업이 완료될 때까지 기다리거나 [`/tasks`](/docs/ko/commands)로 중지한 후 `/tui fullscreen` 또는 `/tui default`를 다시 실행하세요.3486* `Cannot switch renderers while work is running in the background`: 백그라운드 셸 또는 하위 에이전트 같은 재시작이 중단할 백그라운드 작업이 실행 중입니다. [`/tasks`](/docs/ko/commands)로 작업이 완료될 때까지 기다리거나 중지한 후 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다.
3279* `Cannot switch renderers in this session`: 세션에 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 어쨌든 다시 시작했으며 다시 시작된 세션이 없이 실행되었습니다.3487*
3280 3488
3281제한 메시지에서 괄호 안의 부분이 Claude Code가 발견한 제한을 이름 지정합니다:3489`Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 어쨌든 다시 시작했고 다시 시작된 세션이 제한 없이 실행되었습니다.
3490
3491제한 메시지에서 괄호 안의 부분은 Claude Code가 찾은 제한을 이름 지정합니다:
3282 3492
3283```text theme={null}3493```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.3494Cannot 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 3496
3287메시지가 괄호 안에 표시할 수 있는 각 이유:3497메시지가 괄호 안에 표시할 수 있는 각 이유:
3288 3498
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)이 포함됩니다.3499* `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가 대신 다시 프롬프트합니다.3500* `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`로 전달하는 규칙과 함께 요청 규칙을 추가했습니다. 요청 규칙에 대한 플래그는 없습니다.3501* `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`: 권한 업데이트가 세션 중간에 규칙 또는 디렉토리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄이 같은 값으로 텍스트를 전달할 수 없습니다.3502* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 중간에 규칙 또는 디렉토리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄이 텍스트를 동일한 값으로 전달할 수 없습니다.
3293 3503
3294**해야 할 일:**3504**해야 할 일:**
3295 3505
3296* 이러한 제한 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나 다시 전환하려면 `/tui default`를 실행하세요. Claude Code는 [`tui` 설정](/docs/ko/settings-reference#tui)을 거기에 저장합니다.3506* 이러한 제한 없이 시작된 세션에서 `/tui fullscreen` 또는 `/tui default`를 실행하여 다시 전환합니다. Claude Code는 [`tui` 설정](/docs/ko/settings-reference#tui)을 거기에 저장합니다.
3297 3507
3298<h3 id="couldnt-open-claude-desktop">3508<h3 id="couldnt-open-claude-desktop">
3299 Claude Desktop을 열 수 없음3509 Claude Desktop을 열 수 없음
3300</h3>3510</h3>
3301 3511
3302[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했는데 Claude Desktop을 열기 위해 Claude Code가 사용하는 시스템 명령어가 실패했습니다. 세션은 터미널에 남아 있습니다.3512[`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭 `/app`을 실행했고 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령어가 실패했습니다. 세션은 터미널에 남아 있습니다.
3303 3513
3304```text theme={null}3514```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.3515Error: 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 3517
3308**해야 할 일:**3518**해야 할 일:**
3309 3519
3310* Claude Desktop을 직접 열고 `/desktop`을 다시 실행하세요.3520* Claude Desktop을 직접 열고 `/desktop`을 다시 실행합니다.
3311* 해당 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행한 후 디버그 로그를 확인하세요.3521* 해당 명령어의 전체 오류 출력을 읽으려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행한 후 디버그 로그를 확인합니다.
3312 3522
3313v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였으며 무엇이 실패했는지 말하지 않았습니다.3523v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였고 무엇이 실패했는지 말하지 않았습니다.
3314 3524
3315<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3525<h3 id="terminal-setup-left-your-zed-keymap-unchanged">
3316 /terminal-setup이 Zed 키맵을 변경하지 않음3526 /terminal-setup이 Zed 키맵을 변경하지 않음
3317</h3>3527</h3>
3318 3528
3319Zed에서 [`/terminal-setup`](/docs/ko/terminal-config#enter-multiline-prompts)을 실행했는데 Claude Code가 Zed `keymap.json`에 대한 업데이트를 완료할 수 없어서 파일을 그대로 두었습니다.3529Zed에서 [`/terminal-setup`](/docs/ko/terminal-config#enter-multiline-prompts)을 실행했고 Claude Code가 Zed `keymap.json`에 대한 업데이트를 완료할 수 없어서 파일을 그대로 두었습니다.
3320 3530
3321각 메시지는 키맵 경로를 이름 지정하고 직접 추가할 키바인딩 블록으로 끝납니다:3531각 메시지는 키맵 경로를 이름 지정하고 직접 추가할 키바인딩 블록으로 끝납니다:
3322 3532
3326{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }3536{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }
3327```3537```
3328 3538
3329메시지의 첫 줄이 원인을 이름 지정합니다:3539메시지의 첫 줄은 원인을 이름 지정합니다:
3330 3540
3331* `Couldn't read your Zed keymap, so it was left unchanged.`: Claude Code가 파일을 읽을 수 없습니다. 예를 들어 파일 권한 때문입니다.3541* `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.`: 파일이 잘 읽혔지만 `//` 주석 및 후행 쉼표가 허용되어도 키바인딩 블록 배열로 파싱되지 않습니다.3542* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일이 잘 읽혔지만 `//` 주석 및 후행 쉼표가 허용되어도 키바인딩 블록 배열로 파싱되지 않습니다.
3335 3545
3336**해야 할 일:**3546**해야 할 일:**
3337 3547
3338* 메시지의 블록을 메시지가 이름 지정한 경로의 `keymap.json`의 최상위 배열에 복사하세요.3548* 메시지의 블록을 메시지가 이름 지정하는 경로의 `keymap.json`의 최상위 배열에 복사합니다.
3339* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 후 `/terminal-setup`을 다시 실행하세요.3549* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 후 `/terminal-setup`을 다시 실행합니다.
3340 3550
3341v2.1.247 이전에는 `/terminal-setup`이 `//` 주석 또는 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 설치된 것으로 보고하면서 자체 바인딩만으로 전체 파일을 바꿨습니다. 이전 버전이 바꾼 키맵을 복원하려면 [멀티라인 프롬프트 입력](/docs/ko/terminal-config#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용하세요.3551v2.1.247 이전에는 `/terminal-setup`이 `//` 주석 또는 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었고 전체 파일을 자신의 바인딩만으로 바꾸면서 바인딩이 설치되었다고 보고했습니다. 이전 버전이 바꾼 키맵을 복원하려면 [멀티라인 프롬프트 입력](/docs/ko/terminal-config#enter-multiline-prompts) 아래에 설명된 `.bak` 백업 파일을 사용합니다.
3342 3552
3343<h3 id="skill-usage-reports-are-not-available-on-this-connection">3553<h3 id="skill-usage-reports-are-not-available-on-this-connection">
3344 이 연결에서 스킬 사용 보고서를 사용할 수 없음3554 스킬 사용 보고서는 이 연결에서 사용할 수 없음
3345</h3>3555</h3>
3346 3556
3347[Remote Control](/docs/ko/remote-control)을 통해 [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행했습니다. 휴대폰 또는 브라우저에서 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며 대신 이 메시지로 응답합니다:3557[Remote Control](/docs/ko/remote-control)을 통해, 휴대폰 또는 브라우저에서 [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않고 대신 이 메시지로 응답합니다:
3348 3558
3349```text theme={null}3559```text theme={null}
3350Skill usage reports are not available on this connection.3560Skill usage reports are not available on this connection.
3352 3562
3353**해야 할 일:**3563**해야 할 일:**
3354 3564
3355* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나 거기서 `claude -p "/skill-doctor"`를 실행하세요.3565* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나 거기서 `claude -p "/skill-doctor"`를 실행합니다.
3356 3566
3357<h3 id="custom-output-styles-cant-be-selected-over-remote-control">3567<h3 id="custom-output-styles-cant-be-selected-over-remote-control">
3358 Remote Control 또는 릴레이된 메시지에서 사용자 정의 출력 스타일을 선택할 수 없음3568 사용자 정의 출력 스타일을 Remote Control을 통해 선택할 수 없음
3359</h3>3569</h3>
3360 3570
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) 이름은 존재하지 않는 이름과 같은 응답을 받습니다:3571[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 3572
3363```text theme={null}3573```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.3574Custom 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 3576
3367**해야 할 일:**3577**해야 할 일:**
3368 3578
3369* 기본 제공 스타일을 선택하세요. 예를 들어 `/output-style concise`3579* 기본 제공 스타일을 선택합니다. 예를 들어 `/output-style concise`.
3370* 사용자 정의 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션이 자체 터미널을 가지고 있으면 거기서 `/output-style <style>`을 실행하세요.3580* 사용자 정의 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle)을 설정하거나 세션 자체의 터미널에서 `/output-style <style>`을 실행합니다(있는 경우).
3371 3581
3372<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">3582<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">
3373 출력 스타일이 이 세션이 로드하지 않는 로컬 설정에 저장됨3583 출력 스타일이 이 세션이 로드하지 않는 로컬 설정에 저장됨
3374</h3>3584</h3>
3375 3585
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는 효과가 없을 설정을 쓰는 대신 거부합니다:3586이 세션의 설정 소스가 `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 3587
3378```text theme={null}3588```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.3589Output 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 3591
3382**해야 할 일:**3592**해야 할 일:**
3383 3593
3384* 세션의 설정 소스에 `local`을 추가하고 다시 전환하세요.3594* 세션의 설정 소스에 `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)를 참조하세요.3595* 세션이 로드하는 설정 파일(예: 프로젝트의 `.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 3596
3387<h2 id="plugin-errors">3597<h2 id="plugin-errors">
3388 플러그인 오류3598 플러그인 오류
3415 Marketplace is registered from an untrusted source3625 Marketplace is registered from an untrusted source
3416</h3>3626</h3>
3417 3627
3418마켓플레이스가 [공식 Anthropic 마켓플레이스용으로 예약된](/docs/ko/plugins/marketplace-reference#marketplace-file) 이름으로 등록되어 있지만 등록된 소스가 `anthropics` GitHub 저장소가 아닙니다. Claude Code는 마켓플레이스를 로드하거나 새로 고칠 때마다 예약된 이름을 다시 확인하므로 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. v2.1.205 이전에는 마켓플레이스가 추가될 때만 이름이 확인되었으므로 이름이 예약되기 전에 등록된 항목이 계속 로드되었습니다.3628마켓플레이스가 [공식 Anthropic 마켓플레이스용으로 예약된](/docs/ko/plugins/marketplace-reference#marketplace-file) 이름으로 등록되어 있지만 등록된 소스가 `anthropics` GitHub 저장소가 아닙니다. Claude Code는 마켓플레이스를 로드하거나 새로 고칠 때마다 예약된 이름을 다시 확인하므로 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. v2.1.205 이전에는 이름이 예약되기 전에 등록된 항목이 계속 로드되었습니다.
3419 3629
3420```text theme={null}3630```text theme={null}
3421Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.3631Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.
3452* 마켓플레이스의 이름을 예약된 이름의 철자를 지정하지 않는 이름으로 바꾸고 다시 추가하십시오.3662* 마켓플레이스의 이름을 예약된 이름의 철자를 지정하지 않는 이름으로 바꾸고 다시 추가하십시오.
3453* 무시된 항목 경고의 경우 제공하는 `claude plugin marketplace remove` 명령을 실행하거나 `~/.claude/plugins/known_marketplaces.json`에서 항목을 제거하십시오.3663* 무시된 항목 경고의 경우 제공하는 `claude plugin marketplace remove` 명령을 실행하거나 `~/.claude/plugins/known_marketplaces.json`에서 항목을 제거하십시오.
3454 3664
3665<h3 id="claude-code-refuses-the-marketplace-name">
3666 Claude Code refuses the marketplace name
3667</h3>
3668
3669등록된 마켓플레이스의 이름이 [공식 Anthropic 마켓플레이스를 사칭합니다](/docs/ko/plugins/marketplace-reference#reserved-names). 해당 섹션에 나열된 규칙에 따릅니다.
3670
3671마켓플레이스가 확인이 이를 차단하기 전에 이러한 이름으로 등록된 경우 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. Claude Code는 마켓플레이스의 카탈로그를 읽을 때마다 이름을 확인하기 때문입니다. 이름이 공식 이름을 모방할 때 `claude plugin list` 및 `/plugin` **오류** 탭은 다음과 같이 시작하는 메시지와 함께 영향을 받는 각 플러그인을 보고합니다:
3672
3673```text theme={null}
3674Claude Code refuses the marketplace name "anthropic-plugins-v2"
3675```
3676
3677모방하는 이름의 경우 마켓플레이스 자체의 오류는 `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`로 거부합니다.
3678
3679v2.1.282 이전에는 `claude plugin list` 및 `/plugin`이 모방하는 이름의 플러그인을 마켓플레이스의 이름을 원인으로 명명하지 않고 로드 실패로 보고했습니다.
3680
3681**수행할 작업:**
3682
3683* `claude plugin marketplace remove <name>`을 실행하십시오. 이는 또한 마켓플레이스에서 설치된 플러그인을 제거하고 저장된 데이터를 삭제합니다.
3684* 대신 마켓플레이스를 유지하려면 유지 관리자가 이름을 바꿀 때까지 기다린 다음 `claude plugin marketplace update <name>`을 실행하십시오.
3685* 마켓플레이스를 게시하는 경우 `marketplace.json`에서 이름을 바꾸십시오. 사용자는 제거하는 대신 마켓플레이스를 업데이트합니다.
3686
3455<h3 id="marketplace-is-already-added-from-a-different-source">3687<h3 id="marketplace-is-already-added-from-a-different-source">
3456 Marketplace is already added from a different source3688 Marketplace is already added from a different source
3457</h3>3689</h3>
3654 3886
3655* claude.ai 조직의 관리자에게 claude.ai에서 플러그인의 필수 상태를 변경하도록 요청하십시오.3887* claude.ai 조직의 관리자에게 claude.ai에서 플러그인의 필수 상태를 변경하도록 요청하십시오.
3656 3888
3889<h3 id="plugin-was-not-uninstalled">
3890 Plugin was not uninstalled
3891</h3>
3892
3893[`claude plugin uninstall`](/docs/ko/plugins/cli-reference#plugin-uninstall)을 실행했거나 `/plugin` **설치됨** 탭에서 **제거**를 선택했으며 제거가 `"<plugin>" was not uninstalled:`로 시작하는 메시지와 함께 중지되었습니다.
3894
3895Claude Code가 `enabledPlugins`에서 플러그인의 항목을 제거하고 해당 범위의 설정 파일을 다시 읽었을 때 플러그인이 여전히 켜져 있었거나 이를 켤 수 있는 파일을 읽거나 확인할 수 없었습니다. 설정 항목이 이를 다시 켤 수 있는 동안 플러그인의 저장된 옵션, 비밀 및 데이터를 삭제하면 이를 잃게 되므로 제거가 대신 중지됩니다: 플러그인은 설치된 상태로 유지되고 저장된 것은 삭제되지 않습니다.
3896
3897```text theme={null}
3898✘ 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.
3899```
3900
3901메시지의 중간 부분은 파일과 원인의 이름을 지정합니다:
3902
3903* `it is still switched on in <file>, although the settings change reported no error`: 설정 쓰기가 성공를 보고했지만 파일을 읽을 때 항목이 여전히 있음
3904* `it is still switched on in <file>, and the settings change failed (<error>)`: 파일을 저장할 수 없음. 괄호 안의 이유
3905* `<file> is there and could not be read`: 파일이 존재하지만 설정으로 읽을 수 없음. 예를 들어 유효한 JSON이 아니므로 플러그인을 여전히 활성화할 수 있음
3906* `<file> (not read: it is on a network path or is a link to one, or could not be checked)`: Claude Code가 프로젝트 또는 로컬 설정 파일을 읽지 않았습니다. 파일 또는 이를 보유한 `.claude` 폴더가 네트워크 위치로 이어지는 링크이거나 해당 경로를 검사할 수 없기 때문입니다.
3907
3908`claude plugin uninstall`은 종료 코드 1로 종료되며 `--json`을 사용하면 결과는 `failureCode: "settings_still_on"`을 전달합니다. `/plugin`은 동일한 메시지를 표시합니다.
3909
3910**수행할 작업:**
3911
3912* 메시지의 마지막 문장을 따르십시오: 이를 명명한 설정 파일을 복구하거나 바꾸거나 해당 파일의 `enabledPlugins`에서 플러그인의 항목을 직접 제거한 다음 제거를 다시 실행하십시오.
3913
3657<h2 id="tool-errors">3914<h2 id="tool-errors">
3658 도구 오류3915 도구 오류
3659</h2>3916</h2>
3703* Claude가 파일을 변경할 수 있어야 하면 `/permissions`의 `Read` 거부 규칙을 제거하거나 좁힙니다. 또는 [설정](/docs/ko/settings-reference#permission-settings)에서 제거합니다.3960* Claude가 파일을 변경할 수 있어야 하면 `/permissions`의 `Read` 거부 규칙을 제거하거나 좁힙니다. 또는 [설정](/docs/ko/settings-reference#permission-settings)에서 제거합니다.
3704* 파일이 그대로 유지되어야 하면 규칙을 유지하고 NotebookEdit 도구도 차단하기 위해 동일한 경로에 `Edit` 거부 규칙을 추가합니다.3961* 파일이 그대로 유지되어야 하면 규칙을 유지하고 NotebookEdit 도구도 차단하기 위해 동일한 경로에 `Edit` 거부 규칙을 추가합니다.
3705 3962
3963<h3 id="path-cannot-contain-null-bytes">
3964 경로에 null 바이트가 포함될 수 없음
3965</h3>
3966
3967파일 도구 호출의 경로 또는 패턴 인수에 null 바이트가 포함되어 있으며, 파일 시스템과 검색 도구는 이를 수락할 수 없습니다. Read, Write, Edit, NotebookEdit, Glob 및 Grep은 이를 확인하고 메시지는 도구와 인수의 이름을 지정합니다:
3968
3969```text theme={null}
3970Read file_path cannot contain null bytes (\0). Remove the null byte and try again.
3971```
3972
3973도구 호출이 실패하고 Claude는 오류를 보며 턴이 계속됩니다.
3974
3975**할 일:**
3976
3977* 당신 쪽에서는 아무것도 할 필요가 없습니다: 오류는 도구의 결과로 Claude에 반환되며 메시지 자체가 Claude에 null 바이트를 제거하고 다시 시도하도록 지시합니다.
3978
3979v2.1.281 이전에는 Read, Write, Edit 또는 NotebookEdit 경로의 null 바이트가 `Path contains null bytes`라는 이름의 오류로 전체 턴을 종료했으며 도구는 실행되지 않았습니다.
3980
3706<h3 id="subagent-type-is-required">3981<h3 id="subagent-type-is-required">
3707 subagent\_type이 필수입니다3982 subagent\_type이 필수입니다
3708</h3>3983</h3>
3839 4114
3840v2.1.236 이전에는 Claude Code가 이러한 전송을 보낸 것으로 보고했습니다. 수신 세션이 읽지 않고 삭제했습니다.4115v2.1.236 이전에는 Claude Code가 이러한 전송을 보낸 것으로 보고했습니다. 수신 세션이 읽지 않고 삭제했습니다.
3841 4116
4117<h3 id="cross-session-message-dropped-at-the-inbox">
4118 교차 세션 메시지가 수신자 세션의 받은편지함에서 삭제됨
4119</h3>
4120
4121Claude가 [교차 세션 메시지](/docs/ko/cross-session-messaging)를 이 머신의 다른 세션으로 보냈고 해당 세션의 받은편지함이 Claude가 해당 세션에서 읽기 전에 메시지를 삭제했습니다. 줄은 수신자의 주소를 지정하고, 수신자가 이유를 제공했을 때 대시 뒤에 이유를 추가합니다:
4122
4123```text wrap theme={null}
4124Cross-session message was dropped at the recipient session's inbox (recipient: uds:/tmp/cc-socks/13605.sock) and not delivered — its queue of undelivered peer messages was full. Claude was told not to resend right away.
4125```
4126
4127한 줄이 여러 삭제된 메시지를 포함할 수 있습니다. 그러면 복수형으로 시작합니다. 예를 들어 `Cross-session messages (12) were dropped`입니다. 주소가 어느 세션에 속하는지 찾으려면 각 세션에서 `/status`가 표시하는 [`Peer address` 행](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)과 비교합니다.
4128
4129대시 뒤에 줄은 다음 이유 중 하나 이상을 제공합니다:
4130
4131* `its queue of undelivered peer messages was full`: 수신자가 이미 다른 세션에서 받은편지함이 허용하는 만큼 많은 전달되지 않은 메시지를 보유하고 있습니다.
4132* `you sent faster than that session accepts`: 전송 세션의 메시지가 수신자가 한 발신자로부터 수락하는 것보다 빠르게 도착했습니다.
4133* `it repeated your previous message`: 메시지가 전송 세션이 이 수신자로 최근에 보낸 메시지와 동일했습니다.
4134* `a relay loop between sessions was cut`: 메시지가 세션이 서로 메시지를 보내는 체인을 계속했고 체인이 수신자를 너무 많이 통과했거나 너무 길어졌습니다.
4135
4136**할 일:**
4137
4138* 수신자가 삭제된 메시지를 본 적이 없다고 가정합니다. Claude Code는 동일하게 Claude에 알리고 여전히 중요한 것을 나중에 한 메시지에 포함하도록 지시합니다.
4139* 세션이 서로 자주 업데이트를 보내면 Claude에 더 적은 수의 더 큰 메시지를 보내도록 요청합니다. 예를 들어 세션이 작업을 완료할 때 한 보고서입니다.
4140* `a relay loop between sessions was cut`의 경우 세션 중 하나에 직접 다음 지시를 입력합니다. Claude가 자신의 프롬프트에 응답하여 보내는 메시지는 새 체인을 시작합니다.
4141
4142v2.1.238 이전에는 수신자의 받은편지함이 메시지를 삭제했을 때 전송 세션이 보고를 받지 못했습니다.
4143
3842<h3 id="refusing-to-send-a-cross-session-message">4144<h3 id="refusing-to-send-a-cross-session-message">
3843 교차 세션 메시지 전송 거부4145 교차 세션 메시지 전송 거부
3844</h3>4146</h3>
3853 4155
3854* `reply target is a symlink`: 기호 링크가 대상 세션의 소켓 경로에 있습니다. Claude Code는 링크가 대상 세션이 만들지 않은 엔드포인트로 메시지를 리디렉션할 수 있으므로 이를 통해 전달하지 않습니다.4156* `reply target is a symlink`: 기호 링크가 대상 세션의 소켓 경로에 있습니다. Claude Code는 링크가 대상 세션이 만들지 않은 엔드포인트로 메시지를 리디렉션할 수 있으므로 이를 통해 전달하지 않습니다.
3855* `cannot vet reply target`: Claude Code가 대상 경로를 전혀 검사할 수 없습니다. 예를 들어 권한 오류로 읽기가 실패한 경우입니다.4157* `cannot vet reply target`: Claude Code가 대상 경로를 전혀 검사할 수 없습니다. 예를 들어 권한 오류로 읽기가 실패한 경우입니다.
3856* `connected endpoint is not the expected process`: 소켓을 보유한 프로세스가 메시지가 주소 지정된 세션이 아니므로 주소가 오래되었거나 다른 프로세스가 소켓을 대체했습니다.
3857* `connected endpoint identity could not be read`: Claude Code가 연결했지만 소켓의 다른 쪽을 보유한 프로세스를 읽을 수 없어서 대상을 확인할 수 없습니다. 이는 일시적일 수 있습니다.
3858* `connected endpoint is not owned by this user`: 소켓을 보유한 프로세스가 다른 사용자 계정으로 실행되므로 세션 중 하나가 아닙니다.
3859* `connected endpoint owner could not be read`: Claude Code가 연결했지만 다른 쪽을 소유한 사용자 계정을 읽을 수 없어서 엔드포인트가 당신의 것인지 확인할 수 없습니다.
3860* `connected endpoint is a different process with the expected pid`: 프로세스 ID가 메시지가 주소 지정된 것과 일치하지만 Claude Code가 동일한 프로세스인지 확인할 수 없습니다. 보통 해당 세션이 종료되었고 운영 체제가 프로세스 ID를 재사용했으므로 주소가 오래되었습니다.
3861 4158
3862**할 일:**4159**할 일:**
3863 4160
3864* 보통 아무것도 하지 않습니다: 확인은 메시지가 주소 지정된 세션 이외의 엔드포인트에 도달하는 것을 방지하며 아무것도 보내지지 않았습니다.4161* 보통 아무것도 하지 않습니다: 확인은 메시지가 주소 지정된 세션 이외의 엔드포인트에 도달하는 것을 방지하며 아무것도 보내지지 않았습니다.
3865* Claude에 세션을 다시 나열하고 다시 보내도록 요청합니다. 오래된 주소로 인한 거부는 Claude가 현재 세션으로 보낸 후 해결됩니다.
3866* 한 세션에 대해 `reply target is a symlink`가 반복되면 해당 세션의 소켓 경로에 링크를 만든 것을 확인합니다. 이는 `/status` 아래의 `Peer address`에 표시됩니다.4162* 한 세션에 대해 `reply target is a symlink`가 반복되면 해당 세션의 소켓 경로에 링크를 만든 것을 확인합니다. 이는 `/status` 아래의 `Peer address`에 표시됩니다.
3867* `connected endpoint identity could not be read`의 경우 다시 보냅니다. 조건은 일시적일 수 있습니다.
3868* 공유 머신에서 `connected endpoint is not owned by this user`가 나타나면 해당 주소의 세션이 다른 사용자의 계정으로 실행되므로 Claude가 당신의 계정에서 메시지를 보낼 수 없습니다.
3869
3870v2.1.248 이전에는 Claude Code가 엔드포인트의 소유 사용자 또는 프로세스 시작 시간을 확인하지 않았으므로 이러한 확인의 이름을 지정하는 거부는 이전 버전에 나타나지 않습니다.
3871 4163
3872<h3 id="refusing-after-a-symlink-changed">4164<h3 id="refusing-after-a-symlink-changed">
3873 경로 읽기, 쓰기 또는 검색 거부4165 경로 읽기, 쓰기 또는 검색 거부
3883 4175
3884* `its symlink resolution changed after permission was checked`: 경로를 따라 또는 Grep 또는 Glob 검색 루트에서 기호 링크가 권한 확인과 작업 사이에 대체되었습니다. 읽기 거부에서 괄호 안의 구문은 어느 비교가 실패했는지 지정합니다.4176* `its symlink resolution changed after permission was checked`: 경로를 따라 또는 Grep 또는 Glob 검색 루트에서 기호 링크가 권한 확인과 작업 사이에 대체되었습니다. 읽기 거부에서 괄호 안의 구문은 어느 비교가 실패했는지 지정합니다.
3885* `its parent-directory symlink resolution changed after permission was checked`: 쓰기 경로가 통과하는 디렉토리가 더 이상 승인된 위치로 해석되지 않습니다.4177* `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를 링크의 대상으로 지시합니다.4178* `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가 경로를 디스크의 최종 위치로 따를 수 없습니다. 예를 들어 경로의 기호 링크가 루프를 형성하거나 링크가 해석되지 않는 경우입니다.
4179* `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`에 대한 쓰기입니다.4180* `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/` 디렉토리가 다른 위치로 연결되어 있습니다.4181* `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가 검색을 준비하는 동안 해당 링크가 변경되었습니다.4182* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`: `Read` 거부 규칙이 기호 링크를 통과하는 경로의 이름을 지정했고 Claude Code가 검색을 준비하는 동안 해당 링크가 변경되었습니다.
3901 4194
3902v2.1.251 이전에는 Claude Code가 파일 쓰기에 대해서만 경로의 해석을 다시 확인했으므로 권한 확인 후 대체된 링크가 메시지 없이 읽기 또는 검색을 다른 위치로 리디렉션할 수 있었습니다. 이러한 거부 중에서 부모 디렉토리, 기호 링크를 통한, 그리고 기호 링크된 디렉토리 쓰기 거부만 이전 버전에 나타납니다.4195v2.1.251 이전에는 Claude Code가 파일 쓰기에 대해서만 경로의 해석을 다시 확인했으므로 권한 확인 후 대체된 링크가 메시지 없이 읽기 또는 검색을 다른 위치로 리디렉션할 수 있었습니다. 이러한 거부 중에서 부모 디렉토리, 기호 링크를 통한, 그리고 기호 링크된 디렉토리 쓰기 거부만 이전 버전에 나타납니다.
3903 4196
4197v2.1.280 이전에는 `where it leads on disk could not be determined` 거부가 나타나지 않았습니다.
4198
3904<h3 id="task-output-swap-refused">4199<h3 id="task-output-swap-refused">
3905 작업 출력 스왑 거부4200 작업 출력 스왑 거부
3906</h3>4201</h3>
3926* 또는 Claude Code 임시 디렉토리 아래의 프로젝트 디렉토리를 확인합니다. 예제 메시지의 `/private/tmp/claude-501/-Users-you-my-project`입니다. 해당 경로가 기호 링크이거나 거기에 있으면 안 되는 디렉토리이면 링크의 대상이 아닌 링크 또는 디렉토리 자체를 제거하고 Claude Code를 다시 시작합니다.4221* 또는 Claude Code 임시 디렉토리 아래의 프로젝트 디렉토리를 확인합니다. 예제 메시지의 `/private/tmp/claude-501/-Users-you-my-project`입니다. 해당 경로가 기호 링크이거나 거기에 있으면 안 되는 디렉토리이면 링크의 대상이 아닌 링크 또는 디렉토리 자체를 제거하고 Claude Code를 다시 시작합니다.
3927* 거부가 반복되면 프로세스가 세션이 실행되는 동안 Claude Code의 임시 디렉토리 아래의 항목을 대체, 링크 또는 제거합니다. [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 다른 것이 관리하지 않는 디렉토리로 설정하고 다시 시작합니다.4222* 거부가 반복되면 프로세스가 세션이 실행되는 동안 Claude Code의 임시 디렉토리 아래의 항목을 대체, 링크 또는 제거합니다. [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 다른 것이 관리하지 않는 디렉토리로 설정하고 다시 시작합니다.
3928 4223
4224<h3 id="disk-quota-or-temp-filesystem-is-full">
4225 디스크 할당량 또는 임시 파일 시스템이 가득 참
4226</h3>
4227
4228Claude Code는 각 Bash 및 PowerShell 명령의 출력을 임시 디렉토리 아래의 파일에 저장합니다. 명령이 0이 아닌 코드로 종료되고 출력이 전혀 없으면 Claude Code는 해당 파일을 보유한 파일 시스템이 공간 또는 inode가 부족한지, 또는 디스크 할당량이 사용되었는지 확인합니다. 그렇다면 진단이 빈 출력 대신 명령의 결과에 나타납니다:
4229
4230```text wrap theme={null}
4231Your 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.
4232```
4233
4234메시지는 무엇이 부족한지 지정합니다:
4235
4236* `Your disk quota is full ... (EDQUOT)`: 해당 파일 시스템에 대한 당신의 할당량이 사용되었습니다. 할당량은 파일 시스템이 여전히 여유 공간을 표시하는 동안 가득 찰 수 있습니다.
4237* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`: 파일 시스템 또는 할당량에 공간이 남지 않았습니다.
4238* `Command output was lost: the temp filesystem at ... is full` 또는 `... is out of inodes`: 파일 시스템에 거의 여유 공간이 남지 않았거나 inode가 부족합니다.
4239
4240**할 일:**
4241
4242* Claude Code의 임시 디렉토리를 보유한 파일 시스템에서 더 이상 필요하지 않은 파일을 삭제합니다. `EDQUOT`의 경우 당신의 할당량에 포함되는 파일을 삭제합니다. `out of inodes`의 경우 각 파일이 크기에 관계없이 하나의 inode를 차지하므로 몇 개의 큰 파일이 아닌 많은 파일을 삭제합니다.
4243* 또는 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)을 여유 공간이 있는 파일 시스템의 디렉토리로 설정하여 Claude Code를 다시 시작합니다.
4244* 그런 다음 Claude에 명령을 다시 실행하도록 합니다. 인쇄한 출력은 손실되었으며 잘리지 않았습니다.
4245
3929<h3 id="the-source-file-is-not-valid-utf-8-text">4246<h3 id="the-source-file-is-not-valid-utf-8-text">
3930 소스 파일이 유효한 UTF-8 텍스트가 아님4247 소스 파일이 유효한 UTF-8 텍스트가 아님
3931</h3>4248</h3>
3993 백그라운드 세션에서 거부된 명령4310 백그라운드 세션에서 거부된 명령
3994</h3>4311</h3>
3995 4312
3996대화형 대화 상자를 여는 명령은 백그라운드 세션에 터미널이 연결되지 않은 상태에서는 그렇게 할 수 없습니다. `/install-github-app`, `/mcp` 설정 목록 및 MCP 서버 메뉴의 인증 작업은 메시지로 응답하며, 세션은 [에이전트 뷰](/docs/ko/agent-view)의 **입력 필요** 아래에 나타나므로 찾아서 연결하고 명령을 다시 실행할 수 있습니다. 터미널이 연결되어 있는 동안 이러한 명령은 정상적으로 작동합니다.4313대화형 대화 상자를 여는 명령은 백그라운드 세션에 터미널이 연결되지 않은 상태에서는 그렇게 할 수 없습니다. `/install-github-app`, `/mcp` 설정 목록 및 MCP 서버 메뉴의 인증 작업은 메시지로 응답하며, `/install-github-app` 및 `/mcp` 설정 목록의 경우 세션은 [에이전트 뷰](/docs/ko/agent-view)의 **입력 필요** 아래에 나타나므로 찾아서 연결하고 명령을 다시 실행할 수 있습니다. 터미널이 연결되어 있는 동안 이러한 명령은 정상적으로 작동합니다.
3997 4314
3998v2.1.216 이전에는 이러한 거부 중 하나 후에 세션이 **입력 필요** 아래에 나타나지 않았습니다. v2.1.213부터 v2.1.215까지는 터미널이 연결되어 있는 동안 명령이 여전히 작동했으며, 거부 메시지는 연결하고 명령을 다시 실행하도록 지시했습니다. v2.1.208부터 v2.1.212까지는 Claude Code가 터미널이 연결되어 있는 동안에도 이를 거부했으며, `Can't open MCP settings in a background session`과 같은 메시지가 표시되었습니다. 이러한 버전에서는 일반 `claude` 세션에서 명령을 실행하거나 업그레이드하십시오. v2.1.208 이전에는 백그라운드 세션 내에서 대화 상자를 열었습니다. v2.1.208에서만 Claude Code는 백그라운드 세션에서 `/model` 선택기도 거부했으며, `/upgrade`는 브라우저를 열지 않고 업그레이드 URL을 인쇄했습니다.4315v2.1.216 이전에는 `/install-github-app` 또는 `/mcp` 설정 목록이 거부된 후 세션이 **입력 필요** 아래에 나타나지 않았습니다. v2.1.213부터 v2.1.215까지는 터미널이 연결되어 있는 동안 명령이 여전히 작동했으며, 거부 메시지는 연결하고 명령을 다시 실행하도록 지시했습니다. v2.1.208부터 v2.1.212까지는 Claude Code가 터미널이 연결되어 있는 동안에도 이를 거부했으며, `Can't open MCP settings in a background session`과 같은 메시지가 표시되었습니다. 이러한 버전에서는 일반 `claude` 세션에서 명령을 실행하거나 업그레이드하십시오. v2.1.208 이전에는 백그라운드 세션 내에서 대화 상자를 열었습니다. v2.1.208에서만 Claude Code는 백그라운드 세션에서 `/model` 선택기도 거부했으며, `/upgrade`는 브라우저를 열지 않고 업그레이드 URL을 인쇄했습니다.
3999 4316
4000표현은 명령의 이름을 지정합니다. `/mcp` 설정 목록은 다음을 보고합니다:4317표현은 명령의 이름을 지정합니다. `/mcp` 설정 목록은 다음을 보고합니다:
4001 4318
4005 4322
4006**할 일:**4323**할 일:**
4007 4324
4008* 에이전트 뷰에서 **입력 필요** 아래에 나열된 세션에 연결하고 명령을 다시 실행합니다.4325* 에이전트 뷰에서 세션에 연결하고 명령을 다시 실행합니다.
4009* 또는 `/mcp reconnect <server>`, `/mcp enable` 또는 `/mcp disable`과 같이 메시지가 명시하는 형식을 사용합니다. 이는 연결하지 않고도 작동합니다.4326* 또는 `/mcp reconnect <server>`, `/mcp enable` 또는 `/mcp disable`과 같이 메시지가 명시하는 형식을 사용합니다. 이는 연결하지 않고도 작동합니다.
4010 4327
4011<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">4328<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">
4040**할 일:**4357**할 일:**
4041 4358
4042* 일반적으로 아무것도 하지 않습니다: Claude는 메시지가 요청하는 로컬 철자로 재시도합니다.4359* 일반적으로 아무것도 하지 않습니다: Claude는 메시지가 요청하는 로컬 철자로 재시도합니다.
4043* 파일이 로컬 파일이 아닌 네트워크 공유에 있는 경우 네트워크 경로로 철자된 경우 세션의 로컬 작업 공간 외부에 있습니다. 일반 대화형 세션에서 편집합니다.
4044 4360
4045<h3 id="command-blocked-by-the-worktree-isolation-checks">4361<h3 id="command-blocked-by-the-worktree-isolation-checks">
4046 Worktree 격리 확인으로 인해 명령이 차단됨4362 Worktree 격리 확인으로 인해 명령이 차단됨
4275 4591
4276일부 계정에서 메시지는 `background service` 대신 `daemon`을 말합니다.4592일부 계정에서 메시지는 `background service` 대신 `daemon`을 말합니다.
4277 4593
4278npm 설치에서 `npm install -g @anthropic-ai/claude-code`가 바이너리를 대체하는 동안 나타나는 `EUNKNOWN`은 [`EACCES` during a reinstall](#eacces-when-starting-a-background-session)과 같은 원인을 가지며 설치가 완료된 후 재시도할 때 지워집니다.4594npm 설치에서 `npm install -g @anthropic-ai/claude-code`가 바이너리를 대체하는 동안 나타나는 `EUNKNOWN`은 [백그라운드 세션을 시작할 때 EACCES](#eacces-when-starting-a-background-session)와 같은 원인을 가지며 설치가 완료된 후 재시도할 때 지워집니다.
4279 4595
4280Claude Code는 서비스가 터미널을 닫을 때 생존하도록 PowerShell을 통해 백그라운드 서비스를 시작하며, PowerShell 7이 설치되어 있으면 PowerShell 7을 사용하고 그렇지 않으면 Windows PowerShell 5.1을 사용합니다. PowerShell이 실행될 수 없으면 Claude Code는 대신 서비스를 직접 시작하므로 PowerShell만 차단하는 정책은 이 오류를 발생시키지 않습니다. npm 설치가 실행 중이 아닌 동안 이를 보면 정책이 Claude Code 실행 파일 자체를 차단합니다.4596Claude Code는 서비스가 터미널을 닫을 때 생존하도록 PowerShell을 통해 백그라운드 서비스를 시작하며, PowerShell 7이 설치되어 있으면 PowerShell 7을 사용하고 그렇지 않으면 Windows PowerShell 5.1을 사용합니다. PowerShell이 실행될 수 없으면 Claude Code는 대신 서비스를 직접 시작하므로 PowerShell만 차단하는 정책은 이 오류를 발생시키지 않습니다.
4281 4597
4282v2.1.212 이전에는 Claude Code가 Windows PowerShell 5.1만 사용하여 서비스를 시작했으므로 그룹 정책이 PowerShell 5.1을 차단한 모든 머신이 `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`으로 실패했으며, PowerShell 7이 설치되어 있었습니다.4598v2.1.212 이전에는 Claude Code가 Windows PowerShell 5.1만 사용하여 서비스를 시작했으므로 그룹 정책이 PowerShell 5.1을 차단한 모든 머신이 `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`으로 실패했으며, PowerShell 7이 설치되어 있었습니다.
4283 4599
4341 백그라운드 세션을 시작할 때 작업 디렉토리가 더 이상 존재하지 않음4657 백그라운드 세션을 시작할 때 작업 디렉토리가 더 이상 존재하지 않음
4342</h3>4658</h3>
4343 4659
4344더 이상 존재하지 않는 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하려고 했습니다. 이는 에이전트 뷰에서 디스패치하거나 작업 중인 디렉토리가 삭제되거나 이동된 후 `/background`를 실행할 때 발생합니다. 또한 프로세스가 종료되고 디렉토리가 없는 세션에 연결하거나 다시 시작할 때 발생합니다. 새 프로세스가 같은 디렉토리에서 시작되기 때문입니다. Claude Code는 세션을 시작하지 않으며 메시지는 누락된 디렉토리를 명시합니다:4660더 이상 존재하지 않는 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하려고 했습니다. Claude Code는 세션을 시작하지 않으며 메시지는 누락된 디렉토리를 명시합니다:
4345 4661
4346```text theme={null}4662```text theme={null}
4347Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)4663Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)
4349 4665
4350v2.1.257 이전에는 세션이 시작된 것처럼 보였다가 에이전트 뷰에서 같은 이유로 실패한 행으로 표시되었습니다.4666v2.1.257 이전에는 세션이 시작된 것처럼 보였다가 에이전트 뷰에서 같은 이유로 실패한 행으로 표시되었습니다.
4351 4667
4668v2.1.281 이전에는 이 메시지가 세션을 시작하기 전에 디렉토리가 이미 없었을 때도 나타났습니다. 그 경우는 [`could not be resolved on disk`](#workspace-not-trusted-when-dispatching-a-background-session)를 보고합니다.
4669
4352**할 일:**4670**할 일:**
4353 4671
4354* 메시지가 명시하는 디렉토리를 다시 만들거나 존재하는 디렉토리에서 디스패치한 다음 다시 시도합니다.4672* 메시지가 명시하는 디렉토리를 다시 만들거나 존재하는 디렉토리에서 디스패치한 다음 다시 시도합니다.
4355 4673
4674<h3 id="workspace-not-trusted-when-dispatching-a-background-session">
4675 백그라운드 세션을 디스패치할 때 작업 공간을 신뢰하지 않음
4676</h3>
4677
4678[신뢰하지 않은](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 디렉토리에서 [백그라운드 세션](/docs/ko/agent-view)을 시작하거나 다시 시작했으며, 작업 공간 신뢰 대화가 나타날 수 없었습니다. Claude Code는 세션을 시작하지 않습니다:
4679
4680```text theme={null}
4681Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.
4682```
4683
4684세션의 자체 디렉토리의 터미널에서 같은 명령은 신뢰 대화를 대신 표시하고 수락하면 세션을 시작합니다. 이 메시지는 스크립트와 같이 대화가 나타날 수 없는 곳이나 다른 디렉토리에서 세션을 다시 시작할 때 나타납니다.
4685
4686두 가지 변형은 다른 원인을 명시합니다:
4687
4688* **`The home directory is trusted one session at a time`**: 세션의 디렉토리는 홈 디렉토리입니다. Claude Code는 홈 디렉토리에 대한 신뢰를 절대 저장하지 않으므로 이전 세션에서 대화를 수락해도 계산되지 않습니다.
4689* **`<path> could not be resolved on disk`**: Claude Code가 디스크에서 세션의 디렉토리를 찾을 수 없었습니다.
4690
4691**할 일:**
4692
4693* 메시지가 명시하는 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락한 다음 명령을 다시 실행합니다.
4694* 홈 디렉토리 메시지의 경우 홈 디렉토리의 터미널에서 명령을 실행하여 대화가 나타날 수 있도록 하거나 프로젝트 디렉토리에서 대신 세션을 시작합니다.
4695* `could not be resolved on disk` 메시지의 경우 디렉토리를 다시 만들거나 존재하는 디렉토리에서 새 세션을 시작합니다.
4696
4356<h2 id="wrapper-and-ide-errors">4697<h2 id="wrapper-and-ide-errors">
4357 래퍼 및 IDE 오류4698 래퍼 및 IDE 오류
4358</h2>4699</h2>
4437 4778
4438* 건너뛴 파일을 식별하여 아래 단계로 각각을 처리할 수 있도록 합니다. 메시지는 개수만 제공하므로, 복원이 실행될 때 건너뛴 각 경로를 이름으로 나열하는 디버그 로그 `~/.claude/debug/<session-id>.txt`를 확인하고, 다음 복원 전에 `/debug`로 디버그 로깅을 켭니다. macOS 또는 Linux에서는 대신 링크를 직접 찾을 수 있습니다: 심볼릭 링크는 `find . -type l`, 하드 링크된 파일은 `find . -type f -links +1`을 사용합니다.4779* 건너뛴 파일을 식별하여 아래 단계로 각각을 처리할 수 있도록 합니다. 메시지는 개수만 제공하므로, 복원이 실행될 때 건너뛴 각 경로를 이름으로 나열하는 디버그 로그 `~/.claude/debug/<session-id>.txt`를 확인하고, 다음 복원 전에 `/debug`로 디버그 로깅을 켭니다. macOS 또는 Linux에서는 대신 링크를 직접 찾을 수 있습니다: 심볼릭 링크는 `find . -type l`, 하드 링크된 파일은 `find . -type f -links +1`을 사용합니다.
4439* 건너뛴 파일이 dotfile 관리자가 관리하는 설정 파일이나 pnpm과 같은 도구로 하드 링크된 파일처럼 의도적으로 만든 링크인 경우, 되돌리기는 해당 내용을 그대로 두었습니다. 세션의 변경 사항을 취소하려면 Claude에게 편집을 되돌리도록 요청하거나 파일을 직접 편집합니다.4780* 건너뛴 파일이 dotfile 관리자가 관리하는 설정 파일이나 pnpm과 같은 도구로 하드 링크된 파일처럼 의도적으로 만든 링크인 경우, 되돌리기는 해당 내용을 그대로 두었습니다. 세션의 변경 사항을 취소하려면 Claude에게 편집을 되돌리도록 요청하거나 파일을 직접 편집합니다.
4440* 링크를 만들지 않았다면, 해당 경로의 내용을 신뢰하기 전에 검사합니다: 체크포인트 이후 무언가가 파일을 대체했을 수 있습니다.4781* 링크를 만들지 않았다면, 해당 경로의 내용을 신뢰하기 전에 검사합니다.
4441 4782
4442<h3 id="no-files-were-restored">4783<h3 id="no-files-were-restored">
4443 파일이 복원되지 않음4784 파일이 복원되지 않음
4532 구성 경고4873 구성 경고
4533</h2>4874</h2>
4534 4875
4535Claude Code는 이러한 메시지의 대부분을 stderr에 기록하며, 대부분을 시작 시에 기록합니다. 항목이 디버그 로그나 대화 보기의 시작 알림 같은 다른 곳에 나타나거나 [인식되지 않은 모델 진단 라인](#unrecognized-model-id-on-a-request)처럼 요청 시간에 나타나는 경우 그렇게 표시됩니다.4876Claude Code는 이러한 메시지 대부분을 대화가 아닌 stderr에 기록하며, 대부분 시작 시에 기록합니다. 항목이 디버그 로그나 대화 보기의 시작 알림 같은 다른 곳에 나타나거나 요청 시간의 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request) 같은 다른 시간에 나타나면 그렇게 표시됩니다.
4536 4877
4537<h3 id="fullscreen-failed-start-notice">4878<h3 id="fullscreen-failed-start-notice">
4538 전체 화면 렌더러가 시작을 완료하지 못함4879 전체 화면 렌더러가 시작을 완료하지 못함
4541이 머신의 이전 [전체 화면](/docs/ko/fullscreen) 세션이 시작을 완료하기 전에 종료되었으므로 Claude Code는 이 세션을 클래식 렌더러에서 시작하고 다음 알림 중 하나를 출력합니다:4882이 머신의 이전 [전체 화면](/docs/ko/fullscreen) 세션이 시작을 완료하기 전에 종료되었으므로 Claude Code는 이 세션을 클래식 렌더러에서 시작하고 다음 알림 중 하나를 출력합니다:
4542 4883
4543```text theme={null}4884```text theme={null}
4544Claude Code의 전체 화면 렌더러가 지난번 이 머신에서 시작을 완료하지 못했으므로 이번 실행은 클래식 렌더러를 사용합니다. 다음 실행에서 전체 화면을 다시 시도할 것입니다. /tui default는 클래식 렌더러를 유지합니다.4885Claude Code의 전체 화면 렌더러가 이 머신에서 마지막으로 시작을 완료하지 못했으므로 이번 실행은 클래식 렌더러를 사용합니다. 다음 실행에서 전체 화면을 다시 시도할 것입니다. /tui default는 클래식 렌더러를 유지합니다.
4545 4886
4546Claude Code의 전체 화면 렌더러가 이 머신에서 반복적으로 시작에 실패했으므로 여기서 비활성화되었습니다. /tui fullscreen을 실행하여 다시 시도하세요(이는 업데이트 후에도 재설정됩니다).4887Claude Code의 전체 화면 렌더러가 이 머신에서 반복적으로 시작에 실패했으므로 여기서 비활성화되었습니다. /tui fullscreen을 실행하여 다시 시도하세요(이는 업데이트 후에도 재설정됩니다).
4547```4888```
4549**할 일:**4890**할 일:**
4550 4891
4551* [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting)을 따르세요. 어떤 알림을 받는지, Claude Code가 이후 세션에서 무엇을 하는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 설명합니다.4892* [전체 화면 렌더링](/docs/ko/fullscreen#fullscreen-renderer-didnt-finish-starting)을 따르세요. 어떤 알림을 받는지, Claude Code가 이후 세션에서 무엇을 하는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 설명합니다.
4552* 종료된 세션이 종료 메시지를 출력했다면 [복구할 수 없는 인터페이스 오류 후 Claude Code 종료](#exited-after-an-unrecoverable-interface-error)를 참조하여 이름이 지정된 내용을 확인하세요.4893* 종료된 세션이 종료 메시지를 출력했다면 [Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨](#exited-after-an-unrecoverable-interface-error)을 참조하여 이름이 지정된 내용을 확인하세요.
4553 4894
4554v2.1.236 이전에는 Claude Code가 알림을 출력하지 않았고 실패한 시작 후에도 계속 전체 화면 렌더링에서 세션을 시작했습니다.4895v2.1.236 이전에는 Claude Code가 알림을 출력하지 않았고 실패한 시작 후에도 전체 화면 렌더링에서 세션을 계속 시작했습니다.
4555 4896
4556<h3 id="exited-after-an-unrecoverable-interface-error">4897<h3 id="exited-after-an-unrecoverable-interface-error">
4557 복구할 수 없는 인터페이스 오류 후 Claude Code 종료4898 Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨
4558</h3>4899</h3>
4559 4900
4560Claude Code는 터미널 인터페이스가 복구할 수 없는 오류에 부딪혔을 때 종료되며, 두 렌더러 중 하나에서 이 메시지를 출력합니다. 두 번째 문장은 [전체 화면](/docs/ko/fullscreen) 렌더러가 시작되는 동안 오류가 발생했을 때만 나타납니다:4901Claude Code는 터미널 인터페이스가 복구할 수 없는 오류에 부딪혔을 때 이 메시지를 출력하고 종료합니다(두 렌더러 모두). 두 번째 문장은 [전체 화면](/docs/ko/fullscreen) 렌더러가 시작되는 동안 오류가 발생했을 때만 나타납니다:
4561 4902
4562```text theme={null}4903```text theme={null}
4563Claude Code가 복구할 수 없는 인터페이스 오류(<error>)로 인해 종료되었습니다. 전체 화면 렌더러가 시작되는 동안 발생했으므로 다음 실행은 클래식 렌더러를 사용할 것입니다(CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1은 언제든지 이를 강제합니다).4904Claude Code가 복구 불가능한 인터페이스 오류(<error>)로 인해 종료되었습니다. 전체 화면 렌더러가 시작되는 동안 발생했으므로 다음 실행은 클래식 렌더러를 사용할 것입니다(CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1은 언제든지 이를 강제합니다).
4564```4905```
4565 4906
4566**할 일:**4907**할 일:**
4574 에이전트 설명이 15.0k 토큰 제한을 초과함4915 에이전트 설명이 15.0k 토큰 제한을 초과함
4575</h3>4916</h3>
4576 4917
4577Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다. 기본 제공 에이전트를 제외한 [서브에이전트](/docs/ko/sub-agents)의 결합된 설명이 Claude Code가 추정하는 15,000 토큰을 초과합니다. 각 에이전트는 이름과 `description` frontmatter를 계산합니다. Claude Code는 총합이 제한을 초과하는지 여부와 관계없이 모든 에이전트를 로드하므로 경고는 로드되는 내용을 변경하지 않습니다.4918Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다. 기본 제공 에이전트를 제외한 [서브에이전트](/docs/ko/sub-agents)의 결합된 설명이 Claude Code가 추정하는 15,000 토큰을 초과합니다. 각 에이전트는 이름과 `description` frontmatter를 계산합니다. Claude Code는 합계가 제한을 초과하는지 여부와 관계없이 모든 에이전트를 로드하므로 경고는 로드되는 내용을 변경하지 않습니다.
4578 4919
4579```text theme={null}4920```text theme={null}
4580에이전트 설명이 15.0k 토큰 제한을 초과함(~16.2k 토큰) · Claude에게 .claude/agents/의 에이전트 설명을 정리하도록 요청하세요4921에이전트 설명이 15.0k 토큰 제한을 초과함(~16.2k 토큰) · Claude에게 .claude/agents/의 에이전트 설명을 정리하도록 요청하세요
4585* 에이전트 파일의 `description` frontmatter를 단축하거나 Claude에게 정리하도록 요청하세요.4926* 에이전트 파일의 `description` frontmatter를 단축하거나 Claude에게 정리하도록 요청하세요.
4586* 더 이상 사용하지 않는 에이전트 파일을 제거하세요.4927* 더 이상 사용하지 않는 에이전트 파일을 제거하세요.
4587 4928
4929<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">
4930 스킬, 명령 또는 워크플로우가 로드되지 않았습니다(이름이 예약됨)
4931</h3>
4932
4933스킬 폴더, 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)하고 해당 항목을 로드하지 않습니다.
4934
4935Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다:
4936
4937```text theme={null}
4938로드되지 않음: .claude/skills/anthropic-skills의 이름을 바꾸고 다시 시작하세요 — 해당 이름은 "anthropic-skills"를 사용하며, 이는 claude.ai 계정에서 동기화된 스킬을 위해 예약된 이름입니다
4939```
4940
4941알림은 거부된 첫 번째 항목에 대해 변경할 내용을 이름으로 지정합니다: 이름을 바꿀 폴더 또는 파일, 편집할 `name:` 줄, 또는 이름을 바꿀 워크플로우. 둘 이상의 항목이 거부되면 알림은 `· 2 more` 같은 개수로 끝나고 [디버그 로그](/docs/ko/debug-your-config)가 각각을 이름으로 지정합니다.
4942
4943**할 일:**
4944
4945* 알림이 이름으로 지정한 항목의 이름을 바꾸거나 가리키는 `name:` 줄을 편집한 후 세션을 다시 시작하세요.
4946
4947v2.1.282 이전에는 Claude Code가 이러한 이름의 스킬과 명령을 로드했습니다.
4948
4588<h3 id="workspace-has-not-been-trusted">4949<h3 id="workspace-has-not-been-trusted">
4589 작업 공간이 신뢰되지 않음4950 작업 영역이 신뢰되지 않음
4590</h3>4951</h3>
4591 4952
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` 규칙은 영향을 받지 않습니다.4953Claude 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 4954
4594```text theme={null}4955```text theme={null}
4595.claude/settings.local.json의 2개 permissions.allow 항목을 무시합니다: 이 작업 공간이 신뢰되지 않았습니다. 여기서 Claude Code를 대화형으로 한 번 실행하고 신뢰 대화를 수락하거나 /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted: true를 설정하세요.4956.claude/settings.local.json의 2개 permissions.allow 항목을 무시합니다: 이 작업 영역이 신뢰되지 않았습니다. 여기서 Claude Code를 대화형으로 한 번 실행하고 신뢰 대화를 수락하거나, /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted: true를 설정하세요.
4596```4957```
4597 4958
4598**할 일:**4959**할 일:**
4599 4960
4600* 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락하세요. [프로젝트 allow 규칙 및 작업 공간 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)에서 해당 수락이 어느 폴더를 포함하는지 설명합니다.4961* 디렉토리에서 `claude`를 실행하고 신뢰 대화를 수락하세요. [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)는 해당 수락이 어느 폴더를 포함하는지 설명합니다.
4601* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 대화가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 설정하세요.4962* [비대화형 모드](/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)를 참조하세요.4963* 메시지가 `.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 4964
4604<h3 id="working-directory-is-a-network-path">4965<h3 id="working-directory-is-a-network-path">
4605 작업 디렉토리가 네트워크 경로임4966 작업 디렉토리가 네트워크 경로임
4606</h3>4967</h3>
4607 4968
4608Claude Code는 네트워크 경로를 작업 디렉토리로 추가하지 않습니다. 네트워크 경로를 조회하면 이름이 지정된 호스트에 연결할 수 있으며, Windows에서는 해당 연결이 호스트에 자격 증명을 보낼 수 있으므로 Claude Code는 조회 없이 경로를 거부합니다. `/add-dir`을 이러한 경로로 실행할 때 또는 시작 시 경고로 이 메시지를 봅니다. 시작 시 나타나면 Claude Code는 해당 디렉토리 없이 시작합니다.4969Claude Code는 네트워크 경로를 작업 디렉토리로 추가하지 않습니다. 네트워크 경로를 조회하면 이름이 지정된 호스트에 연결할 수 있으며, Windows에서는 해당 연결이 호스트에 자격 증명을 보낼 수 있으므로 Claude Code는 조회하지 않고 경로를 거부합니다. `/add-dir`을 이러한 경로로 실행할 때 또는 시작 시 경고로 이 메시지를 봅니다. 시작 시 나타나면 Claude Code는 해당 디렉토리 없이 시작합니다.
4609 4970
4610```text theme={null}4971```text theme={null}
4611\\server\share는 네트워크 경로이므로 작업 디렉토리로 추가할 수 없습니다. Windows에서는 공유를 드라이브 문자로 매핑하고 --add-dir로 실행 시 전달하세요(세션 중간에 추가된 드라이브 문자는 아직 원격 읽기 신뢰를 수행하지 않습니다).4972\\server\share는 네트워크 경로이므로 작업 디렉토리로 추가할 수 없습니다. Windows에서는 공유를 드라이브 문자로 매핑하고 --add-dir로 실행 시 전달하세요(세션 중간에 추가된 드라이브 문자는 아직 원격 읽기 신뢰를 수행하지 않습니다).
4621 4982
4622**할 일:**4983**할 일:**
4623 4984
4624* Windows에서는 공유를 드라이브 문자로 매핑하세요(예: `net use Z: \\server\share`). 그리고 `claude --add-dir Z:\`로 실행 시 드라이브를 전달하세요.4985* Windows에서는 `net use Z: \\server\share` 같은 명령으로 공유를 드라이브 문자로 매핑하고 `claude --add-dir Z:\`로 실행 시 드라이브를 전달하세요.
4625* macOS 또는 Linux에서는 공유를 로컬 경로에 마운트하고 해당 경로를 대신 추가하세요.4986* macOS 또는 Linux에서는 공유를 로컬 경로에 마운트하고 대신 해당 경로를 추가하세요.
4626* 경로가 `permissions.additionalDirectories`에 있으면 이를 나열하는 설정 파일에서 제거하세요.4987* 경로가 `permissions.additionalDirectories`에 있으면 이를 나열하는 설정 파일에서 제거하세요.
4627 4988
4628v2.1.257 이전에는 Claude Code가 도달 가능한 네트워크 경로를 작업 디렉토리로 수락했습니다.4989v2.1.257 이전에는 Claude Code가 도달 가능한 네트워크 경로를 작업 디렉토리로 수락했습니다.
4631 원격 관리 설정을 로드하지 못함4992 원격 관리 설정을 로드하지 못함
4632</h3>4993</h3>
4633 4994
4634세션이 [서버 관리 설정](/docs/ko/server-managed-settings)에 적합하지만 Claude Code가 이를 가져올 수 없어서 대화형 세션에 이 경고를 표시합니다. 괄호로 묶인 원인은 `network error`, `request timed out`, 또는 `authentication rejected (401)` 같은 실패한 내용을 명시하고, 줄의 나머지는 세션이 실행되는 정책을 나타냅니다:4995세션이 [서버 관리 설정](/docs/ko/server-managed-settings)에 적합하지만 Claude Code가 설정을 가져올 수 없거나 서버가 반환한 내용을 적용할 수 없어서 대화형 세션에서 이 경고를 표시합니다.
4996
4997괄호로 묶인 원인은 `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 4998
4636* **이전 성공적인 가져오기에서 캐시된 설정**: Claude Code는 [제외된 환경 변수](/docs/ko/server-managed-settings#fetch-and-caching-behavior)를 제외하고 캐시된 정책에서 세션을 실행하며, 줄은 `using cached policy`를 읽습니다.4999줄의 나머지 부분은 세션이 실행되는 정책을 나타냅니다:
4637* **캐시 없음**: Claude Code는 서버 관리 설정 없이 세션을 실행하며, 줄은 `no remote policy applied`를 읽습니다.5000
5001* **이전 성공적인 가져오기에서 캐시된 설정**: Claude Code는 [보류된 환경 변수](/docs/ko/server-managed-settings#fetch-and-caching-behavior)를 제외한 해당 캐시된 정책에서 세션을 실행하며, 줄은 `using cached policy`로 읽습니다.
5002* **캐시 없음**: Claude Code는 서버 관리 설정 없이 세션을 실행하며, 줄은 `no remote policy applied`로 읽습니다.
4638 5003
4639**할 일:**5004**할 일:**
4640 5005
4641* 메시지가 명시하는 원인에 대해 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하세요. 인증 원인의 경우 `/status`로 로그인을 확인하세요.5006* 메시지가 이름으로 지정한 원인에 대해 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하세요. 인증 원인의 경우 `/status`로 로그인을 확인하세요.
5007* `no setting in the server response could be applied as written`의 경우 관리자에게 서버의 설정을 수정하도록 요청하세요.
4642* 전체 진단을 위해 `/status` 또는 `claude doctor`를 실행하세요.5008* 전체 진단을 위해 `/status` 또는 `claude doctor`를 실행하세요.
4643 5009
4644v2.1.248 이전에는 Claude Code가 실패한 설정 가져오기를 디버그 로그에만 보고했습니다.5010v2.1.248 이전에는 Claude Code가 실패한 설정 가져오기를 디버그 로그에서만 보고했습니다.
4645 5011
4646<h3 id="managed-settings-were-not-approved">5012<h3 id="managed-settings-were-not-approved">
4647 관리 설정이 승인되지 않음5013 관리 설정이 승인되지 않음
4648</h3>5014</h3>
4649 5015
4650조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 승인이 필요한 설정이 포함되어 있고 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부했으므로 Claude Code는 이를 적용하지 않고 종료됩니다:5016조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 승인이 필요한 설정이 포함되어 있고 [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)를 거부했으므로 Claude Code는 이를 적용하지 않고 종료합니다:
4651 5017
4652```text theme={null}5018```text theme={null}
4653관리 설정이 승인되지 않았습니다. 이를 적용하지 않고 종료합니다.5019관리 설정이 승인되지 않았습니다. 이를 적용하지 않고 종료합니다.
4658* Claude Code를 다시 시작하고 대화를 승인하여 조직의 설정에서 계속하세요. 거부된 대화는 기억되지 않으므로 다음 시작 시 다시 나타납니다.5024* Claude Code를 다시 시작하고 대화를 승인하여 조직의 설정에서 계속하세요. 거부된 대화는 기억되지 않으므로 다음 시작 시 다시 나타납니다.
4659* 대화가 나열하는 설정에 대해 확실하지 않으면 승인하기 전에 조직의 관리 설정을 유지하는 사람에게 문의하세요.5025* 대화가 나열하는 설정에 대해 확실하지 않으면 승인하기 전에 조직의 관리 설정을 유지하는 사람에게 문의하세요.
4660 5026
5027<h3 id="managed-settings-block-the-default-model">
5028 관리 설정이 기본 모델을 차단함
5029</h3>
5030
5031조직의 [관리 설정](/docs/ko/managed-settings)이 기본 옵션이 해석되는 모델과 이를 단계적으로 낮출 수 있는 모든 모델을 차단합니다. 기본 옵션에서 시작할 세션은 차단된 모델을 실행하는 대신 시작 시 종료됩니다. 어떤 메시지를 보는지는 이를 차단하는 설정에 따라 다릅니다. [`deniedModels`](/docs/ko/model-config#block-specific-models-or-versions) 목록이 이를 차단하면 메시지는 다음과 같이 읽습니다:
5032
5033```text theme={null}
5034Claude Code를 시작할 수 없습니다: 조직의 관리 설정이 "deniedModels"에서 기본 모델(claude-opus-5-5)을 차단하고 있으며, 허용하는 모델 중 기본값으로 사용할 수 있는 모델이 없습니다. 관리자에게 "deniedModels" 또는 "availableModels"을 업데이트하도록 요청하세요.
5035```
5036
5037`availableModels` 목록이 [`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch)를 `"exact"`로 설정하여 이를 생략하면 메시지는 다음과 같이 읽습니다:
5038
5039```text theme={null}
5040Claude Code를 시작할 수 없습니다: 조직이 "availableModels"에 나열된 모델만 허용하며, 기본 모델로 사용할 수 있는 모델이 없습니다(claude-opus-5-5가 나열되지 않음). 관리자에게 "availableModels"을 업데이트하도록 요청하세요.
5041```
5042
5043**할 일:**
5044
5045* 설정을 관리하는 경우 사용자가 실행할 수 있는 모델을 `availableModels`에 추가하거나 모든 폴백을 차단하는 `deniedModels` 항목을 좁히세요. [특정 모델 또는 버전 차단](/docs/ko/model-config#block-specific-models-or-versions)은 기본 옵션이 어떻게 단계적으로 낮춰지는지 설명합니다.
5046* 설정을 관리하지 않으면 메시지를 관리자에게 보내세요. 자신의 설정 파일은 관리 `availableModels` 또는 `deniedModels` 목록을 확대할 수 없습니다.
5047
4661<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5048<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">
4662 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨5049 MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨
4663</h3>5050</h3>
4664 5051
4665`/mcp`의 서버에서 **다시 연결**을 선택했거나 비활성화된 서버를 다시 켰는데, [MCP 서버를 제한](/docs/ko/managed-mcp)하는 설정이 해당 서버를 차단합니다. Claude Code는 이를 연결하기를 거부하고 다음을 표시합니다:5052`/mcp`의 서버에서 **다시 연결**을 선택했거나 비활성화된 서버를 다시 켰으며, [MCP 서버를 제한](/docs/ko/managed-mcp)하는 설정이 해당 서버를 차단합니다. Claude Code는 이를 연결하기를 거부하고 표시합니다:
4666 5053
4667```text theme={null}5054```text theme={null}
4668MCP 서버 <name>이(가) 엔터프라이즈 관리 정책에 의해 차단되었습니다5055MCP 서버 <name>이(가) 엔터프라이즈 관리 정책에 의해 차단되었습니다
4669```5056```
4670 5057
4671다음 설정 중 하나가 메시지를 생성할 수 있습니다:5058이러한 설정 중 하나가 메시지를 생성할 수 있습니다:
4672 5059
4673* 자신의 `~/.claude/settings.json` 또는 프로젝트의 `.claude/settings.json`에 있는 것을 포함하여 서버와 일치하는 [`deniedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 항목5060* 자신의 `~/.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) 목록5061* 서버가 일치하지 않는 [`allowedMcpServers`](/docs/ko/managed-mcp#policy-based-control-with-allowlists-and-denylists) 목록
4675* `mcp` 잠금이 있는 [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization)으로, `~/.claude.json` 및 `.mcp.json`에서 구성된 서버를 차단합니다.5062* `mcp`가 잠긴 [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization)으로, `~/.claude.json` 및 `.mcp.json`에서 구성된 서버를 차단합니다.
4676* 서버가 claude.ai 커넥터일 때 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)5063* 서버가 claude.ai 커넥터일 때 [`disableClaudeAiConnectors`](/docs/ko/mcp#disable-claude-ai-connectors)
4677 5064
4678**할 일:**5065**할 일:**
4680* 자신의 사용자 및 프로젝트 설정 파일에서 이러한 설정 중 하나를 확인하고 변경하거나 제거하세요.5067* 자신의 사용자 및 프로젝트 설정 파일에서 이러한 설정 중 하나를 확인하고 변경하거나 제거하세요.
4681* 자신의 설정이 차단을 설명하지 않으면 관리자에게 어떤 관리 설정이 서버를 차단하는지 문의하세요.5068* 자신의 설정이 차단을 설명하지 않으면 관리자에게 어떤 관리 설정이 서버를 차단하는지 문의하세요.
4682 5069
4683v2.1.257 이전에는 `/mcp`의 **다시 연결** 및 다시 활성화가 중간 세션 정책 업데이트가 차단한 서버를 연결할 수 있었습니다.5070v2.1.257 이전에는 `/mcp`의 **다시 연결** 및 다시 활성화가 세션 중간 정책 업데이트가 차단한 서버를 연결할 수 있었습니다.
4684 5071
4685<h3 id="managed-settings-document-could-not-be-parsed">5072<h3 id="managed-settings-document-could-not-be-parsed">
4686 관리 설정 문서를 구문 분석할 수 없음5073 관리 설정 문서를 구문 분석할 수 없음
4687</h3>5074</h3>
4688 5075
4689조직이 [관리 설정](/docs/ko/managed-settings)을 배포하고, 배포된 문서 중 하나가 있지만 JSON 객체로 구문 분석할 수 없어서 Claude Code는 정책을 실행하지 않고 시작 시 코드 1로 종료됩니다. 줄은 메시지 앞에 실패한 소스를 명시합니다:5076조직이 [관리 설정](/docs/ko/managed-settings)을 배포하고 배포된 문서 중 하나가 있지만 JSON 객체로 구문 분석할 수 없어서 Claude Code는 문서가 수행하는 정책 없이 실행하는 대신 시작 시 코드 1로 종료됩니다. 줄은 메시지 앞에 실패한 소스를 이름으로 지정합니다:
4690 5077
4691```text theme={null}5078```text theme={null}
4692/Library/Application Support/ClaudeCode/managed-settings.json: 관리 설정 문서를 JSON 객체로 구문 분석할 수 없습니다. 해당 설정이 적용되지 않습니다. 수정하거나 제거하세요.5079/Library/Application Support/ClaudeCode/managed-settings.json: 관리 설정 문서를 JSON 객체로 구문 분석할 수 없습니다. 해당 설정이 적용되지 않습니다. 수정하거나 제거하세요.
4698* macOS 관리 기본 설정 프로필, `per-user managed preferences` 또는 `device-level managed preferences`5085* macOS 관리 기본 설정 프로필, `per-user managed preferences` 또는 `device-level managed preferences`
4699* Windows 레지스트리 값, `Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`5086* Windows 레지스트리 값, `Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`
4700 5087
4701[Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 각 소스를 구문 분석할 수 없게 만드는 것을 나열합니다.5088[Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 각 소스를 구문 분석할 수 없게 만드는 것을 나열합니다.
4702 5089
4703Claude Code는 다른 관리 소스가 유효한 정책을 제공하더라도 시작을 거부합니다. 대화형 세션, `claude -p`, Agent SDK 세션, [백그라운드 세션](/docs/ko/agent-view), 및 `claude doctor`를 포함한 대부분의 하위 명령에서 이 오류를 봅니다. 거부는 의도적으로 폐쇄됩니다: Claude Code가 구문 분석할 수 없는 문서의 설정은 적용될 수 없으며, 계속 진행하면 조직의 제어 없이 세션이 실행됩니다.5090Claude Code는 다른 관리 소스가 유효한 정책을 제공하더라도 시작을 거부합니다. 대화형 세션, `claude -p`, Agent SDK 세션, [백그라운드 세션](/docs/ko/agent-view), 및 대부분의 하위 명령(`claude doctor` 포함)에서 이 오류를 봅니다. 거부는 의도적으로 폐쇄됩니다: Claude Code가 구문 분석할 수 없는 문서의 설정은 적용될 수 없으며, 어쨌든 시작하면 조직의 제어 없이 세션이 실행됩니다.
4704 5091
4705구문 분석 가능한 문서의 스키마 문제는 이 오류를 생성하지 않습니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)에서 Claude Code가 하나를 사용하는 것을 다룹니다.5092구문 분석 가능한 문서의 스키마 문제는 이 오류를 생성하지 않습니다. [Claude Code가 삭제한 항목 찾기](/docs/ko/managed-settings#find-entries-claude-code-dropped)는 Claude Code가 하나를 사용하는 것을 다룹니다.
4706 5093
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)에서 읽기 실패가 시작 시 종료되는 경우를 다룹니다.5094`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 5095
4709**할 일:**5096**할 일:**
4710 5097
4711* 머신을 관리하면 명시된 문서를 JSON 객체로 구문 분석하도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 계산되며 실행을 차단하지 않습니다.5098* 머신을 관리하면 명명된 문서가 JSON 객체로 구문 분석되도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈 `managed-settings.json`은 `{}`로 계산되며 실행을 차단하지 않습니다.
4712* 그렇지 않으면 관리자에게 배포된 문서를 수정하도록 요청하세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.5099* 관리하지 않으면 관리자에게 배포된 문서를 수정하도록 요청하세요. 자신의 설정 파일의 아무것도 이 오류를 야기하거나 지우지 않습니다.
4713 5100
4714<h3 id="otelheadershelper-failed">5101<h3 id="otelheadershelper-failed">
4715 otelHeadersHelper 실패5102 otelHeadersHelper 실패
4716</h3>5103</h3>
4717 5104
4718Claude Code는 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper) 스크립트가 실패하거나 [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 충족하지 않는 출력을 출력할 때 대화형 세션당 한 번 터미널 인터페이스에 알림으로 이 경고를 표시합니다.5105Claude Code는 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper) 스크립트가 실패하거나 [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 충족하지 않는 출력을 출력할 때 대화형 세션당 한 번 터미널 인터페이스에서 알림으로 이 경고를 표시합니다.
4719 5106
4720스크립트가 계속 실패하는 동안 내보내기가 실패하고 원격 분석 백엔드는 세션에서 아무것도 받지 못합니다.5107스크립트가 계속 실패하는 동안 내보내기가 실패하고 원격 분석 백엔드는 세션에서 아무것도 받지 않습니다.
4721 5108
4722`See /status:` 뒤의 텍스트는 스크립트의 종료 코드 다음에 오류 출력 같은 실패한 내용을 명시합니다:5109`See /status:` 뒤의 텍스트는 스크립트의 종료 코드 다음에 오류 출력 같은 실패한 내용을 나타냅니다:
4723 5110
4724```text theme={null}5111```text theme={null}
4725otelHeadersHelper 실패. 원격 분석이 내보내지지 않습니다. /status 참조: exited 1: token service unreachable5112otelHeadersHelper 실패. 원격 분석을 내보내지 않습니다. /status 참조: exited 1: token service unreachable
4726```5113```
4727 5114
4728**할 일:**5115**할 일:**
4729 5116
4730* `/status`를 실행하여 실패 세부 정보를 읽으세요.5117* `/status`를 실행하여 실패 세부 정보를 읽으세요.
4731* 스크립트를 수정하여 30초 이내에 종료 0으로 종료하고 stdout에 문자열 헤더 값의 JSON 객체를 출력하도록 하세요. [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 참조하세요.5118* 스크립트가 30초 이내에 0으로 종료되고 stdout에 문자열 헤더 값의 JSON 객체를 출력하도록 수정하세요. [스크립트 요구 사항](/docs/ko/monitoring-usage#script-requirements)을 참조하세요.
4732* 조직이 [관리 설정](/docs/ko/managed-settings)을 통해 스크립트를 배포하면 이를 유지하는 사람에게 수정하도록 요청하세요.5119* 조직이 [관리 설정](/docs/ko/managed-settings)을 통해 스크립트를 배포하면 이를 유지하는 사람에게 수정하도록 요청하세요.
4733 5120
4734[비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 같은 실패가 stderr에 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>` 대신 나타납니다.5121[비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 동일한 실패가 stderr에 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>` 대신 나타납니다.
4735 5122
4736<h3 id="headershelper-not-run">5123<h3 id="headershelper-not-run">
4737 headersHelper가 실행되지 않음5124 headersHelper 실행되지 않음
4738</h3>5125</h3>
4739 5126
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)에서 이 검사가 적용되는 서버를 참조하세요.5127Claude 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 5128
4742Claude Code는 [비대화형 모드](/docs/ko/headless)에서만 이 줄을 기록하며, 서버당 한 번입니다. 대화형 세션에서는 같은 거부를 디버그 로그에 기록합니다.5129Claude Code는 [비대화형 모드](/docs/ko/headless)에서만 이 줄을 서버당 한 번 기록합니다. 대화형 세션에서는 동일한 거부를 디버그 로그에 기록합니다.
4743 5130
4744```text theme={null}5131```text theme={null}
4745MCP 서버 'internal-api': headersHelper가 실행되지 않음 — 이 작업 공간에 지속된 신뢰가 없습니다. 여기서 대화형으로 신뢰 대화를 한 번 수락하거나 /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted를 설정하세요.5132MCP 서버 'internal-api': headersHelper 실행되지 않음 — 이 작업 영역에 저장된 신뢰가 없습니다. 여기서 한 번 대화형으로 신뢰 대화를 수락하거나 /Users/you/.claude.json에서 projects["/Users/you/project"].hasTrustDialogAccepted를 설정하세요.
4746```5133```
4747 5134
4748메시지가 출력하는 `projects` 키는 [프로젝트 allow 규칙 및 작업 공간 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)가 Claude Code가 신뢰를 키하는 폴더입니다. 부모 폴더에 대한 신뢰 대화를 수락하는 것은 검사를 만족하지 않으며, `-p` 또는 SDK 세션도 만족하지 않습니다.5135메시지가 출력하는 `projects` 키는 [프로젝트 allow 규칙 및 작업 영역 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)가 Claude Code가 신뢰를 키하는 폴더입니다. 부모 폴더에 대한 신뢰 대화를 수락하는 것은 검사를 만족하지 않으며, `-p` 또는 SDK 세션도 만족하지 않습니다.
4749 5136
4750**할 일:**5137**할 일:**
4751 5138
4752* 메시지가 명시하는 폴더에서 `claude`를 실행하고 신뢰 대화를 수락한 다음 `-p` 또는 SDK 명령을 다시 실행하세요.5139* 메시지가 이름으로 지정한 폴더에서 `claude`를 실행하고 신뢰 대화를 수락한 후 `-p` 또는 SDK 명령을 다시 실행하세요.
4753* 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 직접 설정하세요.5140* `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 직접 설정하고 메시지가 출력하는 정확한 `projects` 키를 사용하세요.
4754* 홈 디렉토리에서 세션을 시작했으면 신뢰한 프로젝트 디렉토리에서 작업하세요. 홈 디렉토리에서 신뢰 대화를 수락하면 Claude Code는 현재 세션에만 해당 신뢰를 유지합니다.5141* 홈 디렉토리에서 세션을 시작했으면 신뢰한 프로젝트 디렉토리에서 작업하세요. 홈 디렉토리에서 신뢰 대화를 수락하면 Claude Code는 현재 세션에만 해당 신뢰를 유지합니다.
4755 5142
4756<h3 id="malformed-tool-content-rule">5143<h3 id="malformed-tool-content-rule">
4757 잘못된 Tool(content) 규칙5144 잘못된 형식의 Tool(content) 규칙
4758</h3>5145</h3>
4759 5146
4760설정 파일의 [권한 규칙](/docs/ko/permissions#permission-rule-syntax)이 `Tool` 또는 `Tool(content)` 형태를 갖지 않습니다. 예를 들어 닫는 괄호 뒤에 텍스트가 있거나 괄호 중 하나가 누락되었습니다. Claude Code는 규칙을 건너뛰고 대화형 세션이 시작될 때 유효하지 않은 설정 대화에 나열하며, [`claude doctor`](/docs/ko/debug-your-config#check-resolved-settings) 출력에도 나열합니다:5147[권한 규칙](/docs/ko/permissions#permission-rule-syntax)이 설정 파일 중 하나에 `Tool` 또는 `Tool(content)` 형태가 아닙니다. 예를 들어 닫는 괄호 뒤에 텍스트가 있거나 괄호 중 하나가 누락되었습니다. Claude Code는 규칙을 건너뛰고 대화형 세션이 시작될 때 유효하지 않은 설정 대화에 나열하며, [`claude doctor`](/docs/ko/debug-your-config#check-resolved-settings) 출력에서:
4761 5148
4762```text theme={null}5149```text theme={null}
4763유효하지 않은 권한 규칙 "Bash(ls) x"가 건너뛰어졌습니다: 잘못된 Tool(content) 규칙. 규칙은 Tool 또는 Tool(content) 형태를 가지며 닫는 ")"에서 끝나야 합니다. 내용 내의 괄호는 리터럴입니다.5150유효하지 않은 권한 규칙 "Bash(ls) x"를 건너뛰었습니다: 잘못된 형식의 Tool(content) 규칙. 규칙은 Tool 또는 Tool(content) 형태이며 닫는 ")"에서 끝나야 합니다. 내용 내의 괄호는 리터럴입니다.
4764```5151```
4765 5152
4766**할 일:**5153**할 일:**
4767 5154
4768* 메시지와 함께 나열된 설정 파일에서 규칙을 다시 작성하여 닫는 괄호에서 끝나도록 하세요. 예를 들어 `Bash(ls) x` 대신 `Bash(ls *)`5155* 메시지와 함께 나열된 설정 파일에서 규칙을 다시 작성하여 닫는 괄호에서 끝나도록 하세요. 예를 들어 `Bash(ls) x` 대신 `Bash(ls *)`
4769* 내용 내의 괄호는 그대로 두세요. 이들은 리터럴이므로 `Edit(./Finance (2024)/*)`와 같은 규칙은 이스케이프 없이 유효합니다.5156* 내용 내의 괄호는 그대로 두세요. 이들은 리터럴이므로 `Edit(./Finance (2024)/**)` 같은 규칙은 이스케이프 없이 유효합니다.
4770 5157
4771v2.1.260 이전에는 Claude Code가 일치하지 않는 괄호가 있는 규칙을 `Mismatched parentheses`로 보고했습니다.5158v2.1.260 이전에는 Claude Code가 일치하지 않는 괄호가 있는 규칙을 `Mismatched parentheses`로 보고했습니다.
4772 5159
4774 파일 권한 검사와 일치하지 않음5161 파일 권한 검사와 일치하지 않음
4775</h3>5162</h3>
4776 5163
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` 규칙에 대해서만 검사하므로 다른 파일 도구 중 하나를 명시하는 경로 규칙을 절대 참조하지 않습니다. 규칙을 유지하고 다른 것은 변경하지 않습니다. 경고는 규칙, 괄호의 소스, 그리고 작성할 대체를 명시합니다:5164Claude 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 5165
4779```text theme={null}5166```text theme={null}
4780권한 deny 규칙(.claude/settings.json): Write(docs/**)는 파일 권한 검사와 일치하지 않습니다 — Edit(path) 규칙만 사용됩니다. 대신 Edit(docs/**)를 사용하세요(Edit 규칙은 모든 파일 편집 도구를 포함합니다).5167권한 deny 규칙(.claude/settings.json): Write(docs/**)는 파일 권한 검사와 일치하지 않습니다 — Edit(path) 규칙만 있습니다. 대신 Edit(docs/**)를 사용하세요(Edit 규칙은 모든 파일 편집 도구를 포함합니다).
4781```5168```
4782 5169
4783**할 일:**5170**할 일:**
4784 5171
4785* `Write(path)`, `NotebookEdit(path)`, 및 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구를 포함합니다.5172* `Write(path)`, `NotebookEdit(path)`, 및 레거시 `MultiEdit(path)` 규칙을 `Edit(path)`로 바꾸세요. `Edit` 규칙은 모든 파일 편집 도구를 포함합니다.
4786* `--allowedTools`를 제외하고, Claude Code가 경고 없이 `Glob` 규칙을 수락하며, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.5173* `--allowedTools`를 제외하고, Claude Code가 경고 없이 `Glob` 규칙을 수락하며, `Glob(path)` 규칙을 `Read(path)`로 바꾸세요.
4787* 경고가 괄호에 명시하는 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는 `--allowed-tools` 및 `--disallowed-tools`의 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5174* 경고가 괄호에 이름으로 지정한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 및 `--disallowed-tools`의 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.
4788* `Write` 또는 `Glob` 같은 베어 도구 이름 규칙은 그대로 두세요. Claude Code는 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치시키고 이들에 대해 경고하지 않습니다.5175* `Write` 또는 `Glob` 같은 베어 도구 이름 규칙은 그대로 두세요. Claude Code는 [도구 수준](/docs/ko/permissions#match-all-uses-of-a-tool)에서 일치하며 이에 대해 경고하지 않습니다.
4789* 소스가 `managed policy settings`를 읽으면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.5176* 소스가 `managed policy settings`로 읽히면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.
4790 5177
4791[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 stderr 대신 디버그 로그에 기록하므로 머신 읽기 출력이 깨끗합니다. `~/.claude/debug/<session-id>.txt`에서 캡처하려면 `--debug`로 실행하세요. v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5178[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록하므로 머신 읽기 출력이 깨끗합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요. v2.1.210 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.
4792 5179
4793<h3 id="has-a-wildcard-before-the-rest-of-the-command">5180<h3 id="has-a-wildcard-before-the-rest-of-the-command">
4794 명령의 나머지 부분 앞에 와일드카드가 있음5181 명령의 나머지 부분 앞에 와일드카드가 있음
4795</h3>5182</h3>
4796 5183
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)은 일치 규칙을 보여줍니다.5184Claude 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 5185
4799경고는 의도한 것보다 와일드카드가 더 넓은 규칙을 좁힐 수 있도록 존재합니다. Claude Code는 규칙을 유지하고 일치 방식을 변경하지 않습니다. 경고는 규칙과 괄호의 소스를 명시합니다:5186경고는 의도한 것보다 와일드카드가 더 넓은 규칙을 좁힐 수 있도록 존재합니다. Claude Code는 규칙을 유지하고 일치 방식에 대해 아무것도 변경하지 않습니다. 경고는 규칙과 괄호의 소스를 이름으로 지정합니다:
4800 5187
4801```text theme={null}5188```text theme={null}
4802권한 allow 규칙(.claude/settings.json): Bash(git -C * status *)는 명령의 나머지 부분 앞에 와일드카드가 있으므로 해당 위치에 삽입된 모든 옵션과도 일치하고 프롬프트 없이 승인합니다. git의 경우 -c 및 --exec-path 같은 옵션은 임의의 명령을 실행할 수 있습니다. 해당 *를 의도한 정확한 값으로 바꾸거나 *를 하위 명령 뒤에만 사용하세요(예: Bash(git status *)).5189권한 allow 규칙(.claude/settings.json): Bash(git -C * status *)는 명령의 나머지 부분 앞에 와일드카드가 있으므로 해당 위치에 삽입된 모든 옵션과도 일치하며 프롬프트 없이 이를 승인합니다. git의 경우 -c 및 --exec-path 같은 옵션은 임의의 명령을 실행할 수 있습니다. 해당 *를 의도한 정확한 값으로 바꾸거나 부분 명령 뒤에만 *를 사용하세요(예: Bash(git status *)).
4803```5190```
4804 5191
4805**할 일:**5192**할 일:**
4806 5193
4807* 하위 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.5194* 부분 명령 앞의 `*`를 의도한 정확한 값으로 바꾸세요: `Bash(git * main)` 대신 `Bash(git checkout main)`.
4808* 모든 `*`를 하위 명령 뒤로 이동하세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 하위 명령당 하나의 규칙을 작성하세요.5195* 모든 `*`를 부분 명령 뒤로 이동하세요: `Bash(git -C * status *)` 대신 `Bash(git status *)`. 허용하려는 부분 명령당 하나의 규칙을 작성하세요.
4809* 경고가 괄호에 명시하는 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는 `--allowed-tools` 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.5196* 경고가 괄호에 이름으로 지정한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는 `--allowed-tools` 플래그 자체. 디스크에 존재하지 않는 `claude-settings-<hash>.json` 경로는 인라인 `--settings` 값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요.
4810* 소스가 `managed policy settings`를 읽으면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.5197* 소스가 `managed policy settings`로 읽히면 경고를 관리 설정을 유지하는 사람에게 전달하세요. 자신이 직접 지울 수 없기 때문입니다.
4811 5198
4812Claude Code는 같은 형태의 deny 및 ask 규칙에 대해 경고하지 않습니다: 승인하는 대신 일치하는 추가 명령을 거부하거나 프롬프트합니다. 또한 `Bash(git commit *)`처럼 하위 명령이 첫 `*` 앞에 오는 규칙이나 `Bash(git *)`처럼 `*` 뒤에 옵션 이외의 단어가 없는 규칙, 또는 `Bash(git:*)`처럼 `:*` 접두사 규칙에 대해서도 경고하지 않습니다.5199Claude Code는 동일한 형태의 deny 및 ask 규칙에 대해 경고하지 않습니다: 이를 승인하는 대신 일치하는 추가 명령을 거부하거나 프롬프트합니다. 또한 부분 명령이 첫 번째 `*` 앞에 오는 규칙(예: `Bash(git commit *)`)이나 `*` 뒤에 옵션 이외의 단어가 없는 규칙(예: `Bash(git *)`)이나 `:*` 접두사 규칙(예: `Bash(git:*)`)에 대해서도 경고하지 않습니다.
4813 5200
4814[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 stderr 대신 디버그 로그에 기록하므로 머신 읽기 출력이 깨끗합니다. `~/.claude/debug/<session-id>.txt`에서 캡처하려면 `--debug`로 실행하세요. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.5201[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록하므로 머신 읽기 출력이 깨끗합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.
4815 5202
4816<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5203<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">
4817 crossSessionInbound는 accept, hold, refuse 중 하나여야 함5204 crossSessionInbound는 accept, hold, refuse 중 하나여야 함
4818</h3>5205</h3>
4819 5206
4820설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 Claude Code가 인식하지 못하는 값(예: 오타 `"reject"`)으로 설정합니다. 경고의 두 번째 문장은 어느 파일이 값을 보유하는지에 따라 다릅니다. 사용자, 프로젝트, 로컬, 또는 `--settings` 파일에서는 다음을 읽습니다:5207설정 파일이 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 Claude Code가 인식하지 못하는 값(예: 오타 `"reject"`)으로 설정합니다. 경고의 두 번째 문장은 어떤 파일이 값을 보유하는지에 따라 다릅니다. 사용자, 프로젝트, 로컬 또는 `--settings` 파일에서 읽습니다:
4821 5208
4822```text theme={null}5209```text theme={null}
4823"crossSessionInbound"는 "accept", "hold", "refuse" 중 하나여야 합니다. "reject"를 받았습니다. 이 값은 무시되었습니다. 존재하는 동안 교차 세션 메시지는 전달되는 대신 승인을 위해 보류됩니다. 위의 값 중 하나로 설정하세요.5210"crossSessionInbound"는 "accept", "hold", "refuse" 중 하나여야 합니다. "reject"를 받았습니다. 이 값은 무시되었습니다. 존재하는 동안 교차 세션 메시지는 전달되는 대신 승인을 위해 보류됩니다. 위의 값 중 하나로 설정하세요.
4824```5211```
4825 5212
4826[관리 설정](/docs/ko/managed-settings)에서 Claude Code는 인식되지 않는 값을 가장 제한적인 값인 `refuse`로 취급하고 경고는 관리자가 수정할 때까지 교차 세션 메시지가 거부된다고 말합니다. hold가 다른 설정 파일의 값과 결합되는 방식은 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 참조하세요.5213[관리 설정](/docs/ko/managed-settings)에서 Claude Code는 인식되지 않는 값을 가장 제한적인 값인 `refuse`로 취급하며 경고는 관리자가 수정할 때까지 교차 세션 메시지가 거부된다고 말합니다. hold가 다른 설정 파일의 값과 결합되는 방식은 [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound)를 참조하세요.
4827 5214
4828**할 일:**5215**할 일:**
4829 5216
4830* 키를 `"accept"`, `"hold"`, 또는 `"refuse"`로 설정하거나 제거하세요.5217* 키를 `"accept"`, `"hold"`, 또는 `"refuse"`로 설정하거나 제거하세요.
4831* 경고가 관리 설정을 명시하면 관리자에게 값을 수정하도록 요청하세요.5218* 경고가 관리 설정을 이름으로 지정하면 관리자에게 값을 수정하도록 요청하세요.
4832 5219
4833v2.1.248 이전에는 Claude Code가 인식되지 않는 값을 경고 없이 무시했습니다.5220v2.1.248 이전에는 Claude Code가 인식되지 않는 값을 경고 없이 무시했습니다.
4834 5221
4836 200K 제한이 적용되지 않음5223 200K 제한이 적용되지 않음
4837</h3>5224</h3>
4838 5225
4839[`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정했으며, 이는 일반적으로 [자동 압축](/docs/ko/model-config#default-auto-compact-thresholds)이 1M 컨텍스트 모델의 세션을 200K 윈도우에 유지하게 하지만, 이 세션을 200K 이하로 제한하는 압축 임계값이 없어서 대화가 이를 초과할 수 있습니다.5226[`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/ko/env-vars)을 설정했습니다. 이는 일반적으로 [자동 압축](/docs/ko/model-config#default-auto-compact-thresholds)이 1M 컨텍스트 모델의 세션을 200K 윈도우에 유지하게 하지만, 이 세션을 200K 이하로 제한하는 압축 임계값이 없으므로 대화가 이를 초과하여 증가할 수 있습니다.
4840 5227
4841```text theme={null}5228```text theme={null}
4842CLAUDE_CODE_DISABLE_1M_CONTEXT가 설정되었지만 <model>에 대해 200K 제한이 적용되지 않으므로 이 세션은 이를 초과할 수 있습니다. 이를 적용하려면 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000(또는 autoCompactWindow 설정)을 설정하세요.5229CLAUDE_CODE_DISABLE_1M_CONTEXT가 설정되었지만 <model>에 대해 200K 제한이 적용되지 않으므로 이 세션은 이를 초과하여 증가할 수 있습니다. 이를 적용하려면 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000(또는 autoCompactWindow 설정)을 설정하세요.
4843```5230```
4844 5231
4845Claude Code는 네이티브 1M 윈도우를 가진 것으로 인식하는 모든 모델과 인식하지 못하는 모델 ID에 대해 가정하는 윈도우에서 압축하는 200K 제한을 자체적으로 적용합니다. 경고는 다른 구성이 해당 적용을 무효화할 때 나타납니다:5232Claude Code는 기본 1M 윈도우가 있는 것으로 인식하는 모든 모델과 인식하지 못하는 모델 ID에 대해 가정하는 윈도우에서 압축하는 200K 제한을 자체적으로 적용합니다. 경고는 다른 구성이 해당 적용을 무효화할 때 나타납니다:
4846 5233
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 버전으로 업데이트`를 해결책으로 제공합니다.5234* 모델 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에서 세션을 압축하지 않습니다.5235* `context-1m` 베타는 [`ANTHROPIC_BETAS`](/docs/ko/env-vars) 또는 [`--betas`](/docs/ko/cli-reference#cli-flags) 플래그를 통해 요청되며 여전히 해당 베타를 수락하는 모델에서 API에 1M 윈도우를 요청하는 동안 아무것도 200K에서 세션을 압축하지 않습니다.
4849 5236
4850**할 일:**5237**할 일:**
4851 5238
4852* [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하거나 [`autoCompactWindow`](/docs/ko/settings-reference#autocompactwindow) 설정을 `200000`으로 설정하여 자동 압축이 200K 경계에서 압축하도록 하세요.5239* [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/ko/env-vars)을 설정하거나 [`autoCompactWindow`](/docs/ko/settings-reference#autocompactwindow) 설정을 `200000`으로 설정하여 자동 압축이 200K 경계에서 압축하도록 하세요.
4853* 메시지가 이 버전이 인식하지 못하는 모델 ID를 명시하면 `claude update`를 실행하세요. ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.5240* 메시지가 이 버전이 인식하지 못하는 모델 ID를 이름으로 지정하면 `claude update`를 실행하세요. ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다.
4854* 세션이 모델의 전체 윈도우를 대신 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 경고는 200K 제한이 적용되지 않는다는 것만 보고합니다.5241* 세션이 모델의 전체 윈도우를 대신 사용하기를 원하면 `CLAUDE_CODE_DISABLE_1M_CONTEXT`를 설정 해제하세요. 경고는 200K 제한이 적용되지 않음을 보고합니다.
4855 5242
4856[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다.5243[백그라운드 세션](/docs/ko/agent-view) 또는 `--output-format json` 또는 `stream-json`에서 Claude Code는 경고를 디버그 로그에 stderr 대신 기록합니다.
4857 5244
4858<h3 id="unrecognized-model-id-on-a-request">5245<h3 id="unrecognized-model-id-on-a-request">
4859 요청에서 인식되지 않은 모델 ID5246 요청에서 인식되지 않은 모델 ID
4860</h3>5247</h3>
4861 5248
4862Claude Code는 Claude Code 버전이 인식하지 못하는 모델 ID에 대한 요청을 보냈고, 해당 ID를 인식하는 모델로 매핑하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 찾지 못했습니다. Claude Code는 여전히 구성한 대로 ID를 사용하여 요청을 보내며, 종료하거나 모델을 전환하지 않습니다.5249Claude Code는 Claude Code 버전이 인식하지 못하는 모델 ID에 대한 요청을 보냈으며, 해당 ID를 인식하는 모델에 매핑하는 [`modelOverrides`](/docs/ko/model-config#override-model-ids-per-version) 항목을 찾지 못했습니다. Claude Code는 여전히 구성한 대로 ID를 사용하여 요청을 보내며 종료하거나 모델을 전환하지 않습니다.
4863 5250
4864```text theme={null}5251```text theme={null}
4865[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}5252[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}
4866```5253```
4867 5254
4868stderr를 읽는 스크립트 또는 하네스에서 `[claude-code:unrecognized_model]` 접두사와 일치하세요. 접두사와 한 공백 뒤에 Claude Code는 한 줄 JSON 객체를 기록합니다. Claude Code는 나중 버전에서 필드를 추가할 수 있으므로 예상하지 못한 필드는 무시하세요. 최소한 다음 두 가지를 기록합니다:5255stderr를 읽는 스크립트 또는 하네스에서 `[claude-code:unrecognized_model]` 접두사와 일치합니다. 접두사와 한 칸 뒤에 Claude Code는 한 줄 JSON 객체를 기록합니다. Claude Code는 나중 버전에서 필드를 추가할 수 있으므로 예상하지 못한 필드는 무시하세요. 최소한 이 두 가지를 기록합니다:
4869 5256
4870* `model`: 구성한 대로 모델 문자열5257* `model`: 구성한 대로 모델 문자열
4871* `query_source`: 모델을 사용한 요청 경로. Claude Code는 `-p` 실행에 대해 `sdk`를 보고하고 서브에이전트에 대해 `agent:`로 시작하는 값을 보고합니다.5258* `query_source`: 모델을 사용한 요청 경로. Claude Code는 `-p` 실행에 대해 `sdk`를 보고하고 `agent:`로 시작하는 값을 서브에이전트에 대해 보고합니다.
4872 5259
4873Claude Code는 실행 방식에 따라 두 곳 중 하나에 줄을 기록합니다:5260Claude Code는 실행 방식에 따라 두 곳 중 하나에 줄을 기록합니다:
4874 5261
4875* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 Claude Code는 모든 `--output-format` 아래 stderr에 기록하므로 줄을 필터링하지 않고 stdout을 구문 분석할 수 있습니다.5262* [비대화형 모드](/docs/ko/headless)에서 `-p`를 사용하면 Claude Code는 모든 `--output-format` 아래 stderr에 기록하므로 줄을 필터링하지 않고 stdout을 구문 분석할 수 있습니다.
4876* 대화형 세션 또는 [백그라운드 세션](/docs/ko/agent-view)에서 Claude Code는 디버그 로그에 기록합니다. `~/.claude/debug/<session-id>.txt`에서 캡처하려면 `--debug`로 실행하세요.5263* 대화형 세션 또는 [백그라운드 세션](/docs/ko/agent-view)에서 Claude Code는 디버그 로그에 기록합니다. `--debug`로 실행하여 `~/.claude/debug/<session-id>.txt`에서 캡처하세요.
4877 5264
4878Claude Code는 프로세스당 모델 문자열당 한 번 줄을 기록합니다. [서브에이전트](/docs/ko/sub-agents#choose-a-model) 또는 [백그라운드 기능](/docs/ko/costs#background-token-usage)이 사용하는 것처럼 각 추가 인식되지 않은 ID에 대해 별도의 줄을 기록합니다.5265Claude Code는 프로세스당 모델 문자열당 한 번 줄을 기록합니다. [서브에이전트](/docs/ko/sub-agents#choose-a-model) 또는 [백그라운드 기능](/docs/ko/costs#background-token-usage)이 사용하는 것 같은 추가 인식되지 않은 ID에 대해 별도의 줄을 기록합니다.
4879 5266
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에 대해 줄을 기록하지 않습니다.5267Claude 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 5268
4882**할 일:**5269**할 일:**
4883 5270
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`에 대해 이 항목을 추가하세요:5271* 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 5272
4886 ```json theme={null}5273 ```json theme={null}
4887 {5274 {
4893 5280
4894 Claude Code는 `my-proxy-model`을 `claude-opus-4-6`으로 취급하고 줄 기록을 중지합니다.5281 Claude Code는 `my-proxy-model`을 `claude-opus-4-6`으로 취급하고 줄 기록을 중지합니다.
4895 5282
4896* ID가 Claude Code 버전보다 새로운 모델을 명시하면 `claude update`를 실행하세요.5283* ID가 Claude Code 버전보다 최신 모델을 이름으로 지정하면 `claude update`를 실행하세요.
4897 5284
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)을 설정하는 곳에서 대신 수정하세요.5285* 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 5286
4900v2.1.233 이전에는 Claude Code가 인식하지 못하는 모델 ID에 대한 요청을 보낼 때 줄을 기록하지 않았습니다.5287v2.1.233 이전에는 Claude Code가 인식하지 못하는 모델 ID에 대한 요청을 보낼 때 줄을 기록하지 않았습니다.
4901 5288
4903 종료된 세션이 남긴 오래된 샌드박스 마스크 파일5290 종료된 세션이 남긴 오래된 샌드박스 마스크 파일
4904</h3>5291</h3>
4905 5292
4906`claude doctor`는 진단에서 이 경고를 출력하고 `/status`는 같은 줄을 나열합니다. [샌드박싱](/docs/ko/sandboxing)이 파일 시스템 격리를 켜서 활성화되면 Linux 및 WSL2에 나타납니다.5293`claude doctor`는 진단에서 이 경고를 출력하며 `/status`는 동일한 줄을 나열합니다. [샌드박싱](/docs/ko/sandboxing)이 파일 시스템 격리를 켜서 활성화되면 Linux 및 WSL2에 나타납니다.
4907 5294
4908샌드박스된 명령이 실행되는 동안 샌드박스는 아직 존재하지 않는 파일에 대한 쓰기 거부를 0바이트 읽기 전용 자리 표시자를 만들어 유지하고 나중에 제거합니다. SIGKILL 같은 것으로 정리 실행 전에 종료된 세션은 자리 표시자를 남깁니다. 이후 세션은 모든 시작에서 읽기 전용으로 다시 바인드하므로 "Yes, and don't ask again" 저장 같은 설정 쓰기가 하나가 있는 곳에서 실패합니다.5295샌드박스된 명령이 실행되는 동안 샌드박스는 아직 존재하지 않는 파일에 대한 쓰기 거부를 0바이트 읽기 전용 자리 표시자를 만들어 유지하고 나중에 제거합니다. SIGKILL로 종료된 세션 같은 정리 전에 세션이 종료되면 자리 표시자가 남습니다. 이후 세션은 모든 시작에서 읽기 전용으로 다시 바인드하므로 "Yes, and don't ask again" 저장 같은 설정 쓰기가 하나가 있는 곳에서 실패합니다.
4909 5296
4910```text theme={null}5297```text theme={null}
4911- 종료된 세션이 남긴 오래된 샌드박스 마스크 파일: /home/you/project/.claude/settings.local.json5298- 종료된 세션이 남긴 오래된 샌드박스 마스크 파일: /home/you/project/.claude/settings.local.json
4912 수정: 해당 프로젝트에서 다른 Claude Code 세션이 실행되지 않는 동안 각각을 `rm <path>`로 제거하세요 — 설정 파일이 속한 곳의 0바이트 읽기 전용 파일은 "Yes, and don't ask again" 저장을 실패하게 하고 샌드박스는 모든 시작에서 읽기 전용으로 다시 바인드합니다.5299 수정: 다른 Claude Code 세션이 해당 프로젝트에서 실행되지 않는 동안 각각을 `rm <path>`로 제거하세요 — 설정 파일이 속한 곳의 0바이트 읽기 전용 파일은 "Yes, and don't ask again" 저장을 실패하게 하며 샌드박스는 모든 시작에서 읽기 전용으로 다시 바인드합니다.
4913```5300```
4914 5301
4915**할 일:**5302**할 일:**
4916 5303
4917* 해당 프로젝트에서 실행 중인 다른 Claude Code 세션을 종료한 다음 `rm`으로 각 나열된 파일을 삭제하세요. 경고는 최대 3개 파일을 명시하고 나머지를 계산하므로 경고가 더 이상 나타나지 않을 때까지 삭제 후 `claude doctor`를 다시 실행하세요. 다른 세션의 샌드박스가 여전히 사용 중인 자리 표시자는 해당 세션의 쓰기 보호의 라이브 부분입니다.5304* 해당 프로젝트에서 실행 중인 다른 Claude Code 세션을 종료한 후 `rm`으로 각 나열된 파일을 삭제하세요. 경고는 최대 3개 파일을 이름으로 지정하고 나머지를 계산하므로 경고가 더 이상 나타나지 않을 때까지 삭제 후 `claude doctor`를 다시 실행하세요. 다른 세션의 샌드박스가 여전히 사용 중인 자리 표시자는 해당 세션의 쓰기 보호의 라이브 부분입니다.
4918* "Yes, and don't ask again"으로 저장한 권한 선택이 고정되지 않았으면 자리 표시자를 삭제한 후 다시 저장하세요.5305* "Yes, and don't ask again"으로 저장한 권한 선택이 고착되지 않으면 자리 표시자를 삭제한 후 다시 저장하세요.
4919 5306
4920v2.1.257 이전에는 `claude doctor`가 이러한 파일을 플래그하지 않았습니다. 이전 버전은 세션이 종료될 때 같은 자리 표시자를 남깁니다.5307v2.1.257 이전에는 `claude doctor`가 이러한 파일을 플래그하지 않았습니다. 이전 버전은 세션이 종료될 때 동일한 자리 표시자를 남깁니다.
4921 5308
4922<h2 id="responses-seem-lower-quality-than-usual">5309<h2 id="responses-seem-lower-quality-than-usual">
4923 응답 품질이 평소보다 낮아 보입니다5310 응답 품질이 평소보다 낮아 보입니다
4927 5314
4928* 구성된 [`--fallback-model`](/docs/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 제어를 인수받으며, 트랜스크립트에 공지가 표시됩니다5315* 구성된 [`--fallback-model`](/docs/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 제어를 인수받으며, 트랜스크립트에 공지가 표시됩니다
4929* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다5316* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다
4930* [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 Fable 5.1, Fable 5, Opus 5.5, Opus 5에서 세션을 플래그된 카테고리의 폴백 모델로 이동하며, 해당 카테고리에 폴백 모델이 있을 때 트랜스크립트에 공지를 표시합니다5317* [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)은 Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5, Opus 5에서 세션을 플래그된 카테고리의 폴백 모델로 이동하며, 해당 카테고리에 폴백 모델이 있을 때 트랜스크립트에 공지를 표시합니다
4931 5318
4932아래의 모델 선택 확인은 두 번째와 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아니라 트랜스크립트 공지로 나타납니다. [모델 구성](/docs/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.5319아래의 모델 선택 확인은 두 번째와 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아니라 트랜스크립트 공지로 나타납니다. [모델 구성](/docs/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.
4933 5320
