# Claude Code CLI — Configuration with OmniRoute (한국어) 🌐 **Languages:** 🇺🇸 [English](../../../../guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇹 [am](../../../am/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇦 [ar](../../../ar/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇿 [az](../../../az/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇬 [bg](../../../bg/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇩 [bn](../../../bn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇦 [bs](../../../bs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇿 [cs](../../../cs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇰 [da](../../../da/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇪 [de](../../../de/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇷 [el](../../../el/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇸 [es](../../../es/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇪 [et](../../../et/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇷 [fa](../../../fa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇮 [fi](../../../fi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇷 [fr](../../../fr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇪 [ga](../../../ga/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [gu](../../../gu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ha](../../../ha/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇱 [he](../../../he/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [hi](../../../hi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇷 [hr](../../../hr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇺 [hu](../../../hu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇲 [hy](../../../hy/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇩 [id](../../../id/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ig](../../../ig/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇹 [it](../../../it/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇯🇵 [ja](../../../ja/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇪 [ka](../../../ka/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇭 [km](../../../km/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [kn](../../../kn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇹 [lt](../../../lt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇻 [lv](../../../lv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ml](../../../ml/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [mr](../../../mr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇾 [ms](../../../ms/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇹 [mt](../../../mt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇲 [my](../../../my/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇵 [ne](../../../ne/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇱 [nl](../../../nl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇴 [no](../../../no/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [or](../../../or/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [pa](../../../pa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇭 [phi](../../../phi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇱 [pl](../../../pl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇹 [pt](../../../pt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇴 [ro](../../../ro/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇺 [ru](../../../ru/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇰 [si](../../../si/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇰 [sk](../../../sk/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇮 [sl](../../../sl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇸 [sr](../../../sr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇪 [sv](../../../sv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇪 [sw](../../../sw/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ta](../../../ta/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [te](../../../te/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇭 [th](../../../th/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇷 [tr](../../../tr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇰 [ur](../../../ur/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇿 [uz](../../../uz/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇻🇳 [vi](../../../vi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [yo](../../../yo/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CLAUDE-CODE-CONFIGURATION.md) --- **Claude Code** CLI(`claude`)가 로컬 또는 원격 VPS의 OmniRoute를 가리키도록 설정하고, Codex 설정과 동일하게 모델별 프로필을 사용하세요. --- ## 빠른 시작 ```bash # 로컬 OmniRoute를 대상으로 Claude Code 실행(활성 컨텍스트 자동 감지) omniroute launch # 원격 OmniRoute를 대상으로 실행(`omniroute connect ` 후에는 자동으로 연결됨) omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx # 모델별 프로필을 생성한 다음 하나를 선택하여 실행 omniroute setup-claude # ~/.claude/profiles//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 ` 후 `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/` 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` 조각을 복사 버튼과 함께 표시합니다. ```jsonc { "env": { "ANTHROPIC_BASE_URL": "http://:20128", "ANTHROPIC_AUTH_TOKEN": "", "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/.config.toml`과 달리 **네이티브 프로필 파일이 없습니다**. 일반적으로 사용하는 메커니즘은 `CLAUDE_CONFIG_DIR`입니다. 프로필마다 별도의 구성 디렉터리를 사용하며, 각 디렉터리는 자체 `settings.json`, 자격 증명, 기록 및 캐시를 가집니다. `omniroute setup-claude`는 실시간 `/v1/models` 카탈로그를 가져와 모델별 프로필을 `~/.claude/profiles//settings.json`에 작성하며, **`setup-codex`와 동일한 이름**(`glm52`, `kimi-k27`, `deepseek-pro`, …)을 재사용합니다. ```jsonc // ~/.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 `으로 실행하거나(활성 컨텍스트의 `ANTHROPIC_AUTH_TOKEN`을 삽입함), 직접 `ANTHROPIC_AUTH_TOKEN`을 내보낸 후 `CLAUDE_CONFIG_DIR=~/.claude/profiles/ claude`를 실행하세요. **모델 검색 후 자동 동기화(선택 사항).** OmniRoute는 공급자 모델 동기화로 실시간 카탈로그가 변경될 때마다 동일한 `~/.claude/profiles//settings.json` 파일을 자동으로 다시 생성할 수 있습니다. 따라서 명령을 다시 실행하지 않아도 신규 모델이나 이름이 변경된 모델의 프로필이 생성됩니다. 이 기능은 **기본적으로 꺼져 있습니다**. **CLI Code 대시보드**에서 활성화하거나("CLI profile auto-sync" → Claude Code), `OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true`를 설정하세요. 기본적으로 활성화된 `CLI_ALLOW_CONFIG_WRITES` 설정도 따릅니다. 활성화하면 프로필 파일만 작성하며, 활성/기본 Claude 구성, 인증 또는 `~/.claude/settings.json`은 절대 변경하지 않습니다. ### 프로필 생성 및 사용 ```bash # 로컬 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 모델에 매핑하세요. ```bash 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 `를 실행한 후([원격 모드](./REMOTE-MODE.md) 참조), `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=`로 강제 지정하세요(프로필도 이 방식을 사용합니다). **`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`(기본값은 꺼짐, [환경](../reference/ENVIRONMENT.md) 참조)를 사용하면 접두사가 없는 `claude-*` ID가 대신 Claude Code로 라우팅됩니다. 명시적인 제공자 접두사가 항상 우선합니다. **인증 오류** — 프로필에는 토큰이 저장되지 않습니다. `omniroute launch --profile`을 사용하거나(토큰 주입) `ANTHROPIC_AUTH_TOKEN`을 내보내세요. **프로필이 격리되지 않음** — 각 프로필은 서로 다른 `CLAUDE_CONFIG_DIR`을 사용합니다. 세션 내에서 `echo $CLAUDE_CONFIG_DIR`을 실행해 `~/.claude/profiles/`을 가리키는지 확인하세요.