Развертывание и эксплуатация шлюза Claude apps

1. Настройка вашего поставщика идентификации: зарегистрируйте клиента OAuth и проверьте примечания для каждого IdP для Okta, Entra и Google
2. Развертывание шлюза: создайте образ контейнера с закрепленной версией и запустите его на Kubernetes, Cloud Run или вашей собственной платформе. Этот раздел также охватывает решения по стоимости, обходу, нескольким шлюзам и бессерверным вычислениям
3. Настройка операций: журналы, зонды здоровья, поведение при сбое, ротация секретов и обновления. Справочник для подключения мониторинга и runbooks
4. Проверка позиции безопасности: какие данные куда передаются, модель угроз и ответы на вопросы соответствия. Справочник для проверки безопасности

Настройка поставщика удостоверений

• Обслуживает /.well-known/openid-configuration по HTTPS в production; шлюз принимает http:// издателя, и издатель loopback дополнительно требует CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• Поддерживает поток authorization-code. PKCE (Proof Key for Code Exchange) включен по умолчанию; отключите его с помощью oidc.use_pkce: false для IdP, которые его не поддерживают
• Возвращает email и опционально groups в id_token или обслуживает их из конечной точки userinfo с oidc.userinfo_fallback: true

• Okta: сервер авторизации организации в https://example.okta.com возвращает тонкий id_token, который опускает email и groups, поэтому установите oidc.userinfo_fallback: true всякий раз, когда вы используете его как issuer. Пользовательский сервер авторизации, такой как https://example.okta.com/oauth2/default, который включает email и опционально groups в id_token, выдает их напрямую и не требует fallback. Okta выдает groups только когда область groups запрашивается в oidc.scopes и фильтр утверждения groups приложения это позволяет; userinfo_fallback не может заполнить утверждение, которое IdP не был попрошен выдать.
• Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra выдает Object ID групп, а не имена, поэтому используйте GUID в managed.policies.match.groups или используйте App Roles для читаемых имен. Если ваш tenant выдает роли под roles вместо groups, установите oidc.groups_claim: roles.
• Google Workspace: issuer = https://accounts.google.com. id_token Google не содержит groups. Чтобы использовать основанные на группах allowed_groups или managed.policies с Google в качестве IdP, настройте oidc.google_groups, которая ищет группы каждого пользователя через Admin SDK Directory API, используя сервисный аккаунт с делегированием на уровне домена. Без этого используйте oidc.allowed_email_domains для проверки членства и managed.policies.match.email_domain для назначения политики. Google также игнорирует стандартную область offline_access. Для refresh tokens установите oidc.scopes: [openid, profile, email] и oidc.extra_auth_params: { access_type: offline, prompt: consent }.

Развертывание

• Стоимость: нет отдельной лицензии или платы за место. Шлюз является частью бинарного файла claude, поэтому вы платите за inference через ваше существующее обязательство, плюс вычисления, на которых он работает.
• Обход: шлюз не требует, чтобы единственный маршрут к модели проходил через него. Разработчик со своими собственными учетными данными все еще может вызвать поставщика напрямую, поэтому закрытие этого пути — это решение политики сети, например блокировка выхода на api.anthropic.com кроме как от шлюза. Блокировка этого выхода также нарушает проверку безопасности домена WebFetch, которая вызывает api.anthropic.com с каждой машины разработчика. Установите skipWebFetchPreflight: true в управляемой политике, чтобы отключить это.
• Несколько шлюзов: каждый — это отдельное развертывание со своей конфигурацией, и CLI хранит доверие и учетные данные для каждого имени хоста шлюза, поэтому команды могут использовать разные шлюзы без конфликтов. Чтобы обслуживать несколько издателей OIDC, запустите отдельные экземпляры.
• Бессерверная архитектура: Cloud Run работает, если вы установите min-instances: 1, чтобы избежать холодного обнаружения OIDC. Lambda и Cloud Functions не работают, потому что шлюз — это долгоживущий HTTP сервер.

• На каждом upstream кроме provider: anthropic, шлюз записывает SSE ping один раз, когда поток был молчалив около 15 секунд.
• На provider: anthropic, шлюз пропускает ответ без изменений, включая собственные ping’и API Anthropic.

Выберите адрес для шлюза

• Частный адрес: разместите шлюз за внутренним балансировщиком нагрузки или VPN с именем хоста, которое разрешается только в частные адреса, такие как RFC 1918 или CGNAT 100.64.0.0/10. Машины пользователей могут иметь любой адрес. Предварительное требование о частной сети перечисляет допустимые диапазоны.
• Объявленный блок: если ваша внутренняя сеть использует публичное пространство IPv4, принадлежащее вашей организации, укажите этот блок в управляемой настройке gatewayInternalNetworks. И шлюз, и машина пользователя должны находиться в этом блоке. См. Разрешение шлюза в публичном адресном пространстве, которым вы владеете.

Образ контейнера

1. Загрузите сборку Linux для архитектуры вашего образа из закрепленного выпуска; см. Установка конкретной версии для URL загрузки.
2. Проверьте его против подписанного GPG manifest.json выпуска, как описано в Целостность бинарного файла и подпись кода.
3. Скопируйте его в контекст сборки.

• Образ на основе glibc: единственные динамические зависимости сборки glibc — это библиотеки glibc. Образам на основе Musl нужна сборка linux-x64-musl или linux-arm64-musl, единственной динамической зависимостью которой является musl.
• Записываемый каталог состояния: шлюз работает как любой пользователь, но минимальные образы не имеют записываемого home. Установите CLAUDE_CONFIG_DIR на записываемый путь, такой как /tmp/.claude.
• Команда контейнера: claude gateway --config /etc/claude/gateway.yaml, с файлом конфигурации, смонтированным только для чтения, и секретами, предоставленными как переменные окружения; шлюз слушает на listen.port, по умолчанию 8080.

Kubernetes

• Смонтируйте конфигурацию из ConfigMap и секреты из Secret; ссылайтесь на секреты в YAML через ${file:/path/to/secret} или как переменные окружения
• Завершите TLS на Ingress и установите listen.public_url на имя хоста Ingress
• Укажите зонд готовности на GET /readyz и зонд живучести на GET /healthz

Cloud Run

• Оставьте listen.port на его значении по умолчанию 8080, которое соответствует PORT Cloud Run по умолчанию, или установите port: ${PORT}
• Установите public_url на внешне доступное происхождение. Для production это обычно имя хоста внутреннего балансировщика нагрузки, потому что /login отклоняет публичные адреса и URL *.run.app разрешается на один, поэтому URL Cloud Run один работает только для curl или дымового теста браузера. Исключение — сеть, где *.run.app разрешается приватно через Private Service Connect и приватную зону Cloud DNS; в этой топологии URL Cloud Run — это действительный public_url. Пример Google Cloud охватывает оба.
• Смонтируйте конфигурацию как том секрета
• Установите min-instances: 1, чтобы избежать холодного обнаружения OIDC при первом запросе

Отправьте URL шлюза на машины разработчиков

Крупные развертывания

• Шлюз не может видеть за вашим балансировщиком нагрузки. Без listen.trusted_proxies каждый разработчик выглядит как исходящий с адреса балансировщика нагрузки и делит один лимит. Шлюз логирует предупреждение в первый раз, когда он игнорирует заголовок X-Forwarded-For. Если балансировщик нагрузки должен быть указан в listen.trusted_proxies, укажите его, прежде чем менять что-либо ещё. Если разработчики всё ещё делят один адрес, поднимите rate_limits.
• Много разработчиков делят несколько NAT или VPN адресов выхода. Они делят лимиты этих адресов даже когда trusted_proxies правильно установлен. Поднимите rate_limits, чтобы соответствовать.

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

Эксплуатация

Логи

• События аудита: однострочный JSON для каждого события, значимого для безопасности. Направьте stderr в ваш агрегатор логов. Генерируемые события включают config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, access.public_client, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert и admin.limit.delete. Поля зависят от события:
  • Успешные события выпуска и обновления содержат sub, email, client_ip и результат
  • auth.denied и access.denied содержат причину и IP-адрес клиента, а для auth.denied ещё и путь запроса, поскольку при этих отказах идентификатор пользователя отсутствует. Две причины access.denied меняют содержимое события:
    • xff_unparseable: событие также содержит запись X-Forwarded-For, которую не удалось прочитать
    • client_ip_unknown: событие не содержит IP-адреса клиента, поскольку у соединения не было адреса пира, а список access_control был задан
  • access.public_client содержит IP-адрес клиента первого запроса в рамках процесса, пришедшего с публичного адреса, когда access_control.allow_cidrs пуст. Шлюз обслуживает запрос как обычно; событие сигнализирует о том, что шлюз может быть доступен из публичного интернета. Что считается публичным адресом и какой список разрешённых адресов рекомендуется, см. в справочнике по access_control.
  • inference фиксирует, какой вышестоящий сервер обслужил запрос, и статус ответа
  • desktop_bootstrap.denied фиксирует отклонённый запрос начальной загрузки Claude Desktop с указанием причины (not_configured, policy_not_opted_in или no_policy_matched) и идентификатора пользователя
  • guardrail.trace фиксирует, какой фильтр сработал, без совпавшего текста
  • admin.denied фиксирует отклонённую попытку аутентификации в API администратора с IP-адресом клиента, методом, путём и причиной, без предъявленного ключевого материала: invalid_key, если был предъявлен x-api-key, не совпавший ни с одним настроенным ключом; bearer_rejected, если был предъявлен только заголовок Authorization и он не прошёл проверку как сессия шлюза в admin.admin_groups; или no_credentials, если не был предъявлен ни один из заголовков
• Операционные логи: удобочитаемые строки с префиксом [gateway] о запуске, предупреждениях и ошибках вышестоящих серверов. Переменная окружения CLAUDE_GATEWAY_LOG_LEVEL управляет уровнем детализации и принимает значения debug, info, warn или error; по умолчанию используется info. На уровне debug при каждом входе и обновлении также записываются в лог имена (но не значения) claims в id_token, а также имена claims userinfo, если userinfo_fallback их предоставил, что позволяет диагностировать настройки email_claim и groups_claim без записи персональных данных в лог. На события аудита эта переменная не влияет — они генерируются всегда.

Запись операционных логов в формате JSON

{"severity":"INFO","time":"2026-11-04T17:03:21.512Z","message":"claude gateway listening on http://0.0.0.0:8080"}

Работоспособность

Одновременные запросы к вышестоящим серверам

• Добавить реплики.
• Повысить лимит на каждой реплике. Задайте переменную окружения BUN_CONFIG_MAX_HTTP_REQUESTS в контейнере шлюза целым числом от 1 до 65535, затем перезапустите контейнер.

Держите API_TIMEOUT_MS выше времени до первого байта шлюза

• provider: anthropic: задайте API_TIMEOUT_MS выше максимального времени, за которое ваш вышестоящий сервер отправляет первое событие.
• Любой другой вышестоящий сервер: задайте значение более чем на 20 секунд выше максимального времени, за которое ваш вышестоящий сервер возвращает заголовки ответа. Шлюз отправляет свой первый keepalive ping примерно через 15 секунд после этих заголовков, если первое событие вышестоящего сервера не придёт раньше. Шлюз версии старше v2.1.229 не отправляет ping, поэтому для него используйте правило для provider: anthropic.

Более быстрая повторная попытка для запроса без ответа с помощью крайнего срока первого байта

export CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000

Поведение при сбоях

• Существующие сессии: Bearer-токены проверяются локально с помощью секрета JWT, обновления сессий не обращаются к хранилищу, и процесс шлюза по-прежнему может обслуживать запросы инференса
• Новые входы: завершаются ошибкой до восстановления Postgres, поскольку поток авторизации устройства и его счётчики ограничения частоты запросов хранятся в Postgres
• Применение лимитов расходов: по умолчанию во время сбоя работает в открытом режиме (fail open), то есть запросы пропускаются и инференс продолжает работать; переключите его в закрытый режим (fail closed), если предпочитаете блокировать запросы, а не пропускать их без учёта расходов
• Готовность: по умолчанию /readyz сообщает о неготовности, как только Postgres становится недоступен, поэтому все реплики одновременно не проходят проверку готовности. Если трафик направляется только на реплики, прошедшие проверку, весь трафик, включая инференс, который шлюз ещё мог бы обслужить, отклоняется до восстановления Postgres. Проверка жизнеспособности на /healthz всё это время продолжает проходить успешно.

Льготный период готовности

Ротация секрета JWT

1. Сгенерируйте новый секрет. Добавьте его в начало массива session.jwt_secret.
2. Выполните повторное развёртывание. Новые токены подписываются новым секретом; старые токены по-прежнему проходят проверку.
3. По истечении ttl_hours с запасом удалите старый секрет и снова выполните развёртывание.

Postgres

• База данных: сам PostgreSQL, самостоятельно размещённый или управляемый, минимальной версии или новее. Базы данных, которые лишь реализуют протокол Postgres, например распределённые SQL-базы данных, не поддерживаются.
• Адрес: store.postgres_url принимает один хост. Если база данных состоит из нескольких узлов, используйте адрес перед ними, например эндпоинт вашего управляемого сервиса, балансировщик нагрузки или виртуальный IP-адрес. Задайте льготный период готовности дольше, чем длится переключение на резервный узел.

Определение размера пула соединений

• Реплики: учитывайте максимальное число одновременно работающих. Начните с максимума автомасштабирования или с числа реплик, если автомасштабирование не используется, и добавьте дополнительные реплики, которые поэтапное обновление запускает до остановки старых. В Amazon ECS с настройками по умолчанию и в Cloud Run их может быть столько же.
• Оставшиеся соединения: возьмите значение max_connections базы данных, затем вычтите то, что резервирует база данных, и то, что удерживают другие клиенты. PostgreSQL резервирует superuser_reserved_connections, по умолчанию три. Управляемый сервис может резервировать больше, поэтому сверьтесь с его документацией.

• База данных: увеличьте её max_connections
• Реплики: запускайте меньше реплик или настройте оркестратор на запуск меньшего числа дополнительных реплик при поэтапном обновлении
• Пул: уменьшите store.max_connections, но при включённых лимитах расходов сохраняйте его достаточным для нагрузки каждой реплики. Иначе проверки расходов могут завершаться по таймауту в ожидании соединения, а шлюз будет записывать в лог spend check failed: spend precheck timed out.

Обновления

• Окно завершения: задайте переменную окружения CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS в контейнере шлюза положительным целым числом миллисекунд, например 120000. Шлюз игнорирует значение в любой другой форме, например 120s, и сохраняет значение по умолчанию 25 секунд
• Льготный период вашего оркестратора: terminationGracePeriodSeconds в Kubernetes или stopTimeout в Amazon ECS

• Amazon ECS на Fargate: stopTimeout допускает не более 120 секунд
• Cloud Run: останавливает экземпляр через 10 секунд после SIGTERM, поэтому открытые потоки получают там не более 10 секунд независимо от окна завершения

Безопасность

Поток данных

Краткое резюме модели угроз

• Разработчики держат краткосрочные JWT вместо сырых ключей upstream. Ветвь CLI-к-шлюзу использует грант устройства RFC 8628, и обмен авторизацией шлюза с IdP запускает PKCE в конфигурации по умолчанию, поэтому перехваченный код авторизации IdP бесполезен.
• Страница проверки устройства применяет same-origin POST и ограничение скорости для каждого IP согласно RFC 8628 §5.1. См. Сопротивление brute-force пользовательского кода.
• Исходящие запросы шлюза к вашему IdP, вашим сборщикам OTLP и provider: anthropic upstreams проходят через защиту от подделки запроса на стороне сервера (SSRF), которая разрешает DNS, блокирует link-local и адреса облачных метаданных плюс loopback по умолчанию и закрепляет соединение на разрешенный IP, поэтому управляемые оператором URL не могут быть перенаправлены на конечные точки облачных метаданных. Диапазоны приватных RFC 1918 намеренно разрешены, потому что IdP и сборщики OTLP обычно живут на приватных IP. Для других поставщиков шлюз отказывает в base_url, который называет один из этих адресов или имя хоста метаданных при загрузке конфигурации, и SDK поставщика затем подключается без проверки DNS. Если вы включите только прокси выход, эта проверка адреса переходит к вашему forward proxy: шлюз передает ему имена хостов и список разрешений прокси должен отказать этим назначениям. Установите CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 в окружении шлюза только когда что-то, что шлюз должен достичь, легитимно живет на loopback, такое как локальная разработка IdP или сборщик OTLP sidecar на localhost. Переменная ослабляет блокировку loopback для каждого настроенного оператором URL и также пропускает предупреждение при загрузке, которое проверяет, может ли pod достичь конечной точки облачных метаданных, поэтому предпочитайте давать сборщику его собственный внутренний адрес.

• Скомпрометированный хост шлюза: хост как содержит upstream учетные данные, так и распределяет управляемые параметры каждому подключенному разработчику, поэтому контроль над конфигурацией шлюза сравним с контролем над вашим MDM. Диалог одобрения CLI для параметров, способных к shell, ограничивает молчаливые изменения, но не заменяет безопасность хоста.
• Вредоносный поставщик OIDC: поставщик подписывает id_tokens, которым шлюз доверяет, поэтому он может утверждать любую идентификацию. Проверка и защита вашего IdP — это ваша ответственность.

Сопротивление brute-force пользовательского кода

Позиция соответствия

• Резидентность данных: собственная плоскость данных шлюза не отправляет ничего Anthropic, если только API Anthropic не является настроенным upstream; когда это так, ваше существующее соглашение об обработке данных применяется к пути inference. Телеметрия, аудит, идентификация и параметры идут только к назначениям, которые вы настраиваете.
• Трафик хост-процесса: хост-процесс — это Claude Code CLI. claude gateway работает под теми же правилами третьих сторон, что и развертывания Amazon Bedrock и Google Cloud’s Agent Platform, и не отправляет ничего Anthropic. До v2.1.227 хост-процесс отправлял телеметрию запуска, такую как версия продукта и платформа, которую установка CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 в окружении контейнера отключала. Эти выпуски также отправляли один запрос HEAD при загрузке, без тела или учетных данных, на /api/hello на https://api.anthropic.com, или на ANTHROPIC_BASE_URL когда окружение установило его, если только окружение также не установило переменную прокси, такую как HTTPS_PROXY или сертификат клиента mTLS. Они игнорировали ответ, поэтому блокировка этого запроса на брандмауэре выхода не влияла на шлюз.
• Аналитика клиента: CLI отключает свою собственную аналитику использования и отчеты об ошибках при входе в шлюз. До первого входа CLI все еще отправляет события запуска Anthropic, включая на машинах, чьи управляемые параметры принуждают вход в шлюз. Чтобы отключить и их, доставьте DISABLE_TELEMETRY в тех же управляемых параметрах на стороне клиента, которые принуждают вход в шлюз.
• Отчеты об ошибках: CLI отключает отчеты об ошибках всякий раз, когда его запросы модели идут на любую конечную точку, отличную от первоклассного API Anthropic, такую как Amazon Bedrock или пользовательский ANTHROPIC_BASE_URL.
• Машины клиентов: CLI разработчиков все еще отправляют проверки имени хоста WebFetch и проверки версии Anthropic, если не установлены CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 и skipWebFetchPreflight: true. У запросов к маркетплейсам плагинов есть собственные способы отключения. См. использование данных.
• Рейтинги опроса: при входе в шлюз CLI отключает загрузку рейтингов, привязанную к Anthropic, вместе с потоками аналитики, поэтому он не отправляет рейтинги Anthropic.
• Обмен транскриптом: выбор Yes на подсказке обмена транскриптом опроса записывает локальный файл в ~/.claude/feedback-bundles/ вместо загрузки Anthropic.
• Обновления клиента: проверки обновлений отделены от трафика шлюза. Закрепите версии через вашу собственную дистрибуцию и установите DISABLE_UPDATES, если ноутбуки не должны получать выпуски. DISABLE_AUTOUPDATER останавливает только фоновые обновления, в то время как claude update все еще работает.
• TLS: обслуживайте public_url по HTTPS в production, либо из собственного слушателя шлюза через listen.tls, либо из TLS-завершающего ingress перед простыми HTTP репликами, с установленным listen.public_url в обоих случаях. Шлюз не отказывает простой HTTP. IdP должен обслуживать HTTPS в production, и Postgres поддерживает ?sslmode=require. Установите Strict-Transport-Security на вашем ingress.
• Раскрытие уязвимостей: следуйте Отчету о проблемах безопасности

Запросы к маркетплейсам плагинов

• Список маркетплейсов: список разрешённых маркетплейсов strictKnownMarketplaces, в который этот маркетплейс не входит, или запись blockedMarketplaces, которая его называет
• Переменная окружения: CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL со значением "1" в управляемом блоке env

Устранение неполадок

• Проблема шлюза: stderr шлюза для соответствующего окна, ваш gateway.yaml с редактированными секретами, версию шлюза, показанную на целевой странице в / и в заголовке ответа x-cc-gateway-version на /managed/settings, и что недавно изменилось
• Проблема входа: разработчик запускает claude --debug-file ./claude-debug.txt, воспроизводит и отправляет этот файл плюс журнал аудита шлюза для того же окна
• Проблема inference: запрошенная модель, настроенные upstreams и журнал аудита шлюза для запроса, который записывает, какой upstream обслужил его и статус ответа

Слишком большие заголовки запросов после входа

• Шлюз старше v2.1.284: обновите шлюз
• Задан limits.max_request_header_bytes: увеличьте значение или удалите ключ
• Ни то, ни другое не применимо, или 431 продолжает возникать после этого: сделайте так, чтобы ваш IdP выдавал меньше групп. В разделе Identity provider setup описано, как Okta, Microsoft Entra ID и Google Workspace передают группы

• oidc.allowed_groups: определяет, кто может войти
• admin.admin_groups: определяет, кто может вызывать admin API со своей сессией шлюза
• match.groups в managed.policies: определяет, какая политика применяется к разработчику
• groups у upstream: определяет, какие upstream обслуживают разработчика
• rbac_group лимиты расходов: определяют, какие групповые лимиты применяются к разработчику

Долгое мышление заканчивается таймаутами прокси

• Первый запрос: поток, который доставляет первое событие ответа, message_start, а затем только пинги, пока Claude думает. С настройками по умолчанию Claude Code завершает этот поток примерно через 12,5 минуты.
• Остальные 10: тот же запрос, отправленный без потоковой передачи, а затем повторно, всего 10 отправок по умолчанию. Они не получают пингов, поэтому медленный ответ упирается в таймаут прокси.

Подтвердите причину

Error streaming, falling back to non-streaming mode: Stream idle timeout - no chunks received

Выберите значение

Передайте значение в политике

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_STREAM_IDLE_TIMEOUT_MS: "1800000"

Долгое мышление на upstream Anthropic API

• Долгий запрос: поток, который доставляет message_start, а затем только пинги, пока Claude думает. С настройками по умолчанию Claude Code завершает его примерно через 20 минут, а после увеличения переменной — позже.
• Ошибки: запросы, которые Claude Code затем отправляет без потоковой передачи. Каждый из них завершается ошибкой 502 от шлюза или ошибкой 504 от вашего прокси, если таймаут прокси короче времени ожидания шлюза. Это время ожидания — timeouts.upstream_ttfb_ms, и для этого исправления увеличивать его не нужно.

Связанное

• Обзор шлюза Claude apps: быстрый старт и подключение разработчика
• Справочник по конфигурации: каждый параметр файла gateway.yaml