การตรวจสอบสิทธิ์พร็อกซีที่เชื่อถือได้

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ควรใช้เมื่อใด

• คุณรัน OpenClaw อยู่หลัง identity-aware proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
• Proxy ของคุณจัดการการตรวจสอบสิทธิ์ทั้งหมดและส่งผ่านตัวตนผู้ใช้ผ่าน headers
• คุณอยู่ในสภาพแวดล้อม Kubernetes หรือ container ที่ proxy เป็นเส้นทางเดียวไปยัง Gateway
• คุณพบข้อผิดพลาด WebSocket 1008 unauthorized เพราะเบราว์เซอร์ไม่สามารถส่ง tokens ใน WS payloads ได้

​

ไม่ควรใช้เมื่อใด

• หาก proxy ของคุณไม่ได้ตรวจสอบสิทธิ์ผู้ใช้ (เป็นเพียง TLS terminator หรือ load balancer)
• หากมีเส้นทางใดก็ตามไปยัง Gateway ที่ข้าม proxy (ช่องโหว่ firewall, การเข้าถึงเครือข่ายภายใน)
• หากคุณไม่แน่ใจว่า proxy ของคุณลบหรือเขียนทับ forwarded headers อย่างถูกต้องหรือไม่
• หากคุณต้องการเพียงการเข้าถึงแบบผู้ใช้เดียวส่วนตัว (พิจารณา Tailscale Serve + loopback เพื่อการตั้งค่าที่ง่ายกว่า)

​

วิธีทำงาน

​

พฤติกรรมการจับคู่ Control UI

• การจับคู่จะไม่ใช่ด่านหลักสำหรับการเข้าถึง Control UI ในโหมดนี้อีกต่อไป
• นโยบายการตรวจสอบสิทธิ์ของ reverse proxy และ allowUsers จะกลายเป็นการควบคุมการเข้าถึงที่มีผลจริง
• จำกัด gateway ingress ให้เฉพาะ IP ของ proxy ที่เชื่อถือได้เท่านั้น (gateway.trustedProxies + firewall)

​

การกำหนดค่า

{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source 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,
      },
    },
  },
}

​

ข้อมูลอ้างอิงการกำหนดค่า

​

TLS termination และ HSTS

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

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

​

แนวทางการ rollout

• เริ่มด้วย max age สั้น ๆ ก่อน (เช่น max-age=300) ระหว่างตรวจสอบ traffic
• เพิ่มเป็นค่าที่มีอายุยาว (เช่น max-age=31536000) เฉพาะหลังจากมีความมั่นใจสูงแล้ว
• เพิ่ม includeSubDomains เฉพาะเมื่อทุก subdomain พร้อมใช้ HTTPS
• ใช้ preload เฉพาะเมื่อคุณตั้งใจทำตามข้อกำหนด preload สำหรับชุดโดเมนทั้งหมดของคุณ
• การพัฒนาภายในเครื่องแบบ loopback-only ไม่ได้รับประโยชน์จาก HSTS

​

ตัวอย่างการตั้งค่า Proxy

{
  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",
      },
    },
  },
}

​

การกำหนดค่า token แบบผสม

• ลบ shared token เมื่อใช้โหมด trusted-proxy หรือ
• เปลี่ยน gateway.auth.mode เป็น "token" หากคุณตั้งใจใช้การตรวจสอบสิทธิ์แบบ token-based

​

Operator scopes header

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

• เมื่อมี header อยู่ OpenClaw จะเคารพชุด scope ที่ประกาศไว้
• เมื่อมี header อยู่แต่ค่าว่าง คำขอจะประกาศว่า ไม่มี operator scopes
• เมื่อไม่มี header อยู่ API HTTP แบบมีตัวตนประกอบตามปกติจะ fallback ไปยังชุด scope เริ่มต้นมาตรฐานของ operator
• เส้นทาง HTTP ของ Plugin แบบ Gateway-auth จะแคบกว่าโดยค่าเริ่มต้น: เมื่อไม่มี x-openclaw-scopes runtime scope ของเส้นทางเหล่านั้นจะ fallback ไปที่ operator.write
• คำขอ HTTP จาก browser-origin ยังคงต้องผ่าน gateway.controlUi.allowedOrigins (หรือโหมด Host-header fallback ที่ตั้งใจใช้) แม้หลังจากการตรวจสอบสิทธิ์แบบ trusted-proxy สำเร็จแล้ว

​

รายการตรวจสอบความปลอดภัย

• พร็อกซีเป็นเส้นทางเดียวเท่านั้น: พอร์ต Gateway ถูกไฟร์วอลล์จากทุกอย่าง ยกเว้นพร็อกซีของคุณ
• trustedProxies มีรายการน้อยที่สุด: มีเฉพาะ IP พร็อกซีจริงของคุณ ไม่ใช่ทั้งซับเน็ต
• แหล่งที่มาของพร็อกซีแบบ loopback เป็นความตั้งใจ: การยืนยันตัวตนแบบ trusted-proxy จะปิดกั้นคำขอจากแหล่งที่มาแบบ loopback โดยค่าเริ่มต้น เว้นแต่จะเปิดใช้ gateway.auth.trustedProxy.allowLoopback อย่างชัดเจนสำหรับพร็อกซีบนโฮสต์เดียวกัน
• พร็อกซีล้างส่วนหัว: พร็อกซีของคุณเขียนทับ (ไม่ใช่ต่อท้าย) ส่วนหัว x-forwarded-* จากไคลเอนต์
• การสิ้นสุด TLS: พร็อกซีของคุณจัดการ TLS; ผู้ใช้เชื่อมต่อผ่าน HTTPS
• allowedOrigins ระบุอย่างชัดเจน: Control UI ที่ไม่ใช่ loopback ใช้ gateway.controlUi.allowedOrigins ที่ระบุอย่างชัดเจน
• ตั้งค่า allowUsers แล้ว (แนะนำ): จำกัดไว้เฉพาะผู้ใช้ที่รู้จัก แทนที่จะอนุญาตทุกคนที่ยืนยันตัวตนแล้ว
• ไม่มีการกำหนดค่า token แบบผสม: อย่าตั้งค่าทั้ง gateway.auth.token และ gateway.auth.mode: "trusted-proxy"
• รหัสผ่านสำรองในเครื่องเป็นส่วนตัว: หากคุณกำหนดค่า gateway.auth.password สำหรับผู้เรียกโดยตรงภายใน ให้ไฟร์วอลล์พอร์ต Gateway ไว้เพื่อไม่ให้ไคลเอนต์ระยะไกลที่ไม่ผ่านพร็อกซีเข้าถึงได้โดยตรง

​

การตรวจสอบความปลอดภัย

• คำเตือน/คำเตือนวิกฤตพื้นฐาน gateway.trusted_proxy_auth
• การกำหนดค่า trustedProxies ที่ขาดหายไป
• การกำหนดค่า userHeader ที่ขาดหายไป
• allowUsers ว่างเปล่า (อนุญาตผู้ใช้ที่ยืนยันตัวตนแล้วทุกคน)
• เปิดใช้ allowLoopback สำหรับแหล่งที่มาของพร็อกซีบนโฮสต์เดียวกัน
• นโยบาย browser-origin แบบ wildcard หรือขาดหายไปบนพื้นผิว Control UI ที่เปิดเผย

​

การแก้ไขปัญหา

​

การย้ายจากการยืนยันตัวตนแบบ token

​

ที่เกี่ยวข้อง

• การกำหนดค่า — ข้อมูลอ้างอิงการกำหนดค่า
• การเข้าถึงระยะไกล — รูปแบบการเข้าถึงระยะไกลอื่นๆ
• ความปลอดภัย — คู่มือความปลอดภัยฉบับเต็ม
• Tailscale — ทางเลือกที่ง่ายกว่าสำหรับการเข้าถึงเฉพาะ tailnet