Конфигурация Claude apps gateway

Справочник по каждому параметру gateway.yaml: listener и TLS, OIDC, session, хранилище Postgres, upstreams Amazon Bedrock, Claude Platform на AWS, Agent Platform Google Cloud и Microsoft Foundry, маршрутизация моделей, управляемые политики и телеметрия.

Развёртывание Claude apps gateway настраивается одним файлом YAML, обычно gateway.yaml. Файл определяет всё, что делает gateway: где он слушает, как разработчики входят в систему, куда идёт вывод, и какие политики и телеметрия применяются. Эта страница — справочник по каждому параметру в этом файле.

Чтобы написать свой первый файл, начните с quickstart, который создаёт минимальную рабочую конфигурацию и запускает её. Когда у вас будет конфигурация, которой вы довольны, руководство по развёртыванию охватывает контейнеризацию и размещение на Kubernetes, Cloud Run или вашей собственной платформе.

Gateway читает файл один раз при запуске с помощью claude gateway --config /path/to/gateway.yaml. Каждый параметр проверяется по схеме при загрузке, поэтому неправильная конфигурация не запускается с ошибкой на уровне поля, а не при первом использовании.

Полный пример в конце этой страницы охватывает каждый раздел.

Структура файла

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

Обязательные разделы:

• listen: адрес привязки, публичный URL, завершение TLS
• oidc: ваш поставщик идентификации (IdP), включая издателя, клиента, сопоставление утверждений и кто может входить
• session: токены-носители, которые выпускает gateway, с секретом и временем жизни
• store: PostgreSQL для грантов устройств и счётчиков ограничения скорости
• upstreams: куда идёт вывод, будь то Anthropic, Amazon Bedrock, Claude Platform на AWS, Agent Platform Google Cloud или Microsoft Foundry

Опциональные разделы:

• admin: аутентификация Admin API и сохранение лимитов расходов
• enforcement: поведение лимитов расходов при сбое — пропускать запросы (fail-open) или блокировать (fail-closed)
• pricing: договорные ставки и множитель скидки для счётчика расходов и для цифр стоимости, которые видят разработчики
• models и auto_include_builtin_models: кураторский список моделей администратором и ID для каждого upstream
• managed: управляемые политики параметров по группам IdP
• telemetry: пересылка OTLP на ваш стек наблюдаемости
• access_control, limits, timeouts, rate_limits: разрешение/запрет IP, ограничения размера запроса, время до первого байта upstream и лимиты входа по IP

Расширение секретов

Не пишите секреты, такие как client_secret, jwt_secret или postgres_url, прямо в gateway.yaml. Ссылайтесь на них одной из форм ниже, и gateway разрешит значение при загрузке из переменной окружения или файла:

Обязательные разделы

`listen`

Блок listen управляет тем, где служит gateway: адрес привязки и порт, видимое снаружи происхождение и опциональное завершение TLS.

`oidc`

Блок oidc подключает gateway к вашему поставщику идентификации и решает, кто может входить. Он называет издателя и клиента OAuth, сопоставляет утверждения, которые несут электронную почту и группы, и ограничивает вход по домену электронной почты или группе.

OpenID Connect (OIDC) — это протокол SSO, который gateway использует с вашим поставщиком идентификации; см. Настройка поставщика идентификации для того, что нужно зарегистрировать на стороне IdP.

Запросы IdP через прямой прокси

Upstream вывода соблюдают HTTPS_PROXY и HTTP_PROXY на каждой версии. Собственные запросы gateway к IdP, обнаружению, JWKS, токену и userinfo идут напрямую, если вы не установите oidc.use_proxy: true, что требует v2.1.227 или позже. Когда переменная прокси установлена, use_proxy не установлена и издатель не охватывается NO_PROXY, gateway держит эти запросы прямыми и логирует уведомление при загрузке, прося вас выбрать; use_proxy: false держит их прямыми и молчит уведомление.

С use_proxy: true, pod разрешает имя хоста каждой конечной точки IdP сам и просит прокси CONNECT к разрешённому IP адресу, поэтому прокси должен принять CONNECT к IP адресу каждого хоста, который называет документ обнаружения, не только издателя. Используйте URL прокси http://. ca_cert_pem и защита SSRF применяются на проксированном пути также.

`session`

Блок session формирует токены-носители, которые выпускает gateway после входа: секрет, который их подписывает, и как долго они живут.

`store`

Блок store указывает gateway на его базу данных PostgreSQL, которая содержит гранты устройств и счётчики ограничения скорости.

Для локальной разработки укажите postgres_url на одноразовый контейнер Postgres, например docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

`upstreams`

upstreams — это упорядоченный список. Gateway пересылает вывод на первый upstream, который разрешает запрошенную модель.

На 5xx, 429, 401, 403, 404 или timeout gateway переходит на следующий upstream; другие 4xx не переходят, потому что эти ошибки относятся к запросу, а не к upstream. 401 или 403 означает, что собственные учётные данные gateway не прошли проверку на этом upstream. 404 означает, что этот upstream не служит запрошенной модели, поэтому более поздний upstream в списке всё ещё может.

Если вы установите forward_user_identity: true на upstream, 429, который он возвращает на запрос, который нёс электронную почту разработчика, не переходит. См. как отказ в лимите на пользователя достигает разработчика.

Переход при 404 требует gateway v2.1.198 или позже. Более ранние выпуски возвращали первый 404 клиенту даже когда более поздний upstream в списке служил модели.

Несколько upstream одного поставщика должны установить отличный name:.

Клиенты Bedrock, Claude Platform on AWS, Agent Platform и Foundry создаются один раз при запуске, и их SDK обновляют учётные данные внутри, поэтому ротация облачных учётных данных не требует перезагрузки. Статические ключи API Anthropic и носители читаются при запуске; см. Anthropic API.

Сообщения об ошибках upstream

Gateway возвращает ответ об ошибке одного upstream или собственный 502, в зависимости от того, как ответили upstream:

• Upstream вернул статус, на который gateway не переходит: ответ этого upstream. Gateway не пробует дальнейшие upstream.
• Каждый upstream, который пробовал gateway, не удался способом, на который он переходит: последний 429. Когда ни один не вернул 429, gateway предпочитает, по порядку, последний 401 или 403, последний 404 и последний 501. Когда ни один не вернул ни один из них, собственный 502 gateway, all upstreams failed (N attempted), где N считает каждую запись в upstreams, включая записи, которые gateway пропустил, потому что они не служат запрошенной модели.

Когда gateway возвращает ответ upstream, он сохраняет код статуса upstream. Сохраняет ли он сообщение upstream, зависит от поставщика. Тело ошибки upstream Anthropic API достигает разработчика без изменений.

Upstream Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform и Microsoft Foundry могут называть ID вашей учётной записи, ARN ролей и ID проектов в тексте их ошибки. Gateway записывает этот полный текст в операционный журнал. То, что видит разработчик из этих upstream, зависит от отклонения:

• 400 или 413 в стандартном конверте ошибок Anthropic: собственное сообщение upstream, такое как prompt is too long. Claude Platform on AWS, Agent Platform и Microsoft Foundry возвращают этот конверт для отклонений API модели.
• 400 или 413 в собственной форме поставщика: токен capability_rejected:. Когда gateway не может классифицировать отклонение, upstream rejected the request на 400 или request too large for this upstream на 413.
• Любой другой статус: универсальный текст для каждого статуса, такой как upstream rate limit exceeded на 429.

Например, gateway заменяет Input is too long for requested model. Amazon Bedrock на capability_rejected: prompt_too_long. Claude Code автоматически компактирует на этот токен, как и на prompt is too long.

Сохранение сообщения 400 или 413 облачного upstream или его замена на токен capability_rejected: требует gateway v2.1.233 или позже.

Anthropic API

Минимальный upstream Anthropic — это ключ API из Claude Console:

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # ИЛИ токен-носитель OAuth (например, токен, обменённый Workload-Identity-Federation):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # по умолчанию; переопределите для прямого прокси

Две формы учётных данных отличаются заголовком, который они отправляют:

• api_key: отправляет x-api-key. Ротируйте его в Claude Console и обновите переменную env.
• oauth_token: отправляет Authorization: Bearer. Используйте форму носителя, когда ваша организация выпускает короткоживущие токены вместо долгоживущих ключей API. Носитель читается один раз при запуске, поэтому обновите, переподключив секрет и перезагрузив.

Вместо статического ключа или носителя вы можете использовать Workload Identity Federation. Создайте правило федерации, следуя руководству Workload Identity Federation, затем смонтируйте JWT OIDC вашей рабочей нагрузки как файл, такой как проецируемый токен сервис-аккаунта Kubernetes или id-token платформы CI. Gateway обменивает JWT на короткоживущий носитель и автоматически его обновляет. Файл токена перечитывается при каждом обмене, поэтому ротированные проецируемые токены подхватываются без перезагрузки.

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # требуется, если правило охватывает >1 рабочего пространства
      # service_account_id: svac_...   # опциональная проверка ожидаемой цели

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # по умолчанию false

Когда токен IdP не несёт электронную почту, gateway отправляет только x-claude-gateway-user-id и опускает два заголовка электронной почты. Если ваш IdP помещает электронную почту в другое утверждение, установите oidc.email_claim на это утверждение.

Когда ваш прокси ответит 429 на запрос, который нёс электронную почту разработчика, gateway возвращает этот ответ разработчику как есть вместо перехода на следующий upstream, поэтому бюджет на пользователя вашего прокси или лимит скорости держится. Другие ответы прокси следуют обычным правилам переходов. Если токен IdP разработчика не несёт электронную почту, gateway пересылает их запросы без заголовков электронной почты, поэтому 429 на один из этих запросов считается пропускной способностью upstream и переходит. До v2.1.267 на сервере gateway каждый 429 переходил.

Установите forward_user_identity только на upstream, чей base_url — это прокси, который вы управляете. Gateway отправляет электронные письма разработчиков на любой сервер, который называет этот base_url. Если base_url — это Anthropic API, что является по умолчанию, gateway отказывается запускаться.

Amazon Bedrock

Для развёртывания Bedrock на стороне клиента, которое gateway заменяет или находится перед ним, см. Claude Code на Amazon Bedrock. Upstream на стороне gateway:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # предпочтительно: цепочка учётных данных AWS по умолчанию
    # ИЛИ явные учётные данные:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # ИЛИ токен-носитель Bedrock API:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Переопределите конечную точку bedrock-runtime для развёртываний FIPS или VPC-endpoint:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

Пустой блок auth использует цепочку учётных данных AWS SDK по умолчанию: переменные env, ~/.aws/credentials, роль задачи ECS, метаданные экземпляра EC2 или IRSA на EKS. В production дайте поду gateway роль IAM вместо встраивания статических ключей в образ контейнера.

Явные учётные данные должны быть полными: gateway не запускается, когда aws_access_key_id и aws_secret_access_key не установлены вместе, или когда aws_session_token установлен без них. До v2.1.207 частичный блок auth: прошёл проверку.

Claude Platform on AWS

Claude Platform on AWS предоставляет собственный API Anthropic на инфраструктуре AWS по адресу aws-external-anthropic.<region>.api.aws. Он использует собственные ID моделей Anthropic, соблюдает заголовки anthropic-beta в том виде, в котором они отправлены, и обслуживает count_tokens, поэтому никакой перевод, специфичный для Bedrock, не применяется. Поставщик anthropicAws требует Claude Code v2.1.198 или позже; более ранние выпуски gateway отклоняют его при загрузке.

Для развёртывания на стороне клиента той же платформы см. Claude Code на Claude Platform on AWS. Upstream на стороне gateway:

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # отправляется как x-api-key
    # ИЛИ SigV4 через цепочку учётных данных AWS по умолчанию:
    # auth: {}
    # ИЛИ явные учётные данные SigV4:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Переопределите полученную конечную точку:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

Платформа работает в отдельной учётной записи AWS от Amazon Bedrock и подписывает запросы SigV4 для собственного имени сервиса, aws-external-anthropic, поэтому роль IAM, ограниченная Bedrock, не авторизует её. Ключ API в auth.api_key имеет приоритет, когда также установлены учётные данные SigV4. Пустой блок auth использует цепочку учётных данных AWS SDK по умолчанию, ту же цепочку, которую использует upstream Amazon Bedrock.

Поскольку платформа разрешает первоклассные ID моделей, встроенный каталог маршрутизирует на неё без блока models:. Когда вы курируете список models:, ключируйте запись anthropicAws: с первоклассным ID.

Google Cloud Agent Platform

Для эквивалентной настройки на стороне клиента см. Claude Code на Google Cloud. Upstream на стороне gateway:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # предпочтительно: Application Default Credentials
    # ИЛИ файл ключа сервис-аккаунта:
    # auth: { service_account_json: /secrets/sa.json }
    # Переопределите конечную точку aiplatform для Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

Пустой блок auth использует Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS, метаданные GCE или Workload Identity GKE. Файлы ключей JSON сервис-аккаунта поддерживаются, но не рекомендуются; используйте Workload Identity или присоедините сервис-аккаунт к экземпляру GCE или Cloud Run.

Установите region: global для использования глобальной конечной точки Agent Platform вместо региональной. Google затем маршрутизирует каждый запрос в доступный регион, поэтому вы не отслеживаете доступность модели для каждого региона. Установка конкретного региона закрепляет каждый запрос на нём.

Microsoft Foundry

Для развёртывания Foundry на стороне клиента см. Claude Code на Microsoft Foundry. Upstream на стороне gateway:

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # предпочтительно: DefaultAzureCredential / Managed Identity
    # ИЛИ ключ API:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

use_azure_ad: true разрешается через DefaultAzureCredential: Managed Identity на AKS, ACI или App Service; Azure CLI; или учётные данные окружения. Ключи API работают, но являются проектными и не ротируются автоматически. Конечная точка Foundry получена из resource:; установите опциональный base_url для переопределения для суверенных облаков, таких как Azure Government.

Несколько upstream

Один и тот же поставщик может появляться более одного раза с отличным name:. Это охватывает разные регионы, разные учётные записи через разные цепочки учётных данных, выделенную пропускную способность в сравнении с по требованию и кросс-провайдерный fallback.

Gateway пробует upstream по порядку. 5xx, 429, 401, 403, 404, timeout и отсутствие конечной точки (501) переходят; другие 4xx не переходят.

429 — это пропускная способность для каждого upstream, поэтому истощение выделенной пропускной способности (PT) переходит на по требованию. Если вы установите forward_user_identity: true на upstream, 429 к запросу, который нёс электронную почту разработчика, — это отказ на пользователя вместо этого и не переходит.

404 — это доступность модели для каждого upstream, поэтому upstream, который не включил модель, не блокирует более поздний upstream, который её служит. Upstream, который не может разрешить запрошенную модель, пропускается без сетевого раундтрипа.

Этот пример маршрутизирует выделенное выделение пропускной способности Bedrock в первую очередь, переполнение на по требованию и вторую учётную запись, и переходит на Anthropic API в последнюю очередь:

upstreams:
  # Основной: выделенная пропускная способность в вашем домашнем регионе.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Переполнение: по требованию между регионами.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Другая учётная запись: отдельное выделение Bedrock через учётные данные предполагаемой роли.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Последняя инстанция: прямой Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# ID моделей для каждого upstream ключены на `name:` upstream.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

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

CLI применяет одинаковое управление функциями к gateway независимо от того, какой upstream служит данному запросу, поэтому переход не отправляет поле тела, которое upstream отклонил бы.

Опциональные разделы

`admin`

Опциональный. Включает /v1/organizations/spend_limits, который отражает публичный Admin API Anthropic, и применение расходов для каждого разработчика на /v1/messages. См. Лимиты расходов для того, как устанавливаются и применяются ограничения; этот раздел охватывает ключи gateway.yaml, которые включают функцию и настраивают её.

admin:
  # Именованные статические ключи API для конечных точек администратора, отправляемые как x-api-key.
  # ID появляется в журнале аудита как admin-key:<id>, поэтому каждый ключ
  # атрибутируется. Массив для ротации: добавьте новый ключ, перекатите клиентов,
  # удалите старый.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # Группы IdP, предоставленные полному администратору через обычный JWT gateway (без ключа API).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

`enforcement`

Блок enforcement управляет тем, как проверки лимитов расходов ведут себя, когда хранилище недоступно.

`pricing`

Блок pricing сообщает счётчику расходов, что нужно взимать вместо цены USD по прайс-листу, поэтому ограничения и /effective отражают ваши договорные ставки. Суммы остаются в USD и остаются оценкой, а не счётом. Два предварительных условия:

• Claude Code v2.1.227 или позже на сервере gateway. Более ранние версии отклоняют неизвестный ключ при загрузке.
• Блок admin: или, в v2.1.268 или позже, блок managed: с по крайней мере одной политикой. Gateway отказывается запускаться с установленным pricing и без одного из этих блоков, потому что ничто не будет его читать.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

Как счётчик соответствует строке переопределения:

• Строка заменяет цену по прайс-листу для запросов, которые upstream, upstreams[].name, обслуживает для model. Это включает более высокую ставку быстрого режима, поэтому запросы быстрого и стандартного режимов измеряются по одним и тем же четырём ставкам.
• Встроенный ID, такой как claude-sonnet-4-6, соответствующий models[].id, охватывает каждую датированную форму, региональную форму Amazon Bedrock или форму Google Cloud Agent Platform, которую счётчик оценивает как эту модель. Любая другая строка, такая как псевдоним или ARN профиля вывода, соответствует ID, который отправил клиент, или строке, отправленной upstream, без учёта регистра.
• Где строки перекрываются, счётчик выбирает наиболее специфичную строку, а не первую строку: строку, чей model — это точная строка модели, отправленная upstream, затем строку, соответствующую точному ID, который отправил клиент, затем строку, называющую встроенную модель.
• Неизвестное имя upstream приводит к сбою при загрузке, как и две строки для одного upstream, которые называют одну и ту же модель, включая два написания одной встроенной модели. Gateway предупреждает при загрузке о строке, которую ни одна запрашиваемая модель не может использовать.
• Запросы веб-поиска остаются по цене $0.01 по прайс-листу; множитель всё ещё применяется к ним.

Для ставок по регионам дайте каждому региону свой именованный upstream и одну строку на upstream.

Отправка ставок подписанным клиентам

С v2.1.268 или позже на сервере gateway, gateway также помещает ставки из pricing в политики managed, которые он обслуживает, как управляемый параметр modelPricing. Разработчики, соответствующие политике, затем видят ставки pricing для первого upstream, который обслуживает каждый ID модели в /usage, строке состояния и OpenTelemetry. Разработчик, который не соответствует ни одной политике, не получает управляемые параметры, поэтому его цифры остаются по цене по прайс-листу. Клиенты применяют параметр в Claude Code v2.1.242 или позже.

• Что добавляет gateway: если блок cli политики уже не устанавливает modelPricing, gateway добавляет multiplier и, для каждого ID модели, который клиент может запросить, строку переопределения первого upstream, который обслуживает этот ID. Ставка, которую только failover upstream взимает, остаётся на gateway.
• Исключить одну политику: установите modelPricing на {} в блоке cli этой политики, и её разработчики остаются по цене по прайс-листу.
• Сохранить собственные ставки политики: политика, чей блок cli устанавливает modelPricing со своим собственным multiplier или overrides, сохраняет этот modelPricing целиком, и gateway не добавляет свои ставки к нему.

`models`

Блок models — это опциональный кураторский список моделей администратором, обслуживаемый в /v1/models и используемый для перевода ID моделей для каждого upstream. Требуется для регионов Bedrock, не входящих в США, ARN выделенной пропускной способности Amazon Bedrock и имён развёртываний Microsoft Foundry.

auto_include_builtin_models: true   # false: выставляйте только список ниже
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: опциональный текст, показываемый в клиентах, которые его выставляют
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # или ARN профиля вывода
      foundry: your-opus-deployment-name

Каждый ключ под upstream_model должен соответствовать name настроенного upstream, который по умолчанию является именем поставщика. Ключ, который не соответствует ни одному upstream, приводит к сбою при загрузке, поэтому опустите строки для поставщиков, которых вы не используете.

`managed`

Блок managed определяет политики доступа на основе ролей, ключённые на группы IdP или домен электронной почты. Политики оцениваются по порядку; первое совпадение выбирается, затем объединяется на базу match: {} catch-all, описанную ниже. Они обслуживаются для каждого пользователя в GET /managed/settings с кешированием ETag/304.

managed:
  policies:
    # Конкретные группы в первую очередь.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Catch-all по умолчанию в последнюю очередь: соответствует каждому аутентифицированному пользователю.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

Catch-all match: {}, обычно указываемый в последнюю очередь, рассматривается как базовый слой. Каждая другая политика наследует любой ключ, который она не устанавливает, из catch-all, поэтому записи для каждой роли должны только перечислять то, что отличается от организационного значения по умолчанию. Правила слияния зависят от типа ключа:

• Списки разрешений: availableModels и permissions.allow. Список конкретной политики полностью заменяет базовый.
• Списки запретов и массивы hooks: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces и каждый массив типа события hooks. Они берут объединение базового и политики, поэтому организационный запрет или hook аудита не может быть случайно удалён переопределением для каждой роли.
• Ключи типа Record: env, modelOverrides и skillOverrides. Эти поверхностные слияния, поэтому блок env для каждой роли переопределяет ключи, которые он устанавливает, и наследует остальное из базового.

availableModels также применяется на стороне сервера в /v1/messages, поэтому запрещённая модель возвращает 400 независимо от того, что отправляет клиент.

Gateway проверяет значение model перед тем, как передать запрос, поэтому неправильное значение никогда не достигает upstream. Он отклоняет запрос с 400 в двух случаях:

• Когда значение отсутствует или пусто, gateway отклоняет запрос с сообщением model is required. Эта проверка требует gateway, работающего на Claude Code v2.1.228 или позже.
• Когда значение присутствует, но не является строкой, gateway отклоняет запрос с сообщением model must be a string. Требует gateway, работающего на Claude Code v2.1.221 или позже.

Аутентифицированный пользователь, который не соответствует ни одной политике, получает значения по умолчанию gateway, что означает каждую модель в каталоге и никаких управляемых параметров. Добавьте catch-all match: {} в последнюю очередь, если вы хотите гарантированную политику по умолчанию.

Значения matcher, которые останавливают gateway при загрузке

При загрузке gateway проверяет блок match каждой политики и список admin_groups. Любое из этих значений останавливает gateway с ошибкой, которая называет поле:

• Пустой список groups
• Пустая запись в groups или в admin_groups
• Пустой email_domain
• email_domain, который содержит @, пробел или запятую. Gateway обрезает значение и удаляет один ведущий @ перед этой проверкой. Напишите один голый домен, такой как example.com.

До v2.1.232 gateway запускался с этими значениями. Каждое значение имело этот эффект:

• Пустой email_domain: gateway пропускал проверку домена, поэтому политика с пустым email_domain и без списка groups соответствовала каждому аутентифицированному пользователю
• Пустой список groups: политика не соответствовала никому
• email_domain, содержащий @, пробел или запятую: политика не соответствовала никому
• Пустая запись в groups или в admin_groups: запись соответствовала пользователю только, когда утверждение groups IdP этого пользователя также содержало пустую запись. В admin_groups это совпадение предоставляло доступ администратора. Если ваш список admin_groups никогда не содержал пустую запись, никто не получал доступ администратора таким образом.

Что входит в `cli`

Каждое значение cli — это полный документ Claude Code managed-settings.json, та же схема, которую вы развернули бы через MDM или /etc/claude-code/managed-settings.json, выраженная здесь как YAML. CLI применяет доставленный документ на управляемом уровне, выше параметров пользователя и проекта, вместо управляемых параметров сервера. Он поэтому игнорирует параметры ограниченные источниками политики на уровне ОС, такие как policyHelper и wslInheritsWindowsSettings.

Gateway проверяет каждый документ по схеме параметров CLI при загрузке, поэтому нераспознанный ключ верхнего уровня приводит к сбою загрузки с ошибкой, называющей каждый нарушающий ключ. Намеренно открытые части схемы всё ещё принимают произвольные значения, потому что более новые клиенты могут распознавать записи, которые схема gateway не распознаёт. Эти открытые ключи — env, pluginConfigs и ключи, вложенные под permissions.

Поскольку проверка использует схему, поставляемую с установленной версией gateway, размещение ключа параметров верхнего уровня, введённого более новым выпуском Claude Code, в управляемую конфигурацию требует сначала обновления gateway. Дымовой тест новой политики на одном клиенте перед развёртыванием.

Полный справочник ключей находится в Параметры Claude Code. Ключи, которые операторы достают в первую очередь:

managed:
  policies:
    - match: {}
      cli:
        # Доступ к модели (также применяется на стороне сервера в /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        # Политика разрешений
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # блокирует --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # игнорирует правила разрешений пользователя/проекта

        # Окружение, отправляемое в процесс CLI. DISABLE_UPDATES блокирует
        # фоновые и ручные обновления; DISABLE_AUTOUPDATER останавливает только
        # фоновые обновления.
        env:
          DISABLE_UPDATES: "1"                    # закрепите версии через вашу собственную дистрибуцию

        # Hooks на уровне организации. Команды hook запускаются на машинах разработчиков, не на
        # gateway, поэтому путь должен существовать на каждой ОС клиента в политике.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

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

• hooks
• переменные env, которые требуют одобрения разработчика, такие как переменные прокси и базового URL
• параметры выполнения оболочки, такие как apiKeyHelper и statusLine
• параметры двоичного файла sandbox sandbox.bwrapPath, sandbox.socatPath и sandbox.ripgrep
• Параметры Sandbox, которые перехватывают трафик, внедряют учётные данные или ослабляют изоляцию, такие как sandbox.network.tlsTerminate и параметры порта прокси. Диалоги одобрения безопасности перечисляют их все.

Память одобрения охватывает, как долго одобрение длится и когда диалог появляется снова.

Claude Code применяет некоторые доставленные переменные env без показа разработчику диалога одобрения безопасности, такие как параметры выбора модели и числовые ограничения. Другие доставленные переменные могут требовать одобрения разработчика перед вступлением в силу; непустое значение прокси, базового URL или OTEL_EXPORTER_OTLP_ENDPOINT всегда это делает. Когда доставленная переменная нуждается в одобрении, диалог называет её.

Переменные окружения и диалог одобрения имеет детали, включая четыре переключателя конфиденциальности, чьё доставленное значение решает, нуждаются ли они в одобрении. До v2.1.218 Claude Code применял меньше переменных без запроса разработчика, поэтому больше доставленных переменных запускали диалог.

Телеметрия gateway отправляет OTEL_EXPORTER_OTLP_ENDPOINT, поэтому установка telemetry.forward_to запускает диалог на каждом интерактивном клиенте. Диалог защищает машину разработчика от скомпрометированного или враждебного gateway, а не организацию от разработчика.

Неинтерактивный запуск с флагом -p не может показать диалог. Он применяет отправленные параметры только для этого запуска и не записывает их как одобренные, поэтому следующий интерактивный сеанс разработчика всё ещё показывает диалог. До версии 2.1.207 неинтерактивный запуск сохранял параметры как одобренные и ни один последующий интерактивный сеанс не показывал диалог для них.

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

Ключ cli был назван settings в более ранних выпусках. Это написание всё ещё принимается как псевдоним, но новые развёртывания должны использовать cli.

MCP серверы в политике

Чтобы предоставить MCP серверы клиентам Claude Code, которым соответствует политика, установите managedMcpServers в блоке cli этой политики. Вам нужен Claude Code v2.1.259 или позже на сервере gateway и на клиентах.

Gateway проверяет каждую запись при загрузке с теми же правилами, которые Claude Code применяет на клиенте, и если запись не проходит проверку, gateway отказывается запускаться и называет запись.

Если вы напишете ссылку ${VAR} в gateway.yaml, gateway разрешает её из своего окружения при загрузке через расширение секретов перед тем, как запустить проверки записей, поэтому каждый соответствующий клиент получает буквальное значение и может его прочитать. Руководство заголовка для предоставленных серверов применяется к расширенному значению.

Gateway отклоняет написание .mcp.json mcpServers в блоке cli, и его ошибка загрузки называет managedMcpServers как ключ для использования. До v2.1.259 gateway отклонял любое определение MCP сервера в блоке cli.

Наложение Claude Desktop

Если ваша организация также развёртывает Claude Desktop, один и тот же gateway обслуживает обоих клиентов. Укажите bootstrapUrl в управляемой конфигурации Claude Desktop на <listen.public_url>/user/bootstrap. Claude Desktop выводит издателя OAuth из этого URL, запускает ту же подпись входа с кодом устройства против этого gateway и получает свою конфигурацию из ответа.

Gateway выводит большую часть ответа из блока cli соответствующей политики и из конфигурации gateway верхнего уровня:

• Список моделей из availableModels

• Отключённые инструменты из записей permissions.deny с названием инструмента. Если вы установите disabledBuiltinTools в блоке desktop политики, gateway обслуживает объединение вашего значения и выведённого списка, поэтому вы можете отключить больше инструментов таким образом, но не можете повторно включить инструмент, который вы отключили через permissions.deny

• Список разрешений исходящего трафика из sandbox.network.allowedDomains. Если вы установите coworkEgressAllowedHosts в блоке desktop политики, gateway использует это значение вместо выведённого списка

• Конечная точка OTLP, которая указывает на сам gateway, и атрибуты идентификации подписанного пользователя. Gateway передаёт экспорты, которые он получает в этой конечной точке, вашим назначениям forward_to. Он включает конечную точку и атрибуты, когда вы устанавливаете оба telemetry.forward_to и listen.public_url.

  Claude Desktop экспортирует каждый сигнал с одной кодировкой: http/protobuf, или http/json, когда вы установите OTEL_EXPORTER_OTLP_PROTOCOL или один из его вариантов для каждого сигнала на http/json в env политики. До Claude Code v2.1.261 на сервере gateway ответ установил http/json независимо, поэтому сборщик, который принимает только protobuf, отклонил экспорты Claude Desktop

Чтобы установить disabledBuiltinTools, coworkEgressAllowedHosts или собственный параметр managedMcpServers Claude Desktop в блоке desktop политики, вам нужен Claude Code v2.1.232 или позже на сервере gateway. managedMcpServers Claude Desktop принимает значение массива, а не объекта.

Gateway опускает ключи без эквивалента Claude Desktop, такие как hooks и ограниченные правила разрешений, такие как Bash(npm *), из ответа bootstrap.

Добавьте опциональный блок desktop рядом с cli для установки параметров Claude Desktop напрямую. Напишите параметры из справочника управляемой конфигурации Claude Desktop как плоские имена ключей. Не включайте ключи, которые Claude Desktop читает только из MDM или локальных файлов, такие как bootstrapUrl; gateway отклоняет их при загрузке. До v2.1.232 gateway принимал фиксированный список из 11 ключей функциональных ворот, такие как chatTabEnabled и disableAutoUpdates, и отклонял каждый другой ключ при загрузке. До v2.1.227 gateway также отклонял chatTabEnabled и chatAdvancedFileAnalysisEnabled при загрузке.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

Каждый ключ опциональный; Claude Desktop применяет свой собственный по умолчанию для любого ключа, который вы опустите. Gateway проверяет каждый блок desktop при загрузке по схеме конфигурации, которую сам использует Claude Desktop, поэтому ошибка появляется при запуске gateway как ошибка, называющая ключ, а не достигает каждого подключённого desktop. Gateway не запускается при загрузке, когда блок содержит:

• Неизвестный ключ
• Узнанный ключ, чьё значение Claude Desktop отклонил бы или молча отбросил, такой как пустое значение или неправильно написанный подключ внутри вложенной записи. До v2.1.260 gateway молча отбросил неправильно написанное поле внутри вложенного объекта записи managedMcpServers или orgPluginSettings вместо отказа при загрузке.
• Ключ, который gateway вычисляет сам: соединение вывода, список моделей и реле OTLP. Настройте их через upstreams, models и раздел telemetry forward_to.
• Устаревший псевдоним текущего ключа. В ошибке загрузки gateway называет канонический ключ для написания.

Если вы используете устаревшее значение или форму записи, такую как запись managedMcpServers без transport, gateway запускается и регистрирует предупреждение, которое называет замену.

Gateway проверяет блок desktop по схеме, поставляемой с его установленной версией, как он делает блок cli. Чтобы доставить параметр, введённый более новым выпуском Claude Desktop, сначала обновите gateway. Например, userPluginMarketplacesEnabled и userPluginUploadsEnabled нуждаются в Claude Code v2.1.260 или позже на сервере gateway и Claude Desktop 1.37937.0 или позже на машинах членов.

Если вы установите orgPluginSettings в блоке desktop политики, gateway обслуживает его в форме массива, которую читают Claude Desktop 1.15200.0 и позже. Более старые desktops игнорируют массив и не применяют политику инструмента плагина, поэтому обновите членов до 1.15200.0 или позже перед тем, как полагаться на это.

Gateway заполняет ключи, которые блок desktop политики не устанавливает, из блока desktop catch-all match: {}, так же, как он заполняет блок cli политики из базового. Если вы установите disabledBuiltinTools или builtinToolPolicy в обоих базовом и политике роли, gateway сохраняет ограничение базового:

• disabledBuiltinTools: gateway использует объединение списка базового и списка политики
• builtinToolPolicy: если вы установите инструмент на значение, отличное от allow, в базовом, gateway сохраняет это значение, даже если вы установите allow для того же инструмента в политике роли

Для каждого другого ключа, если вы установите его в политике роли, gateway использует значение политики роли. Gateway заменяет массив или вложенный объект, такой как banner, целиком, поэтому если вы установите banner.text в политике роли, gateway отбросит banner.backgroundColor базового.

Если вы не развёртываете Claude Desktop, вообще не включайте desktop в ваши политики; gateway затем возвращает 404 из /user/bootstrap для каждого пользователя.

Приоритет с другими управляемыми источниками

Если устройство также имеет политику, доставленную MDM, или локальный managed-settings.json, параметры, доставленные gateway, занимают первое место. Приоритет в управляемом уровне на странице управляемых параметров говорит, когда применяются локальные источники, и имеет ключи, которые Claude Code читает из каждого источника администратора независимо от того, какой источник он выбрал, такие как ключи блокировки sandbox, forceRemoteSettingsRefresh и для каждой переменной env слияние. policyHelper, настроенный в профиле MDM или файле управляемых параметров, запускается только, когда gateway не доставляет параметры; запись говорит, что его вывод заменяет.

Встраивающие хосты, такие как Claude Desktop, могут предоставлять политику через опцию SDK managedSettings. Параметры родителя из встраивающих хостов говорит, когда Claude Code применяет это, и Ограничить параметры родителя перечисляет, какие параметры в направлении разрешения всё ещё применяются без блокировок allowManaged*Only.

Политики gateway применяются к каждому вызову Claude Code на машине, включая неинтерактивные запуски claude -p и сеансы, порождённые Agent SDK. Если gateway недоступен при запуске, сеансы с выполненным входом завершаются с ошибкой, а не работают без своей политики.

`telemetry`

CLI отправляет метрики, логи и, когда включено, трассировки на gateway, который передаёт их дословно каждому настроенному назначению. Экспорты используют OpenTelemetry Protocol (OTLP) по HTTP. Чтобы пропустить реле и иметь сеансы, экспортирующие прямо на ваш сборщик, назовите сборщик в политике. См. Мониторинг использования для метрик и событий, которые выпускает CLI.

CLI штампует каждый экспорт идентификацией аутентифицированного пользователя, прочитанной из JWT, выданного gateway: атрибуты user.id, user.email и user.groups. Атрибуция затрат и использования для каждого разработчика поэтому работает без конфигурации на стороне разработчика.

Claude Desktop и сеансы Cowork, подписанные через gateway, штампуют свою телеметрию с user.email и user.groups наряду с enduser.id, поэтому вы можете охватить использование терминала, Desktop и Cowork одним запросом на user.email или user.groups. user.groups — это список групп IdP, разделённый запятыми.

Как и все данные OpenTelemetry из Claude Code, эти атрибуты идут только на назначения, которые настраивает ваша организация, никогда на Anthropic.

Если список групп пользователя длиннее 255 символов после процентного кодирования, или имя группы содержит запятую или знак равенства, gateway оставляет user.groups из телеметрии Desktop и Cowork этого пользователя, а не усекает его. Сеансы терминала этого пользователя всё ещё несут полный список.

Вам нужен Claude Code v2.1.265 или позже на сервере gateway для user.email и user.groups на телеметрии Desktop и Cowork, и Claude Desktop 1.24012 или позже на машине каждого разработчика для user.groups.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Opt-in для каждого сигнала. По умолчанию: только метрики.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

Каждый URL forward_to должен использовать https://, с одним исключением для сборщика на собственном интерфейсе loopback gateway:

• http://localhost:<port> проходит проверку конфигурации, но защита SSRF блокирует каждый экспорт с ECONNREFUSED_SSRF, если вы не установите CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 в окружении gateway
• http://127.0.0.1:<port> или http://[::1]:<port> не запускается при загрузке, если эта переменная не установлена

Для сборщика в кластере выставьте его по HTTPS на его собственный внутренний адрес или запустите его как sidecar с установленной переменной.

Телеметрия отключена в CLI по умолчанию. Когда вы устанавливаете оба telemetry.forward_to и listen.public_url, gateway включает её для подключённых клиентов, отправляя шесть переменных окружения через /managed/settings:

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER и OTEL_TRACES_EXPORTER, каждый установлен на otlp, если по крайней мере одно назначение forward_to включает этот сигнал, и на none в противном случае
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

До Claude Code v2.1.265 на сервере gateway, gateway отправлял все три селектора экспортера как otlp, включая для сигналов, которые ни одно назначение не включало.

Отправленная конечная точка строится из публичного URL, поэтому метрики и логи не нуждаются в конфигурации OTEL от разработчиков или политик.

Разработчики, подписанные через /login, не могут перенаправлять экспорты с собственной конфигурацией OTEL:

• Локально установленные переменные: Claude Code применяет отправленные переменные на управляемом уровне, поэтому каждая переопределяет значение, которое разработчик устанавливает для неё локально.
• Локально настроенные конечные точки: с включённым экспортом OTLP/HTTP, CLI игнорирует любую локально настроенную конечную точку, независимо от того, отправил ли gateway переменные телеметрии. Его экспорты идут на gateway, если политика не называет ваш сборщик как конечную точку.

Без назначения forward_to для сигнала, gateway принимает и отбрасывает его. Если разработчики уже экспортируют телеметрию Claude Code на один из ваших сборщиков, добавьте его как назначение forward_to, с включёнными логами или трассировками, если они их экспортируют, поэтому он продолжает получать их данные после того, как они подпишутся. Чтобы пропустить реле вместо этого, назовите сборщик в политике.

Трассировки дополнительно требуют CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 на каждом клиенте. Установите её в блоке env управляемой политики, так как gateway не отправляет её. Разработчики одобряют её в том же диалоге одобрения безопасности, который отправленная конечная точка уже запускает.

Установите её на 1 только в политиках, чьи группы вы хотите отследить. Политика, которая не устанавливает её, наследует значение из вашей политики match: {} catch-all, если эта политика устанавливает одно, согласно правилам слияния. Чтобы помешать клиентам группы отправлять трассировки, даже когда разработчик устанавливает переменную локально, установите её на 0 в политике этой группы.

Оба кодирования OTLP protobuf и JSON передаются, и любой совместимый с OpenTelemetry backend работает как назначение.

Экспорт прямо на ваш сборщик

Чтобы иметь сеансы, подписанные через /login, отправлять телеметрию прямо на ваш сборщик вместо реле, установите OTEL_EXPORTER_OTLP_ENDPOINT на базовый URL https:// сборщика в блоке env управляемой политики. Claude Code добавляет /v1/metrics, /v1/logs или /v1/traces к URL, который вы устанавливаете, такой как https://otel-collector.example.com:4318, и экспортирует каждый сигнал туда по OTLP/HTTP. Требует Claude Code v2.1.265 или позже на машине каждого разработчика. Более ранние клиенты экспортируют через реле.

Чтобы аутентифицироваться на сборщик, установите OTEL_EXPORTER_OTLP_HEADERS в том же блоке env. Сеансы никогда не отправляют токен сеанса gateway разработчика на сборщик, названный таким образом.

Когда вы добавляете или изменяете эту конечную точку в политике, Claude Code просит каждого разработчика одобрить её в диалоге одобрения безопасности перед применением её в интерактивном сеансе.

Claude Code проверяет конечную точку перед экспортом сигнала прямо и сохраняет этот сигнал на реле, когда проверка не удаётся. Проверки включают:

• Конечная точка поступает от самого gateway. Если вы устанавливаете ту же переменную в профиль MDM или локальный managed-settings.json, экспорты остаются на реле.
• URL использует https://, или http:// на адрес loopback
• URL разрешается на путь, заканчивающийся на /v1/<signal>, без запроса или фрагмента. Claude Code строит этот путь сам из универсальной переменной. Он использует переменную для каждого сигнала, такую как OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, как написано, поэтому включите полный путь туда.
• URL не является собственным хостом gateway. Конечная точка, адресованная gateway, сохраняет путь реле и его токен сеанса.
• Ни вы, ни разработчик не настроили otelHeadersHelper ни в каком источнике параметров. С настроенным помощником, каждый сигнал остаётся на реле.

Конечная точка, которую вы называете, изменяет только то, куда идут экспорты. Вы всё ещё выбираете, какие сигналы экспортируют вообще с селекторами OTEL_*_EXPORTER.

Конечная точка одна не включает экспорт, поэтому также установите переменные, которые это делают, если только gateway уже не отправляет их:

• Если gateway уже отправляет переменные телеметрии, они охватывают включение, селекторы и протокол, и ваша явная конечная точка переопределяет отправленное значение <public_url>. Установите селектор OTEL_*_EXPORTER на otlp сами только для сигнала, который ни одно назначение forward_to не включает.
• Если это не так, также установите CLAUDE_CODE_ENABLE_TELEMETRY=1, селекторы OTEL_*_EXPORTER и OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Когда разработчик выходит, или подписывается на другой gateway, экспорты на сборщик останавливаются и Claude Code отбрасывает каждый оставшийся пакет, а не отправляет его.

Когда назначение не удаётся

Gateway не буферизирует, не повторяет и не хранит телеметрию, поэтому он отбрасывает экспорт, который не достигает назначения, а не доставляет его поздно. Каждое назначение успешно или не удаётся само по себе, и экспортирующий клиент получает ответ об успехе в любом случае, поэтому неудачная доставка появляется только в журнале gateway.

После пяти последовательных неудачных доставок на назначение, gateway приостанавливает переадресацию на него в 30-секундных растяжениях, регистрируя каждую паузу, пока доставка не удаётся. Любой ответ об ошибке, timeout или ошибка соединения считаются неудачной доставкой, кроме 400, 413, 415, 422 и 431, которые означают, что сборщик отклонил полезную нагрузку этого экспорта как неправильно сформированную или слишком большую.

Отклонённая полезная нагрузка ни продвигает, ни сбрасывает счётчик отказов: gateway продолжает переадресацию на назначение и регистрирует предупреждение, называющее его и статус, при первом отказе назначения и каждом сотом после.

HTTP tuning

Четыре опциональных блока верхнего уровня, access_control, limits, timeouts и rate_limits, настраивают HTTP поверхность. Значения по умолчанию подходят для большинства развёртываний.

Полный пример

Эта полная справочная конфигурация охватывает каждый основной раздел; блоки HTTP tuning сохраняют свои значения по умолчанию. Скопируйте её, удалите то, что вам не нужно, и заполните свои значения. Конфигурация в Quickstart — это минимальная версия этого.

# Запустите с:
#   claude gateway --config gateway.yaml
#
# Многословность операционного журнала управляется переменной окружения
# CLAUDE_GATEWAY_LOG_LEVEL (debug | info | warn | error; по умолчанию info). debug
# также регистрирует имена утверждений в каждом id_token для диагностики groups_claim.
# Это не влияет на события аудита, которые всегда выпускаются.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Опустите блок tls при запуске за TLS-завершающим ingress.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Требуется, когда издатель — сервер организации Okta, чьи id_tokens
  # могут опускать электронную почту и группы; gateway заполняет их из /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta выпускает группы только, когда область `groups` запрашивается и
  # фильтр утверждения groups приложения их разрешает. Политика подрядчиков ниже
  # соответствует группам, поэтому область запрашивается здесь.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Роли приложения Entra: используйте `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5

# Включает /v1/organizations/spend_limits (отражает публичный Admin API Anthropic)
# и применение расходов для каждого разработчика на /v1/messages. Опустите для отключения.
# Сами ограничения устанавливаются через admin API, а не здесь.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

# Измеряйте по договорным ставкам вместо цены USD в прайс-листе. Требует admin:.
# Ставки ниже — это заполнители, а не реальные договорные цены.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # Ограничьте опцию Default picker на availableModels вместо
        # значения по умолчанию уровня, поэтому подрядчики не получают 400 по умолчанию.
        enforceAvailableModels: true
        # allow автоматически одобряет эти инструменты; это не блокирует остальное.
        # Добавьте правила deny для ограничения инструментов.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

Управляемые параметры на стороне клиента

Всё выше настраивает сервер gateway. Указание машин разработчиков на него настраивается отдельно, на каждом устройстве, через управляемые параметры Claude Code. Gateway не может отправлять эти ключи сам, потому что они говорят клиенту, где находится gateway.

Для CLI установите эти ключи в managed-settings.json для каждой ОС. Два ключа входа маршрутизируют /login каждого разработчика на ваш gateway:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

parentSettingsBehavior: "merge" сохраняет доставку Claude Desktop списка разрешённых исходящих соединений в его встроенные сеансы Claude Code; Доставка политики в сеансы Claude Desktop объясняет механизм и где должно находиться согласие.

Развёртывайте файл managed-settings.json на каждое устройство, обычно через вашу платформу MDM. Путь файла отличается по платформе. См. где каждый механизм хранит политику.

По умолчанию политика реестра в Windows или управляемые предпочтения plist в macOS заменяют файл managed-settings.json вместо слияния с ним, за исключением ключей исключения и проверок между источниками выше. Все три ключа в этом фрагменте следуют правилу источника с наивысшим приоритетом, поэтому парки, которые доставляют политику через Group Policy или профили конфигурации, должны поместить все три в этот механизм вместо этого.

Для Claude Desktop установите ключ bootstrapUrl в собственной управляемой конфигурации Claude Desktop на <listen.public_url>/user/bootstrap. Поток входа и политика для каждой группы затем совпадают с CLI после того, как политика на стороне сервера даёт согласие ключом desktop; без этого согласия /user/bootstrap возвращает 404. См. Наложение Claude Desktop для серверной части.

forceLoginGatewayUrl и значение "gateway" forceLoginMethod соблюдаются только из управляемого источника на машине: managed-settings.json, plist macOS или реестр HKLM Windows, или помощник политики. Разработчик, устанавливающий их в своём собственном ~/.claude/settings.json, не имеет эффекта, и также не имеет эффекта установка их в полезной нагрузке gateway.

Связанное

• Обзор Claude apps gateway: quickstart и подключение разработчика
• Руководство по развёртыванию: настройка IdP, образ контейнера, Kubernetes и Cloud Run, и операции
• Лимиты расходов: ограничения для каждого разработчика и Admin API