Documentation 2026-10-06 23:59 UTC to 2026-10-07 07:00 UTC

717| `accountInfo()` | 계정 정보를 반환합니다 |717| `accountInfo()` | 계정 정보를 반환합니다 |

718| `reconnectMcpServer(serverName)` | 이름으로 MCP 서버를 다시 연결합니다. 이름이 `.mcp.json` 또는 `~/.claude.json`과 같은 설정 파일의 항목과도 일치하는 경우, Claude Code는 설정 파일 항목이 아니라 [`mcpServers`](#options) 또는 `setMcpServers()`를 통해 구성한 서버를 다시 연결합니다. 이 확인 순서는 Claude Code v2.1.257 이상이 필요합니다 |718| `reconnectMcpServer(serverName)` | 이름으로 MCP 서버를 다시 연결합니다. 이름이 `.mcp.json` 또는 `~/.claude.json`과 같은 설정 파일의 항목과도 일치하는 경우, Claude Code는 설정 파일 항목이 아니라 [`mcpServers`](#options) 또는 `setMcpServers()`를 통해 구성한 서버를 다시 연결합니다. 이 확인 순서는 Claude Code v2.1.257 이상이 필요합니다 |

719| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 확인 방식으로, 이름으로 MCP 서버를 활성화하거나 비활성화합니다. 서버를 비활성화하면 연결이 끊기고 해당 도구가 제거됩니다. 서버 종류별로 필요한 Claude Code 버전은 [`toggleMcpServer()`](#togglemcpserver)를 참조하세요 |719| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 확인 방식으로, 이름으로 MCP 서버를 활성화하거나 비활성화합니다. 서버를 비활성화하면 연결이 끊기고 해당 도구가 제거됩니다. 서버 종류별로 필요한 Claude Code 버전은 [`toggleMcpServer()`](#togglemcpserver)를 참조하세요 |

720| `setMcpServers(servers)` | 이 세션의 MCP 서버 집합을 동적으로 교체합니다. 추가 및 제거된 서버와 오류를 알려 주는 [`McpSetServersResult`](#mcpsetserversresult)로 resolve됩니다 |720| `setMcpServers(servers)` | 이 메서드가 관리하는 MCP 서버, 즉 이 메서드로 추가한 서버와 [인프로세스 SDK 서버](#createsdkmcpserver)를 교체합니다. 추가 및 제거된 서버와 오류를 명시하는 [`McpSetServersResult`](#mcpsetserversresult)로 resolve됩니다. 연결 상태가 유지되는 다른 서버는 해당 섹션에서 설명합니다 |

721| `readMcpResource(serverName, uri)` | *Alpha.* 애플리케이션이 도구의 위젯을 렌더링할 수 있도록 연결된 MCP 서버에서 MCP Apps `ui://` 리소스 하나를 읽습니다. [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse)로 resolve됩니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다 |721| `readMcpResource(serverName, uri)` | *Alpha.* 애플리케이션이 도구의 위젯을 렌더링할 수 있도록 연결된 MCP 서버에서 MCP Apps `ui://` 리소스 하나를 읽습니다. [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse)로 resolve됩니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다 |

722| `streamInput(stream)` | 멀티턴 대화를 위해 입력 메시지를 쿼리로 스트리밍합니다 |722| `streamInput(stream)` | 멀티턴 대화를 위해 입력 메시지를 쿼리로 스트리밍합니다 |

723| `stopTask(taskId)` | ID로 실행 중인 백그라운드 작업을 중지합니다 |723| `stopTask(taskId)` | ID로 실행 중인 백그라운드 작업을 중지합니다 |

1337| `mcpServer` | `{ name: string; source: string }` | `mcp__*` 도구의 경우, 해당 도구를 제공하는 MCP 서버와 그 서버 정의의 출처로, [`McpServerProvenance`](#mcpserverprovenance)의 필드를 가집니다. 다른 도구에서는 없습니다. Agent SDK v0.3.274 이상이 필요합니다 |1337| `mcpServer` | `{ name: string; source: string }` | `mcp__*` 도구의 경우, 해당 도구를 제공하는 MCP 서버와 그 서버 정의의 출처로, [`McpServerProvenance`](#mcpserverprovenance)의 필드를 가집니다. 다른 도구에서는 없습니다. Agent SDK v0.3.274 이상이 필요합니다 |

1338| `decisionReason` | `string` | 이 권한 요청이 트리거된 이유를 설명 |1338| `decisionReason` | `string` | 이 권한 요청이 트리거된 이유를 설명 |

1339| `defaultToNo` | `boolean` | `true`이면 실수로 누른 키 하나로 이 요청이 승인되어서는 안 됩니다. 프롬프트를 거부 옵션에 포커스된 상태로 열고, 승인을 미리 선택하지 말며, 한 번의 키 입력으로 승인하는 단축키를 제공하지 마세요. Agent SDK v0.3.268 이상이 필요합니다 |1339| `defaultToNo` | `boolean` | `true`이면 실수로 누른 키 하나로 이 요청이 승인되어서는 안 됩니다. 프롬프트를 거부 옵션에 포커스된 상태로 열고, 승인을 미리 선택하지 말며, 한 번의 키 입력으로 승인하는 단축키를 제공하지 마세요. Agent SDK v0.3.268 이상이 필요합니다 |

1340| `suppressAlwaysAllowRule` | `boolean` | `true`이면 이 요청에 대해 영구적인 항상 허용 선택지를 제공하지 마세요. 해당 선택지가 기록할 규칙이 요청 자체의 작업보다 더 많은 권한을 부여하기 때문입니다. Agent SDK v0.3.268 이상이 필요합니다 |1340| `suppressAlwaysAllowRule` | `boolean` | `true`이면 이 요청에 대해 영구적인 항상 허용 선택지를 제공하지 마세요. Agent SDK v0.3.268 이상이 필요합니다 |

1341| `toolUseID` | `string` | 어시스턴트 메시지 내에서 이 특정 도구 호출의 고유 식별자 |1341| `toolUseID` | `string` | 어시스턴트 메시지 내에서 이 특정 도구 호출의 고유 식별자 |

1342| `agentID` | `string` | 서브에이전트 내에서 실행 중인 경우, 서브에이전트의 ID |1342| `agentID` | `string` | 서브에이전트 내에서 실행 중인 경우, 서브에이전트의 ID |

1343| `requestId` | `string` | `control_request` 엔벨로프의 `request_id`. 서명된 HTTP POST처럼 애플리케이션이 SDK 외부에서 보내는 `control_response`는 Claude Code 프로세스가 응답을 요청과 매칭할 수 있도록 이 값을 그대로 포함해야 합니다 |1343| `requestId` | `string` | `control_request` 엔벨로프의 `request_id`. 서명된 HTTP POST처럼 애플리케이션이 SDK 외부에서 보내는 `control_response`는 Claude Code 프로세스가 응답을 요청과 매칭할 수 있도록 이 값을 그대로 포함해야 합니다 |

5528 5528 

5529`setMcpServers()`를 호출할 때, Claude Code는 다음 규칙을 적용합니다:5529`setMcpServers()`를 호출할 때, Claude Code는 다음 규칙을 적용합니다:

5530 5530 

5531* **호출이 이름을 지정하지 않는 서버**: Claude Code는 플러그인 제공 서버를 계속 실행합니다. Agent SDK v0.3.210 이상이 필요합니다.5531* **호출이 이름을 지정하지 않는 서버**: [클라우드 세션](/docs/ko/claude-code-on-the-web) 외부에서 Claude Code는 이전 `setMcpServers()` 호출이 추가한 서버와 인프로세스 SDK 서버의 연결을 끊고 이를 `removed`에 나열합니다. 다른 서버는 계속 실행되며 `removed`에 나열되지 않습니다. 여기에는 [`mcpServers`](#options) 옵션의 stdio, HTTP 및 SSE 서버, 설정 파일의 서버, 플러그인 제공 서버가 포함됩니다.

5532* **호출이 이름을 지정하는 서버**: CLI가 시작 시 시작한 기본 제공 서버를 제외하고, Claude Code는 구성이 전달한 것과 다를 때만 실행 중인 서버를 교체합니다.5532* **호출이 이름을 지정하는 서버**: Claude Code는 이전 `setMcpServers()` 호출이 추가한 stdio, HTTP 또는 SSE 서버를 해당 구성이 전달한 것과 다를 때만 교체합니다. 해당 이름으로 이미 등록된 인프로세스 SDK 서버는 그대로 유지되므로, 이를 교체하려면 한 호출에서 제외한 다음 호출에서 추가하세요.

5533* **CLI가 시작 시 시작한 기본 제공 서버**: 호출이 하나를 이름으로 지정하면, Claude Code는 해당 항목을 삭제하고 `errors`에서 보고합니다.5533* **CLI가 시작 시 시작한 기본 제공 서버**: 호출이 하나를 이름으로 지정하면, Claude Code는 해당 항목을 삭제하고 `errors`에서 보고합니다.

5534 5534 

5535프로미스는 새로 추가된 stdio, HTTP 및 SSE 서버가 연결되거나 실패한 후 해결되므로, 연결된 서버의 도구는 다음 턴에서 사용 가능합니다.5535프로미스는 새로 추가된 stdio, HTTP 및 SSE 서버가 연결되거나 실패한 후 해결되므로, 연결된 서버의 도구는 다음 턴에서 사용 가능합니다.

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋으로 인해 삭제가 거부된 세션을 삭제하고, worktree와 해당 브랜치 및 커밋을 함께 삭제합니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.260 이상 필요 |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 푸시되지 않은 커밋으로 인해 삭제가 거부된 세션을 삭제하고, worktree와 해당 브랜치 및 커밋을 함께 삭제합니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.260 이상 필요 |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | git 또는 `WorktreeRemove` 훅이 worktree를 제거할 수 없어 삭제가 거부된 세션을 삭제하고, worktree 디렉터리를 어쨌든 삭제하며 해당 브랜치는 저장소에 남겨둡니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.268 이상 필요 |820| `claude rm <id> --force-remove-worktree <worktree-id>` | git 또는 `WorktreeRemove` 훅이 worktree를 제거할 수 없어 삭제가 거부된 세션을 삭제하고, worktree 디렉터리를 어쨌든 삭제하며 해당 브랜치는 저장소에 남겨둡니다. 거부 시 출력된 정확한 값을 전달합니다. [세션 삭제 시 제거되는 항목](#what-deleting-a-session-removes) 참조. v2.1.268 이상 필요 |

821| `claude daemon status` | [감독자](#the-supervisor-process)의 상태, 버전, 소켓 디렉터리 및 워커 수 인쇄 |821| `claude daemon status` | [감독자](#the-supervisor-process)의 상태, 버전, 소켓 디렉터리 및 워커 수 인쇄 |

822| `claude daemon logs` | 감독자의 로그 파일 [`~/.claude/daemon.log`](#where-state-is-stored)를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 도착하는 대로 인쇄 |

822| `claude daemon stop --any` | 감독자 프로세스와 이를 호스팅하는 백그라운드 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 상태로 유지하면 다음 감독자가 이들에 다시 연결됩니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |823| `claude daemon stop --any` | 감독자 프로세스와 이를 호스팅하는 백그라운드 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 상태로 유지하면 다음 감독자가 이들에 다시 연결됩니다. 다음 `claude agents` 또는 `claude --bg`는 새로운 감독자를 시작합니다 |

823 824 

824`claude attach`와 `claude logs`는 ID 대신 실행 중인 세션 이름의 일부를 받을 수 있습니다(예: `claude logs "auth refactor"`). 이름을 전달하려면 Claude Code v2.1.290 이상이 필요합니다.825`claude attach`와 `claude logs`는 ID 대신 실행 중인 세션 이름의 일부를 받을 수 있습니다(예: `claude logs "auth refactor"`). 이름을 전달하려면 Claude Code v2.1.290 이상이 필요합니다.

20 20 

21이 작업을 지원하지만 에이전트를 실행하는 방식이 아닌 세 가지 추가 도구가 있습니다:21이 작업을 지원하지만 에이전트를 실행하는 방식이 아닌 세 가지 추가 도구가 있습니다:

22 22 

23* [Worktrees](/docs/ko/worktrees)는 각 세션에 별도의 git 체크아웃을 제공하므로 병렬 세션이 동일한 파일을 편집하지 않습니다. 직접 실행하는 세션에 사용하세요. 에이전트 뷰에서 디스패치된 세션은 [파일을 편집하기 전에 자신의 worktree로 이동](/docs/ko/agent-view#how-file-edits-are-isolated)하고, 생성하는 서브에이전트도 각각 하나씩 얻을 수 있습니다.23* [Worktrees](/docs/ko/worktrees)는 각 세션에 별도의 git 체크아웃을 제공하므로 병렬 세션이 각자 자신의 파일 사본을 편집합니다. 직접 실행하는 세션에 사용하세요. 에이전트 뷰에서 디스패치된 세션은 [파일을 편집하기 전에 자신의 worktree로 이동](/docs/ko/agent-view#how-file-edits-are-isolated)하고, 생성하는 서브에이전트도 각각 하나씩 얻을 수 있습니다.

24* [크로스 세션 메시징](/docs/ko/cross-session-messaging)을 통해 Claude는 이 머신의 다른 Claude Code 세션, 다른 머신의 세션, 또는 [웹의 Claude Code](/docs/ko/claude-code-on-the-web)의 세션을 나열하고 메시지를 보낼 수 있으므로, 직접 실행하는 세션들이 결과와 상태를 서로 전달할 수 있습니다.24* [크로스 세션 메시징](/docs/ko/cross-session-messaging)을 통해 Claude는 이 머신의 다른 Claude Code 세션, 다른 머신의 세션, 또는 [웹의 Claude Code](/docs/ko/claude-code-on-the-web)의 세션을 나열하고 메시지를 보낼 수 있으므로, 직접 실행하는 세션들이 결과와 상태를 서로 전달할 수 있습니다.

25* [`/batch`](/docs/ko/commands)는 Claude가 하나의 큰 변경을 5\~30개의 worktree 격리 서브에이전트로 분할하는 [스킬](/docs/ko/skills)입니다. 이는 서브에이전트와 worktree의 패키지된 사용이지, 별도의 조율 스타일이 아닙니다.25* [`/batch`](/docs/ko/commands)는 Claude가 하나의 큰 변경을 5\~30개의 worktree 격리 서브에이전트로 분할하는 [스킬](/docs/ko/skills)입니다. 이는 서브에이전트와 worktree의 패키지된 사용이지, 별도의 조율 스타일이 아닙니다.

26 26 

75| - | - |75| - | - |

76| Claude Code v2.1.195 이상 | `claude gateway` 서브명령 및 게이트웨이 로그인 흐름은 v2.1.195에서 제공됩니다. 이전 공개 빌드는 이를 포함하지 않습니다. 게이트웨이 서버를 실행하는 머신과 각 개발자의 머신 모두 v2.1.195 이상이어야 합니다; `claude update`를 실행하여 최신 릴리스를 받으세요. [Claude Platform on AWS 업스트림](/docs/ko/claude-apps-gateway-config#claude-platform-on-aws)은 게이트웨이 서버에서 Claude Code v2.1.198 이상이 필요합니다. |76| Claude Code v2.1.195 이상 | `claude gateway` 서브명령 및 게이트웨이 로그인 흐름은 v2.1.195에서 제공됩니다. 이전 공개 빌드는 이를 포함하지 않습니다. 게이트웨이 서버를 실행하는 머신과 각 개발자의 머신 모두 v2.1.195 이상이어야 합니다; `claude update`를 실행하여 최신 릴리스를 받으세요. [Claude Platform on AWS 업스트림](/docs/ko/claude-apps-gateway-config#claude-platform-on-aws)은 게이트웨이 서버에서 Claude Code v2.1.198 이상이 필요합니다. |

77| OpenID Connect (OIDC) ID 제공자 | Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex 또는 PingFederate와 같은 다른 OIDC 호환 IdP. 게이트웨이는 표준 OIDC 검색 및 인증 코드 흐름을 이에 대해 실행합니다. SAML 및 LDAP는 지원되지 않습니다. |77| OpenID Connect (OIDC) ID 제공자 | Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex 또는 PingFederate와 같은 다른 OIDC 호환 IdP. 게이트웨이는 표준 OIDC 검색 및 인증 코드 흐름을 이에 대해 실행합니다. SAML 및 LDAP는 지원되지 않습니다. |

78| PostgreSQL 14 이상 | 브라우저 콜백이 쓰고 폴링 CLI가 읽는 장치 로그인 흐름, 그리고 속도 제한 카운터를 지원합니다. 가장 작은 계층을 포함한 모든 관리 Postgres가 작동합니다. 지출 제한이 구성되지 않으면 게이트웨이는 몇 KB의 단기 인증 상태를 저장합니다; [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)을 사용하면 백업해야 하는 지속적인 지출, 감사 및 ID 테이블도 보유합니다. `?sslmode=require`를 통한 TLS가 권장됩니다. |78| PostgreSQL 11 이상 | 장치 로그인 흐름과 속도 제한 카운터를 지원합니다. 가장 작은 계층을 포함한 관리형 PostgreSQL 서비스가 작동합니다; [지원되는 데이터베이스](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)을 사용하면 백업해야 하는 지속적인 지출, 감사 및 ID 테이블도 보유합니다. `?sslmode=require`를 통한 TLS가 권장됩니다. PostgreSQL 11, 12, 13은 게이트웨이 서버에서 Claude Code v2.1.290 이상이 필요합니다. PostgreSQL 프로젝트는 더 이상 해당 버전을 유지 관리하지 않으므로 가능하면 더 새로운 버전을 사용하세요. |

79| 모델 업스트림 | Amazon Bedrock 자격증명, Claude Platform on AWS 자격증명, Google Cloud 자격증명, Microsoft Foundry 리소스 또는 Anthropic API 키. 장애 조치를 사용한 여러 업스트림이 지원됩니다. |79| 모델 업스트림 | Amazon Bedrock 자격 증명, Claude Platform on AWS 자격 증명, Google Cloud 자격 증명, Microsoft Foundry 리소스 또는 Anthropic API 키. 장애 조치를 사용한 여러 업스트림이 지원됩니다. |

80| HTTPS | 게이트웨이는 개발자 노트북과 로그인에 사용되는 모든 브라우저에서 `https://`를 통해 도달 가능해야 합니다; 게이트웨이는 동일한 리스너에서 장치 확인 페이지를 제공합니다. `listen.tls`를 통해 TLS 인증서를 제공하거나, TLS 종료 수신 대기 뒤에서 실행하고, 두 경우 모두 `listen.public_url`을 외부 원본으로 설정하세요. 일반 `http://` 원본은 게이트웨이 호스트가 루프백인 경우에만 허용됩니다: `localhost`, `127.0.0.1` 또는 `::1`. |80| HTTPS | 게이트웨이는 개발자 노트북과 로그인에 사용되는 모든 브라우저에서 `https://`를 통해 도달 가능해야 합니다; 게이트웨이는 동일한 리스너에서 장치 확인 페이지를 제공합니다. `listen.tls`를 통해 TLS 인증서를 제공하거나, TLS 종료 수신 대기 뒤에서 실행하고, 두 경우 모두 `listen.public_url`을 외부 원본으로 설정하세요. `/login`에서 Claude Code는 게이트웨이 호스트가 루프백인 경우에만 일반 `http://` 원본을 허용합니다: `localhost`, `127.0.0.1` 또는 `::1`. |

81| 개인 네트워크 주소 | `/login`에서 Claude Code는 게이트웨이의 호스트명 또는 IP 주소가 개인 주소로만 확인되도록 요구합니다: RFC 1918, 링크 로컬, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7` 또는 루프백. 호스팅하는 게이트웨이의 경우 선언한 블록 외의 모든 공개 주소는 거부됩니다; 배포 가이드의 [위협 모델](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)을 참조하세요. 개발자 머신이 HTTPS를 회사 프록시를 통해 라우팅하는 경우, 로그인은 프록시 호스트도 개인 주소로 확인되도록 요구합니다; 그렇지 않으면 게이트웨이 호스트를 `NO_PROXY`에 추가하여 CLI가 직접 연결하도록 하세요. 내부 네트워크가 조직이 소유한 공개 IPv4 공간에서 번호가 지정된 경우 [해당 블록을 선언](#allow-a-gateway-on-public-address-space-you-own)하여 `/login`이 거기서 게이트웨이를 수락하도록 하세요. |81| 개인 네트워크 주소 | `/login`에서 Claude Code는 게이트웨이의 호스트명 또는 IP 주소가 개인 주소로만 확인되도록 요구합니다: RFC 1918, 링크 로컬, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7` 또는 루프백. 호스팅하는 게이트웨이의 경우 선언한 블록 외의 모든 공개 주소는 거부됩니다; 배포 가이드의 [위협 모델](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)을 참조하세요. 개발자 머신이 HTTPS를 회사 프록시를 통해 라우팅하는 경우, 로그인은 프록시 호스트도 개인 주소로 확인되도록 요구합니다; 그렇지 않으면 게이트웨이 호스트를 `NO_PROXY`에 추가하여 CLI가 직접 연결하도록 하세요. 내부 네트워크가 조직이 소유한 공개 IPv4 공간에서 번호가 지정된 경우 [해당 블록을 선언](#allow-a-gateway-on-public-address-space-you-own)하여 `/login`이 거기서 게이트웨이를 수락하도록 하세요. |

82| Linux 런타임 | 게이트웨이 서버는 네이티브 Linux 바이너리에서만 실행됩니다. macOS는 로컬 개발에 작동합니다. Windows는 서버 플랫폼으로 지원되지 않습니다. |82| Linux 런타임 | 게이트웨이 서버는 네이티브 Linux 바이너리에서만 실행됩니다. macOS는 로컬 개발에 작동합니다. Windows는 서버 플랫폼으로 지원되지 않습니다. |

83 83 

91 </Step>91 </Step>

92 92 

93 <Step title="PostgreSQL 데이터베이스 프로비저닝">93 <Step title="PostgreSQL 데이터베이스 프로비저닝">

94 가장 작은 관리 계층을 포함한 모든 Postgres 14 이상이 작동합니다. 게이트웨이는 부팅 시 자체 스키마 마이그레이션을 실행하므로 데이터베이스 역할은 테이블을 생성하고 변경할 권한이 필요합니다; [`store`](/docs/ko/claude-apps-gateway-config#store)를 참조하세요.94 PostgreSQL 11 이상을 사용하세요. 가장 작은 관리형 계층으로 충분합니다. 게이트웨이는 부팅 시 자체 스키마 마이그레이션을 실행하므로 데이터베이스 역할은 테이블을 생성하고 변경할 권한이 필요합니다; [`store`](/docs/ko/claude-apps-gateway-config#store)를 참조하세요.

95 </Step>95 </Step>

96 96 

97 <Step title="gateway.yaml 작성">97 <Step title="gateway.yaml 작성">

117 ttl_hours: 1 # IdP 프로비저닝 해제 시 취소 지연도 제한117 ttl_hours: 1 # IdP 프로비저닝 해제 시 취소 지연도 제한

118 118 

119 store:119 store:

120 postgres_url: ${GATEWAY_POSTGRES_URL} # 관리 Postgres의 경우 ?sslmode=require 추가120 postgres_url: ${GATEWAY_POSTGRES_URL} # 관리형 Postgres의 경우 ?sslmode=require 추가

121 121 

122 upstreams:122 upstreams:

123 - provider: bedrock123 - provider: bedrock

124 region: us-east-1124 region: us-east-1

125 auth: {} # 비어있음: AWS 기본 자격증명 체인125 auth: {} # 비어있음: AWS 기본 자격 증명 체인

126 # (IRSA, EC2/ECS 작업 역할, 환경 변수, ~/.aws)126 # (IRSA, EC2/ECS 작업 역할, 환경 변수, ~/.aws)

127 127 

128 # 모델은 업스트림별로 자동으로 변환됩니다. 기본 제공 카탈로그128 # 모델은 업스트림별로 자동으로 변환됩니다. 기본 제공 카탈로그

132 auto_include_builtin_models: true132 auto_include_builtin_models: true

133 ```133 ```

134 134 

135 이 구성은 기본 Bedrock 모델 카탈로그로 작동하는 로그인 루프에 충분합니다. 실행되면 [`managed.policies`](/docs/ko/claude-apps-gateway-config#managed)를 통해 그룹별 RBAC 및 관리 설정을 추가하고, [`telemetry`](/docs/ko/claude-apps-gateway-config#telemetry)를 통해 텔레메트리 팬아웃을 추가하고, [`models`](/docs/ko/claude-apps-gateway-config#models)를 통해 다중 업스트림 장애 조치, 프로비저닝된 처리량 ARN 또는 미국 이외 지역을 추가하세요.135 이 구성은 기본 Amazon Bedrock 모델 카탈로그로 작동하는 로그인 루프에 충분합니다. 실행되면 [`managed.policies`](/docs/ko/claude-apps-gateway-config#managed)를 통해 그룹별 RBAC 및 관리형 설정을 추가하고, [`telemetry`](/docs/ko/claude-apps-gateway-config#telemetry)를 통해 텔레메트리 팬아웃을 추가하고, [`models`](/docs/ko/claude-apps-gateway-config#models)를 통해 다중 업스트림 장애 조치, 프로비저닝된 처리량 ARN 또는 미국 이외 지역을 추가하세요.

136 136 

137 <Note>137 <Note>

138 Amazon Bedrock 업스트림은 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 `inference-profile/us.anthropic.*` ARN과 기본 `foundation-model/anthropic.*` ARN 모두에 가진 AWS 주체가 필요합니다. 또한 Bedrock 콘솔의 모델 카탈로그에서 계정에 대해 제출된 Anthropic의 일회성 사용 사례 양식이 필요합니다.138 Amazon Bedrock 업스트림은 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 `inference-profile/us.anthropic.*` ARN과 기본 `foundation-model/anthropic.*` ARN 모두에 가진 AWS 주체가 필요합니다. 또한 Bedrock 콘솔의 모델 카탈로그에서 계정에 대해 제출된 Anthropic의 일회성 사용 사례 양식이 필요합니다.

139 139 

140 정적 키보다는 EKS의 IRSA, ECS 작업 역할 또는 EC2 인스턴스 프로필을 사용하여 자격증명을 제공하세요. [`upstreams` 참조](/docs/ko/claude-apps-gateway-config#upstreams)는 전체 IAM 세부사항, 클라우드 간 자격증명 매트릭스, 다른 제공자의 `auth` 블록을 가집니다.140 정적 키보다는 EKS의 IRSA, ECS 작업 역할 또는 EC2 인스턴스 프로필을 사용하여 자격 증명을 제공하세요. [`upstreams` 참조](/docs/ko/claude-apps-gateway-config#upstreams)는 전체 IAM 세부사항, 클라우드 간 자격 증명 매트릭스, 다른 제공자의 `auth` 블록을 가집니다.

141 </Note>141 </Note>

142 </Step>142 </Step>

143 143 

154 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}154 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

155 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}155 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

156 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway156 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

157 # AWS 자격증명: 프로덕션에서는 이를 생략하고 인스턴스157 # AWS 자격 증명: 프로덕션에서는 이를 생략하고 인스턴스

158 # 역할을 사용하세요. 로컬 Compose 테스트의 경우 자신의 것을 전달하세요:158 # 역할을 사용하세요. 로컬 Compose 테스트의 경우 자신의 것을 전달하세요:

159 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}159 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

160 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}160 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

172 volumes: { pgdata: }172 volumes: { pgdata: }

173 ```173 ```

174 174 

175 게이트웨이는 구성을 읽고, Postgres에 연결하고 스키마 마이그레이션을 적용하고, IdP에 대해 OIDC 검색을 실행하고, 업스트림 클라이언트를 빌드하고, 수신 대기를 시작하는 단일 Linux 바이너리입니다. 부팅은 구성, Postgres 연결, OIDC 검색 및 업스트림 클라이언트 구성에 대해 실패 폐쇄됩니다. 이 중 하나가 도달 불가능하거나 잘못 구성된 경우, 게이트웨이는 저하된 상태에서 트래픽을 제공하는 대신 오류로 종료됩니다.175 게이트웨이는 구성을 읽고, Postgres에 연결하고 스키마 마이그레이션을 적용하고, IdP에 대해 OIDC 검색을 실행하고, 업스트림 클라이언트를 빌드하고, 수신 대기를 시작하는 단일 Linux 바이너리입니다.

176 176 

177 성공적인 부팅은 Amazon Bedrock 및 Google Cloud의 Agent Platform 인스턴스 자격증명이 부팅 시가 아닌 첫 요청에서 확인되기 때문에 추론 경로를 검증하지 않습니다.177 부팅은 구성, Postgres 연결, OIDC 검색 및 업스트림 클라이언트 구성에 대해 실패 폐쇄됩니다. 이 중 하나가 도달 불가능하거나 잘못 구성된 경우, 게이트웨이는 저하된 상태에서 트래픽을 제공하는 대신 오류로 종료됩니다.

178 

179 성공적인 부팅은 Amazon Bedrock 및 Google Cloud의 Agent Platform 인스턴스 자격 증명이 부팅 시가 아닌 첫 요청에서 확인되기 때문에 추론 경로를 검증하지 않습니다.

178 180 

179 부팅 시퀀스에 대해 stderr를 감시하세요. 로그 라인은 `[gateway] <timestamp> <level> <message>` 형식을 사용하고, 감사 이벤트는 `evt` 필드가 있는 단일 라인 JSON이며, 시작 배너(아래 생략됨)는 마이그레이션과 수신 대기 라인 사이에 인쇄됩니다. 신규 데이터베이스는 스키마 마이그레이션당 하나의 `migration N applied` 라인을 인쇄합니다; 이미 마이그레이션된 데이터베이스는 없습니다. 순서대로 다음을 볼 수 있습니다:181 부팅 시퀀스에 대해 stderr를 감시하세요. 로그 라인은 `[gateway] <timestamp> <level> <message>` 형식을 사용하고, 감사 이벤트는 `evt` 필드가 있는 단일 라인 JSON이며, 시작 배너(아래 생략됨)는 마이그레이션과 수신 대기 라인 사이에 인쇄됩니다. 신규 데이터베이스는 스키마 마이그레이션당 하나의 `migration N applied` 라인을 인쇄합니다; 이미 마이그레이션된 데이터베이스는 없습니다. 순서대로 다음을 볼 수 있습니다:

180 182 

187 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080189 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

188 ```190 ```

189 191 

190 게이트웨이는 또한 `access_control.allow_cidrs`가 비어있다는 경고를 기록합니다. 게이트웨이가 제공하는 클라이언트 주소를 제한하는 것이 없기 때문에 여기서는 예상됩니다. [`access_control` 참조](/docs/ko/claude-apps-gateway-config#http-tuning)는 권장 범위를 가집니다.192 게이트웨이는 또한 `access_control.allow_cidrs`가 비어있다는 경고를 기록합니다. 허용 목록을 설정하기 전까지는 게이트웨이가 제공하는 클라이언트 주소를 제한하는 것이 없기 때문에 여기서는 예상된 동작입니다. [`access_control` 참조](/docs/ko/claude-apps-gateway-config#http-tuning)는 권장 범위를 가집니다.

191 193 

192 부팅이 `claude gateway listening on` 라인 전에 종료되면, stderr의 마지막 라인이 문제를 이름 지정합니다:194 부팅이 `claude gateway listening on` 라인 전에 종료되면, stderr의 마지막 라인이 문제를 이름 지정합니다:

193 195 

253 </Step>255 </Step>

254 256 

255 <Step title="개발자 로그인">257 <Step title="개발자 로그인">

256 이 마지막 단계는 서버가 아닌 개발자 머신에서 발생합니다. 해당 머신의 [관리 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에서 `forceLoginMethod`를 `"gateway"`로 설정하고 `forceLoginGatewayUrl`을 게이트웨이의 `public_url`로 설정한 다음 `/login`을 실행하고, **Cloud gateway** 화면에서 Enter를 누르고, 브라우저 로그인을 완료하세요. [게이트웨이 URL 설정](#set-the-gateway-url) 아래는 두 키를 모든 개발자 머신에 배포하는 것을 다룹니다.258 이 마지막 단계는 서버가 아닌 개발자 머신에서 발생합니다. 해당 머신의 [관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에서 `forceLoginMethod`를 `"gateway"`로 설정하고 `forceLoginGatewayUrl`을 게이트웨이의 `public_url`로 설정한 다음 `/login`을 실행하고, **Cloud gateway** 화면에서 Enter를 누르고, 브라우저 로그인을 완료하세요. [게이트웨이 URL 설정](#set-the-gateway-url) 아래는 두 키를 모든 개발자 머신에 배포하는 것을 다룹니다.

257 </Step>259 </Step>

258</Steps>260</Steps>

259 261 

158게이트웨이는 부팅 시 키와 인증서를 한 번 읽으므로 변경된 파일은 재시작 후에만 적용됩니다. IdP에 없는 인증서를 제시하는 토큰 요청이 없도록 다음 순서로 회전합니다:158게이트웨이는 부팅 시 키와 인증서를 한 번 읽으므로 변경된 파일은 재시작 후에만 적용됩니다. IdP에 없는 인증서를 제시하는 토큰 요청이 없도록 다음 순서로 회전합니다:

159 159 

1601. 새 인증서를 이전 인증서와 함께 IdP에 업로드합니다.1601. 새 인증서를 이전 인증서와 함께 IdP에 업로드합니다.

1612. `gateway.yaml`이 로드하는 키와 인증서 파일을 교체한 후 게이트웨이를 재시작합니다.1612. `gateway.yaml`이 로드하는 키와 인증서 파일을 교체한 후 게이트웨이를 재시작합니다. 여러 복제본을 실행하는 경우 이전 인증서를 제거할 때까지 IdP에 두 인증서가 모두 있으므로 [롤링 재시작](/docs/ko/claude-apps-gateway-deploy#upgrades)을 사용할 수 있습니다.

1623. IdP에서 이전 인증서를 제거합니다.1623. 모든 복제본이 재시작된 후 IdP에서 이전 인증서를 제거합니다.

163 163 

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 전방 프록시를 통한 IdP 요청165 전방 프록시를 통한 IdP 요청

227 227 

228| 필드 | 필수 | 설명 |228| 필드 | 필수 | 설명 |

229| - | - | - |229| - | - | - |

230| `postgres_url` | 예 | `postgres://` 또는 `postgresql://` URL입니다. 필수: 장치 부여 랑데부입니다. 브라우저 콜백이 작성하고 폴링 CLI가 읽으므로 교차 복제본 상태가 필요합니다. 게이트웨이는 부팅 및 업그레이드 시 자체 스키마 마이그레이션을 실행하므로 역할은 대상 스키마에서 테이블을 생성하고 변경할 권리가 필요합니다. [업그레이드](/docs/ko/claude-apps-gateway-deploy#upgrades) 및 [Postgres](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. |230| `postgres_url` | 예 | 쉼표로 구분된 목록이 아닌 하나의 호스트를 가진 `postgres://` 또는 `postgresql://` URL입니다. 게이트웨이는 부팅 및 업그레이드 시 자체 스키마 마이그레이션을 실행하므로 역할은 대상 스키마에서 테이블을 생성하고 변경할 권리가 필요합니다. [업그레이드](/docs/ko/claude-apps-gateway-deploy#upgrades) 및 [Postgres](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. |

231| `username` | 아니오 | `postgres_url`의 사용자를 재정의합니다. |231| `username` | 아니오 | `postgres_url`의 사용자를 재정의합니다. |

232| `password` | 아니오 | 데이터베이스 자격 증명입니다. 자격 증명이 URL에서 벗어나도록 `postgres_url`이 아닌 여기에 설정합니다. 모든 문자를 수락하고 URL 자격 증명보다 우선합니다. |232| `password` | 아니오 | 데이터베이스 자격 증명입니다. 자격 증명이 URL에서 벗어나도록 `postgres_url`이 아닌 여기에 설정합니다. 모든 문자를 수락하고 URL 자격 증명보다 우선합니다. |

233| `max_connections` | 아니오 | 복제본당 Postgres 연결 풀 크기입니다. 기본값 `5`로 보수적이고 공유 데이터베이스에 친화적입니다. [지출 제한](#admin)이 활성화되면 핫 경로는 추론 요청당 몇 가지 작업을 수행하므로 로드 아래의 전용 데이터베이스에 대해 이를 높이고 복제본 × 이를 데이터베이스의 `max_connections` 아래로 유지합니다. |233| `max_connections` | 아니오 | 복제본당 Postgres 연결 풀 크기입니다. 기본값 `5`로 보수적이고 공유 데이터베이스에 친화적입니다. [지출 제한](#admin)이 활성화되면 핫 경로는 추론 요청당 몇 가지 작업을 수행하므로 로드 아래의 전용 데이터베이스에 대해 이를 높이고 복제본 × 이를 데이터베이스의 `max_connections` 아래로 유지합니다. |

313 프록시를 실행하는 경우 사용자별 ID 헤더313 프록시를 실행하는 경우 사용자별 ID 헤더

314</h5>314</h5>

315 315 

316`provider: anthropic` 업스트림의 `base_url`을 Anthropic API 대신 실행하는 프록시로 지정할 수 있습니다. 해당 프록시에 각 요청을 보낸 개발자를 알리려면 해당 업스트림에 `forward_user_identity: true`를 설정합니다. 그러면 프록시는 개발자별로 지출을 기인할 수 있습니다. 게이트웨이 v2.1.233 이상을 실행해야 합니다.316`provider: anthropic` 업스트림의 `base_url`을 Anthropic API 대신 실행하는 프록시로 지정할 수 있습니다. 해당 프록시에 각 요청을 보낸 개발자를 알리려면 해당 업스트림에 `forward_user_identity: true`를 설정합니다. 그러면 프록시는 개발자별로 지출을 기인할 수 있습니다. Claude Code v2.1.233 이상을 실행하는 게이트웨이가 필요합니다.

317 317 

318예를 들어 `upstream-gateway.internal.example.com`의 프록시의 경우:318예를 들어 `upstream-gateway.internal.example.com`의 프록시의 경우:

319 319 

413 413 

414Bedrock 업스트림에 `assume_role`을 설정하면 게이트웨이는 자체 AWS 신원을 사용하여 이름을 지정하는 역할에 대해서만 `sts:AssumeRole`을 호출합니다. 이는 게이트웨이와 다른 AWS 계정에 있을 수 있습니다. 해당 업스트림의 모든 Bedrock 요청은 STS가 반환하는 1시간 자격 증명으로 서명되므로 장기 액세스 키가 계정을 교차하지 않습니다.414Bedrock 업스트림에 `assume_role`을 설정하면 게이트웨이는 자체 AWS 신원을 사용하여 이름을 지정하는 역할에 대해서만 `sts:AssumeRole`을 호출합니다. 이는 게이트웨이와 다른 AWS 계정에 있을 수 있습니다. 해당 업스트림의 모든 Bedrock 요청은 STS가 반환하는 1시간 자격 증명으로 서명되므로 장기 액세스 키가 계정을 교차하지 않습니다.

415 415 

416게이트웨이 v2.1.281 이상을 실행해야 합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다.416Claude Code v2.1.281 이상을 실행하는 게이트웨이가 필요합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다.

417 417 

418```yaml theme={null}418```yaml theme={null}

419upstreams:419upstreams:

470 470 

471기본적으로 게이트웨이는 모든 Bedrock 요청을 하나의 자격 증명으로 서명하므로 AWS는 모든 개발자의 요청을 단일 IAM 주체 아래에서 봅니다. [`assume_role`](#bedrock-in-another-aws-account)에 `session_name: email`을 추가하면 게이트웨이는 개발자당 시간당 한 번 `sts:AssumeRole`을 호출하고 세션 이름을 해당 개발자의 이메일로 설정하며 반환된 자격 증명으로 요청에 서명하므로 각 개발자의 요청은 자신의 가정된 역할 세션 아래에서 AWS에 도달합니다. 역할은 게이트웨이의 자체 계정에 있을 수 있습니다.471기본적으로 게이트웨이는 모든 Bedrock 요청을 하나의 자격 증명으로 서명하므로 AWS는 모든 개발자의 요청을 단일 IAM 주체 아래에서 봅니다. [`assume_role`](#bedrock-in-another-aws-account)에 `session_name: email`을 추가하면 게이트웨이는 개발자당 시간당 한 번 `sts:AssumeRole`을 호출하고 세션 이름을 해당 개발자의 이메일로 설정하며 반환된 자격 증명으로 요청에 서명하므로 각 개발자의 요청은 자신의 가정된 역할 세션 아래에서 AWS에 도달합니다. 역할은 게이트웨이의 자체 계정에 있을 수 있습니다.

472 472 

473게이트웨이 v2.1.281 이상을 실행해야 합니다. [AWS의 비용 기인](/docs/ko/claude-apps-gateway-on-aws#cost-attribution)은 IAM 역할과 AWS 청구가 세션을 표시하는 위치를 다룹니다.473Claude Code v2.1.281 이상을 실행하는 게이트웨이가 필요합니다. [AWS의 비용 기인](/docs/ko/claude-apps-gateway-on-aws#cost-attribution)은 IAM 역할과 AWS 청구가 세션을 표시하는 위치를 다룹니다.

474 474 

475```yaml theme={null}475```yaml theme={null}

476upstreams:476upstreams:

586 586 

587빈 `auth` 블록은 Application Default Credentials를 사용합니다: `GOOGLE_APPLICATION_CREDENTIALS`, GCE 메타데이터 또는 GKE Workload Identity. 서비스 계정 JSON 키 파일은 지원되지만 권장되지 않습니다. Workload Identity를 사용하거나 GCE 또는 Cloud Run 인스턴스에 서비스 계정을 연결합니다.587빈 `auth` 블록은 Application Default Credentials를 사용합니다: `GOOGLE_APPLICATION_CREDENTIALS`, GCE 메타데이터 또는 GKE Workload Identity. 서비스 계정 JSON 키 파일은 지원되지만 권장되지 않습니다. Workload Identity를 사용하거나 GCE 또는 Cloud Run 인스턴스에 서비스 계정을 연결합니다.

588 588 

589Google Cloud의 Agent Platform에 대해 [전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)를 사용하려면 `region: global`을 설정합니다. Google은 각 요청을 사용 가능한 지역으로 라우팅하므로 지역별 모델 가용성을 추적하지 않습니다. 특정 지역을 설정하면 모든 요청이 이에 고정됩니다.589지역 엔드포인트 대신 [Google Cloud의 Agent Platform용 전역 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)를 사용하려면 `region: global`을 설정합니다. Google은 각 요청을 사용 가능한 지역으로 라우팅하므로 지역별 모델 가용성을 추적하지 않습니다. 특정 지역을 설정하면 모든 요청이 이에 고정됩니다.

590 590 

591| 설정 | 방법 |591| 설정 | 방법 |

592| - | - |592| - | - |

221* **[지출 제한 적용](/docs/ko/claude-apps-gateway-spend-limits#postgres-availability)**: 중단 중에 기본적으로 열린 상태로 실패하므로 추론이 계속 흐릅니다. 계량되지 않은 상태로 실행하기보다는 차단하려면 닫힌 상태로 전환합니다221* **[지출 제한 적용](/docs/ko/claude-apps-gateway-spend-limits#postgres-availability)**: 중단 중에 기본적으로 열린 상태로 실패하므로 추론이 계속 흐릅니다. 계량되지 않은 상태로 실행하기보다는 차단하려면 닫힌 상태로 전환합니다

222* **준비 상태**: 기본적으로 `/readyz`는 Postgres에 도달할 수 없게 되자마자 준비되지 않음으로 보고하므로, 모든 복제본이 한 번에 준비 상태 확인에 실패합니다. 트래픽이 확인을 통과한 복제본에만 도달하는 경우, 게이트웨이가 여전히 처리할 수 있는 추론을 포함한 모든 트래픽은 Postgres가 복구될 때까지 실패합니다. `/healthz`의 생존성 프로브는 전체 기간 동안 계속 통과합니다.222* **준비 상태**: 기본적으로 `/readyz`는 Postgres에 도달할 수 없게 되자마자 준비되지 않음으로 보고하므로, 모든 복제본이 한 번에 준비 상태 확인에 실패합니다. 트래픽이 확인을 통과한 복제본에만 도달하는 경우, 게이트웨이가 여전히 처리할 수 있는 추론을 포함한 모든 트래픽은 Postgres가 복구될 때까지 실패합니다. `/healthz`의 생존성 프로브는 전체 기간 동안 계속 통과합니다.

223 223 

224Postgres가 다운되는 동안 생존성 프로브는 계속 통과합니다.

225 

226IdP가 다운되면, 기존 세션은 `ttl_hours`까지 작동하고 새로운 로그인은 실패합니다. 세션 새로고침은 다시 시도 답변을 받고 IdP가 돌아오면 성공합니다. IdP에 빈번한 유지 보수 창이 있으면 더 긴 `ttl_hours`를 설정합니다.224IdP가 다운되면, 기존 세션은 `ttl_hours`까지 작동하고 새로운 로그인은 실패합니다. 세션 새로고침은 다시 시도 답변을 받고 IdP가 돌아오면 성공합니다. IdP에 빈번한 유지 보수 창이 있으면 더 긴 `ttl_hours`를 설정합니다.

227 225 

228<h4 id="readiness-grace-period">226<h4 id="readiness-grace-period">

251 Postgres249 Postgres

252</h3>250</h3>

253 251 

252게이트웨이는 상태를 PostgreSQL 데이터베이스에 저장합니다:

253 

254* **데이터베이스**: 자체 호스팅 또는 관리형 PostgreSQL 자체이며, [최소 버전](/docs/ko/claude-apps-gateway#prerequisites) 이상이어야 합니다. 분산 SQL 데이터베이스처럼 Postgres 프로토콜만 구현하는 데이터베이스는 지원되지 않습니다.

255* **주소**: `store.postgres_url`은 하나의 호스트를 받습니다. 데이터베이스에 여러 노드가 있으면, 관리형 서비스의 엔드포인트, 로드 밸런서 또는 가상 IP와 같이 노드 앞에 있는 주소를 사용합니다. 장애 조치가 걸리는 시간보다 긴 [준비 상태 유예 기간](#readiness-grace-period)을 설정합니다.

256 

254게이트웨이는 부팅 시간 마이그레이션으로 생성된 5개의 데이터 테이블과 `_migrations` 테이블을 보유합니다:257게이트웨이는 부팅 시간 마이그레이션으로 생성된 5개의 데이터 테이블과 `_migrations` 테이블을 보유합니다:

255 258 

256| 테이블 | 내용 | 보존 |259| 테이블 | 내용 | 보존 |

398| CLI `/login`: `Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 또는 `HTTP_PROXY`의 호스트명이 개발자 머신에서 확인되지 않음. 일반적으로 회사 네트워크에 연결되지 않았기 때문 | 개발자가 네트워크 또는 VPN에 연결하고 다시 시도하거나 프록시 URL을 수정하도록 하세요 |401| CLI `/login`: `Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 또는 `HTTP_PROXY`의 호스트명이 개발자 머신에서 확인되지 않음. 일반적으로 회사 네트워크에 연결되지 않았기 때문 | 개발자가 네트워크 또는 VPN에 연결하고 다시 시도하거나 프록시 URL을 수정하도록 하세요 |

399| CLI `/login`: `Could not resolve gateway host <host>` | 머신이 gateway의 내부 DNS 이름을 확인할 수 없음. 일반적으로 회사 네트워크에 없기 때문 | 개발자가 네트워크 또는 VPN에 연결한 후 `/login`을 다시 시도하도록 하세요 |402| CLI `/login`: `Could not resolve gateway host <host>` | 머신이 gateway의 내부 DNS 이름을 확인할 수 없음. 일반적으로 회사 네트워크에 없기 때문 | 개발자가 네트워크 또는 VPN에 연결한 후 `/login`을 다시 시도하도록 하세요 |

400| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |403| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

404| 부트 종료: `store.postgres_url in <path> is not a URL the gateway can read`, 또는 v2.1.290 이전에서는 단순한 `Invalid URL` 또는 `URI error` | URL을 파싱할 수 없음. 예를 들어 둘 이상의 호스트를 나열하거나 비밀번호에 인코딩되지 않은 `/`, `?`, `#`, `%`가 포함된 경우 | [하나의 호스트](#postgres)를 지정하고 비밀번호를 [`store.password`](/docs/ko/claude-apps-gateway-config#store)로 옮기세요 |

401| 부트 종료: `requires the native binary` | Node 대신 네이티브 바이너리에서 실행 중 | [독립 실행형 설치 방법](/docs/ko/setup) 중 하나로 Claude Code를 설치하세요 |405| 부트 종료: `requires the native binary` | Node 대신 네이티브 바이너리에서 실행 중 | [독립 실행형 설치 방법](/docs/ko/setup) 중 하나로 Claude Code를 설치하세요 |

402| 부트가 `config.load` 후 OIDC 검색 오류로 종료됨 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않음 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 비공개 PKI의 경우 `ca_cert_pem`을 설정하세요. 포드가 정방향 프록시를 통해서만 IdP에 도달하는 경우 [`oidc.use_proxy: true`](/docs/ko/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)를 설정하세요. v2.1.227 이전 버전에서는 대신 포드에 IdP의 각 엔드포인트에 대한 직접 경로를 제공하세요. 포드가 IdP의 호스트명을 확인할 수 없거나 프록시가 IP 주소에 대한 `CONNECT`를 거부하는 경우 [프록시 전용 송신](/docs/ko/claude-apps-gateway-config#proxy-only-egress)을 참조하세요. v2.1.277 이상이 필요합니다. |406| 부트가 `config.load` 후 OIDC 검색 오류로 종료됨 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않음 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 비공개 PKI의 경우 `ca_cert_pem`을 설정하세요. 포드가 정방향 프록시를 통해서만 IdP에 도달하는 경우 [`oidc.use_proxy: true`](/docs/ko/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)를 설정하세요. v2.1.227 이전 버전에서는 대신 포드에 IdP의 각 엔드포인트에 대한 직접 경로를 제공하세요. 포드가 IdP의 호스트명을 확인할 수 없거나 프록시가 IP 주소에 대한 `CONNECT`를 거부하는 경우 [프록시 전용 송신](/docs/ko/claude-apps-gateway-config#proxy-only-egress)을 참조하세요. v2.1.277 이상이 필요합니다. |

403| 부트가 Postgres 권한 오류로 종료됨 | 데이터베이스 역할이 스키마에 대한 DDL 권한이 없음 | 부트 시 테이블을 생성하고 변경할 수 있도록 gateway 스키마에 대해 역할에 `CREATE` 권한을 부여하세요 |407| 부트가 Postgres 권한 오류로 종료됨 | 데이터베이스 역할이 스키마에 대한 DDL 권한이 없음 | 부트 시 테이블을 생성하고 변경할 수 있도록 gateway 스키마에 대해 역할에 `CREATE` 권한을 부여하세요 |

404| 로그: `could not connect to Postgres at boot, attempt 1 of 3` | gateway가 시작될 때 데이터베이스에 도달할 수 없었음. 예를 들어 네트워크가 아직 시작 중인 콜드 인스턴스 | gateway가 부팅을 완료하면 조치가 필요하지 않습니다. 데이터베이스에 도달할 수 없을 때 gateway는 종료되기 전에 2초 간격으로 연결을 3번 시도합니다. `could not connect to Postgres`로 종료되면 `store.postgres_url`과 데이터베이스로의 네트워크 경로를 확인하세요. 시도가 거부되지 않고 시간 초과되면 각 시도에 더 많은 시간을 주기 위해 [`store.connect_timeout_seconds`](/docs/ko/claude-apps-gateway-config#store)를 높이세요. |408| 로그: `could not connect to Postgres at boot, attempt 1 of 3` | gateway가 시작될 때 데이터베이스에 도달할 수 없었음. 예를 들어 네트워크가 아직 시작 중인 콜드 인스턴스 | gateway가 부팅을 완료하면 조치가 필요하지 않습니다. 데이터베이스에 도달할 수 없을 때 gateway는 종료되기 전에 2초 간격으로 연결을 3번 시도합니다. `could not connect to Postgres`로 종료되면 `store.postgres_url`(하나의 호스트를 지정하는지 포함)과 데이터베이스로의 네트워크 경로를 확인하세요. 시도가 거부되지 않고 시간 초과되면 각 시도에 더 많은 시간을 주기 위해 [`store.connect_timeout_seconds`](/docs/ko/claude-apps-gateway-config#store)를 높이세요. |

405| `/oauth/callback`이 "Sign-in could not be completed"를 표시함 | 이메일 도메인이 거부됨, id\_token 검증 실패, 또는 `email_verified`가 명시적으로 `false`이며 gateway는 항상 재정의 없이 거부함 | `allowed_email_domains`을 확인하고 IdP가 확인된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에서 이메일을 내보내는 경우 `oidc.email_claim`을 설정하세요. |409| `/oauth/callback`이 "Sign-in could not be completed"를 표시함 | 이메일 도메인이 거부됨, id\_token 검증 실패, 또는 `email_verified`가 명시적으로 `false`이며 gateway는 항상 재정의 없이 거부함 | `allowed_email_domains`을 확인하고 IdP가 확인된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에서 이메일을 내보내는 경우 `oidc.email_claim`을 설정하세요. |

406| 로그: `token exchange failed request_id=<id>: id_token missing email claim` | IdP가 기본적으로 id\_token에 `email`을 포함하지 않음. 이 거부는 `allowed_email_domains`이 설정된 경우에만 발생함. 없으면 누락된 이메일이 이메일 없이 세션을 발행함 | IdP를 구성하여 id\_token에 `email`을 내보내도록 하세요. Okta: 사용자 정의 권한 부여 서버의 ID 토큰 클레임에 `email`을 추가하세요. Entra: 앱 등록에서 `email`을 선택적 클레임으로 추가하세요. PingFederate: `email`을 내보내는 OpenID Connect 정책을 활성화하세요. IdP가 userinfo 엔드포인트에서 `email`을 제공하지만 id\_token에 포함하지 않는 경우(예: Okta org 권한 부여 서버) `oidc.userinfo_fallback: true`를 설정하세요. |410| 로그: `token exchange failed request_id=<id>: id_token missing email claim` | IdP가 기본적으로 id\_token에 `email`을 포함하지 않음. 이 거부는 `allowed_email_domains`이 설정된 경우에만 발생함. 없으면 누락된 이메일이 이메일 없이 세션을 발행함 | IdP를 구성하여 id\_token에 `email`을 내보내도록 하세요. Okta: 사용자 정의 권한 부여 서버의 ID 토큰 클레임에 `email`을 추가하세요. Entra: 앱 등록에서 `email`을 선택적 클레임으로 추가하세요. PingFederate: `email`을 내보내는 OpenID Connect 정책을 활성화하세요. IdP가 userinfo 엔드포인트에서 `email`을 제공하지만 id\_token에 포함하지 않는 경우(예: Okta org 권한 부여 서버) `oidc.userinfo_fallback: true`를 설정하세요. |

407| 로그: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, 개발자가 매 `session.ttl_hours`마다 `Cloud gateway session expired`를 봄 | IdP가 새로 고침 토큰을 수락했지만 함께 id\_token을 반환하지 않았으므로 gateway가 IdP의 userinfo 엔드포인트에 사용자의 클레임을 요청했습니다. IdP가 새로 고쳐진 액세스 토큰을 거기서 거부했습니다. gateway가 `temporarily_unavailable`으로 응답하므로 Claude Code는 새로 고침 토큰을 유지하지만 세션을 갱신할 수 없습니다. v2.1.260 이전의 gateway 버전은 `(at …)` 세부 정보 없이 동일한 줄을 기록합니다. | [`oidc.scope_on_refresh: true`](/docs/ko/claude-apps-gateway-config#oidc)를 설정하세요. gateway v2.1.260 이상에서 사용 가능하므로 새로 고침 요청이 `openid`를 다시 요청합니다. Okta와 같은 일부 IdP는 요청할 때만 새로 고침 시 id\_token을 반환합니다. PingFederate에서는 대신 **Applications > OAuth > OpenID Connect Policy Management** 아래에서 **Return ID Token On Refresh Grant**를 활성화하세요. 키는 PingFederate의 동작을 변경하지 않습니다. 여전히 생략하는 다른 IdP의 경우 userinfo 엔드포인트가 새로 고침으로 발급된 액세스 토큰을 수락하는지 확인하세요. 임시 방편으로 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)를 높이세요. 프로비저닝 해제 트레이드오프는 [Identity provider setup](#identity-provider-setup)을 참조하세요. |411| 로그: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, 개발자가 매 `session.ttl_hours`마다 `Cloud gateway session expired`를 봄 | IdP가 새로 고침 토큰을 수락했지만 함께 id\_token을 반환하지 않았으므로 gateway가 IdP의 userinfo 엔드포인트에 사용자의 클레임을 요청했습니다. IdP가 새로 고쳐진 액세스 토큰을 거기서 거부했습니다. gateway가 `temporarily_unavailable`으로 응답하므로 Claude Code는 새로 고침 토큰을 유지하지만 세션을 갱신할 수 없습니다. v2.1.260 이전의 gateway 버전은 `(at …)` 세부 정보 없이 동일한 줄을 기록합니다. | [`oidc.scope_on_refresh: true`](/docs/ko/claude-apps-gateway-config#oidc)를 설정하세요. gateway v2.1.260 이상에서 사용 가능하므로 새로 고침 요청이 `openid`를 다시 요청합니다. Okta와 같은 일부 IdP는 요청할 때만 새로 고침 시 id\_token을 반환합니다. PingFederate에서는 대신 **Applications > OAuth > OpenID Connect Policy Management** 아래에서 **Return ID Token On Refresh Grant**를 활성화하세요. 키는 PingFederate의 동작을 변경하지 않습니다. 여전히 생략하는 다른 IdP의 경우 userinfo 엔드포인트가 새로 고침으로 발급된 액세스 토큰을 수락하는지 확인하세요. 임시 방편으로 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)를 높이세요. 프로비저닝 해제 트레이드오프는 [Identity provider setup](#identity-provider-setup)을 참조하세요. |

169 </Step>169 </Step>

170 170 

171 <Step title="PostgreSQL용 Amazon RDS 프로비저닝">171 <Step title="PostgreSQL용 Amazon RDS 프로비저닝">

172 인스턴스는 공개 주소가 없는 프라이빗 서브넷에서 실행되며 스토리지 암호화가 켜져 있습니다. 엔진 버전은 Postgres 16으로 고정되어 있으며, 이는 게이트웨이의 지원되는 최소값인 PostgreSQL 14를 충족하고 아래 매개변수 그룹 패밀리가 인스턴스가 실행하는 엔진 주 버전과 일치함을 보장합니다.172 인스턴스는 프라이빗 서브넷에서 Postgres 16을 실행하며, 공개 주소가 없고 스토리지 암호화가 켜져 있습니다.

173 173 

174 먼저 프라이빗 서브넷에 데이터베이스를 배치하는 서브넷 그룹과 `rds.force_ssl=1`을 사용하는 매개변수 그룹을 생성하여 서버가 일반 텍스트 연결을 거부하도록 합니다. 엔진 버전은 매개변수 그룹의 패밀리가 인스턴스가 실행하는 엔진 주 버전과 일치해야 하므로 한 번만 고정됩니다:174 먼저 프라이빗 서브넷에 데이터베이스를 배치하는 서브넷 그룹과 `rds.force_ssl=1`을 사용하는 매개변수 그룹을 생성하여 서버가 일반 텍스트 연결을 거부하도록 합니다. 엔진 버전은 매개변수 그룹의 패밀리가 인스턴스가 실행하는 엔진 주 버전과 일치해야 하므로 한 번만 고정됩니다:

175 175 

201 --no-publicly-accessible --storage-encrypted201 --no-publicly-accessible --storage-encrypted

202 ```202 ```

203 203 

204 리터럴 `--master-user-password` 인수는 명령이 실행되는 동안 프로세스 테이블 및 감사/EDR 로그에 표시됩니다. 공유 또는 모니터링되는 호스트에서는 번들의 `setup.sh`가 하는 방식처럼 `0600` 파일에서 `--cli-input-json`을 통해 암호를 전달하십시오.204 리터럴 `--master-user-password` 인수는 명령이 실행되는 동안 프로세스 테이블 및 감사/EDR 로그에 표시되며, 이는 비밀 단계의 참고 사항이 다루는 것과 동일한 노출입니다. 공유 또는 모니터링되는 호스트에서는 번들의 `setup.sh`가 하는 방식처럼 `0600` 파일에서 `--cli-input-json`을 통해 암호를 전달하십시오.

205 205 

206 인스턴스가 시작될 때까지 기다리십시오. 몇 분이 걸릴 수 있습니다. 그런 다음 프라이빗 엔드포인트를 읽고 게이트웨이가 사용할 연결 문자열을 조합하십시오:206 인스턴스가 시작될 때까지 기다리십시오. 몇 분이 걸릴 수 있습니다. 그런 다음 프라이빗 엔드포인트를 읽고 게이트웨이가 사용할 연결 문자열을 조합하십시오:

207 207 

220 <Step title="gateway.yaml 작성">220 <Step title="gateway.yaml 작성">

221 `upstreams` 블록은 `auth: {}`로 Bedrock을 가리키므로 게이트웨이는 ECS의 작업 역할 또는 EKS의 IRSA 역할에서 AWS 기본 자격 증명 체인을 통해 인증합니다. 모든 필드는 [구성 참조](/docs/ko/claude-apps-gateway-config)를 참조하십시오.221 `upstreams` 블록은 `auth: {}`로 Bedrock을 가리키므로 게이트웨이는 ECS의 작업 역할 또는 EKS의 IRSA 역할에서 AWS 기본 자격 증명 체인을 통해 인증합니다. 모든 필드는 [구성 참조](/docs/ko/claude-apps-gateway-config)를 참조하십시오.

222 222 

223 2개의 `listen` 필드는 게이트웨이 앞에 있는 것에 따라 다릅니다:223 2개의 `listen` 필드는 게이트웨이 앞단에 무엇이 있는지를 설명합니다:

224 224 

225 * `public_url`: 외부 `https://` 원점이며, 비루프백 바인드에 필수입니다. [listen 참조](/docs/ko/claude-apps-gateway-config#listen)를 참조하십시오. 게이트웨이는 IdP `redirect_uri`와 검색 문서를 이 값에서만 빌드하며, `X-Forwarded-*` 헤더에서는 빌드하지 않습니다.225 * `public_url`: 외부 `https://` 원점이며, 비루프백 바인드에 필수입니다. [`listen` 참조](/docs/ko/claude-apps-gateway-config#listen)를 참조하십시오. 게이트웨이는 IdP `redirect_uri`와 검색 문서를 이 값에서만 빌드하며, `X-Forwarded-*` 헤더에서는 빌드하지 않습니다.

226 * `trusted_proxies`: 프론트 엔드의 소스 범위입니다. 게이트웨이는 TCP 피어가 이 목록에 있을 때만 `X-Forwarded-For`를 준수하고, 신뢰할 수 있는 홉을 지나 체인을 걷습니다. 따라서 IP별 로그인 속도 제한 및 감사 이벤트는 로드 밸런서의 IP가 아닌 개발자 IP를 기록합니다.226 * `trusted_proxies`: 프론트 엔드의 소스 범위입니다. 게이트웨이는 TCP 피어가 이 목록에 있을 때만 `X-Forwarded-For`를 준수하고, 신뢰할 수 있는 홉을 지나 체인을 걷습니다. 따라서 IP별 로그인 속도 제한 및 감사 이벤트는 로드 밸런서의 IP가 아닌 개발자 IP를 기록합니다.

227 227 

228 두 트랙 모두에서 프론트 엔드는 직접 생성되거나 AWS Load Balancer Controller에 의해 생성되는 내부 ALB이며, ALB의 노드는 연결된 서브넷에서 주소를 가져오므로 `trusted_proxies`를 해당 서브넷의 CIDR로 설정하십시오. 이는 해당 서브넷의 모든 호스트를 프록시로 신뢰합니다. ALB의 수신 소스인 회사 CIDR이 이들과 겹치지 않도록 유지하고, 신뢰할 수 없는 워크로드와 서브넷을 공유하지 마십시오. 이들은 `X-Forwarded-For`를 통해 클라이언트 IP를 스푸핑할 수 있습니다.228 두 트랙 모두에서 프론트 엔드는 직접 생성되거나 AWS Load Balancer Controller에 의해 생성되는 내부 ALB이며, ALB의 노드는 연결된 서브넷에서 주소를 가져오므로 `trusted_proxies`를 해당 서브넷의 CIDR로 설정하십시오. 이는 해당 서브넷의 모든 호스트를 프록시로 신뢰합니다. ALB의 수신 소스인 회사 CIDR이 이들과 겹치지 않도록 유지하고, 신뢰할 수 없는 워크로드와 서브넷을 공유하지 마십시오. 이들은 `X-Forwarded-For`를 통해 클라이언트 IP를 스푸핑할 수 있습니다.

244 # Okta org 인증 서버는 이메일과 그룹을 생략하는 얇은 id_token을 반환합니다.244 # Okta org 인증 서버는 이메일과 그룹을 생략하는 얇은 id_token을 반환합니다.

245 # 게이트웨이는 /userinfo에서 이들을 채웁니다.245 # 게이트웨이는 /userinfo에서 이들을 채웁니다.

246 userinfo_fallback: true246 userinfo_fallback: true

247 # Okta는 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가 이를 허용할 때만 그룹을 내보냅니다.247 # Okta는 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가

248 # 이를 허용할 때만 그룹을 내보냅니다.

248 scopes: [openid, profile, email, offline_access, groups]249 scopes: [openid, profile, email, offline_access, groups]

249 250 

250 session:251 session:

251 jwt_secret: ${GATEWAY_JWT_SECRET} # EKS: ${file:/secrets/jwt-secret}252 jwt_secret: ${GATEWAY_JWT_SECRET} # EKS: ${file:/secrets/jwt-secret}

252 ttl_hours: 8 # 프로비저닝 해제 지연을 제한합니다. 더 엄격한 취소를 위해 1로 낮추십시오.253 ttl_hours: 8 # 프로비저닝 해제 지연을 제한합니다. 더 엄격한 취소를 위해

254 # 1에 가깝게 낮추십시오.

253 255 

254 store:256 store:

255 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}

256 # readiness_grace_seconds: 300 # RDS 장애 조치를 통해 상태 확인을 계속 통과합니다.258 # readiness_grace_seconds: 300 # RDS 장애 조치 중에도

259 # 상태 확인을 계속 통과합니다.

257 260 

258 upstreams:261 upstreams:

259 - provider: bedrock262 - provider: bedrock

260 region: <your-region> # IAM 정책의 ARN이 이를 포함하도록 $AWS_REGION과 일치합니다.263 region: <your-region> # IAM 정책의 ARN이 이를 포함하도록

261 auth: {} # AWS 기본 자격 증명 체인: ECS 작업 역할 또는 EKS의 IRSA264 # $AWS_REGION과 일치시킵니다.

265 auth: {} # AWS 기본 자격 증명 체인:

266 # ECS 작업 역할 또는 EKS의 IRSA

262 ```267 ```

263 268 

264 <Note>269 <Note>

307 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem312 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

308 ```313 ```

309 314 

310 ECR 리포지토리를 생성하고 Docker를 로그인하십시오. 불변 태그는 배포 단계가 고정하는 `<version>` 태그를 나중에 다른 이미지로 자동으로 다시 가리킬 수 없음을 의미합니다:315 ECR 저장소를 생성하고 Docker를 로그인하십시오. 불변 태그는 배포 단계가 고정하는 `<version>` 태그를 나중에 다른 이미지로 자동으로 다시 가리킬 수 없음을 의미합니다:

311 316 

312 ```bash theme={null}317 ```bash theme={null}

313 aws ecr create-repository --repository-name claude-gateway \318 aws ecr create-repository --repository-name claude-gateway \

396 401 

397 HTTPS 리스너를 추가합니다. `--ssl-policy`는 최신 TLS 하한을 고정합니다. 생략하면 여전히 TLS 1.0/1.1을 허용하는 레거시 `ELBSecurityPolicy-2016-08` 기본값으로 돌아갑니다.402 HTTPS 리스너를 추가합니다. `--ssl-policy`는 최신 TLS 하한을 고정합니다. 생략하면 여전히 TLS 1.0/1.1을 허용하는 레거시 `ELBSecurityPolicy-2016-08` 기본값으로 돌아갑니다.

398 403 

399 ALB는 기본적으로 60초 동안 데이터가 없는 연결을 닫습니다. 게이트웨이의 keepalive 핑은 스트림을 해당 기본값 내에 유지하므로 시간 초과를 높이면 핑 주기 위에 여유를 추가합니다. [문제 해결](#troubleshooting) 행에서 끊어진 스트림을 다룹니다. 아래 명령은 리스너를 추가하고 시간 초과를 높입니다:404 ALB는 기본적으로 60초 동안 데이터가 없는 연결을 닫습니다. 게이트웨이의 keepalive 핑은 스트림을 해당 기본값 내에 유지하므로 타임아웃을 높이면 핑 주기 위에 여유를 추가합니다. 끊어진 스트림에 대한 [문제 해결](#troubleshooting) 행에서 그 메커니즘과 이전 게이트웨이에 대해 다룹니다. 아래 명령은 리스너를 추가하고 타임아웃을 높입니다:

400 405 

401 ```bash theme={null}406 ```bash theme={null}

402 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \407 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \

420 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"425 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

421 ```426 ```

422 427 

423 60초 유예 기간은 콜드 작업이 이미지를 가져오고, 저장소에 연결하고, 첫 번째 상태 확인에 응답할 시간을 제공합니다. ECS가 배포에 대한 실패를 계산하기 시작하기 전입니다. 대상 그룹의 `GET /readyz`에 대한 상태 확인은 저장소에 도달할 수 있는지 확인하므로 Postgres에 도달할 수 없는 작업은 회전에 들어가지 않습니다. [중단 동작](/docs/ko/claude-apps-gateway-deploy#outage-behavior)에서 트레이드오프와 `/healthz` 대안을 참조하십시오.428 60초 유예 기간은 ECS가 배포에 대한 실패를 계산하기 시작하기 전에 콜드 작업이 이미지를 가져오고, 저장소에 연결하고, 첫 번째 상태 확인에 응답할 시간을 제공합니다.

429 

430 대상 그룹의 `GET /readyz`에 대한 상태 확인은 저장소에 도달할 수 있는지 확인하므로 Postgres에 도달할 수 없는 작업은 회전에 들어가지 않습니다. RDS 장애 조치와 같은 짧은 데이터베이스 중단 동안에도 작업이 상태 확인을 계속 통과하도록 하려면 [중단 동작](/docs/ko/claude-apps-gateway-deploy#outage-behavior)에 설명된 대로 `store.readiness_grace_seconds`를 설정하십시오. 해당 문서에서는 `/healthz` 대안도 다룹니다.

424 431 

425 작업은 공개 IP가 없는 프라이빗 서브넷에서 실행되므로 모든 이그레스(Bedrock, IdP, Secrets Manager, ECR, CloudWatch Logs로)는 NAT 게이트웨이를 통해 이동합니다. Bedrock 트래픽을 공개 경로에서 벗어나게 하려면 `bedrock-runtime` 인터페이스 VPC 엔드포인트를 생성하고 업스트림의 `base_url`을 가리키십시오. [Bedrock 업스트림 참조](/docs/ko/claude-apps-gateway-config#amazon-bedrock)에 표시됩니다. IdP는 여전히 인터넷 이그레스가 필요합니다.432 작업은 공개 IP가 없는 프라이빗 서브넷에서 실행되므로 모든 이그레스(Bedrock, IdP, Secrets Manager, ECR, CloudWatch Logs로)는 NAT 게이트웨이를 통해 이동합니다. Bedrock 트래픽을 공개 경로에서 벗어나게 하려면 `bedrock-runtime` 인터페이스 VPC 엔드포인트를 생성하고 업스트림의 `base_url`을 가리키십시오. [Bedrock 업스트림 참조](/docs/ko/claude-apps-gateway-config#amazon-bedrock)에 표시됩니다. IdP는 여전히 인터넷 이그레스가 필요합니다.

426 433 

471 </Step>478 </Step>

472 479 

473 <Step title="게이트웨이 URL을 개발자 머신에 푸시">480 <Step title="게이트웨이 URL을 개발자 머신에 푸시">

474 게이트웨이가 이제 실행 중이지만 개발자는 게이트웨이 URL이 머신에 있을 때까지 `/login`에서 도달할 수 없습니다. [관리형 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 설정하고 MDM을 통해 각 디바이스에 배포하십시오. 개발자가 수동으로 선택할 수 있는 로그인 선택기의 게이트웨이 옵션이 없습니다.481 게이트웨이가 이제 실행 중이지만 개발자는 게이트웨이 URL이 머신에 있을 때까지 `/login`에서 도달할 수 없습니다. MDM을 통해 각 디바이스에 배포하는 [관리형 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)에서 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 설정하십시오. 개발자가 수동으로 선택할 수 있는 로그인 선택기의 게이트웨이 옵션이 없습니다.

475 </Step>482 </Step>

476</Steps>483</Steps>

477 484 

442`claude --cloud` 및 `claude --teleport`는 claude.ai 계정으로 로그인해야 합니다. API 키로 인증하거나 저장된 계정 세부 정보가 오래된 경우 다음 중 하나가 표시됩니다.442`claude --cloud` 및 `claude --teleport`는 claude.ai 계정으로 로그인해야 합니다. API 키로 인증하거나 저장된 계정 세부 정보가 오래된 경우 다음 중 하나가 표시됩니다.

443 443 

444* `Unable to get organization UUID`444* `Unable to get organization UUID`

445* API 키 인증이 충분하지 않다는 메시지445* ``Cloud sessions need a claude.ai sign-in. Run `claude auth login` (or /login in a local session), then try again.``

446* 세션 ID 없이 `claude --teleport`를 실행할 때 세션 선택기에 표시되는 `Error loading Claude Code sessions`446* 세션 ID 없이 `claude --teleport`를 실행할 때 세션 선택기에 표시되는 `Error loading Claude Code sessions`

447 447 

448`/login`을 실행하여 claude.ai 계정으로 로그인한 다음 명령을 다시 시도하세요. 오류가 제공자의 이름을 지정하면 [오류 표](#errors-when-sending-to-a-cloud-session)를 참조하세요: 클라우드 세션을 타사 제공자를 통해 사용할 수 없습니다.448셸에서 [`claude auth login`](/docs/ko/cli-reference#cli-commands)을 실행하여 claude.ai 계정으로 로그인한 다음 명령을 다시 시도하세요. 실행 중인 세션 안에서는 `/login`이 같은 역할을 합니다. 오류가 대신 제공자의 이름을 표시하면 [오류 표](#errors-when-sending-to-a-cloud-session)를 참조하세요: 클라우드 세션을 타사 제공자를 통해 사용할 수 없습니다.

449 

450v2.1.274부터 v2.1.289까지는 로그인 메시지가 `Claude Code cloud sessions require authentication with a Claude.ai account. API key authentication is not sufficient. Please run /login to authenticate, or check your authentication status with /status.`로 표시되었습니다.

449 451 

450<h3 id="remote-control-session-expired-or-access-denied">452<h3 id="remote-control-session-expired-or-access-denied">

451 Remote Control 세션 만료 또는 액세스 거부453 Remote Control 세션 만료 또는 액세스 거부

31| `claude attach <id\|name>` | 이 터미널에서 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다. ID 대신 실행 중인 세션 이름의 일부를 전달하려면 Claude Code v2.1.290 이상이 필요합니다 | `claude attach 7c5dcf5d` |31| `claude attach <id\|name>` | 이 터미널에서 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다. ID 대신 실행 중인 세션 이름의 일부를 전달하려면 Claude Code v2.1.290 이상이 필요합니다 | `claude attach 7c5dcf5d` |

32| `claude auto-mode defaults` | 기본 제공 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다. `--label <prefix>`는 해당 접두사로 시작하는 레이블이 있는 규칙만 인쇄합니다(대소문자 구분 안 함). Claude Code v2.1.208 이상이 필요합니다 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 기본 제공 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다. `--label <prefix>`는 해당 접두사로 시작하는 레이블이 있는 규칙만 인쇄합니다(대소문자 구분 안 함). Claude Code v2.1.208 이상이 필요합니다 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | 사용자 설정 파일에서 `autoMode` 섹션을 제거하여 기본 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 구성을 복원합니다. 작성하기 전에 확인을 요청합니다. `-y`/`--yes`를 전달하여 프롬프트를 건너뜁니다. [관리형 설정](/docs/ko/server-managed-settings) 또는 `--settings` 플래그의 규칙은 여전히 적용됩니다. Claude Code v2.1.212 이상이 필요합니다. [기본값 및 유효한 구성 검사](/docs/ko/auto-mode-config#inspect-the-defaults-and-your-effective-config) 참조 | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | 사용자 설정 파일에서 `autoMode` 섹션을 제거하여 기본 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 구성을 복원합니다. 작성하기 전에 확인을 요청합니다. `-y`/`--yes`를 전달하여 프롬프트를 건너뜁니다. [관리형 설정](/docs/ko/server-managed-settings) 또는 `--settings` 플래그의 규칙은 여전히 적용됩니다. Claude Code v2.1.212 이상이 필요합니다. [기본값 및 유효한 구성 검사](/docs/ko/auto-mode-config#inspect-the-defaults-and-your-effective-config) 참조 | `claude auto-mode reset --yes` |

34| `claude daemon logs` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 로그 파일 `~/.claude/daemon.log`를 팔로우하며, `Ctrl+C`를 누를 때까지 새 줄이 들어오는 대로 인쇄합니다 | `claude daemon logs` |

35| `claude daemon run` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)를 이 터미널의 포그라운드에서 실행하고 로그를 인쇄합니다 | `claude daemon run` |

34| `claude daemon status` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 | `claude daemon status` |36| `claude daemon status` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 | `claude daemon status` |

35| `claude daemon stop --any` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)와 이를 호스팅하는 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 중인 상태로 두면 다음 감독자가 이들에 다시 연결됩니다. `--any`는 기본값인 온디맨드 감독자 중지를 확인합니다. 이를 사용하여 [응답하지 않는 감독자](/docs/ko/agent-view#agent-view-says-the-background-service-did-not-respond)에서 복구합니다 | `claude daemon stop --any --keep-workers` |37| `claude daemon stop --any` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)와 이를 호스팅하는 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 중인 상태로 두면 다음 감독자가 이들에 다시 연결됩니다. `--any`는 기본값인 온디맨드 감독자 중지를 확인합니다. 이를 사용하여 [응답하지 않는 감독자](/docs/ko/agent-view#agent-view-says-the-background-service-did-not-respond)에서 복구합니다 | `claude daemon stop --any --keep-workers` |

36| `claude doctor` | 세션을 시작하지 않고 터미널에서 읽기 전용 설치 및 설정 진단을 인쇄합니다. 설치 상태, 설정 파일 검증 오류 및 Remote Control 적격성을 포함합니다. 수정을 적용할 수도 있는 세션 내 설정 점검을 위해 [`/doctor`](/docs/ko/commands#all-commands)를 실행합니다 | `claude doctor` |38| `claude doctor` | 세션을 시작하지 않고 터미널에서 읽기 전용 설치 및 설정 진단을 인쇄합니다. 설치 상태, 설정 파일 검증 오류 및 Remote Control 적격성을 포함합니다. 수정을 적용할 수도 있는 세션 내 설정 점검을 위해 [`/doctor`](/docs/ko/commands#all-commands)를 실행합니다 | `claude doctor` |

1092실행 중인 데스크톱 앱의 버전을 보려면:1092실행 중인 데스크톱 앱의 버전을 보려면:

1093 1093 

1094* **macOS**: 메뉴 모음에서 **Claude**를 클릭한 다음 **About Claude**를 클릭합니다1094* **macOS**: 메뉴 모음에서 **Claude**를 클릭한 다음 **About Claude**를 클릭합니다

1095* **Windows**: **Help**를 클릭한 다음 **About**을 클릭합니다1095* **Windows**: **Help**를 클릭한 다음 **About Claude**를 클릭합니다

1096 1096 

1097버전 번호를 클릭하여 클립보드에 복사합니다.1097버전 번호를 클릭하여 클립보드에 복사합니다.

1098 1098 

92* **Cmd+S**로 스크린샷 또는 **Cmd+R**로 화면 녹화 저장 (창의 캡처 버튼 또는 단축키 사용, 파일은 Desktop에 저장됨)92* **Cmd+S**로 스크린샷 또는 **Cmd+R**로 화면 녹화 저장 (창의 캡처 버튼 또는 단축키 사용, 파일은 Desktop에 저장됨)

93* **Detach simulator**를 클릭하여 기기 스트리밍 중지 (종료하지 않음), 창을 **Attach simulator** 상태로 반환93* **Detach simulator**를 클릭하여 기기 스트리밍 중지 (종료하지 않음), 창을 **Attach simulator** 상태로 반환

94 94 

95시뮬레이터의 비디오 스트림을 조정하려면 창의 **Display** 메뉴를 엽니다. Mac에 부담이 되면 **Frame rate** 또는 **Resolution**을 낮춥니다. 두 설정 모두 창이 기기를 표시하는 방식을 변경하며, 앱 실행 방식은 변경하지 않습니다.95창에 **Display** 메뉴가 표시되면 이 메뉴를 사용하여 시뮬레이터의 비디오 스트림을 조정합니다. Mac에 부담이 되면 **Frame rate** 또는 **Resolution**을 낮춥니다. 두 설정 모두 창이 기기를 표시하는 방식을 변경하며, 앱 실행 방식은 변경하지 않습니다.

96 96 

97사용자와 Claude가 동일한 기기를 제어하므로 탭이 Claude가 보는 앱 상태를 변경합니다. Claude가 특정 화면을 확인하도록 하려면 탭하여 이동한 후 요청합니다. Claude가 기기를 제어하는 동안 창은 화면 위에 **Claude is using this device** 배지를 표시합니다. 배지가 사라질 때까지 탭을 기다려 결과가 입력이 아닌 앱을 반영하도록 합니다.97사용자와 Claude가 동일한 기기를 제어하므로 탭이 Claude가 보는 앱 상태를 변경합니다. Claude가 특정 화면을 확인하도록 하려면 탭하여 이동한 후 요청합니다. Claude가 기기를 제어하는 동안 창은 화면 위에 **Claude is using this device** 배지를 표시합니다. 배지가 사라질 때까지 탭을 기다려 결과가 입력이 아닌 앱을 반영하도록 합니다.

98 98 

354| `CLAUDE_CODE_PERFORCE_MODE` | Perforce 인식 쓰기 보호를 활성화하려면 `1`로 설정합니다. 설정하면 대상 파일에 소유자 쓰기 비트가 없을 경우 Edit, Write, NotebookEdit이 `p4 edit <file>` 힌트와 함께 실패합니다. Perforce는 동기화된 파일이 `p4 edit`으로 열릴 때까지 이 비트를 해제합니다. 이렇게 하면 Claude Code가 Perforce 변경 추적을 우회하지 못합니다 |354| `CLAUDE_CODE_PERFORCE_MODE` | Perforce 인식 쓰기 보호를 활성화하려면 `1`로 설정합니다. 설정하면 대상 파일에 소유자 쓰기 비트가 없을 경우 Edit, Write, NotebookEdit이 `p4 edit <file>` 힌트와 함께 실패합니다. Perforce는 동기화된 파일이 `p4 edit`으로 열릴 때까지 이 비트를 해제합니다. 이렇게 하면 Claude Code가 Perforce 변경 추적을 우회하지 못합니다 |

355| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉터리를 재정의합니다. 이름과 달리 캐시 자체가 아니라 상위 디렉터리를 설정합니다. 마켓플레이스와 플러그인 캐시는 이 경로 아래의 하위 디렉터리에 있습니다. 기본값은 `~/.claude/plugins`입니다 |355| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉터리를 재정의합니다. 이름과 달리 캐시 자체가 아니라 상위 디렉터리를 설정합니다. 마켓플레이스와 플러그인 캐시는 이 경로 아래의 하위 디렉터리에 있습니다. 기본값은 `~/.claude/plugins`입니다 |

356| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각각 [`--plugin-dir`](/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그와 같은 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로를 절대 경로로 지정하거나 `~`로 시작합니다. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)를 참조하세요 |356| `CLAUDE_CODE_PLUGIN_DIRS` | 세션에 로드할 플러그인 디렉터리로, 각각 [`--plugin-dir`](/docs/ko/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 플래그와 같은 방식으로 로드됩니다. 여러 경로는 Unix에서는 `:`, Windows에서는 `;`로 구분합니다. Claude Code는 상대 경로를 건너뛰므로 각 경로를 절대 경로로 지정하거나 `~`로 시작합니다. Claude Code v2.1.280 이상이 필요합니다. [한 세션에 플러그인 로드](/docs/ko/plugins/create#load-a-directory-or-archive-for-one-session)를 참조하세요 |

357| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | [mod](/docs/ko/plugins/mods/overview)의 파일이 변경될 때 Claude Code가 mod를 다시 로드할지 여부를 제어합니다. 다시 로드는 `--plugin-dir`로 디렉터리에서 로드한 mod에 적용되며, 대화형 세션에서는 기본적으로 켜져 있습니다. 비대화형 세션에서도 켜려면 `1`로, 모든 세션에서 끄려면 `0`으로 설정합니다. Claude Code v2.1.287 이상이 필요합니다. [mod 설정 및 환경 변수](/docs/ko/plugins/mods/reference#settings-and-environment-variables)를 참조하세요 |

357| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치기 위한 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결의 경우 이 값을 늘립니다. [Git clone timed out](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)을 참조하세요 |358| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인 마켓플레이스를 복제하거나 새로 고치기 위한 타임아웃(밀리초)입니다(기본값: 120000). 큰 저장소나 느린 네트워크 연결의 경우 이 값을 늘립니다. [Git clone timed out](/docs/ko/plugins/troubleshooting#git-clone-timed-out-after-120s)을 참조하세요 |

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 다시 복제를 시도하지 않고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 다시 복제해도 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |359| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 마켓플레이스 새로 고침이 원격에 연결하거나 인증할 수 없을 때 다시 복제를 시도하지 않고 기존 마켓플레이스 체크아웃을 계속 사용하려면 `1`로 설정합니다. 다시 복제해도 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/docs/ko/plugins/troubleshooting#marketplace-updates-keep-failing-offline)를 참조하세요 |

359| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 약식 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 모든 환경에서 유용합니다 |360| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 약식 소스를 SSH 대신 HTTPS로 복제하려면 `1`로 설정합니다. 플러그인 설치 및 업데이트와 `/plugin marketplace add` 및 `update`에 적용됩니다. CI 러너, 컨테이너 또는 `github.com`용 SSH 키가 구성되지 않은 모든 환경에서 유용합니다 |

197| `Cloud sessions cannot be created from a --restricted session` | [명령줄 오류](#cloud-sessions-cannot-be-created-from-a-restricted-session) |197| `Cloud sessions cannot be created from a --restricted session` | [명령줄 오류](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

198| `Cloud sessions are disabled by your organization's policy` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |198| `Cloud sessions are disabled by your organization's policy` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |

199| `Couldn't verify your organization's policy for cloud sessions` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |199| `Couldn't verify your organization's policy for cloud sessions` | [명령줄 오류](#cloud-sessions-are-disabled-by-your-organizations-policy) |

200| `Cloud sessions need a claude.ai sign-in` | [조직 UUID를 가져올 수 없음](/docs/ko/claude-code-on-the-web#unable-to-get-organization-uuid) |

200| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#the-json-schema-value-is-not-a-valid-json-schema) |201| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#the-json-schema-value-is-not-a-valid-json-schema) |

201| `Error: Invalid --agents configuration:` | [명령줄 오류](#invalid-agents-configuration) |202| `Error: Invalid --agents configuration:` | [명령줄 오류](#invalid-agents-configuration) |

202| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [명령줄 오류](#invalid-agents-configuration) |203| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [명령줄 오류](#invalid-agents-configuration) |

387* 요청 중간에 컴퓨터가 절전 모드로 전환되어 끊어졌다고 Claude Code가 감지한 연결. Claude Code는 이를 위의 규칙에 따른 끊어진 연결로 계산합니다. 재시도 레이블이 특정 이유를 명시하면 `Connection lost while your computer was asleep`로 표시되며, Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 턴이 종료되면 메시지는 `Your computer went to sleep before a response was produced`로 표시됩니다.388* 요청 중간에 컴퓨터가 절전 모드로 전환되어 끊어졌다고 Claude Code가 감지한 연결. Claude Code는 이를 위의 규칙에 따른 끊어진 연결로 계산합니다. 재시도 레이블이 특정 이유를 명시하면 `Connection lost while your computer was asleep`로 표시되며, Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 턴이 종료되면 메시지는 `Your computer went to sleep before a response was produced`로 표시됩니다.

388* 응답 헤더는 도착했지만 Claude의 응답이 도착하지 않았거나, Claude가 사고를 마쳤지만 텍스트나 도구 호출을 시작하지 않은 경우의 정체된 응답 스트림: Claude Code는 정체된 연결을 중단하고 위의 10회 시도 예산 외에 최대 1회까지 요청을 다시 발행합니다. Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 응답이 두 번째로 정체되면 Claude Code는 `The response stalled before a response was produced`로 턴을 종료합니다.389* 응답 헤더는 도착했지만 Claude의 응답이 도착하지 않았거나, Claude가 사고를 마쳤지만 텍스트나 도구 호출을 시작하지 않은 경우의 정체된 응답 스트림: Claude Code는 정체된 연결을 중단하고 위의 10회 시도 예산 외에 최대 1회까지 요청을 다시 발행합니다. Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 응답이 두 번째로 정체되면 Claude Code는 `The response stalled before a response was produced`로 턴을 종료합니다.

389* API가 [첫 바이트 기한이 실행되는](/docs/ko/network-config#streaming-idle-watchdogs) 연결에서 응답 헤더로 응답하지 않는 스트리밍 요청: Claude Code는 기한에서 중단하고 재시도 예산 내에서 모델 요청당 최대 1회까지 다시 보낸 후, 해당 시도도 응답이 없으면 [No response from API](#no-response-from-api)로 턴을 종료합니다. 다른 연결에서는 요청이 `API_TIMEOUT_MS`를 기다립니다. `CLAUDE_CODE_RETRY_WATCHDOG`를 설정하면 1회 재시도 제한이 적용되지 않습니다.390* API가 [첫 바이트 기한이 실행되는](/docs/ko/network-config#streaming-idle-watchdogs) 연결에서 응답 헤더로 응답하지 않는 스트리밍 요청: Claude Code는 기한에서 중단하고 재시도 예산 내에서 모델 요청당 최대 1회까지 다시 보낸 후, 해당 시도도 응답이 없으면 [No response from API](#no-response-from-api)로 턴을 종료합니다. 다른 연결에서는 요청이 `API_TIMEOUT_MS`를 기다립니다. `CLAUDE_CODE_RETRY_WATCHDOG`를 설정하면 1회 재시도 제한이 적용되지 않습니다.

391* Claude가 사고를 마치거나 텍스트 또는 도구 호출을 시작하기 전에 API의 출력 콘텐츠 필터가 중단한 스트리밍 응답. Claude Code는 재시도 예산 내에서 요청을 한 번 다시 보내고, 필터가 두 번째 응답도 중단하면 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)를 표시합니다.

390* 임시 429 스로틀, 하지만 게이트웨이의 지출 한도 `429`는 아닙니다. 이는 스로틀이 아닙니다. [Spend limit reached](#spend-limit-reached)를 참조하세요.392* 임시 429 스로틀, 하지만 게이트웨이의 지출 한도 `429`는 아닙니다. 이는 스로틀이 아닙니다. [Spend limit reached](#spend-limit-reached)를 참조하세요.

391 * claude.ai 구독으로 로그인한 경우, 여기에는 플랜의 할당량 헤더를 전달하지 않는 429 스로틀이 포함됩니다. v2.1.199 이전에는 Claude Code가 API 키 및 Enterprise 로그인에 대해서만 해당 스로틀을 재시도했습니다.393 * claude.ai 구독으로 로그인한 경우, 여기에는 플랜의 할당량 헤더를 전달하지 않는 429 스로틀이 포함됩니다. v2.1.199 이전에는 Claude Code가 API 키 및 Enterprise 로그인에 대해서만 해당 스로틀을 재시도했습니다.

392* 입력 더하기 `max_tokens`이 컨텍스트 한도를 초과하기 때문에 거부된 요청. 변경하지 않고 다시 보내면 같은 방식으로 실패하므로 Claude Code는 감소된 `max_tokens`으로 재시도하고, 두 가지 경우에 재시도를 중지하고 대신 압축합니다:394* 입력 더하기 `max_tokens`이 컨텍스트 한도를 초과하기 때문에 거부된 요청. 변경하지 않고 다시 보내면 같은 방식으로 실패하므로 Claude Code는 감소된 `max_tokens`으로 재시도하고, 두 가지 경우에 재시도를 중지하고 대신 압축합니다:

405* [Amazon Bedrock streaming response with an unexpected content-type](#bedrock-streaming-response-has-an-unexpected-content-type), 게이트웨이 또는 프록시가 응답을 다시 쓰면 재시도도 같은 방식으로 다시 쓸 것이기 때문입니다. Claude Code v2.1.208 이상이 필요합니다.407* [Amazon Bedrock streaming response with an unexpected content-type](#bedrock-streaming-response-has-an-unexpected-content-type), 게이트웨이 또는 프록시가 응답을 다시 쓰면 재시도도 같은 방식으로 다시 쓸 것이기 때문입니다. Claude Code v2.1.208 이상이 필요합니다.

406* 실패한 스트리밍 요청의 비스트리밍 재시도가 성공 상태를 받지만 [no Claude API message in the body](#api-returned-an-empty-or-malformed-response). Claude Code는 해당 오류로 턴을 종료합니다.408* 실패한 스트리밍 요청의 비스트리밍 재시도가 성공 상태를 받지만 [no Claude API message in the body](#api-returned-an-empty-or-malformed-response). Claude Code는 해당 오류로 턴을 종료합니다.

407* 조직의 정책 검사가 거부한 요청, 이는 거부 메시지를 전달하는 `API Error:` 줄로 표시됩니다. 조직의 관리자는 Claude Enterprise 기능인 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)로 검사를 설정하고, 메시지는 구성한 지침으로 끝나거나 기본적으로 관리자에게 연락하도록 안내합니다. Claude Code는 거부가 모델이 아닌 요청의 내용에 관한 것이므로 거부된 요청을 동일한 모델이나 [폴백 모델](/docs/ko/model-config#fallback-model-chains)로 다시 보내지 않습니다. v2.1.239 이전에는 Claude Code가 거부를 표시하기 전에 거부된 요청을 스트리밍 없이 또는 구성된 폴백 모델에서 다시 보낼 수 있었습니다.409* 조직의 정책 검사가 거부한 요청, 이는 거부 메시지를 전달하는 `API Error:` 줄로 표시됩니다. 조직의 관리자는 Claude Enterprise 기능인 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)로 검사를 설정하고, 메시지는 구성한 지침으로 끝나거나 기본적으로 관리자에게 연락하도록 안내합니다. Claude Code는 거부가 모델이 아닌 요청의 내용에 관한 것이므로 거부된 요청을 동일한 모델이나 [폴백 모델](/docs/ko/model-config#fallback-model-chains)로 다시 보내지 않습니다. v2.1.239 이전에는 Claude Code가 거부를 표시하기 전에 거부된 요청을 스트리밍 없이 또는 구성된 폴백 모델에서 다시 보낼 수 있었습니다.

408* API의 출력 콘텐츠 필터가 차단한 응답. Claude Code는 즉시 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)를 표시하며 해당 요청을 재시도하거나 다시 보내지 않습니다.

409 410 

410<h3 id="what-you-see-while-claude-code-retries-or-waits">411<h3 id="what-you-see-while-claude-code-retries-or-waits">

411 Claude Code가 재시도하거나 대기하는 동안 보는 것412 Claude Code가 재시도하거나 대기하는 동안 보는 것

2905API Error: Output blocked by content filtering policy2906API Error: Output blocked by content filtering policy

2906```2907```

2907 2908 

2908Claude Code는 차단이 도착하는 즉시 오류를 표시하고 해당 요청을 종료합니다. 요청을 재시도하거나, 스트리밍 없이 다시 보내거나, [폴백 모델](/docs/ko/model-config#fallback-model-chains)로 전환하지 않습니다. v2.1.285 이전에는 Claude Code가 차단된 요청을 다시 보내고 재시도할 수 있었으며, 때로는 몇 분 동안 그렇게 한 후에야 오류를 표시했습니다.

2909 

2910**할 일:**2909**할 일:**

2911 2910 

2912* 마지막 메시지를 다르게 표현하거나 다른 접근 방식을 취합니다.2911* 마지막 메시지를 다르게 표현하거나 다른 접근 방식을 취합니다.

733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

734```734```

735 735 

736이 에이전트는 `my-plugin:security-reviewer`로 이름 지정되고, 사용자는 `@agent-my-plugin:security-reviewer`로 [명시적으로 호출](/docs/ko/sub-agents#invoke-subagents-explicitly)할 수 있습니다. 이름 형식은 `<plugin>:<name>`이며, `<name>`은 frontmatter에서 오거나 없을 때 파일 이름에서 옵니다.736이 에이전트는 `my-plugin:security-reviewer`로 이름 지정되고, 사용자는 `@agent-my-plugin:security-reviewer`로 [명시적으로 호출](/docs/ko/sub-agents#invoke-subagents-explicitly)할 수 있습니다. 이름 형식은 `<plugin>:<name>`이며, `<name>`은 frontmatter `name` 필드에서 오거나, 해당 필드가 없을 때 파일 이름에서 옵니다.

737 737 

738`agents` manifest 키는 `agents/` 스캔을 대체합니다.738`agents` manifest 키는 `agents/` 스캔을 대체합니다.

739 739 

428 428 

429| 요소 | 그리는 내용 | 사용 위치 |429| 요소 | 그리는 내용 | 사용 위치 |

430| :- | :- | :- |430| :- | :- | :- |

431| `Box` | flex 컨테이너입니다. `flexDirection`, `columnGap`, `padding`, `borderStyle`, `width` 같은 레이아웃 prop을 받습니다. | 모든 곳 |431| `Box` | flex 컨테이너입니다. `flexDirection`, `columnGap`, `padding`, [`borderStyle`](/docs/ko/plugins/mods/reference#box-border-styles), `width` 같은 레이아웃 prop을 받습니다. | 모든 곳 |

432| `Text` | 스타일이 적용된 텍스트입니다. `color`, `bold`, `dimColor`, `italic`, `wrap`을 받습니다. `color`는 테마 키 또는 `'red'` 같은 색상입니다. `wrap`은 `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, `'truncate-end'` 중 하나입니다. | 모든 곳 |432| `Text` | 스타일이 적용된 텍스트입니다. `color`, `bold`, `dimColor`, `italic`, `wrap`을 받습니다. `color`는 테마 키 또는 `'red'` 같은 색상입니다. `wrap`은 `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, `'truncate-end'` 중 하나입니다. | 모든 곳 |

433| `Button` | `onPress`를 호출하는 컨트롤 | 모든 곳 |433| `Button` | `onPress`를 호출하는 컨트롤 | 모든 곳 |

434| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |434| `Link`, `Code`, `Markdown` | `href`와 선택적 `label`을 갖는 링크, 코드 블록, 그리고 Claude의 응답과 같은 방식으로 서식이 지정된 텍스트입니다. `Markdown`은 내용을 `children`이 아닌 `text` prop으로 받으며, `onLinkPress`를 전달할 때는 `key`가 필요합니다. | 모든 곳 |

563많은 창은 텍스트 필드 아래에 목록이 있는 형태입니다. 이 섹션의 예시는 메모 창입니다. 메모를 입력하고 Enter를 눌러 추가하며, 각 메모에는 메모를 삭제하는 `x` 버튼이 있습니다. 메모 두 개를 추가하면 터미널은 창을 다음과 같이 그립니다.563많은 창은 텍스트 필드 아래에 목록이 있는 형태입니다. 이 섹션의 예시는 메모 창입니다. 메모를 입력하고 Enter를 눌러 추가하며, 각 메모에는 메모를 삭제하는 `x` 버튼이 있습니다. 메모 두 개를 추가하면 터미널은 창을 다음과 같이 그립니다.

564 564 

565```text theme={null}565```text theme={null}

566╭──────────────────────────────────────────────────────────╮566╭────────────────────────────────────────────────────────✕─╮

567│ Note: Type a note and press Enter ⏎ add ✕ │567│ Note: Type a note and press Enter ⏎ add │

568│ x buy milk │568│ x buy milk │

569│ x call bob │569│ x call bob │

570╰──────────────────────────────────────────────────────────╯570╰──────────────────────────────────────────────────────────╯

571```571```

572 572 

573위쪽 테두리의 `✕`는 창을 닫기 위한 Claude Code 자체의 표시입니다.

574 

573이 예시는 다음 기법을 사용합니다.575이 예시는 다음 기법을 사용합니다.

574 576 

575* **입력 받기**: `Input`은 사용자가 Enter를 누르면 필드의 텍스트로 `onSubmit(value)`를 호출하고, 변경이 있을 때마다 `onInput(value)`를 호출합니다577* **입력 받기**: `Input`은 사용자가 Enter를 누르면 필드의 텍스트로 `onSubmit(value)`를 호출하고, 변경이 있을 때마다 `onInput(value)`를 호출합니다

242트리를 해당 지점에 맞추려면 훅에서 다음 prop을 읽습니다.242트리를 해당 지점에 맞추려면 훅에서 다음 prop을 읽습니다.

243 243 

244* **`Pane` 또는 밴드의 너비**: `e.props.bodyColumns`에 맞춰 그립니다244* **`Pane` 또는 밴드의 너비**: `e.props.bodyColumns`에 맞춰 그립니다

245* **트랜스크립트 옆에 있는 `Pane`의 높이**: `e.props.placement`가 `'dock'`인 경우 `e.props.scroll.bodyRows`는 창이 가진 행 수입니다245* **트랜스크립트 옆에 있는 `Pane`의 높이**: `e.props.placement`가 `'dock'`인 경우 `e.props.scroll.bodyRows`는 창이 트리에 제공하는 행 수입니다

246* **프롬프트 위에 있는 `Pane`의 높이**: `e.props.placement`가 `'inline'`인 경우 창은 트리에 맞춰 한도까지 커지며, `bodyRows`가 그 한도입니다. [`$.ui.open`의 `rows` 필드](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)로 다른 한도를 요청할 수 있습니다.246* **프롬프트 위에 있는 `Pane`의 높이**: `e.props.placement`가 `'inline'`인 경우 창은 트리에 맞춰 한도까지 커지며, `bodyRows`가 그 한도입니다. [`$.ui.open`의 `rows` 필드](/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)로 다른 한도를 요청할 수 있습니다.

247 247 

248창보다 높은 트리는 전체가 하나로 스크롤됩니다.248창보다 높은 트리는 전체가 하나로 스크롤됩니다.

255 255 

256| 요소 | 주요 prop | 터미널 | 데스크톱 |256| 요소 | 주요 prop | 터미널 | 데스크톱 |

257| :- | :- | :-: | :-: |257| :- | :- | :-: | :-: |

258| [`Box`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex 레이아웃, `gap`, `padding`, `margin`, `width`, `height`, `borderStyle`, `backgroundColor`, `position`, `hover` | ✓ | ✓ |258| [`Box`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex 레이아웃, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ |

259| [`Text`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |259| [`Text`](/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |

260| [`Button`](/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |260| [`Button`](/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |

261| `Link` | `href`, `label` | ✓ | ✓ |261| `Link` | `href`, `label` | ✓ | ✓ |

270 270 

271`Button`에 대한 추가 규칙: `action`은 Claude Code 자체의 [키보드 단축키 액션](/docs/ko/keybindings) 중 하나를 지정하며, 해당 액션에 대한 사용자의 바인딩이 코드(chord) 또는 수정자 키 조합인 경우 그 바인딩으로 버튼이 눌립니다. 밴드에 있는 버튼의 숫자 `hotkey`는 사용자가 빈 프롬프트에 해당 숫자만 입력하고 잠시 멈출 때도 실행됩니다. 하나의 그리기에서 두 버튼이 동일한 `hotkey`를 지정하면 나중의 버튼이 이를 가져갑니다. `autoFocus`는 모든 컨트롤에서 `true`만 허용하므로, 이를 끄려면 해당 prop을 생략하십시오.271`Button`에 대한 추가 규칙: `action`은 Claude Code 자체의 [키보드 단축키 액션](/docs/ko/keybindings) 중 하나를 지정하며, 해당 액션에 대한 사용자의 바인딩이 코드(chord) 또는 수정자 키 조합인 경우 그 바인딩으로 버튼이 눌립니다. 밴드에 있는 버튼의 숫자 `hotkey`는 사용자가 빈 프롬프트에 해당 숫자만 입력하고 잠시 멈출 때도 실행됩니다. 하나의 그리기에서 두 버튼이 동일한 `hotkey`를 지정하면 나중의 버튼이 이를 가져갑니다. `autoFocus`는 모든 컨트롤에서 `true`만 허용하므로, 이를 끄려면 해당 prop을 생략하십시오.

272 272 

273<h3 id="box-border-styles">

274 `Box` 테두리 스타일

275</h3>

276 

277`Box` 주위에 테두리를 그리려면 `borderStyle: 'round'`처럼 `borderStyle`을 다음 이름 중 하나로 설정하십시오. 각 행은 해당 이름에 대해 터미널이 그리는 내용을 설명하고 테두리의 위쪽 가장자리를 보여 줍니다.

278 

279| `borderStyle` | 터미널이 그리는 내용 | 위쪽 가장자리 |

280| :- | :- | :- |

281| `'single'` | 모서리가 각진 가는 선 | `┌──┐` |

282| `'double'` | 이중선 | `╔══╗` |

283| `'round'` | 모서리가 둥근 가는 선 | `╭──╮` |

284| `'bold'` | 굵은 선 | `┏━━┓` |

285| `'singleDouble'` | 위아래는 가는 선, 양옆은 이중선 | `╓──╖` |

286| `'doubleSingle'` | 위아래는 이중선, 양옆은 가는 선 | `╒══╕` |

287| `'classic'` | ASCII 문자 `+`, `-`, `\|` | `+--+` |

288| `'arrow'` | `Box` 안쪽을 가리키는 화살표 | `↘↓↓↙` |

289| `'dashed'` | 모서리가 비어 있는 점선 | `╌╌` |

290| `'quote'` | 왼쪽에 세로로 이어지는 막대 `▎`와 나머지 세 면의 빈 셀 | 빈칸 |

291 

292`borderStyle`에 `'rounded'`처럼 그 밖의 이름을 지정한 `Box`는 테두리 없이 그려집니다.

293 

273<h2 id="limits">294<h2 id="limits">

274 제한295 제한

275</h2>296</h2>

17 17 

18 * **범위, 캐시 및 우선순위가 작동하는 방식**: [플러그인 로딩 참조](/docs/ko/plugins/loading)를 읽습니다.18 * **범위, 캐시 및 우선순위가 작동하는 방식**: [플러그인 로딩 참조](/docs/ko/plugins/loading)를 읽습니다.

19 * **플래그, 필드 또는 명령 조회**: [플러그인 명령 참조](/docs/ko/plugins/cli-reference), [매니페스트 참조](/docs/ko/plugins/manifest-reference) 또는 [마켓플레이스 참조](/docs/ko/plugins/marketplace-reference)를 사용합니다.19 * **플래그, 필드 또는 명령 조회**: [플러그인 명령 참조](/docs/ko/plugins/cli-reference), [매니페스트 참조](/docs/ko/plugins/manifest-reference) 또는 [마켓플레이스 참조](/docs/ko/plugins/marketplace-reference)를 사용합니다.

20 * **`hooks module not loaded` 또는 `hooks module did not load` 메시지**: 해당 플러그인은 [mod](/docs/ko/plugins/mods/overview)이므로 [mod가 로드되지 않음](/docs/ko/plugins/mods/troubleshoot#the-mod-doesn’t-load)을 읽습니다.

20</Note>21</Note>

21 22 

22본 페이지에서 본 정확한 메시지를 검색합니다. 각 메시지는 이를 생성하는 단계 아래에 나열되며, 이는 항상 실행한 명령이 아닙니다. 예를 들어, 마켓플레이스가 누락되어 설치가 실패할 수 있으므로 해당 메시지는 [마켓플레이스 추가](#add-a-marketplace) 아래에 있습니다.23본 페이지에서 본 정확한 메시지를 검색합니다. 각 메시지는 이를 생성하는 단계 아래에 나열되며, 이는 항상 실행한 명령이 아닙니다. 예를 들어, 마켓플레이스가 누락되어 설치가 실패할 수 있으므로 해당 메시지는 [마켓플레이스 추가](#add-a-marketplace) 아래에 있습니다.

43 <Step title="관리 콘솔 열기">43 <Step title="관리 콘솔 열기">

44 claude.ai 콘솔에서 [**조직 설정 > Claude Code > 관리형 설정**](https://claude.ai/admin-settings/claude-code)으로 이동합니다.44 claude.ai 콘솔에서 [**조직 설정 > Claude Code > 관리형 설정**](https://claude.ai/admin-settings/claude-code)으로 이동합니다.

45 45 

46 링크가 Claude Code 페이지 대신 다른 조직 설정 페이지로 리디렉션되면 계정에 필요한 역할이 없습니다. Admin 및 Owner가 아닌 기타 역할은 관리형 설정을 보거나 편집할 수 없으므로 조직의 Owner 또는 Primary Owner에게 변경을 요청하십시오. [액세스 제어](#access-control)를 참조하십시오.46 Team 또는 Enterprise 조직에서 페이지에 액세스 권한이 없다고 표시되면 [Owner 또는 Primary Owner](#access-control)에게 변경을 요청하십시오.

47 </Step>47 </Step>

48 48 

49 <Step title="설정 정의">49 <Step title="설정 정의">

83* 터미널: `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`. Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, 표의 경우는 제외됩니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.83* 터미널: `claude --continue`, `claude --resume <session-id>` 또는 이름이 한 세션과 일치할 때 `-p` 없이 `claude --resume <name>`. Claude Code는 세션이 있던 권한 모드를 복원합니다. 단, 표의 경우는 제외됩니다. `--permission-mode` 또는 `--dangerously-skip-permissions`를 전달하여 복원된 모드를 재정의합니다.

84* 비대화형: `claude -p --resume` 또는 `claude -p --continue`. Claude Code는 새로운 `claude -p` 실행이 시작될 권한 모드로 실행을 시작합니다. 단, 계획 모드에서 종료된 세션은 [아래 조건](#resume-in-plan-mode-with-p)에서 계획 모드로 재개됩니다.84* 비대화형: `claude -p --resume` 또는 `claude -p --continue`. Claude Code는 새로운 `claude -p` 실행이 시작될 권한 모드로 실행을 시작합니다. 단, 계획 모드에서 종료된 세션은 [아래 조건](#resume-in-plan-mode-with-p)에서 계획 모드로 재개됩니다.

85* VS Code: 확장의 대화 패널입니다. 표는 계획 모드에서 종료된 대화만 다룹니다. 나머지는 [과거 대화 재개](/docs/ko/vs-code#resume-past-conversations)를 참조하세요.85* VS Code: 확장의 대화 패널입니다. 표는 계획 모드에서 종료된 대화만 다룹니다. 나머지는 [과거 대화 재개](/docs/ko/vs-code#resume-past-conversations)를 참조하세요.

86* 시작 시 세션 선택기: `claude --resume` 단독, `claude --from-pr` 또는 이름이 여러 세션과 일치할 때 [세션 선택기](#use-the-session-picker)에서 선택한 세션입니다. Claude Code는 저장된 권한 모드를 복원하지 않습니다. 동일한 명령줄에서 새 세션을 시작할 권한 모드로 세션을 시작합니다.86* 시작 시 세션 선택기: `claude --resume` 단독, `claude --from-pr` 또는 여러 세션과 일치하는 이름 중 어느 방법으로 열었든 [세션 선택기](#use-the-session-picker)에서 선택한 세션입니다. Claude Code는 동일한 명령줄에서 새 세션을 시작할 권한 모드로 세션을 시작합니다. 단, 플랜 모드에서 종료된 세션은 `--permission-mode`, `--dangerously-skip-permissions` 또는 `--fork-session`을 전달하지 않는 한 플랜 모드로 재개됩니다. 그 외의 저장된 권한 모드는 복원되지 않습니다.

87* 세션 내 `/resume`(인수 있음 또는 없음): Claude Code는 저장된 권한 모드를 복원하지 않습니다. 전환하는 대화는 현재 세션이 있는 권한 모드에서 계속됩니다.87* 세션 내 `/resume`(인수 있음 또는 없음): 전환하는 대화는 현재 세션이 있는 권한 모드에서 계속됩니다. 단, 플랜 모드에서 종료된 대화는 `--permission-mode` 또는 `--dangerously-skip-permissions`로 Claude Code를 시작했더라도 플랜 모드로 재개됩니다. 해당 대화가 이번 Claude Code 실행에서 이미 열린 적이 있다면(예: 처음 시작한 대화나 `/clear` 또는 `/resume`으로 떠난 대화) 대신 현재 권한 모드에서 계속됩니다.

88 88 

89비대화형 및 VS Code 경로에서 계획 모드 복원은 Claude Code v2.1.246 이상이 필요합니다. 각 행은 세션이 종료된 권한 모드, 재개하는 터미널, 비대화형 및 VS Code 경로 중 어느 것인지, 그리고 Claude Code가 재개된 세션을 시작하는 권한 모드를 나타냅니다.89비대화형 및 VS Code 경로에서 계획 모드 복원은 Claude Code v2.1.246 이상이 필요합니다. 각 행은 세션이 종료된 권한 모드, 재개하는 터미널, 비대화형 및 VS Code 경로 중 어느 것인지, 그리고 Claude Code가 재개된 세션을 시작하는 권한 모드를 나타냅니다.

90 90 

91| 세션이 종료된 모드 | 재개 방식 | 재개 후 권한 모드 |91| 세션이 종료된 모드 | 재개 방식 | 재개 후 권한 모드 |

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | 터미널 | 새 세션이 시작될 권한 모드입니다. [권한을 다시 우회](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)하려면 시작 시 해당 플래그 중 하나 또는 [사용자, `--settings` 또는 관리 설정](/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`로 활성화합니다 |93| `bypassPermissions` | 터미널 | 새 세션이 시작될 권한 모드입니다. [권한을 다시 우회](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)하려면 시작 시 해당 플래그 중 하나 또는 [사용자, `--settings` 또는 관리 설정](/docs/ko/settings-reference#permissions-defaultmode)의 `permissions.defaultMode: "bypassPermissions"`로 활성화합니다 |

94| `plan` | 터미널 | 새 세션이 시작될 권한 모드입니다 |94| `plan` | 터미널 | 플랜 모드입니다. `--fork-session`을 사용하면 새 세션이 시작될 권한 모드입니다 |

95| `auto` | 터미널 | `auto`(계정이 여전히 [자동 모드 요구 사항](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 충족하는 경우에만) |95| `auto` | 터미널 | `auto`(계정이 여전히 [자동 모드 요구 사항](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)을 충족하는 경우에만) |

96| Manual | 터미널 | 새 세션이 [기본 제공 기본값](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 자동 모드로 시작될 때 수동입니다. 설정 파일의 `defaultMode`가 [적용](/docs/ko/permission-modes#which-mode-a-session-starts-in)되면 Claude Code는 재개된 세션을 해당 모드로 시작합니다 |96| Manual | 터미널 | 새 세션이 [기본 제공 기본값](/docs/ko/permission-modes#which-mode-a-session-starts-in)에서 자동 모드로 시작될 때 수동입니다. 설정 파일의 `defaultMode`가 [적용](/docs/ko/permission-modes#which-mode-a-session-starts-in)되면 Claude Code는 재개된 세션을 해당 모드로 시작합니다 |

97| `plan` | 비대화형([아래 조건](#resume-in-plan-mode-with-p)에서) | 계획 모드 |97| `plan` | 비대화형([아래 조건](#resume-in-plan-mode-with-p)에서) | 계획 모드 |

310 310 

311| 필드 | 필수 | 설명 |311| 필드 | 필수 | 설명 |

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | 예 | `code-reviewer` 또는 `reviewer-v2`와 같은 고유 식별자. [Hooks](/docs/ko/hooks#subagentstart)는 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다. 이름은 `:`를 포함할 수 없습니다. `:`는 `my-plugin:reviewer`와 같은 [플러그인 범위 식별자](/docs/ko/plugins/overview)에 예약되어 있습니다. Claude Code는 이름을 포함하는 파일을 로드하지 않고 디버그 로그에 오류를 기록합니다. v2.1.218 이전에는 이러한 이름이 허용되었습니다 |313| `name` | 예 | `code-reviewer` 또는 `reviewer-v2`와 같은 최대 256자의 고유 식별자. [훅](/docs/ko/hooks#subagentstart)은 이 값을 `agent_type`으로 받습니다. 파일 이름이 일치할 필요는 없습니다. 이름은 `:`를 포함할 수 없습니다. `:`는 `my-plugin:reviewer`와 같은 [플러그인 범위 식별자](/docs/ko/plugins/overview)에 예약되어 있습니다 |

314| `description` | 예 | Claude가 이 서브에이전트에 위임해야 할 때 |314| `description` | 예 | Claude가 이 서브에이전트에 위임해야 할 때 |

315| `tools` | 아니오 | 서브에이전트가 사용할 수 있는 [도구](#available-tools). `Read, Grep, Bash`와 같은 쉼표로 구분된 문자열 또는 YAML 목록입니다. 생략하면 서브에이전트가 사용 가능한 모든 도구를 상속합니다. 목록의 항목이 도구로 확인되지 않으면, 서브에이전트는 일반적으로 항목을 이름 지정하는 오류로 [시작에 실패](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)합니다. 스킬을 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용하세요 |315| `tools` | 아니오 | 서브에이전트가 사용할 수 있는 [도구](#available-tools). `Read, Grep, Bash`와 같은 쉼표로 구분된 문자열 또는 YAML 목록입니다. 생략하면 서브에이전트가 사용 가능한 모든 도구를 상속합니다. 목록의 항목이 도구로 확인되지 않으면, 서브에이전트는 일반적으로 항목을 이름 지정하는 오류로 [시작에 실패](/docs/ko/errors#agent-would-be-spawned-with-zero-tools)합니다. 스킬을 컨텍스트에 미리 로드하려면 여기에 `Skill`을 나열하는 대신 `skills` 필드를 사용하세요 |

316| `disallowedTools` | 아니오 | 거부할 도구. 상속되거나 지정된 목록에서 제거됩니다. `tools`와 동일한 형식입니다. `Bash(git push *)`와 같은 지정자가 있는 항목은 여전히 [전체 도구를 제거합니다](#available-tools) |316| `disallowedTools` | 아니오 | 거부할 도구. 상속되거나 지정된 목록에서 제거됩니다. `tools`와 동일한 형식입니다. `Bash(git push *)`와 같은 지정자가 있는 항목은 여전히 [전체 도구를 제거합니다](#available-tools) |

348 348 

349* **`name` 없음**: Claude Code는 파일을 에이전트 옆에 보관된 문서로 취급합니다.349* **`name` 없음**: Claude Code는 파일을 에이전트 옆에 보관된 문서로 취급합니다.

350* **파일의 첫 번째 줄이 아닌 여는 `---`**: Claude Code는 파일을 프론트매터가 없는 것으로 읽고 문서로 취급합니다.350* **파일의 첫 번째 줄이 아닌 여는 `---`**: Claude Code는 파일을 프론트매터가 없는 것으로 읽고 문서로 취급합니다.

351* **`-`로 시작하거나 `:`를 포함하는 `name`**: Claude Code는 파일을 건너뛰고 디버그 로그에 오류를 씁니다. 위의 `name` 행을 참조하세요.351* **`-`로 시작하거나, `:`를 포함하거나, 256자보다 긴 `name`**: Claude Code는 파일을 건너뛰고 디버그 로그에 오류를 기록합니다.

352* **`name`이지만 `description` 없음**: Claude Code는 파일을 건너뛰고 이유를 디버그 로그에 씁니다.352* **`name`이지만 `description` 없음**: Claude Code는 파일을 건너뛰고 이유를 디버그 로그에 씁니다.

353* **파싱되지 않는 YAML**: Claude Code는 파일에서 필드를 읽지 않고, 건너뛰고, 파싱 오류를 디버그 로그에 씁니다.353* **파싱되지 않는 YAML**: Claude Code는 파일에서 필드를 읽지 않고, 건너뛰고, 파싱 오류를 디버그 로그에 씁니다.

354 354 

606| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수를 설정합니다. 공유 구성의 경우 Claude Code 설정을 대신 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars) 항목은 값이 절대 경로인 경우에만 적용됩니다. 확장 프로그램은 `~`를 확장하지 않으며 상대 경로 값은 무시합니다. |606| `environmentVariables` | `[]` | Claude 프로세스에 대한 환경 변수를 설정합니다. 공유 구성의 경우 Claude Code 설정을 대신 사용합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars) 항목은 값이 절대 경로인 경우에만 적용됩니다. 확장 프로그램은 `~`를 확장하지 않으며 상대 경로 값은 무시합니다. |

607| `disableLoginPrompt` | `false` | 인증 프롬프트 건너뛰기(타사 공급자 설정의 경우) |607| `disableLoginPrompt` | `false` | 인증 프롬프트 건너뛰기(타사 공급자 설정의 경우) |

608| `allowDangerouslySkipPermissions` | `false` | 모드 선택기에 권한 무시를 추가합니다. 인터넷 접근이 없는 샌드박스에서만 사용합니다. |608| `allowDangerouslySkipPermissions` | `false` | 모드 선택기에 권한 무시를 추가합니다. 인터넷 접근이 없는 샌드박스에서만 사용합니다. |

609| `claudeProcessWrapper` | - | Claude 프로세스를 실행하는 데 사용되는 실행 파일입니다. 번들된 바이너리 경로는 존재할 때 인수로 전달됩니다. 확장 프로그램 빌드가 플랫폼에 포함되지 않은 경우 별도로 설치된 `claude` 바이너리로 설정합니다. 래핑된 설정에서는 `initialPermissionMode`를 설정하거나 이전 대화에서 Manual, Edit automatically 또는 Auto를 선택하지 않는 한 대화가 Manual 모드에서 시작됩니다. 확장 프로그램이 설정 및 기본 제공 기본값 단계를 건너뛰기 때문입니다. [권한 모드 전환](/docs/ko/permission-modes#switch-permission-modes)을 참조하세요. 활성화 시 "Unsupported platform" 오류는 플랫폼에 번들된 바이너리가 없음을 의미합니다. [어떤 플랫폼에 미리 빌드된 바이너리가 있는지](/docs/ko/troubleshoot-install#native-binary-not-found-after-npm-install) 참조하세요. |609| `claudeProcessWrapper` | - | Claude 프로세스를 실행하는 데 사용되는 실행 파일입니다. 번들된 바이너리 경로는 존재할 때 인수로 전달됩니다. 확장 프로그램 빌드에 해당 플랫폼용 바이너리가 포함되어 있지 않은 경우 별도로 설치된 `claude` 바이너리로 설정합니다. |

610 610 

611<h2 id="use-a-screen-reader">611<h2 id="use-a-screen-reader">

612 화면 읽기 프로그램 사용612 화면 읽기 프로그램 사용

6 6 

7> git worktree에서 병렬 Claude Code 세션을 격리하여 변경 사항이 충돌하지 않도록 합니다. `--worktree` 플래그, 서브에이전트 격리, `.worktreeinclude`, 정리 및 비git VCS 훅을 다룹니다.7> git worktree에서 병렬 Claude Code 세션을 격리하여 변경 사항이 충돌하지 않도록 합니다. `--worktree` 플래그, 서브에이전트 격리, `.worktreeinclude`, 정리 및 비git VCS 훅을 다룹니다.

8 8 

9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉토리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 한 세션의 편집이 다른 세션의 파일을 건드리지 않으므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.9[git worktree](https://git-scm.com/docs/git-worktree)는 자체 파일과 브랜치를 가진 별도의 작업 디렉터리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 세션마다 편집할 파일의 별도 사본이 주어지므로, 한 세션이 기능을 구축하는 동안 두 번째 세션이 버그를 수정할 수 있습니다.

10 10 

11<Note>11<Note>

12 Worktree는 git 저장소가 필요합니다. 다른 버전 관리 시스템의 경우 [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다. [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서는 세션을 시작할 때 **worktree** 옵션을 선택하여 자체 worktree를 제공합니다.12 Worktree는 git 저장소가 필요합니다. 다른 버전 관리 시스템의 경우 [훅을 구성하여 git 로직을 대체](#non-git-version-control)합니다. [데스크톱 앱](/docs/ko/desktop#work-in-parallel-with-sessions)에서는 세션을 시작할 때 **worktree** 옵션을 선택하여 자체 worktree를 제공합니다.

104* **Git 리다이렉트**: Claude Code는 git을 메인 체크아웃으로 리다이렉트하는 Bash 또는 Monitor 명령을 차단합니다. 리다이렉트는 `git -C`, `--git-dir`, `GIT_DIR` 또는 `GIT_WORK_TREE` 변수, 또는 git을 실행하기 전에 메인 체크아웃으로 `cd`를 통해 올 수 있습니다.104* **Git 리다이렉트**: Claude Code는 git을 메인 체크아웃으로 리다이렉트하는 Bash 또는 Monitor 명령을 차단합니다. 리다이렉트는 `git -C`, `--git-dir`, `GIT_DIR` 또는 `GIT_WORK_TREE` 변수, 또는 git을 실행하기 전에 메인 체크아웃으로 `cd`를 통해 올 수 있습니다.

105* **명령 형태**: Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내부에 머물러 있는지 확인할 수 없을 때 Bash 또는 Monitor 명령을 차단합니다. 예를 들어 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없거나 `${!name}` 또는 `${ command; }`와 같은 확장이 텍스트에서 명시하지 않은 명령을 실행할 수 있을 때 발생합니다. Claude Code는 Claude에게 거부된 명령을 다시 작성하는 방법을 알려줍니다. 예를 들어 이를 일반 별도 명령으로 분할합니다. 이 확인을 끌 수 없습니다.105* **명령 형태**: Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내부에 머물러 있는지 확인할 수 없을 때 Bash 또는 Monitor 명령을 차단합니다. 예를 들어 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없거나 `${!name}` 또는 `${ command; }`와 같은 확장이 텍스트에서 명시하지 않은 명령을 실행할 수 있을 때 발생합니다. Claude Code는 Claude에게 거부된 명령을 다시 작성하는 방법을 알려줍니다. 예를 들어 이를 일반 별도 명령으로 분할합니다. 이 확인을 끌 수 없습니다.

106 106 

107이러한 확인은 편집이 대상으로 하는 경로, 명령이 실행되는 디렉터리, 명령의 텍스트를 읽습니다. 어느 확인도 셸 명령이 어떤 파일에 쓰는지는 추적하지 않으므로, `cp`나 셸 리다이렉트처럼 메인 체크아웃에서 git을 실행하지 않고 메인 체크아웃에 쓰는 명령은 이 확인으로 거부되지 않습니다. Claude Code는 이러한 명령을 다른 셸 명령과 동일하게 취급하므로, 명령이 실행되는지 또는 확인을 요청하는지는 [권한 모드](/docs/ko/permission-modes)와 규칙에 따라 달라집니다.

108 

107확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.109확인은 Claude Code를 실행한 저장소에 적용됩니다. 또한 연결된 worktree가 연결된 메인 체크아웃도 포함합니다. PowerShell 명령의 경우 Claude Code는 작업 디렉토리 확인만 적용합니다.

108 110 

109Claude는 각 거부를 worktree의 이름을 지정하고 진행 방법을 설명하는 도구 오류로 봅니다. 거부된 명령의 경우 [거부 메시지의 의미와 이를 해결하는 방법](/docs/ko/errors#command-blocked-by-the-worktree-isolation-checks)을 참조하세요.111Claude는 각 거부를 worktree의 이름을 지정하고 진행 방법을 설명하는 도구 오류로 봅니다. 거부된 명령의 경우 [거부 메시지의 의미와 이를 해결하는 방법](/docs/ko/errors#command-blocked-by-the-worktree-isolation-checks)을 참조하세요.