LLM 게이트웨이 프로토콜 레퍼런스
기준일: 2026-07-26
공식 기준: Gateway protocol reference
개요
자체 LLM 게이트웨이가 Claude Code 요청을 올바르게 전달하기 위한 와이어 계약입니다. 롤아웃: llm-gateway-rollout. 개발자 연결: llm-gateway-connect.
핵심 개념
| 영역 | 요지 |
|---|---|
| API 형식 | Anthropic Messages 등 지원 형식 (formats 표) |
| 스트리밍 | SSE 버퍼링 금지 |
| 헤더 | anthropic-version/anthropic-beta 등 무변경 전달 |
| 오류 | 업스트림 문구 유지 |
| Discovery | 선택 GET /v1/models |
상세
API 형식
기본 가정: POST /v1/messages. Foundry·Claude Platform on AWS 등은 별도 베이스 URL·본문 관례. 선택 엔드포인트·시작 트래픽(버전 확인 등)은 게이트웨이 밖일 수 있음.
스트리밍: 이벤트 도착 즉시 전달. 전체 버퍼링은 Claude Code를 멈추게 함.
형식 불일치: 필드 드롭·재작성 시 도구 호출·캐시·베타 기능 손상. 알 수 없는 필드는 보존.
요청 헤더
헤더 이름은 와이어에서 대소문자 무시. 반드시 무변경 전달: anthropic-version, anthropic-beta. Claude Platform on AWS 업스트림이면 anthropic-workspace-id도. 나머지는 라우팅·추적에 소비 가능.
| Header | 설명 |
|---|---|
Authorization, x-api-key |
개발자 게이트웨이 자격 증명 (변수에 따라 하나 또는 둘) |
anthropic-version |
API 버전 (예: 2023-06-01). Bedrock/Vertex 형식 요청은 본문 anthropic_version 필드도 사용 |
anthropic-beta |
쉼표 구분 capability. 개별 값 allowlist 금지 — 릴리스마다 증가 |
x-claude-code-session-id 등 |
세션 그룹·추적 (원문 표 전체 참고) |
Forward as open lists
anthropic-beta 값과 요청 본문 필드를 고정 allowlist로 걸면 새 Claude Code 릴리스에서 400이 납니다. 헤더·본문을 열린 목록으로 전달.
System prompt attribution
attribution 블록을 제거하지 말고 업스트림으로 전달.
Feature pass-through
| 항목 | 실패 시 |
|---|---|
| 스트리밍 | 응답 stall |
| beta 헤더/본문 | 기능 비활성·400 |
| 오류 문구 | 클라이언트 자동 복구 실패 |
| 재시도 상태 코드 | 잘못된 재시도/포기 |
프리릴리스 억제가 필요하면 클라이언트 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS (롤아웃 표).
모델 discovery
GET /v1/models (지원 시). 피커 채움·캐시. 리다이렉트는 실패로 취급(자격 누수 방지). 요청/응답 스키마 상세는 원문 Request and response 절.
체크리스트
- Messages 호환 또는 충실 변환
- SSE 비버퍼링
- anthropic-version/beta 열린 전달
- 오류 문구 유지
- (선택) /v1/models 검증
다음 단계
기준일
- 문서 작성·동기화 기준일: 2026-07-26
- 원문: https://code.claude.com/docs/en/llm-gateway-protocol