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 (เมื่อตั้งค่าไว้) คำขอจะได้รับอนุญาต

  • การกำหนดค่า

    json5
    {  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 เริ่มทำงาน

    การอนุมัติอุปกรณ์โดยอัตโนมัติ

    การพิสูจน์ตัวตนผ่านพร็อกซีที่เชื่อถือได้สามารถเลือกใช้ข้อมูลประจำตัวจากพร็อกซีเป็นขอบเขตการอนุมัติสำหรับอุปกรณ์เบราว์เซอร์ใหม่ได้:

    json5
    {  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 เมื่อเปิดใช้งาน กฎทั้งหมดต่อไปนี้จะมีผล:

    1. WebSocket ต้องผ่านการพิสูจน์ตัวตนด้วยเมธอด trusted-proxy พร้อมข้อมูลประจำตัวผู้ใช้ที่ไม่ว่างและผ่าน allowUsers เมื่อมีการกำหนดค่ารายการอนุญาต การเชื่อมต่อด้วยโทเค็น รหัสผ่าน Tailscale และการเชื่อมต่อที่ไม่ผ่านการพิสูจน์ตัวตนจะไม่ใช้นโยบายนี้
    2. เฉพาะอุปกรณ์เบราว์เซอร์ใหม่ของ Control UI หรือ WebChat เท่านั้นที่สามารถได้รับอนุมัติโดยอัตโนมัติ คำขอใด ๆ สำหรับอุปกรณ์ที่มีอยู่ รวมถึงการยกระดับขอบเขต จะยังคงรอการอนุมัติด้วยตนเองผ่าน openclaw devices approve <requestId>
    3. อุปกรณ์ได้รับอนุมัติด้วยบทบาท operator หากคำขอเชื่อมต่อมีขอบเขต สิทธิ์ที่มอบจะเป็นส่วนตัดที่ตรงกันทุกประการระหว่างขอบเขตที่ร้องขอกับ deviceAutoApprove.scopes หากคำขอละเว้นขอบเขต ระบบจะมอบรายการที่กำหนดค่าไว้ และหากละเว้นรายการดังกล่าว ค่าเริ่มต้นจะเป็น operator.read, operator.write และ operator.approvals จากนั้นสิทธิ์ที่มอบจะถูกจำกัดเพิ่มเติมด้วยส่วนหัวพร็อกซี x-openclaw-scopes ของการเชื่อมต่อเมื่อมีอยู่ ดังนั้นพร็อกซีที่จำกัดขอบเขตของผู้ใช้จะจำกัดสิทธิ์อุปกรณ์แบบ ถาวร ด้วย ไม่ใช่เพียงเซสชัน โดยส่วนหัวที่มีอยู่แต่เป็นค่าว่างจะไม่ให้ขอบเขตใด ๆ ข้อจำกัดนี้มีผลแม้ไคลเอนต์จะละเว้นรายการขอบเขตของตนเอง
    4. 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.read
    • x-openclaw-scopes: operator.read,operator.write
    • x-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 แบบลูปแบ็กอยู่หลังพร็อกซีต่อไปได้

    ตัวอย่างค่าส่วนหัว:

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

    การสิ้นสุด TLS ที่ Gateway

    หาก OpenClaw ให้บริการ HTTPS โดยตรงด้วยตัวเอง (ไม่มีพร็อกซีที่สิ้นสุด TLS) ให้ตั้งค่า:

    json5
    {  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

    json5
    {  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:

    yaml
    routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true
    Caddy พร้อม OAuth

    Caddy ที่ใช้ Plugin caddy-security สามารถตรวจสอบสิทธิ์ผู้ใช้และส่งส่วนหัวข้อมูลระบุตัวตนได้

    json5
    {  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP ของ Caddy/พร็อกซี sidecar    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

    ส่วนย่อย Caddyfile:

    caddy
    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

    json5
    {  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP ของ nginx/oauth2-proxy    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

    ส่วนย่อยการกำหนดค่า nginx:

    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 พร้อมการตรวจสอบสิทธิ์แบบส่งต่อ
    json5
    {  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 และตรวจทานผลการตรวจสอบ

  • เนื้อหาที่เกี่ยวข้อง

    Was this useful?
    On this page

    On this page