조직 LLM 게이트웨이 롤아웃

기준일: 2026-07-26
공식 기준: Roll out an LLM gateway for your organization

개요

관리자가 Claude Code용 LLM 게이트웨이를 롤아웃하는 절차입니다. 게이트웨이 제품 배포·운영 자체는 벤더 문서를 따르고, 여기서는 Claude Code 연결에 필요한 요구·체크포인트를 다룹니다.

개발자 연결: Connect
와이어 계약: Protocol

핵심 개념

자격 증명	보유자	체크포인트 표기
Provider credential	게이트웨이(업스트림 전달)	클라이언트 명령에 나타나지 않음
Gateway admin/test key	관리자	`<gateway-key>`
Developer key	개발자 각 1개	`<developer-key>`

상세

전제

인프라에 게이트웨이 HTTPS 리다이렉트 없는 최종 주소로 리슨, Claude 모델 이름을 공급자로 라우팅
공급자 자격: Anthropic Console API 키 또는 Bedrock/Agent Platform/Foundry 클라우드 자격
MDM 등으로 개발자 머신에 settings 전달 수단 (how settings reach devices)

게이트웨이 필수 요구

지원 API 형식 (formats 표). 아래 단계는 Anthropic Messages POST /v1/messages 가정
스트리밍: SSE를 버퍼링 없이 전달
Claude 모델 이름 라우팅 (예: claude-sonnet-4-6)
헤더·본문 양방향 무변경: anthropic-beta, anthropic-version 등 (feature pass-through)
업스트림 오류 문구 유지 (클라이언트 자동 복구가 문구 매칭)
요청 본문 WAF 검사 면제: 소스 코드·XML 스타일 태그가 XSS 규칙에 걸려 실세션 403 가능

선택: GET /v1/models (v2.1.129+) 모델 discovery.

5단계 롤아웃

1. 모델 라우팅 확인

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

체크포인트: 200 + content = 해당 모델 이름 라우팅 OK. 404 = 미라우팅. 공급자 401 = 게이트웨이 보유 provider 자격 오류. 모든 라우팅 모델 이름에 반복. 리다이렉트 뒤에 두지 말 것(본문/자격 드롭, discovery 실패).

2. 개발자 자격 증명 발급

개발자마다 키 1개. 동일 curl로 <developer-key> 검증.
Bearer 게이트웨이 → ANTHROPIC_AUTH_TOKEN. x-api-key → ANTHROPIC_API_KEY (credential 표).

3. Claude Code 테스트 (배포 전)

터미널 세션 전용 export (영구 파일 아님):

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"
claude -p "Reply with one word: connected"

체크포인트: 응답 + 게이트웨이 로그 POST /v1/messages 200 (쿼리 ?beta=true 가능 — path로 매칭).

메시지	원인
`Not logged in` + 로그 비어 있음	자격 증명이 세션에 안 들어감
`Not logged in` + 401 body에 `x-api-key`	`ANTHROPIC_API_KEY`로 전환
`Failed to authenticate. API Error: 401` + 업스트림 이름	developer key OK, provider 자격 오류
수분 hang	BASE_URL 오류/미도달 — 로그에 요청 없음

4. 설정 배포

변수/설정	역할	포함 시기
`ANTHROPIC_BASE_URL`	게이트웨이로 API 전송	항상
`apiKeyHelper` 또는 AUTH_TOKEN/API_KEY	게이트웨이 인증	항상 (셋 중 하나)
`ANTHROPIC_CUSTOM_HEADERS`	테넌트/라우팅 헤더	게이트웨이 요구 시
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	`/v1/models` → 피커	discovery 제공 시
`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`	베타 필드 억제	Bedrock/Vertex가 거부 시
Fast mode 스킵 변수	직접 api.anthropic.com 체크 실패 시 복구	조직이 fast mode 사용 시
`ANTHROPIC_MODEL` / DEFAULT_HAIKU 등	요청 모델 이름	게이트웨이 라우팅 이름이 기본과 다를 때
공급자별 BASE_URL 세트	3P 네이티브 형식	Bedrock/Vertex/Foundry/Platform AWS 전면 시

managed settings 예:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

managed ANTHROPIC_BASE_URL은 셸 export로 덮을 수 없음.
금지: 게이트웨이 자격 증명과 함께 forceLoginMethod / forceLoginOrgUUID (v2.1.146+ 에서 first-party login 강제 오류).
Server-managed settings는 api.anthropic.com 직결 필요 → 게이트웨이 배포는 파일 기반 managed settings.

별도 전달: Desktop 3P inference 설정 파일, CI runner env, WSL은 wslInheritsWindowsSettings true 시 Windows managed 상속.

관리 배포 없으면 개발자에게 URL·개인 키·어느 변수에 넣을지·조건부 변수를 전달하고 connect 페이지를 따르게 함.

체크포인트: claude가 로그인 화면 없이 시작, /status에 Anthropic base URL, managed면 Setting sources에 managed.

5. 개발자 머신에서 검증

스트리밍 curl (-N, "stream": true) — data: 줄이 점진 도착해야 함. 한 번에 오면 버퍼링. 모델별 반복.
claude 메시지 후:

로그인 프롬프트 → 배포/키 미도달
Failed to authenticate → 게이트웨이 로그로 developer vs provider 구분
ANTHROPIC_API_KEY 첫 사용 시 1회 승인 프롬프트 가능; AUTH_TOKEN은 무소음 전환
fast mode: /fast — 가용성 체크가 게이트웨이가 아닌 api.anthropic.com 직행 (fast mode behind gateways)

로그: 자격 증명으로 개발자 식별, x-claude-code-session-id로 세션 그룹.

유지보수

변화	증상	조치
새 Claude Code 베타 필드	업데이트 후 `400`	`anthropic-*`·본문 열린 전달, 릴리스 전 게이트웨이 테스트
새 모델	피커/`404`	라우팅 추가 후 curl 재검증, managed 모델 변수 갱신
자격 만료	전원 `401`	provider 자격 게이트웨이에서 회전; developer는 apiKeyHelper

키별 rate limit 시 클라이언트 재시도(최대 10, Retry-After) 반영.

체크리스트

요구사항 6항 + WAF 면제 확인
모든 모델 이름 curl 200
developer key 1인 1키 + 올바른 env 변수명
claude -p 파일럿 통과
managed 배포 후 /status 검증
스트리밍 비버퍼링 확인

다음 단계

기준일

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

조직 LLM 게이트웨이 롤아웃

기준일: 2026-07-26
공식 기준: Roll out an LLM gateway for your organization

개요

개발자 연결: Connect
와이어 계약: Protocol

핵심 개념

자격 증명	보유자	체크포인트 표기
Provider credential	게이트웨이(업스트림 전달)	클라이언트 명령에 나타나지 않음
Gateway admin/test key	관리자	`<gateway-key>`
Developer key	개발자 각 1개	`<developer-key>`

상세

전제

인프라에 게이트웨이 HTTPS 리다이렉트 없는 최종 주소로 리슨, Claude 모델 이름을 공급자로 라우팅
공급자 자격: Anthropic Console API 키 또는 Bedrock/Agent Platform/Foundry 클라우드 자격
MDM 등으로 개발자 머신에 settings 전달 수단 (how settings reach devices)

게이트웨이 필수 요구

지원 API 형식 (formats 표). 아래 단계는 Anthropic Messages POST /v1/messages 가정
스트리밍: SSE를 버퍼링 없이 전달
Claude 모델 이름 라우팅 (예: claude-sonnet-4-6)
헤더·본문 양방향 무변경: anthropic-beta, anthropic-version 등 (feature pass-through)
업스트림 오류 문구 유지 (클라이언트 자동 복구가 문구 매칭)
요청 본문 WAF 검사 면제: 소스 코드·XML 스타일 태그가 XSS 규칙에 걸려 실세션 403 가능

선택: GET /v1/models (v2.1.129+) 모델 discovery.

5단계 롤아웃

1. 모델 라우팅 확인

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

2. 개발자 자격 증명 발급

개발자마다 키 1개. 동일 curl로 <developer-key> 검증.
Bearer 게이트웨이 → ANTHROPIC_AUTH_TOKEN. x-api-key → ANTHROPIC_API_KEY (credential 표).

3. Claude Code 테스트 (배포 전)

터미널 세션 전용 export (영구 파일 아님):

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"
claude -p "Reply with one word: connected"

체크포인트: 응답 + 게이트웨이 로그 POST /v1/messages 200 (쿼리 ?beta=true 가능 — path로 매칭).

메시지	원인
`Not logged in` + 로그 비어 있음	자격 증명이 세션에 안 들어감
`Not logged in` + 401 body에 `x-api-key`	`ANTHROPIC_API_KEY`로 전환
`Failed to authenticate. API Error: 401` + 업스트림 이름	developer key OK, provider 자격 오류
수분 hang	BASE_URL 오류/미도달 — 로그에 요청 없음

4. 설정 배포

변수/설정	역할	포함 시기
`ANTHROPIC_BASE_URL`	게이트웨이로 API 전송	항상
`apiKeyHelper` 또는 AUTH_TOKEN/API_KEY	게이트웨이 인증	항상 (셋 중 하나)
`ANTHROPIC_CUSTOM_HEADERS`	테넌트/라우팅 헤더	게이트웨이 요구 시
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	`/v1/models` → 피커	discovery 제공 시
`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`	베타 필드 억제	Bedrock/Vertex가 거부 시
Fast mode 스킵 변수	직접 api.anthropic.com 체크 실패 시 복구	조직이 fast mode 사용 시
`ANTHROPIC_MODEL` / DEFAULT_HAIKU 등	요청 모델 이름	게이트웨이 라우팅 이름이 기본과 다를 때
공급자별 BASE_URL 세트	3P 네이티브 형식	Bedrock/Vertex/Foundry/Platform AWS 전면 시

managed settings 예:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

별도 전달: Desktop 3P inference 설정 파일, CI runner env, WSL은 wslInheritsWindowsSettings true 시 Windows managed 상속.

관리 배포 없으면 개발자에게 URL·개인 키·어느 변수에 넣을지·조건부 변수를 전달하고 connect 페이지를 따르게 함.

체크포인트: claude가 로그인 화면 없이 시작, /status에 Anthropic base URL, managed면 Setting sources에 managed.

5. 개발자 머신에서 검증

스트리밍 curl (-N, "stream": true) — data: 줄이 점진 도착해야 함. 한 번에 오면 버퍼링. 모델별 반복.
claude 메시지 후:

로그인 프롬프트 → 배포/키 미도달
Failed to authenticate → 게이트웨이 로그로 developer vs provider 구분
ANTHROPIC_API_KEY 첫 사용 시 1회 승인 프롬프트 가능; AUTH_TOKEN은 무소음 전환
fast mode: /fast — 가용성 체크가 게이트웨이가 아닌 api.anthropic.com 직행 (fast mode behind gateways)

로그: 자격 증명으로 개발자 식별, x-claude-code-session-id로 세션 그룹.

유지보수

변화	증상	조치
새 Claude Code 베타 필드	업데이트 후 `400`	`anthropic-*`·본문 열린 전달, 릴리스 전 게이트웨이 테스트
새 모델	피커/`404`	라우팅 추가 후 curl 재검증, managed 모델 변수 갱신
자격 만료	전원 `401`	provider 자격 게이트웨이에서 회전; developer는 apiKeyHelper

키별 rate limit 시 클라이언트 재시도(최대 10, Retry-After) 반영.

체크리스트

요구사항 6항 + WAF 면제 확인
모든 모델 이름 curl 200
developer key 1인 1키 + 올바른 env 변수명
claude -p 파일럿 통과
managed 배포 후 /status 검증
스트리밍 비버퍼링 확인

다음 단계

기준일

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

조직 LLM 게이트웨이 롤아웃

개요

핵심 개념

상세

전제

게이트웨이 필수 요구

5단계 롤아웃

1. 모델 라우팅 확인

2. 개발자 자격 증명 발급

3. Claude Code 테스트 (배포 전)

4. 설정 배포

5. 개발자 머신에서 검증

유지보수

체크리스트

다음 단계

기준일

관련 가이드

조직 LLM 게이트웨이 롤아웃

개요

핵심 개념

상세

전제

게이트웨이 필수 요구

5단계 롤아웃

1. 모델 라우팅 확인

2. 개발자 자격 증명 발급

3. Claude Code 테스트 (배포 전)

4. 설정 배포

5. 개발자 머신에서 검증

유지보수

체크리스트

다음 단계

기준일

관련 가이드