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
