구성 | shunt

shunt는 다음 순서로(우선순위가 높아지는 순서) 구성을 로드합니다:

내장 기본값 — 모든 프로바이더(anthropic, openai, codex 등)가 사전 구성되어 있습니다.
TOML 파일. --config <path>를 사용하면 정확히 그 파일이 사용됩니다(파일이 없으면 오류). 그렇지 않으면 shunt는 다음에서 처음 발견되는 파일을 사용합니다:
- ./shunt.toml
- $XDG_CONFIG_HOME/shunt/shunt.toml(기본값 ~/.config/shunt/shunt.toml)
- $HOMEBREW_PREFIX/etc/shunt.toml(기본 프리픽스 /opt/homebrew 및 /usr/local)
부팅 로그는 어떤 파일이 로드되었는지, 또는 기본값이 사용 중인지 보고합니다.
SHUNT_ 접두사가 붙은 환경 변수로, 중첩 키에는 __를 사용합니다 — 예: SHUNT_SERVER__BIND=0.0.0.0:3001.

기본값이 이미 모든 프로바이더를 정의하므로, shunt.toml에는 변경하려는 부분만 있으면 됩니다. shunt.toml.example에서 시작하세요.

주석이 달린 예시

[server]
bind = "127.0.0.1:3001"        # shunt가 리슨하는 주소
default_provider = "anthropic" # 라우트가 없는 모든 모델의 프로바이더 (패스스루)

# 각 프로바이더는 [providers.<name>] 테이블입니다.
[providers.anthropic]
kind = "anthropic"             # Claude Code 본인의 자격 증명을 변경 없이 전달
base_url = "https://api.anthropic.com"

[providers.openai]
kind = "responses"             # Anthropic Messages -> OpenAI Responses 변환
base_url = "https://api.openai.com/v1"
auth = "api_key"
api_key_env = "OPENAI_API_KEY" # OpenAI 키를 읽어오는 env 변수
# effort = "high"              # 이 프로바이더의 선택적 기본 추론 노력

[providers.codex]
kind = "responses"
base_url = "https://chatgpt.com/backend-api"
auth = "chatgpt_oauth"         # ~/.codex/auth.json 재사용
# effort = "high"

# --- 라우팅: 요청의 `model` id가 프로바이더를 선택하는 방식 ---

# 일치하는 [models.upstream_model] 항목이 먼저 적용됩니다. [[routes]]는 그다음 확인하는 레거시 정확 일치 형식입니다.
[[routes]]
model = "gpt-5.6-sol"
provider = "codex"
# upstream_model = "gpt-5.6-sol"
# effort = "high"

# 그다음 프리픽스 일치.
[[route_prefixes]]
prefix = "gpt-"
provider = "openai"

# 선택: 디스커버리를 통해 /model 선택기에 Claude 이름 별칭을 노출.
# id는 반드시 "claude" 또는 "anthropic"으로 시작해야 하며, 그렇지 않으면 Claude Code가 무시합니다.
# [[models]]
# id = "claude-opus-via-codex"
# display_name = "Opus (via Codex)"

라우팅 우선순위

요청의 model id와 일치하는 [models.upstream_model] 항목.
요청의 model id에 대한 정확한 [[routes]] 일치.
[[route_prefixes]] 프리픽스 일치.
server.default_provider — 기본값은 anthropic이므로, 일치하지 않는 모델은 변경 없이 Anthropic으로 흘러갑니다.

라우트는 전달되는 모델 id(upstream_model)와 추론 노력(effort)을 모델별로 오버라이드할 수 있습니다.

부분 오버라이드

구성 맵은 깊은 병합(deep-merge)되므로, 내장 프로바이더를 부분 오버라이드해도 나머지 기본값은 유지됩니다:

# codex의 기본 effort만 올립니다; 나머지는 모두 내장 값 그대로 유지됩니다.
[providers.codex]
effort = "high"

검증

shunt check
# -> "config ok"를 출력하거나, 구체적인 오류(잘못된 bind 주소, 알 수 없는 프로바이더 등)를 출력

모든 키는 구성 레퍼런스를, 새 백엔드 추가는 프로바이더를 참고하세요.