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

​

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

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

• login_notice: уведомление, которое разработчики видят при входе
• 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
• load_test_mode: нагрузочное тестирование gateway без вызова поставщика модели

​

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

​

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

​

listen

​

oidc

​

Аутентификация клиента по сертификату

openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"

oidc:
  issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
  client_id: <application-id>
  token_endpoint_auth_method: private_key_jwt
  client_assertion:
    private_key_pem: ${file:/etc/gateway/idp-client.key}
    certificate_pem: ${file:/etc/gateway/idp-client.crt}

[gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct  1 23:07:31 2027 GMT

​

Ротация сертификата клиента

1. Загрузите новый сертификат в IdP в дополнение к старому.
2. Замените файлы ключа и сертификата, которые загружает gateway.yaml, затем перезапустите шлюз. Если вы запускаете несколько реплик, подойдёт последовательный перезапуск, потому что у IdP есть оба сертификата, пока вы не удалите старый.
3. После перезапуска всех реплик удалите старый сертификат из IdP.

​

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

​

Исходящий трафик только через прокси

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

• Задан HTTPS_PROXY или HTTP_PROXY.
• NO_PROXY и no_proxy пусты. Если ваша платформа внедряет любую из них в поды, задайте обеим пустое значение в контейнере шлюза. Если указать сборщик телеметрии в NO_PROXY, исходящий трафик только через прокси останется выключенным.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK не включена. Сборщик или IdP на собственном loopback пода нельзя сочетать с исходящим трафиком только через прокси, потому что loopback-адрес, переданный прокси, указывал бы на сам хост прокси, поэтому дайте этим сервисам адрес, доступный для прокси. По той же причине, пока исходящий трафик только через прокси активен, шлюз полностью отклоняет имена вида localhost.

​

session

​

store

​

upstreams

​

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

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

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

​

Anthropic API

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # ИЛИ OAuth Bearer-токен (например, токен, полученный через 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 и обновляйте переменную окружения.
• oauth_token: отправляет Authorization: Bearer. Используйте Bearer-форму, если ваша организация выдаёт короткоживущие токены вместо долгоживущих API-ключей. Bearer-токен читается один раз при запуске, поэтому для обновления перемонтируйте секрет и перезапустите шлюз.

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        # default false

​

Amazon Bedrock

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferred: AWS default credential chain
    # OR explicit credentials:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OR a Bedrock API bearer token:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

Применение guardrail Amazon Bedrock

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # guardrail ID or full ARN
      version: "1"                     # a published version number, or DRAFT
 # keep the quotes: a bare 1 fails at boot

Добавление входных тегов guardrail

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
      input_tagging: user_messages

Что не покрывают входные теги

• Содержимое, которое шлюз не помечает: сообщения, не охваченные вашим значением input_tagging, определения инструментов, входные данные вызовов инструментов, изображения и PDF, среди прочего. Если не задано all_messages_and_system, системный промпт тоже не помечается.
• Результаты инструментов: они содержат то, что возвращают инструменты Claude, например содержимое файлов и веб-страницы. В тестах Anthropic фильтр слов не оценивал их ни с тегами, ни без них.

Запись в лог сработавшего фильтра guardrail

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
    guardrail_trace: true              # default false; beside guardrail, not inside it

Bedrock в другом аккаунте AWS

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # when the role's trust policy requires one

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
  }]
}

• Если STS отклоняет вызов или недоступен, шлюз не отправляет запрос с собственными учётными данными upstream. Он записывает в лог ошибку STS с указанием, что проверить, затем пробует следующий указанный вами upstream. Что получает клиент, если ни один upstream не справился, описано в разделе Сообщения об ошибках upstream. Следующий upstream без assume_role обслужит запрос со своими учётными данными, поэтому указывайте такой upstream, только если вам нужно именно это.
• Шлюз вызывает региональный эндпоинт STS sts.<region>.amazonaws.com, который должен быть доступен из его сети. Для эндпоинта FIPS задайте AWS_USE_FIPS_ENDPOINT=true в окружении шлюза, а не use_fips_endpoint в файле конфигурации AWS.
• assume_role требует исходных учётных данных SigV4: шлюз не запустится, если он задан вместе с aws_bearer_token.
• Без списка groups этот вышестоящий сервер может использовать каждый разработчик, которого допускает шлюз. Чтобы ограничить, какие модели может использовать разработчик, задайте availableModels в политике managed.
• Чтобы модель, обслуживаемая через роль, не обслуживалась также из другого аккаунта, дайте ей пользовательский id, карта upstream_model которого содержит только имя этого вышестоящего сервера. Для такого id шлюз пропускает все остальные вышестоящие серверы, поэтому ни сам запрос, ни подсчёт токенов для прерванного запроса не могут переключиться на другой аккаунт.
• Запрос встроенного имени модели всё равно может дойти до этого вышестоящего сервера, и шлюз подписывает его той же ролью. Указывайте этот вышестоящий сервер последним, если его аккаунт не должен также обслуживать эти модели.

models:
  - id: restricted-claude-opus-4-8      # a custom id, not a built-in model name
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # the only upstream that serves it

Учёт затрат AWS по разработчикам

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # or sub

​

Эндпоинт Amazon Bedrock Mantle

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # required
    auth: {}                           # AWS default credential chain
  - provider: bedrock
    region: us-east-1
    auth: {}

• guardrail: шлюз не применяет guardrail Bedrock к запросам, которые отправляет в Mantle, поэтому отказывается запускаться, если указан upstream mantle, а для какого-либо upstream bedrock задан guardrail.
• assume_role: задайте его для самого вышестоящего сервиса mantle. Без него запросы, обслуживаемые Mantle, отправляются с собственными учётными данными auth вышестоящего сервиса mantle.

​

Claude Platform on AWS

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # sent as x-api-key
    # OR SigV4 via the AWS default credential chain:
    # auth: {}
    # OR explicit SigV4 credentials:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Override the derived endpoint:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

​

Google Cloud Agent Platform

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferred: Application Default Credentials
    # OR a service account key file:
    # auth: { service_account_json: /secrets/sa.json }
    # Override the aiplatform endpoint for Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

​

Microsoft Foundry

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferred: DefaultAzureCredential / Managed Identity
    # OR an API key:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

​

Статические заголовки в запросах к upstream

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

• authorization и x-api-key
• host, content-type и user-agent
• Любое имя, начинающееся с anthropic-, x-goog-, x-amz- или x-amzn-

​

Несколько upstream

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

• Upstream provider: anthropic: timeouts.upstream_ttfb_ms, по умолчанию 120 секунд
• Другие поставщики: до одного часа. Чтобы сократить это ожидание для потоковых запросов, задайте timeouts.upstream_ttfb_ms на шлюзе v2.1.295 или новее. Непотоковые запросы к модели в любом случае ждут до одного часа

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

​

Направление каждой команды к своему вышестоящему провайдеру

upstreams:
  - name: bedrock-payments
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
    groups: [payments-eng]
  - name: bedrock-search
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
    groups: [search-eng]
  - name: bedrock-shared               # no groups: open to everyone, so listed last
    provider: bedrock
    region: us-east-1
    auth: {}

• Значения: записывайте каждую группу точно так, как ваш IdP передаёт её в claim групп, который также читает match.groups. Шлюз отказывается запускаться, если находит пустой список или пустое значение. Он не сверяет значения с вашим IdP, поэтому значение, которому никто не соответствует, не вызывает предупреждения.
• Порядок: размещайте вышестоящего провайдера без списка groups последним. Он обслуживает всех, поэтому, если указать его раньше, он будет перехватывать запросы команды до её собственного провайдера.

Что происходит, если разработчик не входит ни в одну из перечисленных групп

API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one

• Задан oidc.allowed_groups: шлюз отклоняет обновление, и сессия завершается
• Иначе, если у какого-либо вышестоящего провайдера нет списка groups: запросы разработчика переходят к нему
• Иначе, если у каждого вышестоящего провайдера есть список groups: запросы разработчика завершаются этой ошибкой

​

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

​

login_notice

login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

​

admin

admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  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 groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits
  # Try eng-platform's pooled budget first, then eng-all's, then any other group's.
  pooled_conflict_rule: priority_list
  pooled_priority_order: [eng-platform, eng-all]

​

Порядок общих бюджетов

• default_order: сначала самый большой лимит, а равные лимиты — по возрастанию имени группы
• priority_list: бюджеты групп из pooled_priority_order в порядке списка, затем бюджеты остальных групп по имени группы

​

enforcement

​

pricing

• Claude Code v2.1.227 или новее на сервере шлюза. Более ранние версии отклоняют неизвестный ключ при запуске.
• Блок admin: или, в v2.1.268 и новее, блок managed: хотя бы с одной политикой. Шлюз отказывается запускаться, если задан 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 с одной и той же моделью, включая два написания одной встроенной модели. Шлюз выдаёт предупреждение при запуске о строке, которую не может использовать ни одна запрашиваемая модель.
• Запросы веб-поиска остаются по прейскурантной цене $0.01; множитель к ним всё равно применяется.

​

Наценка на цены

pricing:
  multiplier: 1.2

​

Отправка тарифов клиентам, вошедшим в систему

• Что добавляет шлюз: если блок cli политики ещё не задаёт modelPricing, шлюз добавляет multiplier и, для каждого ID модели, который может запросить клиент, строку переопределения первого upstream, обслуживающего этот ID. Тариф, который взимает только резервный upstream, остаётся на шлюзе.
• Upstream со списком groups: если такой upstream — первый, обслуживающий ID модели, шлюз не добавляет строку для этого ID. Тогда разработчики видят собственную ставку Claude Code для этого ID — стандартную ставку модели, если Claude Code распознаёт ID, — умноженную на multiplier.
• Исключение отдельной политики: установите modelPricing в {} в блоке cli этой политики, и её разработчики останутся на прейскурантных ценах.
• Сохранение собственных тарифов политики: политика, блок cli которой задаёт modelPricing с собственными multiplier или overrides, сохраняет этот modelPricing целиком, и шлюз не добавляет в него свои тарифы.

​

models

auto_include_builtin_models: true   # false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # or an inference-profile ARN
      foundry: your-opus-deployment-name

​

managed

managed:
  policies:
    # Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Make the Default option in /model resolve inside each policy's
        # list. The eng-contractors policy inherits enforceAvailableModels.
        enforceAvailableModels: true

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

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

​

Применение всех подходящих политик

managed:
  policy_mode: layered
  policies:
    - match: { groups: [no-web] }
      cli:
        permissions: { deny: ["WebFetch"] }
    - match: { groups: [opus-users] }
      cli:
        availableModels: [opus, sonnet]
    - match: {}
      cli:
        availableModels: [sonnet]
        enforceAvailableModels: true

• Списки разрешённых, одиночные значения и блоки, такие как sandbox: каждый берётся целиком из первой по порядку подходящей политики, которая его задаёт, поэтому списки availableModels двух групп не суммируются.
• Списки запрещённых и массивы хуков: суммируются по всем подходящим политикам, поэтому пользователь в двух группах получает правила запрета обеих групп.
• env, modelOverrides и skillOverrides: записи объединяются по имени, и значение для имени берётся из первой по порядку подходящей политики, которая его задаёт.
• Ключи desktop: объединяются по правилам для базового блока desktop.

• Шаблон с !: отрицание ! в правиле Read или Edit в списке permissions.deny или permissions.ask любой политики, включая политику match: {}
• Ограничение хуков вне политики, охватывающей всех: disableAllHooks, allowedHttpHookUrls или httpHookAllowedEnvVars в любой политике, кроме match: {}

​

Запуск сессий на модели, разрешённой политикой

• Псевдоним, например sonnet, или встроенный ID, например claude-sonnet-4-6: сессии запускаются на одной из этих моделей, и вариант Default в /model указывает на неё
• В списке нет ни псевдонима, ни встроенного ID: сессии могут продолжать запускаться на встроенной модели по умолчанию, поэтому также установите model в один из перечисленных ID в блоке cli этой политики

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [restricted-claude-opus-4-8]
        enforceAvailableModels: true
        model: restricted-claude-opus-4-8
        env:
          ANTHROPIC_DEFAULT_OPUS_MODEL: restricted-claude-opus-4-8   # opus and Default resolve to the ID too

​

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

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

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

​

Выбор между cli и code

• cli: терминал, расширения VS Code и JetBrains, а также Agent SDK. При cli вкладка Code в Claude Desktop получает производные настройки, поэтому ограниченное правило, например Read(./.env), не останавливает там пользователя.
• code: те же места, и при этом может быть охвачена вкладка Code в Claude Desktop.

managed:
  policies:
    - match: {}
      code:
        permissions: { deny: ["Read(./.env)"] }
      desktop: {}

• Чтобы охватить вкладку Code: перейдите на code, как только машины пользователей будут соответствовать условиям из раздела Применение настроек code во вкладке Code
• Чтобы остаться на cli: установите serve_to_desktop: false рядом с cli в политике, чтобы убрать предупреждение

​

Что помещать в cli

managed:
  policies:
    - match: {}
      cli:
        # Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        enforceAvailableModels: true              # Default resolves inside the list

        # Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignore user/project permission rules

        # Environment pushed into the CLI process. DISABLE_UPDATES blocks
        # background and manual updates; DISABLE_AUTOUPDATER stops only
        # background updates.
        env:
          DISABLE_UPDATES: "1"                    # pin versions via your own distribution

        # Org-wide hooks. Hook commands run on developer machines, not the
        # gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

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

​

Проверка политики перед развёртыванием

​

Контекстное окно в сессиях терминала

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

​

Часовой кэш промптов

managed:
  policies:
    - match: {}
      cli:
        promptCacheTtl: 1h
        subagentPromptCacheTtl: 1h

​

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

​

Наложение для Claude Desktop

Настройки, которые шлюз выводит для Claude Desktop

• Список моделей — из availableModels. В список не входят модели, которые политика блокирует с помощью deniedModels или availableModelsMatch: exact. Этот фильтр требует Claude Code v2.1.299 или новее на сервере шлюза. Вариант контекста 1M для каждой модели описан в разделе Расширенный контекст в Claude Desktop
• Отключённые инструменты — из записей permissions.deny, содержащих только имя инструмента. Если вы задаёте disabledBuiltinTools в блоке desktop политики, шлюз отдаёт объединение вашего значения и выведенного списка, поэтому так можно отключить больше инструментов, но нельзя снова включить инструмент, отключённый через permissions.deny
• Список разрешённых адресов для исходящего трафика — из sandbox.network.allowedDomains. Если вы задаёте coworkEgressAllowedHosts в блоке desktop политики, шлюз использует это значение вместо выведенного списка. Если список разрешённых, который отдаёт шлюз, включает * и шлюз при этом не отдаёт allowedWorkspaceFolders для Claude Desktop, Claude Desktop не включает песочницу Bash во вкладке Code
• Эндпоинт OTLP, указывающий на сам шлюз, и атрибуты идентичности вошедшего пользователя. Шлюз пересылает экспорты, полученные на этом эндпоинте, в ваши назначения 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 на сервере шлюза ответ в любом случае задавал http/json, поэтому коллектор, принимающий только protobuf, отклонял экспорты Claude Desktop

Применение настроек code во вкладке Code

• У политики также есть ключ desktop, причём пустой desktop: {} тоже считается
• Claude Desktop версии 2.9939.2 или новее
• Управляемые настройки Claude Code на машине указывают этот шлюз
• Эта машина обращается к шлюзу по HTTPS в частной сети

• По HTTPS, если Claude Desktop поставляется с Claude Code v2.1.296 или новее: вкладка Code не запускается, а ответ на промпт пользователя объясняет причину
• По HTTPS, если Claude Desktop поставляется с более ранней версией: вкладка Code запускается без ваших настроек code, и ничто в сессии об этом не сообщает
• По обычному HTTP: вкладка Code запускается без ваших настроек code, независимо от версии, с которой поставляется Claude Desktop

Прямое задание настроек Claude Desktop

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

Что шлюз отклоняет при запуске

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

Ключи, требующие более новой версии шлюза или Claude Desktop

Как ролевая политика наследует базовый блок desktop

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

Когда изменение политики доходит до Claude Desktop

• Закрыт: Claude Desktop получает ответ bootstrap при запуске, поэтому изменение применяется со следующего запуска
• Открыт: Claude Desktop по умолчанию каждые 10 минут проверяет, изменился ли ответ, и применяет некоторые настройки без перезапуска. Для остальных, например skillCreationEnabled, пользователь видит карточку Relaunch Claude Desktop на боковой панели и сохраняет прежнюю конфигурацию, пока не перезапустит приложение. По умолчанию через 24 часа Claude Desktop показывает диалоговое окно перезапуска и перезапускается сам после 2 минут бездействия

​

Расширенный контекст в Claude Desktop

• Upstream, способный обслуживать запись, сопоставляет её с моделью без поддержки 1M, включая upstream, к которому шлюз обращается только при отказе основного
• Ни её id, ни одно из значений upstream_model не называет модель Claude, например пользовательский псевдоним, направленный на ARN профиля инференса приложения

• Запуск пользователей на варианте 1M: установите modelPrefer1mContext: true в блоке desktop политики. Пользователи, ещё не выбравшие модель, начинают с варианта 1M, если он есть у первой указанной модели. Пользователи, уже выбравшие модель, сохраняют свой выбор.
• Ручное предложение варианта: сделайте это, если сервер шлюза работает на версии старше v2.1.284 или запись не называет модель Claude. Укажите модель в models дважды: один раз с простым ID и один раз с добавленным [1m], оба раза с одной и той же картой upstream_model. Claude Desktop показывает пару как одну модель с вариантом 1M. Шлюз отдаёт запись [1m] без проверки, поэтому добавляйте её только для модели, которую ваши upstream обслуживают с 1M.

models:
  - id: corp-sonnet
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod
  - id: corp-sonnet[1m]
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

managed:
  policies:
    - match: {}
      desktop:
        modelPrefer1mContext: true

Удаление варианта 1M

​

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

​

telemetry

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

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

• 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 применяет переданные переменные на управляемом уровне, поэтому каждая из них переопределяет значение, которое разработчик задаёт для неё локально.
• Локально настроенные эндпоинты: при включённом экспорте OTLP/HTTP CLI игнорирует любой локально настроенный эндпоинт, независимо от того, передал ли шлюз переменные телеметрии. Его экспорт идёт на шлюз, если политика не указывает ваш коллектор в качестве эндпоинта.

​

Отправка кумулятивных метрик

• Сессии терминала: в блоке env под ключом cli или code политики
• Сессии Cowork, которые выполняются на машине пользователя: в блоке env управляемых настроек на стороне клиента на этой машине
• Сессии вкладки Code под политикой code: в блоке env политики, как только вы выполните условия применения настроек code
• Сессии вкладки Code под политикой cli: в блоке env управляемых настроек на стороне клиента на машине, которая выполняет сессию. При работе через SSH это удалённый хост.

​

Добавление собственных меток

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
  resource_attributes:
    service.namespace: claude
    deployment.environment.name: prod

• Имена содержат только буквы, цифры, ., _ и -
• Имена не являются зарезервированными. Без учёта регистра зарезервированы все имена, начинающиеся с user., enduser. или identity., а также service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version и wsl.version
• Значения — непустой печатаемый ASCII без пробелов и без символов , ; = \ " %
• Значения содержат не более 255 символов в подсчёте шлюза после процентного кодирования, поэтому /, : и @ считаются за три символа каждый
• Значения являются текстом, поэтому заключайте в кавычки числа, true или false

​

Изменение групп во время открытой сессии

processors:
  resource/drop-user-groups:
    attributes:
      - key: user.groups
        action: delete

​

Экспорт напрямую в ваш коллектор

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

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

​

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

​

Настройка HTTP

• При запуске: предупреждение в операционном логе рекомендует разрешить только частные диапазоны 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, ::1/128 и fc00::/7, а также любые другие внутренние диапазоны, из которых подключаются ваши разработчики. Если вы привязываете шлюз к loopback-адресу и не задаёте ни trusted_proxies, ни public_url, как при локальной разработке, предупреждение не появляется.
• Во время работы: когда впервые поступает запрос с адреса вне этих частных диапазонов, шлюз записывает в лог предупреждение и генерирует событие аудита access.public_client с IP клиента. Оба срабатывают один раз за процесс. Link-local адреса, 169.254.0.0/16 и fe80::/10, не считаются публичными. Шлюз отвечает на /healthz и /readyz до выполнения этой проверки, поэтому проверки работоспособности из публичных диапазонов её не вызывают.

​

load_test_mode

load_test_mode:
  enabled: true
  reply_tokens: 750     # roughly how many tokens of text each canned reply carries
  reply_seconds: 9.5    # how long a streamed reply takes

​

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

# Запуск с помощью:
#   claude gateway --config gateway.yaml
#
# Подробность операционного журнала контролируется переменной окружения
# CLAUDE_GATEWAY_LOG_LEVEL (debug | info | warn | error; по умолчанию info). debug
# также логирует имена утверждений в каждом id_token для диагностики groups_claim.
# Это не влияет на события аудита, которые всегда генерируются.
# Установите CLAUDE_GATEWAY_LOG_FORMAT=json, чтобы записывать строки операционного
# журнала как объекты JSON с полями severity, time и message.

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
  # могут опускать email и groups; шлюз заполняет их из /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta выдает groups только когда запрашивается scope `groups` и
  # фильтр утверждения groups приложения их разрешает. Политика contractors ниже
  # соответствует groups, поэтому scope запрашивается здесь.
  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
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # продолжайте проходить проверку готовности через отказ базы данных

# Уведомление, показываемое при входе. Его может прочитать любой, у кого есть доступ к шлюзу.
# login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

# Включает /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
#   # pooled_conflict_rule: priority_list
#   # pooled_priority_order: [eng-platform, eng-all]

# enforcement:
#   fail_closed_on_error: false

# Нагрузочное тестирование этого развёртывания без вызова поставщика модели. Никогда на
# шлюзе, который используют разработчики: каждый запрос получает заготовленный ответ.
# load_test_mode:
#   enabled: true
#   # reply_tokens: 750
#   # reply_seconds: 9.5

# Измеряйте по договорным ставкам вместо цены USD по прайс-листу. Требует admin: или
# managed: политику. С managed:, те же ставки также идут подписанным клиентам.
# Ставки ниже — это заполнители, а не реальные договорные цены.
# 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: mantle
  #   region: us-east-1
  #   models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]
  #   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
      # mantle: 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]
        # allow автоматически одобряет эти инструменты; это не блокирует остальное.
        # Добавьте правила deny для ограничения инструментов.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Ограничьте опцию Default в выборе модели значением availableModels каждой политики
        # вместо встроенного значения по умолчанию, чтобы ни одна роль не получила 400 на Default.
        # Политика contractors наследует этот ключ.
        enforceAvailableModels: true
        permissions:
          allow: [Read, Grep, 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}

​

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

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

​

Связанное

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