การจับคู่ที่ Gateway เป็นเจ้าของ

ในการจับคู่ที่ Gateway เป็นเจ้าของ Gateway คือแหล่งข้อมูลจริงสำหรับกำหนดว่าโหนดใด ได้รับอนุญาตให้เข้าร่วมได้ UI (แอป macOS, ไคลเอนต์ในอนาคต) เป็นเพียงส่วนหน้าที่ อนุมัติหรือปฏิเสธคำขอที่รอดำเนินการ

สำคัญ: โหนด WS ใช้ การจับคู่อุปกรณ์ (บทบาท node) ระหว่าง connect node.pair.* เป็นที่เก็บการจับคู่แยกต่างหาก และ ไม่ได้ ใช้กั้นการจับมือ WS เฉพาะไคลเอนต์ที่เรียก node.pair.* อย่างชัดเจนเท่านั้นที่ใช้โฟลว์นี้

# แนวคิด

• คำขอที่รอดำเนินการ: โหนดขอเข้าร่วม ต้องได้รับการอนุมัติ
• โหนดที่จับคู่แล้ว: โหนดที่ได้รับอนุมัติพร้อมโทเค็นยืนยันตัวตนที่ออกให้แล้ว
• ทรานสปอร์ต: เอ็นด์พอยต์ WS ของ Gateway ส่งต่อคำขอ แต่ไม่ได้ตัดสิน สมาชิกภาพ (การรองรับบริดจ์ TCP แบบเดิมถูกนำออกแล้ว)

# การจับคู่ทำงานอย่างไร

1. โหนดเชื่อมต่อกับ WS ของ Gateway และขอจับคู่
2. Gateway เก็บ คำขอที่รอดำเนินการ และส่งอีเวนต์ node.pair.requested
3. คุณอนุมัติหรือปฏิเสธคำขอ (CLI หรือ UI)
4. เมื่ออนุมัติ Gateway จะออก โทเค็นใหม่ (โทเค็นจะถูกหมุนเวียนเมื่อจับคู่ใหม่)
5. โหนดเชื่อมต่อใหม่โดยใช้โทเค็น และตอนนี้ถือว่า "จับคู่แล้ว"

คำขอที่รอดำเนินการจะหมดอายุโดยอัตโนมัติหลังจาก 5 นาที

# เวิร์กโฟลว์ CLI (เหมาะสำหรับแบบไม่มีหน้าจอ)

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status แสดงโหนดที่จับคู่แล้ว/เชื่อมต่ออยู่ และความสามารถของโหนดเหล่านั้น

# พื้นผิว API (โปรโตคอล Gateway)

อีเวนต์:

• node.pair.requested - ส่งเมื่อมีการสร้างคำขอที่รอดำเนินการใหม่
• node.pair.resolved - ส่งเมื่อคำขอได้รับการอนุมัติ/ปฏิเสธ/หมดอายุ

เมธอด:

• node.pair.request - สร้างหรือใช้คำขอที่รอดำเนินการซ้ำ
• node.pair.list - แสดงรายการโหนดที่รอดำเนินการ + โหนดที่จับคู่แล้ว (operator.pairing)
• node.pair.approve - อนุมัติคำขอที่รอดำเนินการ (ออกโทเค็น)
• node.pair.reject - ปฏิเสธคำขอที่รอดำเนินการ
• node.pair.remove - ลบรายการโหนดที่จับคู่แล้วซึ่งค้างอยู่
• node.pair.verify - ตรวจสอบ { nodeId, token }

หมายเหตุ:

• node.pair.request เป็นแบบ idempotent ต่อโหนด: การเรียกซ้ำจะคืน คำขอที่รอดำเนินการเดียวกัน
• คำขอซ้ำสำหรับโหนดที่รอดำเนินการเดียวกันจะรีเฟรชเมทาดาทาโหนดที่เก็บไว้ และสแนปชอตคำสั่งที่ประกาศล่าสุดซึ่งอยู่ในรายการอนุญาต เพื่อให้ผู้ปฏิบัติงานมองเห็นได้
• การอนุมัติจะสร้างโทเค็นใหม่ เสมอ ไม่มีโทเค็นใดถูกคืนจาก node.pair.request
• ระดับขอบเขตผู้ปฏิบัติงานและการตรวจสอบตอนอนุมัติสรุปไว้ใน ขอบเขตผู้ปฏิบัติงาน
• คำขออาจใส่ silent: true เป็นคำใบ้สำหรับโฟลว์อนุมัติอัตโนมัติ
• node.pair.approve ใช้คำสั่งที่ประกาศไว้ในคำขอที่รอดำเนินการเพื่อบังคับใช้ ขอบเขตอนุมัติเพิ่มเติม:
  • คำขอที่ไม่มีคำสั่ง: operator.pairing
  • คำขอคำสั่งที่ไม่ใช่ exec: operator.pairing + operator.write
  • คำขอ system.run / system.run.prepare / system.which: operator.pairing + operator.admin

# การกั้นคำสั่ง Node (2026.3.31+)

เมื่อโหนดเชื่อมต่อเป็นครั้งแรก ระบบจะขอจับคู่โดยอัตโนมัติ จนกว่าคำขอจับคู่จะได้รับการอนุมัติ คำสั่งโหนดที่รอดำเนินการทั้งหมดจากโหนดนั้นจะถูกกรองและจะไม่ถูกเรียกใช้งาน เมื่อสร้างความเชื่อถือผ่านการอนุมัติการจับคู่แล้ว คำสั่งที่โหนดประกาศจะพร้อมใช้งานภายใต้นโยบายคำสั่งปกติ

หมายความว่า:

• โหนดที่ก่อนหน้านี้พึ่งพาเฉพาะการจับคู่อุปกรณ์เพื่อเปิดเผยคำสั่ง ต้องทำการจับคู่โหนดให้เสร็จสมบูรณ์แล้ว
• คำสั่งที่ถูกจัดคิวก่อนการอนุมัติการจับคู่จะถูกทิ้ง ไม่ถูกเลื่อนออกไป

# ขอบเขตความเชื่อถือของอีเวนต์ Node (2026.3.31+)

สรุปที่มาจากโหนดและอีเวนต์เซสชันที่เกี่ยวข้องถูกจำกัดไว้เฉพาะพื้นผิวที่เชื่อถือได้ตามเจตนา โฟลว์ที่ขับเคลื่อนด้วยการแจ้งเตือนหรือถูกทริกเกอร์โดยโหนด ซึ่งก่อนหน้านี้พึ่งพาการเข้าถึงเครื่องโฮสต์หรือเครื่องมือเซสชันที่กว้างกว่า อาจต้องปรับเปลี่ยน การเสริมความแข็งแกร่งนี้ทำให้มั่นใจว่าอีเวนต์โหนดไม่สามารถยกระดับไปสู่การเข้าถึงเครื่องมือระดับโฮสต์เกินกว่าที่ขอบเขตความเชื่อถือของโหนดอนุญาต

การอัปเดตสถานะการปรากฏของโหนดแบบคงทนจะทำตามขอบเขตตัวตนเดียวกัน อีเวนต์ node.presence.alive จะ ได้รับการยอมรับเฉพาะจากเซสชันอุปกรณ์โหนดที่ผ่านการยืนยันตัวตน และอัปเดตเมทาดาทาการจับคู่เฉพาะเมื่อ ตัวตนอุปกรณ์/โหนดจับคู่แล้ว ค่า client.id ที่ประกาศด้วยตัวเองไม่เพียงพอสำหรับเขียน สถานะที่เห็นล่าสุด

# การอนุมัติอัตโนมัติ (แอป macOS)

แอป macOS สามารถพยายามทำ การอนุมัติแบบเงียบ ได้ตามตัวเลือก เมื่อ:

• คำขอถูกทำเครื่องหมายเป็น silent และ
• แอปสามารถตรวจสอบการเชื่อมต่อ SSH ไปยังโฮสต์ gateway โดยใช้ผู้ใช้เดียวกันได้

หากการอนุมัติแบบเงียบล้มเหลว จะย้อนกลับไปใช้พรอมป์ "อนุมัติ/ปฏิเสธ" ตามปกติ

# การอนุมัติอัตโนมัติของอุปกรณ์แบบ CIDR ที่เชื่อถือได้

การจับคู่อุปกรณ์ WS สำหรับ role: node ยังคงเป็นแบบแมนนวลโดยค่าเริ่มต้น สำหรับเครือข่าย โหนดส่วนตัวที่ Gateway เชื่อถือเส้นทางเครือข่ายอยู่แล้ว ผู้ปฏิบัติงานสามารถ เลือกใช้ได้ด้วย CIDR หรือ IP แบบตรงตัวที่ระบุชัดเจน:

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

ขอบเขตความปลอดภัย:

• ปิดใช้งานเมื่อไม่ได้ตั้งค่า gateway.nodes.pairing.autoApproveCidrs
• ไม่มีโหมดอนุมัติอัตโนมัติแบบครอบคลุมทั้ง LAN หรือเครือข่ายส่วนตัว
• เฉพาะการจับคู่อุปกรณ์ role: node ใหม่ที่ไม่มีขอบเขตที่ร้องขอเท่านั้นที่เข้าเกณฑ์
• ไคลเอนต์ผู้ปฏิบัติงาน เบราว์เซอร์ Control UI และ WebChat ยังคงเป็นแบบแมนนวล
• การอัปเกรดบทบาท ขอบเขต เมทาดาทา และกุญแจสาธารณะยังคงเป็นแบบแมนนวล
• เส้นทางเฮดเดอร์พร็อกซีที่เชื่อถือได้แบบ same-host loopback ไม่เข้าเกณฑ์ เพราะเส้นทางนั้น อาจถูกปลอมแปลงโดยผู้เรียกในเครื่องได้

# การอนุมัติอัตโนมัติสำหรับการอัปเกรดเมทาดาทา

เมื่ออุปกรณ์ที่จับคู่แล้วเชื่อมต่อใหม่พร้อมการเปลี่ยนแปลงเมทาดาทาที่ไม่อ่อนไหวเท่านั้น (เช่น ชื่อที่แสดงหรือคำใบ้แพลตฟอร์มไคลเอนต์) OpenClaw จะถือว่าเป็น metadata-upgrade การอนุมัติอัตโนมัติแบบเงียบมีขอบเขตแคบ: ใช้เฉพาะ กับการเชื่อมต่อใหม่ในเครื่องที่ไม่ใช่เบราว์เซอร์และเชื่อถือได้ ซึ่งได้พิสูจน์การครอบครองข้อมูลรับรองในเครื่อง หรือข้อมูลรับรองร่วมแล้ว รวมถึงการเชื่อมต่อใหม่จากแอปเนทีฟบนโฮสต์เดียวกันหลังการเปลี่ยนแปลงเมทาดาทา เวอร์ชัน OS ไคลเอนต์เบราว์เซอร์/Control UI และไคลเอนต์ระยะไกลยังคง ใช้โฟลว์อนุมัติซ้ำแบบชัดเจน การอัปเกรดขอบเขต (อ่านเป็นเขียน/admin) และ การเปลี่ยนกุญแจสาธารณะ ไม่ เข้าเกณฑ์สำหรับการอนุมัติอัตโนมัติแบบ metadata-upgrade - ยังคงเป็นคำขออนุมัติซ้ำแบบชัดเจน

# ตัวช่วยจับคู่ QR

/pair qr เรนเดอร์เพย์โหลดการจับคู่เป็นสื่อที่มีโครงสร้าง เพื่อให้ไคลเอนต์มือถือและ เบราว์เซอร์สามารถสแกนได้โดยตรง

การลบอุปกรณ์ยังจะกวาดล้างคำขอจับคู่ที่รอดำเนินการซึ่งค้างอยู่สำหรับ รหัสอุปกรณ์นั้นด้วย ดังนั้น nodes pending จะไม่แสดงแถวกำพร้าหลังการเพิกถอน

# ความเป็นภายในพื้นที่และเฮดเดอร์ที่ส่งต่อ

การจับคู่ของ Gateway จะถือว่าการเชื่อมต่อเป็น loopback เฉพาะเมื่อทั้งซ็อกเก็ตดิบ และหลักฐานพร็อกซีต้นทางใด ๆ สอดคล้องกัน หากคำขอมาถึงบน loopback แต่ มีเฮดเดอร์ X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto ที่ชี้ไปยังต้นทางที่ไม่ใช่ภายใน หลักฐานเฮดเดอร์ที่ส่งต่อนั้นจะทำให้ การอ้างว่าเป็นพื้นที่ loopback ไม่เข้าเกณฑ์ เส้นทางการจับคู่จึงต้องได้รับการอนุมัติอย่างชัดเจน แทนที่จะถือว่าคำขอเป็นการเชื่อมต่อจากโฮสต์เดียวกันแบบเงียบ ๆ ดู การยืนยันตัวตนพร็อกซีที่เชื่อถือได้ สำหรับกฎเทียบเท่าเกี่ยวกับ การยืนยันตัวตนผู้ปฏิบัติงาน

# พื้นที่จัดเก็บ (ภายในเครื่อง, ส่วนตัว)

สถานะการจับคู่ถูกเก็บไว้ใต้ไดเรกทอรีสถานะของ Gateway (ค่าเริ่มต้น ~/.openclaw):

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

หากคุณแทนที่ OPENCLAW_STATE_DIR โฟลเดอร์ nodes/ จะย้ายตามไปด้วย

หมายเหตุด้านความปลอดภัย:

• โทเค็นเป็นความลับ ให้ถือว่า paired.json เป็นข้อมูลอ่อนไหว
• การหมุนเวียนโทเค็นต้องมีการอนุมัติซ้ำ (หรือการลบรายการโหนด)

# พฤติกรรมของทรานสปอร์ต

• ทรานสปอร์ตเป็นแบบ ไร้สถานะ ไม่เก็บสมาชิกภาพ
• หาก Gateway ออฟไลน์หรือปิดใช้งานการจับคู่ โหนดจะจับคู่ไม่ได้
• หาก Gateway อยู่ในโหมดระยะไกล การจับคู่ยังคงเกิดขึ้นกับที่เก็บของ Gateway ระยะไกล

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

• การจับคู่แชนเนล
• โหนด
• CLI อุปกรณ์