Claude Code Router 3.1.1: установка, маршрутизация и разбор ошибок

Вы хотите подключить Claude Code к DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM или другому совместимому Endpoint, но найденная инструкция всё ещё предлагает править config.json и запускать ccr code. Либо интерфейс открывается, а шлюз на 127.0.0.1:3456 так и не работает. Ниже — порядок действий для актуальной версии 3.1.1: установка, Provider, маршруты, профиль Claude Code и диагностика каждого типового сбоя.

Сначала проверьте версию: в 3.1.1 основной конфиг больше не ведут вручную в config.json

Провайдеры, маршруты и Agent Profiles в текущей версии настраиваются через Web UI. На 26 сентября 2026 года тег latest в npm указывает на 3.1.1. Основная конфигурация хранится в config.sqlite, а gateway.config.json генерируется для работающего шлюза — это следует из метаданных npm и текущего README проекта.

Отсюда два важных вывода. В актуальной CLI-документации агент запускается командой ccr <profile-name-or-id>; команды ccr code в ней нет. А gateway.config.json — не файл, который следует поддерживать вручную. Если инструкция требует config.json или ccr code, сначала выясните, для какой версии CCR она написана: несовместимую команду не стоит принимать за проблему с PATH.

До установки подготовьте Node.js, провайдера и сам Claude Code

Нужны Node.js 22 или новее, доступ к upstream-провайдеру и установленный локально Claude Code. CCR маршрутизирует запросы, но не устанавливает Claude Code и не превращает API-доступ в подписку Claude.ai или Claude Max.

Проверьте Node.js:

node --version

Если основная версия ниже 22, сначала обновите Node.js. В качестве upstream можно выбрать готовый пресет OpenRouter, DeepSeek, Gemini, Moonshot/Kimi или Z.AI либо добавить пользовательский OpenAI-compatible или Anthropic-compatible Endpoint.

Установите npm-пакет и сразу проверьте команду ccr

Сначала убедитесь, что CLI запускается, и только потом переходите к Provider. Так вы не смешаете ошибку установки с ошибкой маршрута.

npm install -g @musistudio/claude-code-router
ccr --help

Обновление и удаление:

npm install -g @musistudio/claude-code-router@latest
npm uninstall -g @musistudio/claude-code-router

Удаление npm-пакета не стирает локальную конфигурацию и базы данных. На macOS/Linux каталог данных — ~/.claude-code-router, на Windows — %APPDATA%\claude-code-router.

Настраивайте в порядке Provider → Check Connection → Client Key → Routing → Server → Profile → сквозная проверка

Сначала добейтесь работы одного маршрута по умолчанию. Если одновременно добавить несколько провайдеров, условия, rewrites, retries и fallback, ошибки 401, неверный Model ID и несовместимый протокол будут выглядеть как одна проблема.

Откройте панель управления:

ccr ui

По умолчанию UI работает на http://127.0.0.1:3458, а модельный шлюз — на http://127.0.0.1:3456. Используйте аутентифицированный URL, который CCR вывел или открыл сам. Если 3458 занят, программа может выбрать следующий свободный порт и показать фактический адрес.

1. Добавьте upstream в Providers

Готовый пресет проще; custom endpoint нужен, когда подходящего пресета нет. В Providers → Add Provider выберите сервис, укажите его собственный API Key, правильный протокол и доступные вашему аккаунту Model ID.

Не определяйте протокол по названию модели. Anthropic Messages, OpenAI Chat/Responses и Gemini используют разные форматы запросов. Base URL, протокол и Model ID должны совпадать с текущей документацией upstream-сервиса.

После сохранения Provider нажмите Check Connection. Это проверка только upstream-настройки: она не подтверждает весь путь Claude Code → CCR gateway → Routing → Provider.

2. Создайте CCR client key в API Keys

CCR client key и management token — разные секреты. Management token защищает Web UI и RPC API, а client key авторизует запросы Claude Code к шлюзу. URL с параметром ccr_web_token нужно считать паролем: не вставляйте его в логи, тикеты или сообщения.

3. Начните с маршрута по умолчанию

В маршруте по умолчанию укажите один Provider, прошедший Check Connection, и одну его модель. Сохраните маршрут, но пока не отправляйте запрос из Claude Code: сначала запустите gateway и создайте Agent Profile.

После успешного сквозного запроса из шага 6 добавляйте в Routing условия, retries, переписывание запросов и упорядоченный fallback. Меняйте по одному элементу и проверяйте снова. Fallback-модель должна поддерживать нужные инструменты, контекст и протокол; одинаковый формат чата ещё не делает модели взаимозаменяемыми.

4. Запустите шлюз в Server

Открытый UI не означает, что шлюз на 3456 готов принимать запросы. В разделе Server запустите gateway и запишите клиентский адрес из интерфейса. По умолчанию это http://127.0.0.1:3456, но используйте фактический URL, показанный CCR. При ошибке старта переключитесь в foreground-режим:

ccr serve

Вывод в терминале помогает отличить занятый порт от незаполненного Provider, отсутствующей модели или проблемы с правами на локальные файлы.

5. Создайте и включите Agent Profile для Claude Code

Актуальный CLI запускает Claude Code через включённый Agent Profile. В Agent Profiles создайте профиль Claude Code, выберите модель из маршрута по умолчанию у Provider, прошедшего Check Connection, сохраните и включите профиль. В режиме CCR Claude Code подключается к CCR gateway из раздела Server (по умолчанию http://127.0.0.1:3456), а не к URL upstream-провайдера. Имя задаётся произвольно, например Claude - Review.

Запуск по имени или ID:

ccr "Claude - Review"

Аргументы самого Claude Code помещайте после --, чтобы CCR не принял их за свои параметры:

ccr "Claude - Review" cli -- --model sonnet

Замените Claude - Review на фактическое имя или ID вашего профиля.

6. Отправьте запрос из Claude Code и проверьте Logs

Только теперь выполняется настоящая сквозная проверка. В запущенном Profile отправьте из Claude Code простой запрос, затем убедитесь в Logs, что выбраны ожидаемые Provider и модель, а статус успешный.

Check Connection у Provider проверяет лишь upstream-соединение. Реальный запрос дополнительно проверяет CCR client key, gateway, Routing, Agent Profile и вызов модели.

Чем отличаются ccr start, ui, serve и stop

Для обычной работы подходят ccr ui и ccr start, для диагностики — ccr serve.

Команда	Когда использовать	Что происходит
ccr start	Фоновая постоянная работа	Запускает detached-сервис управления и gateway, затем печатает аутентифицированный URL
ccr ui	Настройка на локальном компьютере	Повторно использует или запускает фоновый сервис и открывает UI
ccr serve	Диагностика или process supervisor	Работает в foreground и оставляет видимыми ошибки запуска и запросов; ccr web — alias
ccr stop	Перезапуск с другими параметрами	Останавливает detached-сервис, созданный через start или ui

start, ui и serve принимают --host, --port, --open/--no-open и --gateway/--no-gateway. Параметр --port задаёт предпочтительный порт панели управления, а не автоматически порт модельного шлюза 3456.

Ошибка «ccr: command not found»: проверьте Node.js и глобальный bin npm

Не переустанавливайте пакет, пока не проверили runtime и PATH. Выполните:

node --version
npm prefix -g

Node.js должен быть не ниже 22, а глобальный каталог исполняемых файлов npm — присутствовать в PATH текущего shell. После установки откройте новый терминал: некоторые оболочки кэшируют пути к командам.

Если установлено desktop-приложение, учитывайте различие: оно добавляет связанную команду ccr-app, тогда как npm-пакет устанавливает ccr. Наличие ccr-app не подтверждает корректную установку npm CLI.

Шлюз не слушает 127.0.0.1:3456: сначала найдите владельца порта

Нужно различить неудачный старт gateway и конфликт порта. Работающий UI на 3458 ничего не говорит о состоянии 3456.

На macOS/Linux:

lsof -nP -iTCP:3456 -sTCP:LISTEN

На Windows:

netstat -ano | findstr :3456

Если порт удерживает старый CCR или другая программа, сначала определите процесс по PID, а затем корректно остановите его. После этого запустите ccr serve, вернитесь в Server и проверьте наличие Provider, модели и client key.

Ошибки 401, model not found и неверного протокола: проверьте три соответствия

Проверяйте секреты, протокол и Model ID именно в таком порядке. Типовые ошибки — management token вместо client key, CCR client key в поле upstream-провайдера или OpenAI-compatible маршрут к Anthropic-compatible Endpoint.

Порядок проверки:

1. Claude Code подключается к CCR с CCR client key, а не с ccr_web_token.
2. В Provider сохранён собственный API Key upstream-сервиса.
3. Выбранный протокол соответствует Endpoint.
4. Model ID существует у этого провайдера и доступен вашему аккаунту.
5. В Logs фактически выбран ожидаемый Provider и модель.

Не ограничивайтесь последней ошибкой Claude Code. По Logs можно понять, сбой произошёл на авторизации клиента, выборе маршрута, авторизации upstream или уже при запросе к модели.

Профиль не найден, а фоновый сервис хранит старые параметры

Запускаются только включённые Agent Profiles. Имена сопоставляются без учёта регистра, допустимы нормализованные варианты, но при неоднозначности нужен ID. Если launcher не сгенерирован, повторно сохраните профиль в UI.

Повторно используемый фоновый процесс не применяет новые host, port или gateway options. Остановите и создайте его заново:

ccr stop
ccr start --host 127.0.0.1 --port 3458

Поэтому новая команда может завершиться без ошибки, а сервис всё равно продолжит работать со вчерашними настройками.

Прямой ANTHROPIC_BASE_URL проще, когда Endpoint всего один

Если у вас один Anthropic-compatible Endpoint, одна основная модель и не нужны условия, fallback, общие логи и несколько профилей, прямое подключение обычно короче. Установите ANTHROPIC_BASE_URL, переменную авторизации и сопоставление модели по документации провайдера — локальный gateway в такой схеме не обязателен.

CCR полезнее, если выполняется хотя бы одно условие:

• вы переключаетесь между DeepSeek, OpenRouter, Gemini, Kimi, Z.AI и custom endpoints;
• разные задачи или профили должны использовать разные модели;
• нужны retries, условия, rewrites или упорядоченный fallback;
• важно видеть фактический маршрут, статус, tokens, latency и ошибки;
• несколько клиентов должны использовать один локальный gateway.

Сценарий	Что выбрать
Один стабильный Anthropic-compatible Endpoint	Прямой ANTHROPIC_BASE_URL
Несколько провайдеров, моделей или профилей	CCR
Нужна видимость маршрута каждого запроса	CCR
Нужно максимально быстро подключить один сервис	Сначала прямое подключение, затем CCR при усложнении схемы

Пример совместимого Endpoint: BetterToken в CCR

BetterToken можно добавить как один из пользовательских Anthropic-compatible Provider, но это не единственный вариант. В CCR Providers укажите https://bettertoken.ai в поле upstream API endpoint/Base URL — это не Base URL Claude Code — и не добавляйте /v1. Явно выберите протокол Anthropic Messages, затем укажите свой BetterToken API Key и актуальный Model ID. Сохраните Provider и выполните Check Connection.

При использовании CCR Claude Code подключается к CCR gateway, показанному в Server, обычно http://127.0.0.1:3456. Запустите Agent Profile, отправьте запрос и проверьте в Logs, что он ушёл в ожидаемую модель BetterToken. Не направляйте Claude Code прямо на https://bettertoken.ai в этом режиме, иначе запрос обойдёт CCR.

Только если вы намеренно отказываетесь от CCR и подключаетесь напрямую к этому единственному Endpoint, следуйте документации BetterToken для Claude Code и задайте Base URL на macOS/Linux:

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

В PowerShell:

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

В таком прямом режиме переменная авторизации и сопоставление модели по-прежнему берутся из актуальной документации. Не подставляйте в Claude Code OpenAI-compatible Base URL https://www.bettertoken.ai/v1.

Защитите локальные секреты и правильно делайте резервную копию

Оставляйте management listener на 127.0.0.1, если удалённый доступ не нужен. Для удалённого подключения используйте firewall или private network и TLS на доверенном reverse proxy. Не публикуйте gateway во внешнюю сеть без CCR client keys.

Upstream-ключи, логи и runtime-базы находятся в локальном каталоге CCR. Не редактируйте и не копируйте config.sqlite, пока CCR пишет в него. Используйте export в UI либо остановите CCR перед файловой резервной копией.

Финальная проверка должна охватывать весь путь запроса

Успех — это не просто открывшийся UI, а нормальный ответ Claude Code через ожидаемый маршрут. Проверьте:

• node --version показывает 22 или новее;
• ccr --help выполняется;
• в Providers есть upstream, успешно прошедший Check Connection;
• в API Keys создан CCR client key;
• Server показывает запущенный gateway и его клиентский URL (по умолчанию http://127.0.0.1:3456);
• Agent Profile сохранён и включён;
• ccr <profile-name-or-id> запускает Claude Code;
• из Claude Code отправлен реальный запрос, а Logs показывает ожидаемые Provider, модель и успешный статус;
• после каждого нового route или fallback выполнена повторная проверка.

Так установка, авторизация, маршрутизация и запуск агента остаются отдельными слоями. При сбое вы исправляете конкретный слой, а не переустанавливаете CCR и не правите наугад устаревший config.json.