게이트웨이로 Claude Code 실행

기준일: 2026-07-26
공식 기준: Run Claude Code through a gateway

개요

게이트웨이는 조직이 Claude Code와 모델 공급자 사이에 두는 프록시입니다. Claude Code는 공급자에 직접 가지 않고 게이트웨이로 API 트래픽을 보내고, 게이트웨이가 조직이 보유한 자격 증명으로 전달합니다. 개발자는 공급자 자격 증명 대신 게이트웨이 자격 증명으로 인증하므로 인증·사용량·예산·감사 로그를 한곳에서 통제합니다.

Claude Code는 claude 바이너리에 셀프호스트 게이트웨이 Claude apps gateway를 포함합니다. 별도 게이트웨이 제품을 도입하지 않아도 됩니다. 이미 LLM gateway를 운영 중이면 Claude Code도 함께 쓸 수 있습니다.

이 페이지 범위:

• 게이트웨이가 Claude Code와 공급자 사이에 어떻게 놓이는지
• Claude apps gateway vs 기존 게이트웨이 선택
• claude.ai 구독과의 관계
• 게이트웨이 밖에서 따로 설정할 항목

핵심 개념

개념	설명
Developer credential	개발자별, 게이트웨이가 발급. 게이트웨이 인증·사용량 식별
Provider credential	게이트웨이가 보유하는 조직 공급자 계정 자격 증명 (공유)
라우팅	게이트웨이 주소 + 게이트웨이 자격 증명으로 Claude Code를 가리킴
공급자	Anthropic API 또는 Bedrock / Google Cloud Agent Platform / Microsoft Foundry 등 (게이트웨이 설정이 결정)

상세

게이트웨이 동작

각 개발자 Claude Code는 게이트웨이 주소를 가리키고 게이트웨이 발급 자격 증명으로 인증합니다.

게이트웨이는 개발자를 인증하고, 설정한 접근·예산 규칙을 적용한 뒤, 조직 자격 증명으로 공급자에 요청을 전달합니다. Anthropic 형식 단일 엔드포인트를 노출하는 Claude apps gateway 등이면 공급자 변경 시 개발자 머신을 손대지 않아도 됩니다.

흐름 요약 (공식 다이어그램 기준):

1. 개발자 머신: CLI·VS Code 확장 → 게이트웨이 주소 + 개발자별 자격 증명
2. 조직 인프라: 게이트웨이가 인증·사용량·예산·라우팅 후 조직 자격 증명으로 전달
3. 모델 공급자: 설정된 공급자(예: Anthropic API)로 전달, 다른 공급자 옵션은 점선으로 연결 가능

게이트웨이 선택

Claude apps gateway

Anthropic 셀프호스트 게이트웨이이며 claude 바이너리에 포함됩니다. 업스트림으로 Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry, Anthropic API를 라우팅할 수 있습니다. 개발자는 /login으로 기업 IdP SSO 로그인, 게이트웨이는 IdP 그룹별 모델 접근과 managed settings를 강제하고, OTLP 사용량 메트릭을 조직 observability 스택으로 보냅니다.

Claude Code 릴리스와 함께 빌드·테스트되므로 Claude Code가 보내는 헤더·요청 필드를 전달합니다. 별도 유지 게이트웨이는 릴리스마다 전달 규칙 갱신이 필요합니다. 게이트웨이 세션에서 다르게 동작하는 소수의 기능은 Availability and limitations을 참고하세요.

로그인은 브라우저 SSO이며 서비스 토큰 흐름이 없어, 로그인 승인할 개발자가 없는 CI 파이프라인은 이 경로로 인증할 수 없습니다. 그런 경우는 공급자에 직접 구성합니다. 개발자가 로그인한 머신의 Agent SDK 세션과 claude -p는 해당 머신의 게이트웨이 세션·정책을 따릅니다. CI pipelines and remote machines.

배포: Claude apps gateway.

기타 게이트웨이

조직이 이미 LLM/API 게이트웨이를 쓰면 그것을 쓸 수 있습니다. Anthropic은 타 게이트웨이 제품을 보증·유지·감사하지 않으며, 어떤 게이트웨이로든 Claude Code를 비-Claude 모델로 라우팅하는 것을 지원하지 않습니다. 관리자 롤아웃 체크리스트·구현 요구·연결 방법은 Other LLM gateways를 참고하세요.

구독과 게이트웨이

게이트웨이 자격 증명으로 연결하면 사용량은 조직 공급자 계정 API 요금으로 청구되고, 개발자 claude.ai 구독은 사용·청구되지 않습니다. 자체 게이트웨이에 ANTHROPIC_AUTH_TOKEN을 설정하거나 Claude apps gateway에 /login하면 해당 세션의 구독 로그인이 꺼집니다. 그 자격 증명으로 전달된 모든 요청은 게이트웨이 공급자 계정에 청구됩니다.

예외: ANTHROPIC_BASE_URL만 설정하고 게이트웨이 자격 증명이 없으면, 요청은 게이트웨이를 거치지만 저장된 claude.ai 로그인이 활성 자격 증명으로 남아 구독 한도·청구가 적용됩니다. 상세는 Other LLM gateways — subscriptions.

게이트웨이와 별도로 설정할 항목

게이트웨이는 모델 API 요청을 라우팅합니다. 아래는 다른 곳에서 설정합니다.

• 어떤 모델이 답할지: /model 또는 model environment variables. 게이트웨이는 어디로 갈지만 정하고 개발자 모델 선택을 대신하지 않습니다. Claude apps gateway는 그룹별 availableModels allowlist로 선택지를 제한할 수 있습니다.
• 기타 네트워크 트래픽: 버전 확인·다운로드 등은 게이트웨이 경로와 별도로 Anthropic으로 갑니다. 선택적 클라이언트 텔레메트리는 공급자에 따라 다릅니다. telemetry defaults. Claude apps gateway 로그인 세션에서는 게이트웨이 자격 증명이 Anthropic 향 analytics를 끄고, telemetry forwarding이 구성되면 OTLP를 게이트웨이에 고정합니다. 네트워크는 여전히 required domains egress가 필요하거나 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC로 선택 스트림을 끌 수 있습니다.
• 기업 HTTP 프록시: HTTPS_PROXY는 Claude Code와 통신하는 모든 서버(게이트웨이 포함) 사이에 있습니다. 네트워크가 요구하면 게이트웨이 외에 proxy 설정도 합니다. 호스팅 Claude apps gateway는 sign-in이 프록시 호스트가 private network인지도 검사합니다. 아니면 게이트웨이 호스트를 NO_PROXY에 넣어 CLI가 직접 연결하게 합니다.

체크리스트

• 조직이 중앙 자격 증명·예산·감사가 필요한지 판단했다
• Claude apps gateway vs 기존 LLM gateway 중 경로를 골랐다
• 개발자 자격 증명과 공급자 자격 증명 역할을 분리했다
• 구독 청구 vs API 청구 결과를 이해했다 (ANTHROPIC_BASE_URL만 설정한 예외 포함)
• 모델 선택·프록시·nonessential traffic을 게이트웨이와 분리해 설정했다
• CI는 SSO-only 게이트웨이 한계를 알고 직접 공급자 구성을 검토했다

다음 단계

• Claude apps gateway — Anthropic 셀프호스트 배포
• Other LLM gateways — 기존 게이트웨이 구현·연결
• 조직 설정 — 더 넓은 롤아웃 결정

기준일

• 문서 작성·동기화 기준일: 2026-07-26
• 원문: https://code.claude.com/docs/en/gateways