Claude Code CLI — Configuration with OmniRoute (한국어)

빠른 시작

# 로컬 OmniRoute를 대상으로 Claude Code 실행(활성 컨텍스트 자동 감지)
omniroute launch

# 원격 OmniRoute를 대상으로 실행(`omniroute connect <host>` 후에는 자동으로 연결됨)
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# 모델별 프로필을 생성한 다음 하나를 선택하여 실행
omniroute setup-claude            # ~/.claude/profiles/<name>/settings.json에 기록
omniroute launch --profile glm52  # OmniRoute를 통해 glm/glm-5.2를 사용하는 Claude Code

---

Claude Code가 게이트웨이에 연결되는 방식

Claude Code는 Anthropic Messages API를 사용하며 환경 변수를 통해 사용자 지정 엔드포인트를 가리킵니다(--base-url 플래그는 지원하지 않음).

변수	용도
ANTHROPIC_BASE_URL	게이트웨이 루트 URL(Claude Code가 /v1/messages를 추가). /v1 접미사를 포함하지 마세요.
ANTHROPIC_AUTH_TOKEN	Authorization: Bearer …로 전송 — OmniRoute 액세스 토큰/API 키를 사용
ANTHROPIC_API_KEY	대안: x-api-key로 전송. 둘 다 설정된 경우 ANTHROPIC_AUTH_TOKEN이 우선
ANTHROPIC_MODEL	특정 모델 강제 지정(/model 선택기의 기본값 재정의)
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY	1 → 기본 /model 선택기에 /v1/models의 claude*/anthropic* 모델 표시
CLAUDE_CODE_MAX_OUTPUT_TOKENS	응답당 출력 토큰 수 제한(예: 65536)
CLAUDE_CODE_AUTO_COMPACT_WINDOW	자동 압축을 위한 토큰 임계값

환경 변수는 시작 시 한 번만 읽힙니다. 변경한 후 Claude Code를 다시 시작하세요.

omniroute launch는 이러한 변수를 모두 자동으로 설정합니다. 활성 컨텍스트에서 기본 URL과 토큰을 확인하므로 omniroute connect <vps> 후 omniroute launch를 실행하면 바로 작동하며, 서버 상태를 확인한 다음 claude를 실행합니다.

---

검색 별칭 — Claude가 아닌 모델을 /model 선택기에 표시

Claude Code의 게이트웨이 모델 검색은 ID가 claude 또는 anthropic으로 시작하는 모델만 나열합니다. 따라서 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1을 설정해도 기본 /model 선택기에는 일반적으로 OmniRoute의 Claude/Anthropic 모델만 표시됩니다. kimi/kimi-k2.6 또는 glm/glm-5.2는 정상적으로 라우팅되더라도 표시되지 않습니다.

OmniRoute는 활성화된 모든 모델과 조합을 claude/… ID로 미러링할 수 있으므로, 해당 필터를 통과해 선택기에 표시됩니다.

kimi/kimi-k2.6            →  claude/kimi/kimi-k2.6      "Kimi K2.6 (OmniRoute)"
glm/glm-5.2              →  claude/glm/glm-5.2         "GLM 5.2 (OmniRoute)"
<조합 "custo-otimizado"> →  claude/combo/custo-otimizado

Claude Code에서 이러한 항목 중 하나를 선택하면 OmniRoute는 라우팅하기 전에 claude/ 래퍼를 제거해 실제 ID로 되돌립니다. 실제 Claude OAuth 공급자의 진짜 claude/<real-claude-model> ID는 항상 그대로 유지됩니다.

이 기능은 기본적으로 꺼져 있으며, 3단계 게이트로 제어됩니다. 가장 구체적인 설정이 우선하므로, Claude Code를 사용하지 않는 클라이언트에서는 일반 OmniRoute가 카탈로그를 중복 표시하지 않습니다.

수준	위치
모델	공급자 상세 페이지 → 모델별 “Claude Code에 노출” 토글
공급자	공급자 상세 페이지 → 공급자 수준 토글(해당 공급자의 모든 모델에 적용)
전역	설정 → 기능 플래그 → EXPOSE_CC_DISCOVERY_ALIASES(기본적으로 꺼짐)

EXPOSE_CC_DISCOVERY_ALIASES 환경 변수는 전역 수준을 강제로 활성화하며 대시보드 재정의보다 우선합니다. 이 환경 변수가 적용되면 기능 플래그 화면에 “환경 변수를 통해 활성화됨”이라는 메모가 표시됩니다. 공급자별 및 모델별 토글을 사용해 적용 범위를 더 세부적으로 조정할 수 있습니다. 예를 들어 전역 설정을 끄고 Kimi 공급자만 켜면 Kimi 모델만 노출됩니다.

⚠️ Claude가 아닌 모델에서의 윈도 불일치. Claude Code는 인식하지 못하는 모든 ID에 대해 200K 컨텍스트 윈도를 가정합니다(/v1/models에서 실제 윈도 크기를 읽을 수 없음). 더 큰 윈도를 가진 모델(예: Kimi K2의 256K)의 경우, 자동 압축이 너무 일찍 실행되지 않도록 CLAUDE_CODE_AUTO_COMPACT_WINDOW를 모델의 실제 윈도보다 작은 값으로 설정하세요. 위에서 생성한 프로필에는 이미 모델별로 이 설정이 적용되어 있습니다.

---

대시보드의 온보딩 블록

Claude 도구 카드(Dashboard → CLI Code)는 검색 별칭 정보 버튼 옆에 이 인스턴스에 맞는 정확한 settings.json 조각을 복사 버튼과 함께 표시합니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}

기본 URL은 카드에서 확인된 URL이며(직접 입력한 사용자 지정 재정의 포함), 이미 정규화되어 있습니다. 즉, /v1 접미사와 후행 슬래시가 없습니다. 키는 절대 표시되지 않습니다. 이 블록은 자리표시자를 제공하므로 스크린샷이나 붙여 넣은 코드 조각을 통해 키가 유출될 수 없습니다. 자리표시자를 자신의 키로 교체하세요.

실제 컨텍스트 창이 200K가 아닌 모델의 경우 동일한 env 블록 아래에 CLAUDE_CODE_AUTO_COMPACT_WINDOW를 추가하세요. Claude Code는 인식하지 못하는 모든 id의 컨텍스트 창을 200K로 가정하므로, 그렇지 않으면 자동 압축이 잘못된 시점에 실행됩니다(이전 섹션의 경고 참조). 코드 조각 빌더도 이 값을 허용하므로, 대상 모델의 컨텍스트 창을 아는 호출자는 이를 직접 출력할 수 있습니다.

소스: src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet(ClaudeGatewayOnboardingBlock에서 렌더링되는 순수 빌더이며 단위 테스트 완료).

---

프로필(CLAUDE_CONFIG_DIR)

Claude Code에는 Codex의 ~/.codex/<name>.config.toml과 달리 네이티브 프로필 파일이 없습니다. 일반적으로 사용하는 메커니즘은 CLAUDE_CONFIG_DIR입니다. 프로필마다 별도의 구성 디렉터리를 사용하며, 각 디렉터리는 자체 settings.json, 자격 증명, 기록 및 캐시를 가집니다.

omniroute setup-claude는 실시간 /v1/models 카탈로그를 가져와 모델별 프로필을 ~/.claude/profiles/<name>/settings.json에 작성하며, setup-codex와 동일한 이름(glm52, kimi-k27, deepseek-pro, …)을 재사용합니다.

~/.claude/profiles/glm52/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "glm/glm-5.2",
  "effortLevel": "xhigh",
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
    "ANTHROPIC_MODEL": "glm/glm-5.2",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  },
}

인증 토큰은 프로필에 절대 기록되지 않습니다. omniroute launch --profile <name>으로 실행하거나(활성 컨텍스트의 ANTHROPIC_AUTH_TOKEN을 삽입함), 직접 ANTHROPIC_AUTH_TOKEN을 내보낸 후 CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude를 실행하세요.

모델 검색 후 자동 동기화(선택 사항). OmniRoute는 공급자 모델 동기화로 실시간 카탈로그가 변경될 때마다 동일한 ~/.claude/profiles/<name>/settings.json 파일을 자동으로 다시 생성할 수 있습니다. 따라서 명령을 다시 실행하지 않아도 신규 모델이나 이름이 변경된 모델의 프로필이 생성됩니다. 이 기능은 기본적으로 꺼져 있습니다. CLI Code 대시보드에서 활성화하거나(“CLI profile auto-sync” → Claude Code), OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true를 설정하세요. 기본적으로 활성화된 CLI_ALLOW_CONFIG_WRITES 설정도 따릅니다. 활성화하면 프로필 파일만 작성하며, 활성/기본 Claude 구성, 인증 또는 ~/.claude/settings.json은 절대 변경하지 않습니다.

프로필 생성 및 사용

# 로컬 OmniRoute
omniroute setup-claude

# 원격 VPS(VPS URL을 모든 프로필에 포함)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# 일부 공급자만
omniroute setup-claude --only glm,kimi

# 파일을 작성하지 않고 미리 보기
omniroute setup-claude --dry-run

# 프로필 실행
omniroute launch --profile kimi-k27

---

모델 티어(선택 사항)

Claude Code는 요청을 기능 티어별로 라우팅합니다. 티어마다 서로 다른 제공자를 사용하려면 env / 설정에서 각 티어를 OmniRoute 모델에 매핑하세요.

export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"

그렇지 않으면 단일 ANTHROPIC_MODEL(프로필에서 설정하는 값)이 모든 요청에 사용됩니다.

---

원격 모드

omniroute connect <host>를 실행한 후(원격 모드 참조), omniroute launch와 omniroute setup-claude는 자동으로 해당 원격 서버를 대상으로 하고 범위가 지정된 액세스 토큰을 사용하므로 추가 플래그가 필요하지 않습니다. 호출별로 재정의하려면 --remote / --api-key를 사용하세요.

---

문제 해결

Claude Code가 게이트웨이를 무시함 — ANTHROPIC_BASE_URL에 /v1이 포함되어 있지 않은지 확인하고 claude를 다시 시작하세요(env는 시작 시 한 번만 읽습니다). omniroute launch는 이 작업을 자동으로 처리합니다.

/model 선택기가 비어 있거나 게이트웨이 모델이 누락됨 — Claude Code v2.1.219+ 및 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1이 필요합니다. claude* / anthropic* 모델 ID만 선택기에 표시됩니다. 다른 모델은 ANTHROPIC_MODEL=<id>로 강제 지정하세요(프로필도 이 방식을 사용합니다).

400 Ambiguous model 'claude-…' — Claude Code는 항상 접두사가 없는 모델 ID(예: claude-opus-4-8)를 전송하므로, Claude Code(cc/…)와 Claude(claude/…) 제공자가 모두 연결되어 있으면 접두사가 없는 ID가 두 라우트와 일치하여 OmniRoute가 임의로 선택하지 않습니다. 다음 방법 중 하나로 해결하세요. ANTHROPIC_MODEL=cc/claude-opus-4-8로 접두사가 있는 ID를 고정하거나, 접두사가 없는 Claude 모델에 Claude Code 우선 적용을 활성화하세요. Claude 제공자 페이지의 토글 또는 OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true(기본값은 꺼짐, 환경 참조)를 사용하면 접두사가 없는 claude-* ID가 대신 Claude Code로 라우팅됩니다. 명시적인 제공자 접두사가 항상 우선합니다.

인증 오류 — 프로필에는 토큰이 저장되지 않습니다. omniroute launch --profile을 사용하거나(토큰 주입) ANTHROPIC_AUTH_TOKEN을 내보내세요.

프로필이 격리되지 않음 — 각 프로필은 서로 다른 CLAUDE_CONFIG_DIR을 사용합니다. 세션 내에서 echo $CLAUDE_CONFIG_DIR을 실행해 ~/.claude/profiles/<name>을 가리키는지 확인하세요.

---

OmniRoute 소스 코드 (a58000c7685f)