Claude Code 연결

공식 Connect Claude Code to an LLM gateway 가이드를 기반으로 합니다 — shunt가 바로 연결하는 게이트웨이입니다.

1. Claude Code를 shunt로 향하게 하기

실행 중인 게이트웨이(기본 bind 127.0.0.1:3001)로 base URL을 설정하세요. 셸에서 하거나 설정 파일의 env 블록에 영속화하세요:

export ANTHROPIC_BASE_URL=http://127.0.0.1:3001

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3001"
  }
}

기존 Anthropic 자격 증명을 유지하세요 — shunt는 매핑하지 않은 모든 모델에 대해 이를 변경 없이 api.anthropic.com으로 전달하므로, 매핑되지 않은 모델은 이전과 완전히 동일하게 동작합니다. 매핑된 모델의 프로바이더 자격 증명은 shunt 자체가 주입하며, Claude Code는 이를 절대 보내지 않습니다.

2. Anthropic 자격 증명 선택

Claude Code가 shunt로 보내는 자격 증명은 두 가지 역할을 합니다: Claude 패스스루 모델을 인증하고, 모델 디스커버리를 게이팅합니다 — Claude Code는 ANTHROPIC_AUTH_TOKEN, API 키, 또는 apiKeyHelper가 설정되어 있을 때만 GET /v1/models 요청을 보냅니다. 매핑된 모델(gpt-* 등)은 어느 쪽이든 영향을 받지 않습니다.

sk-dummy 같은 더미 값은 디스커버리 게이트를 만족시키지만 패스스루를 깨뜨립니다 — Anthropic으로 전달되어 401을 반환합니다.

claude setup-token을 선호하세요. 이는 1년 OAuth 토큰을 발급하므로(인증 문서), 갱신할 것이 없고 하나의 값이 두 역할을 모두 커버합니다:

claude setup-token                        # 브라우저 로그인 → sk-ant-oat… 출력
export ANTHROPIC_AUTH_TOKEN=sk-ant-oat…   # 또는 설정 `env` 블록에 영속화

shunt token 자격 증명 헬퍼

shunt token은 Claude 구독 OAuth 토큰을 stdout으로 출력하므로, Claude Code의 apiKeyHelper에 바로 연결됩니다:

// ~/.claude/settings.json
{
  "apiKeyHelper": "/path/to/shunt token"
}

• 정적 모드 — SHUNT_GATEWAY_TOKEN 또는 CLAUDE_CODE_OAUTH_TOKEN이 설정되어 있으면, 그 값을 변경 없이 그대로 출력합니다. claude setup-token 값을 가리키게 하면 아무것도 갱신되지 않습니다.
• 자동 갱신 모드 — 그렇지 않으면 ~/.claude/.credentials.json을 읽고(CLAUDE_CREDENTIALS로 오버라이드), 액세스 토큰을 반환하며, 만료 5분 이내일 때만 갱신하여 0600으로 원자적으로 다시 씁니다.

정적 + setup-token 경로가 가장 단순하고 안전한 기본값으로 남아 있습니다.

3. 매핑된 프로바이더의 자격 증명 제공

이것들은 Claude Code가 아니라 shunt의 환경으로 갑니다:

export OPENAI_API_KEY=sk-...   # openai 프로바이더
codex login                    # codex/ChatGPT 프로바이더 (이후 자동 갱신됨)

4. 매핑된 모델 선택

Claude Code의 모델 디스커버리는 claude/anthropic으로 시작하는 id만 존중하므로, OpenAI/Codex id(gpt-*)에는 ANTHROPIC_CUSTOM_MODEL_OPTION을 사용하세요 — 이는 id가 검증을 건너뛰는 선택기 항목을 추가합니다:

export ANTHROPIC_CUSTOM_MODEL_OPTION="gpt-5.6-sol"

그런 다음 Claude Code의 /model에서 선택하세요. 그 id가 shunt가 라우팅하는 대상이므로, 일치하는 [models.upstream_model] 항목, [[routes]], 또는 [[route_prefixes]] 규칙으로 해석되어야 합니다.

두 가지 선택기 노출 방법은 claude-/anthropic- 프리픽스를 기준으로 깔끔하게 갈리며 — 겹치지 않습니다. 디스커버리는 오직 claude-/anthropic- id만 존중하고, ANTHROPIC_CUSTOM_MODEL_OPTION과 CLAUDE_CODE_MAX_CONTEXT_TOKENS 윈도우 오버라이드는 오직 그 프리픽스로 시작하지 않는 id에만 적용됩니다:

그래서 claude-…-via-codex 디스커버리 별칭은 편리하지만(자동 등록, 원탭) 그 컨텍스트 윈도우는 200k 기본값에 고정됩니다 — 오버라이드가 claude- 프리픽스 id에 닿을 수 없습니다(노력 & 컨텍스트). 여러 모델에 걸친 선택기 편의를 위해서는 디스커버리 별칭을(200k 분모를 감수), 정확한 윈도우를 위해서는 한 번에 한 모델씩 ANTHROPIC_CUSTOM_MODEL_OPTION을 통한 비-claude- id를 선택하세요.

에이전트별 우회

컨텍스트별 선택은 Claude Code 자체 노브를 통해 동작합니다 — 메인 세션이 Claude에 머무는 동안 한 에이전트를 매핑된 모델로 우회하세요:

# .claude/agents/researcher.md
---
name: researcher
model: gpt-5.6-sol   # 이 에이전트의 추론이 우회됨; 메인 세션은 Claude에 머무름
---

명명된 서브에이전트의 model: 프론트매터는 서브에이전트를 gpt-* id에 올리는 유일한 방법입니다: 그 필드는 임의의 문자열을 받는 반면, Agent/Task 도구의 model 파라미터는 내장 별칭(opus/sonnet/haiku/fable)으로 제한되어 게이트웨이 id를 받을 수 없습니다. model 오버라이드 없이 에이전트를 타입별로 스폰하세요 — 도구 파라미터가 프론트매터보다 우선하므로(CLAUDE_CODE_SUBAGENT_MODEL > 도구 model > 프론트매터 > inherit), 하나를 전달하면 매핑된 모델을 가립니다. CLAUDE_CODE_SUBAGENT_MODEL은 모든 서브에이전트를 하나의 모델로 강제합니다. 윈도우는 모델 id를 자동으로 따라가므로, 하나의 전역 CLAUDE_CODE_MAX_CONTEXT_TOKENS가 매핑된 서브에이전트의 크기를 정하는 동안 Claude 메인은 자체 값을 유지합니다.

5. 검증

# 매핑되지 않은 모델 -> Anthropic으로 전달 (사용자의 Anthropic 자격 증명 사용)
curl -s -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# 매핑된 모델 -> 프로바이더로 우회 (shunt의 프로바이더 자격 증명 사용)
curl -s -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.6-sol","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

그런 다음 claude를 시작하고, /status를 실행하여 Anthropic base URL 줄이 게이트웨이를 표시하는지 확인하세요. 추론 노력과 컨텍스트 윈도우 튜닝은 노력 & 컨텍스트도 참고하세요.