受信任代理身份验证

适用场景

• 你在身份感知代理（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik + forward auth）后运行 OpenClaw。
• 你的代理处理所有身份验证，并通过请求头传递用户身份。
• 你处于 Kubernetes 或容器环境中，代理是访问 Gateway 网关的唯一路径。
• 由于浏览器无法在 WS 载荷中传递令牌，你遇到了 WebSocket 1008 unauthorized 错误。

不适用场景

• 你的代理不对用户进行身份验证（仅作为 TLS 终止器或负载均衡器）。
• 存在任何绕过代理访问 Gateway 网关的路径（防火墙漏洞、内部网络访问）。
• 你不确定代理是否会正确移除或覆盖转发请求头。
• 你只需要个人单用户访问（可考虑改用 Tailscale Serve + 回环地址）。

工作原理

配置

{  gateway: {    // Trusted-proxy auth expects the proxy's source IP to be non-loopback by default    bind: "lan",     // CRITICAL: Only add your proxy's IP(s) here    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Header containing authenticated user identity (required)        userHeader: "x-forwarded-user",         // Optional: headers that MUST be present (proxy verification)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Optional: restrict to specific users (empty = allow all)        allowUsers: ["nick@example.com", "admin@company.org"],         // Optional: allow a same-host loopback proxy after explicit opt-in        allowLoopback: false,      },    },  },}

配置参考

Control UI 配对行为

当 gateway.auth.mode = "trusted-proxy" 处于启用状态且请求通过可信代理检查时，Control UI WebSocket 会话无需设备配对身份即可连接。

权限范围影响：

• 默认情况下，无设备的 Control UI WebSocket 会话可以连接，但不会获得任何操作员权限范围。OpenClaw 会将请求的权限范围列表清除为 []，以防未绑定到已批准配对设备/令牌的会话自行声明权限。
• 如果 WebSocket 成功连接后，方法因 missing scope 而失败，请使用 HTTPS，以便浏览器生成设备身份并完成配对。请参阅 Control UI 不安全 HTTP。
• 仅限紧急情况下使用：即使没有设备身份，gateway.controlUi.dangerouslyDisableDeviceAuth=true 也会保留请求的权限范围。这会严重降低安全性；请尽快恢复原配置。请参阅 Control UI 不安全 HTTP。

反向代理权限范围上限：如果代理在 Control UI WebSocket 升级请求中发送 x-openclaw-scopes，OpenClaw 会将会话权限范围限制为请求权限范围与声明权限范围的交集。此请求头不会授予权限范围；它只会缩小会话可以持有的权限范围。

影响：

• 在此模式下，配对不再是访问 Control UI 的主要门控。
• 你的反向代理身份验证策略和 allowUsers 将成为实际的访问控制机制。
• 仅允许可信代理 IP 进入 Gateway 网关（gateway.trustedProxies + 防火墙）。

自定义 WebSocket 客户端不属于 Control UI 会话。gateway.controlUi.dangerouslyDisableDeviceAuth 不会向任意 client.mode: "backend" 客户端或采用 CLI 形式的客户端授予权限范围。自定义自动化应使用设备身份/配对、保留的本地直接 client.id: "gateway-client" 后端辅助路径；如果 HTTP 请求/响应接口更合适，也可以使用管理 HTTP RPC 插件。

操作员权限范围请求头

可信代理身份验证是一种携带身份的 HTTP 模式，因此调用方可以选择在 HTTP API 请求中通过 x-openclaw-scopes 声明操作员权限范围。

注意：WebSocket 权限范围由 Gateway 网关协议握手和设备身份绑定决定。在 Control UI WebSocket 升级请求中，x-openclaw-scopes 仅用于限制协商出的会话权限范围，而不会授予权限范围。请参阅 Control UI 配对行为。

示例：

• 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）。
• 默认情况下，采用 Gateway 网关身份验证的插件 HTTP 路由权限范围更窄：如果不存在 x-openclaw-scopes，其运行时权限范围仅回退到 operator.write。
• 即使可信代理身份验证成功，来自浏览器源的 HTTP 请求仍必须通过 gateway.controlUi.allowedOrigins 检查（或有意启用的 Host 请求头回退模式）。

实用规则：如果你希望可信代理请求的权限范围小于默认值，或者采用 Gateway 网关身份验证的插件路由需要比写入权限范围更强的权限，请显式发送 x-openclaw-scopes。

TLS 终止和 HSTS

使用单一 TLS 终止点，并在该处应用 HSTS。

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

上线指导

• 验证流量期间，请先从较短的最长有效期开始（例如 max-age=300）。
• 仅在充分确认无误后，才增加为长期值（例如 max-age=31536000）。
• 仅当每个子域名均已支持 HTTPS 时，才添加 includeSubDomains。
• 仅当你有意满足完整域名集合的预加载要求时，才使用预加载。
• 仅限回环地址的本地开发无法从 HSTS 中受益。

代理设置示例

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Pomerium's IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-pomerium-claim-email",        requiredHeaders: ["x-pomerium-jwt-assertion"],      },    },  },}

routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

openclaw.example.com {    authenticate with oauth2_provider    authorize with policy1     reverse_proxy openclaw:18789 {        header_up X-Forwarded-User {http.auth.user.email}    }}

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

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";}

{  gateway: {    bind: "lan",    trustedProxies: ["172.17.0.1"], // Traefik container IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

混合令牌配置

如果同时配置了共享令牌（gateway.auth.token 或 OPENCLAW_GATEWAY_TOKEN），Gateway 网关启动时会拒绝受信任代理身份验证。二者互斥，因为共享令牌会让同一主机上的调用方通过一条与此模式旨在强制执行的代理验证身份完全不同的路径进行身份验证。

如果启动失败，并显示类似 gateway auth mode is trusted-proxy, but a shared token is also configured 的错误：

• 使用受信任代理模式时移除共享令牌，或者
• 如果你打算使用基于令牌的身份验证，请将 gateway.auth.mode 切换为 "token"。

local loopback 的受信任代理身份标头仍会以关闭方式失败：同一主机上的调用方不会被静默认证为代理用户。绕过代理的 OpenClaw 内部调用方可以改用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 进行身份验证。在受信任代理模式下，令牌回退仍然有意不受支持。

安全检查清单

启用受信任代理身份验证前，请验证：

• [ ] 代理是唯一访问路径：Gateway 网关端口通过防火墙阻止除代理之外的所有访问。
• [ ] trustedProxies 保持最小范围：只包含实际代理 IP，而不是整个子网。
• [ ] local loopback 代理来源是有意配置的：除非为同一主机上的代理显式启用 gateway.auth.trustedProxy.allowLoopback，否则受信任代理身份验证会拒绝来自 local loopback 来源的请求。
• [ ] 代理会清除标头：代理会覆盖（而非追加）客户端提供的 x-forwarded-* 标头。
• [ ] TLS 终止：代理负责处理 TLS；用户通过 HTTPS 连接。
• [ ] 显式配置 allowedOrigins：非 local loopback 的 Control UI 使用显式的 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 标头的来源回退。

故障排查

从令牌身份验证迁移

相关内容

• 配置 — 配置参考
• 操作员权限范围 — 角色、权限范围和审批检查
• 远程访问 — 其他远程访问模式
• 安全性 — 完整的安全指南
• Tailscale — 仅限尾网访问时更简单的替代方案