LLM 게이트웨이에 Claude Code 연결

기준일: 2026-07-26
공식 기준: Connect Claude Code to an LLM gateway

개요

조직 게이트웨이에 Claude Code를 붙이는 개발자 가이드입니다. 관리자 배포 여부 확인 경로와 직접 구성 경로를 모두 다룹니다.

• 롤아웃: llm-gateway-rollout
• 프로토콜: llm-gateway-protocol

핵심 개념

변수	역할
ANTHROPIC_BASE_URL	게이트웨이 주소
ANTHROPIC_AUTH_TOKEN	Bearer (Authorization)
ANTHROPIC_API_KEY	x-api-key
apiKeyHelper	명령으로 키 fetch·회전

상세

기존 설정 확인

1. claude — 로그인 화면이면 자격 증명 미배포
2. /status Status 탭: Anthropic base URL, Auth token/API key/apiKeyHelper, Login method
3. 테스트 메시지

직접 구성

자격 증명 변수

게이트웨이가 Bearer를 보면 ANTHROPIC_AUTH_TOKEN, x-api-key면 ANTHROPIC_API_KEY. 관리자 안내에 따름.

base URL + 자격 증명

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="..."
claude

settings:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "..."
  }
}

백그라운드·agent view까지 상속하려면 settings env 권장.

검증

/status + 테스트 프롬프트. claude -p "Reply with one word: connected".

기존 로그인

게이트웨이 자격 증명이 있으면 해당 세션 구독 로그인 비활성·API 청구. BASE_URL만 있고 자격 증명 없으면 구독 유지 가능 (subscriptions).

표면별

• VS Code: 확장/원격 컨테이너 env
• Desktop: 3P inference·게이트웨이 설정 (managed CLI env만으로 부족할 수 있음)
• GitHub Actions: secrets → job env
• Agent SDK: 프로세스 env
• Slack/web/Remote Control: 표면별 제한 — 해당 문서

추가 구성

• ANTHROPIC_CUSTOM_HEADERS — 테넌트 헤더
• CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY — /v1/models 피커
• apiKeyHelper — 짧은 수명 토큰
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC — 게이트웨이 밖 선택 트래픽
• 클라우드 공급자 전면 시 ANTHROPIC_BEDROCK_BASE_URL 등 + 공급자 플래그 (route through gateway)

트러블슈팅

증상	확인
로그인 화면	자격 증명·managed 미도달
401/403	토큰·헤더 매핑(Bearer vs x-api-key)·그룹 정책
hang	BASE_URL·프록시·NO_PROXY
피커 비움	discovery
기능 이상	헤더/오류 문구 드롭 (protocol)

체크리스트

• /status base URL·auth 확인
• settings env로 상속
• 표면별 env 정렬
• 구독 vs API 청구 이해

다음 단계

• Gateways
• Rollout
• Protocol

기준일

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