Claude apps gateway 개요
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Claude apps gateway는 개발자 Claude Code 클라이언트와 모델 provider 사이에 두는 self-hosted 서비스입니다. 개발자는 API 키·클라우드 자격증명 대신 기업 IdP로 로그인하고, gateway가 upstream 자격증명을 보유하며 IdP 그룹별 모델 접근·managed settings를 강제하고 OTLP 텔레메트리를 조직 관측 스택으로 보냅니다.
claude 바이너리에 포함되어 claude gateway --config gateway.yaml으로 서버를 띄웁니다. 데이터 residency 등으로 자체 클라우드 경유가 필요할 때 적합합니다. SCIM·web/mobile 등 다른 기능이 우선이면 Claude Enterprise가 나을 수 있습니다.
핵심 개념
- Credentials: upstream 키는 인프라에만; 개발자는 단기 bearer token (기본 세션 수명 1시간)
- Access control: IdP 그룹 → 모델 allowlist + managed settings
- Settings delivery: claude.ai server-managed 대신 gateway가 정책 전달
- Telemetry: Datadog/Splunk/ClickHouse 등으로 OTLP metrics (logs/traces는 목적지별 opt-in)
- Upstream routing: 클라이언트는 Anthropic Messages API 사용, gateway가 Bedrock/Claude Platform on AWS/Vertex/Foundry/Anthropic API로 변환·failover
Gateway data plane은 Anthropic API를 upstream으로 쓰지 않는 한 Anthropic 인프라로 데이터를 보내지 않습니다.
다른 gateway
이미 LLM gateway가 있으면 유지하고 Other LLM gateways를 따르세요. 프로토콜 계약은 /protocol 및 gateway protocol reference에 있습니다.
상세
Quickstart 요지
- IdP에 OAuth client 등록, redirect
https://<gateway>/oauth/callback gateway.yaml작성 (listen, oidc, session, store, upstreams)- Postgres와 함께 Docker Compose 등으로 기동
- 개발자가 gateway URL로
/login
사설 네트워크 배포 필수. Claude Code는 private 주소 gateway에만 연결합니다(신뢰 gateway가 설정으로 명령을 밀 수 있으므로). Anthropic 운영 public gateway 엔드포인트만 예외이며, 목록은 바이너리에 고정되어 사용자 호스트를 추가할 수 없습니다 (v2.1.206 이전에는 해당 예외 없음).
개발자 연결
- managed settings 등으로 gateway URL 배포
- Desktop 세션에도 정책 전달 가능
- parent settings 제한으로 로컬 우회 축소
- CI·원격 머신은 비대화형 인증 패턴 문서 참조
조직이 보는 것: 감사·사용량·그룹 정책 적용 여부. 개발자에게 강제되는 것: 모델·도구·네트워크 등 managed 정책.
가용성·제한
gateway 경로에서 web/routines 등 claude.ai 전용 기능 일부는 제한됩니다. 공식 Availability and limitations 절을 배포 전 확인하세요.
체크리스트
- 사설 LB/VPN 호스트명으로만 노출
- IdP OIDC + Postgres store 준비
- upstream 자격증명을 시크릿으로만 주입
- 개발자
/loginE2E 검증 - managed policy·OTLP 목적지 구성