---
read_when:
    - การนำการอนุมัติการจับคู่ Node ไปใช้โดยไม่มีส่วนติดต่อผู้ใช้ของ macOS
    - เพิ่มขั้นตอนการทำงานของ CLI สำหรับอนุมัติโหนดระยะไกล
    - การขยายโปรโตคอล Gateway ด้วยการจัดการ Node
summary: การจับคู่ Node ที่ Gateway เป็นเจ้าของ (ตัวเลือก B) สำหรับ iOS และ Node ระยะไกลอื่นๆ
title: การจับคู่ที่ Gateway เป็นเจ้าของ
x-i18n:
    generated_at: "2026-05-06T09:14:53Z"
    model: gpt-5.5
    provider: openai
    source_hash: 75713e04e37dcbae151d170e2eb459d0e9b9a799c64a10db731b61d7b53998b4
    source_path: gateway/pairing.md
    workflow: 16
---

ในการจับคู่ที่ 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 (เหมาะสำหรับแบบไม่มีหน้าจอ)

```bash
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`
- ระดับขอบเขตผู้ปฏิบัติงานและการตรวจสอบตอนอนุมัติสรุปไว้ใน
  [ขอบเขตผู้ปฏิบัติงาน](/th/gateway/operator-scopes)
- คำขออาจใส่ `silent: true` เป็นคำใบ้สำหรับโฟลว์อนุมัติอัตโนมัติ
- `node.pair.approve` ใช้คำสั่งที่ประกาศไว้ในคำขอที่รอดำเนินการเพื่อบังคับใช้
  ขอบเขตอนุมัติเพิ่มเติม:
  - คำขอที่ไม่มีคำสั่ง: `operator.pairing`
  - คำขอคำสั่งที่ไม่ใช่ exec: `operator.pairing` + `operator.write`
  - คำขอ `system.run` / `system.run.prepare` / `system.which`:
    `operator.pairing` + `operator.admin`

<Warning>
การจับคู่ Node เป็นโฟลว์ความเชื่อถือและตัวตน พร้อมการออกโทเค็น ไม่ได้ตรึงพื้นผิวคำสั่งสดของโหนดเป็นรายโหนด

- คำสั่งสดของโหนดมาจากสิ่งที่โหนดประกาศเมื่อเชื่อมต่อ หลังจากใช้นโยบายคำสั่งโหนดส่วนกลางของ gateway (`gateway.nodes.allowCommands` และ `denyCommands`) แล้ว
- นโยบายอนุญาตและถามสำหรับ `system.run` ต่อโหนดอยู่บนโหนดใน `exec.approvals.node.*` ไม่ได้อยู่ในบันทึกการจับคู่

</Warning>

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

<Warning>
**การเปลี่ยนแปลงที่ไม่เข้ากันย้อนหลัง:** ตั้งแต่ `2026.3.31` คำสั่งโหนดจะถูกปิดใช้งานจนกว่าการจับคู่โหนดจะได้รับการอนุมัติ การจับคู่อุปกรณ์เพียงอย่างเดียวไม่เพียงพอที่จะเปิดเผยคำสั่งโหนดที่ประกาศไว้อีกต่อไป
</Warning>

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

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

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

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

<Warning>
**การเปลี่ยนแปลงที่ไม่เข้ากันย้อนหลัง:** การรันที่มาจากโหนดตอนนี้จะอยู่บนพื้นผิวที่เชื่อถือได้แบบลดลง
</Warning>

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

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

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

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

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

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

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

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

```json5
{
  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 ไม่เข้าเกณฑ์ เส้นทางการจับคู่จึงต้องได้รับการอนุมัติอย่างชัดเจน
แทนที่จะถือว่าคำขอเป็นการเชื่อมต่อจากโฮสต์เดียวกันแบบเงียบ ๆ ดู
[การยืนยันตัวตนพร็อกซีที่เชื่อถือได้](/th/gateway/trusted-proxy-auth) สำหรับกฎเทียบเท่าเกี่ยวกับ
การยืนยันตัวตนผู้ปฏิบัติงาน

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

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

- `~/.openclaw/nodes/paired.json`
- `~/.openclaw/nodes/pending.json`

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

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

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

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

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

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

- [การจับคู่แชนเนล](/th/channels/pairing)
- [โหนด](/th/nodes)
- [CLI อุปกรณ์](/th/cli/devices)