> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Конфигурация Claude apps gateway
> Справочник по каждому параметру gateway.yaml: listener и TLS, OIDC, session, хранилище Postgres, upstreams Bedrock/Agent Platform/Foundry, маршрутизация моделей, управляемые политики и телеметрия.
Развёртывание Claude apps gateway настраивается одним файлом YAML, обычно `gateway.yaml`. Файл определяет всё, что делает gateway: где он слушает, как разработчики входят в систему, куда идёт вывод, и какие политики и телеметрия применяются. Эта страница — справочник по каждому параметру в этом файле. Чтобы написать свой первый файл, начните с [quickstart](/ru/claude-apps-gateway#quickstart), который создаёт минимальную рабочую конфигурацию и запускает её; когда у вас будет конфигурация, которой вы довольны, [руководство по развёртыванию](/ru/claude-apps-gateway-deploy) охватывает контейнеризацию и размещение на Kubernetes, Cloud Run или вашей собственной платформе.
Gateway читает файл один раз при запуске с помощью `claude gateway --config /path/to/gateway.yaml`. Каждый параметр проверяется по схеме при загрузке, поэтому неправильная конфигурация не запускается с ошибкой на уровне поля, а не при первом использовании.
[Полный пример](#complete-example) в конце этой страницы охватывает каждый раздел.
Структура файла
Пять разделов [обязательны](#required-sections). Все остальные разделы [опциональны](#optional-sections), и пропущенный раздел принимает значения по умолчанию. Неизвестные ключи приводят к сбою при загрузке, поэтому опечатка выявляется как именованная ошибка, а не как молча игнорируемый параметр.
**Обязательные разделы:**
* [`listen`](#listen): адрес привязки, публичный URL, завершение TLS
* [`oidc`](#oidc): ваш поставщик идентификации (IdP), включая издателя, клиента, сопоставление утверждений и кто может входить
* [`session`](#session): токены-носители, которые выпускает gateway, с секретом и временем жизни
* [`store`](#store): PostgreSQL для грантов устройств и счётчиков ограничения скорости
* [`upstreams`](#upstreams): куда идёт вывод, будь то Anthropic, Bedrock, Agent Platform или Foundry
**Опциональные разделы:**
* [`admin`](#admin): аутентификация Admin API и сохранение лимитов расходов
* [`enforcement`](#enforcement): поведение лимитов расходов при отказе или разрешении
* [`models`](#models) и `auto_include_builtin_models`: кураторский список моделей администратором и ID для каждого upstream
* [`managed`](#managed): управляемые политики параметров по группам IdP
* [`telemetry`](#telemetry): пересылка OTLP на ваш стек наблюдаемости
* [`access_control`, `limits`, `timeouts`, `rate_limits`](#http-tuning): разрешение/запрет IP, ограничения размера запроса, время до первого байта upstream и лимиты входа по IP
Расширение секретов
Не пишите секреты, такие как `client_secret`, `jwt_secret` или `postgres_url`, прямо в `gateway.yaml`. Ссылайтесь на них одной из форм ниже, и gateway разрешит значение при загрузке из переменной окружения или файла:
| Форма | Разрешается в | Используется для |
| --------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `${VAR}` | Переменная окружения `VAR`. Загрузка не удаётся, если не определена. | Переменные окружения контейнера, AWS Secrets Manager через внедрение env |
| `${file:/path}` | Содержимое файла, обрезано | Монтирования томов Kubernetes Secret, Vault Agent, SOPS |
Обязательные разделы
`listen`
Блок `listen` управляет тем, где служит gateway: адрес привязки и порт, видимое снаружи происхождение и опциональное завершение TLS.
| Поле | Обязательно | Описание |
| ---------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host` | Нет | Адрес привязки. По умолчанию `0.0.0.0`. |
| `port` | Нет | Порт привязки. По умолчанию `8080`. |
| `public_url` | За прокси | Видимое снаружи происхождение `https://`, используется для построения `redirect_uri` IdP и метаданных обнаружения. Требуется за любым прокси, завершающим TLS, таким как ALB, Ingress или Cloud Run, потому что gateway не доверяет заголовкам `X-Forwarded-*` при построении собственного происхождения; они могут быть подделаны клиентом. `trusted_proxies` ниже управляет только разрешением IP клиента. Также требуется для включения [телеметрии](#telemetry), потому что gateway строит конечную точку OTLP, которую он отправляет клиентам, из этого URL. |
| `tls.cert` / `tls.key` | Нет | Пути PEM, если gateway сам завершает TLS |
| `trusted_proxies` | Нет | CIDR или IP балансировщиков нагрузки перед gateway. Когда установлено, gateway доверяет `X-Forwarded-For` только от этих пиров и записывает реальный IP клиента для ограничения скорости по IP и аудита. Эквивалентно nginx `set_real_ip_from`. |
`oidc`
OpenID Connect (OIDC) — это протокол SSO, который gateway использует с вашим поставщиком идентификации; см. [Настройка поставщика идентификации](/ru/claude-apps-gateway-deploy#identity-provider-setup) для того, что нужно зарегистрировать на стороне IdP. Блок `oidc` подключает gateway к вашему поставщику идентификации и решает, кто может входить. Он называет издателя и клиента OAuth, сопоставляет утверждения, которые несут электронную почту и группы, и ограничивает вход по домену электронной почты или группе.
| Поле | Обязательно | Описание |
| ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issuer` | Да | База обнаружения OIDC. Должна служить обнаружением в `/.well-known/openid-configuration`. Используйте HTTPS в production; gateway принимает издателя `http://`. Издатель loopback, такой как `http://localhost:8081`, отклоняется [защитой SSRF](/ru/claude-apps-gateway-deploy#threat-model-summary), если в окружении gateway не установлено `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`. |
| `client_id` / `client_secret` | Да | Из регистрации клиента OAuth |
| `allowed_email_domains` | Нет | Отклоняйте id\_tokens, чьё утверждение `email` не находится в одном из этих доменов, без учёта регистра. Защита в глубину от неправильной конфигурации многотенантного IdP. Независимо от этого параметра, id\_token, чьё утверждение `email_verified` явно `false`, всегда отклоняется. |
| `allowed_groups` | Нет | Ограничьте вход членами этих групп IdP, сопоставленными с `groups_claim`. Пользователь в разрешённом домене электронной почты, но ни в одной из этих групп, отклоняется. Требует, чтобы IdP выпускал утверждение groups. |
| `groups_claim` | Нет | Какое утверждение id\_token несёт членство в группе. По умолчанию `groups`. Microsoft Entra выпускает роли приложения под `roles`. Принимает плоский ключ или RFC 6901 JSON Pointer, такой как `/resource_access/gateway/roles` для вложенных утверждений. |
| `google_groups` | Нет | Посмотрите группы вошедшего пользователя через Google Workspace Admin SDK Directory API, потому что id\_token Google не несёт утверждение groups. Установите `service_account_json_path` на файл ключа сервис-аккаунта с делегированием на уровне домена на область `https://www.googleapis.com/auth/admin.directory.group.readonly` и `admin_email` на администратора Workspace, который сервис-аккаунт олицетворяет; Directory API требует реального субъекта администратора. Адреса электронной почты групп каждого пользователя становятся их утверждением groups, поэтому `allowed_groups` и `managed.policies.match.groups` сопоставляются с адресами электронной почты групп. |
| `email_claim` | Нет | Какое утверждение id\_token несёт электронную почту пользователя. По умолчанию `email`. Некоторые IdP, такие как ADFS и Entra B2C, выпускают `upn` или `preferred_username`. Принимает плоский ключ, JSON Pointer или список резервных ключей, где используется первый присутствующий ключ. |
| `scopes` | Нет | Полное переопределение областей OIDC, которые запрашивает gateway. По умолчанию `[openid, profile, email, offline_access]`. Установите, когда ваш IdP отклоняет области, которые он не распознаёт, или требует пользовательскую область для выпуска групп или электронной почты. Должна включать `openid`. Отказ от `offline_access` отключает токены обновления, поэтому разработчики повторно запускают вход в браузер каждые `session.ttl_hours`. См. [Настройка поставщика идентификации](/ru/claude-apps-gateway-deploy#identity-provider-setup) для рецептов областей для каждого IdP, таких как поток токена обновления Google. |
| `extra_auth_params` | Нет | Дополнительные параметры запроса, добавленные к запросу авторизации IdP, дословно. Это механизм переопределения для поведения, специфичного для IdP, такого как `access_type: offline` для токенов обновления Google, `domain_hint` для некоторых тенантов Entra или `acr_values` для потоков повышения уровня. Не может переопределять параметры протокола, управляемые gateway: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` и `client_id`. |
| `userinfo_fallback` | Нет | Когда id\_token опускает электронную почту или группы, получите их из `/userinfo`. Требуется для облегчённых токенов доступа Keycloak, сервера организации Okta и минимальных токенов ADFS. id\_token остаётся авторитетным; userinfo только заполняет пробелы. По умолчанию `false`. |
| `use_pkce` | Нет | Отправьте вызов PKCE (S256) на запрос авторизации. По умолчанию `true`. Установите `false` только, если ваш IdP отклоняет PKCE для этого конфиденциального клиента. |
| `clock_skew_seconds` | Нет | Допустите дрейф часов при проверке утверждений времени id\_token. По умолчанию `0`, что строго. Повысьте, если вы видите ошибки "token expired / not yet valid" сразу после входа из-за дрейфа часов хоста/IdP. |
| `token_endpoint_auth_method` | Нет | Переопределите метод аутентификации конечной точки токена. Принимает `client_secret_basic` или `client_secret_post`. Автоматически согласовано по умолчанию. |
| `id_token_signed_response_alg` | Нет | Ожидаемый алгоритм подписи id\_token. По умолчанию `RS256`. Установите для IdP, которые подписывают с помощью ES256, PS256 или EdDSA. |
| `additional_authorized_parties` | Нет | Дополнительные значения `azp` для принятия помимо `client_id`, для потоков брокера Keycloak и обмена токенами |
| `discovery_url` | Нет | Получите документ обнаружения из этого URL вместо его получения из `issuer`, для IdP за прокси, который переписывает хост издателя. Путь должен содержать `/.well-known/`. |
| `form_action_origins` | Нет | Дополнительные происхождения для директивы `Content-Security-Policy: form-action` страницы `/device`. Gateway уже разрешает `'self'` и обнаруженное происхождение `authorization_endpoint`, но Chrome применяет `form-action` ко всей цепочке перенаправления. Если ваш IdP перенаправляет через второй хост, такой как Azure AD, объединённый с ADFS, hub-spoke Okta или корпоративный перехватчик SSO, перечислите каждое происхождение, через которое может перенаправляться запрос авторизации. |
| `ca_cert_pem` | Нет | PEM сертификат CA, который заменяет хранилище доверия системы только для запросов IdP. Используйте для Keycloak или Dex за корпоративной PKI. |
`session`
Блок `session` формирует токены-носители, которые выпускает gateway после входа: секрет, который их подписывает, и как долго они живут.
| Поле | Обязательно | Описание |
| ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jwt_secret` | Да | По крайней мере 32 байта энтропии, например из `openssl rand -base64 32`. Подписывает HS256 токены-носители gateway. Принимает одну строку или массив для ротации: индекс 0 подписывает и все записи проверяют. Для ротации добавьте новый секрет в начало, подождите `ttl_hours`, затем удалите старый. |
| `ttl_hours` | Нет | Время жизни токена-носителя gateway. По умолчанию `1`. CLI молча обновляется перед истечением, когда IdP выпускает токены обновления. Более короткое время жизни быстрее отзывает; более длинное делает меньше раундов IdP. Если ваш IdP не может выпускать токены обновления, потому что `offline_access` недоступен, нет молчаливого обновления, поэтому повысьте это до `8` или `12`, чтобы избежать отправки разработчиков обратно на вход в браузер каждый час. |
`store`
Блок `store` указывает gateway на его базу данных PostgreSQL, которая содержит гранты устройств и счётчики ограничения скорости.
| Поле | Обязательно | Описание |
| ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `postgres_url` | Да | URL `postgres://` или `postgresql://`. Требуется: встреча грантов устройств, где обратный вызов браузера пишет и опрашивающий CLI читает, нужно состояние между репликами. Gateway запускает свои собственные миграции схемы при загрузке, поэтому роль нуждается в `CREATE TABLE` на целевой схеме. Если ваша политика безопасности запрещает DDL из роли приложения, запустите миграции с ролью администратора, изначально и снова всякий раз, когда новый выпуск поставляет миграции, и предоставьте роли приложения `SELECT, INSERT, UPDATE, DELETE` на таблицы gateway. См. [Обновления](/ru/claude-apps-gateway-deploy#upgrades) и [Postgres](/ru/claude-apps-gateway-deploy#postgres). |
| `username` | Нет | Переопределяет пользователя в `postgres_url` |
| `password` | Нет | Учётные данные базы данных. Установите здесь, а не в `postgres_url`, чтобы учётные данные оставались вне URL. Принимает любые символы и имеет приоритет над учётными данными URL. |
| `max_connections` | Нет | Размер пула соединений Postgres на реплику. По умолчанию `5`, что консервативно и дружелюбно к общим базам данных. С включёнными [лимитами расходов](#admin) горячий путь выполняет несколько операций на запрос вывода, поэтому повысьте его для выделенной базы данных под нагрузкой и держите реплики × это ниже `max_connections` базы данных. |
Для локальной разработки укажите `postgres_url` на одноразовый контейнер Postgres, например `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.
`upstreams`
`upstreams` — это упорядоченный список. Gateway пересылает вывод на первый upstream, который разрешает запрошенную модель. На `5xx`, `429` или timeout он переходит на следующий; другие `4xx` не переходят, потому что эти ошибки относятся к запросу, а не к upstream. Несколько upstream одного поставщика должны установить отличный `name:`.
Клиенты Bedrock, Agent Platform и Foundry создаются один раз при запуске, и их SDK обновляют учётные данные внутри, поэтому ротация облачных учётных данных не требует перезагрузки. Статические ключи API Anthropic и носители читаются при запуске; см. [Anthropic API](#anthropic-api).
Anthropic API
Минимальный upstream Anthropic — это ключ API из [Claude Console](https://platform.claude.com):
```yaml theme={null}
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](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation), затем смонтируйте JWT OIDC вашей рабочей нагрузки как файл, такой как проецируемый токен сервис-аккаунта Kubernetes или id-token платформы CI. Gateway обменивает JWT на короткоживущий носитель и автоматически его обновляет. Файл токена перечитывается при каждом обмене, поэтому ротированные проецируемые токены подхватываются без перезагрузки.
```yaml theme={null}
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_... # опциональная проверка ожидаемой цели
```
Amazon Bedrock
Для развёртывания Bedrock на стороне клиента, которое gateway заменяет или находится перед ним, см. [Claude Code на Amazon Bedrock](/ru/amazon-bedrock). Upstream на стороне gateway:
```yaml theme={null}
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 вместо встраивания статических ключей в образ контейнера.
| Настройка | Как |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Разрешения IAM | Предоставьте основному принципалу gateway `bedrock:InvokeModel` и `bedrock:InvokeModelWithResponseStream` как на ARN профилей вывода, так и на ARN базовых моделей фундамента. Для встроенного каталога в регионах США: `arn:aws:bedrock:::inference-profile/us.anthropic.*` и `arn:aws:bedrock:*::foundation-model/anthropic.*`. |
| Доступ к модели | В консоли Bedrock, по регионам, запросите и включите доступ к модели для моделей Claude, которые вы хотите. Профили вывода между регионами (`us.anthropic.*`) требуют доступа к модели в каждом регионе, который охватывает профиль. |
| EKS (IRSA) | Создайте роль IAM с политикой выше и политикой доверия для поставщика OIDC вашего кластера, ограниченной сервис-аккаунтом gateway. Аннотируйте сервис-аккаунт с помощью `eks.amazonaws.com/role-arn: arn:aws:iam:::role/claude-gateway`. `auth: {}` подхватывает это. |
| ECS / EC2 | Присоедините роль IAM к определению задачи или профилю экземпляра. `auth: {}` подхватывает это. |
| Где-либо ещё | Передайте учётные данные через переменные env `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` и `AWS_SESSION_TOKEN`, или установите их явно в `auth:` с расширением `${VAR}` |
| Регион | `region:` — это регион конечной точки API. Профили вывода между регионами маршрутизируют по географии (США, ЕС, APAC) независимо от того, какой вы выберете. Для регионов, не входящих в США, или ARN с выделенной пропускной способностью добавьте блок [`models:`](#models) с правильными ID для каждого upstream. |
Для эквивалентной настройки на стороне клиента см. [Claude Code на Google Cloud](/ru/google-vertex-ai). Upstream на стороне gateway:
```yaml theme={null}
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](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) вместо региональной. Google затем маршрутизирует каждый запрос в доступный регион, поэтому вы не отслеживаете доступность модели для каждого региона. Установка конкретного региона закрепляет каждый запрос на нём.
| Настройка | Как |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Разрешения IAM | Предоставьте сервис-аккаунту gateway `roles/aiplatform.user` на проекте или пользовательскую роль с `aiplatform.endpoints.predict`. Включите API Agent Platform (`aiplatform.googleapis.com`). |
| Доступ к модели | В Model Garden включите модели Claude для вашего проекта. Они публикуются в определённых регионах; проверьте карточку модели для поддерживаемых регионов. |
| GKE (Workload Identity) | Привяжите сервис-аккаунт GCP к сервис-аккаунту Kubernetes gateway и аннотируйте KSA с помощью `iam.gke.io/gcp-service-account: claude-gateway@.iam.gserviceaccount.com`. `auth: {}` подхватывает это. |
| Cloud Run / GCE | Установите сервис-аккаунт сервиса на один с `roles/aiplatform.user`. `auth: {}` подхватывает это. |
| Где-либо ещё | `auth: { service_account_json: /secrets/sa.json }`, путь к файлу ключа JSON, смонтированному как секрет. Поле принимает путь к файлу, а не содержимое ключа, поэтому расширение `${file:…}` не задействовано. |
Microsoft Foundry
Для развёртывания Foundry на стороне клиента см. [Claude Code на Microsoft Foundry](/ru/microsoft-foundry). Upstream на стороне gateway:
```yaml theme={null}
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.
| Настройка | Как |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RBAC | Предоставьте идентификатору gateway `Azure AI User` или `Cognitive Services User` на ресурс Foundry |
| Развёртывания | Foundry использует имена развёртываний, выбранные администратором, а не канонические ID моделей. Добавьте блок [`models:`](#models), сопоставляющий каждый канонический ID с именем вашего развёртывания. |
| AKS (workload identity) | Объедините User-Assigned Managed Identity с издателем OIDC кластера и привяжите его к сервис-аккаунту gateway. `use_azure_ad: true` подхватывает это через `WorkloadIdentityCredential`. |
| ACI / App Service | Включите управляемую идентификацию, назначенную системой или пользователем, на ресурсе. `use_azure_ad: true` подхватывает это. |
| Где-либо ещё | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Заключите `${…}` в кавычки внутри `{ }`. |
Несколько upstream
Один и тот же поставщик может появляться более одного раза с отличным `name:`. Это охватывает разные регионы, разные учётные записи через разные цепочки учётных данных, выделенную пропускную способность в сравнении с по требованию и кросс-провайдерный fallback.
Gateway пробует upstream по порядку. `5xx`, `429`, timeout и отсутствие конечной точки (`501`) переходят; другие `4xx` не переходят. `429` — это пропускная способность для каждого upstream, поэтому истощение выделенной пропускной способности (PT) переходит на по требованию. Upstream, который не может разрешить запрошенную модель, пропускается без сетевого раундтрипа.
Этот пример маршрутизирует выделенное выделение пропускной способности Bedrock в первую очередь, переполнение на по требованию и вторую учётную запись, и переходит на Anthropic API в последнюю очередь:
```yaml theme={null}
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; upstream
# без `name:` по умолчанию использует строку поставщика (например, `bedrock`). Любой
# 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
```
| Рычаг | Как |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Разные регионы | Один upstream Bedrock на регион, каждый со своим `region:`. С [`auto_include_builtin_models: true`](#models) профили вывода между регионами маршрутизируют автоматически; для развёртываний, закреплённых на регион, используйте блок `models:`. |
| Разные учётные записи | Один upstream Bedrock на учётную запись, каждый со своими учётными данными в `auth:`. Цепочка по умолчанию (`auth: {}`) использует идентификатор пода; для второй учётной записи установите явные учётные данные или токен-носитель. |
| Выделенная пропускная способность | Сопоставьте модель с ARN выделенной пропускной способности в `models:` для имени этого upstream. Другие upstream сохраняют ID по требованию, поэтому пропускная способность PT исчерпывается перед переходом. |
| Конечные точки VPC / FIPS | Установите `base_url:` на upstream на URL вашей конечной точки VPC или FIPS |
| Маршрутизация, ограниченная моделью | Опустите upstream из карты `upstream_model:` модели и этот upstream пропускается для этой модели. Например, маршрутизируйте Opus на выделенную пропускную способность и Sonnet и Haiku на по требованию. |
Переход между облачными провайдерами или на прямой Anthropic API изменяет, какое соглашение, география и другие условия управляют запросом.
CLI применяет одинаковое управление функциями к gateway независимо от того, какой upstream служит данному запросу, поэтому переход не отправляет поле тела, которое upstream отклонил бы.
Опциональные разделы
`admin`
Опциональный. Включает `/v1/organizations/spend_limits`, который отражает публичный Admin API Anthropic, и применение расходов для каждого разработчика на `/v1/messages`. См. [Лимиты расходов](/ru/claude-apps-gateway-spend-limits) для того, как устанавливаются и применяются ограничения; этот раздел охватывает ключи `gateway.yaml`, которые включают функцию и настраивают её.
```yaml theme={null}
admin:
# Именованные статические ключи API для конечных точек администратора, отправляемые как x-api-key.
# ID появляется в журнале аудита как admin-key:, поэтому каждый ключ
# атрибутируется. Массив для ротации: добавьте новый ключ, перекатите клиентов,
# удалите старый.
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
```
| Поле | Обязательно | Описание |
| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `write_keys` | Нет | Массив `{id, key}`. `x-api-key`, соответствующий одному из них, может перечислять, устанавливать и удалять лимиты расходов. Значения ключей должны быть не менее 32 символов; `id` должны быть уникальны в `read_keys` и `write_keys`. |
| `read_keys` | Нет | Массив `{id, key}`. Только для чтения: каждая конечная точка `GET`, включая перечисление ограничений, получение одного по ID и чтение [`/effective`](/ru/claude-apps-gateway-spend-limits#%2Feffective) и [`/audit`](/ru/claude-apps-gateway-spend-limits#%2Faudit). |
| `admin_groups` | Нет | Имена групп IdP. JWT gateway, чьё утверждение `groups` включает одну из них, имеет полный доступ администратора, чтение и запись, и аудиты как `oidc:`. Используйте это для человеческих администраторов; используйте ключи API для машин. |
| `blocked_message` | Нет | Добавлено дословно к `429 billing_error`, который видит заблокированный разработчик. Напишите всю инструкцию, такую как URL или канал Slack. Если не установлено, ошибка — `spend limit reached`. |
| `audit_retention_days` | Нет | По умолчанию `365`. Старые строки `admin_audit` удаляются. |
| `spend_retention_months` | Нет | По умолчанию `13`. Строки счётчика `spend` старше этого удаляются. По умолчанию сохраняется полный год плюс текущий частичный месяц для отчётности год к году. |
| `identity_retention_days` | Нет | По умолчанию `90`. TTL последнего просмотра для строк `principal_emails`, которые содержат электронную почту каждого разработчика, отображаемое имя и группы (PII). Намеренно короче, чем сохранение расходов, поэтому отозванная идентификация стареет, пока её анонимные счётчики расходов остаются. |
| `group_limit_mode` | Нет | `min` (по умолчанию) или `max`. Когда разработчик находится в нескольких группах с ограничениями, `min` применяет наиболее ограничивающее и `max` наименее. Используется как применением, так и `/effective`. |
`enforcement`
Блок `enforcement` управляет тем, как проверки лимитов расходов ведут себя, когда хранилище недоступно.
| Поле | Обязательно | Описание |
| ---------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fail_closed_on_error` | Нет | По умолчанию `false`. Применение расходов не удаётся открыто при отключении Postgres, поэтому вывод остаётся включённым. Установите `true` для отказа закрыто: разработчики, превысившие лимит, блокируются, но так же и все остальные, если хранилище недоступно. Не имеет эффекта без блока [`admin:`](#admin). |
`models`
Блок `models` — это опциональный кураторский список моделей администратором, обслуживаемый в `/v1/models` и используемый для перевода ID моделей для каждого upstream. Требуется для регионов Bedrock, не входящих в США, ARN выделенной пропускной способности Bedrock и имён развёртываний Foundry.
```yaml theme={null}
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
```
`managed`
Блок `managed` определяет политики доступа на основе ролей, ключённые на группы IdP или домен электронной почты. Политики оцениваются по порядку; первое совпадение выбирается, затем объединяется на базу `match: {}` catch-all, описанную ниже. Они обслуживаются для каждого пользователя в `GET /managed/settings` с кешированием ETag/304.
```yaml theme={null}
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` независимо от того, что отправляет клиент.
| Matcher | Поведение |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `match: {}` | Соответствует каждому аутентифицированному пользователю. Начните с одного из них и добавьте политики, ограниченные группой, выше позже. |
| `match: { groups: [a, b] }` | Соответствует, если утверждение `groups` JWT содержит любую из перечисленных групп. Чувствительно к регистру: группы должны соответствовать точному регистру IdP. |
| `match: { email_domain: example.com }` | Соответствует части после последнего `@` в утверждении `email` JWT, без учёта регистра. Принимает один домен на политику. |
| `match: { groups: [a], email_domain: example.com }` | Оба условия должны соответствовать |
Аутентифицированный пользователь, который не соответствует ни одной политике, получает значения по умолчанию gateway, что означает каждую модель в каталоге и никаких управляемых параметров. Добавьте catch-all `match: {}` в последнюю очередь, если вы хотите гарантированную политику по умолчанию.
Gateway не ведёт собственный каталог пользователей. Он авторизует каждый запрос из токена IdP пользователя, читая членство в группе из утверждения `groups` токена и оценивая политики против него. Нет реестра для перечисления и нет учётных записей для предварительного создания, и поэтому нет конечной точки SCIM, потому что нечего синхронизировать в SCIM.
Запустите управление жизненным циклом пользователя и группы в источнике истины, который является собственной подготовкой SCIM вашего IdP или выделенной платформой управления идентификацией. Членство и отзыв, управляемые там, автоматически поступают в gateway через токен. Если вы хотите подготовку SCIM самих учётных записей Claude, это возможность [Claude for Enterprise](/ru/admin-setup).
Применяются два часов распространения:
* **Содержимое политики**: редактирование политики и переразвёртывание достигает подключённых клиентов при их следующем опросе управляемых параметров, в течение часа
* **Членство в группе**: изменение членства пользователя в группе изменяет, какая политика соответствует им. Это вступает в силу при следующем переминте сеанса, означая следующее молчаливое обновление, ограниченное `session.ttl_hours`.
Что входит в `cli`
Каждое значение `cli` — это полный документ Claude Code `managed-settings.json`, та же схема, которую вы развернули бы через MDM или `/etc/claude-code/managed-settings.json`, выраженная здесь как YAML. CLI применяет доставленный документ на управляемом уровне, выше параметров пользователя и проекта.
Gateway проверяет каждый документ по схеме параметров CLI при загрузке, поэтому неузнанный ключ верхнего уровня или узнанный ключ с неправильным значением не запускается с ошибкой, называющей каждый нарушающий ключ. Намеренно открытые части схемы всё ещё принимают произвольные значения, потому что более новые клиенты могут распознавать записи, которые схема gateway не распознаёт. Эти открытые ключи — `env`, `pluginConfigs` и ключи, вложенные под `permissions`.
Поскольку проверка использует схему, поставляемую с установленной версией gateway, размещение ключа параметров верхнего уровня, введённого более новым выпуском Claude Code, в управляемую конфигурацию требует сначала обновления gateway. Дымовой тест новой политики на одном клиенте перед развёртыванием.
Полный справочник ключей находится в [Параметры Claude Code](/ru/settings#available-settings). Ключи, которые операторы достают в первую очередь:
```yaml theme={null}
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 }
```
| Ключ | Применяется | Эффект |
| ------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `availableModels` | Gateway + CLI | Список разрешений моделей. Также проверяется в `/v1/messages`, поэтому исправленный клиент не может его обойти. |
| `permissions.allow` / `.deny` | CLI | Правила инструментов и команд. См. [Разрешения](/ru/permissions). |
| `permissions.disableBypassPermissionsMode` | CLI | Установите на `disable` для блокировки [`bypassPermissions`](/ru/permission-modes#skip-all-checks-with-bypasspermissions-mode), режима, который автоматически одобряет каждый вызов инструмента, и флага `--dangerously-skip-permissions` |
| `allowManagedPermissionRulesOnly` | CLI | Когда `true`, правила разрешений пользователя и проекта игнорируются; применяются только правила из этого документа |
| `env` | CLI | Переменные окружения, объединённые в процесс CLI. Используйте для телеметрии, автообновления и переопределений имён моделей. |
| `hooks` | CLI | Org-wide [hooks](/ru/hooks) |
Поскольку эти параметры поступают по сети, CLI показывает каждому разработчику диалог одобрения безопасности один раз перед применением чего-либо, что может запустить команду оболочки или изменить, куда идёт трафик. Диалог охватывает:
* `hooks`
* переменные `env`, которые не находятся в встроенном списке безопасности CLI
* параметры выполнения оболочки, такие как `apiKeyHelper` и `statusLine`
* управляемое содержимое CLAUDE.md
Список безопасности определяет, какие переменные `env` применяются без одобрения:
* **В списке безопасности**: переменные автообновления и имён моделей
* **Не в списке безопасности**: переменные прокси, переменные базового URL и `OTEL_EXPORTER_OTLP_ENDPOINT`
[Телеметрия](#telemetry) gateway отправляет `OTEL_EXPORTER_OTLP_ENDPOINT`, поэтому установка `telemetry.forward_to` запускает диалог на каждом интерактивном клиенте. Неинтерактивные запуски с флагом `-p` пропускают диалог и применяют параметры без одобрения. Диалог защищает машину разработчика от скомпрометированного или враждебного gateway, а не организацию от разработчика, поэтому пропуск `-p` является намеренным, а не пробелом.
Если разработчик отклоняет, Claude Code выходит, а не применяет политику. Отправка нового hook или переменной `env`, не входящей в список безопасности, в широкую политику означает диалог одобрения при каждом запуске каждого соответствующего разработчика.
Ключ `cli` был назван `settings` в более ранних выпусках. Это написание всё ещё принимается как псевдоним, но новые развёртывания должны использовать `cli`.
Приоритет с другими управляемыми источниками
Если устройство также имеет локальный `managed-settings.json` или политику, доставленную MDM, управляемые источники не объединяются. Источник с наивысшим приоритетом предоставляет все параметры политики, ранжированные в этом порядке с наивысшим приоритетом в первую очередь:
1. [Помощник политики](/ru/settings#compute-managed-settings-with-a-policy-helper)
2. Параметры, доставленные gateway
3. MDM, через реестр HKLM на Windows или plist на macOS
4. Файл `managed-settings.json`
5. Реестр HKCU, только на Windows
Встраивающие хосты могут предоставлять политику через опцию SDK `managedSettings`. Она игнорируется по умолчанию и применяется только, когда управляемый источник выбирает с [`parentSettingsBehavior: "merge"`](/ru/settings#available-settings), отфильтрованный так, чтобы он мог ужесточить политику, но не ослабить её.
Исключением является небольшой набор кросс-источниковых ключей, соблюдаемых, когда любой источник администратора их устанавливает; пользовательский уровень HKCU исключён:
* `sandbox.network.allowManagedDomainsOnly` и `sandbox.filesystem.allowManagedReadPathsOnly`: когда заблокированы, соответствующие списки разрешений объединяются между источниками
* [`allowAllClaudeAiMcps`](/ru/settings#available-settings): переопределение разрешения только для списка разрешений MCP claude.ai
* `sandbox.bwrapPath` и `sandbox.socatPath`: пути файловой системы к вспомогательным двоичным файлам [sandbox](/ru/sandboxing)
Каждый другой ключ, включая `allowManagedPermissionRulesOnly` и `disableBypassPermissionsMode`, поступает только из источника с наивысшим приоритетом. См. [Приоритет параметров](/ru/settings#settings-precedence) для того же правила на странице параметров.
Политики gateway применяются к каждому вызову Claude Code на машине, включая неинтерактивные запуски `claude -p` и сеансы, порождённые Agent SDK. Если gateway недоступен при запуске, подписанные сеансы выходят с ошибкой, а не запускаются без своей политики.
`mcpServers` внутри блока `cli` политики отклоняется при загрузке gateway. Распределение MCP для каждой группы недоступно; развёртывайте MCP серверы через файловый `managed-mcp.json` на каждом устройстве или позвольте разработчикам добавлять их локально.
`telemetry`
CLI отправляет OpenTelemetry Protocol (OTLP) по HTTP метрики, логи и, когда включено, трассировки на gateway, который передаёт их дословно каждому настроенному назначению. См. [Мониторинг использования](/ru/monitoring-usage) для метрик и событий, которые выпускает CLI.
CLI штампует каждый экспорт идентификацией аутентифицированного пользователя, прочитанной из JWT, выданного gateway: атрибуты `user.id`, `user.email` и `user.groups`. Атрибуция затрат и использования для каждого разработчика поэтому работает без конфигурации на стороне разработчика.
```yaml theme={null}
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}
```
Каждое назначение выбирает `metrics`, `logs` и `traces` независимо, и по умолчанию только метрики. Сигналы отличаются по чувствительности:
* **Метрики**: агрегированные счётчики, такие как количество токенов, количество запросов и задержка
* **Логи и трассировки**: могут нести полные команды bash, входные данные инструментов и пути файлов, охватывая всё, что Claude Code делает на машине разработчика
Включайте логи и трассировки только на назначениях с управлением доступом и политикой сохранения, которые данные гарантируют.
Телеметрия отключена в CLI по умолчанию. Конфигурирование `telemetry.forward_to` вместе с `listen.public_url` включает её. Gateway отправляет пять переменных env каждому подключённому клиенту через `/managed/settings`:
* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
* `OTEL_METRICS_EXPORTER=otlp`
* `OTEL_LOGS_EXPORTER=otlp`
* `OTEL_TRACES_EXPORTER=otlp`
* `OTEL_EXPORTER_OTLP_ENDPOINT=`
Отправленная конечная точка строится из публичного URL, поэтому метрики и логи не нуждаются в конфигурации OTEL от разработчиков или политик. Отправленная конфигурация применяется на управляемом уровне, переопределяя переменные `OTEL_*`, которые разработчик устанавливает локально.
[Трассировки](/ru/monitoring-usage#traces-beta) дополнительно требуют `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` на каждом клиенте. Gateway не отправляет эту переменную, поэтому установите её через блок `env` управляемой политики. Она не находится в списке безопасности CLI, поэтому доставка её через политику охватывается тем же [диалогом одобрения безопасности](#managed), который отправленная конечная точка OTLP уже запускает.
Оба кодирования OTLP protobuf и JSON передаются, и любой совместимый с OpenTelemetry backend работает как назначение.
HTTP tuning
Четыре опциональных блока верхнего уровня, `access_control`, `limits`, `timeouts` и `rate_limits`, настраивают HTTP поверхность. Значения по умолчанию подходят для большинства развёртываний.
| Блок | Ключ | По умолчанию | Описание |
| ---------------- | ---------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_control` | `allow_cidrs` / `deny_cidrs` | пусто | Входящее разрешение/запрет IP по адресу клиента, после разрешения `trusted_proxies`. `deny_cidrs` проверяется в первую очередь; клиент, который он соответствует, отклоняется, даже если `allow_cidrs` также соответствует. Если `allow_cidrs` не пусто, gateway по умолчанию отклоняет. `/healthz` и `/readyz` исключены из `allow_cidrs`. |
| `limits` | `max_request_bytes` | 32 MiB | Максимальный входящий размер тела запроса; запросы большего размера получают `413` перед буферизацией тела. Повысьте для больших запросов файлов или изображений. |
| `limits` | `max_request_header_bytes` | не установлено | Когда установлено, заголовки большего размера возвращают `431` |
| `limits` | `max_url_length` | не установлено | Когда установлено, слишком длинный URL возвращает `414` |
| `timeouts` | `upstream_ttfb_ms` | 120000 | Максимальное ожидание заголовков ответа upstream (время до первого байта). Тело ответа затем потоком без ограничения по стене часов. Применяется к прямому пути upstream Anthropic; Bedrock, Agent Platform и Foundry ограничены собственным timeout SDK поставщика. |
| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Ограничение скорости по IP на неаутентифицированной конечной точке авторизации устройства. Повысьте для большой организации за общим исходящим IP или NAT. Эти ограничения применяются только к потоку входа грантов устройств, а не к выводу `/v1/messages`. См. [Сопротивление перебору пользовательского кода](/ru/claude-apps-gateway-deploy#user-code-brute-force-resistance). |
| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Ограничение скорости по IP на отправки `user_code` в `/device` |
Полный пример
Эта полная справочная конфигурация охватывает каждый основной раздел; блоки [HTTP tuning](#http-tuning) сохраняют свои значения по умолчанию. Скопируйте её, удалите то, что вам не нужно, и заполните свои значения. Конфигурация в [Quickstart](/ru/claude-apps-gateway#quickstart) — это минимальная версия этого.
```yaml gateway.yaml theme={null}
# Запустите с:
# claude gateway --config gateway.yaml
#
# Многословность операционного журнала управляется переменной окружения
# CLAUDE_GATEWAY_LOG_LEVEL (info | warn | error; по умолчанию info). Это не
# влияет на события аудита, которые всегда выпускаются.
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
upstreams:
- provider: anthropic
auth:
api_key: ${ANTHROPIC_API_KEY}
# - provider: bedrock
# region: us-east-1
# auth: {}
# - 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
# vertex: claude-opus-4-8
# foundry:
- 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. Указание машин разработчиков на него настраивается отдельно, на каждом устройстве, через [управляемые параметры](/ru/settings#settings-files) Claude Code. Gateway не может отправлять эти ключи сам, потому что они говорят клиенту, где находится gateway.
Для CLI установите оба ключа в `managed-settings.json` для каждой ОС:
```json theme={null}
{
"forceLoginMethod": "gateway",
"forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}
```
Развёртывайте этот файл на каждое устройство, обычно через вашу платформу MDM. Путь файла отличается по платформе:
| Платформа | Путь |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`, или домен управляемых предпочтений `com.anthropic.claudecode` |
| Linux и WSL | `/etc/claude-code/managed-settings.json` |
| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`, или Group Policy через реестр HKLM |
`forceLoginGatewayUrl` и значение `"gateway"` `forceLoginMethod` соблюдаются только из управляемого уровня, управляемого администратором. Разработчик, устанавливающий их в своём собственном `~/.claude/settings.json`, не имеет эффекта.
* [Обзор Claude apps gateway](/ru/claude-apps-gateway): quickstart и подключение разработчика
* [Руководство по развёртыванию](/ru/claude-apps-gateway-deploy): настройка IdP, образ контейнера, Kubernetes и Cloud Run, и операции
* [Лимиты расходов](/ru/claude-apps-gateway-spend-limits): ограничения для каждого разработчика и Admin API