Claude apps gateway 배포 환경과 실행 방식

Claude apps gateway는 Claude 앱과 Amazon Bedrock 또는 AWS 상의 Claude Platform 사이에서 작동하는 셀프 호스팅 거버넌스 계층을 제공한다. 전사적으로 Claude Code와 Claude Desktop을 배포할 때 관리자가 겪는 인증 처리, 모델 접근 제어, 비용 할당 및 강제 제어 문제를 이 계층에서 해결한다. 기업은 데이터를 외부로 노출하지 않고 자체 인프라 내에서 모든 트래픽을 제어한다.

이 게이트웨이는 별도의 소프트웨어 설치 과정 없이 Claude Code CLI 바이너리에 포함되어 배포된다. 서버 모드로 작동하며 시스템 시작 시 YAML 형식의 설정 파일을 로드하여 운영 정책을 결정한다. 실행을 위해서는 터미널에서 다음과 같은 명령어를 입력한다.

claude gateway --config gateway.yaml

설정 파일인 gateway.yaml은 게이트웨이가 허용할 모델과 부여할 권한을 결정하며, 서버 구동 시점에 해당 내용을 적용한다.

지원 인프라는 AWS의 다양한 컴퓨팅 환경을 포괄한다. 레퍼런스 배포 환경에서는 VPC 내부의 AWS Fargate에서 작동하도록 설계되었으며, 필요에 따라 Amazon EKS나 Amazon EC2에서도 동일한 이미지를 사용하여 실행할 수 있다. 이는 컨테이너 기반 배포 구조를 통해 인프라 환경에 관계없이 실행 가능하도록 한 결과다.

실제 운영 시에는 로드 밸런서의 유휴 제한 시간(Idle Timeout)을 기본값인 60초보다 길게 설정해야 한다. LLM 응답 특성상 발생하는 스트리밍 청크 사이의 일시적 중단이나 지연된 비스트리밍 응답이 있을 때, 제한 시간이 짧으면 연결이 끊겨 응답이 중간에 잘리는 현상이 발생하기 때문이다.

OIDC 기반 인증 흐름과 토큰 관리

인증 세션은 기본 1시간 동안 유효한 단기 베어러 토큰(Bearer Token) 발행으로 시작된다. 플랫폼 팀이 Claude Code와 Claude Desktop이 게이트웨이의 프라이빗 URL을 바라보도록 설정하면 사용자는 `/login` 명령을 통해 인증을 시작한다. 이때 OAuth 2.0 장치 권한 부여 절차가 작동하며 클라이언트는 브라우저를 통해 OIDC(OpenID Connect) ID 제공자에서 인증을 진행한다. 게이트웨이가 장치 검증 페이지를 직접 제공하므로 브라우저는 게이트웨이의 프라이빗 엔드포인트에 접속할 수 있어야 한다. 인증 완료 후 발행된 토큰은 백그라운드에서 자동 갱신되어 세션을 유지한다.

게이트웨이는 자체 사용자 디렉토리를 구축하지 않고 Okta, Microsoft Entra ID, Auth0, Keycloak, Amazon Cognito 등 기업이 이미 사용 중인 외부 ID 제공자에게 인증을 위임한다. 개발자는 SSO(Single Sign-On)를 통해 세션당 한 번만 로그인하면 된다. 게이트웨이는 ID 제공자가 전달하는 사용자의 그룹 멤버십 정보를 내부 정책과 매칭하여 모델 접근 권한을 결정하며, 이를 통해 부서나 역할에 따라 사용할 수 있는 모델 범위를 서버 측에서 강제한다.

Microsoft Entra ID를 사용할 때는 그룹 클레임 확인을 위한 추가 설정이 필요하다. Entra ID는 기본적으로 그룹이나 역할 클레임을 인증 토큰에 포함하지 않기 때문이다. 정책 설정에서 `groups` 항목으로 권한을 구분하려면 OIDC 설정에 `groups_claim: roles` 설정을 명시해야 한다. 이 설정이 누락되면 게이트웨이가 사용자 그룹을 식별할 수 없어 모든 사용자가 기본값인 catch-all 정책의 제약만 받게 된다.

서버 측 모델 접근 제어와 YAML 정책 구조

클라이언트의 요청이 서버에 도달하는 즉시 권한을 검증하며, 허용되지 않은 모델을 요청할 경우 서버가 400 에러를 반환해 접근을 차단한다. 이 방식은 서버 측에서 권한을 강제하므로 클라이언트 소프트웨어 수정이나 API 요청 값 변경을 통한 우회가 불가능하다. 예를 들어 계약직 그룹 사용자가 Claude Opus 4.8 모델을 호출하면, 서버는 그룹 권한 확인 후 요청을 거부하고 400 에러를 송신한다.

모델 접근 권한은 YAML 파일 내 정책 블록에 선언된 순서에 따라 평가된다. 서버는 파일 상단부터 순차적으로 조건을 검토하여 사용자의 그룹 정보와 일치하는 첫 번째 항목을 선택한다. 선택된 개별 정책은 전체 사용자 공통 적용 항목인 catch-all 기본값과 병합되어 최종 접근 권한 세트를 형성한다. 이를 통해 특정 팀에는 고성능 모델을, 일반 사용자에게는 경량 모델만 제공하는 차등 부여 체계를 구현한다.

클라이언트 종류에 따른 제어도 가능하며, Claude Desktop 앱을 허용하려면 각 정책 엔트리에 `desktop: {}` 설정을 포함해야 한다. 이 식별자가 없는 항목은 데스크톱 클라이언트의 접속을 제한한다. 서버에서 결정된 권한은 사용자 인터페이스에 즉각 반영되어, Claude Code와 Claude Desktop의 모델 선택기(Picker)에는 허용된 모델만 목록에 나타난다.

관리자가 YAML 파일을 수정하면 해당 내용은 최대 1시간 이내에 모든 클라이언트에 전파된다. 개별 기기 설정 변경이나 앱 재설치 없이 중앙 서버의 설정 파일 하나로 전사적인 모델 접근 범위를 조정할 수 있으며, 이를 통해 모델별 비용 발생 가능성을 서버 단에서 통제한다.

OTLP를 이용한 사용자별 비용 및 사용량 추적

사용량 관리를 위해 로그와 트레이스 대신 수치 기반의 메트릭 수집을 활용한다. 게이트웨이는 요청에 포함된 베어러 토큰으로 개발자의 신원과 그룹 멤버십을 확인하고, 지출 한도를 평가한 뒤 요청을 Amazon Bedrock이나 AWS 상의 Claude Platform으로 라우팅한다. 응답이 스트리밍되는 동안 발생하는 사용량 데이터는 즉시 수집된다.

데이터 전송에는 OTLP(OpenTelemetry Protocol) 표준 프로토콜을 사용한다. 클라이언트가 생성한 사용량 메트릭을 게이트웨이가 수신하여 설정된 컬렉터로 전달하는 릴레이 구조다. 표준 프로토콜을 채택하여 특정 벤더에 종속되지 않고 기업의 기존 모니터링 환경에 통합할 수 있으며, 사용량을 정밀하게 관측할 수 있다.

수집하는 핵심 지표는 `claude_code.token.usage`(토큰 사용량), `claude_code.cost.usage`(실제 발생 비용), `claude_code.active_time.total`(총 활성 시간) 세 가지다. 모든 수치는 인증된 개발자의 사용자 ID, 이메일, 그룹 멤버십 정보와 결합된다. 이를 통해 관리자는 특정 팀이나 개별 개발자가 할당된 예산을 어느 시점에 얼마나 소모했는지 구체적인 수치로 추적하여 비용 최적화 지점을 식별한다.

지원 백엔드 서비스는 Datadog, Splunk, Grafana, Amazon CloudWatch가 있다. Amazon CloudWatch의 경우 ADOT(AWS Distro for OpenTelemetry) 컬렉터를 경유하여 데이터를 전송한다. 표준화된 데이터 포맷을 사용하므로 별도의 변환 과정 없이 수집된 메트릭을 대시보드에 시각화하여 실시간으로 모니터링한다.

AWS 기반 엔터프라이즈 AI 거버넌스의 운영 효과

수집된 메트릭을 통한 비용 추적과 더불어, 게이트웨이는 요청을 설정 파일의 우선순위에 따라 Amazon Bedrock 또는 AWS 상의 Claude Platform으로 라우팅한다. 시스템은 업스트림의 가용성 상태를 확인하여 장애, 스로틀링, 타임아웃 발생 시 자동으로 다음 경로로 요청을 넘기는 페일오버(Failover)를 수행한다. 다만 제공자 간 페일오버 시 서비스 이용 약관이나 데이터 처리 지역이 변경될 수 있으므로, 기업은 데이터 거버넌스 정책에 따라 물리적 지역 변경 가능성을 검토하고 설정 파일에 반영해야 한다.

중앙 ID 제공자를 통해 인증을 처리하므로, 퇴사자 발생이나 권한 변경 시 ID 제공자에서 계정을 삭제하는 것만으로 모든 AI 도구에 대한 접근을 즉시 차단할 수 있다. 개별 API 키를 회수하거나 전체 키를 교체해야 하는 운영 부담이 사라진다. 또한 게이트웨이가 요청마다 사용자 식별 정보를 포함하여 전송하는 속성을 활용해, 별도의 커스텀 도구 개발 없이도 사용자별 모델 사용량 추적과 비용 배분 체계를 구축할 수 있다.

AWS는 엔드 투 엔드 아키텍처와 배포 패턴을 포함한 레퍼런스 배포 가이드를 제공한다. 이를 통해 기업은 모델 버전 관리와 접근 제어를 코드 기반 설정으로 운영하며, 보안 감사와 정책 변경에 유연하게 대응하는 운영 효율을 확보한다. 구체적인 구현 방법과 구성 요소는 공식 배포 가이드와 설정 참조 문서를 통해 확인 가능하다.

개발자 개별 기기에 자격 증명을 저장하지 않고 중앙에서 팀별 모델 권한을 제어하며 사용자별 비용을 정확히 추적하는 기준을 수립해야 한다.