Claude Code CLI — Configuration with OmniRoute (Русский)

Быстрый старт

# Запустить Claude Code с локальным OmniRoute (активный контекст определяется автоматически)
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  # Claude Code использует glm/glm-5.2 через OmniRoute

---

Как Claude Code подключается к шлюзу

Claude Code взаимодействует с Anthropic Messages API и направляется на пользовательскую конечную точку с помощью переменных окружения (у него нет флага --base-url):

Переменная	Назначение
ANTHROPIC_BASE_URL	Корневой URL шлюза (Claude Code добавляет /v1/messages). Без суффикса /v1.
ANTHROPIC_AUTH_TOKEN	Отправляется как Authorization: Bearer … — используйте токен доступа / API-ключ OmniRoute
ANTHROPIC_API_KEY	Альтернатива: отправляется как x-api-key. Если заданы обе переменные, приоритет имеет ANTHROPIC_AUTH_TOKEN
ANTHROPIC_MODEL	Принудительно задаёт конкретную модель (переопределяет значение по умолчанию в средстве выбора /model)
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY	1 → встроенное средство выбора /model отображает модели claude*/anthropic* из /v1/models
CLAUDE_CODE_MAX_OUTPUT_TOKENS	Ограничивает количество выходных токенов на один ответ (например, 65536)
CLAUDE_CODE_AUTO_COMPACT_WINDOW	Порог токенов для автоматического сжатия

Переменные окружения считываются один раз при запуске — перезапустите Claude Code после их изменения.

omniroute launch задаёт все эти переменные за вас: определяет базовый URL и токен из активного контекста (поэтому после omniroute connect <vps> команда omniroute launch сразу работает), проверяет состояние сервера и запускает claude через exec.

---

Псевдонимы обнаружения — отображение моделей, отличных от Claude, в средстве выбора /model

Механизм обнаружения моделей шлюза в Claude Code отображает только идентификаторы, начинающиеся с claude или anthropic, поэтому при CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 встроенное средство выбора /model обычно показывает только модели Claude/Anthropic из OmniRoute — модели kimi/kimi-k2.6 или glm/glm-5.2 не отображаются, хотя маршрутизация для них работает.

OmniRoute может дублировать любую включённую модель (и комбинацию) под идентификатором claude/…, чтобы она проходила этот фильтр и отображалась в средстве выбора:

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)"
<combo "custo-otimizado"> →  claude/combo/custo-otimizado

Когда вы выбираете один из этих вариантов в Claude Code, OmniRoute удаляет обёртку claude/, восстанавливая реальный идентификатор перед маршрутизацией, — при этом подлинный идентификатор claude/<real-claude-model> (фактический OAuth-провайдер Claude) всегда остаётся без изменений.

По умолчанию эта функция отключена и управляется трёхуровневой системой настроек (наиболее конкретная имеет приоритет), поэтому обычный экземпляр OmniRoute не удваивает свой каталог для клиентов, которые не используют Claude Code:

Уровень	Где
Модель	Страница сведений о провайдере → переключатель “Expose in Claude Code” для каждой модели
Провайдер	Страница сведений о провайдере → переключатель уровня провайдера (распространяется на все его модели)
Глобальный	Settings → Feature Flags → EXPOSE_CC_DISCOVERY_ALIASES (по умолчанию отключено)

Переменная окружения EXPOSE_CC_DISCOVERY_ALIASES принудительно включает глобальный уровень и имеет приоритет над настройкой на панели управления (когда она активна, на экране Feature Flags отображается примечание “active via environment variable”). Переключатели для отдельных провайдеров и моделей дополнительно уточняют настройку — например, если глобальный уровень отключён, а провайдер Kimi включён, будут доступны только модели Kimi.

⚠️ Несоответствие размера окна для моделей, отличных от Claude. Claude Code предполагает контекстное окно размером 200K для любого нераспознанного идентификатора (он не может получить реальный размер окна из /v1/models). Для модели с большим окном (например, 256K у Kimi K2) задайте CLAUDE_CODE_AUTO_COMPACT_WINDOW меньше реального размера окна модели, чтобы автоматическое сжатие не срабатывало преждевременно. Созданные выше профили уже настраивают это отдельно для каждой модели.

---

Блок онбординга на панели управления

Карточка инструмента Claude (Панель управления → CLI Code) отображает точный фрагмент settings.json для этого экземпляра рядом с кнопкой информации о псевдониме обнаружения, а также кнопку копирования:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<ваш OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<ваш API-ключ OmniRoute>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}

Базовый URL — это адрес, определённый карточкой (включая введённое вами пользовательское переопределение) и уже нормализованный: без суффикса /v1 и без завершающей косой черты. Ключ никогда не отображается: блок содержит заполнитель, поэтому ключ не может утечь через снимок экрана или вставленный фрагмент. Замените заполнитель своим ключом.

Добавьте CLAUDE_CODE_AUTO_COMPACT_WINDOW в тот же блок env для любой модели, реальное окно контекста которой не равно 200K: Claude Code предполагает 200K для каждого неизвестного ему идентификатора, поэтому без этого автоматическое сжатие срабатывает не в тот момент (см. предупреждение в предыдущем разделе). Конструктор фрагментов также принимает это значение, поэтому вызывающая сторона, которой известен размер окна целевой модели, может указать его напрямую.

Источник: src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet (чистый конструктор, покрытый модульными тестами), отображаемый компонентом ClaudeGatewayOnboardingBlock.

---

Профили (CLAUDE_CONFIG_DIR)

В Claude Code нет встроенных файлов профилей (в отличие от ~/.codex/<name>.config.toml в Codex). Стандартный механизм — 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» → Claude Code) либо задайте OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true (также учитывается CLI_ALLOW_CONFIG_WRITES, по умолчанию включённая). Если функция включена, она записывает только файлы профилей и никогда не изменяет активную или стандартную конфигурацию Claude, данные аутентификации либо ~/.claude/settings.json.

Создание и использование профилей

# Локальный OmniRoute
omniroute setup-claude

# Удалённый VPS (встраивает URL-адрес VPS в каждый профиль)
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 распределяет запросы по уровням возможностей. При необходимости сопоставьте каждый уровень с моделью 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 (переменные окружения считываются один раз при запуске). omniroute launch сделает это за вас.

Средство выбора /model пусто / модели шлюза отсутствуют — требуется Claude Code v2.1.219+ и CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. В средстве выбора отображаются только идентификаторы моделей claude* / anthropic*; чтобы принудительно использовать любую другую модель, задайте ANTHROPIC_MODEL=<id> (именно это делают профили).

400 Ambiguous model 'claude-…' — Claude Code всегда отправляет идентификаторы моделей без префикса (например, claude-opus-4-8), поэтому, когда одновременно подключены провайдеры Claude Code (cc/…) и Claude (claude/…), идентификатор без префикса соответствует двум маршрутам, и OmniRoute отказывается выбирать автоматически. Исправить это можно одним из двух способов: явно укажите идентификатор с префиксом через ANTHROPIC_MODEL=cc/claude-opus-4-8 или включите параметр Предпочитать Claude Code для моделей Claude без префикса — с помощью переключателя на странице провайдера Claude или OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true (по умолчанию отключено; см. Переменные окружения) — тогда идентификаторы claude-* без префикса будут направляться в Claude Code. Явные префиксы провайдеров всегда имеют приоритет.

Ошибки аутентификации — профиль не содержит токен. Используйте omniroute launch --profile (эта команда внедряет токен) или экспортируйте ANTHROPIC_AUTH_TOKEN.

Профили не изолированы — каждый профиль использует отдельный CLAUDE_CONFIG_DIR; убедитесь, что внутри сеанса команда echo $CLAUDE_CONFIG_DIR указывает на ~/.claude/profiles/<name>.

---

Исходный код OmniRoute (a58000c7685f)