​

Xác Thực Proxy Tin Cậy

⚠️ Tính năng nhạy cảm về bảo mật. Chế độ này ủy quyền xác thực hoàn toàn cho reverse proxy của bạn. Cấu hình sai có thể khiến Gateway bị truy cập trái phép. Đọc kỹ trang này trước khi kích hoạt.

​

Khi Nào Sử Dụng

• Bạn chạy OpenClaw sau một proxy nhận diện danh tính (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
• Proxy của bạn xử lý toàn bộ xác thực và truyền danh tính người dùng qua các header
• Bạn đang ở trong môi trường Kubernetes hoặc container nơi proxy là con đường duy nhất đến Gateway
• Bạn gặp lỗi WebSocket 1008 không được phép vì trình duyệt không thể truyền token trong payload WS

​

Khi Nào KHÔNG Sử Dụng

• Nếu proxy của bạn không xác thực người dùng (chỉ là một TLS terminator hoặc load balancer)
• Nếu có bất kỳ con đường nào đến Gateway mà bỏ qua proxy (lỗ hổng firewall, truy cập mạng nội bộ)
• Nếu bạn không chắc chắn liệu proxy của bạn có xóa/ghi đè đúng các header chuyển tiếp
• Nếu bạn chỉ cần truy cập cá nhân cho một người dùng (xem xét Tailscale Serve + loopback để thiết lập đơn giản hơn)

​

Cách Hoạt Động

1. Reverse proxy của bạn xác thực người dùng (OAuth, OIDC, SAML, v.v.)
2. Proxy thêm một header với danh tính người dùng đã xác thực (ví dụ: x-forwarded-user: nick@example.com)
3. OpenClaw kiểm tra rằng yêu cầu đến từ một IP proxy tin cậy (được cấu hình trong gateway.trustedProxies)
4. OpenClaw trích xuất danh tính người dùng từ header đã cấu hình
5. Nếu mọi thứ đều ổn, yêu cầu được cho phép

​

Kiểm Soát Hành Vi Ghép Đôi UI

• Ghép đôi không còn là cổng chính cho truy cập Control UI trong chế độ này.
• Chính sách xác thực proxy của bạn và allowUsers trở thành kiểm soát truy cập hiệu quả.
• Giữ ingress gateway khóa chỉ với các IP proxy tin cậy (gateway.trustedProxies + firewall).

​

Cấu Hình

{
  gateway: {
    // Sử dụng loopback cho các thiết lập proxy cùng máy; sử dụng lan/custom cho các host proxy từ xa
    bind: "loopback",

    // QUAN TRỌNG: Chỉ thêm IP của proxy của bạn ở đây
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Header chứa danh tính người dùng đã xác thực (bắt buộc)
        userHeader: "x-forwarded-user",

        // Tùy chọn: các header phải có mặt (xác minh proxy)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Tùy chọn: giới hạn cho người dùng cụ thể (trống = cho phép tất cả)
        allowUsers: ["nick@example.com", "admin@company.org"],
      },
    },
  },
}

​

Tham Khảo Cấu Hình

​

Kết Thúc TLS và HSTS

​

Mô Hình Khuyến Nghị: Kết Thúc TLS Proxy

• Phù hợp cho các triển khai hướng internet.
• Giữ chính sách chứng chỉ + bảo mật HTTP ở một nơi.
• OpenClaw có thể giữ HTTP loopback phía sau proxy.

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

​

Kết Thúc TLS Gateway

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

​

Hướng Dẫn Triển Khai

• Bắt đầu với thời gian tồn tại ngắn trước (ví dụ max-age=300) trong khi xác thực lưu lượng.
• Tăng lên các giá trị lâu dài (ví dụ max-age=31536000) chỉ sau khi đã tự tin.
• Thêm includeSubDomains chỉ khi mọi tên miền phụ đã sẵn sàng cho HTTPS.
• Sử dụng preload chỉ khi bạn cố ý đáp ứng yêu cầu preload cho toàn bộ tập tên miền của bạn.
• Phát triển cục bộ chỉ loopback không có lợi từ HSTS.

​

Ví Dụ Cài Đặt Proxy

​

Pomerium

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // IP của Pomerium
    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

​

Caddy với OAuth

{
  gateway: {
    bind: "lan",
    trustedProxies: ["127.0.0.1"], // IP của Caddy (nếu trên cùng máy)
    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}
    }
}

​

nginx + oauth2-proxy

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // IP của nginx/oauth2-proxy
    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";
}

​

Traefik với Forward Auth

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

​

Danh Sách Kiểm Tra Bảo Mật

• Proxy là con đường duy nhất: Cổng Gateway được firewall từ mọi thứ ngoại trừ proxy của bạn
• trustedProxies là tối thiểu: Chỉ các IP proxy thực tế của bạn, không phải toàn bộ subnet
• Proxy xóa header: Proxy của bạn ghi đè (không thêm) các header x-forwarded-* từ client
• Kết thúc TLS: Proxy của bạn xử lý TLS; người dùng kết nối qua HTTPS
• allowUsers được đặt (khuyến nghị): Giới hạn cho người dùng đã biết thay vì cho phép bất kỳ ai đã xác thực

​

Kiểm Toán Bảo Mật

• Thiếu cấu hình trustedProxies
• Thiếu cấu hình userHeader
• allowUsers trống (cho phép bất kỳ người dùng đã xác thực nào)

​

Khắc Phục Sự Cố

​

”trusted_proxy_untrusted_source”

• IP proxy có đúng không? (IP container Docker có thể thay đổi)
• Có load balancer nào trước proxy của bạn không?
• Sử dụng docker inspect hoặc kubectl get pods -o wide để tìm IP thực tế

​

”trusted_proxy_user_missing”

• Proxy của bạn có được cấu hình để truyền các header danh tính không?
• Tên header có đúng không? (không phân biệt chữ hoa/thường, nhưng chính tả quan trọng)
• Người dùng có thực sự được xác thực tại proxy không?

​

“trusted_proxy_missing_header”

• Cấu hình proxy của bạn cho các header cụ thể đó
• Liệu các header có bị xóa ở đâu đó trong chuỗi không

​

”trusted_proxy_user_not_allowed”

​

WebSocket Vẫn Thất Bại

• Hỗ trợ nâng cấp WebSocket (Upgrade: websocket, Connection: upgrade)
• Truyền các header danh tính trên các yêu cầu nâng cấp WebSocket (không chỉ HTTP)
• Không có một đường dẫn xác thực riêng cho các kết nối WebSocket

​

Di Chuyển Từ Xác Thực Token

1. Cấu hình proxy của bạn để xác thực người dùng và truyền các header
2. Kiểm tra thiết lập proxy độc lập (curl với các header)
3. Cập nhật cấu hình OpenClaw với xác thực proxy tin cậy
4. Khởi động lại Gateway
5. Kiểm tra các kết nối WebSocket từ Control UI
6. Chạy openclaw security audit và xem xét các phát hiện

​

Liên Quan

• Bảo Mật — hướng dẫn bảo mật đầy đủ
• Cấu Hình — tham khảo cấu hình
• Truy Cập Từ Xa — các mô hình truy cập từ xa khác
• Tailscale — giải pháp thay thế đơn giản hơn cho truy cập chỉ qua tailnet