受信任代理认证

​

何时使用

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

​

何时不要使用

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

​

工作原理

​

配置

{
  gateway: {
    // Trusted-proxy auth expects the proxy's source IP to be non-loopback by default
    bind: "lan",

    // 关键：这里只添加你的代理 IP
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      identityScopes: {
        "[email protected]": ["operator.admin"],
      },
      trustedProxy: {
        // 包含已认证用户身份的请求头（必需）
        userHeader: "x-forwarded-user",

        // 可选：必须存在的请求头（代理验证）
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // 可选：限制为特定用户（空值 = 允许所有）
        allowUsers: ["[email protected]", "[email protected]"],

        // 可选：在明确启用后允许同主机 loopback 代理
        allowLoopback: false,

        // Optional: let authenticated proxy users enroll new browser devices
        deviceAutoApprove: {
          enabled: false,
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
      },
    },
  },
}

​

配置参考

​

按身份授予作用域

{
  gateway: {
    auth: {
      mode: "trusted-proxy",
      identityScopes: {
        "[email protected]": ["operator.admin"],
        "[email protected]": ["operator.read", "operator.write"],
      },
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

自动设备批准

{
  gateway: {
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        allowUsers: ["[email protected]"],
        deviceAutoApprove: {
          enabled: true,
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
      },
    },
  },
}

1. WebSocket 必须通过 trusted-proxy 方法完成身份验证，并且具有非空的用户身份；当配置了允许列表时，该身份还必须通过 allowUsers。Token、密码、Tailscale 以及未经身份验证的连接永远不会使用此策略。
2. 只有新的 Control UI 或 WebChat 浏览器设备可以自动批准。任何针对现有设备的请求，包括权限范围升级，仍会保持待处理状态，需要通过 openclaw devices approve <requestId> 手动批准。
3. 设备将以 operator 角色获得批准。如果连接请求包含权限范围，则授予的权限范围是请求权限范围与 deviceAutoApprove.scopes 的精确交集。如果请求未包含权限范围，则授予配置的列表；当该列表被省略时，默认授予 operator.read、operator.write 和 operator.approvals。当存在连接的 x-openclaw-scopes 代理标头时，最终授予的权限范围还会受到该标头的进一步限制，因此，缩小用户权限范围的代理也会限制持久化设备授予的权限，而不仅仅是会话权限——存在但为空的标头将不会授予任何权限范围。即使客户端省略自身的权限范围列表，此限制仍然适用。
4. 只有通过在 deviceAutoApprove.scopes 中明确列出，才允许使用 operator.admin。列出后，每个通过代理身份验证的用户都可以请求并在新的浏览器设备上自动获得完整的管理员权限；未包含权限范围的请求也会自动获得完整管理员权限。openclaw security audit 会报告 CRITICAL gateway.trusted_proxy_device_auto_approve_admin 问题，并且 Gateway 会在启动时记录一次警告。如果选定的已验证用户需要会话管理员权限，而不需要持久化的管理员设备授予，请优先使用针对性的 identityScopes 管理员授予。

​

Control UI 配对行为

• 无设备的 Control UI WebSocket 会话无法自行声明权限。OpenClaw 会将其请求的 scope 列表清除为 []，然后在代理身份验证通过后应用任何匹配的服务端 identityScopes 授权。
• 如果 WebSocket 成功连接后方法因 missing scope 失败，请使用 HTTPS，以便浏览器生成设备身份并完成配对。请参阅 Control UI 不安全 HTTP。
• 仍包含已弃用的 gateway.controlUi.dangerouslyDisableDeviceAuth=true 密钥的旧配置，请使用有边界的 Control UI 升级迁移。

• 配对不再是无设备 Control UI 访问的主要门槛。匹配的 identityScopes 条目可以在不创建配对记录的情况下授权该会话。当 deviceAutoApprove.enabled 为 true 时，代理身份也会成为新浏览器设备注册的批准门槛。
• 你的反向代理身份验证策略和 allowUsers 将成为实际的访问控制。
• 仅允许受信任的代理 IP 访问网关入口（gateway.trustedProxies + 防火墙）。

​

操作员作用域头

• 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-auth 插件 HTTP 路由的默认范围更窄：当 x-openclaw-scopes 缺失时，它们的运行时作用域会回退为仅 operator.write。
• 即使 trusted-proxy 认证成功，浏览器来源的 HTTP 请求仍然必须通过 gateway.controlUi.allowedOrigins（或有意启用的 Host 头回退模式）。

​

TLS 终止与 HSTS

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

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

​

部署建议

• 先从较短的 max age 开始，例如 max-age=300，以便在验证流量时使用。
• 只有在确认充分后，才增加到较长的值，例如 max-age=31536000。
• 只有当所有子域名都已准备好使用 HTTPS 时，才添加 includeSubDomains。
• 只有当你确实为整个域名集合满足 preload 要求时，才使用 preload。
• 仅用于本地 loopback 的开发不会从 HSTS 中获益。

​

代理设置示例

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium 的 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: [email protected]
    pass_identity_headers: true

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Caddy/sidecar 代理 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 容器 IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

混合令牌配置

• 在使用 trusted-proxy 模式时移除共享令牌，或
• 如果你打算使用基于令牌的认证，请将 gateway.auth.mode 切换为 "token"。

​

安全检查清单

• Proxy 是唯一通路：Gateway 端口已设置防火墙，仅允许您的代理访问。
• trustedProxies 保持最小范围：仅配置实际的代理 IP，而不是整个子网。
• 环回代理来源是有意设置的：对于环回来源的请求，受信任代理认证默认会失败并关闭，除非针对同主机代理明确启用 gateway.auth.trustedProxy.allowLoopback。
• 代理会移除标头：您的代理会覆盖（而不是追加）客户端传入的 x-forwarded-* 标头。
• TLS 终止：您的代理处理 TLS；用户通过 HTTPS 连接。
• allowedOrigins 已明确设置：非环回 Control UI 使用明确的 gateway.controlUi.allowedOrigins。
• 已设置 allowUsers（推荐）：将访问限制为已知用户，而不是允许任何已通过认证的用户。
• 不存在混合令牌配置：不要同时设置 gateway.auth.token 和 gateway.auth.mode: "trusted-proxy"。
• 本地密码回退保持私有：如果为内部直接调用方配置了 gateway.auth.password，请保持 Gateway 端口受防火墙保护，以便非代理远程客户端无法直接访问。
• 设备自动批准是有意设置的：如果 deviceAutoApprove.enabled 为 true，请将反向代理账户安全视为设备注册边界，并确保授予的作用域列表不包含管理员权限且保持最小范围。

​

安全审计

• 基础 gateway.trusted_proxy_auth 警告／严重提醒。
• 缺少 trustedProxies 配置。
• 缺少 userHeader 配置。
• allowUsers 为空（允许任何已认证的用户）。
• 为同主机代理来源启用了 allowLoopback。
• 启用了浏览器设备自动批准（将新设备配对委托给代理身份）。

​

故障排查

​

从 token 认证迁移

​

相关

• 配置 — 配置参考
• Operator 作用域 — 角色、作用域和审批检查
• 远程访问 — 其他远程访问模式
• 安全性 — 完整安全指南
• Tailscale — 仅限 tailnet 访问的更简单替代方案。