---
read_when:
- Запуск OpenClaw за прокси-сервером с контролем идентификации
- Настройка Pomerium, Caddy или nginx с OAuth перед OpenClaw
- Устранение ошибок WebSocket 1008 «unauthorized» при настройке обратного прокси
- Выбор места для настройки HSTS и других HTTP-заголовков усиления безопасности
sidebarTitle: Trusted proxy auth
summary: Делегируйте аутентификацию Gateway доверенному обратному прокси (Pomerium, Caddy, nginx + OAuth)
title: Аутентификация через доверенный прокси
x-i18n:
generated_at: "2026-07-13T18:15:41Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 24
provider: openai
source_hash: 612070e4872af23c2ac41b529c8b2fa8513bf18fccc053783f55ad00b44e1a5f
source_path: gateway/trusted-proxy-auth.md
workflow: 16
---
**Функция, критически важная для безопасности.** В этом режиме аутентификация полностью делегируется обратному прокси. Неправильная конфигурация может открыть несанкционированный доступ к вашему Gateway. Внимательно прочитайте эту страницу перед включением.
## Когда использовать
- Вы запускаете OpenClaw за **прокси с поддержкой идентификации** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
- Ваш прокси выполняет всю аутентификацию и передаёт идентификатор пользователя через заголовки.
- Вы работаете в Kubernetes или контейнерной среде, где прокси — единственный путь к Gateway.
- Вы сталкиваетесь с ошибками WebSocket `1008 unauthorized`, поскольку браузеры не могут передавать токены в полезной нагрузке WS.
## Когда НЕ следует использовать
- Ваш прокси не аутентифицирует пользователей, а лишь завершает TLS или выполняет балансировку нагрузки.
- Существует какой-либо путь к Gateway в обход прокси (бреши в межсетевом экране, доступ из внутренней сети).
- Вы не уверены, что прокси правильно удаляет или перезаписывает перенаправленные заголовки.
- Вам нужен только персональный однопользовательский доступ (вместо этого рассмотрите Tailscale Serve + loopback).
## Как это работает
Ваш обратный прокси аутентифицирует пользователей (OAuth, OIDC, SAML и т. д.).
Прокси добавляет заголовок с идентификатором аутентифицированного пользователя (например, `x-forwarded-user: nick@example.com`).
OpenClaw проверяет, что запрос поступил с **IP-адреса доверенного прокси** (`gateway.trustedProxies`) и это не собственный loopback-адрес или адрес локального интерфейса Gateway.
OpenClaw считывает обязательные заголовки, а затем идентификатор пользователя из настроенного заголовка.
Если все проверки пройдены и пользователь соответствует `allowUsers` (если задано), запрос авторизуется.
## Конфигурация
```json5
{
gateway: {
// По умолчанию аутентификация доверенного прокси требует, чтобы IP-адрес источника прокси не был loopback-адресом
bind: "lan",
// КРИТИЧЕСКИ ВАЖНО: добавляйте сюда только IP-адреса своих прокси
trustedProxies: ["10.0.0.1", "172.17.0.1"],
auth: {
mode: "trusted-proxy",
trustedProxy: {
// Заголовок с идентификатором аутентифицированного пользователя (обязательно)
userHeader: "x-forwarded-user",
// Необязательно: заголовки, которые ОБЯЗАТЕЛЬНО должны присутствовать (проверка прокси)
requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],
// Необязательно: ограничить доступ указанными пользователями (пусто = разрешить всем)
allowUsers: ["nick@example.com", "admin@company.org"],
// Необязательно: разрешить loopback-прокси на том же хосте после явного включения
allowLoopback: false,
},
},
},
}
```
**Правила среды выполнения в порядке проверки**
1. IP-адрес источника запроса должен соответствовать `gateway.trustedProxies` (с учётом CIDR), иначе запрос отклоняется (`trusted_proxy_untrusted_source`).
2. Запросы из loopback-источников (`127.0.0.1`, `::1`) отклоняются, если не задано `gateway.auth.trustedProxy.allowLoopback = true` и loopback-адрес также не включён в `trustedProxies` (`trusted_proxy_loopback_source`). Эта проверка выполняется до проверки заголовков, поэтому запрос из loopback-источника завершается этой ошибкой, даже если обязательные заголовки также отсутствуют.
3. Источники не из loopback, совпадающие с одним из адресов локальных сетевых интерфейсов хоста Gateway, отклоняются для защиты от подмены (`trusted_proxy_local_interface_source`). Если не удаётся определить интерфейсы, запрос также отклоняется (`trusted_proxy_local_interface_check_failed`).
4. `requiredHeaders` и `userHeader` должны присутствовать и не должны быть пустыми.
5. Если `allowUsers` не пуст, он должен содержать извлечённого пользователя.
**Наличие перенаправленных заголовков отменяет локальность loopback для локального прямого резервного режима.** Если запрос поступает через loopback, но содержит заголовок `Forwarded`, любой `X-Forwarded-*` или `X-Real-IP`, это исключает возможность локального прямого резервного входа по паролю и проверки идентификатора устройства, хотя аутентификация через доверенный прокси всё равно завершается ошибкой из-за loopback.
`allowLoopback` предоставляет локальным процессам на хосте Gateway ту же степень доверия, что и обратному прокси. Включайте этот параметр, только если Gateway по-прежнему защищён межсетевым экраном от прямого удалённого доступа, а локальный прокси удаляет или перезаписывает предоставленные клиентом заголовки идентификации.
Внутренние клиенты Gateway, трафик которых не проходит через обратный прокси, должны использовать `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, а не заголовки идентификации доверенного прокси. Для развёртываний Control UI не на loopback по-прежнему требуется явное указание `gateway.controlUi.allowedOrigins`.
### Справочник по конфигурации
Массив доверенных IP-адресов прокси (или CIDR). Запросы с других IP-адресов отклоняются.
Должно иметь значение `"trusted-proxy"`.
Имя заголовка с идентификатором аутентифицированного пользователя.
Дополнительные заголовки, которые должны присутствовать, чтобы запрос считался доверенным.
Список разрешённых идентификаторов пользователей. Пустой список разрешает доступ всем аутентифицированным пользователям.
Явное включение поддержки loopback-прокси на том же хосте.
Включайте `allowLoopback`, только если локальный обратный прокси является предполагаемой границей доверия. Любой локальный процесс, способный подключиться к Gateway, может попытаться отправить заголовки идентификации прокси, поэтому ограничьте прямой доступ к Gateway только этим хостом и требуйте заголовки, устанавливаемые прокси, например `x-forwarded-proto`, или заголовок с подписанным утверждением, если ваш прокси его поддерживает.
## Поведение сопряжения Control UI
Когда параметр `gateway.auth.mode = "trusted-proxy"` активен и запрос проходит проверки доверенного прокси, сеансы WebSocket Control UI могут подключаться без идентификатора сопряжённого устройства.
Особенности областей доступа:
- Сеансы WebSocket Control UI без устройства подключаются, но по умолчанию не получают областей доступа оператора. OpenClaw очищает список запрошенных областей доступа до `[]`, чтобы сеанс, не привязанный к одобренному сопряжённому устройству или токену, не мог самостоятельно назначить себе разрешения.
- Если после успешного подключения WebSocket методы завершаются ошибкой `missing scope`, используйте HTTPS, чтобы браузер мог создать идентификатор устройства и завершить сопряжение. См. [Небезопасный HTTP для Control UI](/ru/web/control-ui#insecure-http).
- Только для аварийного доступа: `gateway.controlUi.dangerouslyDisableDeviceAuth=true` сохраняет запрошенные области доступа даже без идентификатора устройства. Это серьёзно снижает безопасность; как можно скорее отмените это изменение. См. [Небезопасный HTTP для Control UI](/ru/web/control-ui#insecure-http).
Ограничение областей доступа обратным прокси: если при запросе обновления соединения WebSocket Control UI ваш прокси отправляет `x-openclaw-scopes`, OpenClaw ограничивает области доступа сеанса пересечением запрошенных и объявленных областей. Этот заголовок не предоставляет области доступа, а лишь ограничивает доступный сеансу набор.
Следствия:
- В этом режиме сопряжение больше не является основным механизмом ограничения доступа к Control UI.
- Фактическим механизмом контроля доступа становятся политика аутентификации вашего обратного прокси и `allowUsers`.
- Разрешайте входящий трафик Gateway только с IP-адресов доверенных прокси (`gateway.trustedProxies` + межсетевой экран).
Пользовательские клиенты WebSocket не являются сеансами Control UI. `gateway.controlUi.dangerouslyDisableDeviceAuth` не предоставляет области доступа произвольным клиентам `client.mode: "backend"` или клиентам в формате CLI. Пользовательская автоматизация должна использовать идентификатор устройства и сопряжение, зарезервированный для прямого локального доступа вспомогательный серверный путь `client.id: "gateway-client"` или [плагин admin HTTP RPC](/ru/plugins/admin-http-rpc), если интерфейс HTTP-запросов и ответов подходит лучше.
## Заголовок областей доступа оператора
Аутентификация через доверенный прокси — это режим HTTP **с передачей идентификатора**, поэтому вызывающие стороны могут при необходимости объявлять области доступа оператора с помощью `x-openclaw-scopes` в запросах к HTTP API.
Примечание: области доступа WebSocket определяются рукопожатием протокола Gateway и привязкой идентификатора устройства. В запросах обновления соединения WebSocket Control UI заголовок `x-openclaw-scopes` только ограничивает согласованные области доступа сеанса, но не предоставляет их. См. [Поведение сопряжения Control UI](#control-ui-pairing-behavior).
Примеры:
- `x-openclaw-scopes: operator.read`
- `x-openclaw-scopes: operator.read,operator.write`
- `x-openclaw-scopes: operator.admin,operator.write`
Поведение:
- Если заголовок присутствует, OpenClaw учитывает объявленный набор областей доступа.
- Если заголовок присутствует, но пуст, запрос объявляет **отсутствие** областей доступа оператора.
- Если заголовок отсутствует, обычные HTTP API с передачей идентификатора используют стандартный набор областей доступа оператора по умолчанию (`operator.admin`, `operator.read`, `operator.write`, `operator.approvals`, `operator.pairing`, `operator.talk.secrets`).
- HTTP-маршруты плагинов **с аутентификацией Gateway** по умолчанию имеют более узкие права: при отсутствии `x-openclaw-scopes` их область доступа среды выполнения ограничивается только `operator.write`.
- HTTP-запросы из браузера должны проходить проверку `gateway.controlUi.allowedOrigins` (или намеренно включённый резервный режим заголовка Host) даже после успешной аутентификации через доверенный прокси.
Практическое правило: явно отправляйте `x-openclaw-scopes`, если запрос доверенного прокси должен иметь более узкие права, чем предоставляются по умолчанию, или если маршруту плагина с аутентификацией Gateway требуется область доступа шире, чем запись.
## Завершение TLS и HSTS
Используйте одну точку завершения TLS и применяйте HSTS в ней.
Когда ваш обратный прокси обслуживает HTTPS для `https://control.example.com`, настройте `Strict-Transport-Security` на прокси для этого домена.
- Хорошо подходит для развёртываний с доступом из интернета.
- Позволяет хранить сертификат и политику усиления безопасности HTTP в одном месте.
- OpenClaw может продолжать использовать loopback HTTP за прокси.
Пример значения заголовка:
```text
Strict-Transport-Security: max-age=31536000; includeSubDomains
```
Если OpenClaw самостоятельно обслуживает HTTPS напрямую (без прокси, завершающего TLS), задайте:
```json5
{
gateway: {
tls: { enabled: true },
http: {
securityHeaders: {
strictTransportSecurity: "max-age=31536000; includeSubDomains",
},
},
},
}
```
`strictTransportSecurity` принимает строковое значение заголовка или `false` для явного отключения.
### Рекомендации по внедрению
- Сначала используйте короткий срок действия (например, `max-age=300`), пока проверяете трафик.
- Переходите к длительным значениям (например, `max-age=31536000`) только после полной проверки.
- Добавляйте `includeSubDomains`, только если каждый поддомен готов к работе через HTTPS.
- Используйте предварительную загрузку, только если вы намеренно выполняете её требования для всего набора доменов.
- Локальная разработка исключительно через loopback не получает преимуществ от HSTS.
## Примеры настройки прокси
Pomerium передаёт идентификатор в `x-pomerium-claim-email` (или других заголовках утверждений), а JWT — в `x-pomerium-jwt-assertion`.
```json5
{
gateway: {
bind: "lan",
trustedProxies: ["10.0.0.1"], // IP-адрес Pomerium
auth: {
mode: "trusted-proxy",
trustedProxy: {
userHeader: "x-pomerium-claim-email",
requiredHeaders: ["x-pomerium-jwt-assertion"],
},
},
},
}
```
Фрагмент конфигурации Pomerium:
```yaml
routes:
- from: https://openclaw.example.com
to: http://openclaw-gateway:18789
policy:
- allow:
or:
- email:
is: nick@example.com
pass_identity_headers: true
```
Caddy с плагином `caddy-security` может аутентифицировать пользователей и передавать заголовки идентификации.
```json5
{
gateway: {
bind: "lan",
trustedProxies: ["10.0.0.1"], // IP-адрес прокси Caddy/sidecar
auth: {
mode: "trusted-proxy",
trustedProxy: {
userHeader: "x-forwarded-user",
},
},
},
}
```
Фрагмент Caddyfile:
```caddy
openclaw.example.com {
authenticate with oauth2_provider
authorize with policy1
reverse_proxy openclaw:18789 {
header_up X-Forwarded-User {http.auth.user.email}
}
}
```
oauth2-proxy аутентифицирует пользователей и передаёт идентификатор в `x-auth-request-email`.
```json5
{
gateway: {
bind: "lan",
trustedProxies: ["10.0.0.1"], // IP-адрес nginx/oauth2-proxy
auth: {
mode: "trusted-proxy",
trustedProxy: {
userHeader: "x-auth-request-email",
},
},
},
}
```
Фрагмент конфигурации nginx:
```nginx
location / {
auth_request /oauth2/auth;
auth_request_set $user $upstream_http_x_auth_request_email;
proxy_pass http://openclaw:18789;
proxy_set_header X-Auth-Request-Email $user;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
```
```json5
{
gateway: {
bind: "lan",
trustedProxies: ["172.17.0.1"], // IP-адрес контейнера Traefik
auth: {
mode: "trusted-proxy",
trustedProxy: {
userHeader: "x-forwarded-user",
},
},
},
}
```
## Смешанная конфигурация токенов
Gateway отклоняет запуск с аутентификацией через доверенный прокси, если также настроен общий токен (`gateway.auth.token` или `OPENCLAW_GATEWAY_TOKEN`). Эти варианты взаимоисключающие, поскольку общий токен позволил бы вызывающим сторонам на том же хосте аутентифицироваться совершенно иным способом, нежели через подтверждённый прокси идентификатор, применение которого должен обеспечивать этот режим.
Если запуск завершается ошибкой наподобие `gateway auth mode is trusted-proxy, but a shared token is also configured`:
- Удалите общий токен при использовании режима доверенного прокси или
- Переключите `gateway.auth.mode` на `"token"`, если планируете использовать аутентификацию по токену.
Заголовки идентификации доверенного прокси из loopback-интерфейса по-прежнему отклоняются: вызывающие стороны на том же хосте не проходят неявную аутентификацию как пользователи прокси. Внутренние вызывающие стороны OpenClaw, обходящие прокси, могут вместо этого аутентифицироваться с помощью `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`. Резервная аутентификация по токену намеренно не поддерживается в режиме доверенного прокси.
## Контрольный список безопасности
Перед включением аутентификации через доверенный прокси убедитесь в следующем:
- [ ] **Прокси — единственный путь**: порт Gateway защищён межсетевым экраном от всего, кроме вашего прокси.
- [ ] **trustedProxies минимален**: указаны только фактические IP-адреса вашего прокси, а не целые подсети.
- [ ] **Источник прокси из loopback-интерфейса выбран намеренно**: аутентификация через доверенный прокси отклоняет запросы из loopback-интерфейса, если `gateway.auth.trustedProxy.allowLoopback` явно не включён для прокси на том же хосте.
- [ ] **Прокси удаляет заголовки**: ваш прокси перезаписывает (а не дополняет) заголовки `x-forwarded-*`, полученные от клиентов.
- [ ] **Завершение TLS**: ваш прокси обрабатывает TLS; пользователи подключаются по HTTPS.
- [ ] **allowedOrigins задан явно**: Control UI вне loopback-интерфейса использует явно заданный `gateway.controlUi.allowedOrigins`.
- [ ] **allowUsers задан** (рекомендуется): доступ ограничен известными пользователями, а не предоставляется всем прошедшим аутентификацию.
- [ ] **Нет смешанной конфигурации токенов**: не задавайте одновременно `gateway.auth.token` и `gateway.auth.mode: "trusted-proxy"`.
- [ ] **Локальная резервная аутентификация по паролю закрыта от внешнего доступа**: если вы настраиваете `gateway.auth.password` для внутренних прямых вызывающих сторон, защитите порт Gateway межсетевым экраном, чтобы удалённые клиенты вне прокси не могли подключаться к нему напрямую.
## Аудит безопасности
`openclaw security audit` помечает аутентификацию через доверенный прокси как проблему **критического** уровня серьёзности. Это сделано намеренно: предупреждение напоминает, что безопасность делегируется конфигурации вашего прокси.
Аудит проверяет следующее:
- Базовое предупреждение или критическое напоминание для `gateway.trusted_proxy_auth`.
- Отсутствует конфигурация `trustedProxies`.
- Отсутствует конфигурация `userHeader`.
- Пустой `allowUsers` (разрешает доступ любому аутентифицированному пользователю).
- Включён `allowLoopback` для источников прокси на том же хосте.
Когда Control UI открыт для внешнего доступа, также применяются отдельные проверки, не относящиеся непосредственно к доверенному прокси: `gateway.controlUi.allowedOrigins` с подстановочным знаком или отсутствующим значением, а также резервное определение источника по заголовку Host.
## Устранение неполадок
Запрос поступил не с IP-адреса из `gateway.trustedProxies`. Проверьте:
- Правильно ли указан IP-адрес прокси? (IP-адреса контейнеров Docker могут изменяться.)
- Есть ли перед вашим прокси балансировщик нагрузки?
- Используйте `docker inspect` или `kubectl get pods -o wide`, чтобы определить фактические IP-адреса.
OpenClaw отклонил запрос доверенного прокси из loopback-интерфейса.
Проверьте:
- Подключается ли прокси с `127.0.0.1` / `::1`?
- Пытаетесь ли вы использовать аутентификацию через доверенный прокси с обратным прокси на том же хосте, подключающимся через loopback-интерфейс?
Исправление:
- Для внутренних клиентов на том же хосте, которые не проходят через прокси, предпочтительно использовать аутентификацию по токену или паролю либо
- Направьте трафик через адрес доверенного прокси вне loopback-интерфейса и сохраните этот IP-адрес в `gateway.trustedProxies` либо
- Для намеренно настроенного обратного прокси на том же хосте задайте `gateway.auth.trustedProxy.allowLoopback = true`, сохраните loopback-адрес в `gateway.trustedProxies` и убедитесь, что прокси удаляет или перезаписывает заголовки идентификации.
IP-адрес источника запроса совпал с одним из собственных адресов сетевых интерфейсов хоста Gateway вне loopback-интерфейса (а не с адресом прокси). Эта защита предотвращает подмену трафика с того же хоста в tailnet-сетях или мостовых сетях Docker. `..._check_failed` означает, что при обнаружении интерфейсов произошла ошибка, поэтому OpenClaw отклоняет запрос.
Проверьте:
- Отправляет ли процесс на самом хосте Gateway заголовки идентификации напрямую, в обход прокси?
- Работает ли прокси в том же сетевом пространстве имён, что и Gateway, с IP-адресом, который также отображается как локальный интерфейс?
Исправление: направьте трафик прокси через адрес, который не привязан локально к хосту Gateway, либо используйте `allowLoopback` только для настоящей конфигурации прокси на том же хосте.
Заголовок пользователя был пуст или отсутствовал. Проверьте:
- Настроен ли ваш прокси на передачу заголовков идентификации?
- Правильно ли указано имя заголовка? (Регистр не учитывается, но написание имеет значение.)
- Действительно ли пользователь прошёл аутентификацию на прокси?
Обязательный заголовок отсутствовал. Проверьте:
- Конфигурацию прокси для этих конкретных заголовков.
- Не удаляются ли заголовки где-либо в цепочке.
Пользователь аутентифицирован, но отсутствует в `allowUsers`. Добавьте его или удалите список разрешённых пользователей.
`gateway.auth.mode` имеет значение `"trusted-proxy"`, но `gateway.trustedProxies` пуст, либо отсутствует сам `gateway.auth.trustedProxy`. Все запросы отклоняются, пока не будут заданы оба параметра.
Аутентификация через доверенный прокси выполнена успешно, но браузерный заголовок `Origin` не прошёл проверку источника Control UI.
Проверьте:
- `gateway.controlUi.allowedOrigins` содержит точный источник браузера.
- Вы не полагаетесь на источники с подстановочным знаком, если только намеренно не хотите разрешить доступ всем.
- Если вы намеренно используете режим резервного определения по заголовку Host, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` задан осознанно.
Соединение WebSocket устанавливается, но `chat.history`, `sessions.list` или
`models.list` завершается ошибкой `missing scope: operator.read`.
Распространённые причины:
- Сеанс Control UI без устройства: аутентификация через доверенный прокси может разрешить соединение WebSocket без идентификатора устройства, но OpenClaw намеренно очищает области доступа в сеансах без устройства.
- Собственный серверный клиент: `gateway.controlUi.dangerouslyDisableDeviceAuth` предназначен для Control UI и не предоставляет области доступа произвольным серверным или CLI-подобным клиентам WebSocket.
- Чрезмерно узкий `x-openclaw-scopes`: если прокси добавляет этот заголовок в запрос обновления соединения WebSocket для Control UI, области доступа сеанса ограничиваются указанным набором. Пустое значение заголовка означает отсутствие областей доступа.
Исправление:
- Для Control UI используйте HTTPS, чтобы браузер мог создать идентификатор устройства и завершить сопряжение.
- Для пользовательской автоматизации используйте идентификатор устройства и сопряжение, зарезервированный внутренний серверный путь прямого локального доступа `gateway-client` или [административный HTTP RPC](/ru/plugins/admin-http-rpc).
- Используйте `gateway.controlUi.dangerouslyDisableDeviceAuth: true` только как временный аварийный путь для Control UI.
Убедитесь, что ваш прокси:
- Поддерживает обновление соединений WebSocket (`Upgrade: websocket`, `Connection: upgrade`).
- Передаёт заголовки идентификации в запросах обновления соединения WebSocket, а не только в HTTP-запросах.
- Не использует отдельный путь аутентификации для соединений WebSocket.
## Миграция с аутентификации по токену
Настройте прокси для аутентификации пользователей и передачи заголовков.
Проверьте конфигурацию прокси отдельно (с помощью curl и заголовков).
Добавьте аутентификацию через доверенный прокси в конфигурацию OpenClaw.
Перезапустите Gateway.
Проверьте соединения WebSocket из Control UI.
Запустите `openclaw security audit` и изучите результаты.
## Связанные материалы
- [Конфигурация](/ru/gateway/configuration) — справочник по конфигурации
- [Области доступа оператора](/ru/gateway/operator-scopes) — роли, области доступа и проверки подтверждений
- [Удалённый доступ](/ru/gateway/remote) — другие схемы удалённого доступа
- [Безопасность](/ru/gateway/security) — полное руководство по безопасности
- [Tailscale](/ru/gateway/tailscale) — более простая альтернатива для доступа только из tailnet-сети