Развертывание LLM-шлюза для вашей организации

Разверните продукт шлюза для Claude Code: настройте его для перенаправления того, что отправляет Claude Code, выдайте учетные данные разработчика, распределите конфигурацию через управляемые параметры и проверьте развертывание.

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

Предварительные требования

Для завершения развертывания вам потребуется:

• Шлюз, развернутый на вашей инфраструктуре, обслуживающий HTTPS по точному адресу, который вы будете распределять разработчикам, а не адресу, который перенаправляет на него, и настроенный для маршрутизации имен моделей Claude к вашему поставщику
• Учетные данные поставщика для шлюза для перенаправления:
  • Для Anthropic API: ключ API из Claude Console
  • Для облачного поставщика: облачные учетные данные с доступом к моделям. См. предварительные требования на странице Amazon Bedrock, Google Cloud's Agent Platform или Microsoft Foundry
• Способ доставки файлов параметров на машины разработчиков, например MDM или управление конфигурацией
  • Если у вас его еще нет, как параметры достигают устройств сравнивает варианты

Требования к шлюзу

Какой бы продукт ни предоставлял шлюз, он должен:

• Принимать поддерживаемый формат API: один из форматов в таблице форматов API. Шаги развертывания ниже предполагают Anthropic Messages API в POST /v1/messages, который обслуживает большинство шлюзов
• Потоковая передача ответов: передавать события, отправляемые сервером, по мере их поступления, включая пинги для поддержания соединения, вместо буферизации всего ответа; потоковая передача охватывает то, что буферизация или удаленные пинги нарушают
• Маршрутизация имен моделей Claude: сопоставлять каждое имя, которое используют разработчики, с восходящей моделью. Claude Code отправляет имя модели, такое как claude-sonnet-4-6, в каждом запросе; в большинстве продуктов шлюза сопоставление представляет собой список моделей или таблицу маршрутизации в собственной конфигурации шлюза
• Перенаправлять заголовки и тело без изменений: передавать anthropic-beta, anthropic-version и тело запроса в обоих направлениях; таблица сквозной передачи функций сопоставляет каждый с функцией, которая нарушается без него
• Возвращать ошибки восходящего потока без изменений: автоматическое восстановление Claude Code соответствует формулировке ошибки, поэтому обертывание ошибок в собственный конверт шлюза нарушает его, если только сообщение конверта не содержит один из токенов capability_rejected:, которые шлюз Claude apps заменяет на формулировки ошибок облачных поставщиков
• Исключить путь из проверки тела запроса WAF: подсказки Claude Code содержат исходный код и теги в стиле XML, которые соответствуют правилам тела для межсайтовых скриптов; WAF перед шлюзом возвращает 403 на реальных сеансах, в то время как короткие тестовые запросы проходят

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

Шаги развертывания

Развертывание состоит из пяти шагов, каждый с контрольной точкой:

1. Подтвердить маршрутизацию моделей шлюзом
2. Выдать каждому разработчику учетные данные
3. Протестировать Claude Code против шлюза
4. Распределить базовый URL и учетные данные
5. Проверить с машины разработчика

Шаги включают три различных учетных данных, и контрольные точки называют их по заполнителю, чтобы вы могли определить, какой из них виноват, когда что-то не работает:

Подтвердить маршрутизацию моделей шлюзом

Ваш шлюз уже должен быть настроен с учетными данными вашего поставщика, прослушивающий на его базовом URL и перенаправляющий запросы к API вашего поставщика. Протестируйте, что путь работает от конца к концу с минимальным запросом, подставив два значения из вашего развертывания:

• <gateway-key> — это любые учетные данные, которые позволяют вам вызывать шлюз прямо сейчас: административный ключ, тестовый ключ или ваш собственный ключ разработчика, если вы уже выдали его. Не каждый продукт шлюза имеет отдельные административные учетные данные; если у вас их нет, сначала выдайте себе ключ разработчика в Выдать учетные данные разработчика
• model — это имя модели Claude, которое ваш шлюз настроен маршрутизировать. В примере используется claude-sonnet-4-6; подставьте имя, которое вы настроили

curl -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <gateway-key>" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
-Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Контрольная точка: 200 с полем content означает, что шлюз достиг поставщика с этим именем модели. 404 означает, что это имя не маршрутизируется на шлюзе; 401 от поставщика означает, что учетные данные поставщика шлюза неправильные.

Повторите запрос один раз для каждого имени модели Claude в конфигурации маршрутизации вашего шлюза. Имя, которое шлюз не маршрутизирует, возвращает 404 любому разработчику, который его выбирает, поэтому протестируйте каждое имя перед развертыванием.

Выдать учетные данные разработчика

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

Подтвердите, что недавно выданный ключ работает против шлюза с тем же запросом, что и Подтвердить маршрутизацию моделей шлюзом, заменив <gateway-key> на новый <developer-key>:

curl -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <developer-key>" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
-Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Контрольная точка: 200 с полем content означает, что ключ разработчика достигает шлюза и шлюз его перенаправляет. 401 здесь, когда предыдущий шаг был успешным, означает, что ключ разработчика неправильный или еще не вступил в силу на шлюзе.

Выдача одного ключа на разработчика вместо общего ключа — это то, что делает возможной атрибуцию использования для каждого разработчика и отдельное удаление. Переменная окружения, которая содержит ключ, зависит от того, какой заголовок читает шлюз. Для шлюза, который проверяет учетные данные в заголовке Authorization: Bearer, разработчики устанавливают свой ключ в ANTHROPIC_AUTH_TOKEN. Для шлюза, который читает ключи из заголовка x-api-key, разработчики вместо этого устанавливают ANTHROPIC_API_KEY; таблица учетных данных охватывает сопоставление.

Протестировать Claude Code против шлюза

Запустите Claude Code через шлюз самостоятельно перед распределением чего-либо, используя ту же конфигурацию, которую развертывание будет доставлять по всему парку. Введите их непосредственно в терминал, а не в файл .env или файл параметров; они действуют только для этого сеанса терминала, поэтому закрытие его возвращает вашу машину в нормальное состояние. Используйте ANTHROPIC_API_KEY вместо ANTHROPIC_AUTH_TOKEN, если ваш шлюз читает заголовок x-api-key:

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "<developer-key>"

Затем отправьте одноразовую подсказку через шлюз:

claude -p "Reply with one word: connected"

Контрольная точка: подсказка возвращает ответ, и запрос появляется в журнале шлюза как POST к пути /v1/messages со статусом 200. Claude Code добавляет строку запроса, такую как ?beta=true, поэтому сопоставляйте по пути, а не по полному URL. Два сообщения об ошибке указывают в разные стороны:

• Not logged in: проверьте журнал шлюза, чтобы различить две причины. Если он пуст, никакие учетные данные не достигли сеанса и никакой запрос не покинул машину; повторно запустите экспорты в оболочке, которую вы тестируете. Если он показывает отклоненный запрос с x-api-key в теле 401, шлюз ожидает ключи в этом заголовке вместо этого; переключитесь на ANTHROPIC_API_KEY
• Failed to authenticate. API Error: 401 означает, что учетные данные были отправлены и отклонены, и журнал шлюза говорит где: 401, называющий api.anthropic.com или конечную точку вашего поставщика, означает, что шлюз достиг восходящего потока, но его учетные данные поставщика были отклонены, поэтому ключ разработчика работал и учетные данные поставщика, которые держит шлюз, неправильные или заполнитель

Неправильный или недостижимый базовый URL производит другой симптом: Claude Code повторяет попытку подключения с отступом и может сидеть без вывода в течение нескольких минут перед сообщением об ошибке. Если команда кажется зависшей, проверьте журнал шлюза вместо ожидания; отсутствие поступающего запроса означает, что ANTHROPIC_BASE_URL не указывает на шлюз.

Распределить конфигурацию

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

Что распределять

Один и тот же набор переменных применяется независимо от выбранного пути. Большинство развертываний требуют только ANTHROPIC_BASE_URL и учетные данные; включите условные строки, когда ваша настройка шлюза требует их.

Распределить через управляемые параметры

Доставляйте переменные через блок env файла управляемых параметров, отправляемого MDM, политикой реестра или управлением конфигурацией:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

Добавьте условные переменные из таблицы в тот же блок env. Управляемый ANTHROPIC_BASE_URL применяется и не может быть переопределен экспортом оболочки разработчика, так как Claude Code применяет его над переменными процесса и параметрами с более низким приоритетом.

Не включайте forceLoginMethod или forceLoginOrgUUID в управляемые параметры вместе с учетными данными шлюза. Любой ключ, с любым значением, блокирует ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN и apiKeyHelper при запуске, и разработчики не могут продолжить. Они видят This machine's managed settings require a first-party login или Administrator policy requires a Cloud gateway sign-in под значением "gateway".

Доставка управляемых параметров на сервере требует прямого подключения к api.anthropic.com, поэтому она не достигает сеансов, маршрутизируемых через шлюз. Развертывания шлюза используют этот путь управляемых параметров на основе файлов, который применяет те же ключи.

Для учетных данных распределите одну команду apiKeyHelper в файле управляемых параметров, как показано выше; команда аутентифицируется в вашем хранилище секретов как локальный разработчик, поэтому каждая машина получает свой собственный ключ. Альтернативно, доставляйте каждому разработчику его ключ через ваш существующий процесс секретов и попросите их установить ANTHROPIC_AUTH_TOKEN самостоятельно.

Некоторые окружения требуют отдельной доставки:

• Настольное приложение читает маршрутизацию шлюза из своей конфигурации вывода третьей стороны, не из управляемых параметров; разверните этот файл через MDM вместе с управляемыми параметрами, чтобы сеансы рабочего стола также маршрутизировались через шлюз. См. документацию конфигурации рабочего стола и документацию шлюза рабочего стола
• Бегуны CI нуждаются в ANTHROPIC_BASE_URL и учетных данных, установленных в окружении бегуна
• WSL на управляемых машинах Windows читает управляемые параметры Windows только когда wslInheritsWindowsSettings имеет значение true

Передать разработчикам значения для самостоятельной установки

Если у вас нет распределения управляемых параметров, отправьте каждому разработчику то, что ему нужно, чтобы следовать странице подключения:

• URL шлюза
• Их личные учетные данные
• Какую переменную поместить учетные данные в: ANTHROPIC_AUTH_TOKEN для шлюза с токеном-носителем или ANTHROPIC_API_KEY для шлюза x-api-key. Сообщение разработчикам, какой из них, экономит им метод проб и ошибок, описанный на странице подключения
• Любые условные переменные из таблицы Что распределять, с их значениями

Страница подключения проводит разработчиков через установку каждой.

Контрольная точка: на машине разработчика claude запускает сеанс без отображения экрана входа, так как распределенные учетные данные удовлетворяют аутентификацию. Затем запустите /status и откройте вкладку Status: строка Anthropic base URL показывает адрес шлюза, а для управляемого распределения строка Setting sources включает управляемые параметры. Экран входа или отсутствующая строка Anthropic base URL означает, что конфигурация не достигла машины.

Проверить развертывание

Подтвердите, что все работает с машины разработчика, а не хоста шлюза, чтобы тест охватывал сетевой путь, который используют разработчики. Отправьте потоковый запрос, который проверяет конечную точку, сквозную передачу потока и маршрутизацию модели одновременно:

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <developer-key>" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'
$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `
-H "Authorization: Bearer <developer-key>" `
-H "anthropic-version: 2023-06-01" `
-H "content-type: application/json" `
--data-binary '@-'

Вы должны видеть строки data:, поступающие постепенно. Весь ответ, поступающий сразу после паузы, означает, что шлюз буферизирует, что замораживает Claude Code; 404 означает, что имя модели не маршрутизируется. Повторите для каждого имени модели.

Затем запустите claude и отправьте сообщение. Каждый симптом на этом шаге имеет одну причину:

• Приглашение входа означает пробел в учетных данных. Запустите /status и откройте вкладку Status: когда строка Setting sources не включает управляемые параметры, распределение не достигло машины; когда она включает, учетные данные разработчика не были доставлены, поэтому установите ANTHROPIC_AUTH_TOKEN или apiKeyHelper
• Ошибки Failed to authenticate означают, что шлюз отклоняет запросы; его журнал говорит, какие учетные данные не прошли. Отклонение, которое сам журнал шлюза регистрирует, называет ключ разработчика, в то время как 401 от api.anthropic.com или конечной точки вашего поставщика означает, что учетные данные поставщика, которые держит шлюз, были отклонены
• Одноразовое приглашение одобрения для ключа ожидается при первом использовании, когда шлюз ожидает ключи в заголовке x-api-key, установленном как ANTHROPIC_API_KEY. С ANTHROPIC_AUTH_TOKEN никакое приглашение не появляется и переменная берет на себя молча; ранее сохраненный вход claude.ai неактивен для этого сеанса

Если ваша организация использует быстрый режим, запустите /fast здесь тоже: проверка доступности вызывает api.anthropic.com напрямую, а не следует базовому URL шлюза, поэтому сеанс, маршрутизируемый через шлюз, может сообщить быстрый режим как недоступный или отключенный, даже если вывод работает. Использовать быстрый режим за прокси и LLM шлюзами сопоставляет каждое сообщение с переменной, которая его восстанавливает, распределяемой с остальной конфигурацией.

Наконец, проверьте журналы шлюза на предмет отправленного вами сообщения: учетные данные идентифицируют разработчика, и заголовок x-claude-code-session-id группирует запросы по сеансам. Если функции не работают с симптомами устранения неполадок, шлюз удаляет заголовки или переписывает ошибки; см. требования к шлюзу выше.

Поддерживать шлюз

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

При определении размера ограничений скорости для каждого ключа учитывайте повторные попытки клиента при переходящих сбоях, включая ответы 429, до 10 раз с отступом, соблюдая Retry-After. Держите справочник совместимости как контракт для того, что отправляет каждый выпуск Claude Code.

Планирование обновлений версии Claude Code

Некоторое поведение Claude Code встроено в установленную версию, а не установлено на вашем шлюзе, поэтому перемещение разработчиков на новый выпуск может изменить поведение во всем развертывании даже когда конфигурация шлюза не изменилась. Чтобы контролировать, когда это происходит, закрепите разработчиков на протестированной версии с помощью requiredMaximumVersion, или с помощью DISABLE_UPDATES, если вы распределяете Claude Code через свой собственный канал. Перед тем как повысить закрепление, прочитайте запись журнала изменений нового выпуска и протестируйте его против шлюза.

Когда вы тестируете выпуск, новые заголовки или поля запроса, которые шлюз отклоняет, появляются как ошибки 400, описанные в Поддерживать шлюз. Таблица ниже охватывает зависящие от версии изменения, которые не производят ошибку, с параметром, который сохраняет каждое из них постоянным при обновлениях.

Связанные ресурсы

• Подключение Claude Code к LLM-шлюзу: шаги настройки для разработчиков, с конфигурацией для каждой поверхности и таблицей устранения неполадок, которую вы можете передать разработчикам
• Справочник протокола шлюза: справочник для операторов шлюза, охватывающий конечные точки, заголовки для перенаправления и таблицу сквозной передачи функций
• Какое значение использует Claude Code: как управляемые, проектные и пользовательские параметры объединяются
• Механизмы доставки: где находится управляемый файл на каждой платформе
• Настройка Claude Code для вашей организации: более широкое развертывание, частью которого является этот шлюз, включая применение политики, видимость использования и обработку данных