Настройка API-роутера Claude Code: Base URL, модели и журналы использования

Настройка API-роутера Claude Code — это не то же самое, что изменение базового URL-адреса OpenAI SDK. Claude Code использует формат шлюза Anthropic Messages, поэтому важно проверить корневой путь роутера, заголовок с учетными данными, имя модели, которое будет отправлять Claude Code, и записи об использовании, подтверждающие, что запросы поступают на правильный аккаунт.

Это руководство представляет ориентированную на продакшн настройку Flatkey для разработчиков, команд по продуктам ИИ, создателей автоматизации, инженеров платформ, финансовых операторов и специалистов по закупкам. Оно охватывает базовый URL, предварительную проверку с одним токеном, имена моделей, обнаружение моделей шлюзом, журналы использования и режимы сбоев, прежде чем вы переведете повседневную работу по написанию кода на API-роутер Claude Code.

Примечание об источнике: эта информация была проверена 29 июня 2026 года по официальной документации по LLM-шлюзам Claude Code, руководству по подключению к шлюзу Claude Code, справочнику по протоколу шлюза, документации по конфигурации моделей, документации по мониторингу и текущим общедоступным страницам Flatkey. Для дымового теста Claude Code в реальном времени не использовался ключ Flatkey, привязанный к конкретному аккаунту, поэтому приведенные ниже фрагменты кода являются шаблонами для запуска с вашим собственным ключом и одобренной моделью.

Краткий ответ: настройка API-роутера Claude Code

Для настройки API-роутера Claude Code с Flatkey сконфигурируйте Claude Code, указав корневой путь роутера Flatkey для Claude Code, ключ Flatkey и точное имя модели Claude, которую может вызывать ваш аккаунт. Затем протестируйте эндпоинт Anthropic Messages, прежде чем начинать длительную сессию кодирования.

Это краткая версия. Остальная часть этого руководства по API-роутеру Claude Code превращает эти поля в воспроизводимый план настройки.

Что подтверждает официальная документация по шлюзу Claude Code

Официальный обзор шлюза Claude Code определяет LLM-шлюз как прокси между Claude Code и провайдером модели. Claude Code отправляет API-трафик на шлюз, а шлюз перенаправляет его с учетными данными провайдера, контролируемыми организацией. На той же странице перечислены преимущества шлюза, такие как централизованные учетные данные, отслеживание использования, контроль затрат, журналы аудита и переключение между провайдерами.

Правило для базового URL является специфичным. Обычно Claude Code отправляет запросы в API Anthropic, но установка ANTHROPIC_BASE_URL вместо этого направляет эти запросы на шлюз. Затем руководство по подключению проверяет маршрут, отправляя POST-запрос на $ANTHROPIC_BASE_URL/v1/messages с заголовком anthropic-version: 2023-06-01.

Справочник по протоколу шлюза добавляет детали со стороны оператора. Для формата Anthropic Messages шлюз, выбранный с помощью ANTHROPIC_BASE_URL, должен обслуживать путь /v1/messages и, опционально, /v1/messages/count_tokens. Там также говорится, что ответы от модели должны передаваться в потоковом режиме, поскольку Claude Code обрабатывает серверные события (server-sent events) по мере их поступления.

Для API-роутера Claude Code это означает, что вы должны проверять путь Anthropic Messages, а не только совместимый с OpenAI путь для завершения чатов. Маршрут OpenAI может работать для других инструментов, в то время как Claude Code все равно будет выдавать ошибку, если отсутствуют /v1/messages, потоковая передача или обязательные заголовки Anthropic.

Значения Flatkey, проверенные для этой настройки

На главной странице Flatkey, проверенной 29 июня 2026 года, есть заголовок One API gateway for production AI teams и мета-описание, в котором говорится, что Flatkey объединяет доступ к моделям, маршрутизацию, биллинг, аналитику использования и операционный контроль. На той же главной странице по-прежнему показаны примеры в стиле OpenAI с использованием https://console.flatkey.ai/v1 и /v1/chat/completions, которые полезны для инструментов, совместимых с OpenAI, но не являются шаблоном базового URL для Claude Code.

На текущей странице примеров использования Flatkey Claude Code говорится, что Claude Code настраивается с помощью https://router.flatkey.ai и API-ключа Flatkey. Там также рекомендуется создать или скопировать ключ на странице https://console.flatkey.ai/keys перед запуском установщика. Используйте этот корневой URL-адрес роутера, специфичный для Claude Code, для ручной настройки, описанной ниже, если в вашей учетной записи Flatkey не указано более новое значение.

На странице цен Flatkey, проверенной 29 июня 2026 года, опубликованы цены с серверным рендерингом для 635 моделей ИИ от 23 провайдеров. Карта конечных точек включает /v1/messages, /v1/chat/completions, /v1/responses, /v1/images/generations, /v1/video/generations и /v1beta/models/{model}:generateContent. В этой статье это рассматривается как устаревшее публичное подтверждение охвата конечных точек, а не как гарантия того, что каждая учетная запись может вызывать каждую модель.

Пошаговая настройка с Flatkey

1. Создайте или выберите ключ Flatkey. Используйте ключ, принадлежащий нужному человеку, команде или среде. Не допускайте его попадания в скриншоты, промпты, репозитории и комментарии к задачам.
2. Начните с экспорта в оболочке. Не сохраняйте настройки до тех пор, пока не сработает предварительная проверка с одним токеном.
3. Используйте корневой URL-адрес роутера Claude Code. Для текущей страницы Flatkey Claude Code это значение — https://router.flatkey.ai.
4. Выберите переменную для учетных данных. Используйте ANTHROPIC_AUTH_TOKEN, когда ключ должен отправляться как Authorization: Bearer. Используйте ANTHROPIC_API_KEY только тогда, когда шлюз ожидает x-api-key.
5. Установите модель для первого теста. Используйте идентификатор актуальной модели Claude, включенной для вашей учетной записи Flatkey. Если модель не видна в средстве выбора Claude Code, используйте обнаружение шлюза или добавьте пользовательскую модель после того, как предварительная проверка сработает.
6. Выполните предварительную проверку с помощью curl. Запрос с одним токеном отделяет маршрутизацию Flatkey от состояния пользовательского интерфейса Claude Code.
7. Запустите Claude Code из той же оболочки. Это позволит CLI унаследовать только что протестированные переменные.
8. Выполните /status. Убедитесь, что в строке базового URL-адреса Anthropic указан роутер Flatkey, а в строке учетных данных — имя установленной вами переменной.
9. Отправьте один небольшой промпт. Затем проверьте использование Flatkey и любую включенную вами телеметрию Claude Code.

Настройка в оболочке

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_AUTH_TOKEN="fk_replace_with_your_flatkey_key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"

Если в инструкциях вашего шлюза явно указано x-api-key, замените ANTHROPIC_AUTH_TOKEN на ANTHROPIC_API_KEY и обновите заголовок предварительной проверки. Не устанавливайте обе переменные для первого теста; смешанные источники учетных данных затрудняют выявление причин сбоев.

Постоянные настройки после успешного теста

После того как тест в оболочке пройдет успешно, вы можете поместить те же переменные в блок env файла ~/.claude/settings.json. Не помещайте учетные данные в файл .claude/settings.json проекта, который вы коммитите.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
    "ANTHROPIC_AUTH_TOKEN": "fk_replace_with_your_flatkey_key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

Предварительная проверка маршрута Messages перед запуском Claude Code

Самая быстрая проверка API-роутера Claude Code — это запрос Messages с одним токеном. Если он не удался, исправьте ключ Flatkey, базовый URL-адрес, сетевой путь или модель, прежде чем изменять настройки Claude Code.

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1,
    "messages": [
      {"role": "user", "content": "."}
    ]
  }'

JSON-ответ, который начинается с идентификатора сообщения и содержит поле контента, означает, что маршрут и учетные данные работают. В официальной документации также отмечается, что ошибка неизвестной модели все равно доказывает, что шлюз аутентифицировал запрос, прежде чем отклонить имя модели. Код 401 означает, что учетные данные были отклонены или отправлены в неверном заголовке.

Внимательно следите за итоговым URL-адресом. При ANTHROPIC_BASE_URL=https://router.flatkey.ai тест обращается к https://router.flatkey.ai/v1/messages. Если ваша команда создает /v1/v1/messages, значит, вы скопировали базовый URL-адрес клиентского SDK в поле шлюза Claude Code.

Имена моделей: псевдонимы, обнаружение и пользовательские записи

Имена моделей — вторая по распространенности причина сбоев API-роутера Claude Code. Базовый URL-адрес направляет трафик в Flatkey, но Claude Code все равно требуется значение модели для отправки в запросе.

В документации по конфигурации моделей говорится, что Claude Code поддерживает встроенные настройки моделей, такие как default, best, sonnet, opus, haiku, и варианты с длинным контекстом, например sonnet[1m] и opus[1m]. В той же документации указано, что ANTHROPIC_MODEL применяется только к сессии, которую вы запускаете с этой переменной, в то время как /model может сохранить интерактивный выбор для последующих сессий.

Для маршрута Flatkey безопаснее всего начинать с полного идентификатора модели Claude, который Flatkey включил для вашего ключа, а затем решать, отображать ли его в средстве выбора. Не следует предполагать, что общее имя семейства, маркетинговое название или заголовок строки провайдера будут приняты в качестве идентификатора модели в запросе.

Обнаружение моделей шлюза

Claude Code может запрашивать конечную точку /v1/models шлюза при запуске, когда ANTHROPIC_BASE_URL указывает на шлюз Anthropic Messages и включено обнаружение. В документации протокола указано, что запрос — это GET /v1/models?limit=1000 с 3-секундным тайм-аутом, и Claude Code считывает из ответа id и необязательный display_name.

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude --debug

Обнаружение по умолчанию отключено, чтобы общий ключ не предоставлял доступ ко всем доступным моделям каждому пользователю. Если обнаружение не удается, Claude Code переключается на кэшированный или встроенный селектор. Если ваша учетная запись Flatkey обслуживает модель под псевдонимом, который не отображается при обнаружении, добавьте вместо этого пользовательскую опцию.

Пользовательская опция модели

export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-sonnet-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet via Flatkey"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Claude model routed through the Flatkey API router"

Пользовательская опция модели пропускает проверку на стороне клиента для этого идентификатора модели, что полезно для контролируемого пилотного проекта. Это не заменяет предварительный запрос. Если активен список разрешенных для организации, включите туда и пользовательский идентификатор модели.

Журналы использования: что проверять после первого запроса

Надежная настройка API-роутера Claude Code завершается подтверждением использования, а не просто успешным ответом. В публичном позиционировании Flatkey говорится, что он объединяет биллинг, аналитику использования и операционный контроль; документация по шлюзу Claude Code также представляет отслеживание использования и контроль затрат как преимущества шлюза. Используйте оба уровня целенаправленно.

Для телеметрии Claude Code включайте OpenTelemetry только с осознанной настройкой конфиденциальности. В документации по мониторингу говорится, что текст запросов по умолчанию редактируется, в то время как такие настройки, как OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 и OTEL_LOG_RAW_API_BODIES, добавляют конфиденциальные данные. Исключите ведение журналов необработанных тел запросов из стандартной настройки для разработчиков, если это не одобрено вашей службой безопасности.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Используйте OTEL_RESOURCE_ATTRIBUTES для полей с низкой кардинальностью, таких как отдел, идентификатор команды или центр затрат. Избегайте использования введенных пользователем названий проектов или идентификаторов тикетов в качестве меток, если ваша система наблюдаемости не может справиться с кардинальностью и последствиями для конфиденциальности.

Режимы сбоев, которые следует отлаживать в первую очередь

Контрольный список для производственной среды для команд

Прежде чем стандартизировать API-роутер Claude Code для всей команды, зафиксируйте операционные данные, которые понадобятся при будущем инциденте или финансовой проверке.

Внутренний путь миграции

Если Flatkey становится общим маршрутом для нескольких инструментов разработки, поддерживайте настройку Claude Code в соответствии с остальным кластером интеграции. Используйте руководство по миграции API, совместимого с OpenAI, для шаблонов базовых URL SDK, но помните, что Claude Code использует маршрут Anthropic Messages вместо /v1/chat/completions.

Для настройки десктопного клиента сравните с руководством по настройке API Cherry Studio. Для шаблонов маршрутизации на машине разработчика, смежных с Claude Code, см. настройку cc-switch для Claude Code. После того как первый промпт сработает, ознакомьтесь с ценами на модели Flatkey, а затем получите ключ для любой дополнительной среды, которой требуется отдельная граница учетных данных.

Часто задаваемые вопросы

Какой базовый URL следует использовать для API-роутера Claude Code с Flatkey?

Используйте специфичный для Claude Code корневой URL роутера Flatkey, указанный для вашего аккаунта. 29 июня 2026 года на странице Flatkey, посвященной вариантам использования Claude Code, было указано, что Claude Code настраивается с помощью https://router.flatkey.ai. Предварительная проверка должна достигать ровно одного пути /v1/messages.

Следует ли использовать ANTHROPIC_AUTH_TOKEN или ANTHROPIC_API_KEY?

Используйте ANTHROPIC_AUTH_TOKEN, когда шлюз ожидает токен носителя (bearer token) в заголовке Authorization. Используйте ANTHROPIC_API_KEY, когда он ожидает x-api-key. Если вы сделали предположение и получили ошибку 401, поменяйте переменные и повторите тест.

Могу ли я использовать совместимый с OpenAI базовый URL Flatkey для Claude Code?

Не напрямую, просто скопировав поле. Инструменты, совместимые с OpenAI, часто используют базовый URL, заканчивающийся на /v1, в то время как Claude Code добавляет /v1/messages к ANTHROPIC_BASE_URL. Используйте значение роутера Flatkey для Claude Code и проверьте конечный URL.

Как добавить модели Flatkey в средство выбора моделей Claude Code?

Включите CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, когда шлюз обслуживает /v1/models, или добавьте одну строку ручного выбора с помощью ANTHROPIC_CUSTOM_MODEL_OPTION. В обоих случаях убедитесь, что точный ID модели включен для вашего ключа Flatkey.

Какие журналы использования следует проверять после настройки?

Проверьте использование Flatkey по ключу, модели, семейству конечных точек, временной метке, токенам и стоимости, где это возможно. Также используйте /status Claude Code и метрики OpenTelemetry, такие как claude_code.cost.usage и claude_code.token.usage, когда включена телеметрия организации.

Заключение

Надежная настройка API-роутера Claude Code имеет четыре подтверждающих элемента: базовый URL Claude Code от Flatkey, правильный заголовок учетных данных, протестированное имя модели и журнал использования, который могут просматривать финансовые и платформенные команды. Начните с предварительного запроса /v1/messages в один токен, подтвердите /status, а затем масштабируйте маршрут только после того, как будут задокументированы журналы и откат. Когда вы будете готовы маршрутизировать Claude Code через общий шлюз, получите ключ и сначала протестируйте самый маленький промпт.