126 126
127각 메커니즘이 정책을 저장하는 위치는 [각 메커니즘이 정책을 저장하는 위치](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy)를 참조하고, Claude Desktop `bootstrapUrl` 동등물은 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)을 참조하세요.127각 메커니즘이 정책을 저장하는 위치는 [각 메커니즘이 정책을 저장하는 위치](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy)를 참조하고, Claude Desktop `bootstrapUrl` 동등물은 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)을 참조하세요.
128 128
129<h3 id="large-rollouts">
130 대규모 롤아웃
131</h3>
132
133로그인은 클라이언트 IP 주소별로 속도 제한되며, 기본값은 소규모 팀에 적합합니다. 각 주소는 10분마다 30개의 로그인 시작과 10개의 코드 제출을 받습니다. 수천 명의 개발자로의 롤아웃은 첫 번째 아침에 해당 제한에 도달할 수 있으며, 두 가지 이유 중 하나입니다:
134
135* **게이트웨이가 로드 밸런서를 볼 수 없습니다.** [`listen.trusted_proxies`](/docs/ko/claude-apps-gateway-config#listen)가 없으면, 모든 개발자가 로드 밸런서의 주소에서 오는 것으로 나타나고 하나의 제한을 공유합니다. 다른 모든 것보다 먼저 설정하세요. 게이트웨이는 `X-Forwarded-For` 헤더를 무시할 때 처음으로 경고를 기록합니다.
136* **많은 개발자가 몇 개의 NAT 또는 VPN 송신 주소를 공유합니다.** `trusted_proxies`가 올바를 때도 해당 주소의 제한을 공유합니다. [`rate_limits`](/docs/ko/claude-apps-gateway-config#http-tuning)를 맞추도록 올리세요.
137
138`max`를 크기 조정하려면, 개발자를 공유하는 송신 주소로 나누세요. 기본값인 10분인 하나의 `window_seconds` 기간 내에 그 중 몇 명이 로그인하는지 추정하세요. 그런 다음 재시도 및 Claude Code와 Claude Desktop 모두에 로그인하는 개발자를 포함하도록 두 배로 늘리세요.
139
140예를 들어, 4개의 송신 주소 뒤에 있는 10,000명의 개발자가 1시간에 걸쳐 균등하게 로그인합니다. 이는 주소당 2,500명의 개발자이고 각 10분마다 약 420명이며, 이를 두 배로 늘리고 1,000으로 올림합니다. 아래 예제는 두 제한을 모두 1,000으로 설정합니다:
141
142```yaml theme={null}
143rate_limits:
144 device_authorization: { max: 1000, window_seconds: 600 }
145 device_verify: { max: 1000, window_seconds: 600 }
146```
147
148`device_verify`는 누군가가 다른 개발자의 로그인 코드를 추측하는 것을 막는 것이므로, 추정이 필요한 만큼만 올리세요. 이 제한에서도, 코드는 20자 알파벳에서 8자이고 10분 후에 만료되므로, 추측은 비실용적으로 유지됩니다. [사용자 코드 무차별 대입 공격 저항](#user-code-brute-force-resistance)을 참조하세요.
149
150IdP가 새로고침 토큰을 발급할 때, Claude Code는 세션을 자동으로 갱신하므로, 롤아웃 후 제한을 다시 설정할 수 있습니다. 새로고침 토큰이 없으면, 개발자는 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)마다 다시 로그인합니다. 해당 정상 상태 속도에 대해 두 제한을 모두 크기 조정하고 올린 상태로 유지하세요.
151
152제한에 도달하면, Claude Code v2.1.274 이상은 `The gateway is limiting sign-in attempts right now`를 표시합니다. v2.1.274 이상의 게이트웨이는 확인 페이지에 `Too many attempts came from your network address`를 표시하며, 확인할 설정이 있습니다. 또한 변경할 설정의 이름을 지정하는 `sign-in refused` 로그 라인을 작성합니다.
153
129<h2 id="operations">154<h2 id="operations">
130 운영155 운영
131</h2>156</h2>
160 185
161`/.well-known/oauth-authorization-server`의 OAuth 검색 문서는 구성 로드, OIDC 검색, 업스트림 클라이언트 구성 및 Postgres 마이그레이션이 모두 성공한 후에만 `200`을 반환하므로, 엔드 투 엔드 부팅 확인으로도 작동합니다.186`/.well-known/oauth-authorization-server`의 OAuth 검색 문서는 구성 로드, OIDC 검색, 업스트림 클라이언트 구성 및 Postgres 마이그레이션이 모두 성공한 후에만 `200`을 반환하므로, 엔드 투 엔드 부팅 확인으로도 작동합니다.
162 187
188<h3 id="concurrent-upstream-requests">
189 동시 업스트림 요청
190</h3>
191
192기본적으로 각 게이트웨이 복제본은 동시에 최대 256개의 요청을 업스트림으로 보냅니다. 스트리밍 응답은 스트림이 끝날 때까지 제한에 대해 계산됩니다.
193
194복제본이 제한에 있을 때 도착하는 요청은 게이트웨이 내에서 빈 슬롯을 기다립니다. 개발자는 시작이 느리거나 중단된 것처럼 보이는 응답을 봅니다. `provider: anthropic` 업스트림에서, [`timeouts.upstream_ttfb_ms`](/docs/ko/claude-apps-gateway-config#http-tuning)보다 오래 기다리는 요청은 해당 업스트림을 포기하고, 나중 업스트림이 이를 제공하지 않으면 502로 실패합니다.
195
196`upstream requests:`를 포함하는 시작 로그 줄은 적용 중인 제한을 보여줍니다. 복제본이 제한보다 더 많은 요청을 열어 두는 동안, 또한 `client requests are open`을 포함하는 경고를 최대 분당 한 번 기록합니다.
197
198동시에 더 많은 요청을 제공하려면 두 가지 옵션이 있습니다:
199
200* 복제본을 추가합니다.
201* 각 복제본의 제한을 높입니다. 게이트웨이 컨테이너에서 `BUN_CONFIG_MAX_HTTP_REQUESTS` 환경 변수를 1에서 65535 사이의 정수로 설정한 다음 컨테이너를 다시 시작합니다.
202
203복제본은 요청이 열려 있는 평균 초 수로 나눈 제한 정도의 요청 속도로 제한을 채웁니다. 예를 들어, 요청이 평균 10초 동안 열려 있으면, 기본 제한 256의 복제본은 약 초당 26개 요청으로 제한을 채웁니다.
204
205CPU에서 자동 스케일링하면, 제한의 복제본은 스케일 아웃을 트리거하지 않고 요청을 큐에 넣으므로, 복제본이 `client requests are open` 경고를 기록할 때 표시하는 CPU 수준 아래로 대상을 설정합니다.
206
207<Warning>
208 모든 열린 요청은 스트리밍 중 및 슬롯을 기다리는 동안 게이트웨이 프로세스에서 메모리를 보유합니다. 제한을 256으로 유지하면, 과부하 복제본의 메모리는 여전히 증가합니다. 대기 요청이 요청 본문을 유지하기 때문입니다. 컨테이너의 메모리를 피크 시 열린 요청 수에 맞게 크기를 조정하고, 제한을 변경할 때 메모리를 감시합니다. 메모리가 부족한 복제본은 종료되고 보유한 모든 스트림을 삭제합니다.
209</Warning>
210
163<h3 id="outage-behavior">211<h3 id="outage-behavior">
164 중단 동작212 중단 동작
165</h3>213</h3>
207 업그레이드255 업그레이드
208</h3>256</h3>
209 257
210258복제본은 상태 비저장이므로 롤링 재시작은 언제든지 안전합니다. 게이트웨이는 부팅 시 스키마 마이그레이션을 실행하므로, 새 바이너리를 배포하면 데이터베이스가 자동으로 마이그레이션됩니다. 동시 복제본은 Postgres 자문 잠금에서 직렬화되므로 각 마이그레이션을 적용하는 것은 하나뿐입니다.복제본은 상태 비저장이므로 롤링 재시작은 게이트웨이 상태를 잃지 않습니다. 게이트웨이는 부팅 시 스키마 마이그레이션을 실행하므로, 새 바이너리를 배포하면 데이터베이스가 자동으로 마이그레이션됩니다. 동시 복제본은 Postgres 자문 잠금에서 직렬화되므로 각 마이그레이션을 적용하는 것은 하나뿐입니다.
259
260오케스트레이터가 롤링 재시작 또는 스케일 인에서처럼 `SIGTERM`으로 복제본을 중지할 때, 게이트웨이는 새 연결을 수락하는 것을 중지하고 이미 진행 중인 요청 및 스트림이 종료되기 전에 완료되도록 합니다. 드레인 윈도우라고 불리는 최대 25초를 기다린 다음 여전히 열려 있는 것을 닫습니다. `SIGINT`(예: 터미널의 Ctrl+C)는 동일한 드레인을 시작하고, 드레인 중 두 번째 신호는 열린 요청을 닫고 즉시 종료합니다. 드레인은 게이트웨이 v2.1.274 이상이 필요합니다.
261
262긴 생성은 몇 분 동안 스트리밍할 수 있습니다. Kubernetes 및 Amazon ECS에서 이 둘을 함께 높여 해당 스트림에 더 많은 시간을 제공합니다:
263
264* **드레인 윈도우**: 게이트웨이 컨테이너에서 `CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS` 환경 변수를 `120000`과 같은 양의 정수 밀리초로 설정합니다. 게이트웨이는 `120s`와 같은 다른 형식의 값을 무시하고 25초 기본값을 유지합니다
265* **오케스트레이터의 유예 기간**: Kubernetes의 `terminationGracePeriodSeconds` 또는 Amazon ECS의 `stopTimeout`
266
267유예 기간은 두 플랫폼 모두에서 기본값 30초입니다. 드레인 윈도우보다 최소 5초 이상 길게 유지하거나, 오케스트레이터가 드레인이 완료되기 전에 게이트웨이를 종료합니다. Kubernetes에서 유예 기간이 게이트웨이가 `SIGTERM`을 받을 때가 아니라 훅이 실행되기 전에 계산을 시작하기 때문에 `preStop` 훅의 기간도 추가합니다.
268
269플랫폼은 또한 드레인이 실행될 수 있는 기간을 제한할 수 있습니다:
270
271* **Amazon ECS on Fargate**: `stopTimeout`은 최대 120초를 허용합니다
272* **Cloud Run**: `SIGTERM` 후 10초 후에 인스턴스를 중지하므로, 열린 스트림은 드레인 윈도우가 무엇이든 최대 10초를 얻습니다
273
274드레인 윈도우가 여전히 열린 요청으로 끝나면, 게이트웨이는 `drain window over after`를 포함하는 경고를 기록하고, 자른 요청을 계산하며, 높일 두 설정의 이름을 지정합니다.
211 275
212마이그레이션은 추가 전용이므로 더 적은 마이그레이션을 아는 이전 바이너리로 롤백하는 것은 안전합니다. 추가 행을 무시합니다. 롤백은 또한 YAML을 이전 바이너리의 스키마에 대해 재검증하므로, 새 릴리스에서 도입한 키를 채택한 구성은 이전 바이너리에서 부팅이 실패합니다. 롤백 전에 새 키를 제거하세요.276마이그레이션은 추가 전용이므로 더 적은 마이그레이션을 아는 이전 바이너리로 롤백하는 것은 안전합니다. 추가 행을 무시합니다. 롤백은 또한 YAML을 이전 바이너리의 스키마에 대해 재검증하므로, 새 릴리스에서 도입한 키를 채택한 구성은 이전 바이너리에서 부팅이 실패합니다. 롤백 전에 새 키를 제거하세요.
213 277
239 303
240* 개발자는 원시 업스트림 키 대신 단기 JWT를 보유합니다. CLI-게이트웨이 레그는 RFC 8628 장치 부여를 사용하고, 게이트웨이의 IdP와의 인증 코드 교환은 기본 구성에서 PKCE를 실행하므로, 가로챈 IdP 인증 코드는 쓸모가 없습니다.304* 개발자는 원시 업스트림 키 대신 단기 JWT를 보유합니다. CLI-게이트웨이 레그는 RFC 8628 장치 부여를 사용하고, 게이트웨이의 IdP와의 인증 코드 교환은 기본 구성에서 PKCE를 실행하므로, 가로챈 IdP 인증 코드는 쓸모가 없습니다.
241* 장치 검증 페이지는 동일 출처 POST 및 RFC 8628 §5.1당 IP당 속도 제한을 적용합니다. [사용자 코드 무차별 대입 저항](#user-code-brute-force-resistance)을 참조하세요.305* 장치 검증 페이지는 동일 출처 POST 및 RFC 8628 §5.1당 IP당 속도 제한을 적용합니다. [사용자 코드 무차별 대입 저항](#user-code-brute-force-resistance)을 참조하세요.
242306* 아웃바운드 요청은 DNS를 확인하고, 링크 로컬 및 클라우드 메타데이터 주소와 기본적으로 루프백을 차단하며, 연결을 확인된 IP에 고정하는 서버 측 요청 위조(SSRF) 가드를 통과합니다. 따라서 IdP 및 OTLP 대상과 같은 운영자 영향 URL은 클라우드 메타데이터 엔드포인트로 리디렉션될 수 없습니다. RFC 1918 프라이빗 범위는 의도적으로 허용됩니다. IdP 및 OTLP 수집기가 일반적으로 프라이빗 IP에 있기 때문입니다. 루프백 IdP 또는 `localhost`의 사이드카 OTLP 수집기와 같이 게이트웨이가 정당하게 도달해야 하는 것이 루프백에 있을 때만 게이트웨이의 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하세요. 변수는 모든 운영자 구성 URL에 대해 루프백 블록을 완화하고 또한 포드가 클라우드 메타데이터 엔드포인트에 도달할 수 있는지 확인하는 부팅 시간 경고를 건너뜁니다. 따라서 수집기에 자체 내부 주소를 제공하는 것을 선호하세요.* 게이트웨이의 IdP, OTLP 수집기 및 `provider: anthropic` 업스트림에 대한 요청은 DNS를 확인하고, 링크 로컬 및 클라우드 메타데이터 주소와 기본적으로 루프백을 차단하며, 연결을 확인된 IP에 고정하는 서버 측 요청 위조(SSRF) 가드를 통과합니다. 따라서 운영자 영향 URL은 클라우드 메타데이터 엔드포인트로 리디렉션될 수 없습니다. RFC 1918 프라이빗 범위는 의도적으로 허용됩니다. IdP 및 OTLP 수집기가 일반적으로 프라이빗 IP에 있기 때문입니다. 다른 공급자의 경우, 게이트웨이는 구성을 로드할 때 이러한 주소 또는 메타데이터 호스트명을 지정하는 `base_url`을 거부하고, 공급자의 SDK는 DNS 확인 없이 연결합니다.
307
308 [프록시 전용 송신](/docs/ko/claude-apps-gateway-config#proxy-only-egress)을 켜면, 해당 주소 확인이 포워드 프록시로 이동합니다: 게이트웨이는 호스트명을 전달하고 프록시의 허용 목록은 해당 대상을 거부해야 합니다.
309
310 게이트웨이가 정당하게 도달해야 하는 것이 루프백에 있을 때만 게이트웨이의 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하세요. 예를 들어 로컬 개발 IdP 또는 `localhost`의 사이드카 OTLP 수집기. 변수는 모든 운영자 구성 URL에 대해 루프백 블록을 완화하고 또한 포드가 클라우드 메타데이터 엔드포인트에 도달할 수 있는지 확인하는 부팅 시간 경고를 건너뜁니다. 따라서 수집기에 자체 내부 주소를 제공하는 것을 선호하세요.
243 311
244자신의 송신 제어를 추가하면, 게이트웨이는 워크로드 ID와 같은 인스턴스 메타데이터 자격 증명을 사용할 때마다 메타데이터 서버에 도달해야 합니다.312자신의 송신 제어를 추가하면, 게이트웨이는 워크로드 ID와 같은 인스턴스 메타데이터 자격 증명을 사용할 때마다 메타데이터 서버에 도달해야 합니다.
245 313
254 322
255`user_code` 개발자가 `/device` 검증 페이지에 입력하는 것은 20자 알파벳에서 그려진 8자이며, 20⁸ 또는 약 2.56×10¹⁰ 조합을 산출하고 10분 후 만료됩니다.323`user_code` 개발자가 `/device` 검증 페이지에 입력하는 것은 20자 알파벳에서 그려진 8자이며, 20⁸ 또는 약 2.56×10¹⁰ 조합을 산출하고 10분 후 만료됩니다.
256 324
257325게이트웨이는 [`rate_limits`](/docs/ko/claude-apps-gateway-config#http-tuning)를 통해 구성 가능한 장치 부여 엔드포인트에 IP당 속도 제한을 적용합니다. 많은 개발자가 단일 공유 회사 NAT 주소에서 로그인하면 제한을 올리세요. 제한은 로그인 흐름에만 적용되며 추론에는 적용되지 않습니다.게이트웨이는 [`rate_limits`](/docs/ko/claude-apps-gateway-config#http-tuning)를 통해 구성 가능한 장치 부여 엔드포인트에 IP당 속도 제한을 적용합니다. 많은 개발자가 단일 공유 회사 NAT 주소에서 로그인하면 제한을 올리세요. [대규모 롤아웃](#large-rollouts)은 크기를 조정하는 방법을 보여줍니다. 제한은 로그인 흐름에만 적용되며 추론에는 적용되지 않습니다.
258 326
259<h3 id="compliance-posture">327<h3 id="compliance-posture">
260 규정 준수 태세328 규정 준수 태세
284gateway stderr에는 감사 이벤트 스트림이 포함되고, 감사 로그는 개발자 신원을 기록하며, 디버그 파일은 개발자 머신의 hook 및 MCP 서버 출력을 기록합니다. 공개 이슈에 게시하기 전에 이를 검토하고 수정하세요.352gateway stderr에는 감사 이벤트 스트림이 포함되고, 감사 로그는 개발자 신원을 기록하며, 디버그 파일은 개발자 머신의 hook 및 MCP 서버 출력을 기록합니다. 공개 이슈에 게시하기 전에 이를 검토하고 수정하세요.
285 353
286| 증상 | 원인 | 해결 방법 |354| 증상 | 원인 | 해결 방법 |
287355| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
288| 개발자의 `/login`이 **Cloud gateway** 화면 대신 표준 계정 선택기를 표시함 | 해당 머신의 관리 설정에서 `forceLoginMethod` 또는 `forceLoginGatewayUrl`이 설정되지 않음 | [관리 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)을 기기에 배포하세요. `/login`은 여기서 gateway URL을 읽습니다 |356| 개발자의 `/login`이 **Cloud gateway** 화면 대신 표준 계정 선택기를 표시함 | 해당 머신의 관리 설정에서 `forceLoginMethod` 또는 `forceLoginGatewayUrl`이 설정되지 않음 | [관리 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)을 기기에 배포하세요. `/login`은 여기서 gateway URL을 읽습니다 |
289| 개발자의 요청이 `Not signed in to the Cloud gateway — run /login.`으로 실패함 | 머신의 관리 설정이 `forceLoginMethod: "gateway"` 또는 `forceLoginGatewayUrl`을 설정했고, 세션에 gateway 로그인이 없음. 남은 claude.ai 로그인은 요구사항을 충족하지 않음 | 개발자가 `/login`을 실행하고 gateway 로그인을 완료하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |357| 개발자의 요청이 `Not signed in to the Cloud gateway — run /login.`으로 실패함 | 머신의 관리 설정이 `forceLoginMethod: "gateway"` 또는 `forceLoginGatewayUrl`을 설정했고, 세션에 gateway 로그인이 없음. 남은 claude.ai 로그인은 요구사항을 충족하지 않음 | 개발자가 `/login`을 실행하고 gateway 로그인을 완료하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |
290| Claude Desktop이 부트스트랩 구성을 가져올 수 없다고 보고함 | `/user/bootstrap`이 404를 반환함: 사용자와 일치하는 정책이 `desktop` 키를 포함하지 않거나 일치하는 정책이 없음. gateway 감사 로그는 각 거부를 `desktop_bootstrap.denied`로 이유와 함께 기록함 | 사용자와 일치하는 정책 또는 `match: {}` 기본 계층에 `desktop` 블록을 추가하세요. 빈 `desktop: {}`으로 충분합니다. [Claude Desktop 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)를 참조하세요. |358| Claude Desktop이 부트스트랩 구성을 가져올 수 없다고 보고함 | `/user/bootstrap`이 404를 반환함: 사용자와 일치하는 정책이 `desktop` 키를 포함하지 않거나 일치하는 정책이 없음. gateway 감사 로그는 각 거부를 `desktop_bootstrap.denied`로 이유와 함께 기록함 | 사용자와 일치하는 정책 또는 `match: {}` 기본 계층에 `desktop` 블록을 추가하세요. 빈 `desktop: {}`으로 충분합니다. [Claude Desktop 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)를 참조하세요. |
291| 시작 시 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.`를 표시함 | 설치된 Claude Code 빌드가 gateway 지원보다 이전 버전임 | 개발자가 Cloud gateway 지원을 포함하는 릴리스로 Claude Code를 업데이트하도록 하세요 |359| 시작 시 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.`를 표시함 | 설치된 Claude Code 빌드가 gateway 지원보다 이전 버전임 | 개발자가 Cloud gateway 지원을 포함하는 릴리스로 Claude Code를 업데이트하도록 하세요 |
292| 시작이 `Administrator policy requires a Cloud gateway sign-in on this machine`으로 종료됨 | 개발자의 환경이 `ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`을 설정하거나, 설정이 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper)를 구성하거나, 이전 Claude Console 로그인의 API 키가 여전히 저장되어 있음 | 해당하는 각각을 지우도록 개발자에게 지시하세요: 변수를 설정 해제하거나, `apiKeyHelper` 항목을 제거하거나, `claude auth logout`을 실행하여 저장된 키를 제거합니다. 그런 다음 `claude`를 시작하고 `/login`으로 로그인하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |360| 시작이 `Administrator policy requires a Cloud gateway sign-in on this machine`으로 종료됨 | 개발자의 환경이 `ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`을 설정하거나, 설정이 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper)를 구성하거나, 이전 Claude Console 로그인의 API 키가 여전히 저장되어 있음 | 해당하는 각각을 지우도록 개발자에게 지시하세요: 변수를 설정 해제하거나, `apiKeyHelper` 항목을 제거하거나, `claude auth logout`을 실행하여 저장된 키를 제거합니다. 그런 다음 `claude`를 시작하고 `/login`으로 로그인하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |
293| 시작 또는 `/login`이 `/managed/settings` 로드에서 403 후 `Claude Code may not be enabled for your organization`을 보고함 | gateway 또는 그 앞의 무언가가 `/managed/settings` 요청에 403으로 응답함. gateway 자체 설정 경로는 절대 403으로 응답하지 않음. 상태는 [`access_control`](/docs/ko/claude-apps-gateway-config#http-tuning) IP 확인 또는 gateway 앞의 프록시 또는 WAF에서 옴. 감사 로그는 IP 확인 거부를 `access.denied`로 이유와 함께 기록함. 개발자는 로그인 상태를 유지함 | 실패 시간에 `access.denied`에 대한 감사 로그를 확인하고 `access_control` 목록 또는 프론트 엔드를 수정한 후 개발자가 `claude`를 다시 시작하도록 하세요 |361| 시작 또는 `/login`이 `/managed/settings` 로드에서 403 후 `Claude Code may not be enabled for your organization`을 보고함 | gateway 또는 그 앞의 무언가가 `/managed/settings` 요청에 403으로 응답함. gateway 자체 설정 경로는 절대 403으로 응답하지 않음. 상태는 [`access_control`](/docs/ko/claude-apps-gateway-config#http-tuning) IP 확인 또는 gateway 앞의 프록시 또는 WAF에서 옴. 감사 로그는 IP 확인 거부를 `access.denied`로 이유와 함께 기록함. 개발자는 로그인 상태를 유지함 | 실패 시간에 `access.denied`에 대한 감사 로그를 확인하고 `access_control` 목록 또는 프론트 엔드를 수정한 후 개발자가 `claude`를 다시 시작하도록 하세요 |
362| CLI `/login`: `The gateway is limiting sign-in attempts right now`, 또는 이전 버전에서 `Request failed with status code 429`. `/device` 페이지는 이전에 시도하지 않은 개발자에게 `Too many attempts`를 표시할 수 있음 | IP당 로그인 속도 제한에 도달함. `listen.trusted_proxies`가 로드 밸런서를 포함하지 않아 모든 개발자가 해당 주소를 공유하거나, 많은 개발자가 NAT 또는 VPN 송신 주소를 공유함. `result: rate_limited`가 있는 감사 이벤트는 동일한 하나 또는 몇 개의 `client_ip` 값을 표시함. | 먼저 `listen.trusted_proxies`를 로드 밸런서의 소스 범위로 설정한 후, 개발자가 여전히 주소를 공유하는 경우 `rate_limits`를 높이세요. [대규모 롤아웃](#large-rollouts)을 참조하세요. |
294| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 호스트명이 최소 하나의 공개 IP 주소로 확인됨. Claude Code는 각 확인된 주소를 확인하고 모든 주소가 비공개여야 함. 일반적인 원인은 한 패밀리가 공개 주소로 확인되는 이중 스택 이름이며, AWS 내부 이중 스택 로드 밸런서를 포함하여 공개 범위 AAAA 주소를 반환함 | gateway 이름이 개발자 머신에서 비공개 주소로만 확인되도록 하세요. 이중 스택 이름의 경우 공개 범위 레코드를 삭제하거나 별도의 내부 전용 DNS 이름을 제공하세요. [비공개 네트워크 전제 조건](/docs/ko/claude-apps-gateway#prerequisites)을 참조하세요. 주소가 조직이 소유하고 내부적으로 사용하는 공개 공간인 경우 [해당 블록을 선언](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)하세요. |363| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 호스트명이 최소 하나의 공개 IP 주소로 확인됨. Claude Code는 각 확인된 주소를 확인하고 모든 주소가 비공개여야 함. 일반적인 원인은 한 패밀리가 공개 주소로 확인되는 이중 스택 이름이며, AWS 내부 이중 스택 로드 밸런서를 포함하여 공개 범위 AAAA 주소를 반환함 | gateway 이름이 개발자 머신에서 비공개 주소로만 확인되도록 하세요. 이중 스택 이름의 경우 공개 범위 레코드를 삭제하거나 별도의 내부 전용 DNS 이름을 제공하세요. [비공개 네트워크 전제 조건](/docs/ko/claude-apps-gateway#prerequisites)을 참조하세요. 주소가 조직이 소유하고 내부적으로 사용하는 공개 공간인 경우 [해당 블록을 선언](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)하세요. |
295| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 또는 `HTTP_PROXY`가 gateway 호스트에 적용되고 프록시의 호스트명이 공개 주소로 확인됨. 호스트가 비공개 주소로만 확인되는 프록시는 허용되며 이 오류를 트리거하지 않음 | 개발자 머신의 `NO_PROXY`에 gateway 호스트를 추가하여 연결이 직접 이루어지도록 하거나, 호스트명이 비공개 주소로 확인되는 프록시를 사용하세요. 메시지는 추가할 정확한 `NO_PROXY` 항목을 이름으로 지정합니다 |364| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 또는 `HTTP_PROXY`가 gateway 호스트에 적용되고 프록시의 호스트명이 공개 주소로 확인됨. 호스트가 비공개 주소로만 확인되는 프록시는 허용되며 이 오류를 트리거하지 않음 | 개발자 머신의 `NO_PROXY`에 gateway 호스트를 추가하여 연결이 직접 이루어지도록 하거나, 호스트명이 비공개 주소로 확인되는 프록시를 사용하세요. 메시지는 추가할 정확한 `NO_PROXY` 항목을 이름으로 지정합니다 |
296| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway가 [`gatewayInternalNetworks`](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)에 선언된 블록에 있고, 개발자 머신이 해당 블록 외부의 주소에서 도달함: VPN 주소 풀, 컨테이너 또는 WSL2 NAT 세그먼트, 또는 조직의 네트워크가 아님 | 개발자가 네트워크의 호스트 OS에서 `/login`을 실행하도록 하세요. 표시된 주소도 조직의 공개 공간인 경우 gateway 항목을 두 주소를 모두 포함하는 블록으로 바꾸세요(`/8`까지). 두 번째 겹치는 항목은 거부됩니다 |365| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway가 [`gatewayInternalNetworks`](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)에 선언된 블록에 있고, 개발자 머신이 해당 블록 외부의 주소에서 도달함: VPN 주소 풀, 컨테이너 또는 WSL2 NAT 세그먼트, 또는 조직의 네트워크가 아님 | 개발자가 네트워크의 호스트 OS에서 `/login`을 실행하도록 하세요. 표시된 주소도 조직의 공개 공간인 경우 gateway 항목을 두 주소를 모두 포함하는 블록으로 바꾸세요(`/8`까지). 두 번째 겹치는 항목은 거부됩니다 |
301| CLI `/login`: `Could not resolve gateway host <host>` | 머신이 gateway의 내부 DNS 이름을 확인할 수 없음. 일반적으로 회사 네트워크에 없기 때문 | 개발자가 네트워크 또는 VPN에 연결한 후 `/login`을 다시 시도하도록 하세요 |370| CLI `/login`: `Could not resolve gateway host <host>` | 머신이 gateway의 내부 DNS 이름을 확인할 수 없음. 일반적으로 회사 네트워크에 없기 때문 | 개발자가 네트워크 또는 VPN에 연결한 후 `/login`을 다시 시도하도록 하세요 |
302| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |371| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |
303| 부트 종료: `requires the native binary` | Node 대신 네이티브 바이너리에서 실행 중 | [독립 실행형 설치 방법](/docs/ko/setup) 중 하나로 Claude Code를 설치하세요 |372| 부트 종료: `requires the native binary` | Node 대신 네이티브 바이너리에서 실행 중 | [독립 실행형 설치 방법](/docs/ko/setup) 중 하나로 Claude Code를 설치하세요 |
304373| 부트가 `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의 각 엔드포인트에 대한 직접 경로를 제공하세요. || 부트가 `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 이상이 필요합니다. |
305| 부트가 Postgres 권한 오류로 종료됨 | 데이터베이스 역할이 스키마에 대한 DDL 권한이 없음 | 부트 시 테이블을 생성하고 변경할 수 있도록 gateway 스키마에 대해 역할에 `CREATE` 권한을 부여하세요 |374| 부트가 Postgres 권한 오류로 종료됨 | 데이터베이스 역할이 스키마에 대한 DDL 권한이 없음 | 부트 시 테이블을 생성하고 변경할 수 있도록 gateway 스키마에 대해 역할에 `CREATE` 권한을 부여하세요 |
375| 로그: `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)를 높이세요. |
306| `/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`을 설정하세요. |376| `/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`을 설정하세요. |
307| 로그: `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`를 설정하세요. |377| 로그: `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`를 설정하세요. |
308| 로그: `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)을 참조하세요. |378| 로그: `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)을 참조하세요. |
309| 모든 Amazon Bedrock 요청이 502를 반환함. 로그가 `Could not load credentials from any providers`를 표시함 | EC2에서 IMDSv2의 기본 홉 제한 1이 컨테이너 내부의 인스턴스 메타데이터 요청을 차단함. 부트 및 `/readyz`는 AWS SDK가 클라이언트 구성이 아닌 첫 번째 요청에서 인스턴스 자격 증명을 확인하므로 어쨌든 통과함 | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`로 홉 제한을 높이거나 시작 템플릿에서 설정하세요. 변경 사항은 인스턴스의 모든 컨테이너에 적용됩니다. 가능한 경우 ECS 작업 역할을 선호하세요. 이는 ECS 컨테이너 자격 증명 엔드포인트에서 자격 증명을 읽고 변경을 완전히 피하거나, 노출을 제한하기 위해 전용 gateway 인스턴스에 변경을 적용하세요. |379| 모든 Amazon Bedrock 요청이 502를 반환함. 로그가 `Could not load credentials from any providers`를 표시함 | EC2에서 IMDSv2의 기본 홉 제한 1이 컨테이너 내부의 인스턴스 메타데이터 요청을 차단함. 부트 및 `/readyz`는 AWS SDK가 클라이언트 구성이 아닌 첫 번째 요청에서 인스턴스 자격 증명을 확인하므로 어쨌든 통과함 | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`로 홉 제한을 높이거나 시작 템플릿에서 설정하세요. 변경 사항은 인스턴스의 모든 컨테이너에 적용됩니다. 가능한 경우 ECS 작업 역할을 선호하세요. 이는 ECS 컨테이너 자격 증명 엔드포인트에서 자격 증명을 읽고 변경을 완전히 피하거나, 노출을 제한하기 위해 전용 gateway 인스턴스에 변경을 적용하세요. |
380| 피크 로드에서 응답이 시작되기 느리거나 중단된 것처럼 보이거나, 업스트림이 정상인데도 502 `all upstreams failed`로 실패함 | 복제본이 업스트림으로 한 번에 보내는 것보다 더 많은 요청을 열어 두었으므로 추가 요청은 gateway 내부에서 대기함. `provider: anthropic` 업스트림에서 `timeouts.upstream_ttfb_ms`보다 오래 대기하는 요청은 해당 업스트림을 포기하며, 이후 업스트림이 제공하지 않으면 502를 생성함. 로그는 `client requests are open`을 포함하는 경고를 표시함. | 복제본을 추가하거나 각 복제본의 제한을 높이세요. [동시 업스트림 요청](#concurrent-upstream-requests)을 참조하세요. |
310| IdP 오류: unknown or unsupported scope | IdP가 인식하지 못하는 범위를 거부함 | `oidc.scopes`를 정확히 IdP가 수락하는 목록으로 설정하세요. `openid`를 포함해야 합니다. 기본값은 `openid profile email offline_access`입니다. |381| IdP 오류: unknown or unsupported scope | IdP가 인식하지 못하는 범위를 거부함 | `oidc.scopes`를 정확히 IdP가 수락하는 목록으로 설정하세요. `openid`를 포함해야 합니다. 기본값은 `openid profile email offline_access`입니다. |
311| `oidc.scopes` 설정 후 세션이 자동으로 갱신되지 않음 | `offline_access`가 재정의에서 삭제됨 | IdP가 지원하는 경우 `offline_access`를 다시 추가하세요. 새로 고침 토큰 없이 개발자는 매 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. |382| `oidc.scopes` 설정 후 세션이 자동으로 갱신되지 않음 | `offline_access`가 재정의에서 삭제됨 | IdP가 지원하는 경우 `offline_access`를 다시 추가하세요. 새로 고침 토큰 없이 개발자는 매 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. |
312| 브라우저가 "This request came from another site and was blocked"를 표시함 | 교차 사이트 양식 POST, CSRF 보호로 차단됨. 포함되거나 프록시된 페이지의 경우 예상됨 | 검증 링크를 직접 열기 |383| 브라우저가 "This request came from another site and was blocked"를 표시함 | 교차 사이트 양식 POST, CSRF 보호로 차단됨. 포함되거나 프록시된 페이지의 경우 예상됨 | 검증 링크를 직접 열기 |