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

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

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

## แนวคิด

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

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

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

คำขอที่รอดำเนินการหมดอายุโดยอัตโนมัติหลังจาก **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` แสดง Node ที่จับคู่แล้ว/เชื่อมต่ออยู่ และความสามารถของ Node เหล่านั้น

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

อีเวนต์:

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

เมธอด:

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

หมายเหตุ:

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

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

</Warning>

## การควบคุมคำสั่ง Node (2026.3.31+)

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

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

ซึ่งหมายความว่า:

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

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

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

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

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

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

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

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

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

## การอนุมัติอัตโนมัติสำหรับอุปกรณ์ Trusted-CIDR

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

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

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

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

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

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

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

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

การลบอุปกรณ์จะกวาดคำขอจับคู่ที่รอดำเนินการและค้างเก่าสำหรับ
id ของอุปกรณ์นั้นด้วย ดังนั้น `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` เป็นข้อมูลอ่อนไหว
- การหมุนเวียนโทเค็นต้องมีการอนุมัติซ้ำ (หรือลบรายการ Node)

## พฤติกรรมการขนส่ง

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

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

- [การจับคู่ช่องทาง](/th/channels/pairing)
- [Node](/th/nodes)
- [CLI อุปกรณ์](/th/cli/devices)
