Claude 앱 게이트웨이 구성

모든 gateway.yaml 옵션에 대한 참조: 리스너 및 TLS, OIDC, 세션, Postgres 저장소, Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry 업스트림, 모델 라우팅, 관리형 정책 및 텔레메트리.

Claude 앱 게이트웨이 배포는 하나의 YAML 파일(관례상 gateway.yaml)로 구성됩니다. 이 파일은 게이트웨이가 수행하는 모든 작업을 정의합니다: 어디서 수신 대기하는지, 개발자가 어떻게 로그인하는지, 추론이 어디로 가는지, 어떤 정책과 텔레메트리가 적용되는지입니다. 이 페이지는 해당 파일의 모든 옵션에 대한 참조입니다.

첫 번째 파일을 작성하려면 빠른 시작에서 시작하세요. 이 페이지는 최소한의 작동 구성을 구축하고 실행합니다. 만족스러운 구성이 있으면 배포 가이드에서 Kubernetes, Cloud Run 또는 자신의 플랫폼에서 컨테이너화 및 호스팅하는 방법을 다룹니다.

게이트웨이는 claude gateway --config /path/to/gateway.yaml을 사용하여 시작 시 파일을 한 번 읽습니다. 모든 옵션은 부팅 시 스키마에 대해 검증되므로 잘못된 구성은 첫 사용 시가 아니라 필드 수준 오류로 시작 시 실패합니다.

이 페이지 끝의 완전한 예제는 모든 섹션을 다룹니다.

파일 구조

5개 섹션은 필수입니다. 다른 모든 섹션은 선택사항이며, 생략된 섹션은 기본값을 사용합니다. 알 수 없는 키는 부팅에 실패하므로, 오타는 자동으로 무시되는 설정이 아니라 명명된 오류로 표시됩니다.

필수 섹션:

• listen: 바인드 주소, 공개 URL, TLS 종료
• oidc: 발급자, 클라이언트, 클레임 매핑 및 로그인 가능 대상을 포함한 ID 공급자(IdP)
• session: 게이트웨이가 발급하는 베어러 토큰, 비밀 및 수명 포함
• store: 디바이스 권한 부여 및 속도 제한 카운터용 PostgreSQL
• upstreams: 추론이 이동하는 위치, Anthropic, Amazon Bedrock, AWS의 Claude Platform, Google Cloud의 Agent Platform 또는 Microsoft Foundry 여부

선택사항 섹션:

• login_notice: 개발자가 로그인할 때 표시되는 공지
• admin: Admin API 인증 및 지출 한도 보유
• enforcement: 지출 한도 실패 개방 또는 실패 폐쇄 동작
• pricing: 계약된 요금 및 지출 미터 및 개발자가 보는 비용 수치에 대한 승수
• models 및 auto_include_builtin_models: 관리자 선별 모델 목록 및 업스트림별 ID
• managed: IdP 그룹별 관리형 설정 정책
• telemetry: 관찰성 스택으로의 OTLP 전달
• access_control, limits, timeouts, rate_limits: IP 허용/거부, 요청 크기 제한, 업스트림 첫 바이트까지의 시간 및 IP별 로그인 한도
• load_test_mode: 모델 공급자를 호출하지 않고 게이트웨이 부하 테스트

비밀 확장

client_secret, jwt_secret 또는 postgres_url과 같은 비밀을 gateway.yaml에 직접 작성하지 마세요. 아래 형식 중 하나로 참조하면 게이트웨이가 부팅 시 환경 변수 또는 파일에서 값을 확인합니다:

필수 섹션

listen

listen 블록은 게이트웨이가 서비스하는 위치, 즉 바인드 주소와 포트, 외부에 노출되는 오리진, 선택적 TLS 종료를 제어합니다.

프런트엔드가 전달하는 마지막 X-Forwarded-For 항목이 어떤 개발자도 작성하지 않은 항목인 경우에만 해당 프런트엔드를 trusted_proxies에 나열하세요. 개발자가 연결하는 주소나 범위는 나열하지 마세요. 받은 각 연결의 주소를 덧붙이는 프런트엔드는 조건을 충족합니다. 개발자가 보낸 헤더를 그대로 전달하는 프런트엔드는 충족하지 않습니다.

일부 로드 밸런서처럼 ipv4:port 또는 [ipv6]:port 형식으로 작성된 X-Forwarded-For 항목은 포트를 제외하고 읽힙니다. 대괄호 없이 포트가 붙은 IPv6 주소는 다른 주소로 읽히거나 전혀 읽히지 않을 수 있습니다. 그런 형식을 작성하는 프록시에서는 포트 옵션을 끄세요.

oidc

oidc 블록은 게이트웨이를 ID 공급자에 연결하고 누가 로그인할 수 있는지 결정합니다. 발급자와 OAuth 클라이언트를 지정하고, 이메일과 그룹을 담는 클레임을 매핑하며, 이메일 도메인이나 그룹으로 로그인을 제한합니다.

OpenID Connect(OIDC)는 게이트웨이가 ID 공급자와 사용하는 SSO 프로토콜입니다. IdP 측에 등록할 항목은 ID 공급자 설정을 참조하십시오.

인증서 클라이언트 인증

Microsoft Entra의 인증서 자격 증명처럼 ID 공급자가 클라이언트 시크릿 대신 인증서로 OAuth 클라이언트를 인증하는 경우 token_endpoint_auth_method: private_key_jwt를 설정하십시오. 게이트웨이 서버에 Claude Code v2.1.284 이상이 필요합니다.

이 구성에서 게이트웨이는 시크릿을 보내지 않습니다. 개발자가 로그인할 때와 게이트웨이가 세션을 새로 고칠 때마다 인증서의 개인 키로 서명한 단기 JWT로 IdP 토큰 엔드포인트에 인증합니다. JWT는 RS256으로 서명되며, kid 대신 x5t 및 x5t#S256 지문 헤더로 인증서를 식별합니다. IdP는 등록된 인증서를 지문으로 찾을 수 있어야 합니다.

1. 키와 인증서 생성

PKCS#8 또는 PKCS#1 PEM 형식의 2048비트 이상인 암호화되지 않은 RSA 개인 키와 그에 대한 인증서를 생성하십시오. 게이트웨이는 이 조건을 충족하지 않는 키로는 시작을 거부합니다. 다음 openssl 명령은 그러한 키와 1년간 유효한 자체 서명 인증서를 생성합니다.

openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"

이 명령은 현재 디렉터리에 idp-client.key와 idp-client.crt를 작성합니다. 두 파일을 게이트웨이가 읽을 수 있는 위치에 복사하거나 마운트하십시오. 3단계의 예시는 /etc/gateway/를 사용합니다.

2. IdP에 인증서 업로드

개인 키가 아닌 인증서를 IdP의 게이트웨이 앱 등록에 업로드하십시오.

3. gateway.yaml에 키와 인증서 추가

client_assertion 블록에 개인 키와 인증서를 지정하십시오. client_secret은 생략하십시오. private_key_jwt와 함께 설정되면 게이트웨이가 시작을 거부합니다. 다음 oidc 블록은 인증서로 Microsoft Entra 테넌트에 게이트웨이를 인증합니다.

oidc:
  issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
  client_id: <application-id>
  token_endpoint_auth_method: private_key_jwt
  client_assertion:
    private_key_pem: ${file:/etc/gateway/idp-client.key}
    certificate_pem: ${file:/etc/gateway/idp-client.crt}

두 값 모두 파일 경로가 아닌 PEM 내용이므로, 예시처럼 마운트된 파일을 ${file:/path}로 로드하십시오. certificate_pem이 체인의 나머지 부분이 없는 단일 PEM 인증서가 아니거나 그 공개 키가 private_key_pem과 일치하지 않으면 게이트웨이는 시작을 거부합니다.

4. 게이트웨이 재시작 및 부팅 로그 확인

게이트웨이를 재시작하고 부팅 로그에서 다음 줄을 찾으십시오.

[gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct  1 23:07:31 2027 GMT

SHA-1 지문을 업로드한 인증서에 대해 IdP가 표시하는 지문과 비교하십시오. 인증서가 만료되었거나 아직 유효하지 않으면 게이트웨이는 시작되지만, 인증서를 교체할 때까지 로그인과 새로 고침이 실패한다는 경고를 로그에 기록합니다. IdP가 인증서를 수락하는지 확인하려면 개발자 한 명이 게이트웨이를 통해 로그인하도록 하십시오.

클라이언트 인증서 교체

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

1. 새 인증서를 기존 인증서와 함께 IdP에 업로드합니다.
2. gateway.yaml이 로드하는 키 및 인증서 파일을 교체한 다음 게이트웨이를 재시작합니다. 여러 복제본을 실행하는 경우, 기존 인증서를 제거할 때까지 IdP에 두 인증서가 모두 있으므로 롤링 재시작이 가능합니다.
3. 모든 복제본이 재시작된 후 IdP에서 기존 인증서를 제거합니다.

포워드 프록시를 통한 IdP 요청

추론 업스트림은 모든 버전에서 HTTPS_PROXY와 HTTP_PROXY를 따릅니다. 디스커버리, JWKS, 토큰, userinfo 등 게이트웨이 자체의 IdP 요청은 oidc.use_proxy: true를 설정하지 않으면 직접 전송되며, 이 설정에는 v2.1.227 이상이 필요합니다. 프록시 변수가 설정되어 있고 use_proxy가 설정되지 않았으며 발급자가 NO_PROXY에 포함되지 않은 경우, 게이트웨이는 해당 요청을 직접 보내고 부팅 시 선택을 요청하는 알림을 로그에 기록합니다. use_proxy: false는 요청을 직접 보내고 알림을 표시하지 않습니다.

use_proxy: true를 사용하면 파드가 각 IdP 엔드포인트의 호스트 이름을 직접 확인하고 확인된 IP 주소로 CONNECT하도록 프록시에 요청합니다. 따라서 프록시는 발급자뿐 아니라 디스커버리 문서가 지정하는 모든 호스트의 IP 주소로의 CONNECT를 허용해야 합니다. http:// 프록시 URL을 사용하십시오. ca_cert_pem과 SSRF 보호는 프록시 경로에도 적용됩니다.

프록시 전용 이그레스는 이 두 가지를 모두 바꿉니다. 활성화된 동안에는 use_proxy: false를 설정하지 않는 한 IdP 요청이 프록시를 따르며, 게이트웨이는 각 IdP 호스트 이름을 먼저 확인하지 않고 프록시에 전달합니다.

프록시 전용 이그레스

파드가 포워드 프록시를 통해서만 다른 호스트에 도달할 수 있고 공용 DNS 이름을 직접 확인할 수 없는 경우, 또는 프록시가 IP 주소로의 CONNECT를 거부하는 경우에는 게이트웨이 환경에서 HTTPS_PROXY와 함께 CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1을 설정하십시오. v2.1.277 이상이 필요합니다. 설정 파일의 어떤 내용도 게이트웨이의 주소 검사를 완화할 수 없도록 gateway.yaml 키가 아닌 환경 변수로 제공됩니다.

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

프록시 전용 이그레스가 활성화되어 있으면 게이트웨이는 부팅 시 network: 줄 하나를 로그에 기록합니다.

아래 각 행은 HTTPS_PROXY가 설정된 게이트웨이의 아웃바운드 요청 유형 하나를 기본 동작과 프록시 전용 이그레스 활성 시로 나누어 보여 줍니다.

게이트웨이 환경이 다음 세 가지 조건을 모두 충족하지 않으면 프록시 전용 이그레스는 꺼진 상태로 유지됩니다.

• HTTPS_PROXY 또는 HTTP_PROXY가 설정되어 있습니다.
• NO_PROXY와 no_proxy가 비어 있습니다. 플랫폼이 둘 중 하나를 파드에 주입하는 경우, 게이트웨이 컨테이너에서 둘 다 빈 값으로 설정하십시오. NO_PROXY에 텔레메트리 수집기를 나열하면 프록시 전용 이그레스가 꺼진 상태로 유지됩니다.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK이 켜져 있지 않습니다. 프록시에 전달된 루프백 주소는 프록시 호스트 자신의 루프백이 되므로, 파드 자체 루프백에 있는 수집기나 IdP는 프록시 전용 이그레스와 함께 사용할 수 없습니다. 대신 해당 서비스에 프록시가 도달할 수 있는 주소를 부여하십시오. 같은 이유로 프록시 전용 이그레스가 활성화된 동안 게이트웨이는 localhost 형식의 이름을 즉시 거부합니다.

이 조건 중 하나라도 충족되지 않으면 게이트웨이는 부팅 시 이를 막은 변수를 명시하는 경고를 로그에 기록하고 기본 동작을 유지합니다.

프록시 전용 이그레스가 활성화되면 내부 수집기와 IP 주소로 구성된 호스트를 포함한 모든 목적지를 프록시에서 허용하십시오. oidc.use_proxy: false로 내부 IdP를 직접 연결로 유지할 수 있습니다.

[!WARNING]

프록시의 허용 목록이 게이트웨이 자체 검사만큼 엄격한 경우에만 이 기능을 켜십시오. 프록시는 169.254.169.254와 metadata.google.internal 같은 클라우드 메타데이터 엔드포인트, 링크 로컬 주소, 프록시 호스트 자신의 루프백을 거부해야 하며, 이름만이 아니라 이름이 확인되는 주소를 기준으로 거부해야 합니다. 게이트웨이가 더 이상 이러한 주소로 확인되는 호스트 이름을 걸러내지 않기 때문입니다. 요청받는 곳 어디에나 연결하는 프록시는 이러한 요청에 대해 게이트웨이의 SSRF 보호를 무력화합니다.

session

session 블록은 게이트웨이가 로그인 후 발급하는 베어러 토큰, 즉 토큰에 서명하는 시크릿과 토큰 수명을 정의합니다.

store

store 블록은 디바이스 그랜트와 속도 제한 카운터를 보관하는 게이트웨이의 PostgreSQL 데이터베이스를 지정합니다.

로컬 개발의 경우 postgres_url을 일회용 Postgres 컨테이너로 지정하십시오. 예: docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

upstreams

upstreams는 순서가 있는 목록입니다. 게이트웨이는 요청된 모델을 확인하는 첫 번째 업스트림으로 추론을 전달하며, groups 목록에 해당 개발자가 포함되지 않은 업스트림은 건너뜁니다.

5xx, 429, 401, 403, 404 또는 타임아웃이 발생하면 게이트웨이는 다음 업스트림으로 페일오버합니다. 그 외의 4xx는 업스트림이 아니라 요청에 원인이 있는 오류이므로 페일오버하지 않습니다. 401 또는 403은 업스트림이 게이트웨이가 사용한 자격 증명을 거부했거나, 예를 들어 요청된 모델에 대한 액세스를 거부했다는 의미입니다. 404는 해당 업스트림이 요청된 모델을 제공하지 않는다는 의미이므로, 목록의 뒤쪽 업스트림이 여전히 제공할 수 있습니다.

업스트림에 forward_user_identity: true를 설정하면, 개발자 이메일이 포함된 요청에 대해 그 업스트림이 반환한 429는 페일오버하지 않습니다. 사용자별 한도 거부가 개발자에게 전달되는 방식을 참조하십시오.

404에서의 페일오버에는 게이트웨이 v2.1.198 이상이 필요합니다. 이전 릴리스는 목록의 뒤쪽 업스트림이 모델을 제공하더라도 첫 번째 404를 클라이언트에 반환했습니다.

같은 공급자의 여러 업스트림에는 서로 다른 name:을 설정해야 합니다.

Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry 클라이언트는 시작 시 한 번 빌드되고 해당 SDK가 내부적으로 자격 증명을 새로 고치므로, 클라우드 자격 증명을 교체해도 재시작이 필요하지 않습니다. 정적 Anthropic API 키와 베어러는 시작 시 읽습니다. Anthropic API를 참조하십시오.

업스트림 오류 메시지

게이트웨이는 업스트림의 응답 방식에 따라 한 업스트림의 오류 응답 또는 자체 502를 반환합니다.

• 업스트림이 게이트웨이가 페일오버하지 않는 상태를 반환한 경우: 해당 업스트림의 응답입니다. 게이트웨이는 더 이상 다른 업스트림을 시도하지 않습니다.
• 게이트웨이가 시도한 모든 업스트림이 장애 조치 대상인 방식으로 실패한 경우: 마지막 429를 반환합니다. 429를 반환한 업스트림이 없으면 게이트웨이는 마지막 401 또는 403, 마지막 404, 마지막 501 순으로 우선합니다. 그중 아무것도 반환되지 않았으면 게이트웨이 자체의 502, all upstreams failed (N attempted)를 반환합니다. N은 건너뛴 항목을 포함한 upstreams 항목 수에서 groups 목록에 해당 개발자가 포함되지 않은 항목을 뺀 값입니다.

게이트웨이가 업스트림의 응답을 반환할 때 업스트림의 상태 코드는 유지합니다. 업스트림의 메시지를 유지하는지는 공급자에 따라 다릅니다. Anthropic API 업스트림의 오류 본문은 변경 없이 개발자에게 전달됩니다.

Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry 업스트림은 오류 텍스트에 계정 ID, 역할 ARN, 프로젝트 ID를 포함할 수 있습니다. 게이트웨이는 그 전체 텍스트를 운영 로그에 기록합니다. 이러한 업스트림에서 개발자에게 표시되는 내용은 거부 유형에 따라 다릅니다.

• Anthropic의 표준 오류 봉투 형식의 400 또는 413: prompt is too long 같은 업스트림 자체의 메시지입니다. Claude Platform on AWS, Agent Platform, Microsoft Foundry는 모델 API 거부에 이 봉투를 반환합니다.
• 공급자 자체 형식의 400 또는 413: capability_rejected: 토큰입니다. 게이트웨이가 거부를 분류할 수 없으면 400에서는 upstream rejected the request, 413에서는 request too large for this upstream입니다.
• 그 외 상태: 429의 upstream rate limit exceeded 같은 상태별 일반 문구입니다.

예를 들어, 게이트웨이는 Amazon Bedrock의 Input is too long for requested model.을 capability_rejected: prompt_too_long으로 대체합니다. Claude Code는 prompt is too long에서와 마찬가지로 이 토큰에서 자동으로 압축합니다.

클라우드 업스트림의 400 또는 413 메시지를 유지하거나 capability_rejected: 토큰으로 대체하려면 게이트웨이 v2.1.233 이상이 필요합니다.

Anthropic API

최소한의 Anthropic 업스트림은 Claude Console의 API 키입니다.

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # default; override for a forward proxy

두 자격 증명 형식은 전송하는 헤더가 다릅니다.

• api_key: x-api-key를 전송합니다. Claude Console에서 교체하고 환경 변수를 업데이트하십시오.
• oauth_token: Authorization: Bearer를 전송합니다. 조직이 장기 API 키 대신 단기 토큰을 발급하는 경우 베어러 형식을 사용하십시오. 베어러는 시작 시 한 번 읽으므로, 시크릿을 다시 마운트하고 재시작하여 새로 고치십시오.

정적 키나 베어러 대신 Workload Identity Federation을 사용할 수 있습니다. Workload Identity Federation 가이드에 따라 페더레이션 규칙을 만든 다음, Kubernetes 프로젝션된 서비스 계정 토큰이나 CI 플랫폼의 id-token 같은 워크로드의 OIDC JWT를 파일로 마운트하십시오. 게이트웨이는 JWT를 단기 베어러로 교환하고 자동으로 새로 고칩니다. 토큰 파일은 교환할 때마다 다시 읽으므로, 교체된 프로젝션 토큰이 재시작 없이 반영됩니다.

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # required if the rule covers >1 workspace
      # service_account_id: svac_...   # optional expected-target check

직접 운영하는 프록시를 위한 사용자별 ID 헤더

provider: anthropic 업스트림의 base_url을 Anthropic API 대신 직접 운영하는 프록시로 지정할 수 있습니다. 각 요청을 어떤 개발자가 보냈는지 해당 프록시에 알리려면 그 업스트림에 forward_user_identity: true를 설정하십시오. 그러면 프록시가 개발자별로 지출을 귀속할 수 있습니다. Claude Code v2.1.233 이상을 실행하는 게이트웨이가 필요합니다.

예를 들어 upstream-gateway.internal.example.com에 있는 프록시의 경우:

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # default false

게이트웨이는 해당 업스트림으로 전달하는 모든 요청에 다음 헤더를 추가합니다.

IdP 토큰에 이메일이 없으면 게이트웨이는 x-claude-gateway-user-id만 보내고 두 이메일 헤더는 생략합니다. IdP가 이메일을 다른 클레임에 넣는 경우 oidc.email_claim을 그 클레임으로 설정하십시오.

프록시는 x-claude-code-session-id 같이 Claude Code가 보내는 x-claude-code-* 헤더를 받지 않습니다. 게이트웨이는 이 헤더를 어떤 업스트림에도 전달하지 않으므로, 위 표의 헤더로 개발자별로 요청을 그룹화하십시오.

개발자 이메일이 포함된 요청에 프록시가 429로 응답하면, 게이트웨이는 다음 업스트림으로 페일오버하는 대신 그 응답을 그대로 개발자에게 반환하므로 프록시의 사용자별 예산이나 속도 제한이 유지됩니다. 프록시의 다른 응답은 일반적인 페일오버 규칙을 따릅니다. 개발자의 IdP 토큰에 이메일이 없으면 게이트웨이는 이메일 헤더 없이 요청을 전달하므로, 그러한 요청에 대한 429는 업스트림 용량으로 간주되어 페일오버합니다. 게이트웨이 서버가 v2.1.267 이전이면 모든 429가 페일오버했습니다.

forward_user_identity는 base_url이 사용자가 직접 운영하는 프록시인 업스트림에만 설정하십시오. 게이트웨이는 해당 base_url이 가리키는 서버가 무엇이든 그 서버로 개발자 이메일을 보냅니다. base_url이 기본값인 Anthropic API이면 게이트웨이는 시작을 거부합니다.

[!NOTE]

Amazon Bedrock 업스트림에 forward_user_identity를 설정하면 게이트웨이는 시작 시 Unrecognized key(s) in object: 'forward_user_identity'와 함께 종료됩니다. 프록시가 Bedrock 앞에 있는 경우 대신 provider: anthropic 업스트림으로 나열하십시오. 게이트웨이는 해당 업스트림에 Anthropic Messages 형식을 보내므로, 프록시가 Bedrock용으로 요청을 변환해야 합니다. 대신 AWS에 각 개발자를 식별시키려면 개발자별 AWS 비용 귀속을 참조하십시오.

Amazon Bedrock

게이트웨이가 대체하거나 앞단에 위치하는 클라이언트 측 Amazon Bedrock 배포에 대해서는 Amazon Bedrock에서 Claude Code 사용을 참조하십시오. 게이트웨이 측 업스트림은 다음과 같습니다.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferred: AWS default credential chain
    # OR explicit credentials:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OR a Bedrock API bearer token:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

빈 auth 블록은 AWS SDK의 기본 자격 증명 체인인 환경 변수, ~/.aws/credentials, ECS 태스크 역할, EC2 인스턴스 메타데이터 또는 EKS의 IRSA를 사용합니다. 프로덕션에서는 컨테이너 이미지에 정적 키를 포함하는 대신 게이트웨이 파드에 IAM 역할을 부여하십시오.

명시적 자격 증명은 완전해야 합니다. aws_access_key_id와 aws_secret_access_key가 함께 설정되지 않았거나, 이들 없이 aws_session_token이 설정되면 게이트웨이는 부팅 시 실패합니다. v2.1.207 이전에는 불완전한 auth: 블록도 검증을 통과했습니다.

Amazon Bedrock 가드레일 적용

게이트웨이가 Bedrock 업스트림을 통해 보내는 모든 추론 요청에 Amazon Bedrock 가드레일을 적용하려면 해당 업스트림에 guardrail 블록을 추가하십시오. 게이트웨이 서버에 Claude Code v2.1.281 이상이 필요합니다.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # guardrail ID or full ARN
      version: "1"                     # a published version number, or DRAFT
 # keep the quotes: a bare 1 fails at boot

이 업스트림의 요청에 서명하는 주체, 즉 게이트웨이의 AWS 주체 또는 assume_role을 사용하는 경우 role_arn에 지정된 역할에도 해당 가드레일에 대한 bedrock:ApplyGuardrail을 부여하십시오.

guardrail은 모든 bedrock 업스트림에 설정하거나 어디에도 설정하지 마십시오. 그렇지 않으면 페일오버가 가드레일이 없는 Bedrock 업스트림으로 요청을 보낼 수 있으므로, 게이트웨이는 혼합된 구성에서 시작을 거부합니다.

가드레일은 Bedrock 업스트림에만 적용됩니다. upstreams에 다른 공급자를 나열하면 게이트웨이는 가드레일 없이 해당 공급자로 요청을 보내며, 그 공급자가 mantle이면 시작을 거부합니다.

amazon-bedrock-guardrailConfig 같은 amazon-bedrock-* 필드를 본문에 담은 /v1/messages 요청이 guardrail이 설정된 Bedrock 업스트림에 도달하면, 게이트웨이는 요청을 전달하는 대신 400으로 응답합니다.

[!WARNING]

기본적으로 게이트웨이는 프롬프트에 입력 태그를 추가하지 않으므로, Amazon Bedrock이 태그가 지정된 입력에만 적용하는 가드레일 필터는 게이트웨이를 통한 트래픽에서 실행되지 않습니다. 태그를 추가하려면 input_tagging을 설정하십시오. 어떤 필터가 입력 태그에 의존하는지는 Amazon Bedrock 문서의 입력 태그를 참조하십시오.

가드레일 입력 태그 추가

Amazon Bedrock 가드레일의 프롬프트 공격 필터에 필요한 입력 태그를 게이트웨이가 추가하도록 하려면, guardrail 블록에 input_tagging을 설정하고 게이트웨이를 재시작하십시오. 모든 bedrock 업스트림에 동일한 값을 설정해야 하며, 그렇지 않으면 게이트웨이가 시작을 거부합니다. 게이트웨이 서버에 Claude Code v2.1.316 이상이 필요합니다. 이 키를 지원하지 않는 버전의 게이트웨이는 시작 시 Unrecognized key(s) in object: 'input_tagging'과 함께 종료됩니다.

[!WARNING]

Amazon Bedrock 문서에 따르면 요청에 입력 태그가 포함되면 가드레일의 모든 필터가 태그가 없는 콘텐츠에 대한 평가를 중단합니다. 개발자가 사용하는 게이트웨이에 설정하기 전에 테스트 게이트웨이에서 input_tagging을 시험해 보십시오.

input_tagging은 다음 값 중 하나를 받습니다.

last_message에서 Claude의 마지막 응답 이후 user 메시지에 태그를 지정할 텍스트가 없으면, 게이트웨이는 대신 그 응답 이후의 대화 중간 시스템 메시지에 태그를 지정합니다. 도구 호출도 응답으로 간주됩니다.

프롬프트 공격 필터에 대한 Amazon Bedrock의 지침은 시스템 프롬프트를 제외하도록 사용자 입력에 태그를 지정하는 것입니다. all_messages_and_system을 설정하면 Claude Code 자체의 시스템 프롬프트를 플래그하는 필터가 요청을 차단할 수 있습니다.

아래 예시는 모든 user 메시지의 텍스트에 태그를 지정합니다.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
      input_tagging: user_messages

user 메시지에는 시스템 리마인더처럼 Claude Code가 추가하는 텍스트도 포함될 수 있으므로, 테스트 게이트웨이에서 일반 요청이 차단되지 않는지 확인하십시오.

Anthropic의 테스트에서 태그가 지정된 세션은 프롬프트 간에 프롬프트 캐시 읽기를 유지했으며, 태그로 인한 입력 토큰 증가는 없었습니다.

입력 태그가 다루지 않는 범위

어떤 input_tagging 값도 태그가 적용되지 않는 위치에 의도적으로 텍스트를 넣는 개발자를 막지 못합니다. 요청의 다음 부분은 가드레일이 평가할 것이라고 기대하지 마십시오.

• 게이트웨이가 태그를 지정하지 않는 콘텐츠: input_tagging 값이 제외하는 메시지, 도구 정의, 도구 호출 입력, 이미지, PDF 등입니다. all_messages_and_system을 설정하지 않으면 시스템 프롬프트도 태그가 지정되지 않습니다.
• 도구 결과: 파일 내용이나 웹 페이지처럼 Claude의 도구가 반환하는 내용입니다. Anthropic의 테스트에서 단어 필터는 태그 유무와 관계없이 이를 평가하지 않았습니다.

AWS 계정이나 조직이 가드레일을 강제 적용하는 경우, 해당 가드레일이 입력 태그를 처리하는 방식은 Amazon Bedrock 문서를 참조하십시오.

어떤 가드레일 필터가 작동했는지 로그에 기록

어떤 Amazon Bedrock 가드레일 필터가 개발자의 요청을 차단했는지 확인하려면, Bedrock 업스트림에 guardrail_trace: true를 설정하고 게이트웨이를 재시작한 다음 개발자가 요청을 다시 보내도록 하십시오. 그런 다음 감사 로그에서 해당 요청의 guardrail.trace 이벤트를 찾으십시오. 게이트웨이 서버에 Claude Code v2.1.314 이상이 필요합니다. 이전 게이트웨이는 guardrail_trace를 발견하면 시작을 거부합니다.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
    guardrail_trace: true              # default false; beside guardrail, not inside it

게이트웨이는 필터가 작동했거나 가드레일의 조치가 INTERVENED일 때, 일치한 텍스트 없이 guardrail.trace 이벤트를 기록합니다. email 또는 sub로 개발자의 이벤트를 찾으십시오. 스트리밍 요청 하나가 여러 이벤트를 생성할 수 있고 그중 하나는 filters 목록이 비어 있을 수 있으므로, 같은 request_id를 가진 모든 이벤트를 읽으십시오.

이 이벤트는 Bedrock 트레이스의 match 필드를 포함하여 필터가 일치시킨 텍스트를 제외합니다. 게이트웨이가 스트리밍 여부와 관계없이 각 응답에서 Bedrock의 트레이스 데이터를 제거하므로 개발자는 이를 받지 않습니다.

클라이언트가 /v1/messages 요청 본문에 amazon-bedrock-* 필드를 보내면, 게이트웨이는 guardrail_trace를 설정한 업스트림에서 400으로 응답합니다.

다른 AWS 계정의 Bedrock

Bedrock 업스트림에 assume_role을 설정하면 게이트웨이는 자체 AWS ID를 지정된 역할에 대해 sts:AssumeRole을 호출하는 용도로만 사용하며, 이 역할은 게이트웨이와 다른 AWS 계정에 있을 수 있습니다. 해당 업스트림의 모든 Bedrock 요청은 STS가 반환한 1시간짜리 자격 증명으로 서명되므로, 장기 액세스 키가 계정 간에 오가지 않습니다.

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

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # when the role's trust policy requires one

assume_role 블록은 세 가지 키를 받습니다.

역할의 신뢰 정책은 IRSA나 ECS 태스크 역할 같은 게이트웨이 자체 주체를 지정합니다. 해당 주체에는 역할에 대한 sts:AssumeRole이 필요하며 자체 Bedrock 권한은 필요하지 않습니다. external_id를 설정하지 않으면 Condition을 제거하십시오.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
  }]
}

• STS가 거부하거나 연결할 수 없는 경우, 게이트웨이는 업스트림 자체 자격 증명으로 요청을 보내지 않습니다. 확인할 사항과 함께 STS 오류를 로그에 기록한 다음, 나열된 다음 업스트림을 시도합니다. 성공한 업스트림이 없을 때 클라이언트가 받는 내용은 업스트림 오류 메시지에서 다룹니다. assume_role이 없는 뒤쪽 업스트림은 자체 자격 증명으로 요청을 처리하므로, 그것이 의도한 바일 때만 나열하십시오.
• 게이트웨이는 리전 STS 엔드포인트 sts.<region>.amazonaws.com을 호출하므로, 네트워크에서 여기에 도달할 수 있어야 합니다. FIPS 엔드포인트를 사용하려면 AWS 설정 파일의 use_fips_endpoint 대신 게이트웨이 환경에 AWS_USE_FIPS_ENDPOINT=true를 설정하십시오.
• assume_role에는 SigV4 소스 자격 증명이 필요합니다. aws_bearer_token과 함께 설정되면 게이트웨이가 시작을 거부합니다.
• groups 목록이 없으면 게이트웨이가 허용하는 모든 개발자가 이 업스트림을 사용할 수 있습니다. 개발자가 사용할 수 있는 모델을 제한하려면 managed 정책에서 availableModels를 설정하십시오.
• 역할을 통해 제공되는 모델이 다른 계정에서도 제공되지 않도록 하려면, upstream_model 맵에 이 업스트림의 이름만 있는 사용자 지정 ID를 부여하십시오. 이러한 ID의 경우 게이트웨이는 다른 모든 업스트림을 건너뛰므로, 요청도 중단된 요청의 토큰 계산도 다른 계정으로 장애 조치될 수 없습니다.
• 기본 제공 모델 이름에 대한 요청은 여전히 이 업스트림에 도달할 수 있으며, 게이트웨이는 같은 역할로 서명합니다. 해당 계정에서 그러한 모델도 제공해야 하는 경우가 아니라면 이 업스트림을 마지막에 나열하십시오.

다음 예시는 격리된 업스트림만 제공하는 사용자 지정 id를 한 모델에 부여합니다.

models:
  - id: restricted-claude-opus-4-8      # a custom id, not a built-in model name
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # the only upstream that serves it

개발자별 AWS 비용 귀속

기본적으로 게이트웨이는 모든 Bedrock 요청에 하나의 자격 증명으로 서명하므로, AWS는 모든 개발자의 요청을 단일 IAM 주체로 인식합니다. assume_role에 session_name: email을 추가하면 게이트웨이는 개발자별로 시간당 한 번 세션 이름을 해당 개발자의 이메일로 설정하여 sts:AssumeRole을 호출하고, 반환된 자격 증명으로 그 개발자의 요청에 서명합니다. 따라서 각 개발자의 요청은 자신의 assumed-role 세션으로 AWS에 도달합니다. 역할은 게이트웨이 자체 계정에 있어도 됩니다.

Claude Code v2.1.281 이상을 실행하는 게이트웨이가 필요합니다. IAM 역할과 AWS 청구에서 세션이 표시되는 위치는 AWS의 비용 귀속에서 다룹니다.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # or sub

session_name은 어떤 검증된 클레임이 AWS RoleSessionName이 될지 선택하며, email 또는 sub입니다. 게이트웨이는 ASCII 문자, 숫자, _+,.@- 이외의 문자를 UTF-8 바이트마다 =XX 16진수로 작성하고, 64자를 넘는 결과는 접두사와 해시로 줄여서 각 개발자의 세션 이름이 유효하고 고유하도록 유지합니다. 토큰에 해당 클레임이 없는 개발자의 요청은 이 업스트림을 통해 전송되지 않으며, 운영자 로그에 sub로 전환하거나 oidc.email_claim을 설정하라는 안내가 표시됩니다.

활성 개발자 한 명당 게이트웨이 복제본마다 시간당 한 번의 STS 호출이 발생하며, 동시에 들어온 첫 요청들은 하나의 호출을 공유합니다.

게이트웨이는 이 역할로 자체 호출도 한 번 수행합니다. 지출 한도의 정확성을 유지하기 위해 클라이언트가 중단한 요청의 토큰을 계산하는 것입니다. 그 계산과 토큰 하나짜리 폴백 요청은 공유 claude-apps-gateway 세션으로 서명되므로, AWS는 폴백을 개발자가 아닌 claude-apps-gateway에 귀속합니다.

엄격한 개발자별 귀속을 위해서는 나열하는 모든 Bedrock 업스트림에 session_name과 함께 assume_role을 설정하십시오. 이 설정이 없는 업스트림은 처리하는 요청에 자체 자격 증명으로 서명합니다.

Amazon Bedrock Mantle 엔드포인트

mantle 공급자는 Amazon Bedrock의 Mantle 엔드포인트로 추론을 보냅니다. 게이트웨이 서버에 Claude Code v2.1.283 이상이 필요합니다. 이전 게이트웨이 릴리스는 부팅 시 이를 거부하므로, 추가하기 전에 모든 복제본을 업그레이드하십시오.

아래 예시는 Mantle을 먼저 두고, 그 뒤에 models 필드에서 제외된 모든 모델을 제공할 Amazon Bedrock 업스트림을 둡니다.

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # required
    auth: {}                           # AWS default credential chain
  - provider: bedrock
    region: us-east-1
    auth: {}

아래 표는 mantle 업스트림에 고유한 필드를 나열합니다.

업스트림의 AWS ID에 추론과 토큰 계산을 위한 Mantle 자체 IAM 작업을 부여하십시오. 이 작업은 Mantle 엔드포인트 사용에 나열되어 있습니다.

게이트웨이가 알지 못하는 Mantle 모델 ID의 경우, 최상위 models: 블록에 이 업스트림의 이름을 해당 ID에 매핑하는 upstream_model을 가진 항목을 추가하십시오. 그런 다음 그 항목의 id를 이 업스트림의 models 필드에도 넣으십시오.

bedrock 업스트림의 guardrail과 assume_role 설정은 Mantle이 처리하는 요청에는 적용되지 않습니다.

• guardrail: 게이트웨이는 Mantle로 보내는 요청에 Bedrock 가드레일을 적용하지 않으므로, 어떤 bedrock 업스트림이든 guardrail을 설정한 상태에서 mantle 업스트림이 나열되면 시작을 거부합니다.
• assume_role: mantle 업스트림 자체에 설정하십시오. 설정하지 않으면 Mantle이 처리하는 요청은 mantle 업스트림 자체의 auth 자격 증명으로 전송됩니다.

Mantle 자체 오류 응답의 의미는 Mantle 엔드포인트 오류를 참조하십시오.

Claude Platform on AWS

Claude Platform on AWS는 AWS 인프라에서 aws-external-anthropic.<region>.api.aws로 퍼스트 파티 Anthropic API를 제공합니다. 퍼스트 파티 모델 ID를 사용하고, anthropic-beta 헤더를 전송된 그대로 따르며, count_tokens를 제공하므로 Bedrock 전용 변환은 적용되지 않습니다. anthropicAws 공급자에는 Claude Code v2.1.198 이상이 필요하며, 이전 게이트웨이 릴리스는 부팅 시 이를 거부합니다.

같은 플랫폼의 클라이언트 측 배포에 대해서는 Claude Platform on AWS에서 Claude Code 사용을 참조하십시오. 게이트웨이 측 업스트림은 다음과 같습니다.

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # sent as x-api-key
    # OR SigV4 via the AWS default credential chain:
    # auth: {}
    # OR explicit SigV4 credentials:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Override the derived endpoint:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

이 플랫폼은 Amazon Bedrock과 별도의 AWS 계정에서 실행되며 자체 서비스 이름인 aws-external-anthropic으로 SigV4 요청에 서명하므로, Bedrock 범위의 IAM 역할로는 인가되지 않습니다. SigV4 자격 증명도 설정된 경우 auth.api_key의 API 키가 우선합니다. 빈 auth 블록은 Amazon Bedrock 업스트림과 같은 AWS SDK의 기본 자격 증명 체인을 사용합니다.

플랫폼이 퍼스트 파티 모델 ID를 확인하므로, 기본 제공 카탈로그는 models: 블록 없이 이 플랫폼으로 라우팅됩니다. models: 목록을 직접 구성하는 경우, 항목의 키를 anthropicAws:로 하고 퍼스트 파티 ID를 지정하십시오.

Google Cloud Agent Platform

동등한 클라이언트 측 설정은 Google Cloud에서 Claude Code 사용을 참조하십시오. 게이트웨이 측 업스트림은 다음과 같습니다.

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferred: Application Default Credentials
    # OR a service account key file:
    # auth: { service_account_json: /secrets/sa.json }
    # Override the aiplatform endpoint for Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

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

리전 엔드포인트 대신 Google Cloud Agent Platform의 글로벌 엔드포인트를 사용하려면 region: global을 설정하십시오. 그러면 Google이 각 요청을 사용 가능한 리전으로 라우팅하므로 리전별 모델 가용성을 추적할 필요가 없습니다. 특정 리전을 설정하면 모든 요청이 해당 리전에 고정됩니다.

Microsoft Foundry

클라이언트 측 Microsoft Foundry 배포에 대해서는 Microsoft Foundry에서 Claude Code 사용을 참조하십시오. 게이트웨이 측 업스트림은 다음과 같습니다.

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferred: DefaultAzureCredential / Managed Identity
    # OR an API key:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

use_azure_ad: true는 DefaultAzureCredential을 통해 확인되며, AKS, ACI 또는 App Service의 Managed Identity, Azure CLI 또는 환경 자격 증명을 사용합니다. API 키도 작동하지만 프로젝트 전체에 적용되며 자동으로 교체되지 않습니다. Microsoft Foundry의 엔드포인트는 resource:에서 도출되며, Azure Government 같은 소버린 클라우드의 경우 선택적 base_url을 설정하여 재정의하십시오.

업스트림 요청의 정적 헤더

게이트웨이가 한 업스트림에 보내는 요청에 고정 헤더를 추가하려면 해당 업스트림에 headers:를 설정하십시오. 공급자 앞에서 직접 운영하는 프록시가 헤더로 트래픽을 라우팅하거나 귀속하는 경우에 사용합니다.

headers:에는 게이트웨이 서버에 Claude Code v2.1.277 이상이 필요합니다. 이전 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 키를 추가하기 전에 모든 복제본을 업그레이드하고, 이전 버전으로 롤백하기 전에 키를 제거하십시오.

헤더는 base_url이 가리키는 서버로, base_url이 설정되지 않은 경우 공급자 자체의 엔드포인트로 전송됩니다. 프록시가 헤더를 제거하지 않으면 공급자도 헤더를 받습니다.

다음 예시는 upstream-proxy.internal.example.com에 있는 프록시를 통해 provider: vertex 업스트림에 도달합니다. 프록시가 읽는 x-source 헤더를 설정하고, PROXY_TOKEN 환경 변수의 토큰을 x-proxy-token으로 보냅니다.

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

값은 양 끝에 공백이 없는 출력 가능한 ASCII 텍스트입니다. 숫자, true 또는 false는 YAML이 텍스트로 읽도록 따옴표로 감싸십시오.

시크릿을 설정 파일에 포함하지 않으려면 시크릿 확장을 사용해 ${VAR}로 환경 변수에서, 또는 ${file:/path}로 파일에서 값을 로드하십시오. 빈 값으로 확인되는 ${VAR}는 게이트웨이 시작을 막습니다.

headers:는 모든 공급자에서 작동하며, 각 업스트림은 자신의 헤더만 보냅니다.

게이트웨이가 업스트림에 보내는 모든 요청에 헤더가 포함되는 것은 아닙니다.

AWS SigV4로 요청에 서명하는 Amazon Bedrock 또는 Claude Platform on AWS 업스트림에서는 이 헤더가 서명의 일부이므로, 프록시가 변경 없이 전달해야 합니다.

게이트웨이가 예약한 이름을 사용하면 시작을 거부하며, 시작 오류에 해당 헤더 이름이 표시됩니다. 예약된 이름은 다음과 같습니다.

• authorization 및 x-api-key
• host, content-type, user-agent
• anthropic-, x-goog-, x-amz- 또는 x-amzn-으로 시작하는 모든 이름

여러 업스트림

같은 공급자를 서로 다른 name:으로 여러 번 사용할 수 있습니다. 이를 통해 서로 다른 리전, 서로 다른 자격 증명 체인을 통한 서로 다른 계정, 프로비저닝된 처리량 대 온디맨드, 공급자 간 폴백을 구성할 수 있습니다.

게이트웨이는 업스트림을 순서대로 시도합니다. 5xx, 429, 401, 403, 404, 타임아웃, 엔드포인트 누락(501)은 페일오버하고, 그 외의 4xx는 페일오버하지 않습니다.

429는 업스트림별 용량이므로, 프로비저닝된 처리량(PT)이 소진되면 온디맨드로 페일오버합니다. 업스트림에 forward_user_identity: true를 설정하면, 개발자 이메일이 포함된 요청에 대한 429는 대신 사용자별 거부가 되어 페일오버하지 않습니다.

요청은 다음 경우에만 다음 업스트림으로 넘어갑니다.

• 업스트림이 실패한 경우
• 업스트림이 요청된 모델을 제공하지 않는 경우
• 업스트림에 해당 개발자를 포함하지 않는 groups 목록이 있는 경우

게이트웨이는 실패한 업스트림을 기록하지 않으므로, 업스트림이 다운된 동안 그 업스트림에 도달하는 모든 요청은 여전히 해당 업스트림을 시도하고 실패할 때까지 기다린 후 다음으로 넘어갑니다.

게이트웨이는 응답이 시작될 때까지 다음 시간 동안 기다립니다.

• provider: anthropic 업스트림: timeouts.upstream_ttfb_ms, 기본값 120초
• 기타 공급자: 최대 1시간. 스트리밍 요청의 대기 시간을 줄이려면 게이트웨이 v2.1.295 이상에서 timeouts.upstream_ttfb_ms를 설정하십시오. 비스트리밍 모델 요청은 어느 경우든 최대 1시간을 기다립니다

404는 업스트림별 모델 가용성이므로, 모델을 활성화하지 않은 업스트림이 그 모델을 제공하는 뒤쪽 업스트림을 막지 않습니다. 요청된 모델을 확인할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.

다음 예시는 프로비저닝된 처리량의 Amazon Bedrock 할당량으로 먼저 라우팅하고, 온디맨드와 두 번째 계정으로 넘친 요청을 보내며, 마지막으로 Anthropic API로 폴백합니다.

upstreams:
  # Primary: provisioned throughput in your home region.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Overflow: on-demand cross-region.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Different account: a separate Bedrock allotment via static keys.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Last resort: direct Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Per-upstream model IDs are keyed on the upstream's `name:`.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

클라우드 공급자 간 또는 직접 Anthropic API로 페일오버하면 요청에 적용되는 계약, 지역 및 기타 조건이 달라집니다.

CLI는 어떤 업스트림이 요청을 처리하든 게이트웨이에 같은 기능 제한을 적용하므로, 기본적으로 페일오버는 업스트림이 거부할 본문 필드를 보내지 않습니다. 정책에서 1시간 캐시 TTL을 설정하면 목록의 모든 업스트림으로 전송되므로, 모든 업스트림이 이를 수락하는 경우에만 설정하십시오.

각 팀을 전용 업스트림으로 보내기

각 팀의 요청을 해당 팀의 AWS 계정 또는 Google Cloud 프로젝트로 보내려면, 팀마다 업스트림을 하나씩 나열하고 각각에 groups 목록을 지정합니다. 나열된 IdP 그룹에 속한 개발자만 첫 시도와 페일오버 시 해당 업스트림에 도달합니다. 모든 공급자가 groups를 지원합니다. 게이트웨이 서버에 Claude Code v2.1.314 이상이 필요합니다.

이 예시는 payments-eng 그룹과 search-eng 그룹에 각각 AWS 계정을 할당하고, 모든 개발자가 사용할 수 있도록 groups 목록이 없는 업스트림을 추가합니다.

upstreams:
  - name: bedrock-payments
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
    groups: [payments-eng]
  - name: bedrock-search
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
    groups: [search-eng]
  - name: bedrock-shared               # no groups: open to everyone, so listed last
    provider: bedrock
    region: us-east-1
    auth: {}

예시 구성에서 각 개발자의 요청은 해당 행의 첫 번째 업스트림에서 시작하여 페일오버 시 다음 업스트림으로 이동합니다.

팀의 업스트림이 요청된 모델을 403으로 거부하면, 게이트웨이는 해당 팀의 행에서 그 모델을 제공하는 다음 업스트림을 시도합니다. 팀을 하나의 업스트림에 고정하려면 모든 업스트림에 groups 목록을 지정하고, 다른 업스트림이 해당 팀 개발자가 속한 그룹을 나열하지 않도록 합니다. 그러면 해당 팀에는 페일오버가 없으며, 나열된 그룹 어디에도 속하지 않은 개발자의 요청은 400으로 실패합니다.

각 개발자가 의도한 업스트림에 도달하도록 하려면, 정확히 일치하는 항목을 작성하고 개방된 업스트림을 마지막에 배치합니다.

• 항목: 각 그룹을 IdP가 groups 클레임으로 보내는 값과 정확히 동일하게 작성합니다. match.groups도 이 클레임을 읽습니다. 게이트웨이는 빈 목록이나 빈 항목을 발견하면 시작을 거부합니다. 항목을 IdP와 대조하지는 않으므로, 아무와도 일치하지 않는 항목이 있어도 경고가 표시되지 않습니다.
• 순서: groups 목록이 없는 업스트림은 마지막에 배치합니다. 이 업스트림은 모든 사용자에게 제공되므로, 앞에 나열되면 팀 전용 업스트림보다 먼저 해당 팀의 요청을 가져갑니다.

[!WARNING]

v2.1.314 이전 버전의 게이트웨이는 groups를 발견하면 시작을 거부하므로, 이를 추가하기 전에 모든 레플리카를 업그레이드하세요.

롤백하기 전에 groups 목록이 있는 각 업스트림과 이를 참조하는 모든 upstream_model 키 또는 가격 재정의를 제거하고, 업스트림을 최소 하나 이상 유지하세요. groups 키만 제거하면 해당 업스트림이 모든 개발자에게 개방됩니다. 제거된 업스트림을 여전히 참조하는 키나 재정의가 있으면 게이트웨이가 references unknown upstream 오류와 함께 시작되지 않습니다.

개발자가 나열된 그룹에 속하지 않은 경우

모든 업스트림에 groups 목록이 있으면, 해당 그룹 중 어디에도 속하지 않은 개발자에게는 다음 오류가 표시되며 게이트웨이는 어떤 공급자에도 연결하지 않습니다.

API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one

IdP에서 개발자를 나열된 그룹에 추가하거나, groups 목록이 없는 업스트림을 추가하세요.

게이트웨이는 토큰을 갱신할 때마다 개발자의 그룹을 다시 읽습니다. IdP가 갱신 시 그룹을 누락하면 해당 개발자는 그룹이 없는 상태가 됩니다.

• oidc.allowed_groups가 설정된 경우: 게이트웨이가 갱신을 거부하고 세션이 종료됩니다
• 그렇지 않고 groups 목록이 없는 업스트림이 있는 경우: 개발자의 요청이 해당 업스트림으로 이동합니다
• 그렇지 않고 모든 업스트림에 groups 목록이 있는 경우: 개발자의 요청이 위 오류와 함께 실패합니다

IdP의 userinfo 엔드포인트가 groups 클레임을 반환하고 oidc.google_groups가 설정되지 않은 경우, oidc.userinfo_fallback을 true로 설정하면 해당 엔드포인트에서 그룹을 가져와 채웁니다.

선택 섹션

login_notice

개발자가 로그인할 때 공지를 표시하려면 최상위 login_notice 키에 최대 500자의 공지 텍스트를 설정합니다. 다음 예시는 게이트웨이의 대상 사용자와 액세스 문의처를 안내합니다.

login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

개발자는 브라우저의 게이트웨이 인증 페이지와 터미널의 대화형 로그인 화면에서 Notice from <gateway hostname> 아래에 표시되는 텍스트를 확인합니다. 텍스트의 줄바꿈은 공백으로 바뀝니다. 공지는 로그인 전에 표시되므로 게이트웨이에 접근할 수 있는 누구나 읽을 수 있습니다.

게이트웨이 서버에 Claude Code v2.1.319 이상이 필요하며, 터미널 화면의 경우 개발자의 머신에도 필요합니다. 이전 버전의 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 키를 추가하기 전에 모든 레플리카를 업그레이드하고, 롤백하기 전에 키를 제거하십시오.

admin

선택 사항입니다. Anthropic의 공개 Admin API를 그대로 따르는 /v1/organizations/spend_limits와 /v1/messages에서의 개발자별 지출 한도 적용을 활성화합니다. 한도를 설정하고 적용하는 방법은 지출 한도를 참조하십시오. 이 섹션에서는 이 기능을 켜고 조정하는 gateway.yaml 키를 다룹니다.

admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits
  # Try eng-platform's pooled budget first, then eng-all's, then any other group's.
  pooled_conflict_rule: priority_list
  pooled_priority_order: [eng-platform, eng-all]

풀 예산 순서

풀 예산은 그룹 전체가 함께 사용하는 하나의 월간 한도입니다. 풀 예산을 설정하려면 그룹의 월간 한도를 설정하는 요청에 pooled_budget을 추가합니다. 예를 들어 $5,000의 경우 "pooled_budget": {"amount": "500000"}와 같이 작성합니다. 이 요청에는 그룹의 scope, "period": "monthly", amount도 포함되며, amount는 계속 각 구성원의 개별 한도로 사용됩니다.

이러한 그룹에 여러 개 속한 개발자의 경우, 각 요청은 지출이 한도 미만인 첫 번째 예산에 반영되며, 모든 예산이 소진되면 거부됩니다. pooled_conflict_rule은 게이트웨이가 예산을 시도하는 순서를 설정합니다.

• default_order: 가장 큰 한도부터, 한도가 같으면 그룹 이름의 오름차순으로 시도합니다
• priority_list: pooled_priority_order에 있는 그룹의 예산을 목록 순서대로 시도한 다음, 나머지 그룹의 예산을 그룹 이름순으로 시도합니다

pooled_conflict_rule: priority_list 없이 그룹을 나열하면 게이트웨이는 목록을 무시하고 부팅 시 경고를 로그에 기록합니다.

v2.1.319 이전의 게이트웨이 서버는 pooled_conflict_rule 또는 pooled_priority_order를 발견하면 시작을 거부합니다. 두 키 중 하나를 추가하기 전에 모든 레플리카를 업그레이드하고, 롤백하기 전에 두 키를 모두 제거하십시오.

enforcement

enforcement 블록은 저장소를 사용할 수 없을 때 지출 한도 검사가 어떻게 동작하는지 제어합니다.

pricing

pricing 블록은 지출 미터가 USD 정가 대신 어떤 요금을 적용할지 지정하므로, 한도와 /effective에 계약 요금이 반영됩니다. 금액은 USD로 유지되며 청구서가 아닌 추정치입니다. 사전 요구 사항은 두 가지입니다.

• 게이트웨이 서버에 Claude Code v2.1.227 이상이 필요합니다. 이전 버전은 부팅 시 알 수 없는 키를 거부합니다.
• admin: 블록, 또는 v2.1.268 이상에서는 정책이 하나 이상 있는 managed: 블록이 필요합니다. pricing이 설정되어 있는데 두 블록이 모두 없으면 이를 읽는 곳이 없으므로 게이트웨이가 시작되지 않습니다.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

미터가 재정의 행을 매칭하는 방식은 다음과 같습니다.

• 행은 upstreams[].name인 upstream이 model에 대해 처리하는 요청의 정가를 대체합니다. 여기에는 더 높은 빠른 모드 요금도 포함되므로, 빠른 요청과 일반 요청이 동일한 네 가지 요금으로 측정됩니다.
• claude-sonnet-4-6 같은 기본 제공 ID는 models[].id와 같은 방식으로 매칭되며, 미터가 해당 모델로 가격을 책정하는 모든 날짜 표기 형식, 리전별 Amazon Bedrock 형식, Google Cloud Agent Platform 형식을 포괄합니다. 별칭이나 추론 프로필 ARN 같은 그 밖의 문자열은 클라이언트가 보낸 ID 또는 업스트림으로 보낸 문자열과 대소문자 구분 없이 매칭됩니다.
• 행이 겹치는 경우 미터는 첫 번째 행이 아니라 가장 구체적인 행을 선택합니다. 즉 model이 업스트림으로 보낸 모델 문자열과 정확히 일치하는 행, 그다음 클라이언트가 보낸 ID와 정확히 일치하는 행, 그다음 기본 제공 모델을 지정한 행 순입니다.
• 알 수 없는 업스트림 이름은 부팅 실패를 일으키며, 하나의 업스트림에 동일한 모델을 지정한 두 행(하나의 기본 제공 모델을 두 가지 표기로 지정한 경우 포함)도 마찬가지입니다. 요청 가능한 모델이 사용할 수 없는 행에 대해서는 게이트웨이가 부팅 시 경고합니다.
• 웹 검색 요청은 $0.01 정가를 유지하며, multiplier는 여전히 적용됩니다.

리전별 요금을 적용하려면 각 리전에 고유한 이름의 업스트림을 지정하고 업스트림마다 행을 하나씩 두십시오.

가격 할증

게이트웨이 서버에 v2.1.271 이상이 있으면 multiplier를 1보다 크게(최대 10) 설정하여 내부 차지백 요금처럼 공급자가 청구하는 금액보다 많이 측정할 수 있습니다. 다음 예시는 모든 요청을 가격의 120%로 측정합니다.

pricing:
  multiplier: 1.2

admin: 블록이 있으면 할증이 지출 한도에도 적용됩니다. 미터가 가격의 120%를 계산하므로 개발자가 한도에 더 빨리 도달합니다. 게이트웨이는 부팅 시 이를 알리는 경고를 로그에 기록합니다.

multiplier는 업스트림 공급자가 요청에 대해 청구하는 금액을 변경하지 않습니다.

게이트웨이가 로그인한 클라이언트에 요금도 전송하는 경우, 개발자가 할증을 확인하려면 Claude Code v2.1.271 이상이 필요합니다. 이전 클라이언트는 1보다 큰 multiplier를 무시하고 할증 없이 비용을 표시합니다.

v2.1.271 이전 게이트웨이 서버는 multiplier를 1보다 크게 설정하면 시작되지 않습니다.

로그인한 클라이언트에 요금 전송

게이트웨이 서버에서 v2.1.268 이상을 사용하면, 게이트웨이는 pricing의 요금을 자신이 제공하는 managed 정책에 modelPricing 관리형 설정으로 함께 넣습니다.

그러면 정책과 일치하는 개발자는 /usage, 상태줄, OpenTelemetry에서 pricing 요금을 보게 됩니다. 어떤 정책과도 일치하지 않는 개발자는 관리형 설정을 받지 않으므로 수치가 정가로 유지됩니다. 클라이언트는 Claude Code v2.1.242 이상에서 이 설정을 적용합니다.

• 게이트웨이가 추가하는 항목: 정책의 cli 블록에 이미 modelPricing이 설정되어 있지 않으면, 게이트웨이는 multiplier와, 클라이언트가 요청할 수 있는 모든 모델 ID에 대해 해당 ID를 처리하는 첫 번째 업스트림의 재정의 행을 추가합니다. 장애 조치 업스트림만 청구하는 요금은 게이트웨이에만 남습니다.
• groups 목록이 있는 업스트림: 이런 업스트림이 특정 모델 ID를 처리하는 첫 번째 업스트림이면, 게이트웨이는 해당 ID에 대한 행을 추가하지 않습니다. 그러면 개발자는 해당 ID에 대한 Claude Code 자체 요금을 보게 되며, 이는 Claude Code가 ID를 인식하는 경우 모델의 표준 요금에 multiplier를 곱한 값입니다.
• 특정 정책 제외: 해당 정책의 cli 블록에서 modelPricing을 {}로 설정하면 그 정책의 개발자는 정가로 유지됩니다.
• 정책 자체 요금 유지: cli 블록에서 자체 multiplier 또는 overrides로 modelPricing을 설정한 정책은 해당 modelPricing을 그대로 유지하며, 게이트웨이는 자체 요금을 추가하지 않습니다.

models

models 블록은 관리자가 선별하는 선택적 모델 목록으로, /v1/models에서 제공되며 업스트림별로 모델 ID를 변환하는 데 사용됩니다. 미국 외 Amazon Bedrock 리전, Amazon Bedrock 프로비저닝된 처리량 ARN, Microsoft Foundry 배포 이름에는 필수입니다.

auto_include_builtin_models: true   # false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # or an inference-profile ARN
      foundry: your-opus-deployment-name

upstream_model 아래의 각 키는 구성된 업스트림의 name과 일치해야 하며, 기본값은 공급자 이름입니다. 어떤 업스트림과도 일치하지 않는 키는 부팅 실패를 일으키므로, 사용하지 않는 공급자의 줄은 생략하십시오.

managed

managed 블록은 IdP 그룹 또는 이메일 도메인을 기준으로 하는 역할 기반 접근 정책을 정의합니다. 정책은 순서대로 평가되며, 기본적으로 첫 번째로 매칭된 정책이 선택된 다음 match: {} 포괄 기본 정책 위에 병합됩니다. 두 역할 정책에 매칭되는 사용자는 첫 번째 정책만 받으므로, 매칭되는 모든 정책을 적용하지 않는 한 두 번째 정책의 거부 규칙은 적용되지 않습니다. 정책은 ETag/304 캐싱과 함께 GET /managed/settings에서 사용자별로 제공됩니다.

managed:
  policies:
    # Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Make the Default option in /model resolve inside each policy's
        # list. The eng-contractors policy inherits enforceAvailableModels.
        enforceAvailableModels: true

관례상 마지막에 나열하는 match: {} 캐치올은 기본 계층으로 취급됩니다. 다른 모든 정책은 설정하지 않은 키를 캐치올에서 상속하므로, 역할별 항목에는 조직 기본값과 다른 부분만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다.

• 허용 목록: availableModels 및 permissions.allow. 특정 정책의 목록이 기본 정책의 목록을 완전히 대체합니다.
• 거부 목록 및 훅 배열: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces, deniedModels, 그리고 모든 hooks 이벤트 유형 배열. 이들은 기본 정책과 정책의 합집합을 취하므로, 조직 전체의 거부 규칙이나 감사 훅이 역할별 재정의로 인해 실수로 누락되지 않습니다.
• 레코드 유형 키: env, modelOverrides, skillOverrides. 이들은 얕은 병합을 수행하므로, 역할별 env 블록은 자신이 설정한 키를 재정의하고 나머지는 기본 정책에서 상속합니다.

availableModels는 /v1/messages에서 서버 측으로도 적용되므로, 거부된 모델은 클라이언트가 무엇을 보내든 400을 반환합니다. 빈 목록은 모든 모델을 거부합니다. 이 검사는 개발자가 모델을 선택하기 전 세션이 시작되는 모델에도 적용되므로, 정책이 허용하는 모델로 세션을 시작하도록 하십시오.

게이트웨이는 요청을 중계하기 전에 model 값 자체를 검증하므로, 잘못된 형식의 값은 업스트림에 도달하지 않습니다. 다음 두 경우에 요청을 400으로 거부합니다.

• 값이 없거나 비어 있으면 게이트웨이는 model is required 메시지와 함께 요청을 거부합니다. 이 검사에는 Claude Code v2.1.228 이상을 실행하는 게이트웨이가 필요합니다.
• 값이 있지만 문자열이 아니면 게이트웨이는 model must be a string 메시지와 함께 요청을 거부합니다. Claude Code v2.1.221 이상을 실행하는 게이트웨이가 필요합니다.

어떤 정책과도 매칭되지 않는 인증된 사용자는 게이트웨이 기본값을 받으며, 이는 카탈로그의 모든 모델과 관리형 설정 없음을 의미합니다. 기본 정책을 보장하려면 마지막에 match: {} 캐치올을 추가하십시오.

그룹 정책의 규칙은 사용자의 토큰에 해당 그룹이 포함된 동안에만 적용되므로, 조직 전체 거부 규칙은 match: {} 정책에 넣으세요.

[!NOTE]

게이트웨이는 자체 사용자 디렉터리를 보관하지 않습니다. 사용자의 IdP 토큰으로 각 요청을 승인하며, 토큰의 groups 클레임에서 그룹 멤버십을 읽고 이를 기준으로 정책을 평가합니다. 열거할 명단도, 미리 생성할 계정도 없으므로 SCIM이 동기화할 대상이 없어 SCIM 엔드포인트도 없습니다.

사용자 및 그룹 수명 주기 관리는 신뢰할 수 있는 원본, 즉 IdP의 기본 SCIM 프로비저닝이나 전용 ID 거버넌스 플랫폼에서 수행하십시오. 그곳에서 관리되는 멤버십과 프로비저닝 해제는 토큰을 통해 게이트웨이에 자동으로 반영됩니다. Claude 계정 자체의 SCIM 프로비저닝이 필요하다면 이는 Claude for Enterprise 기능입니다.

두 가지 반영 주기가 적용됩니다.

• 정책 내용: 정책을 편집하고 재배포하면 연결된 Claude Code 클라이언트의 다음 관리형 설정 폴링 시(1시간 이내) 반영됩니다. 단, 다음 실행 시에만 적용되는 변경 사항은 예외입니다
• 그룹 멤버십: 사용자의 그룹 멤버십을 변경하면 매칭되는 정책이 바뀝니다. 이는 다음 세션 재발급, 즉 session.ttl_hours로 제한되는 다음 자동 갱신 시 적용됩니다.

Claude Desktop은 자체 일정을 따릅니다.

매칭되는 모든 정책 적용

여러 역할 정책에 매칭되는 사용자는 policies 옆에 policy_mode: layered를 설정하지 않는 한 첫 번째 정책만 받습니다. layered를 사용하면 첫 번째 match: {} 정책까지 사용자와 매칭되는 모든 정책이 적용됩니다.

policy_mode에는 게이트웨이 서버의 Claude Code v2.1.316 이상이 필요합니다. 이를 지원하지 않는 버전의 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 키를 추가하기 전에 모든 복제본을 업그레이드하고, 이전 버전으로 롤백하기 전에 키를 제거하세요. 다음 예시에서는 한 그룹이 WebFetch를 잃고 다른 그룹이 Opus를 얻습니다.

managed:
  policy_mode: layered
  policies:
    - match: { groups: [no-web] }
      cli:
        permissions: { deny: ["WebFetch"] }
    - match: { groups: [opus-users] }
      cli:
        availableModels: [opus, sonnet]
    - match: {}
      cli:
        availableModels: [sonnet]
        enforceAvailableModels: true

다음 표는 no-web과 opus-users에 모두 속한 사용자가 기본값인 first_match와 layered에서 각각 무엇을 받는지 보여 줍니다.

게이트웨이는 매칭되는 각 정책을 그 아래에 나열된 정책 위에 기본 계층과 같은 병합 규칙으로 병합합니다.

• 허용 목록, 단일 값, sandbox 같은 블록: 각각 이를 설정한 정책 중 가장 먼저 나열된 매칭 정책에서 통째로 가져오므로, 두 그룹의 availableModels 목록은 합산되지 않습니다.
• 거부 목록과 훅 배열: 매칭되는 모든 정책에 걸쳐 합산되므로, 두 그룹에 속한 사용자는 두 그룹의 거부 규칙을 모두 받습니다.
• env, modelOverrides, skillOverrides: 항목은 이름별로 병합되며, 해당 이름을 설정한 정책 중 가장 먼저 나열된 매칭 정책이 값을 제공합니다.
• desktop 키: 기본 desktop 블록에 대한 규칙에 따라 병합됩니다.

[!WARNING]

정책이 합쳐지면 어느 한 정책만으로는 주어지지 않는 더 느슨한 규칙이 될 수 있습니다. 예를 들어 match: {} 정책은 sandbox.enabled: true를 설정하고, 한 그룹의 정책은 permissions.allow: ["Bash"]를, 다른 그룹의 정책은 sandbox.enabled: false를 설정한다고 가정합니다. 두 그룹에 모두 속한 사용자는 샌드박스가 꺼진 상태로 Bash가 허용됩니다. 이 경우 Bash를 허용하는 정책을 맨 앞에 나열하고, match: {} 정책의 sandbox 블록 전체를 그 정책에 복사하세요.

layered를 사용하면 게이트웨이는 다음을 포함한 일부 설정에서 시작을 거부합니다.

• ! 패턴: match: {} 정책을 포함한 모든 정책의 permissions.deny 또는 permissions.ask 목록에 있는 Read 또는 Edit 규칙의 ! 부정
• 포괄 정책 외부의 훅 제한: match: {} 이외의 정책에 있는 disableAllHooks, allowedHttpHookUrls, httpHookAllowedEnvVars

정책이 허용하는 모델로 세션 시작

availableModels에 Claude Code의 기본 모델이 빠져 있으면, 개발자가 /model 등으로 목록에 있는 모델을 선택할 때까지 세션이 400 응답을 받습니다. 게이트웨이 세션에서 기본 모델은 opus 별칭이 가리키는 Opus 모델이며, availableModels만으로는 이를 바꾸지 않습니다.

이를 해결하려면 같은 cli 블록에 enforceAvailableModels: true를 설정한 다음, 목록에 어떤 종류의 항목이 있는지 확인하십시오.

• sonnet 같은 별칭 또는 claude-sonnet-4-6 같은 기본 제공 ID: 세션이 그중 하나의 모델로 시작되며, /model의 Default 옵션이 해당 모델로 결정됩니다
• 목록에 별칭이나 기본 제공 ID가 없는 경우: 세션이 계속 기본 제공 기본 모델로 시작될 수 있으므로, 해당 정책의 cli 블록에서 model도 목록의 ID 중 하나로 설정하십시오

다음 정책은 models가 정의하는 사용자 지정 ID 하나를 나열하고 해당 ID로 세션을 시작합니다.

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [restricted-claude-opus-4-8]
        enforceAvailableModels: true
        model: restricted-claude-opus-4-8
        env:
          ANTHROPIC_DEFAULT_OPUS_MODEL: restricted-claude-opus-4-8   # opus and Default resolve to the ID too

부팅 시 게이트웨이를 중지시키는 matcher 값

부팅 시 게이트웨이는 모든 정책의 match 블록과 admin_groups 목록을 검사합니다. 다음 값 중 하나라도 있으면 게이트웨이는 해당 필드를 명시하는 오류와 함께 중지됩니다.

• 빈 groups 목록
• groups 또는 admin_groups의 빈 항목
• 빈 email_domain
• @, 공백 또는 쉼표가 포함된 email_domain. 게이트웨이는 이 검사 전에 값의 앞뒤 공백을 제거하고 맨 앞의 @ 하나를 제거합니다. example.com처럼 도메인 하나만 작성하십시오.

v2.1.232 이전에는 게이트웨이가 이러한 값으로도 시작되었습니다. 각 값의 영향은 다음과 같았습니다.

• 빈 email_domain: 게이트웨이가 도메인 검사를 건너뛰었으므로, 빈 email_domain이 있고 groups 목록이 없는 정책은 인증된 모든 사용자와 매칭되었습니다
• 빈 groups 목록: 정책이 아무와도 매칭되지 않았습니다
• @, 공백 또는 쉼표가 포함된 email_domain: 정책이 아무와도 매칭되지 않았습니다
• groups 또는 admin_groups의 빈 항목: 해당 사용자의 IdP groups 클레임에도 빈 항목이 있는 경우에만 사용자와 매칭되었습니다. admin_groups에서는 이 매칭이 관리자 액세스 권한을 부여했습니다. admin_groups 목록에 빈 항목이 한 번도 없었다면 이런 방식으로 관리자 액세스 권한을 얻은 사람은 없습니다.

cli 또는 code 선택

[!WARNING]

정책이 code 키를 사용할 때 다음 각 항목은 게이트웨이 시작을 막습니다.

• 게이트웨이 버전: code에는 게이트웨이 서버에 Claude Code v2.1.296 이상이 필요합니다. 이전 게이트웨이는 이 키를 발견하면 시작되지 않습니다. 키를 추가하기 전에 모든 레플리카를 업그레이드하고, 이전 버전으로 롤백하기 전에는 code를 다시 cli로 변경하십시오.
• 혼합된 키: code와 cli(또는 그 이전 표기인 settings)가 모두 있는 파일은 부팅 시 게이트웨이를 중지시킵니다. 한 번의 편집으로 모든 블록을 하나의 키 아래에 두십시오.

.env 파일 읽기를 거부하는 규칙 같은 정책의 Claude Code 설정은 cli 또는 code 키 아래의 블록에 들어갑니다. code가 권장 키이고 cli는 레거시 키입니다. 두 키는 동일한 내용을 받습니다. 키는 설정이 적용되는 위치를 결정합니다.

• cli: 터미널, VS Code 및 JetBrains 확장 프로그램, Agent SDK. cli 아래에서는 Claude Desktop의 Code 탭이 파생 설정을 받으므로, Read(./.env) 같은 범위 지정 규칙은 그곳에서 사용자를 막지 않습니다.
• code: 동일한 위치에 더해 Claude Desktop의 Code 탭까지 적용할 수 있습니다.

cli를 사용하는 파일은 기존대로 동작하며, desktop 키가 있는 정책에서 cli를 발견한 게이트웨이는 부팅 시 경고하되 그대로 시작됩니다. 설정이 Code 탭에도 적용되도록 하려면 code로 전환하십시오.

전환하기 전에 Code 탭에 code 설정 적용을 읽어 보십시오. 설정이 그곳에 적용되려면 정책에 desktop 키가 필요하고 사용자 머신에 설정 작업이 필요하며, Claude Desktop에서 웹 검색이 꺼집니다.

다음 정책은 거부 규칙을 code 아래에 두고 빈 desktop 키를 함께 둡니다.

managed:
  policies:
    - match: {}
      code:
        permissions: { deny: ["Read(./.env)"] }
      desktop: {}

전환할 때는 블록 이름을 바꾸는 동일한 편집에서 serve_to_desktop 줄을 모두 삭제하십시오. 안내에서 cli 블록을 언급하는 곳에서는 code 블록을 사용하십시오.

serve_to_desktop: true는 정책의 cli 설정을 Code 탭에 제공하는 레거시 방식입니다. Claude Desktop이 bootstrapUrl을 통해 연결하는 경우에는 효과가 없습니다. 정책이 cli를 사용하는 동안 이 키를 언급하는 부팅 경고가 나타나면 해당 설정이 Code 탭에 도달하지 않고 있다는 의미입니다.

• Code 탭에 적용하려면: 사용자 머신이 Code 탭에 code 설정 적용의 조건을 충족하면 code로 전환하십시오
• cli를 유지하려면: 경고를 없애기 위해 정책에서 cli 옆에 serve_to_desktop: false를 설정하십시오

cli에 들어가는 내용

각 code 또는 cli 값은 완전한 Claude Code managed-settings.json 문서로, MDM이나 /etc/claude-code/managed-settings.json을 통해 배포하는 것과 동일한 스키마를 여기서는 YAML로 표현한 것입니다. CLI는 전달된 문서를 사용자 및 프로젝트 설정보다 상위인 관리형 계층에서, 서버 관리형 설정 대신 적용합니다. 따라서 policyHelper 및 wslInheritsWindowsSettings처럼 OS 수준 정책 소스로 제한된 설정은 무시합니다.

게이트웨이는 부팅 시 CLI의 설정 스키마로 각 문서를 검증하므로, 인식되지 않는 최상위 키가 있으면 문제가 되는 모든 키를 명시하는 오류와 함께 부팅이 실패합니다. 스키마에서 의도적으로 열려 있는 부분은 여전히 임의의 값을 허용하는데, 이는 최신 클라이언트가 게이트웨이 스키마에 없는 항목을 인식할 수 있기 때문입니다. 이러한 열린 키에는 env, pluginConfigs, permissions 아래에 중첩된 키가 포함됩니다.

검증에는 게이트웨이에 설치된 버전에 번들된 스키마가 사용되므로, 최신 Claude Code 릴리스에서 도입된 최상위 설정 키를 관리형 구성에 넣으려면 먼저 게이트웨이를 업그레이드해야 합니다. 새 정책을 배포하기 전에 클라이언트 하나에서 스모크 테스트하십시오.

전체 키 참조는 Claude Code 설정에 있습니다. 운영자가 가장 먼저 사용하는 키는 다음과 같습니다.

managed:
  policies:
    - match: {}
      cli:
        # Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        enforceAvailableModels: true              # Default resolves inside the list

        # Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignore user/project permission rules

        # Environment pushed into the CLI process. DISABLE_UPDATES blocks
        # background and manual updates; DISABLE_AUTOUPDATER stops only
        # background updates.
        env:
          DISABLE_UPDATES: "1"                    # pin versions via your own distribution

        # Org-wide hooks. Hook commands run on developer machines, not the
        # gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

이러한 설정은 네트워크를 통해 전달되므로, CLI는 아래 나열된 설정을 적용하기 전에 각 개발자에게 보안 승인 대화상자를 표시합니다.

• hooks
• 프록시 및 기본 URL 변수처럼 개발자의 승인이 필요한 env 변수
• apiKeyHelper 및 statusLine 같은 셸 실행 설정
• 샌드박스 바이너리 설정 sandbox.bwrapPath, sandbox.socatPath, sandbox.ripgrep
• sandbox.network.tlsTerminate 및 프록시 포트 설정처럼 트래픽을 가로채거나, 자격 증명을 주입하거나, 격리를 약화시키는 샌드박스 설정. 보안 승인 대화상자에 모두 나열되어 있습니다.

승인 기억에서 승인이 유지되는 기간과 대화상자가 다시 나타나는 시점을 다룹니다.

Claude Code는 모델 선택 설정 및 숫자 제한처럼 일부 전달된 env 변수를 개발자에게 승인 대화상자를 표시하지 않고 적용합니다. 전달된 다른 변수는 개발자의 승인이 필요할 수 있으며, 비어 있지 않은 프록시, 기본 URL 또는 OTEL_EXPORTER_OTLP_ENDPOINT 값은 항상 승인이 필요합니다. 전달된 변수에 승인이 필요하면 대화상자에 해당 변수가 표시됩니다. 전달된 값에 따라 승인 필요 여부가 결정되는 네 가지 개인정보 토글을 포함한 세부 사항은 환경 변수와 승인 대화상자를 참조하십시오.

게이트웨이의 텔레메트리 구성은 OTEL_EXPORTER_OTLP_ENDPOINT를 푸시하므로, telemetry.forward_to를 설정하면 각 대화형 클라이언트에서 대화상자가 표시됩니다. 이 대화상자는 손상되었거나 악의적인 게이트웨이로부터 개발자의 머신을 보호하기 위한 것이지, 개발자로부터 조직을 보호하기 위한 것이 아닙니다.

claude -p, Agent SDK 세션, Claude Desktop의 Code 탭 세션 같은 비대화형 실행은 대화상자를 표시할 수 없습니다. 이 경우 푸시된 설정을 해당 실행에만 적용하고 승인된 것으로 기록하지 않으므로, 개발자의 다음 대화형 세션에서는 여전히 대화상자가 표시됩니다.

개발자가 거부하면 Claude Code는 정책을 적용하지 않고 해당 세션을 종료합니다. 따라서 광범위한 정책에 새 훅이나 대화상자를 유발하는 env 변수를 푸시하면, 매칭되는 모든 개발자가 대화형 세션에서 대화상자를 보게 됩니다. 실행 중인 대화형 세션에서는 다음 1시간 단위 폴링 시 표시되며, 그렇지 않으면 개발자의 다음 대화형 시작 시 나타납니다.

cli 키는 이전 릴리스에서 settings라는 이름이었으며, 게이트웨이는 여전히 이 표기를 별칭으로 허용합니다. 새 배포에서는 code를 사용하십시오.

배포 전 정책 테스트

정책 변경을 테스트하려면 임시 Postgres 데이터베이스를 대상으로 게이트웨이를 시작하십시오. 게이트웨이는 cli, code, desktop 블록의 내용을 검사하기 전에 Postgres에 연결하고 스키마 마이그레이션을 적용합니다. 데이터베이스에 연결할 수 없으면 시작이 could not connect to Postgres에서 멈추고 블록 내용에 대해서는 아무것도 보고하지 않습니다.

터미널 세션의 컨텍스트 윈도우

/login으로 로그인한 터미널 세션은 Opus 4.7 이상, Sonnet 5 이상, Fable 모델에 1M 컨텍스트 윈도우를 사용합니다. 모델 ID에 [1m] 접미사가 필요 없으며, 세션은 약 967K 토큰에서 압축됩니다. 개발자 머신의 Claude Code v2.1.287 이전에는 모델 ID가 [1m]으로 끝나지 않는 한 Claude Code가 Opus 및 Fable 모델을 200K 윈도우로 취급했습니다.

대신 터미널 세션이 200K 경계에서 압축되도록 하려면 정책의 env에서 자동 압축 윈도우를 설정하십시오.

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

Claude Code는 이 변수를 개발자에게 승인 대화상자를 표시하지 않고 적용합니다. 이 변수는 [1m]으로 끝나는 모델 ID를 포함한 모든 모델에 적용됩니다.

대신 1M 컨텍스트를 끄려면 같은 env 블록에서 CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"을 설정하십시오. 그러면 Claude Code는 모든 모델을 200K 윈도우로 취급합니다. 대화형 세션에서는 이 변수가 적용되기 전에 각 개발자가 승인 대화상자에서 승인해야 합니다.

1시간 프롬프트 캐시

기본 5분 대신 1시간 프롬프트 캐시 TTL을 요청하려면 정책의 기존 code, cli 또는 settings 블록에 다음 키를 추가하고 게이트웨이를 다시 시작하십시오. 이 키에는 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.242 이상이 필요합니다.

promptCacheTtl은 메인 대화를 다룹니다. subagentPromptCacheTtl은 선택 사항이며 서브에이전트, 워크플로, 백그라운드 요청을 다룹니다. 다음 예시는 cli 키를 사용하는 match: {} 정책에 두 키를 모두 추가합니다.

managed:
  policies:
    - match: {}
      cli:
        promptCacheTtl: 1h
        subagentPromptCacheTtl: 1h

[!WARNING]

업스트림이 게이트웨이가 제공하는 모든 모델에 대해 1시간 TTL을 지원하는 경우에만 이 키를 설정하십시오. 업스트림이 TTL을 거부하면 요청이 실패하며, 게이트웨이와 Claude Code 모두 5분 TTL로 재시도하지 않습니다. Amazon Bedrock의 경우 지원되는 모델, 리전 및 제한을 확인하십시오.

promptCacheTtl을 확인하려면 정책과 매칭되는 사용자로 게이트웨이에 로그인하여 캐시 쓰기에 사용된 TTL을 확인하십시오. 게이트웨이가 제공하는 각 모델에 대해 확인을 반복하려면 --model을 전달하십시오.

1시간 캐시 쓰기는 5분 쓰기보다 비용이 더 높습니다. 지출 한도가 이 더 높은 요금을 계산하려면 게이트웨이 서버에 v2.1.286 이상이 필요합니다.

정책의 MCP 서버

정책과 매칭되는 Claude Code 클라이언트에 MCP 서버를 제공하려면 해당 정책의 cli 블록에서 managedMcpServers를 설정하십시오. 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.259 이상이 필요합니다.

게이트웨이는 부팅 시 Claude Code가 클라이언트에서 적용하는 것과 동일한 규칙으로 각 항목을 검사하며, 항목이 검사에 실패하면 시작을 거부하고 해당 항목을 명시합니다.

gateway.yaml에 ${VAR} 참조를 작성하면, 게이트웨이는 항목 검사를 실행하기 전에 부팅 시 시크릿 확장을 통해 자신의 환경에서 이를 해석하므로, 매칭되는 모든 클라이언트가 리터럴 값을 받고 읽을 수 있습니다. 제공되는 서버에 대한 헤더 지침은 확장된 값에 적용됩니다.

게이트웨이는 cli 블록에서 .mcp.json 표기인 mcpServers를 거부하며, 부팅 오류에서 사용할 키로 managedMcpServers를 명시합니다. v2.1.259 이전에는 게이트웨이가 cli 블록의 모든 MCP 서버 정의를 거부했습니다.

Claude Desktop 오버레이

조직에서 Claude Desktop도 배포하는 경우, 동일한 게이트웨이가 두 클라이언트를 모두 지원합니다. Claude Desktop의 관리형 구성에서 bootstrapUrl을 <listen.public_url>/user/bootstrap으로 지정하십시오. Claude Desktop은 이 URL에서 OAuth 발급자를 도출하고, 이 게이트웨이를 대상으로 동일한 디바이스 코드 로그인을 실행하며, 응답에서 구성을 가져옵니다.

[!NOTE]

게이트웨이 서버에 Claude Code v2.1.203 이상과 명시적인 옵트인이 필요합니다. 사용자와 매칭되는 정책에 desktop 키가 없으면 /user/bootstrap은 404를 반환합니다. 빈 desktop: {}로 정책을 옵트인할 수 있으며, match: {} 기본 계층의 desktop 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 desktop_bootstrap.serve 또는 desktop_bootstrap.denied로 기록합니다.

Claude Desktop을 배포하지 않는 경우 정책에서 desktop을 완전히 제외하십시오. 그러면 게이트웨이는 모든 사용자에 대해 /user/bootstrap에서 404를 반환합니다.

게이트웨이가 Claude Desktop용으로 도출하는 설정

게이트웨이는 부트스트랩 응답의 상당 부분을 매칭된 정책의 cli 또는 code 블록과 최상위 게이트웨이 구성에서 도출합니다.

• 모델 목록: availableModels에서 도출합니다. 목록에서는 정책이 deniedModels 또는 availableModelsMatch: exact로 차단하는 모델이 제외됩니다. 이 필터에는 게이트웨이 서버에 Claude Code v2.1.299 이상이 필요합니다. 각 모델의 1M 컨텍스트 옵션은 Claude Desktop의 확장 컨텍스트에서 다룹니다

• 비활성화된 도구: 도구 이름만 있는 permissions.deny 항목에서 도출합니다. 정책의 desktop 블록에서 disabledBuiltinTools를 설정하면 게이트웨이는 설정한 값과 도출된 목록의 합집합을 제공하므로, 이 방식으로 더 많은 도구를 비활성화할 수는 있지만 permissions.deny로 비활성화한 도구를 다시 활성화할 수는 없습니다

• 이그레스 허용 목록: sandbox.network.allowedDomains에서 도출합니다. 정책의 desktop 블록에서 coworkEgressAllowedHosts를 설정하면 게이트웨이는 도출된 목록 대신 해당 값을 사용합니다. 게이트웨이가 제공하는 허용 목록에 *가 포함되어 있고 게이트웨이가 Claude Desktop의 allowedWorkspaceFolders도 함께 제공하지 않으면, Claude Desktop은 Code 탭에서 Bash 샌드박스를 켜지 않습니다

• 게이트웨이 자신을 가리키는 OTLP 엔드포인트와 로그인한 사용자의 ID 속성. 게이트웨이는 해당 엔드포인트에서 받은 내보내기 데이터를 forward_to 대상으로 중계합니다. telemetry.forward_to와 listen.public_url을 모두 설정하면 엔드포인트와 속성이 포함됩니다.

  Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다. 기본은 http/protobuf이며, 정책의 env에서 OTEL_EXPORTER_OTLP_PROTOCOL 또는 신호별 변형 중 하나를 http/json으로 설정하면 http/json을 사용합니다. 게이트웨이 서버의 Claude Code v2.1.261 이전에는 응답이 항상 http/json을 설정했으므로, protobuf만 받는 수집기는 Claude Desktop의 내보내기를 거부했습니다

정책의 desktop 블록에서 disabledBuiltinTools, coworkEgressAllowedHosts 또는 Claude Desktop 자체의 managedMcpServers 설정을 지정하려면 게이트웨이 서버에 Claude Code v2.1.232 이상이 필요합니다. Claude Desktop의 managedMcpServers는 객체가 아닌 배열 값을 받습니다.

게이트웨이는 hooks 및 Bash(npm *) 같은 범위 지정 권한 규칙처럼 Claude Desktop에 대응하는 항목이 없는 키를 부트스트랩 응답에서 생략합니다.

Code 탭에 code 설정 적용

정책이 code 키 아래에 보유한 Claude Code 설정은 다음 조건이 모두 충족될 때 Claude Desktop의 Code 탭에 적용됩니다.

• 정책에 desktop 키도 있어야 하며, 빈 desktop: {}도 해당됩니다
• Claude Desktop이 버전 2.9939.2 이상이어야 합니다
• 머신의 Claude Code 관리형 설정이 이 게이트웨이를 지정해야 합니다
• 해당 머신이 사설 네트워크에서 HTTPS로 게이트웨이에 연결되어야 합니다

마지막 두 조건은 세션에서 Claude Code를 실행하는 머신에 적용됩니다. 로컬 세션의 경우 사용자 자신의 컴퓨터이고, SSH를 통한 Code 탭 세션의 경우 원격 호스트입니다.

cli를 code로 이름을 바꾸기 전에 해당 머신에 클라이언트 측 관리형 설정을 배포하십시오. 처음 두 조건이 충족되고 마지막 두 조건 중 하나가 충족되지 않으면, 정책과 매칭되는 사용자는 다음 결과 중 하나를 얻습니다.

• HTTPS 연결, Claude Desktop이 Claude Code v2.1.296 이상을 번들하는 경우: Code 탭이 시작되지 않으며, 사용자의 프롬프트에 대한 응답에서 그 이유를 알려 줍니다
• HTTPS 연결, Claude Desktop이 이전 버전을 번들하는 경우: Code 탭이 code 설정 없이 시작되며, 세션에서 이를 알리지 않습니다
• 일반 HTTP 연결: Claude Desktop이 번들하는 버전과 관계없이 Code 탭이 code 설정 없이 시작됩니다

게이트웨이 앞단의 프록시가 /managed/settings에 자체 404로 응답하는 경우에도, 네 가지 조건을 모두 충족하는 머신을 포함하여 Code 탭이 code 설정 없이 시작됩니다.

desktop 키가 있는 정책에서 설정을 포함하는 code 블록은 Cowork, Chat, Code 탭에서 WebSearch 도구를 끕니다. MCP 서버에 대해서는 managedMcpServers가 적용되는 위치를 참조하십시오.

Claude Desktop 설정 직접 지정

Claude Desktop 설정을 직접 지정하려면 cli와 함께 선택적 desktop 블록을 추가하십시오. Claude Desktop의 관리형 구성 참조에 있는 설정을 평면 키 이름으로 작성하십시오. bootstrapUrl처럼 Claude Desktop이 MDM이나 로컬 파일에서만 읽는 키는 제외하십시오. 게이트웨이는 부팅 시 이를 거부합니다.

다음 예시는 eng-contractors 그룹에 대해 cli 설정과 함께 세 가지 Claude Desktop 키를 설정합니다.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        enforceAvailableModels: true
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

모든 키는 선택 사항이며, 생략한 키에는 Claude Desktop 자체 기본값이 적용됩니다.

게이트웨이가 부팅 시 거부하는 항목

게이트웨이는 부팅 시 Claude Desktop 자체가 사용하는 구성 스키마로 각 desktop 블록을 검증하므로, 실수가 연결된 모든 데스크톱에 도달하는 대신 게이트웨이 시작 시 해당 키를 명시하는 오류로 드러납니다. 블록에 다음이 포함되면 게이트웨이는 부팅에 실패합니다.

• 알 수 없는 키
• 빈 값이나 중첩 항목 안의 철자가 틀린 하위 키처럼 Claude Desktop이 거부하거나 조용히 무시할 값을 가진 인식된 키. v2.1.260 이전에는 게이트웨이가 managedMcpServers 또는 orgPluginSettings 항목의 중첩 객체 안에 있는 철자가 틀린 필드를 부팅 실패 대신 조용히 무시했습니다.
• 게이트웨이가 직접 계산하는 키: 추론 연결, 모델 목록, OTLP 중계. 이는 upstreams, models, telemetry 섹션의 forward_to를 통해 구성하십시오.
• 현재 키의 레거시 별칭. 부팅 오류에서 게이트웨이는 작성해야 할 표준 키를 명시합니다.

transport가 없는 managedMcpServers 항목처럼 deprecated 값이나 항목 형태를 사용하면, 게이트웨이는 시작되고 대체 항목을 명시하는 경고를 로그에 기록합니다.

v2.1.232 이전에는 게이트웨이가 chatTabEnabled 및 disableAutoUpdates 같은 11개의 고정된 기능 게이트 키 목록만 허용하고 다른 모든 키를 부팅 시 거부했습니다. v2.1.227 이전에는 게이트웨이가 chatTabEnabled와 chatAdvancedFileAnalysisEnabled도 부팅 시 거부했습니다.

이후 버전의 게이트웨이 또는 Claude Desktop이 필요한 키

게이트웨이는 cli 블록과 마찬가지로, 설치된 버전에 번들된 스키마로 desktop 블록을 검증합니다. 최신 Claude Desktop 릴리스에서 도입된 설정을 전달하려면 먼저 게이트웨이를 업그레이드하십시오. 예를 들어 userPluginMarketplacesEnabled와 userPluginUploadsEnabled에는 게이트웨이 서버에 Claude Code v2.1.260 이상, 구성원 머신에 Claude Desktop 1.37937.0 이상이 필요합니다.

blockReadsOutsideWorkingDirectories, disableBypassPermissionsMode, configRecheckIntervalMinutes, sshClientPath에는 게이트웨이 서버에 Claude Code v2.1.281 이상이 필요합니다. microsoftAuthBroker의 required 값과 Microsoft 365 managedMcpServers 항목의 continuousAccessEvaluation 필드도 마찬가지입니다. required 값보다 이전의 Claude Desktop 릴리스는 이를 disabled로 읽으므로, 모든 구성원의 Claude Desktop이 이를 지원한 후에만 required를 설정하십시오. Claude Desktop의 관리형 구성 참조에 각 키를 처음 읽는 릴리스가 나열되어 있습니다.

[!NOTE]

sshTransport에는 게이트웨이 서버에 Claude Code v2.1.293 이상이 필요합니다.

정책의 desktop 블록에서 orgPluginSettings를 설정하면, 게이트웨이는 Claude Desktop 1.15200.0 이상이 읽는 배열 형식으로 이를 제공합니다. 이전 데스크톱은 배열을 무시하고 플러그인 도구 정책을 적용하지 않으므로, 이에 의존하기 전에 구성원을 1.15200.0 이상으로 업데이트하십시오.

역할 정책이 기본 desktop 블록을 상속하는 방식

게이트웨이는 정책의 cli 블록을 기본 정책에서 채우는 것과 같은 방식으로, 정책의 desktop 블록이 설정하지 않은 키를 match: {} 캐치올의 desktop 블록에서 채웁니다. 기본 정책과 역할 정책 모두에서 disabledBuiltinTools 또는 builtinToolPolicy를 설정하면 게이트웨이는 기본 정책의 제한을 유지합니다.

• disabledBuiltinTools: 게이트웨이는 기본 정책의 목록과 정책의 목록의 합집합을 사용합니다
• builtinToolPolicy: 기본 정책에서 도구를 allow 이외의 값으로 설정하면, 역할 정책에서 같은 도구에 allow를 설정하더라도 게이트웨이는 그 값을 유지합니다

다른 모든 키의 경우, 역할 정책에서 설정하면 게이트웨이는 역할 정책의 값을 사용합니다. 게이트웨이는 배열이나 banner 같은 중첩 객체를 통째로 대체하므로, 역할 정책에서 banner.text를 설정하면 게이트웨이는 기본 정책의 banner.backgroundColor를 제거합니다.

정책 변경이 Claude Desktop에 반영되는 시점

변경된 정책으로 게이트웨이를 재배포한 후, Claude Desktop은 대부분의 설정을 다음 시작 시에만 적용합니다.

• 닫혀 있는 경우: Claude Desktop은 시작할 때 부트스트랩 응답을 가져오므로, 변경 사항은 다음 시작부터 적용됩니다
• 열려 있는 경우: Claude Desktop은 기본적으로 10분마다 응답 변경 여부를 확인하며, 일부 설정은 재시작 없이 적용합니다. skillCreationEnabled 같은 나머지 설정의 경우, 사용자는 사이드바에서 Relaunch Claude Desktop 카드를 보게 되며 앱을 재시작할 때까지 이전 구성을 유지합니다. 기본적으로 24시간이 지나면 Claude Desktop은 재시작 대화상자를 표시하고 2분간 활동이 없으면 자동으로 재시작합니다

24시간을 단축하려면 정책의 desktop 블록에서 relaunchEnforcementHours를 설정하십시오. 게이트웨이 서버에 Claude Code v2.1.260 이상, 구성원 머신에 Claude Desktop 1.40609.0 이상이 필요합니다. 0으로 설정하면 Claude Desktop이 변경 사항을 발견하는 즉시 대화상자가 나타납니다.

Claude Desktop의 확장 컨텍스트

게이트웨이에서 Claude Desktop을 제공하는 경우, 모델 선택기는 1M 컨텍스트 윈도우로 실행할 수 있는 각 나열 모델에 대해 1M 컨텍스트 옵션을 제공합니다. 여기에는 Claude Opus 4.6 이상, Claude Sonnet 4.6 이상, Fable 모델이 포함됩니다. 이 옵션은 확장 컨텍스트에서 설명하는 모델의 [1m] 변형입니다. 게이트웨이 서버에 Claude Code v2.1.284 이상이 필요합니다.

models 항목은 다음과 같은 경우 1M 옵션을 받지 않습니다.

• 해당 항목을 처리할 수 있는 업스트림이 1M을 지원하지 않는 모델에 매핑하는 경우. 게이트웨이가 장애 조치 시에만 연결하는 업스트림도 포함됩니다
• id와 upstream_model 값 중 어느 것도 Claude 모델을 지정하지 않는 경우. 예를 들어 애플리케이션 추론 프로필 ARN으로 라우팅되는 사용자 지정 별칭이 해당됩니다

선택기가 제공하는 항목을 변경하려면 다음 중 하나를 사용하십시오.

• 사용자를 1M 옵션으로 시작: 정책의 desktop 블록에서 modelPrefer1mContext: true를 설정하십시오. 아직 모델을 선택하지 않은 사용자는 첫 번째 나열 모델에 1M 옵션이 있을 때 1M 옵션으로 시작합니다. 이미 모델을 선택한 사용자는 선택을 유지합니다.
• 옵션을 수동으로 제공: 게이트웨이 서버가 v2.1.284보다 오래된 버전을 실행하거나 항목이 Claude 모델을 지정하지 않는 경우 이 방법을 사용하십시오. models에 모델을 두 번 나열하되, 한 번은 일반 ID로, 한 번은 [1m]을 덧붙여 나열하고 둘 다 동일한 upstream_model 맵을 사용하십시오. Claude Desktop은 이 쌍을 1M 옵션이 있는 하나의 모델로 표시합니다. 게이트웨이는 [1m] 항목을 검사하지 않고 제공하므로, 업스트림이 1M으로 제공하는 모델에 대해서만 추가하십시오.

다음 예시는 애플리케이션 추론 프로필로 라우팅되는 사용자 지정 별칭에 대해 옵션을 수동으로 제공하고 새 사용자를 해당 옵션으로 시작합니다.

models:
  - id: corp-sonnet
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod
  - id: corp-sonnet[1m]
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

managed:
  policies:
    - match: {}
      desktop:
        modelPrefer1mContext: true

1M 옵션 제거

선택기에서 옵션을 제거하려면 정책의 cli 키 아래 env 블록에서 CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"을 설정하십시오. id가 [1m]으로 끝나는 항목도 나열했다면 게이트웨이가 여전히 이를 제공하므로 해당 항목도 삭제하십시오.

이 변수는 정책과 매칭되는 개발자의 터미널 세션에도 적용됩니다. 그곳에서 무엇이 바뀌는지는 확장 컨텍스트를 참조하십시오.

다른 관리형 소스와의 우선순위

디바이스에 MDM으로 전달된 정책이나 로컬 managed-settings.json도 있는 경우, 게이트웨이가 전달한 설정이 가장 우선합니다. 관리형 설정 페이지의 관리형 계층 내 우선순위에서 로컬 소스가 적용되는 시점을 설명하며, 샌드박스 잠금 키, forceRemoteSettingsRefresh, 변수별 env 병합처럼 어떤 소스가 선택되든 관계없이 Claude Code가 모든 관리자 소스에서 읽는 키도 나와 있습니다. MDM 프로필이나 관리형 설정 파일에 구성된 policyHelper는 게이트웨이가 설정을 전달하지 않을 때만 실행되며, 해당 항목에서 그 출력이 무엇을 대체하는지 설명합니다.

Claude Desktop 같은 임베딩 호스트는 SDK managedSettings 옵션을 통해 정책을 제공할 수 있습니다. 임베딩 호스트의 상위 설정에서 Claude Code가 이를 적용하는 시점을 설명하며, 상위 설정 제한에서 allowManaged*Only 잠금 없이도 여전히 적용되는 허용 방향 설정을 나열합니다.

게이트웨이 정책은 비대화형 claude -p 실행과 Agent SDK가 생성한 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. 시작 시 게이트웨이에 연결할 수 없으면 로그인한 세션은 정책 없이 실행되는 대신 오류와 함께 종료됩니다.

telemetry

CLI는 메트릭, 로그, 그리고 활성화된 경우 트레이스를 게이트웨이로 보내며, 게이트웨이는 이를 구성된 각 대상으로 그대로 중계합니다. 내보내기는 HTTP를 통한 OpenTelemetry Protocol(OTLP)을 사용합니다. 중계를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 정책에서 수집기를 지정하십시오. CLI가 내보내는 메트릭과 이벤트는 사용량 모니터링을 참조하십시오.

/login으로 로그인한 세션에서 CLI는 게이트웨이가 발급한 JWT에서 읽은 인증된 사용자의 ID, 즉 user.id, user.email, user.groups 속성을 각 내보내기에 기록합니다. 따라서 개발자 측 구성 없이도 개발자별 비용 및 사용량 귀속이 가능합니다. 개발자가 로그인하기 전에 Claude Code가 기록하는 이벤트는 이 ID를 포함하지 않습니다. 개발자 그룹 변경 시 어떤 속성이 이를 따르는지 확인하려면 열린 세션 중 그룹 변경을 참조하십시오.

게이트웨이를 통해 로그인한 Claude Desktop 및 Cowork 세션은 enduser.id와 함께 user.email과 user.groups를 텔레메트리에 기록하므로, user.email 또는 user.groups에 대한 하나의 쿼리로 터미널, Desktop, Cowork 사용량을 모두 다룰 수 있습니다. user.groups는 쉼표로 구분된 IdP 그룹 목록입니다.

Desktop 및 Cowork 텔레메트리에는 ID 공급자가 사용자에 대해 발급하는 sub 클레임인 enduser.sub도 포함되며, 이는 사용자의 이메일이 변경되어도 동일하게 유지됩니다. 터미널 세션은 같은 값을 user.id에 기록하므로, enduser.sub를 터미널 user.id와 매칭하는 쿼리로 한 사용자의 터미널, Desktop, Cowork 사용량을 함께 다룰 수 있습니다. Desktop 및 Cowork 내보내기에서 user.id는 주체(subject)가 아닌 익명 식별자입니다.

Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로, 이러한 속성은 조직이 구성한 대상으로만 전송되며 Anthropic에는 절대 전송되지 않습니다.

사용자의 그룹 목록이 퍼센트 인코딩 후 255자를 초과하거나 그룹 이름에 쉼표나 등호가 포함된 경우, 게이트웨이는 잘라내지 않고 해당 사용자의 Desktop 및 Cowork 텔레메트리에서 user.groups를 제외합니다. 해당 사용자의 터미널 세션은 여전히 전체 목록을 포함합니다.

게이트웨이는 주체가 퍼센트 인코딩 후 255자를 초과하거나, 공백, 인쇄 가능한 ASCII 범위를 벗어난 문자, 또는 , ; = \ " % 중 하나를 포함하는 경우 enduser.sub를 제외합니다. 해당 사용자의 Desktop 및 Cowork 텔레메트리는 다른 속성을 유지합니다.

Desktop 및 Cowork 텔레메트리의 user.email 및 user.groups에는 게이트웨이 서버에 Claude Code v2.1.265 이상이 필요하며, user.groups에는 각 개발자 머신에 Claude Desktop 1.24012 이상이 필요합니다.

enduser.sub에는 게이트웨이 서버에 Claude Code v2.1.274 이상이 필요합니다.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

[!WARNING]

각 대상은 metrics, logs, traces를 독립적으로 옵트인하며, 기본값은 메트릭만입니다. 신호마다 민감도가 다릅니다.

• 메트릭: 토큰 수, 요청 수, 지연 시간 같은 집계 카운터
• 로그 및 트레이스: 전체 Bash 명령, 도구 입력, 파일 경로를 포함할 수 있어 Claude Code가 개발자 머신에서 수행하는 모든 작업을 다룹니다

해당 데이터에 걸맞은 액세스 제어와 보존 정책이 있는 대상에서만 로그와 트레이스를 활성화하십시오.

각 forward_to URL은 https://를 사용해야 하며, 게이트웨이 자체 루프백 인터페이스의 수집기에 대해서만 예외가 있습니다.

• http://localhost:<port>는 구성 검증을 통과하지만, 게이트웨이 환경에 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1을 설정하지 않으면 SSRF 가드가 모든 내보내기를 ECONNREFUSED_SSRF로 차단합니다
• http://127.0.0.1:<port> 또는 http://[::1]:<port>는 해당 변수를 설정하지 않으면 부팅에 실패합니다

클러스터 내 수집기의 경우 자체 내부 주소에서 HTTPS로 노출하거나, 변수를 설정한 사이드카로 실행하십시오.

HTTPS_PROXY가 설정되어 있으면 게이트웨이는 해당 프록시를 통해 내보내기를 전송합니다.

내부 수집기에 직접 연결하려면 호스트 이름이나 .internal.example.com처럼 앞에 점이 붙은 도메인으로 NO_PROXY에 추가하십시오. 이를 위해서는 게이트웨이 서버에 Claude Code v2.1.277 이상이 필요합니다. 게이트웨이가 프록시 없이 수집기에 연결할 수 있는지 확인하십시오. 앞에 점이 없는 항목은 해당 이름과 정확히 일치하는 경우에만 매칭되며 그 하위 이름과는 매칭되지 않습니다. CIDR 범위는 매칭되지 않습니다.

프록시 전용 이그레스가 켜져 있으면 NO_PROXY 항목이 하나라도 있으면 프록시 전용 이그레스가 꺼지므로, 대신 프록시에서 수집기를 허용하십시오.

CLI에서 텔레메트리는 기본적으로 꺼져 있습니다. telemetry.forward_to와 listen.public_url을 모두 설정하면, 게이트웨이는 /managed/settings를 통해 여섯 개의 환경 변수를 푸시하여 연결된 클라이언트에서 텔레메트리를 켭니다.

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, OTEL_TRACES_EXPORTER: 각각 하나 이상의 forward_to 대상이 해당 신호를 활성화하면 otlp로, 그렇지 않으면 none으로 설정됩니다
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

자체 레이블을 추가하면 게이트웨이는 OTEL_RESOURCE_ATTRIBUTES도 푸시합니다.

게이트웨이 서버의 Claude Code v2.1.265 이전에는 어떤 대상도 옵트인하지 않은 신호를 포함하여 세 가지 내보내기 선택자를 모두 otlp로 푸시했습니다.

푸시되는 엔드포인트는 공개 URL로 구성되므로, 메트릭과 로그에는 개발자나 정책의 OTEL 구성이 필요하지 않습니다.

/login으로 로그인한 개발자는 자신의 OTEL 구성으로 내보내기를 리디렉션할 수 없습니다.

• 로컬에서 설정한 변수: Claude Code는 푸시된 변수를 관리형 계층에서 적용하므로, 각 변수는 개발자가 로컬에서 설정한 값을 재정의합니다.
• 로컬에서 구성한 엔드포인트: OTLP/HTTP 내보내기가 활성화되어 있으면, 게이트웨이가 텔레메트리 변수를 푸시했는지와 관계없이 CLI는 로컬에서 구성한 엔드포인트를 무시합니다. 정책이 수집기를 엔드포인트로 지정하지 않는 한 내보내기는 게이트웨이로 전송됩니다.

신호에 대한 forward_to 대상이 없으면 게이트웨이는 이를 받아서 폐기합니다. 개발자가 이미 Claude Code 텔레메트리를 조직의 수집기 중 하나로 내보내고 있다면, 로그인 후에도 해당 수집기가 데이터를 계속 받도록 forward_to 대상으로 추가하고, 개발자가 로그나 트레이스를 내보내는 경우 이를 활성화하십시오. 대신 중계를 건너뛰려면 정책에서 수집기를 지정하십시오.

트레이스에는 각 클라이언트에 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1도 필요합니다. 게이트웨이가 이를 푸시하지 않으므로 관리형 정책의 env 블록에서 설정하십시오. 개발자는 푸시된 엔드포인트가 이미 유발하는 동일한 보안 승인 대화상자에서 이를 승인합니다.

트레이스를 수집하려는 그룹의 정책에서만 1로 설정하십시오. 이를 설정하지 않은 정책은 병합 규칙에 따라 match: {} 캐치올 정책이 값을 설정한 경우 그 값을 상속합니다. 개발자가 로컬에서 변수를 설정하더라도 특정 그룹의 클라이언트가 트레이스를 보내지 않도록 하려면 해당 그룹의 정책에서 0으로 설정하십시오.

protobuf와 JSON OTLP 인코딩이 모두 중계되며, OpenTelemetry와 호환되는 모든 백엔드를 대상으로 사용할 수 있습니다.

누적 메트릭 전송

수집기가 누적 메트릭만 받는 경우 OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE를 cumulative로 설정하십시오. Claude Code는 기본적으로 델타 메트릭을 보내며, 게이트웨이는 변환 없이 이를 중계합니다. 각 세션 유형이 변수를 읽는 위치에 설정하십시오.

• 터미널 세션: 정책의 cli 또는 code 키 아래 env 블록
• 사용자 머신에서 실행되는 Cowork 세션: 해당 머신의 클라이언트 측 관리형 설정의 env 블록
• code 정책 아래의 Code 탭 세션: code 설정이 적용되는 조건을 충족한 후 정책의 env 블록
• cli 정책 아래의 Code 탭 세션: 세션을 실행하는 머신의 클라이언트 측 관리형 설정의 env 블록. SSH를 통한 경우에는 원격 호스트입니다.

머신의 관리형 설정에 변수를 추가하는 경우, 해당 머신에서 우선순위가 가장 높은 소스에 parentSettingsBehavior: "merge"도 설정하십시오. 이 설정이 없으면 Cowork 세션과 cli 정책 아래의 Code 탭 세션은 Claude Desktop이 상위 설정으로 전달하는 이그레스 허용 목록 및 기타 정책 없이 실행됩니다.

자체 레이블 추가

게이트웨이를 통해 로그인한 세션의 텔레메트리에 service.namespace나 deployment.environment.name 같은 고정 레이블을 붙이려면 telemetry.resource_attributes를 설정하십시오. 각 레이블은 OpenTelemetry 리소스 속성이며, 모든 대상이 동일한 레이블을 받습니다.

세션은 telemetry.forward_to와 listen.public_url도 함께 설정한 경우에만 레이블을 받습니다. 다음 예시는 두 개의 레이블을 추가합니다.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
  resource_attributes:
    service.namespace: claude
    deployment.environment.name: prod

레이블이 다음 규칙 중 하나를 위반하면 게이트웨이는 시작을 거부하며, 시작 오류에서 해당 레이블을 명시합니다.

• 이름에는 문자, 숫자, ., _, -만 사용합니다
• 이름은 예약된 이름이 아니어야 합니다. 대소문자 구분 없이 비교하며, 예약된 이름은 user., enduser., identity.로 시작하는 모든 이름과 service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version, wsl.version입니다
• 값은 공백이 없고 , ; = \ " % 중 어느 것도 포함하지 않는, 비어 있지 않은 인쇄 가능한 ASCII여야 합니다
• 값은 게이트웨이가 퍼센트 인코딩 후 계산하는 기준으로 최대 255자이므로, /, :, @는 각각 3자로 계산됩니다
• 값은 텍스트이므로 숫자, true, false는 따옴표로 감싸십시오

telemetry.resource_attributes를 설정하려면 게이트웨이 서버에 Claude Code v2.1.281 이상이 필요합니다. 이전 게이트웨이는 이 키를 발견하면 시작되지 않습니다. 키를 추가하기 전에 모든 레플리카를 업그레이드하고, 이전 버전으로 롤백하기 전에는 키를 제거하십시오.

/login으로 로그인한 터미널 세션은 다른 텔레메트리 변수와 함께 푸시되는 OTEL_RESOURCE_ATTRIBUTES로 레이블을 받습니다. 정책의 env 블록에서 OTEL_RESOURCE_ATTRIBUTES를 설정하면, 해당 정책과 매칭되는 터미널 세션은 레이블 대신 그 값을 받습니다. Claude Desktop은 user.email 및 기타 ID 속성과 함께 게이트웨이로부터 레이블을 받습니다.

Claude Code는 각 레이블을 모든 메트릭 데이터 포인트에도 복사하므로, 리소스 속성을 인덱싱하지 않는 백엔드에서도 이를 기준으로 메트릭을 필터링할 수 있습니다. 이 복사를 끄려면 메트릭 카디널리티 제어를 참조하십시오.

열린 세션 중 그룹 변경

터미널 세션은 user.groups를 OTLP 리소스에 넣고, 각 메트릭 데이터 포인트와 이벤트에도 다시 넣습니다. 세션이 열려 있는 동안 개발자의 그룹이 변경되면, 다음 자동 갱신 이후 사용량에 대한 데이터 포인트와 이벤트는 새 그룹을 포함합니다. 리소스는 개발자가 Claude Code를 재시작할 때까지 이전 그룹을 유지하므로, 데이터 포인트나 이벤트의 속성을 기준으로 그룹화하십시오.

OpenTelemetry Collector의 Prometheus remote write 내보내기 도구에서 resource_to_telemetry_conversion을 켜면, 내보내기 도구가 각 데이터 포인트의 user.groups를 리소스의 값으로 대체하므로 모든 데이터 포인트에 이전 그룹이 표시됩니다. 데이터 포인트의 값을 유지하려면 해당 내보내기 도구보다 앞에서 리소스의 user.groups를 삭제하십시오.

다음 OpenTelemetry Collector resource 프로세서는 이를 나열한 파이프라인에서 속성을 삭제합니다.

processors:
  resource/drop-user-groups:
    attributes:
      - key: user.groups
        action: delete

메트릭 파이프라인의 processors에 resource/drop-user-groups를 추가하면, 각 시계열은 자체 데이터 포인트의 user_groups 레이블을 포함합니다.

수집기로 직접 내보내기

/login을 통해 로그인한 세션이 릴레이를 거치지 않고 수집기로 텔레메트리를 직접 보내도록 하려면, 관리형 정책의 env 블록에서 OTEL_EXPORTER_OTLP_ENDPOINT를 수집기의 https:// 기본 URL로 설정합니다. Claude Code는 설정한 URL(예: https://otel-collector.example.com:4318)에 /v1/metrics, /v1/logs 또는 /v1/traces를 덧붙이고, 각 신호를 OTLP/HTTP를 통해 해당 위치로 내보냅니다. 각 개발자의 머신에 Claude Code v2.1.265 이상이 필요합니다. 이전 버전의 클라이언트는 릴레이를 통해 내보냅니다.

수집기에 인증하려면 같은 env 블록에서 OTEL_EXPORTER_OTLP_HEADERS를 설정합니다. 세션은 이런 방식으로 지정된 수집기에 개발자의 게이트웨이 세션 토큰을 절대 보내지 않습니다.

정책에서 이 엔드포인트를 추가하거나 변경하면, Claude Code는 대화형 세션에 적용하기 전에 각 개발자에게 보안 승인 대화 상자에서 승인하도록 요청합니다.

Claude Code는 신호를 직접 내보내기 전에 엔드포인트를 확인하며, 확인에 실패하면 해당 신호를 릴레이에 유지합니다. 확인 항목은 다음과 같습니다.

• 엔드포인트가 게이트웨이 자체에서 제공됩니다. 같은 변수를 MDM 프로필이나 로컬 managed-settings.json에서 설정하면 내보내기는 릴레이에 유지됩니다.
• URL이 https://를 사용하거나, 루프백 주소에 대해 http://를 사용합니다
• URL이 쿼리나 프래그먼트 없이 /v1/<signal>로 끝나는 경로로 확인됩니다. Claude Code는 일반 변수로부터 이 경로를 직접 만듭니다. OTEL_EXPORTER_OTLP_METRICS_ENDPOINT와 같은 신호별 변수는 작성된 그대로 사용하므로, 여기에는 전체 경로를 포함해야 합니다.
• URL이 게이트웨이 자체의 호스트가 아닙니다. 게이트웨이를 대상으로 하는 엔드포인트는 릴레이 경로와 세션 토큰을 유지합니다.
• 관리자와 개발자 모두 어떤 설정 소스에서도 otelHeadersHelper를 구성하지 않았습니다. 헬퍼가 구성되어 있으면 모든 신호가 릴레이에 유지됩니다.

지정한 엔드포인트는 내보내기 대상만 변경합니다. 어떤 신호를 내보낼지는 여전히 OTEL_*_EXPORTER 선택자로 선택합니다.

엔드포인트만으로는 내보내기가 켜지지 않으므로, 게이트웨이가 이미 푸시하고 있지 않다면 내보내기를 켜는 변수도 함께 설정합니다.

• 게이트웨이가 이미 텔레메트리 변수를 푸시하고 있다면, 해당 변수가 활성화, 선택자, 프로토콜을 처리하며 명시적으로 지정한 엔드포인트가 푸시된 <public_url> 값을 재정의합니다. 어떤 forward_to 대상도 활성화하지 않는 신호에 대해서만 OTEL_*_EXPORTER 선택자를 직접 otlp로 설정합니다.
• 그렇지 않다면 CLAUDE_CODE_ENABLE_TELEMETRY=1, OTEL_*_EXPORTER 선택자, OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf도 설정합니다.

개발자가 로그아웃하거나 다른 게이트웨이에 로그인하면 수집기로의 내보내기가 중단되고, Claude Code는 남아 있는 각 배치를 전송하지 않고 삭제합니다.

대상 전송이 실패하는 경우

게이트웨이는 텔레메트리를 버퍼링하거나 재시도하거나 저장하지 않으므로, 대상에 도달하지 못한 내보내기는 나중에 전달하지 않고 삭제합니다. 각 대상은 개별적으로 성공하거나 실패하며, 내보내는 클라이언트는 어느 경우든 성공 응답을 받으므로 전송 실패는 게이트웨이의 로그에만 나타납니다.

한 대상으로의 전송이 연속으로 다섯 번 실패하면, 게이트웨이는 전송이 성공할 때까지 30초 단위로 해당 대상으로의 전달을 일시 중지하며 각 일시 중지를 로그에 기록합니다. 모든 오류 응답, 타임아웃, 연결 오류는 전송 실패로 간주되지만, 400, 413, 415, 422, 431은 예외입니다. 이 코드들은 수집기가 해당 내보내기의 페이로드를 형식이 잘못되었거나 너무 크다는 이유로 거부했음을 의미합니다.

거부된 페이로드는 실패 횟수를 늘리지도 초기화하지도 않습니다. 게이트웨이는 해당 대상으로 계속 전달하며, 대상의 첫 번째 거부와 이후 매 100번째 거부마다 대상과 상태를 명시한 경고를 로그에 기록합니다.

HTTP 조정

선택 사항인 네 가지 최상위 블록 access_control, limits, timeouts, rate_limits로 HTTP 사용 환경을 조정합니다. 대부분의 배포에는 기본값이 적합합니다.

기본값대로 두 access_control 목록을 모두 비워 두면 게이트웨이는 모든 클라이언트 주소에 응답하므로, 게이트웨이에 접근할 수 있는 대상은 네트워크에 의해서만 제한됩니다. 게이트웨이는 개발자 머신에서 명령을 실행하는 관리형 설정을 푸시할 수 있으므로 이 점이 중요합니다.

allow_cidrs가 비어 있는 동안 게이트웨이는 요청에 응답하는 방식은 바꾸지 않고 두 곳에서 경고합니다.

• 부팅 시: 운영 로그의 경고가 사설 범위 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, ::1/128, fc00::/7과 개발자가 연결하는 기타 내부 범위만 허용하도록 권장합니다. 로컬 개발에서처럼 게이트웨이를 루프백 주소에 바인딩하고 trusted_proxies와 public_url을 모두 설정하지 않으면 경고가 나타나지 않습니다.
• 런타임 시: 이러한 사설 범위 밖의 주소에서 처음으로 요청이 도착하면, 게이트웨이는 경고를 로그에 기록하고 클라이언트 IP를 포함한 access.public_client 감사 이벤트를 발생시킵니다. 둘 다 프로세스당 한 번 발생합니다. 링크 로컬 주소인 169.254.0.0/16과 fe80::/10은 공용으로 간주되지 않습니다. 게이트웨이는 이 확인이 실행되기 전에 /healthz와 /readyz에 응답하므로, 공용 범위에서 오는 상태 프로브는 이 확인을 트리거하지 않습니다.

두 신호 모두 게이트웨이가 확인한 클라이언트 주소를 사용합니다. 로드 밸런서, 포트 포워드 또는 터널이 트래픽을 중계하면서 listen.trusted_proxies에 등록되어 있지 않으면, 게이트웨이는 일반적으로 사설 주소인 중계 장치의 주소를 보게 되므로 런타임 경고와 사설 허용 목록 모두 이를 통해 중계된 트래픽을 잡아내지 못합니다.

중계자가 listen.trusted_proxies에 속하는 경우 그곳에 나열하십시오. 어떤 경우든 게이트웨이와 그 앞에 있는 모든 것이 공용 인터넷에서 도달할 수 없도록 유지하십시오.

load_test_mode

load_test_mode 블록을 사용하면 모델 제공자를 호출하지 않고 게이트웨이의 부하 테스트를 수행할 수 있습니다. 이 모드가 켜져 있는 동안 게이트웨이는 평소처럼 각 제공자 요청을 빌드하고 서명한 다음, 전송하는 대신 폐기하고 일반 응답 경로를 통해 미리 준비된 응답을 스트리밍합니다. 응답은 미리 준비된 응답임을 알리는 문장으로 시작하는 채우기 텍스트입니다.

게이트웨이 서버에 Claude Code v2.1.282 이상이 필요합니다. 이전 버전의 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 블록을 추가하기 전에 모든 복제본을 업그레이드하고, 롤백하기 전에 블록을 제거하세요.

아래 예시는 기본값으로 모드를 켜며, 약 750 토큰 분량의 텍스트 응답을 약 10초에 걸쳐 스트리밍합니다.

load_test_mode:
  enabled: true
  reply_tokens: 750     # roughly how many tokens of text each canned reply carries
  reply_seconds: 9.5    # how long a streamed reply takes

이 모드의 부하 테스트는 게이트웨이, Postgres, 그리고 게이트웨이 앞의 모든 구성 요소를 대상으로 합니다. 제공자의 제한, 속도, 네트워크 경로, 또는 각 레플리카의 동시 업스트림 요청 제한에서의 대기는 대상에 포함되지 않습니다. 열려 있는 요청이 이 제한보다 많으면, 즉 프로덕션 요청이 대기하기 시작하는 시점에는 레플리카가 여전히 client requests are open 경고를 로그에 기록합니다.

모델 요청이 제공자에게 전송되지 않으므로 복제본의 요청당 CPU는 추정치이며, 제공자로의 트래픽도 암호화하는 프로덕션 환경보다 낮게 측정됩니다. 실제 제공자를 대상으로 소규모 파일럿을 실행하여 복제본 수를 확인하세요. v2.1.283 이전에는 추정치가 훨씬 낮게 측정됩니다.

모드가 켜져 있는 동안 요청에 최대 일곱 자리 정수를 담은 x-load-test-user 헤더를 포함할 수 있습니다. 게이트웨이는 각 숫자를 별도의 개발자로 간주하며, 요청과 함께 전달된 토큰의 개발자 이메일과 그룹을 사용합니다.

부하 테스트 배포에는 전용의 빈 데이터베이스를 제공하세요. 이미 어떤 개발자라도 사용량이 발생한 데이터베이스에서는 게이트웨이가 이 모드를 켠 상태로 시작을 거부하기 때문입니다.

[!WARNING]

개발자가 사용하는 게이트웨이에서는 절대 이 모드를 켜지 마세요. 모든 요청이 미리 준비된 응답을 받고 모델은 호출되지 않습니다. 모드가 켜져 있는 동안 게이트웨이는 부팅 시 load_test_mode is on 경고를 로그에 기록하고, 각 inference 감사 이벤트에 load_test: true를 표시합니다.

완전한 예제

이 전체 참조 구성은 모든 핵심 섹션을 다룹니다. HTTP 조정 블록은 기본값을 유지합니다. 복사하고 필요하지 않은 것을 삭제하고 값을 채웁니다. 빠른 시작의 구성은 이것의 최소 버전입니다.

# 실행:
#   claude gateway --config gateway.yaml
#
# 운영 로그 상세도는 CLAUDE_GATEWAY_LOG_LEVEL
# 환경 변수(debug | info | warn | error; 기본값 info)로 제어됩니다. debug는
# 또한 각 id_token의 클레임 이름을 기록하여 groups_claim 진단을 위해 사용됩니다.
# 감사 이벤트는 항상 내보내지므로 영향을 주지 않습니다.
# CLAUDE_GATEWAY_LOG_FORMAT=json을 설정하면 운영 로그 줄을 severity, time, message가
# 포함된 JSON 객체로 기록합니다.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # TLS 종료 ingress 뒤에서 실행할 때 tls 블록을 생략합니다.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Okta org 서버가 발급자인 경우 필수입니다. id_token은
  # 이메일 및 그룹을 생략할 수 있습니다. 게이트웨이는 /userinfo에서 채웁니다.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta는 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가
  # 허용할 때만 그룹을 내보냅니다. 아래의 계약자 정책은
  # 그룹과 일치하므로 범위가 여기에서 요청됩니다.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra 앱 역할: `roles` 사용
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # 데이터베이스 장애 조치 중에도 준비 상태 확인을 계속 통과합니다.

# 로그인 시 표시되는 안내문입니다. 게이트웨이에 접근할 수 있는 사람은 누구나 읽을 수 있습니다.
# login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

# /v1/organizations/spend_limits(Anthropic Admin API를 미러링함)를 활성화합니다.
# 및 /v1/messages에서 개발자별 지출 적용. 비활성화하려면 생략합니다.
# 한도 자체는 관리자 API를 통해 설정되며 여기에서는 설정되지 않습니다.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min
#   # pooled_conflict_rule: priority_list
#   # pooled_priority_order: [eng-platform, eng-all]

# enforcement:
#   fail_closed_on_error: false

# 모델 제공자를 호출하지 않고 이 배포를 부하 테스트합니다. 개발자가 사용하는
# 게이트웨이에서는 절대 사용하지 마십시오. 모든 요청이 미리 정해진 응답을 받습니다.
# load_test_mode:
#   enabled: true
#   # reply_tokens: 750
#   # reply_seconds: 9.5

# 계약 요금으로 미터링하고 USD 정가 대신 사용합니다. admin: 또는 managed: 정책이 필요합니다.
# managed:를 사용하면 동일한 요금이 로그인한 클라이언트로도 이동합니다.
# 아래 요금은 자리 표시자이며 실제 계약 가격이 아닙니다.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: mantle
  #   region: us-east-1
  #   models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # mantle: anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # allow는 이 도구를 자동 승인합니다. 나머지를 차단하지 않습니다.
        # 도구를 제한하려면 거부 규칙을 추가합니다.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # 기본 선택기 옵션을 기본 제공 기본값 대신 각 정책의 availableModels로
        # 제한하여 어떤 역할도 기본값에서 400을 받지 않도록 합니다.
        # 계약자 정책은 이 키를 상속합니다.
        enforceAvailableModels: true
        permissions:
          allow: [Read, Grep, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

클라이언트 측 관리형 설정

위의 모든 것은 게이트웨이 서버를 구성합니다. 개발자 머신을 지정하는 것은 각 장치에서 Claude Code의 관리형 설정을 통해 별도로 구성됩니다. 게이트웨이는 로그인 키를 직접 푸시할 수 없습니다. 왜냐하면 이 키들이 클라이언트에게 게이트웨이가 어디에 있는지 알려주기 때문입니다.

CLI의 경우 OS별 managed-settings.json에서 이 키들을 설정합니다. 두 개의 로그인 키는 각 개발자의 /login을 게이트웨이로 라우팅합니다:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

parentSettingsBehavior: "merge"는 Claude Desktop의 이그레스 허용 목록 전달이 임베드된 Claude Code 세션에서 작동하도록 유지합니다. Claude Desktop 세션에 정책 전달에서 메커니즘과 옵트인이 위치해야 하는 곳을 설명합니다.

개발자가 클라우드 공급자 변수 또는 자신의 ANTHROPIC_BASE_URL로 게이트웨이를 우회하는 것을 방지하려면 같은 파일에 "allowedProviders": ["gateway"]를 추가합니다. Claude Code는 Cloud 게이트웨이로 설정되지 않은 머신의 모든 세션을 거부하고, forceLoginGatewayUrl이 지정하는 게이트웨이 또는 파일의 env 블록이 ANTHROPIC_BASE_URL으로 설정한 URL을 가진 게이트웨이만 허용합니다. claude gateway는 이 목록을 설정하는 머신에서 실행되기를 거부하므로 게이트웨이 호스트에서 이 키를 제외합니다. 설정 참조의 allowedProviders 항목을 참조하십시오. Claude Code v2.1.285 이상이 필요합니다.

managed-settings.json 파일을 각 장치에 배포합니다. 일반적으로 MDM 플랫폼을 통해 배포합니다. 파일 경로는 플랫폼마다 다릅니다. 각 메커니즘이 정책을 저장하는 위치를 참조하십시오.

기본적으로 Windows의 레지스트리 정책 또는 macOS의 관리형 기본 설정 plist는 위의 예외 키 및 교차 소스 확인을 제외하고 managed-settings.json 파일을 병합하지 않고 대체합니다. 이 스니펫의 모든 세 키는 최고 우선순위 소스 규칙을 따르므로 그룹 정책 또는 구성 프로필을 통해 정책을 전달하는 플릿은 대신 해당 메커니즘에 모두 세 개를 배치해야 합니다.

Claude Desktop의 경우 Claude Desktop의 자체 관리형 구성에서 bootstrapUrl 키를 <listen.public_url>/user/bootstrap으로 설정합니다. 로그인 흐름 및 그룹별 정책은 정책이 desktop 키로 서버 측에서 옵트인되면 CLI의 정책과 일치합니다. 옵트인이 없으면 /user/bootstrap은 404를 반환합니다. 서버 측 절반은 Claude Desktop 오버레이를 참조하십시오.

Claude Code는 forceLoginGatewayUrl, gatewayInternalNetworks, 및 forceLoginMethod의 "gateway" 값을 머신의 관리형 소스에서 인정합니다: managed-settings.json, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 헬퍼. 게이트웨이 페이로드에서 이들을 설정해도 게이트웨이 로그인은 구성되지 않습니다. 개발자 자신의 ~/.claude/settings.json에 대해서는 사용자 설정에서 게이트웨이 URL 설정을 참조하십시오.

페이로드에서 forceLoginMethod 및 forceLoginOrgUUID를 제외합니다. Claude Code는 여전히 시작 자격 증명 확인을 위해 페이로드에서 두 키를 모두 읽으므로, 머신에 Anthropic 발급 자격 증명을 유지하는 개발자는 로그인 후에도 관리자 정책이 Cloud 게이트웨이 로그인을 요구합니다에서 설명한 시작 종료를 받게 됩니다.

관련

• Claude 앱 게이트웨이 개요: 빠른 시작 및 개발자 연결
• 배포 가이드: IdP 설정, 컨테이너 이미지, Kubernetes 및 Cloud Run, 운영
• 지출 한도: 개발자별 한도 및 관리자 API