可信代理认证（Trusted Proxy Auth）

⚠️ 安全敏感功能。该模式会把认证完全委托给你的反向代理；配置错误可能导致未授权访问。

适用场景

当你满足以下条件时，可以考虑 trusted-proxy：

• Gateway 前面有“身份感知代理”（如 Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik forward-auth）。
• 代理负责鉴权，并通过请求头传递用户身份（例如 x-forwarded-user）。
• 代理是访问 Gateway 的唯一网络路径。
• 你在反向代理 + WebSocket 场景遇到 1008 unauthorized（某些 WS 场景无法按预期携带 token）。

不适用场景

• 代理不做用户鉴权（只是 TLS 终止或负载均衡）。
• 存在绕过代理直连 Gateway 的路径。
• 不确定代理是否会覆盖（而不是追加）客户端传入的 x-forwarded-* 头。

工作原理

1. 代理完成用户鉴权（OAuth/OIDC/SAML…）。
2. 代理转发到 Gateway，并注入用户身份头（例如 x-forwarded-user）。
3. OpenClaw 校验请求来源 IP 是否在 gateway.trustedProxies 内。
4. OpenClaw 从配置的请求头读取用户身份并授权。

配置示例

{
  gateway: {
    bind: "lan",
    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: ["[email protected]", "[email protected]"],
      },
    },
  },
}

安全检查清单

• 防火墙只允许代理访问 Gateway 端口。
• gateway.trustedProxies 只包含你实际控制的代理 IP（避免过大网段）。
• 代理必须覆盖转发头，避免客户端伪造 x-forwarded-*。