Claude Code 연결

Claude Code를 shunt로 향하게 하고, 올바른 Anthropic 자격 증명을 선택하고, 매핑된 모델을 고르기.

공식 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-* 등)은 어느 쪽이든 영향을 받지 않습니다.

자격 증명	토큰 갱신	디스커버리	Claude 패스스루	과금
claude.ai OAuth 로그인만	자동	❌ 절대 발동 안 함	✅	구독
`claude setup-token`의 `ANTHROPIC_AUTH_TOKEN` — 권장	불필요(1년 토큰)	✅	✅	구독
`apiKeyHelper` = `shunt token`	헬퍼가 갱신	✅	✅	구독
`ANTHROPIC_AUTH_TOKEN=<실제 API 키>`	불필요	✅	✅	API(구독 아님)

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 경로가 가장 단순하고 안전한 기본값으로 남아 있습니다.

`shunt gateway token` 헬퍼

shunt가 [server.gateway]를 운영한다면, 공유 토큰 하나 대신 사용자마다 자기 게이트웨이 세션을 가질 수 있습니다. 한 번 로그인한 뒤 두 번째 헬퍼를 사용하세요:

shunt gateway login https://gateway.example.com

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

이것은 위의 shunt token과는 다른 자격 증명입니다: 그쪽은 업스트림 Claude 구독 토큰을, 이쪽은 shunt 배포가 당신에게 발급한 토큰을 출력합니다. 헬퍼는 만료 5분 전에 갱신하며, 동시에 실행 중인 Claude Code 세션들이 일회용 refresh token을 재사용하지 못하도록 파일 잠금 아래에서 처리합니다. shunt gateway logout으로 세션을 삭제합니다.

설정 파일 건너뛰기: `shunt gateway claude`

~/.claude/settings.json을 아예 건드리지 않으려면, 프로세스 하나에 대해서만 shunt가 연결을 구성하게 하세요:

shunt gateway claude
shunt gateway claude -p 'summarize this repo' --model opus

게이트웨이 base URL과 apiKeyHelper를 함께 담은 인라인 --settings 문서와 함께 Claude Code를 실행하며, 그 호출에만 적용됩니다 — 설정 파일은 그대로이고, 셸에 이미 export된 ANTHROPIC_BASE_URL보다 이 문서가 우선합니다(Claude Code 2.1.234 기준 실측). claude 뒤의 인자는 그대로 전달되며, 맨 앞에 오는 --help와 --config만 shunt가 가져갑니다(--config는 조용히 삼켜지는 대신 거부됩니다). 따라서 claude 자신의 --help나 --config는 -- 뒤에 두세요. shunt gateway claude를 참고하세요.

또한 실행되는 프로세스에서 자격 증명 및 프로바이더 모드 관련 변수 34개와, CLAUDE_CODE_HOST_AUTH_ENV_VAR가 가리키는 변수까지 제거합니다. 그렇게 하지 않으면 export된 ANTHROPIC_AUTH_TOKEN이 apiKeyHelper를 완전히 이겨버리고, CLAUDE_CODE_USE_GATEWAY는 클라이언트를 게이트웨이 프로바이더 모드로 전환시켜 헬퍼를 아예 조회하지 않게 만듭니다 — 둘 중 하나만 있어도 이 배선이 조용히 무력화됩니다. ANTHROPIC_BASE_URL은 settings 문서가 주입하므로 그대로 둡니다. 이것으로 닫히는 것은 주변 환경(ambient environment) 경로뿐입니다. settings 파일의 env 블록, 사용자가 이미 설정해 둔 apiKeyHelper, 기존에 저장된 로그인, 또는 file-descriptor 리더의 well-known 경로 폴백은 여전히 실행된 클라이언트에 자격 증명을 공급할 수 있습니다.

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-`/`anthropic-` id (디스커버리 별칭)	비-`claude-` id (예: `gpt-5.6-sol`)
`/v1/models` 디스커버리 → `/model` 선택기	✅ 자동 등록(“From gateway”), 여러 모델	❌ Claude Code가 버림
`ANTHROPIC_CUSTOM_MODEL_OPTION`	❌ 존중되지 않음	✅ 선택기에 추가(id 하나만)
`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 윈도우	❌ 무시됨 → 200k 기본값	✅ 적용됨 → 실제 윈도우 설정

그래서 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 줄이 게이트웨이를 표시하는지 확인하세요. 추론 노력과 컨텍스트 윈도우 튜닝은 노력 & 컨텍스트도 참고하세요.