LLM Gateway — 개발자 설정 가이드

사내 LLM 게이트웨이를 통해 Claude Code 와 Codex 에서 승인된 모델을 사용하는 방법입니다.

1 원클릭 설정 — setup-developer 실행

관리자에게 받은 온보딩 번들(게이트웨이 리포의 scripts/ + outputs.json)에서 아래 한 줄을 실행합니다. 편집할 파일은 없습니다.

./scripts/setup-developer.sh          # Windows: .\scripts\setup-developer.ps1

스크립트가 자동으로 수행하는 일:

2 로그인 (가상 키 발급 준비)

llmgw-login          # Windows: llmgw-login.ps1

aws sso login --profile llm-gateway

3 게이트웨이 접속 (HTTP — PoC 전용)

이 게이트웨이는 HTTP(평문) 로 서비스됩니다 — 가상 키와 프롬프트가 암호화 없이 전송되므로 PoC 용도로만 사용하세요. 접근은 허용된 사내 IP 대역(Security Group allowlist)에서만 가능합니다. 별도의 인증서 신뢰나 터널 설정은 필요 없습니다 — https://llmgw.example.com 로 바로 접속합니다.

4 웹 검색 MCP 등록 (Claude Code)

서버 측 등록만으로는 클라이언트에서 안 보입니다. 아래 명령 한 번으로 등록하세요 — headersHelper 가 회전 키를 동적 주입합니다.

claude mcp add-json websearch '{
  "type": "http",
  "url": "https://llmgw.example.com/mcp/",
  "headersHelper": "~/.llm-gateway/get-mcp-headers.sh"
}'
# Windows에서는 headersHelper 를 다음으로 바꾸세요 (setup 이 %USERPROFILE%\.llm-gateway 에 헬퍼를 설치합니다):
#   "headersHelper": "py -3 "%USERPROFILE%\.llm-gateway\gateway_auth.py" mcp-headers"

등록 후 도구 이름: websearch-web-search-tool___WebSearch

5 동작 확인 — healthcheck 실행

./scripts/healthcheck.sh          # Windows: .\scripts\healthcheck.ps1
# 토큰 발급 → https://llmgw.example.com/v1/models 호출까지 자동 검증
# 기대: claude-opus-4-8/claude-sonnet-5/claude-haiku-4-5/claude-fable-5 + gpt-5.5 목록

이제 claude / codex 실행 시 호출이 게이트웨이로 나가고, 사용량은 관리자 대시보드에 집계됩니다.

6 참고 — 스크립트가 병합하는 설정 (수동 확인용)

1단계 스크립트가 병합하는 내용입니다. 직접 편집할 필요는 없고, 문제가 생겼을 때 아래 값이 들어갔는지 확인하는 용도입니다.

# ~/.claude/settings.json (우리 키만 병합 — 나머지는 그대로 유지)
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llmgw.example.com",
    "AWS_REGION": "us-east-1",
    "ANTHROPIC_DEFAULT_OPUS_MODEL":   "claude-opus-4-8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL":  "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL":  "claude-fable-5"
  },
  "apiKeyHelper": "./scripts/get-gateway-token.sh",
  // Windows: setup 이 apiKeyHelper 를 python 절대경로 형태로 기록합니다 — 예: py -3 "%USERPROFILE%\.llm-gateway\gateway_auth.py" token
  "permissions": { "deny": ["WebSearch"] }
}

# ~/.codex/config.toml (우리 provider 블록만 교체 — 다른 섹션은 그대로 유지)
model = "gpt-5.5"
model_provider = "llm-gateway"

[model_providers.llm-gateway]
name     = "Company LLM Gateway (LiteLLM)"
base_url = "https://llmgw.example.com/v1"
wire_api = "responses"

[model_providers.llm-gateway.auth]
command = "./scripts/get-gateway-token.sh"
refresh_interval_ms = 300000
timeout_ms = 5000