Конфигурация 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

• 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 шлюз больше не пробует.
• Каждый опробованный upstream завершился ошибкой, при которой шлюз переключается: последний 429. Если ни один не вернул 429, шлюз выбирает, в порядке предпочтения, последний 401 или 403, последний 404 и последний 501. Если ни один не вернул ничего из этого — собственный 502 шлюза, all upstreams failed (N attempted), где N — число всех записей в upstreams, включая те, которые шлюз пропустил, потому что они не обслуживают запрошенную модель.

• 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        # по умолчанию false

​

Amazon Bedrock

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}
    # ИЛИ Bearer-токен Bedrock API:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Переопределите эндпоинт bedrock-runtime для развёртываний с FIPS или VPC-эндпоинтом:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # ID guardrail или полный ARN
      version: "1"                     # номер опубликованной версии или DRAFT
 # сохраните кавычки: 1 без кавычек вызывает ошибку при загрузке

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # собственная роль шлюза: она только вызывает STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # если политика доверия роли его требует

{
  "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 применяется только к provider: bedrock и требует исходных учётных данных SigV4: шлюз отказывается запускаться, если он задан вместе с aws_bearer_token.
• Этот upstream может использовать каждый разработчик, допущенный шлюзом; какие разработчики могут использовать какие модели, определяет managed. Чтобы модель, обслуживаемая через роль, не обслуживалась также из другого аккаунта, дайте ей пользовательский id, карта upstream_model которого содержит только имя этого upstream. Для такого id шлюз пропускает все остальные upstream, поэтому ни запрос, ни подсчёт токенов для прерванного запроса не могут переключиться на другой аккаунт. Запрос к встроенному имени модели всё равно может дойти до этого upstream, и шлюз подпишет его той же ролью. Указывайте этот upstream последним, если только его аккаунт не должен обслуживать и эти модели.

models:
  - id: claude-opus-restricted          # пользовательский id, а не встроенное имя модели
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # единственный upstream, который её обслуживает

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # собственная роль шлюза: она только вызывает STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # или sub

​

Эндпоинт Amazon Bedrock Mantle

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # обязательно
    auth: {}                           # цепочка учётных данных AWS по умолчанию
  - provider: bedrock
    region: us-east-1
    auth: {}

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

​

Claude Platform on AWS

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

​

Google Cloud Agent Platform

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

​

Microsoft Foundry

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}

​

Статические заголовки в запросах к 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

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

​

Дополнительные разделы

​

admin

admin:
  # Именованные статические API-ключи для эндпоинтов администратора, отправляемые как x-api-key.
  # Идентификатор появляется в журнале аудита как 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 шлюза (без API-ключа).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

​

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’s Agent Platform, которую счётчик оценивает как эту модель. Любая другая строка, такая как псевдоним или ARN профиля вывода, сопоставляется с ID, который отправил клиент, или строкой, отправленной вверх по потоку, без учёта регистра.
• Где строки перекрываются, счётчик выбирает наиболее специфичную строку, а не первую: строку, чей model — это точная строка модели, отправленная вверх по потоку, затем строку, соответствующую точному ID, отправленному клиентом, затем строку, называющую встроенную модель.
• Неизвестное имя upstream вызывает сбой при загрузке, как и две строки для одного upstream, которые называют одну и ту же модель, включая два написания одной встроенной модели. Шлюз предупреждает при загрузке о строке, которую не может использовать ни одна запрашиваемая модель.
• Запросы веб-поиска остаются на цене по прайс-листу $0.01; множитель всё ещё применяется к ним.

​

Надбавка к ценам

pricing:
  multiplier: 1.2

​

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

• Что добавляет шлюз: если блок cli политики уже не устанавливает modelPricing, шлюз добавляет multiplier и, для каждого ID модели, который может запросить клиент, строку переопределения первого upstream, который обслуживает этот ID. Ставка, которую взимает только failover upstream, остаётся на шлюзе.
• Исключить одну политику: установите 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 и каждый массив типа события hooks. Они берут объединение базового и политики, поэтому организационный запрет или хук аудита не может быть случайно удалён переопределением для каждой роли.
• Ключи типа Record: env, modelOverrides и skillOverrides. Они выполняют поверхностное объединение, поэтому блок env для каждой роли переопределяет ключи, которые он устанавливает, и наследует остальное из базового.

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

​

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

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

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [claude-opus-restricted]
        enforceAvailableModels: true
        model: claude-opus-restricted

​

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

• Пустой список 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: {}

​

Что входит в 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"

​

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

​

Наложение Claude Desktop

• Список моделей из availableModels. Расширенный контекст в Claude Desktop описывает вариант с контекстом 1M для каждой модели
• Отключённые инструменты из записей permissions.deny с простым названием инструмента. Если вы установите disabledBuiltinTools в блоке desktop политики, шлюз обслуживает объединение вашего значения и выведённого списка, поэтому вы можете отключить больше инструментов таким образом, но не можете повторно включить инструмент, который вы отключили через permissions.deny
• Список разрешённых исходящих соединений из sandbox.network.allowedDomains. Если вы установите coworkEgressAllowedHosts в блоке desktop политики, шлюз использует это значение вместо выведённого списка
• Эндпоинт 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

• У политики также есть ключ 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

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 и раздел telemetry forward_to.
• Устаревший псевдоним текущего ключа. В ошибке загрузки шлюз называет канонический ключ для написания.

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

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

​

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

• Upstream, который может обслуживать запись, сопоставляет её с моделью без поддержки 1M, включая upstream, к которому шлюз обращается только при failover
• Ни её 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

​

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

​

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 игнорирует любой локально настроенный эндпоинт, независимо от того, отправил ли шлюз переменные телеметрии. Его экспорты идут на шлюз, если политика не называет ваш сборщик эндпоинтом.

​

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

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://, или http:// на адрес обратной связи
• URL разрешается на путь, заканчивающийся на /v1/<signal>, без запроса или фрагмента. Claude Code формирует этот путь сам из общей переменной. Он использует переменную для каждого сигнала, такую как OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, как написано, поэтому включите полный путь туда.
• URL не является собственным хостом шлюза. Эндпоинт, адресованный шлюзу, сохраняет путь реле и его токен сессии.
• Ни вы, ни разработчик не настроили otelHeadersHelper ни в каком источнике настроек. С настроенным помощником каждый сигнал остаётся на реле.

• Если шлюз уже отправляет переменные телеметрии, они охватывают включение, селекторы и протокол, и ваш явный эндпоинт переопределяет отправленное значение <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, плюс любые другие внутренние диапазоны, из которых ваши разработчики подключаются. Если вы привязываете шлюз к адресу обратной связи и не устанавливаете ни 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.
# Это не влияет на события аудита, которые всегда генерируются.

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   # продолжайте проходить проверку готовности через отказ базы данных

# Включает /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

# Нагрузочное тестирование этого развёртывания без вызова поставщика модели. Никогда на
# шлюзе, который используют разработчики: каждый запрос получает заготовленный ответ.
# 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, 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}

​

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

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

​

Связанное

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