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

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

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

แนวคิด

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

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

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

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

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

openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw 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 ของอุปกรณ์: เปลี่ยนแปลง devices/paired.json และ ทำให้เซสชันบทบาทโหนดของอุปกรณ์นั้นไม่ถูกต้อง/ตัดการเชื่อมต่อ อุปกรณ์ หลายบทบาท (เช่น มี operator ด้วย) จะยังคงแถวของตัวเองไว้และเสียเฉพาะบทบาท node ส่วนแถวอุปกรณ์ที่มีเฉพาะโหนดจะถูกลบ นอกจากนี้ยังลบรายการการจับคู่โหนดเดิม ที่ Gateway เป็นเจ้าของซึ่งตรงกันด้วย Authz: operator.pairing สามารถลบ แถวโหนดที่ไม่ใช่ผู้ปฏิบัติการได้ ส่วนผู้เรียกด้วยโทเค็นอุปกรณ์ที่เพิกถอนบทบาทโหนด ของตนเอง บนอุปกรณ์หลายบทบาทต้องมี operator.admin เพิ่มเติม
• node.pair.verify - ตรวจสอบ { nodeId, token }

หมายเหตุ:

• node.pair.request เป็น idempotent ต่อโหนด: การเรียกซ้ำจะคืน คำขอที่รอดำเนินการเดียวกัน
• คำขอซ้ำสำหรับโหนดที่รอดำเนินการเดียวกันยังรีเฟรช metadata ของโหนดที่จัดเก็บไว้ และ snapshot คำสั่งที่ประกาศล่าสุดซึ่งอยู่ใน allowlist เพื่อให้ผู้ปฏิบัติการมองเห็น
• การอนุมัติจะสร้างโทเค็นใหม่เสมอ ทุกครั้ง; จะไม่มีการคืนโทเค็นจาก 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

การควบคุมคำสั่งโหนด (2026.3.31+)

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

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

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

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

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

การอัปเดตสถานะการมีอยู่ของโหนดแบบคงทนทำตามขอบเขตอัตลักษณ์เดียวกัน อีเวนต์ node.presence.alive จะ ยอมรับเฉพาะจากเซสชันอุปกรณ์โหนดที่ผ่านการยืนยันตัวตน และอัปเดต metadata การจับคู่เฉพาะเมื่อ อัตลักษณ์อุปกรณ์/โหนดถูกจับคู่ไว้แล้ว ค่า 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 ยังคงเป็นแบบทำเอง
• การอัปเกรดบทบาท, ขอบเขต, metadata และกุญแจสาธารณะยังคงเป็นแบบทำเอง
• เส้นทางเฮดเดอร์พร็อกซีที่เชื่อถือได้ของ same-host loopback ไม่เข้าเงื่อนไข เพราะ เส้นทางนั้นสามารถถูกปลอมโดยผู้เรียกในเครื่องได้

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

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

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

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

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

ตำแหน่งภายในเครื่องและเฮดเดอร์ที่ส่งต่อ

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

ที่เก็บข้อมูล (ภายในเครื่อง, ส่วนตัว)

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

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

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

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

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

พฤติกรรม Transport

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

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

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