Gateway
การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือได้
ควรใช้เมื่อใด
- คุณใช้งาน OpenClaw เบื้องหลัง พร็อกซีที่รับรู้ข้อมูลประจำตัว (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
- พร็อกซีของคุณจัดการการพิสูจน์ตัวตนทั้งหมดและส่งข้อมูลประจำตัวผู้ใช้ผ่านส่วนหัว
- คุณอยู่ในสภาพแวดล้อม Kubernetes หรือคอนเทนเนอร์ที่พร็อกซีเป็นเส้นทางเดียวไปยัง Gateway
- คุณพบข้อผิดพลาด WebSocket
1008 unauthorizedเนื่องจากเบราว์เซอร์ไม่สามารถส่งโทเค็นในเพย์โหลด WS ได้
ไม่ควรใช้เมื่อใด
- พร็อกซีของคุณไม่ได้พิสูจน์ตัวตนผู้ใช้ (เป็นเพียงตัวสิ้นสุด TLS หรือตัวกระจายโหลด)
- มีเส้นทางใดก็ตามไปยัง Gateway ที่ข้ามพร็อกซี (ช่องโหว่ในไฟร์วอลล์ การเข้าถึงจากเครือข่ายภายใน)
- คุณไม่แน่ใจว่าพร็อกซีลบหรือเขียนทับส่วนหัวที่ส่งต่ออย่างถูกต้องหรือไม่
- คุณต้องการเพียงการเข้าถึงส่วนบุคคลสำหรับผู้ใช้คนเดียว (ให้พิจารณาใช้ Tailscale Serve + loopback แทน)
วิธีการทำงาน
พร็อกซีพิสูจน์ตัวตนผู้ใช้
พร็อกซีย้อนกลับของคุณพิสูจน์ตัวตนผู้ใช้ (OAuth, OIDC, SAML เป็นต้น)
พร็อกซีเพิ่มส่วนหัวข้อมูลประจำตัว
พร็อกซีเพิ่มส่วนหัวที่มีข้อมูลประจำตัวของผู้ใช้ที่ผ่านการพิสูจน์ตัวตนแล้ว (เช่น x-forwarded-user: nick@example.com)
Gateway ตรวจสอบแหล่งที่มาที่เชื่อถือได้
OpenClaw ตรวจสอบว่าคำขอมาจาก IP ของพร็อกซีที่เชื่อถือได้ (gateway.trustedProxies) และไม่ใช่ที่อยู่ loopback หรือที่อยู่อินเทอร์เฟซภายในของ Gateway เอง
Gateway แยกข้อมูลประจำตัว
OpenClaw อ่านส่วนหัวที่จำเป็น แล้วจึงอ่านข้อมูลประจำตัวผู้ใช้จากส่วนหัวที่กำหนดค่าไว้
อนุญาต
หากการตรวจสอบทั้งหมดผ่าน และผู้ใช้ผ่าน allowUsers (เมื่อตั้งค่าไว้) คำขอจะได้รับอนุญาต
การกำหนดค่า
{ gateway: { // การพิสูจน์ตัวตนผ่านพร็อกซีที่เชื่อถือได้กำหนดให้ IP ต้นทางของพร็อกซีไม่ใช่ loopback โดยค่าเริ่มต้น bind: "lan", // สำคัญอย่างยิ่ง: เพิ่มเฉพาะ IP ของพร็อกซีของคุณที่นี่ 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: ["nick@example.com", "admin@company.org"], // ไม่บังคับ: อนุญาตพร็อกซี loopback บนโฮสต์เดียวกันหลังจากเลือกใช้อย่างชัดเจน allowLoopback: false, // ไม่บังคับ: อนุญาตให้ผู้ใช้ที่พร็อกซีพิสูจน์ตัวตนแล้วลงทะเบียนอุปกรณ์เบราว์เซอร์ใหม่ deviceAutoApprove: { enabled: false, scopes: ["operator.read", "operator.write", "operator.approvals"], }, }, }, },}ข้อมูลอ้างอิงการกำหนดค่า
gateway.trustedProxiesstring[]requiredอาร์เรย์ของที่อยู่ IP ของพร็อกซี (หรือ CIDR) ที่เชื่อถือ คำขอจาก IP อื่นจะถูกปฏิเสธ
gateway.auth.modestringrequiredต้องเป็น "trusted-proxy"
gateway.auth.trustedProxy.userHeaderstringrequiredชื่อส่วนหัวที่มีข้อมูลประจำตัวผู้ใช้ที่ผ่านการพิสูจน์ตัวตนแล้ว
gateway.auth.trustedProxy.requiredHeadersstring[]ส่วนหัวเพิ่มเติมที่ต้องมีเพื่อให้คำขอได้รับความเชื่อถือ
gateway.auth.trustedProxy.allowUsersstring[]รายการอนุญาตของข้อมูลประจำตัวผู้ใช้ หากว่างจะหมายถึงอนุญาตผู้ใช้ที่ผ่านการพิสูจน์ตัวตนทั้งหมด
gateway.auth.trustedProxy.allowLoopbackbooleandefault: falseการรองรับพร็อกซีย้อนกลับแบบ loopback บนโฮสต์เดียวกันโดยต้องเลือกใช้อย่างชัดเจน
gateway.auth.trustedProxy.deviceAutoApprove.enabledbooleandefault: falseอนุมัติข้อมูลประจำตัวอุปกรณ์ใหม่ของ Control UI และ WebChat โดยอัตโนมัติหลังจากการพิสูจน์ตัวตนผ่านพร็อกซีที่เชื่อถือได้
gateway.auth.trustedProxy.deviceAutoApprove.scopesstring[]default: ["operator.read", "operator.write", "operator.approvals"]ขอบเขตสูงสุดที่มอบให้อุปกรณ์เบราว์เซอร์ที่ได้รับอนุมัติโดยอัตโนมัติ การระบุ operator.admin อย่างชัดเจนจะทำให้ผู้ใช้ทุกคนที่พร็อกซีพิสูจน์ตัวตนแล้วสามารถขอสิทธิ์อุปกรณ์ระดับผู้ดูแลระบบเต็มรูปแบบโดยอัตโนมัติ ทำให้คำขอที่ไม่มีขอบเขตได้รับสิทธิ์ผู้ดูแลระบบเต็มรูปแบบโดยอัตโนมัติ และทำให้เกิดผลการตรวจสอบความปลอดภัยระดับสำคัญอย่างยิ่ง gateway.trusted_proxy_device_auto_approve_admin พร้อมคำเตือนเมื่อ Gateway เริ่มทำงาน
การอนุมัติอุปกรณ์โดยอัตโนมัติ
การพิสูจน์ตัวตนผ่านพร็อกซีที่เชื่อถือได้สามารถเลือกใช้ข้อมูลประจำตัวจากพร็อกซีเป็นขอบเขตการอนุมัติสำหรับอุปกรณ์เบราว์เซอร์ใหม่ได้:
{ gateway: { auth: { mode: "trusted-proxy", trustedProxy: { userHeader: "x-forwarded-user", allowUsers: ["operator@example.com"], deviceAutoApprove: { enabled: true, scopes: ["operator.read", "operator.write", "operator.approvals"], }, }, }, },}ค่าเริ่มต้นคือ enabled: false เมื่อเปิดใช้งาน กฎทั้งหมดต่อไปนี้จะมีผล:
- WebSocket ต้องผ่านการพิสูจน์ตัวตนด้วยเมธอด
trusted-proxyพร้อมข้อมูลประจำตัวผู้ใช้ที่ไม่ว่างและผ่านallowUsersเมื่อมีการกำหนดค่ารายการอนุญาต การเชื่อมต่อด้วยโทเค็น รหัสผ่าน Tailscale และการเชื่อมต่อที่ไม่ผ่านการพิสูจน์ตัวตนจะไม่ใช้นโยบายนี้ - เฉพาะอุปกรณ์เบราว์เซอร์ใหม่ของ Control UI หรือ WebChat เท่านั้นที่สามารถได้รับอนุมัติโดยอัตโนมัติ คำขอใด ๆ สำหรับอุปกรณ์ที่มีอยู่ รวมถึงการยกระดับขอบเขต จะยังคงรอการอนุมัติด้วยตนเองผ่าน
openclaw devices approve <requestId> - อุปกรณ์ได้รับอนุมัติด้วยบทบาท
operatorหากคำขอเชื่อมต่อมีขอบเขต สิทธิ์ที่มอบจะเป็นส่วนตัดที่ตรงกันทุกประการระหว่างขอบเขตที่ร้องขอกับdeviceAutoApprove.scopesหากคำขอละเว้นขอบเขต ระบบจะมอบรายการที่กำหนดค่าไว้ และหากละเว้นรายการดังกล่าว ค่าเริ่มต้นจะเป็นoperator.read,operator.writeและoperator.approvalsจากนั้นสิทธิ์ที่มอบจะถูกจำกัดเพิ่มเติมด้วยส่วนหัวพร็อกซีx-openclaw-scopesของการเชื่อมต่อเมื่อมีอยู่ ดังนั้นพร็อกซีที่จำกัดขอบเขตของผู้ใช้จะจำกัดสิทธิ์อุปกรณ์แบบ ถาวร ด้วย ไม่ใช่เพียงเซสชัน โดยส่วนหัวที่มีอยู่แต่เป็นค่าว่างจะไม่ให้ขอบเขตใด ๆ ข้อจำกัดนี้มีผลแม้ไคลเอนต์จะละเว้นรายการขอบเขตของตนเอง operator.adminจะได้รับอนุญาตเฉพาะเมื่อระบุไว้อย่างชัดเจนในdeviceAutoApprove.scopesเมื่อระบุไว้ ผู้ใช้ทุกคนที่พร็อกซีพิสูจน์ตัวตนแล้วสามารถขอและรับสิทธิ์ผู้ดูแลระบบเต็มรูปแบบบนอุปกรณ์เบราว์เซอร์ใหม่โดยอัตโนมัติ คำขอที่ไม่มีขอบเขตจะได้รับสิทธิ์ผู้ดูแลระบบเต็มรูปแบบโดยอัตโนมัติopenclaw security auditจะรายงานผลการตรวจสอบระดับสำคัญอย่างยิ่งgateway.trusted_proxy_device_auto_approve_adminและ Gateway จะบันทึกคำเตือนหนึ่งครั้งเมื่อเริ่มทำงาน ควรใช้การอนุมัติผู้ดูแลระบบด้วยตนเองผ่านopenclaw devices approveหรือopenclaw devices rotateจนกว่าจะมีบทบาทแยกตามข้อมูลประจำตัว
ลักษณะการจับคู่ของ Control UI
เมื่อ gateway.auth.mode = "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 จะจำกัดขอบเขตเซสชันไว้ที่ส่วนตัดระหว่างขอบเขตที่ร้องขอกับขอบเขตที่ประกาศ ส่วนหัวนี้ไม่ได้มอบขอบเขต แต่เพียงจำกัดขอบเขตที่เซสชันสามารถมีได้ เมื่อ deviceAutoApprove.enabled เป็น true ข้อจำกัดเดียวกันนี้จะมีผลกับสิทธิ์อุปกรณ์ถาวรที่เขียนโดย การอนุมัติอุปกรณ์โดยอัตโนมัติ ด้วย ดังนั้นอุปกรณ์ที่ได้รับอนุมัติโดยอัตโนมัติจะไม่มีขอบเขตเกินกว่าที่พร็อกซีประกาศไว้
ผลกระทบ:
- การจับคู่จะไม่ใช่ด่านหลักสำหรับการเข้าถึง Control UI แบบไม่มีอุปกรณ์อีกต่อไป เมื่อ
deviceAutoApprove.enabledเป็น true ข้อมูลประจำตัวจากพร็อกซีจะกลายเป็นด่านอนุมัติสำหรับการลงทะเบียนอุปกรณ์เบราว์เซอร์ใหม่ด้วย - นโยบายการพิสูจน์ตัวตนของพร็อกซีย้อนกลับและ
allowUsersจะกลายเป็นการควบคุมการเข้าถึงที่มีผลจริง - จำกัดทางเข้าของ Gateway ให้รับเฉพาะ IP ของพร็อกซีที่เชื่อถือได้ (
gateway.trustedProxies+ ไฟร์วอลล์)
ไคลเอนต์ WebSocket แบบกำหนดเองไม่ใช่เซสชัน Control UI gateway.controlUi.dangerouslyDisableDeviceAuth ไม่ได้มอบขอบเขตแก่ไคลเอนต์ client.mode: "backend" ใด ๆ หรือไคลเอนต์ที่มีรูปแบบ CLI ระบบอัตโนมัติแบบกำหนดเองควรใช้ข้อมูลประจำตัวและการจับคู่อุปกรณ์ เส้นทางตัวช่วยแบ็กเอนด์ภายในโดยตรง client.id: "gateway-client" ที่สงวนไว้ หรือ Plugin RPC สำหรับผู้ดูแลระบบผ่าน HTTP เมื่ออินเทอร์เฟซแบบคำขอและการตอบกลับผ่าน HTTP เหมาะสมกว่า
ส่วนหัวขอบเขตผู้ปฏิบัติการ
การตรวจสอบสิทธิ์ผ่านพร็อกซีที่เชื่อถือได้เป็นโหมด HTTP ที่ มีข้อมูลระบุตัวตน ดังนั้นผู้เรียกจึงสามารถประกาศขอบเขตสิทธิ์ของผู้ดำเนินการด้วย x-openclaw-scopes ในคำขอ HTTP API ได้ตามต้องการ
หมายเหตุ: ขอบเขตสิทธิ์ของ WebSocket กำหนดโดยการจับมือของโปรโตคอล Gateway และการผูกข้อมูลระบุตัวตนของอุปกรณ์ สำหรับคำขออัปเกรด WebSocket ของ Control UI นั้น x-openclaw-scopes เป็นเพียงขีดจำกัดสูงสุดของขอบเขตสิทธิ์เซสชันที่เจรจาได้ ไม่ใช่การให้สิทธิ์ โปรดดูพฤติกรรมการจับคู่ Control UI
ตัวอย่าง:
x-openclaw-scopes: operator.readx-openclaw-scopes: operator.read,operator.writex-openclaw-scopes: operator.admin,operator.write
พฤติกรรม:
- เมื่อมีส่วนหัว OpenClaw จะใช้ชุดขอบเขตสิทธิ์ที่ประกาศไว้
- เมื่อมีส่วนหัวแต่ค่าว่าง คำขอจะประกาศว่า ไม่มี ขอบเขตสิทธิ์ของผู้ดำเนินการ
- เมื่อไม่มีส่วนหัว HTTP API แบบมีข้อมูลระบุตัวตนตามปกติจะย้อนกลับไปใช้ชุดขอบเขตสิทธิ์เริ่มต้นมาตรฐานของผู้ดำเนินการ (
operator.admin,operator.read,operator.write,operator.approvals,operator.pairing,operator.talk.secrets) - เส้นทาง HTTP ของ Plugin ที่ใช้การตรวจสอบสิทธิ์ของ Gateway มีค่าเริ่มต้นที่จำกัดกว่า: เมื่อไม่มี
x-openclaw-scopesขอบเขตสิทธิ์รันไทม์จะย้อนกลับไปใช้เฉพาะoperator.write - คำขอ HTTP ที่มาจากเบราว์เซอร์ยังคงต้องผ่าน
gateway.controlUi.allowedOrigins(หรือโหมดสำรอง Host-header ที่ตั้งใจเปิดใช้) แม้การตรวจสอบสิทธิ์ผ่านพร็อกซีที่เชื่อถือได้จะสำเร็จแล้ว
กฎในการใช้งานจริง: ส่ง x-openclaw-scopes อย่างชัดเจนเมื่อต้องการให้คำขอผ่านพร็อกซีที่เชื่อถือได้มีขอบเขตสิทธิ์แคบกว่าค่าเริ่มต้น หรือเมื่อเส้นทาง Plugin ที่ใช้การตรวจสอบสิทธิ์ของ Gateway ต้องการสิทธิ์ที่สูงกว่าขอบเขตสิทธิ์การเขียน
การสิ้นสุด TLS และ HSTS
ใช้จุดสิ้นสุด TLS เพียงจุดเดียวและใช้ HSTS ที่จุดนั้น
การสิ้นสุด TLS ที่พร็อกซี (แนะนำ)
เมื่อพร็อกซีย้อนกลับจัดการ HTTPS สำหรับ https://control.example.com ให้ตั้งค่า Strict-Transport-Security ที่พร็อกซีสำหรับโดเมนนั้น
- เหมาะสำหรับการติดตั้งใช้งานที่เปิดรับการเชื่อมต่อจากอินเทอร์เน็ต
- รวมใบรับรองและนโยบายเสริมความแข็งแกร่งของ HTTP ไว้ในที่เดียว
- OpenClaw สามารถใช้ HTTP แบบลูปแบ็กอยู่หลังพร็อกซีต่อไปได้
ตัวอย่างค่าส่วนหัว:
Strict-Transport-Security: max-age=31536000; includeSubDomainsการสิ้นสุด TLS ที่ Gateway
หาก OpenClaw ให้บริการ HTTPS โดยตรงด้วยตัวเอง (ไม่มีพร็อกซีที่สิ้นสุด TLS) ให้ตั้งค่า:
{ gateway: { tls: { enabled: true }, http: { securityHeaders: { strictTransportSecurity: "max-age=31536000; includeSubDomains", }, }, },}strictTransportSecurity รับค่าส่วนหัวแบบสตริง หรือ false เพื่อปิดใช้งานอย่างชัดเจน
แนวทางการทยอยเปิดใช้
- เริ่มด้วยอายุสูงสุดที่สั้นก่อน (เช่น
max-age=300) ระหว่างตรวจสอบความถูกต้องของทราฟฟิก - เพิ่มเป็นค่าระยะยาว (เช่น
max-age=31536000) เมื่อมั่นใจในระดับสูงแล้วเท่านั้น - เพิ่ม
includeSubDomainsเมื่อทุกโดเมนย่อยพร้อมใช้ HTTPS แล้วเท่านั้น - ใช้ preload เฉพาะเมื่อคุณตั้งใจปฏิบัติตามข้อกำหนดของ preload สำหรับชุดโดเมนทั้งหมด
- การพัฒนาในเครื่องที่ใช้เฉพาะลูปแบ็กไม่ได้รับประโยชน์จาก HSTS
ตัวอย่างการตั้งค่าพร็อกซี
Pomerium
Pomerium ส่งข้อมูลระบุตัวตนผ่าน x-pomerium-claim-email (หรือส่วนหัวการอ้างสิทธิ์อื่น) และส่ง JWT ผ่าน x-pomerium-jwt-assertion
{ gateway: { bind: "lan", trustedProxies: ["10.0.0.1"], // IP ของ Pomerium auth: { mode: "trusted-proxy", trustedProxy: { userHeader: "x-pomerium-claim-email", requiredHeaders: ["x-pomerium-jwt-assertion"], }, }, },}ส่วนย่อยการกำหนดค่า Pomerium:
routes: - from: https://openclaw.example.com to: http://openclaw-gateway:18789 policy: - allow: or: - email: is: nick@example.com pass_identity_headers: trueCaddy พร้อม OAuth
Caddy ที่ใช้ Plugin caddy-security สามารถตรวจสอบสิทธิ์ผู้ใช้และส่งส่วนหัวข้อมูลระบุตัวตนได้
{ gateway: { bind: "lan", trustedProxies: ["10.0.0.1"], // IP ของ Caddy/พร็อกซี sidecar auth: { mode: "trusted-proxy", trustedProxy: { userHeader: "x-forwarded-user", }, }, },}ส่วนย่อย Caddyfile:
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
oauth2-proxy ตรวจสอบสิทธิ์ผู้ใช้และส่งข้อมูลระบุตัวตนผ่าน x-auth-request-email
{ gateway: { bind: "lan", trustedProxies: ["10.0.0.1"], // IP ของ nginx/oauth2-proxy auth: { mode: "trusted-proxy", trustedProxy: { userHeader: "x-auth-request-email", }, }, },}ส่วนย่อยการกำหนดค่า nginx:
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 พร้อมการตรวจสอบสิทธิ์แบบส่งต่อ
{ gateway: { bind: "lan", trustedProxies: ["172.17.0.1"], // IP ของคอนเทนเนอร์ Traefik auth: { mode: "trusted-proxy", trustedProxy: { userHeader: "x-forwarded-user", }, }, },}การกำหนดค่าโทเค็นแบบผสม
การเริ่มต้น Gateway จะปฏิเสธการตรวจสอบสิทธิ์ผ่านพร็อกซีที่เชื่อถือได้ หากมีการกำหนดค่าโทเค็นที่ใช้ร่วมกันไว้ด้วย (gateway.auth.token หรือ OPENCLAW_GATEWAY_TOKEN) ทั้งสองแบบใช้ร่วมกันไม่ได้ เนื่องจากโทเค็นที่ใช้ร่วมกันจะทำให้ผู้เรียกจากโฮสต์เดียวกันตรวจสอบสิทธิ์ผ่านเส้นทางที่แตกต่างโดยสิ้นเชิงจากข้อมูลระบุตัวตนที่พร็อกซีตรวจสอบแล้ว ซึ่งโหมดนี้มีไว้เพื่อบังคับใช้
หากการเริ่มต้นล้มเหลวพร้อมข้อผิดพลาดเช่น gateway auth mode is trusted-proxy, but a shared token is also configured:
- นำโทเค็นที่ใช้ร่วมกันออกเมื่อใช้โหมดพร็อกซีที่เชื่อถือได้ หรือ
- เปลี่ยน
gateway.auth.modeเป็น"token"หากต้องการใช้การตรวจสอบสิทธิ์ด้วยโทเค็น
ส่วนหัวข้อมูลระบุตัวตนของพร็อกซีที่เชื่อถือได้ผ่านลูปแบ็กยังคงปฏิเสธโดยค่าเริ่มต้น: ผู้เรียกจากโฮสต์เดียวกันจะไม่ถูกตรวจสอบสิทธิ์เป็นผู้ใช้พร็อกซีโดยอัตโนมัติ ผู้เรียกภายใน OpenClaw ที่ข้ามพร็อกซีอาจตรวจสอบสิทธิ์ด้วย gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD แทน การย้อนกลับไปใช้โทเค็นยังคงไม่ได้รับการรองรับโดยตั้งใจในโหมดพร็อกซีที่เชื่อถือได้
รายการตรวจสอบความปลอดภัย
ก่อนเปิดใช้การตรวจสอบสิทธิ์ผ่านพร็อกซีที่เชื่อถือได้ ให้ตรวจสอบว่า:
- [ ] พร็อกซีเป็นเส้นทางเดียวเท่านั้น: พอร์ต 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 ให้ถือว่าความปลอดภัยของบัญชีพร็อกซีย้อนกลับเป็นขอบเขตการลงทะเบียนอุปกรณ์ และกำหนดรายการขอบเขตสิทธิ์ที่มอบให้เป็นแบบไม่ใช่ผู้ดูแลระบบและน้อยที่สุด
การตรวจสอบความปลอดภัย
openclaw security audit ทำเครื่องหมายการตรวจสอบสิทธิ์ผ่านพร็อกซีที่เชื่อถือได้เป็นข้อค้นพบระดับความรุนแรง วิกฤต ซึ่งเป็นพฤติกรรมที่ตั้งใจไว้ เพื่อเตือนว่าคุณกำลังมอบหมายหน้าที่ด้านความปลอดภัยให้แก่การตั้งค่าพร็อกซี
การตรวจสอบจะตรวจหา:
- คำเตือน/การแจ้งเตือนระดับวิกฤตพื้นฐานของ
gateway.trusted_proxy_auth - ไม่มีการกำหนดค่า
trustedProxies - ไม่มีการกำหนดค่า
userHeader allowUsersว่างเปล่า (อนุญาตผู้ใช้ทุกคนที่ผ่านการตรวจสอบสิทธิ์)- เปิดใช้
allowLoopbackสำหรับแหล่งที่มาของพร็อกซีบนโฮสต์เดียวกัน - เปิดใช้การอนุมัติอุปกรณ์เบราว์เซอร์อัตโนมัติ (มอบหมายการจับคู่อุปกรณ์ใหม่ให้แก่ข้อมูลระบุตัวตนของพร็อกซี)
ข้อค้นหาอื่นที่ไม่เฉพาะเจาะจงกับพร็อกซีที่เชื่อถือได้จะมีผลเมื่อเปิดเผย Control UI ด้วย ได้แก่ gateway.controlUi.allowedOrigins ที่เป็นไวลด์การ์ดหรือไม่มีการตั้งค่า และการย้อนกลับไปใช้ต้นทางจาก Host-header
การแก้ไขปัญหา
trusted_proxy_untrusted_source
คำขอไม่ได้มาจาก IP ใน gateway.trustedProxies โปรดตรวจสอบ:
- IP ของพร็อกซีถูกต้องหรือไม่ (IP ของคอนเทนเนอร์ Docker อาจเปลี่ยนแปลงได้)
- มีตัวจัดสรรภาระงานอยู่ด้านหน้าพร็อกซีหรือไม่
- ใช้
docker inspectหรือkubectl get pods -o wideเพื่อค้นหา IP จริง
trusted_proxy_loopback_source
OpenClaw ปฏิเสธคำขอพร็อกซีที่เชื่อถือได้ซึ่งมีแหล่งที่มาเป็นลูปแบ็ก
โปรดตรวจสอบ:
- พร็อกซีกำลังเชื่อมต่อจาก
127.0.0.1/::1หรือไม่ - กำลังพยายามใช้การตรวจสอบสิทธิ์ผ่านพร็อกซีที่เชื่อถือได้กับพร็อกซีย้อนกลับแบบลูปแบ็กบนโฮสต์เดียวกันหรือไม่
วิธีแก้:
- แนะนำให้ใช้การตรวจสอบสิทธิ์ด้วยโทเค็น/รหัสผ่านสำหรับไคลเอนต์ภายในบนโฮสต์เดียวกันที่ไม่ได้ผ่านพร็อกซี หรือ
- กำหนดเส้นทางผ่านที่อยู่พร็อกซีที่เชื่อถือได้ซึ่งไม่ใช่ลูปแบ็ก และเก็บ IP นั้นไว้ใน
gateway.trustedProxiesหรือ - สำหรับพร็อกซีย้อนกลับบนโฮสต์เดียวกันที่ตั้งใจใช้ ให้ตั้งค่า
gateway.auth.trustedProxy.allowLoopback = trueเก็บที่อยู่ลูปแบ็กไว้ในgateway.trustedProxiesและตรวจสอบว่าพร็อกซีตัดหรือเขียนทับส่วนหัวข้อมูลระบุตัวตน
trusted_proxy_local_interface_source / trusted_proxy_local_interface_check_failed
IP ต้นทางของคำขอตรงกับที่อยู่อินเทอร์เฟซเครือข่ายแบบไม่ใช่ลูปแบ็กของโฮสต์ Gateway เองรายการใดรายการหนึ่ง (ไม่ใช่พร็อกซี) ซึ่งเป็นกลไกป้องกันทราฟฟิกปลอมจากโฮสต์เดียวกันบนเครือข่ายส่วนตัวแบบ tailnet หรือเครือข่ายบริดจ์ Docker ส่วน ..._check_failed หมายถึงการค้นหาอินเทอร์เฟซเกิดข้อผิดพลาด ดังนั้น OpenClaw จึงปฏิเสธโดยค่าเริ่มต้น
โปรดตรวจสอบ:
- มีกระบวนการบนโฮสต์ Gateway ส่งส่วนหัวข้อมูลระบุตัวตนโดยตรงและข้ามพร็อกซีหรือไม่
- พร็อกซีทำงานในเนมสเปซเครือข่ายเดียวกับ Gateway โดยใช้ IP ที่แสดงเป็นอินเทอร์เฟซในเครื่องด้วยหรือไม่
วิธีแก้: กำหนดเส้นทางทราฟฟิกของพร็อกซีผ่านที่อยู่ที่ไม่ได้ผูกไว้ในเครื่องโดยโฮสต์ Gateway ด้วย หรือใช้ allowLoopback เฉพาะสำหรับการตั้งค่าพร็อกซีบนโฮสต์เดียวกันจริง ๆ
trusted_proxy_user_missing
ส่วนหัวผู้ใช้ว่างเปล่าหรือไม่มีอยู่ โปรดตรวจสอบ:
- พร็อกซีได้รับการกำหนดค่าให้ส่งส่วนหัวข้อมูลระบุตัวตนหรือไม่
- ชื่อส่วนหัวถูกต้องหรือไม่ (ไม่คำนึงถึงตัวพิมพ์เล็ก-ใหญ่ แต่การสะกดต้องถูกต้อง)
- ผู้ใช้ผ่านการตรวจสอบสิทธิ์ที่พร็อกซีจริงหรือไม่
trusted_proxy_missing_header_*
ไม่มีส่วนหัวที่จำเป็น โปรดตรวจสอบ:
- การกำหนดค่าพร็อกซีสำหรับส่วนหัวเฉพาะเหล่านั้น
- มีการตัดส่วนหัวออกที่จุดใดจุดหนึ่งในลำดับการเชื่อมต่อหรือไม่
trusted_proxy_user_not_allowed
ผู้ใช้ผ่านการยืนยันตัวตนแล้ว แต่ไม่ได้อยู่ใน allowUsers ให้เพิ่มผู้ใช้ดังกล่าวหรือนำรายการอนุญาตออก
trusted_proxy_no_proxies_configured / trusted_proxy_config_missing
gateway.auth.mode เป็น "trusted-proxy" แต่ gateway.trustedProxies ว่างเปล่า หรือไม่มี gateway.auth.trustedProxy เอง คำขอทั้งหมดจะถูกปฏิเสธจนกว่าจะตั้งค่าทั้งสองรายการ
trusted_proxy_origin_not_allowed
การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือสำเร็จ แต่ส่วนหัว Origin ของเบราว์เซอร์ไม่ผ่านการตรวจสอบต้นทางของ Control UI
ตรวจสอบว่า:
gateway.controlUi.allowedOriginsมีต้นทางของเบราว์เซอร์ที่ตรงกันทุกประการ- ไม่ได้ใช้ต้นทางแบบไวลด์การ์ด เว้นแต่ตั้งใจอนุญาตทั้งหมด
- หากตั้งใจใช้โหมดสำรองส่วนหัว Host ให้ตั้งค่า
gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=trueไว้อย่างจงใจ
เชื่อมต่อสำเร็จแต่เมธอดรายงานว่าขาดขอบเขต
WebSocket เชื่อมต่อได้ แต่ chat.history, sessions.list หรือ
models.list ล้มเหลวพร้อม missing scope: operator.read
สาเหตุที่พบบ่อย:
- เซสชัน Control UI ที่ไม่มีอุปกรณ์: การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือสามารถอนุญาตการเชื่อมต่อ WebSocket โดยไม่มีข้อมูลประจำตัวของอุปกรณ์ได้ แต่ OpenClaw จะล้างขอบเขตของเซสชันที่ไม่มีอุปกรณ์ตามการออกแบบ
- ไคลเอนต์แบ็กเอนด์แบบกำหนดเอง:
gateway.controlUi.dangerouslyDisableDeviceAuthจำกัดขอบเขตไว้สำหรับ Control UI และไม่ได้ให้ขอบเขตแก่ไคลเอนต์ WebSocket แบ็กเอนด์หรือไคลเอนต์ที่มีรูปแบบ CLI โดยพลการ x-openclaw-scopesแคบเกินไป: หากพร็อกซีแทรกส่วนหัวนี้ในคำขออัปเกรด WebSocket ของ Control UI ขอบเขตของเซสชันจะถูกจำกัดไว้ที่ชุดดังกล่าว ค่าส่วนหัวที่ว่างเปล่าจะทำให้ไม่มีขอบเขต
วิธีแก้ไข:
- สำหรับ Control UI ให้ใช้ HTTPS เพื่อให้เบราว์เซอร์สามารถสร้างข้อมูลประจำตัวของอุปกรณ์และจับคู่จนเสร็จสมบูรณ์
- สำหรับระบบอัตโนมัติแบบกำหนดเอง ให้ใช้ข้อมูลประจำตัวของอุปกรณ์/การจับคู่ เส้นทางตัวช่วยแบ็กเอนด์
gateway-clientแบบเชื่อมต่อภายในโดยตรงที่สงวนไว้ หรือ RPC HTTP สำหรับผู้ดูแลระบบ - ใช้
gateway.controlUi.dangerouslyDisableDeviceAuth: trueเป็นเส้นทางฉุกเฉินชั่วคราวสำหรับ Control UI เท่านั้น
WebSocket ยังคงล้มเหลว
ตรวจสอบให้แน่ใจว่าพร็อกซี:
- รองรับการอัปเกรด WebSocket (
Upgrade: websocket,Connection: upgrade) - ส่งต่อส่วนหัวข้อมูลประจำตัวในคำขออัปเกรด WebSocket (ไม่ใช่เฉพาะ HTTP)
- ไม่มีเส้นทางการยืนยันตัวตนแยกต่างหากสำหรับการเชื่อมต่อ WebSocket
การย้ายจากการยืนยันตัวตนด้วยโทเค็น
กำหนดค่าพร็อกซี
กำหนดค่าพร็อกซีให้ยืนยันตัวตนผู้ใช้และส่งต่อส่วนหัว
ทดสอบพร็อกซีแยกต่างหาก
ทดสอบการตั้งค่าพร็อกซีแยกต่างหาก (ใช้ curl พร้อมส่วนหัว)
อัปเดตการกำหนดค่า OpenClaw
อัปเดตการกำหนดค่า OpenClaw ให้ใช้การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือ
เริ่ม Gateway ใหม่
เริ่ม Gateway ใหม่
ทดสอบ WebSocket
ทดสอบการเชื่อมต่อ WebSocket จาก Control UI
ตรวจสอบ
เรียกใช้ openclaw security audit และตรวจทานผลการตรวจสอบ
เนื้อหาที่เกี่ยวข้อง
- การกำหนดค่า — เอกสารอ้างอิงการกำหนดค่า
- ขอบเขตของผู้ดำเนินการ — บทบาท ขอบเขต และการตรวจสอบการอนุมัติ
- การเข้าถึงจากระยะไกล — รูปแบบอื่นสำหรับการเข้าถึงจากระยะไกล
- ความปลอดภัย — คู่มือความปลอดภัยฉบับสมบูรณ์
- Tailscale — ทางเลือกที่เรียบง่ายกว่าสำหรับการเข้าถึงเฉพาะภายใน tailnet