1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Claude 앱 게이트웨이 구성
6
7> 모든 gateway.yaml 옵션에 대한 참조: 리스너 및 TLS, OIDC, 세션, Postgres 저장소, Bedrock/Agent Platform/Foundry 업스트림, 모델 라우팅, 관리형 정책 및 텔레메트리.
8
9Claude 앱 게이트웨이 배포는 하나의 YAML 파일(관례상 `gateway.yaml`)로 구성됩니다. 이 파일은 게이트웨이가 수행하는 모든 작업을 정의합니다: 어디서 수신 대기하는지, 개발자가 어떻게 로그인하는지, 추론이 어디로 가는지, 어떤 정책과 텔레메트리가 적용되는지입니다. 이 페이지는 해당 파일의 모든 옵션에 대한 참조입니다. 첫 번째 파일을 작성하려면 [빠른 시작](/ko/claude-apps-gateway#quickstart)에서 시작하세요. 이 페이지는 최소한의 작동 구성을 구축하고 실행합니다. 만족스러운 구성이 있으면 [배포 가이드](/ko/claude-apps-gateway-deploy)에서 Kubernetes, Cloud Run 또는 자신의 플랫폼에서 컨테이너화 및 호스팅하는 방법을 다룹니다.
10
11게이트웨이는 `claude gateway --config /path/to/gateway.yaml`을 사용하여 시작 시 파일을 한 번 읽습니다. 모든 옵션은 부팅 시 스키마에 대해 검증되므로 잘못된 구성은 첫 사용 시가 아니라 필드 수준 오류로 시작 시 실패합니다.
12
13이 페이지 끝의 [완전한 예제](#complete-example)는 모든 섹션을 다룹니다.
14
15<h2 id="file-structure">
16 파일 구조
17</h2>
18
195개 섹션이 [필수](#required-sections)입니다. 다른 모든 섹션은 [선택 사항](#optional-sections)이며, 생략된 섹션은 기본값을 사용합니다. 알 수 없는 키는 부팅을 실패하므로 오타는 자동으로 무시되는 설정이 아니라 명명된 오류로 표시됩니다.
20
21**필수 섹션:**
22
23* [`listen`](#listen): 바인드 주소, 공개 URL, TLS 종료
24* [`oidc`](#oidc): ID 공급자(IdP), 발급자, 클라이언트, 클레임 매핑 및 로그인 가능 사용자 포함
25* [`session`](#session): 게이트웨이가 발급하는 베어러 토큰, 비밀 및 수명 포함
26* [`store`](#store): 장치 권한 부여 및 속도 제한 카운터용 PostgreSQL
27* [`upstreams`](#upstreams): 추론이 가는 위치, Anthropic, Bedrock, Agent Platform 또는 Foundry 여부
28
29**선택 사항 섹션:**
30
31* [`admin`](#admin): 관리자 API 인증 및 지출 한도 보유
32* [`enforcement`](#enforcement): 지출 한도 실패 개방 또는 실패 폐쇄 동작
33* [`models`](#models) 및 `auto_include_builtin_models`: 관리자 선별 모델 목록 및 업스트림별 ID
34* [`managed`](#managed): IdP 그룹별 관리형 설정 정책
35* [`telemetry`](#telemetry): 관찰성 스택으로의 OTLP 전달
36* [`access_control`, `limits`, `timeouts`, `rate_limits`](#http-tuning): IP 허용/거부, 요청 크기 제한, 업스트림 첫 바이트까지의 시간 및 IP당 로그인 한도
37
38<h2 id="secret-expansion">
39 비밀 확장
40</h2>
41
42`client_secret`, `jwt_secret` 또는 `postgres_url`과 같은 비밀을 `gateway.yaml`에 직접 작성하지 마세요. 아래 형식 중 하나로 참조하면 게이트웨이가 부팅 시 환경 변수 또는 파일에서 값을 확인합니다:
43
44| 형식 | 확인 대상 | 사용 대상 |
45| --------------- | ---------------------------- | ------------------------------------------- |
46| `${VAR}` | 환경 변수 `VAR`. 정의되지 않으면 부팅 실패. | 컨테이너 환경 변수, 환경 주입을 통한 AWS Secrets Manager |
47| `${file:/path}` | 파일 내용, 정리됨 | Kubernetes Secret 볼륨 마운트, Vault Agent, SOPS |
48
49<h2 id="required-sections">
50 필수 섹션
51</h2>
52
53<h3 id="listen">
54 `listen`
55</h3>
56
57`listen` 블록은 게이트웨이가 제공하는 위치를 제어합니다: 바인드 주소 및 포트, 외부에서 보이는 원본 및 선택적 TLS 종료.
58
59| 필드 | 필수 | 설명 |
60| ---------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61| `host` | 아니요 | 바인드 주소. 기본값 `0.0.0.0`. |
62| `port` | 아니요 | 바인드 포트. 기본값 `8080`. |
63| `public_url` | 프록시 뒤 | 외부에서 보이는 `https://` 원본, IdP `redirect_uri` 및 검색 메타데이터를 구축하는 데 사용됩니다. ALB, Ingress 또는 Cloud Run과 같은 TLS 종료 프록시 뒤에 필수입니다. 게이트웨이는 자신의 원본을 구성할 때 `X-Forwarded-*` 헤더를 신뢰하지 않기 때문입니다. 이들은 클라이언트가 스푸핑할 수 있습니다. 아래의 `trusted_proxies`는 클라이언트 IP 확인만 제어합니다. 또한 [텔레메트리](#telemetry)를 활성화하려면 필수입니다. 게이트웨이가 클라이언트에 푸시하는 OTLP 엔드포인트를 이 URL에서 구축하기 때문입니다. |
64| `tls.cert` / `tls.key` | 아니요 | 게이트웨이가 자체적으로 TLS를 종료하는 경우 PEM 경로 |
65| `trusted_proxies` | 아니요 | 게이트웨이 앞의 로드 밸런서의 CIDR 또는 IP. 설정하면 게이트웨이는 이 피어에서만 `X-Forwarded-For`를 신뢰하고 IP당 속도 제한 및 감사를 위해 실제 클라이언트 IP를 기록합니다. nginx `set_real_ip_from`과 동등합니다. |
66
67<h3 id="oidc">
68 `oidc`
69</h3>
70
71OpenID Connect(OIDC)는 게이트웨이가 ID 공급자와 함께 사용하는 SSO 프로토콜입니다. IdP 측에서 등록할 내용은 [ID 공급자 설정](/ko/claude-apps-gateway-deploy#identity-provider-setup)을 참조하세요. `oidc` 블록은 게이트웨이를 ID 공급자에 연결하고 로그인할 수 있는 사용자를 결정합니다. 발급자 및 OAuth 클라이언트의 이름을 지정하고, 이메일 및 그룹을 전달하는 클레임을 매핑하며, 이메일 도메인 또는 그룹별로 로그인을 제한합니다.
72
73| 필드 | 필수 | 설명 |
74| ------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75| `issuer` | 예 | OIDC 검색 기본. `/.well-known/openid-configuration`에서 검색을 제공해야 합니다. 프로덕션에서는 HTTPS를 사용하세요. 게이트웨이는 `http://` 발급자를 허용합니다. `http://localhost:8081`과 같은 루프백 발급자는 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`이 게이트웨이의 환경에 설정되지 않으면 [SSRF 가드](/ko/claude-apps-gateway-deploy#threat-model-summary)에 의해 거부됩니다. |
76| `client_id` / `client_secret` | 예 | OAuth 클라이언트 등록에서 |
77| `allowed_email_domains` | 아니요 | `email` 클레임이 이 도메인 중 하나에 없는 id\_token을 거부합니다(대소문자 구분 안 함). 다중 테넌트 IdP 오구성에 대한 심층 방어. 이 설정과 무관하게 `email_verified` 클레임이 명시적으로 `false`인 id\_token은 항상 거부됩니다. |
78| `allowed_groups` | 아니요 | 로그인을 이 IdP 그룹의 구성원으로 제한하며, `groups_claim`과 비교합니다. 허용된 이메일 도메인에 있지만 이 그룹 중 어느 것도 아닌 사용자는 거부됩니다. IdP가 그룹 클레임을 내보내야 합니다. |
79| `groups_claim` | 아니요 | 어느 id\_token 클레임이 그룹 멤버십을 전달하는지. 기본값 `groups`. Microsoft Entra는 `roles` 아래에 앱 역할을 내보냅니다. 평면 키 또는 `/resource_access/gateway/roles`와 같은 중첩된 클레임에 대한 RFC 6901 JSON 포인터를 허용합니다. |
80| `google_groups` | 아니요 | Google Workspace Admin SDK Directory API를 통해 로그인한 사용자의 그룹을 조회합니다. Google의 id\_token은 그룹 클레임을 전달하지 않기 때문입니다. `service_account_json_path`를 `https://www.googleapis.com/auth/admin.directory.group.readonly` 범위에 대한 도메인 전체 위임이 있는 서비스 계정 키 파일로 설정하고, `admin_email`을 서비스 계정이 가장하는 Workspace 관리자로 설정합니다. Directory API는 실제 관리자 주체가 필요합니다. 각 사용자의 그룹 이메일 주소는 그룹 클레임이 되므로 `allowed_groups` 및 `managed.policies.match.groups`는 그룹 이메일과 일치합니다. |
81| `email_claim` | 아니요 | 어느 id\_token 클레임이 사용자의 이메일을 전달하는지. 기본값 `email`. ADFS 및 Entra B2C와 같은 일부 IdP는 대신 `upn` 또는 `preferred_username`을 내보냅니다. 평면 키, JSON 포인터 또는 첫 번째 존재하는 키가 사용되는 폴백 키 목록을 허용합니다. |
82| `scopes` | 아니요 | 게이트웨이가 요청하는 OIDC 범위의 전체 재정의. 기본값 `[openid, profile, email, offline_access]`. IdP가 인식하지 못하는 범위를 거부하거나 그룹 또는 이메일을 내보내기 위해 사용자 정의 범위가 필요한 경우 설정합니다. `openid`를 포함해야 합니다. `offline_access`를 삭제하면 새로 고침 토큰이 비활성화되므로 개발자는 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. Google의 새로 고침 토큰 흐름과 같은 IdP별 범위 레시피는 [ID 공급자 설정](/ko/claude-apps-gateway-deploy#identity-provider-setup)을 참조하세요. |
83| `extra_auth_params` | 아니요 | IdP 인증 요청에 그대로 추가되는 추가 쿼리 매개변수. 이것은 Google 새로 고침 토큰의 `access_type: offline`, 일부 Entra 테넌트의 `domain_hint` 또는 단계별 흐름의 `acr_values`와 같은 IdP 특정 동작에 대한 재정의 메커니즘입니다. 게이트웨이 관리 프로토콜 매개변수는 재정의할 수 없습니다: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` 및 `client_id`. |
84| `userinfo_fallback` | 아니요 | id\_token이 이메일 또는 그룹을 생략할 때 `/userinfo`에서 가져옵니다. Keycloak 경량 액세스 토큰, Okta org 서버 및 ADFS 최소 토큰에 필요합니다. id\_token은 권한이 있는 상태로 유지됩니다. userinfo는 간격만 채웁니다. 기본값 `false`. |
85| `use_pkce` | 아니요 | 인증 요청에 PKCE(S256) 챌린지를 보냅니다. 기본값 `true`. IdP가 이 기밀 클라이언트에 대해 PKCE를 거부하는 경우에만 `false`로 설정합니다. |
86| `clock_skew_seconds` | 아니요 | id\_token 시간 클레임을 검증할 때 클록 드리프트를 허용합니다. 기본값 `0`(엄격함). 로그인 직후 "토큰 만료됨 / 아직 유효하지 않음" 오류가 표시되면 호스트/IdP 클록 스큐로 인해 올립니다. |
87| `token_endpoint_auth_method` | 아니요 | 토큰 엔드포인트 인증 방법을 재정의합니다. `client_secret_basic` 또는 `client_secret_post`를 허용합니다. 기본적으로 자동 협상됩니다. |
88| `id_token_signed_response_alg` | 아니요 | 예상 id\_token 서명 알고리즘. 기본값 `RS256`. IdP가 ES256, PS256 또는 EdDSA로 서명하는 경우 설정합니다. |
89| `additional_authorized_parties` | 아니요 | `client_id` 외에 허용할 추가 `azp` 값, Keycloak 브로커 및 토큰 교환 흐름의 경우 |
90| `discovery_url` | 아니요 | 발급자에서 파생하는 대신 이 URL에서 검색 문서를 가져옵니다. IdP가 발급자 호스트를 다시 쓰는 프록시 뒤에 있는 경우. 경로는 `/.well-known/`을 포함해야 합니다. |
91| `form_action_origins` | 아니요 | `/device` 페이지의 `Content-Security-Policy: form-action` 지시문에 대한 추가 원본. 게이트웨이는 이미 `'self'` 및 검색된 `authorization_endpoint` 원본을 허용하지만 Chrome은 전체 리디렉션 체인에 대해 `form-action`을 적용합니다. IdP가 Azure AD가 ADFS로 페더레이션되거나 허브 스포크 Okta 또는 회사 SSO 인터셉터와 같은 두 번째 호스트를 통해 리디렉션하는 경우 인증 요청이 리디렉션될 수 있는 모든 원본을 나열합니다. |
92| `ca_cert_pem` | 아니요 | IdP 요청에만 시스템 신뢰 저장소를 대체하는 PEM CA 인증서. 회사 PKI 뒤의 Keycloak 또는 Dex에 사용합니다. |
93
94<h3 id="session">
95 `session`
96</h3>
97
98`session` 블록은 로그인 후 게이트웨이가 발급하는 베어러 토큰의 형태를 결정합니다: 서명하는 비밀과 수명.
99
100| 필드 | 필수 | 설명 |
101| ------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
102| `jwt_secret` | 예 | 최소 32바이트의 엔트로피(예: `openssl rand -base64 32`에서). 게이트웨이의 HS256 베어러 토큰에 서명합니다. 단일 문자열 또는 회전용 배열을 허용합니다: 인덱스 0이 서명하고 모든 항목이 검증합니다. 회전하려면 새 비밀을 앞에 추가하고 `ttl_hours`를 기다린 후 이전 비밀을 삭제합니다. |
103| `ttl_hours` | 아니요 | 게이트웨이 베어러 토큰 수명. 기본값 `1`. CLI는 IdP가 새로 고침 토큰을 발급할 때 만료 전에 자동으로 새로 고칩니다. 더 짧은 수명은 더 빠르게 프로비저닝을 해제합니다. 더 긴 수명은 더 적은 IdP 왕복을 만듭니다. IdP가 `offline_access`를 사용할 수 없어서 새로 고침 토큰을 발급할 수 없으면 자동 새로 고침이 없으므로 개발자가 매시간 브라우저 로그인으로 돌아가는 것을 피하기 위해 이를 `8` 또는 `12`로 올립니다. |
104
105<h3 id="store">
106 `store`
107</h3>
108
109`store` 블록은 게이트웨이를 PostgreSQL 데이터베이스로 지정합니다. 이 데이터베이스는 장치 권한 부여 및 속도 제한 카운터를 보유합니다.
110
111| 필드 | 필수 | 설명 |
112| ----------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113| `postgres_url` | 예 | `postgres://` 또는 `postgresql://` URL. 필수: 장치 권한 부여 랑데부(브라우저 콜백이 쓰고 폴링 CLI가 읽음)는 교차 복제본 상태가 필요합니다. 게이트웨이는 부팅 시 자체 스키마 마이그레이션을 실행하므로 역할은 대상 스키마에 대해 `CREATE TABLE`이 필요합니다. 보안 정책이 애플리케이션 역할의 DDL을 금지하는 경우 관리자 역할로 마이그레이션을 실행하고(초기에 그리고 새 릴리스가 마이그레이션을 제공할 때마다 다시) 앱 역할에 게이트웨이의 테이블에 대해 `SELECT, INSERT, UPDATE, DELETE`를 부여합니다. [업그레이드](/ko/claude-apps-gateway-deploy#upgrades) 및 [Postgres](/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. |
114| `username` | 아니요 | `postgres_url`의 사용자를 재정의합니다 |
115| `password` | 아니요 | 데이터베이스 자격증명. 자격증명이 URL에서 벗어나도록 `postgres_url`이 아닌 여기에 설정합니다. 모든 문자를 허용하고 URL 자격증명보다 우선합니다. |
116| `max_connections` | 아니요 | 복제본당 Postgres 연결 풀 크기. 기본값 `5`(보수적이고 공유 데이터베이스에 친화적). [지출 한도](#admin)가 활성화되면 핫 경로는 추론 요청당 몇 가지 작업을 수행하므로 로드 아래의 전용 데이터베이스에 대해 올리고 복제본 × 이를 데이터베이스의 `max_connections` 아래로 유지합니다. |
117
118로컬 개발의 경우 `postgres_url`을 일회용 Postgres 컨테이너로 지정합니다(예: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`).
119
120<h3 id="upstreams">
121 `upstreams`
122</h3>
123
124`upstreams`는 정렬된 목록입니다. 게이트웨이는 요청된 모델을 확인하는 첫 번째 업스트림으로 추론을 전달합니다. `5xx`, `429` 또는 시간 초과 시 다음으로 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. 이러한 오류는 업스트림이 아닌 요청에 기인하기 때문입니다. 동일한 공급자의 여러 업스트림은 고유한 `name:`을 설정해야 합니다.
125
126Bedrock, Agent Platform 및 Foundry 클라이언트는 시작 시 한 번 구축되며 SDK는 자격증명을 내부적으로 새로 고치므로 클라우드 자격증명을 회전해도 재시작이 필요하지 않습니다. 정적 Anthropic API 키 및 베어러는 시작 시 읽혀집니다. [Anthropic API](#anthropic-api)를 참조하세요.
127
128<h4 id="anthropic-api">
129 Anthropic API
130</h4>
131
132최소 Anthropic 업스트림은 [Claude 콘솔](https://platform.claude.com)의 API 키입니다:
133
134```yaml theme={null}
135upstreams:
136 - provider: anthropic
137 auth:
138 api_key: ${ANTHROPIC_API_KEY}
139 # 또는 OAuth 베어러(예: Workload-Identity-Federation 교환 토큰):
140 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
141 # base_url: https://api.anthropic.com # 기본값; 전달 프록시에 대해 재정의
142```
143
144두 자격증명 형식은 전송하는 헤더가 다릅니다:
145
146* **`api_key`**: `x-api-key`를 보냅니다. Claude 콘솔에서 회전하고 환경 변수를 업데이트합니다.
147* **`oauth_token`**: `Authorization: Bearer`를 보냅니다. 조직이 장기 API 키 대신 단기 토큰을 발급할 때 베어러 형식을 사용합니다. 베어러는 시작 시 한 번 읽혀지므로 비밀을 다시 마운트하고 재시작하여 새로 고칩니다.
148
149정적 키 또는 베어러 대신 Workload Identity Federation을 사용할 수 있습니다. [Workload Identity Federation 가이드](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)를 따라 페더레이션 규칙을 만든 후 Kubernetes 프로젝트된 서비스 계정 토큰 또는 CI 플랫폼의 id-token과 같은 파일로 워크로드의 OIDC JWT를 마운트합니다. 게이트웨이는 JWT를 단기 베어러로 교환하고 자동으로 새로 고칩니다. 토큰 파일은 모든 교환에서 다시 읽혀지므로 회전된 프로젝트된 토큰은 재시작 없이 선택됩니다.
150
151```yaml theme={null}
152upstreams:
153 - provider: anthropic
154 auth:
155 federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
156 organization_id: ${ANTHROPIC_ORGANIZATION_ID}
157 identity_token_file: /var/run/secrets/anthropic/id-token
158 # workspace_id: wrkspc_... # 규칙이 >1 워크스페이스를 다루는 경우 필수
159 # service_account_id: svac_... # 선택적 예상 대상 확인
160```
161
162<h4 id="amazon-bedrock">
163 Amazon Bedrock
164</h4>
165
166게이트웨이가 대체하거나 앞에 있는 클라이언트 측 Bedrock 배포의 경우 [Amazon Bedrock의 Claude Code](/ko/amazon-bedrock)를 참조하세요. 게이트웨이 측 업스트림:
167
168```yaml theme={null}
169upstreams:
170 - provider: bedrock
171 region: us-east-1
172 auth: {} # 선호: AWS 기본 자격증명 체인
173 # 또는 명시적 자격증명:
174 # auth:
175 # aws_access_key_id: ${AWS_AKID}
176 # aws_secret_access_key: ${AWS_SK}
177 # aws_session_token: ${AWS_ST}
178 # 또는 Bedrock API 베어러 토큰:
179 # auth:
180 # aws_bearer_token: ${AWS_BEARER_TOKEN}
181 # FIPS 또는 VPC 엔드포인트 배포를 위해 bedrock-runtime 엔드포인트를 재정의합니다:
182 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
183```
184
185빈 `auth` 블록은 AWS SDK의 기본 자격증명 체인을 사용합니다: 환경 변수, `~/.aws/credentials`, ECS 작업 역할, EC2 인스턴스 메타데이터 또는 EKS의 IRSA. 프로덕션에서는 컨테이너 이미지에 정적 키를 포함하는 대신 게이트웨이 포드에 IAM 역할을 제공합니다.
186
187| 설정 | 방법 |
188| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
189| IAM 권한 | 게이트웨이의 주체에 추론 프로필 ARN 및 기본 기초 모델 ARN 모두에 대해 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 부여합니다. US 지역의 기본 제공 카탈로그의 경우: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 및 `arn:aws:bedrock:*::foundation-model/anthropic.*`. |
190| 모델 액세스 | Bedrock 콘솔에서 지역별로 원하는 Claude 모델에 대한 모델 액세스를 요청하고 활성화합니다. 교차 지역 추론 프로필(`us.anthropic.*`)은 프로필이 걸쳐 있는 각 지역에서 모델 액세스가 필요합니다. |
191| EKS(IRSA) | 위의 정책과 클러스터의 OIDC 공급자로 범위가 지정된 신뢰 정책이 있는 IAM 역할을 만듭니다. 게이트웨이의 서비스 계정에 `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`로 주석을 답니다. `auth: {}`가 선택합니다. |
192| ECS / EC2 | IAM 역할을 작업 정의 또는 인스턴스 프로필에 연결합니다. `auth: {}`가 선택합니다. |
193| 다른 곳 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` 및 `AWS_SESSION_TOKEN` 환경 변수를 통해 자격증명을 전달하거나 `auth:`에서 `${VAR}` 확장으로 명시적으로 설정합니다 |
194| 지역 | `region:`은 API 엔드포인트 지역입니다. 교차 지역 추론 프로필은 선택한 지역과 무관하게 지역(US, EU, APAC)을 통해 라우팅합니다. US가 아닌 지역 또는 프로비저닝된 처리량 ARN의 경우 올바른 업스트림별 ID가 있는 [`models:`](#models) 블록을 추가합니다. |
195
196<h4 id="google-cloud-agent-platform">
197 Google Cloud Agent Platform
198</h4>
199
200동등한 클라이언트 측 설정의 경우 [Google Cloud의 Claude Code](/ko/google-vertex-ai)를 참조하세요. 게이트웨이 측 업스트림:
201
202```yaml theme={null}
203upstreams:
204 - provider: vertex
205 region: us-east5
206 project_id: example-prod
207 auth: {} # 선호: Application Default Credentials
208 # 또는 서비스 계정 키 파일:
209 # auth: { service_account_json: /secrets/sa.json }
210 # Private Service Connect를 위해 aiplatform 엔드포인트를 재정의합니다:
211 # base_url: https://us-east5-aiplatform.p.googleapis.com
212```
213
214빈 `auth` 블록은 Application Default Credentials를 사용합니다: `GOOGLE_APPLICATION_CREDENTIALS`, GCE 메타데이터 또는 GKE Workload Identity. 서비스 계정 JSON 키 파일은 지원되지만 권장되지 않습니다. Workload Identity를 사용하거나 GCE 또는 Cloud Run 인스턴스에 서비스 계정을 연결합니다.
215
216`region: global`을 설정하여 지역 엔드포인트 대신 [Agent Platform의 글로벌 엔드포인트](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)를 사용합니다. Google은 각 요청을 사용 가능한 지역으로 라우팅하므로 지역별 모델 가용성을 추적하지 않습니다. 특정 지역을 설정하면 모든 요청이 해당 지역에 고정됩니다.
217
218| 설정 | 방법 |
219| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220| IAM 권한 | 게이트웨이의 서비스 계정에 프로젝트에 대해 `roles/aiplatform.user`를 부여하거나 `aiplatform.endpoints.predict`가 있는 사용자 정의 역할을 부여합니다. Agent Platform API(`aiplatform.googleapis.com`)를 활성화합니다. |
221| 모델 액세스 | Model Garden에서 프로젝트에 대해 Claude 모델을 활성화합니다. 특정 지역에 게시합니다. 지원되는 지역은 모델 카드를 확인하세요. |
222| GKE(Workload Identity) | GCP 서비스 계정을 게이트웨이의 Kubernetes 서비스 계정에 바인드하고 KSA에 `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`으로 주석을 답니다. `auth: {}`가 선택합니다. |
223| Cloud Run / GCE | 서비스의 서비스 계정을 `roles/aiplatform.user`가 있는 것으로 설정합니다. `auth: {}`가 선택합니다. |
224| 다른 곳 | `auth: { service_account_json: /secrets/sa.json }`, JSON 키 파일의 경로가 비밀로 마운트됩니다. 필드는 키 내용이 아닌 파일 경로를 사용하므로 `${file:…}` 확장이 관련되지 않습니다. |
225
226<h4 id="microsoft-foundry">
227 Microsoft Foundry
228</h4>
229
230클라이언트 측 Foundry 배포의 경우 [Microsoft Foundry의 Claude Code](/ko/microsoft-foundry)를 참조하세요. 게이트웨이 측 업스트림:
231
232```yaml theme={null}
233upstreams:
234 - provider: foundry
235 resource: example-foundry # https://example-foundry.services.ai.azure.com
236 auth: { use_azure_ad: true } # 선호: DefaultAzureCredential / Managed Identity
237 # 또는 API 키:
238 # auth:
239 # api_key: ${FOUNDRY_API_KEY}
240```
241
242`use_azure_ad: true`는 `DefaultAzureCredential`을 통해 확인합니다: AKS, ACI 또는 App Service의 Managed Identity, Azure CLI 또는 환경 자격증명. API 키는 작동하지만 프로젝트 전체이며 자동으로 회전하지 않습니다. Foundry의 엔드포인트는 `resource:`에서 파생됩니다. Azure Government와 같은 소주권 클라우드에 대해 선택적 `base_url`을 설정하여 재정의합니다.
243
244| 설정 | 방법 |
245| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
246| RBAC | 게이트웨이의 ID에 Foundry 리소스에 대해 `Azure AI User` 또는 `Cognitive Services User`를 부여합니다 |
247| 배포 | Foundry는 정규 모델 ID가 아닌 관리자 선택 배포 이름을 사용합니다. 각 정규 ID를 배포 이름에 매핑하는 [`models:`](#models) 블록을 추가합니다. |
248| AKS(워크로드 ID) | 사용자 할당 Managed Identity를 클러스터의 OIDC 발급자와 페더레이션하고 게이트웨이의 서비스 계정에 바인드합니다. `use_azure_ad: true`가 `WorkloadIdentityCredential`을 통해 선택합니다. |
249| ACI / App Service | 리소스에서 시스템 할당 또는 사용자 할당 관리 ID를 활성화합니다. `use_azure_ad: true`가 선택합니다. |
250| 다른 곳 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. `{ }` 내에서 `${…}`를 인용합니다. |
251
252<h4 id="multiple-upstreams">
253 여러 업스트림
254</h4>
255
256동일한 공급자는 고유한 `name:`으로 두 번 이상 나타날 수 있습니다. 이는 다양한 지역, 다양한 자격증명 체인을 통한 다양한 계정, 프로비저닝된 처리량 대 온디맨드 및 교차 공급자 장애 조치를 다룹니다.
257
258게이트웨이는 순서대로 업스트림을 시도합니다. `5xx`, `429`, 시간 초과 및 누락된 엔드포인트(`501`)는 장애 조치합니다. 다른 `4xx`는 그렇지 않습니다. `429`는 업스트림별 용량이므로 프로비저닝된 처리량(PT) 소진은 온디맨드로 장애 조치합니다. 요청된 모델을 확인할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.
259
260이 예제는 프로비저닝된 처리량 Bedrock 할당을 먼저 라우팅하고, 온디맨드 및 두 번째 계정으로 오버플로우하며, 마지막으로 Anthropic API로 장애 조치합니다:
261
262```yaml theme={null}
263upstreams:
264 # 기본: 홈 지역의 프로비저닝된 처리량.
265 - name: bedrock-pt
266 provider: bedrock
267 region: us-east-1
268 auth: {}
269 # 오버플로우: 온디맨드 교차 지역.
270 - name: bedrock-od
271 provider: bedrock
272 region: us-west-2
273 auth: {}
274 # 다른 계정: 가정된 역할 자격증명을 통한 별도의 Bedrock 할당.
275 - name: bedrock-acct2
276 provider: bedrock
277 region: us-east-1
278 auth:
279 aws_access_key_id: ${ACCT2_AKID}
280 aws_secret_access_key: ${ACCT2_SK}
281 # 최후의 수단: 직접 Anthropic API.
282 - name: anthropic-fallback
283 provider: anthropic
284 auth:
285 api_key: ${ANTHROPIC_API_KEY}
286
287# 업스트림별 모델 ID는 업스트림의 `name:`으로 키가 지정됩니다. `name:`이 없는 업스트림은
288# 기본값으로 공급자 문자열(예: `bedrock`)을 사용합니다. 모델에 대해 나열되지 않은 모든
289# 업스트림은 건너뜁니다. 이것이 모델을 프로비저닝된 처리량으로 라우팅하는 방법입니다.
290# 다른 모든 것은 온디맨드로 유지됩니다.
291models:
292 - id: claude-opus-4-8
293 label: Claude Opus 4.8
294 upstream_model:
295 bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
296 bedrock-od: us.anthropic.claude-opus-4-8
297 bedrock-acct2: us.anthropic.claude-opus-4-8
298 anthropic-fallback: claude-opus-4-8
299```
300
301| 레버 | 방법 |
302| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
303| 다른 지역 | 지역당 하나의 Bedrock 업스트림, 각각 자신의 `region:`. [`auto_include_builtin_models: true`](#models)를 사용하면 교차 지역 추론 프로필이 자동으로 라우팅됩니다. 지역 고정 배포의 경우 `models:` 블록을 사용합니다. |
304| 다른 계정 | 계정당 하나의 Bedrock 업스트림, 각각 `auth:`의 자신의 자격증명. 기본 체인(`auth: {}`)은 포드의 ID를 사용합니다. 두 번째 계정의 경우 명시적 자격증명 또는 베어러 토큰을 설정합니다. |
305| 프로비저닝된 처리량 | 해당 업스트림의 이름에 대해 `models:`에서 모델을 프로비저닝된 처리량 ARN에 매핑합니다. 다른 업스트림은 온디맨드 ID를 유지하므로 PT 용량이 장애 조치 전에 소진됩니다. |
306| VPC / FIPS 엔드포인트 | 업스트림에서 `base_url:`을 VPC 엔드포인트 또는 FIPS 엔드포인트 URL로 설정합니다 |
307| 모델 범위 라우팅 | 모델의 `upstream_model:` 맵에서 업스트림을 생략하면 해당 업스트림은 해당 모델에 대해 건너뜁니다. 예를 들어 Opus를 프로비저닝된 처리량으로 라우팅하고 Sonnet 및 Haiku를 온디맨드로 라우팅합니다. |
308
309클라우드 공급자 간 또는 직접 Anthropic API로 장애 조치하면 요청을 관리하는 계약, 지역 및 기타 약관이 변경됩니다.
310
311CLI는 어느 업스트림이 주어진 요청을 제공하는지와 무관하게 게이트웨이에 동일한 기능 게이팅을 적용하므로 장애 조치는 업스트림이 거부할 본문 필드를 보내지 않습니다.
312
313<h2 id="optional-sections">
314 선택 사항 섹션
315</h2>
316
317<h3 id="admin">
318 `admin`
319</h3>
320
321선택 사항. Anthropic의 공개 관리자 API를 미러링하는 `/v1/organizations/spend_limits`를 활성화하고 `/v1/messages`에서 개발자별 지출 적용을 활성화합니다. 한도가 설정되고 적용되는 방법은 [지출 한도](/ko/claude-apps-gateway-spend-limits)를 참조하세요. 이 섹션은 기능을 켜고 조정하는 `gateway.yaml` 키를 다룹니다.
322
323```yaml theme={null}
324admin:
325 # 관리자 엔드포인트에 대한 명명된 정적 API 키, x-api-key로 전송됨.
326 # id는 감사 로그에 admin-key:<id>로 나타나므로 각 키는
327 # 귀속 가능합니다. 회전용 배열: 새 키를 추가하고 클라이언트를 롤링하고
328 # 이전 키를 제거합니다.
329 write_keys:
330 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
331 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
332 read_keys:
333 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
334 # 일반 게이트웨이 JWT를 통해 전체 관리자 권한이 부여된 IdP 그룹(API 키 없음).
335 admin_groups: [platform-finops]
336 blocked_message: request an increase at https://go.example.com/claude-limits
337```
338
339| 필드 | 필수 | 설명 |
340| ------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
341| `write_keys` | 아니요 | `{id, key}` 배열. 이 중 하나와 일치하는 `x-api-key`는 지출 한도를 나열, 설정 및 삭제할 수 있습니다. 키 값은 최소 32자여야 합니다. `id`는 `read_keys` 및 `write_keys`에서 고유해야 합니다. |
342| `read_keys` | 아니요 | `{id, key}` 배열. 읽기 전용: 모든 `GET` 엔드포인트, 한도 나열, ID별 가져오기 및 [`/effective`](/ko/claude-apps-gateway-spend-limits#%2Feffective) 및 [`/audit`](/ko/claude-apps-gateway-spend-limits#%2Faudit) 읽기 포함. |
343| `admin_groups` | 아니요 | IdP 그룹 이름. `groups` 클레임이 이 중 하나를 포함하는 게이트웨이 JWT는 전체 관리자 액세스(읽기 및 쓰기)를 가지며 `oidc:<sub>`로 감사합니다. 인간 관리자에게 사용합니다. 기계에는 API 키를 사용합니다. |
344| `blocked_message` | 아니요 | 차단된 개발자가 보는 `429 billing_error`에 그대로 추가됩니다. URL 또는 Slack 채널과 같은 전체 지침을 작성합니다. 설정하지 않으면 오류는 `spend limit reached`입니다. |
345| `audit_retention_days` | 아니요 | 기본값 `365`. 더 오래된 `admin_audit` 행은 정리됩니다. |
346| `spend_retention_months` | 아니요 | 기본값 `13`. 이보다 오래된 `spend` 카운터 행은 정리됩니다. 기본값은 연간 비교 보고를 위해 전체 연도와 현재 부분 월을 유지합니다. |
347| `identity_retention_days` | 아니요 | 기본값 `90`. `principal_emails` 행의 마지막 표시 TTL(각 개발자의 이메일, 표시 이름 및 그룹 포함, PII). 의도적으로 지출 보유보다 짧으므로 프로비저닝 해제된 ID는 익명 지출 카운터가 유지되는 동안 만료됩니다. |
348| `group_limit_mode` | 아니요 | `min`(기본값) 또는 `max`. 개발자가 한도가 있는 여러 그룹에 있을 때 `min`은 가장 제한적인 것을 적용하고 `max`는 가장 제한적이지 않은 것을 적용합니다. 적용 및 `/effective` 모두에서 사용됩니다. |
349
350<h3 id="enforcement">
351 `enforcement`
352</h3>
353
354`enforcement` 블록은 저장소를 사용할 수 없을 때 지출 한도 확인이 어떻게 동작하는지 제어합니다.
355
356| 필드 | 필수 | 설명 |
357| ---------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
358| `fail_closed_on_error` | 아니요 | 기본값 `false`. 지출 적용은 Postgres 중단 시 개방되므로 추론이 계속됩니다. `true`로 설정하여 폐쇄: 초과 용량 개발자는 차단되지만 저장소에 도달할 수 없으면 모두가 차단됩니다. [`admin:`](#admin) 블록 없이는 효과가 없습니다. |
359
360<h3 id="models">
361 `models`
362</h3>
363
364`models` 블록은 선택적 관리자 선별 모델 목록이며 `/v1/models`에서 제공되고 업스트림별 모델 ID를 변환하는 데 사용됩니다. US가 아닌 Bedrock 지역, Bedrock 프로비저닝된 처리량 ARN 및 Foundry 배포 이름에 필수입니다.
365
366```yaml theme={null}
367auto_include_builtin_models: true # false: 아래 목록만 노출
368models:
369 - id: claude-opus-4-8
370 label: Claude Opus 4.8
371 # description: 선택적 텍스트가 표시되는 클라이언트에 표시됨
372 upstream_model:
373 anthropic: claude-opus-4-8
374 bedrock: us.anthropic.claude-opus-4-8 # 또는 추론 프로필 ARN
375 foundry: your-opus-deployment-name
376```
377
378<h3 id="managed">
379 `managed`
380</h3>
381
382`managed` 블록은 IdP 그룹 또는 이메일 도메인을 기반으로 하는 역할 기반 액세스 정책을 정의합니다. 정책은 순서대로 평가됩니다. 첫 번째 일치가 선택되고 아래에 설명된 `match: {}` 캐치올 기본에 병합됩니다. 사용자별로 `GET /managed/settings`에서 ETag/304 캐싱으로 제공됩니다.
383
384```yaml theme={null}
385managed:
386 policies:
387 # 특정 그룹을 먼저.
388 - match: { groups: [eng-contractors] }
389 cli:
390 availableModels: [claude-sonnet-4-6]
391 permissions: { deny: ["WebFetch", "WebSearch"] }
392 # 기본 캐치올 마지막: 인증된 모든 사용자와 일치.
393 - match: {}
394 cli:
395 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
396```
397
398`match: {}` 캐치올(관례상 마지막에 나열됨)은 기본 계층으로 처리됩니다. 모든 다른 정책은 설정하지 않은 모든 키를 캐치올에서 상속하므로 역할별 항목은 조직 기본값과 다른 것만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다:
399
400* **허용 목록**: `availableModels` 및 `permissions.allow`. 특정 정책의 목록은 기본값을 완전히 대체합니다.
401* **거부 목록 및 후크 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` 및 모든 `hooks` 이벤트 유형 배열. 이들은 기본값과 정책의 합집합을 사용하므로 조직 전체 거부 또는 감사 후크는 역할별 재정의로 실수로 삭제될 수 없습니다.
402* **레코드 유형 키**: `env`, `modelOverrides` 및 `skillOverrides`. 이들은 얕게 병합되므로 역할별 `env` 블록은 설정하는 키를 재정의하고 나머지는 기본값에서 상속합니다.
403
404`availableModels`는 또한 `/v1/messages`에서 서버 측으로 적용되므로 거부된 모델은 클라이언트가 보내는 것과 무관하게 `400`을 반환합니다.
405
406| 매처 | 동작 |
407| --------------------------------------------------- | --------------------------------------------------------------------------------- |
408| `match: {}` | 인증된 모든 사용자와 일치합니다. 이 중 하나로 시작하고 나중에 그룹 범위 정책을 위에 추가합니다. |
409| `match: { groups: [a, b] }` | JWT의 `groups` 클레임이 나열된 그룹 중 하나를 포함하면 일치합니다. 대소문자 구분: 그룹은 IdP의 정확한 대소문자와 일치해야 합니다. |
410| `match: { email_domain: example.com }` | JWT의 `email` 클레임에서 마지막 `@` 뒤의 부분과 일치합니다(대소문자 구분 안 함). 정책당 하나의 도메인을 허용합니다. |
411| `match: { groups: [a], email_domain: example.com }` | 두 조건 모두 일치해야 합니다 |
412
413정책과 일치하지 않는 인증된 사용자는 게이트웨이의 기본값을 가져옵니다. 이는 카탈로그의 모든 모델과 관리형 설정이 없음을 의미합니다. 보장된 기본 정책을 원하면 마지막에 `match: {}` 캐치올을 추가합니다.
414
415<Note>
416 게이트웨이는 자신의 사용자 디렉토리를 유지하지 않습니다. 사용자의 IdP 토큰에서 각 요청을 승인하고 토큰의 `groups` 클레임에서 그룹 멤버십을 읽으며 이에 대해 정책을 평가합니다. 열거할 명단이 없고 사전 생성할 계정이 없으므로 SCIM 엔드포인트가 없습니다. 동기화할 것이 없기 때문입니다.
417
418 사용자 및 그룹 수명 주기 관리를 진실의 원본(IdP의 기본 SCIM 프로비저닝 또는 전용 ID 거버넌스 플랫폼)에서 실행합니다. 거기서 관리되는 멤버십 및 프로비저닝 해제는 토큰을 통해 게이트웨이에 자동으로 흐릅니다. Claude 계정 자체의 SCIM 프로비저닝을 원하면 이는 [Claude for Enterprise](/ko/admin-setup) 기능입니다.
419
420 두 가지 전파 시계가 적용됩니다:
421
422 * **정책 내용**: 정책을 편집하고 재배포하면 연결된 클라이언트가 다음 관리형 설정 폴링 시 1시간 이내에 도달합니다.
423 * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 어떤 정책이 일치하는지 변경됩니다. 이는 다음 세션 재발급 시(다음 자동 새로 고침 의미)에 적용되며 `session.ttl_hours`로 제한됩니다.
424</Note>
425
426<h4 id="what-goes-in-cli">
427 `cli`에 들어가는 것
428</h4>
429
430각 `cli` 값은 완전한 Claude Code `managed-settings.json` 문서이며, MDM 또는 `/etc/claude-code/managed-settings.json`을 통해 배포할 동일한 스키마이며, 여기서는 YAML로 표현됩니다. CLI는 관리형 계층에서 전달된 문서를 적용합니다. 사용자 및 프로젝트 설정 위에 있습니다.
431
432게이트웨이는 부팅 시 각 문서를 CLI의 설정 스키마에 대해 검증하므로 인식되지 않는 최상위 키 또는 인식되지만 잘못된 형식의 값이 있는 키는 모든 위반 키의 이름을 지정하는 오류로 부팅을 실패합니다. 의도적으로 개방된 스키마 부분은 여전히 임의의 값을 허용합니다. 더 새로운 클라이언트가 게이트웨이의 스키마가 인식하지 못하는 항목을 인식할 수 있기 때문입니다. 이러한 개방 키는 `env`, `pluginConfigs` 및 `permissions` 아래에 중첩된 키입니다.
433
434검증이 게이트웨이의 설치된 버전과 함께 번들된 스키마를 사용하므로 더 새로운 Claude Code 릴리스에서 도입된 최상위 설정 키를 관리형 구성에 넣으려면 먼저 게이트웨이를 업그레이드해야 합니다. 한 클라이언트에서 새 정책을 연기 테스트한 후 롤아웃합니다.
435
436전체 키 참조는 [Claude Code 설정](/ko/settings#available-settings)에 있습니다. 운영자가 먼저 도달하는 키:
437
438```yaml theme={null}
439managed:
440 policies:
441 - match: {}
442 cli:
443 # 모델 액세스(/v1/messages에서도 서버 측으로 적용됨)
444 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
445
446 # 권한 정책
447 permissions:
448 deny:
449 - "WebFetch"
450 - "Read(./.env)"
451 - "Read(./secrets/**)"
452 disableBypassPermissionsMode: disable # --dangerously-skip-permissions 차단
453 allowManagedPermissionRulesOnly: true # 사용자/프로젝트 권한 규칙 무시
454
455 # CLI 프로세스에 푸시된 환경. DISABLE_UPDATES는 배경 및 수동 업데이트를 차단합니다.
456 # DISABLE_AUTOUPDATER는 배경 업데이트만 중지합니다.
457 env:
458 DISABLE_UPDATES: "1" # 자신의 배포를 통해 버전 고정
459
460 # 조직 전체 후크. 후크 명령은 게이트웨이가 아닌 개발자 머신에서 실행되므로
461 # 경로는 정책의 모든 클라이언트 OS에 존재해야 합니다.
462 hooks:
463 PostToolUse:
464 - matcher: "Edit|Write"
465 hooks:
466 - { type: command, command: /usr/local/bin/audit-edit.sh }
467```
468
469| 키 | 적용 대상 | 효과 |
470| ------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
471| `availableModels` | 게이트웨이 + CLI | 모델 허용 목록. `/v1/messages`에서도 확인되므로 패치된 클라이언트는 이를 우회할 수 없습니다. |
472| `permissions.allow` / `.deny` | CLI | 도구 및 명령 규칙. [권한](/ko/permissions)을 참조하세요. |
473| `permissions.disableBypassPermissionsMode` | CLI | [`bypassPermissions`](/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 모드를 차단하도록 `disable`으로 설정하고 `--dangerously-skip-permissions` 플래그 |
474| `allowManagedPermissionRulesOnly` | CLI | `true`일 때 사용자 및 프로젝트 권한 규칙은 무시됩니다. 이 문서의 규칙만 적용됩니다 |
475| `env` | CLI | CLI 프로세스에 병합된 환경 변수. 텔레메트리, 자동 업데이트 및 모델 이름 재정의에 사용합니다. |
476| `hooks` | CLI | 조직 전체 [후크](/ko/hooks) |
477
478이러한 설정은 네트워크를 통해 도착하므로 CLI는 각 개발자에게 셸 명령을 실행하거나 트래픽이 가는 위치를 변경할 수 있는 모든 것을 적용하기 전에 일회성 보안 승인 대화를 표시합니다. 대화는 다음을 다룹니다:
479
480* `hooks`
481* CLI의 기본 제공 안전 목록에 없는 `env` 변수
482* `apiKeyHelper` 및 `statusLine`과 같은 셸 실행 설정
483* 관리형 CLAUDE.md 내용
484
485안전 목록은 어떤 `env` 변수가 승인 없이 적용되는지 결정합니다:
486
487* **안전 목록에 있음**: 자동 업데이트 및 모델 이름 변수
488* **안전 목록에 없음**: 프록시 변수, 기본 URL 변수 및 `OTEL_EXPORTER_OTLP_ENDPOINT`
489
490게이트웨이의 [텔레메트리](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로 `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화를 트리거합니다. `-p` 플래그를 사용한 비대화형 실행은 대화를 건너뛰고 승인 없이 설정을 적용합니다. 대화는 조직으로부터 개발자를 보호하지 않고 손상되거나 적대적인 게이트웨이로부터 개발자의 머신을 보호하므로 `-p` 건너뛰기는 의도적입니다.
491
492개발자가 거부하면 Claude Code는 정책을 적용하지 않고 종료됩니다. 새 후크 또는 비안전 env 변수를 광범위한 정책에 푸시하면 일치하는 모든 개발자의 다음 시작 시 승인 프롬프트가 표시됩니다.
493
494`cli` 키는 이전 릴리스에서 `settings`로 명명되었습니다. 해당 철자는 여전히 별칭으로 허용되지만 새 배포는 `cli`를 사용해야 합니다.
495
496<h4 id="precedence-with-other-managed-sources">
497 다른 관리형 소스와의 우선순위
498</h4>
499
500장치에 로컬 `managed-settings.json` 또는 MDM 전달 정책도 있으면 관리형 소스는 병합되지 않습니다. 가장 높은 우선순위 소스는 모든 정책 설정을 제공하며 다음 순서로 순위가 지정됩니다(가장 높은 우선순위 먼저):
501
5021. [정책 도우미](/ko/settings#compute-managed-settings-with-a-policy-helper)
5032. 게이트웨이 전달 설정
5043. MDM, Windows의 HKLM 레지스트리 또는 macOS의 plist를 통해
5054. `managed-settings.json` 파일
5065. HKCU 레지스트리(Windows만 해당)
507
508포함 호스트는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. 기본적으로 무시되며 관리형 소스가 [`parentSettingsBehavior: "merge"`](/ko/settings#available-settings)로 옵트인할 때만 적용되며, 정책을 강화할 수 있지만 완화할 수 없도록 필터링됩니다.
509
510예외는 모든 관리형 소스가 설정할 때 적용되는 작은 키 집합입니다. 사용자 쓰기 가능 HKCU 계층은 제외됩니다:
511
512* `sandbox.network.allowManagedDomainsOnly` 및 `sandbox.filesystem.allowManagedReadPathsOnly`: 잠금 시 해당 허용 목록은 소스 전체에서 합집합됩니다.
513* [`allowAllClaudeAiMcps`](/ko/settings#available-settings): claude.ai MCP 서버 허용 목록에 대한 허용 전용 재정의
514* `sandbox.bwrapPath` 및 `sandbox.socatPath`: [샌드박스](/ko/sandboxing) 도우미 바이너리의 파일 시스템 경로
515
516`allowManagedPermissionRulesOnly` 및 `disableBypassPermissionsMode`는 교차 소스가 아니므로 승리한 소스의 값만 적용됩니다. 설정 페이지의 동일한 규칙은 [설정 우선순위](/ko/settings#settings-precedence)를 참조하세요.
517
518게이트웨이 정책은 비대화형 `claude -p` 실행 및 Agent SDK에서 생성된 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. 게이트웨이가 시작 시 도달할 수 없으면 서명된 세션은 정책 없이 실행하지 않고 오류로 종료됩니다.
519
520<Warning>
521 정책의 `cli` 블록 내의 `mcpServers`는 게이트웨이 부팅 시 거부됩니다. 그룹별 MCP 배포는 사용할 수 없습니다. 각 장치에서 파일 기반 `managed-mcp.json`을 통해 MCP 서버를 배포하거나 개발자가 로컬로 추가하도록 합니다.
522</Warning>
523
524<h3 id="telemetry">
525 `telemetry`
526</h3>
527
528CLI는 OpenTelemetry Protocol(OTLP) over HTTP 메트릭, 로그 및 활성화 시 추적을 게이트웨이로 보내며, 게이트웨이는 각 구성된 대상으로 그대로 중계합니다. CLI가 내보내는 메트릭 및 이벤트는 [사용 모니터링](/ko/monitoring-usage)을 참조하세요.
529
530CLI는 각 내보내기에 게이트웨이 발급 JWT에서 읽은 인증된 사용자의 ID를 스탬프합니다: `user.id`, `user.email` 및 `user.groups` 속성. 개발자별 비용 및 사용 귀속은 개발자 측 구성 없이 작동합니다.
531
532```yaml theme={null}
533telemetry:
534 forward_to:
535 - url: https://otel-collector.internal.example.com
536 headers:
537 Authorization: ${OTLP_TOKEN}
538 # 신호별 옵트인. 기본값: 메트릭만.
539 metrics: true
540 logs: false
541 traces: false
542 - url: https://api.datadoghq.com/api/v2/otlp
543 headers:
544 DD-API-KEY: ${DD_API_KEY}
545```
546
547<Warning>
548 각 대상은 `metrics`, `logs` 및 `traces`에 독립적으로 옵트인하며 기본값은 메트릭만입니다. 신호는 민감도가 다릅니다:
549
550 * **메트릭**: 토큰 수, 요청 수 및 지연 시간과 같은 집계 카운터
551 * **로그 및 추적**: 전체 bash 명령, 도구 입력 및 파일 경로를 전달할 수 있으며 Claude Code가 개발자 머신에서 수행하는 모든 것을 다룹니다.
552
553 로그 및 추적은 해당 데이터가 보증하는 액세스 제어 및 보유 정책이 있는 대상에서만 활성화합니다.
554</Warning>
555
556텔레메트리는 CLI에서 기본적으로 꺼져 있습니다. `telemetry.forward_to`를 `listen.public_url`과 함께 구성하면 켜집니다. 게이트웨이는 `/managed/settings`를 통해 모든 연결된 클라이언트에 5개의 환경 변수를 푸시합니다:
557
558* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
559* `OTEL_METRICS_EXPORTER=otlp`
560* `OTEL_LOGS_EXPORTER=otlp`
561* `OTEL_TRACES_EXPORTER=otlp`
562* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
563
564푸시된 엔드포인트는 공개 URL에서 구축되므로 메트릭 및 로그는 개발자 또는 정책의 OTEL 구성이 필요하지 않습니다. 푸시된 구성은 관리형 계층에서 적용되어 개발자가 로컬로 설정하는 `OTEL_*` 변수를 재정의합니다.
565
566[추적](/ko/monitoring-usage#traces-beta)은 추가로 각 클라이언트에서 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`이 필요합니다. 게이트웨이는 해당 변수를 푸시하지 않으므로 관리형 정책의 `env` 블록을 통해 설정합니다. CLI의 안전 목록에 없으므로 정책을 통해 전달하는 것은 푸시된 OTLP 엔드포인트가 이미 트리거하는 동일한 [보안 승인 대화](#managed)로 다룹니다.
567
568Protobuf 및 JSON OTLP 인코딩 모두 중계되며 모든 OpenTelemetry 호환 백엔드가 대상으로 작동합니다.
569
570<h3 id="http-tuning">
571 HTTP 조정
572</h3>
573
5744개의 선택적 최상위 블록 `access_control`, `limits`, `timeouts` 및 `rate_limits`는 HTTP 표면을 조정합니다. 기본값은 대부분의 배포에 적합합니다.
575
576| 블록 | 키 | 기본값 | 설명 |
577| ---------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
578| `access_control` | `allow_cidrs` / `deny_cidrs` | 비어 있음 | 클라이언트 주소별 인바운드 IP 허용/거부, `trusted_proxies` 확인 후. `deny_cidrs`가 먼저 확인됩니다. 일치하는 클라이언트는 `allow_cidrs`도 일치하더라도 거부됩니다. `allow_cidrs`가 비어 있지 않으면 게이트웨이는 기본 거부입니다. `/healthz` 및 `/readyz`는 `allow_cidrs`에서 제외됩니다. |
579| `limits` | `max_request_bytes` | 32 MiB | 최대 인바운드 요청 본문. 크기 초과 요청은 본문이 버퍼링되기 전에 `413`을 가져옵니다. 큰 파일 또는 이미지 요청에 대해 올립니다. |
580| `limits` | `max_request_header_bytes` | 설정 안 함 | 설정하면 크기 초과 헤더는 `431`을 반환합니다 |
581| `limits` | `max_url_length` | 설정 안 함 | 설정하면 과도하게 긴 URL은 `414`를 반환합니다 |
582| `timeouts` | `upstream_ttfb_ms` | 120000 | 업스트림의 응답 헤더(첫 바이트까지의 시간)를 기다리는 최대 시간. 응답 본문은 그 후 벽시계 제한 없이 스트리밍됩니다. 직접 Anthropic 업스트림 경로에 적용됩니다. Bedrock, Agent Platform 및 Foundry는 공급자 SDK의 자체 시간 초과로 제한됩니다. |
583| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 장치 인증 엔드포인트에 대한 IP당 속도 제한. 공유 송신 IP 또는 NAT 뒤의 큰 조직에 대해 올립니다. 이러한 한도는 장치 권한 부여 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 공격 저항](/ko/claude-apps-gateway-deploy#user-code-brute-force-resistance)을 참조하세요. |
584| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | `/device`에서 `user_code` 제출에 대한 IP당 속도 제한 |
585
586<h2 id="complete-example">
587 완전한 예제
588</h2>
589
590이 전체 참조 구성은 모든 핵심 섹션을 다룹니다. [HTTP 조정 블록](#http-tuning)은 기본값을 유지합니다. 복사하고 필요하지 않은 것을 삭제하고 값을 채웁니다. [빠른 시작](/ko/claude-apps-gateway#quickstart)의 구성은 이것의 최소 버전입니다.
591
592```yaml gateway.yaml theme={null}
593# 실행:
594# claude gateway --config gateway.yaml
595#
596# 운영 로그 상세도는 CLAUDE_GATEWAY_LOG_LEVEL
597# 환경 변수(info | warn | error; 기본 info)로 제어됩니다. 감사 이벤트는
598# 항상 내보내지므로 영향을 주지 않습니다.
599
600listen:
601 host: 0.0.0.0
602 port: 8080
603 public_url: https://claude-gateway.internal.example.com
604 # TLS 종료 ingress 뒤에서 실행할 때 tls 블록을 생략합니다.
605 # tls:
606 # cert: /certs/gateway.crt
607 # key: /certs/gateway.key
608 # trusted_proxies:
609 # - 10.0.0.0/8
610
611oidc:
612 issuer: https://example.okta.com
613 client_id: 0oa1example2
614 client_secret: ${OIDC_CLIENT_SECRET}
615 allowed_email_domains:
616 - example.com
617 # Okta org 서버가 발급자인 경우 필수. id_token은
618 # 이메일 및 그룹을 생략할 수 있습니다. 게이트웨이는 /userinfo에서 채웁니다.
619 userinfo_fallback: true
620 # allowed_groups: [claude-code-users]
621 # Okta는 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가
622 # 허용할 때만 그룹을 내보냅니다. 아래의 계약자 정책은
623 # 그룹과 일치하므로 범위가 여기에서 요청됩니다.
624 scopes: [openid, profile, email, offline_access, groups]
625 # extra_auth_params: { access_type: offline, prompt: consent } # Google
626 # groups_claim: groups # Entra 앱 역할: `roles` 사용
627 # email_claim: email
628
629session:
630 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32
631 # ttl_hours: 1
632
633store:
634 postgres_url: ${GATEWAY_POSTGRES_URL}
635 # max_connections: 5
636
637# /v1/organizations/spend_limits(Anthropic Admin API를 미러링함)를 활성화합니다.
638# 및 /v1/messages에서 개발자별 지출 적용. 비활성화하려면 생략합니다.
639# 한도 자체는 관리자 API를 통해 설정되며 여기에서는 설정되지 않습니다.
640# admin:
641# write_keys:
642# - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
643# read_keys:
644# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
645# admin_groups: [platform-finops]
646# blocked_message: request an increase at https://go.example.com/claude-limits
647# # audit_retention_days: 365
648# # spend_retention_months: 13
649# # identity_retention_days: 90
650# # group_limit_mode: min
651
652# enforcement:
653# fail_closed_on_error: false
654
655upstreams:
656 - provider: anthropic
657 auth:
658 api_key: ${ANTHROPIC_API_KEY}
659
660 # - provider: bedrock
661 # region: us-east-1
662 # auth: {}
663
664 # - provider: vertex
665 # region: us-east5
666 # project_id: example-prod
667 # auth: {}
668
669 # - provider: foundry
670 # resource: example-foundry
671 # auth: { use_azure_ad: true }
672
673auto_include_builtin_models: true
674models:
675 - id: claude-opus-4-8
676 label: Claude Opus 4.8
677 upstream_model:
678 anthropic: claude-opus-4-8
679 # bedrock: us.anthropic.claude-opus-4-8
680 # vertex: claude-opus-4-8
681 # foundry: <your-opus-deployment-name>
682 - id: claude-sonnet-4-6
683 label: Claude Sonnet 4.6
684 upstream_model:
685 anthropic: claude-sonnet-4-6
686 - id: claude-haiku-4-5
687 label: Claude Haiku 4.5
688 upstream_model:
689 anthropic: claude-haiku-4-5
690
691managed:
692 policies:
693 - match: { groups: [contractors] }
694 cli:
695 availableModels: [claude-haiku-4-5]
696 # 기본 선택기 옵션을 계약자가 기본값을 얻지 않도록
697 # availableModels로 제한합니다. 그래서 계약자는 기본값에 400을 얻지 않습니다.
698 enforceAvailableModels: true
699 # allow는 이 도구를 자동 승인합니다. 나머지를 차단하지 않습니다.
700 # 도구를 제한하려면 거부 규칙을 추가합니다.
701 permissions: { allow: [Read, Grep] }
702 - match: {}
703 cli:
704 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
705 permissions:
706 allow: [Read, Grep, Bash, Edit]
707 deny: ["WebFetch"]
708 env: { HTTP_PROXY: http://proxy.example.com:8080 }
709
710telemetry:
711 forward_to:
712 - url: https://otel.internal.example.com:4318
713 headers:
714 Authorization: Bearer ${OTEL_TOKEN}
715```
716
717<h2 id="client-side-managed-settings">
718 클라이언트 측 관리형 설정
719</h2>
720
721위의 모든 것은 게이트웨이 서버를 구성합니다. 개발자 머신을 지정하는 것은 각 장치에서 Claude Code의 [관리형 설정](/ko/settings#settings-files)을 통해 별도로 구성됩니다. 게이트웨이는 클라이언트가 게이트웨이가 어디에 있는지 알려주는 키를 푸시할 수 없습니다.
722
723CLI의 경우 OS별 `managed-settings.json`에서 두 키를 모두 설정합니다:
724
725```json theme={null}
726{
727 "forceLoginMethod": "gateway",
728 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
729}
730```
731
732일반적으로 MDM 플랫폼을 통해 각 장치에 해당 파일을 배포합니다. 파일 경로는 플랫폼마다 다릅니다:
733
734| 플랫폼 | 경로 |
735| ----------- | ----------------------------------------------------------------------------------------------------------- |
736| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json` 또는 `com.anthropic.claudecode` 관리형 기본 설정 도메인 |
737| Linux 및 WSL | `/etc/claude-code/managed-settings.json` |
738| Windows | `C:\Program Files\ClaudeCode\managed-settings.json` 또는 HKLM 레지스트리를 통한 그룹 정책 |
739
740`forceLoginGatewayUrl` 및 `forceLoginMethod`의 `"gateway"` 값은 관리자 제어 관리형 계층에서만 적용됩니다. 개발자가 자신의 `~/.claude/settings.json`에서 설정하는 것은 효과가 없습니다.
741
742<h2 id="related">
743 관련
744</h2>
745
746* [Claude 앱 게이트웨이 개요](/ko/claude-apps-gateway): 빠른 시작 및 개발자 연결
747* [배포 가이드](/ko/claude-apps-gateway-deploy): IdP 설정, 컨테이너 이미지, Kubernetes 및 Cloud Run, 운영
748* [지출 한도](/ko/claude-apps-gateway-spend-limits): 개발자별 한도 및 관리자 API
