การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือได้

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

ใช้โหมด auth trusted-proxy เมื่อ:

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

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

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

วิธีทำงาน

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

เมื่อ gateway.auth.mode = "trusted-proxy" ทำงานอยู่และคำขอผ่านการตรวจสอบ trusted-proxy เซสชัน WebSocket ของ Control UI สามารถเชื่อมต่อได้โดยไม่ต้องมีตัวตนอุปกรณ์สำหรับการจับคู่

ผลกระทบด้านขอบเขต:

• เซสชัน WebSocket ของ Control UI ที่ไม่มีอุปกรณ์เชื่อมต่อได้ แต่จะไม่ได้รับขอบเขตผู้ปฏิบัติการตามค่าเริ่มต้น OpenClaw ล้างรายการขอบเขตที่ร้องขอเป็น [] เพื่อให้เซสชันที่ไม่ได้ผูกกับอุปกรณ์/โทเค็นที่จับคู่และได้รับอนุมัติแล้วไม่สามารถประกาศสิทธิ์เองได้
• หากเมธอดล้มเหลวด้วย missing scope หลังจากเชื่อมต่อ WebSocket สำเร็จ ให้ใช้ HTTPS เพื่อให้เบราว์เซอร์สร้างตัวตนอุปกรณ์และจับคู่ให้เสร็จสมบูรณ์ ดู HTTP ที่ไม่ปลอดภัยของ Control UI
• ใช้เฉพาะกรณีฉุกเฉิน: gateway.controlUi.dangerouslyDisableDeviceAuth=true จะคงขอบเขตที่ร้องขอไว้แม้ไม่มีตัวตนอุปกรณ์ นี่เป็นการลดระดับความปลอดภัยอย่างรุนแรง ให้ย้อนกลับโดยเร็ว ดู HTTP ที่ไม่ปลอดภัยของ Control UI

การจำกัดขอบเขตโดยรีเวิร์สพร็อกซี:

• หากพร็อกซีของคุณส่ง x-openclaw-scopes ในคำขออัปเกรด WebSocket ของ Control UI OpenClaw จะจำกัดขอบเขตเซสชันให้เป็นส่วนร่วมระหว่างขอบเขตที่ร้องขอและขอบเขตที่ประกาศ ส่วนหัวนี้ไม่ได้ให้สิทธิ์ขอบเขต แต่เพียงจำกัดสิ่งที่เซสชันสามารถถือได้ให้แคบลงเท่านั้น

ผลกระทบ:

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

ไคลเอนต์ WebSocket แบบกำหนดเองไม่ใช่เซสชัน Control UI gateway.controlUi.dangerouslyDisableDeviceAuth ไม่ได้ให้ขอบเขตแก่ client.mode: "backend" ตามอำเภอใจหรือไคลเอนต์ที่มีรูปแบบเหมือน CLI อัตโนมัติแบบกำหนดเองควรใช้ตัวตนอุปกรณ์/การจับคู่, เส้นทางตัวช่วย backend แบบ direct-local ที่สงวนไว้ client.id: "gateway-client" หรือ Plugin admin HTTP RPC เมื่อพื้นผิวคำขอ/คำตอบ HTTP เหมาะสมกว่า

การกำหนดค่า

{  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 และ HSTS

ใช้จุดสิ้นสุด 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) เฉพาะหลังจากมีความมั่นใจสูงแล้ว
• เพิ่ม includeSubDomains เฉพาะเมื่อทุกซับโดเมนพร้อมใช้ HTTPS
• ใช้ preload เฉพาะเมื่อคุณตั้งใจทำตามข้อกำหนด preload สำหรับชุดโดเมนทั้งหมดของคุณ
• การพัฒนาภายในเครื่องแบบลูปแบ็กเท่านั้นไม่ได้รับประโยชน์จาก 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",      },    },  },}

การกำหนดค่าโทเค็นแบบผสม

OpenClaw ปฏิเสธการกำหนดค่าที่กำกวมซึ่งทั้ง gateway.auth.token (หรือ OPENCLAW_GATEWAY_TOKEN) และโหมด trusted-proxy ทำงานพร้อมกัน การกำหนดค่าโทเค็นแบบผสมอาจทำให้คำขอลูปแบ็กยืนยันตัวตนบนเส้นทาง auth ที่ผิดโดยไม่แสดงอาการ

หากคุณเห็นข้อผิดพลาด mixed_trusted_proxy_token ตอนเริ่มต้น:

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

ส่วนหัวระบุตัวตน trusted-proxy ของ loopback ยังคงปฏิเสธโดยปริยาย: ผู้เรียกจากโฮสต์เดียวกันจะไม่ถูกตรวจสอบสิทธิ์เป็นผู้ใช้ proxy แบบเงียบ ๆ ผู้เรียกภายในของ OpenClaw ที่ข้าม proxy อาจตรวจสอบสิทธิ์ด้วย gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD แทนได้ การ fallback ไปใช้โทเค็นยังคงไม่รองรับโดยเจตนาในโหมด trusted-proxy

ส่วนหัวขอบเขต operator

การตรวจสอบสิทธิ์ trusted-proxy เป็นโหมด HTTP แบบ มีข้อมูลระบุตัวตน ดังนั้นผู้เรียกอาจประกาศขอบเขต operator ด้วย x-openclaw-scopes ในคำขอ HTTP API ได้ตามต้องการ

หมายเหตุ: ขอบเขต WebSocket ถูกกำหนดโดย handshake ของโปรโตคอล Gateway และการผูกข้อมูลระบุตัวตนของอุปกรณ์ ในคำขออัปเกรด WebSocket ของ Control UI นั้น x-openclaw-scopes เป็นเพียงเพดานจำกัดขอบเขตของเซสชันที่เจรจาแล้ว ไม่ใช่การให้สิทธิ์ สำหรับพฤติกรรมขอบเขต WebSocket กับ trusted-proxy ดู พฤติกรรมการจับคู่ของ Control UI

ตัวอย่าง:

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

พฤติกรรม:

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

กฎปฏิบัติ: ส่ง x-openclaw-scopes อย่างชัดเจนเมื่อคุณต้องการให้คำขอ trusted-proxy แคบกว่าค่าเริ่มต้น หรือเมื่อเส้นทาง Plugin ที่ใช้การตรวจสอบสิทธิ์ของ Gateway ต้องการสิทธิ์ที่สูงกว่าขอบเขต write

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

ก่อนเปิดใช้การตรวจสอบสิทธิ์ trusted-proxy ให้ตรวจสอบว่า:

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

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

openclaw security audit จะรายงานการตรวจสอบสิทธิ์ trusted-proxy เป็น finding ระดับความรุนแรง critical นี่เป็นพฤติกรรมโดยเจตนา — เป็นการเตือนว่าคุณกำลังมอบหมายความปลอดภัยให้การตั้งค่า proxy ของคุณ

การตรวจสอบจะตรวจหา:

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

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

การย้ายจากการตรวจสอบสิทธิ์ด้วยโทเค็น

หากคุณกำลังย้ายจากการตรวจสอบสิทธิ์ด้วยโทเค็นไปเป็น trusted-proxy:

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

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