Claude apps gateway 설정 레퍼런스
공식 기준: https://code.claude.com/docs/en/claude-apps-gateway-config
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Claude apps gateway는 YAML 설정 파일로 구성합니다. 시크릿은 ${ENV} 또는 ${file:/path} 확장을 사용하세요. 운영 로그 레벨은 CLAUDE_GATEWAY_LOG_LEVEL(info|warn|error)이며 감사 이벤트와는 별개입니다.
핵심 개념
필수 섹션
| 섹션 | 역할 |
|---|---|
listen |
바인드 포트, public_url, trusted_proxies |
oidc |
issuer, client_id/secret, scopes, PKCE, groups claim, CA |
session |
JWT/세션 TTL 등 |
store |
Postgres 등 상태 저장 |
upstreams |
Bedrock / Claude Platform on AWS / Vertex / Foundry / Anthropic |
선택 섹션
| 섹션 | 역할 |
|---|---|
admin |
Admin API 키, spend limits, retention, admin_groups |
enforcement |
fail_closed 등 |
models |
모델 라우팅·표시 |
managed |
그룹/이메일 도메인별 managed settings policies |
telemetry |
OTLP 목적지 |
| HTTP tuning | 타임아웃·한도 |
상세
listen
port(기본 8080),public_url(개발자·IdP가 보는 origin)- L7 프록시 뒤에서는
trusted_proxies에 프록시 CIDR — 미설정 시 X-Forwarded-For 무시, rate limit·감사가 프록시 IP로 붕괴
oidc
issuer+ well-known discovery- authorization-code + 기본 PKCE (
use_pkce: false로 끌 수 있음) email및 선택groups(id_token 또는userinfo_fallback)- Okta thin token →
userinfo_fallback: true - Entra: groups Object ID 또는 App Roles (
groups_claim: roles) - Google: 그룹은
google_groups/Admin SDK 또는 email_domain 게이팅; offline은extra_auth_params
session / store
세션 TTL(기본 약 1시간), JWT 서명 키, Postgres 연결 문자열. 수평 확장은 stateless replica + 공유 Postgres.
upstreams
provider별 auth(API key, IRSA/Workload Identity, Azure AD 등), 리전, 모델 ID 매핑, failover 순서. per-upstream model ID는 upstream name: 키. 목록에 없는 upstream은 해당 모델 라우팅에서 스킵.
managed
IdP 그룹·이메일 도메인 매칭으로 managed settings 정책 선택. CLI managed settings tier에 적용되어 로컬 우회를 막습니다.
admin / spend
/v1/organizations/spend_limits 미러와 per-developer spend enforcement. 한도 값 자체는 admin API로 설정. write_keys/read_keys, admin_groups, blocked_message, retention 일수 등.
클라이언트 측 managed settings
gateway 로그인 클라이언트가 수신하는 정책 키는 permissions·sandbox 등과 동일한 managed 계층입니다. 상세 키는 settings 문서를 따릅니다.
실행:
claude gateway --config gateway.yaml
체크리스트
- 필수 5섹션 채움
- 시크릿 env/file 확장
-
public_url·redirect URI 일치 -
trusted_proxies설정 (프록시 사용 시) - upstream 모델 ID·failover 검증
- managed policies 그룹 매칭 테스트