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

# การจับคู่ที่ Gateway เป็นเจ้าของ (ตัวเลือก B)

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

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

## แนวคิด

- **คำขอที่รอดำเนินการ**: Node ขอเข้าร่วม; ต้องได้รับการอนุมัติ
- **Node ที่จับคู่แล้ว**: Node ที่ได้รับการอนุมัติพร้อม auth token ที่ออกให้แล้ว
- **ทรานสปอร์ต**: Gateway WS endpoint ส่งต่อคำขอ แต่ไม่ได้เป็นผู้ตัดสิน
  การเป็นสมาชิก (ได้ถอดการรองรับ legacy TCP bridge ออกแล้ว)

## วิธีการทำงานของการจับคู่

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

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

## เวิร์กโฟลว์ CLI (เหมาะกับการใช้งานแบบ headless)

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

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

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

Events:

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

Methods:

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

หมายเหตุ:

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

สำคัญ:

- การจับคู่ Node เป็นโฟลว์ด้านความเชื่อถือ/ตัวตน พร้อมการออก token
- โฟลว์นี้ **ไม่ได้** pin พื้นผิวคำสั่งสดของ Node แต่ละตัว
- คำสั่ง Node สดมาจากสิ่งที่ Node ประกาศตอนเชื่อมต่อ หลังจากใช้
  นโยบายคำสั่ง Node แบบ global ของ Gateway (`gateway.nodes.allowCommands` /
  `denyCommands`) แล้ว
- นโยบาย allow/ask ของ `system.run` แบบต่อ Node อยู่ที่ฝั่ง Node ใน
  `exec.approvals.node.*` ไม่ได้อยู่ในระเบียนการจับคู่

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

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

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

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

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

## ขอบเขตความเชื่อถือของ event จาก Node (2026.3.31+)

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

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

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

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

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

หากการอนุมัติแบบเงียบล้มเหลว ระบบจะ fallback ไปยังพรอมป์ต “Approve/Reject” ปกติ

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

เมื่ออุปกรณ์ที่จับคู่แล้วเชื่อมต่อใหม่พร้อมการเปลี่ยนแปลง metadata ที่ไม่อ่อนไหวเท่านั้น
(เช่น ชื่อที่แสดงหรือคำใบ้แพลตฟอร์มของไคลเอนต์) OpenClaw จะถือว่านี่เป็น `metadata-upgrade`
การอนุมัติอัตโนมัติแบบเงียบมีขอบเขตแคบ: ใช้ได้เฉพาะกับการเชื่อมต่อใหม่จาก CLI/helper ภายในเครื่องที่เชื่อถือได้ ซึ่งพิสูจน์การครอบครอง shared token หรือรหัสผ่านผ่าน loopback มาแล้วเท่านั้น Browser/Control UI clients และไคลเอนต์ระยะไกลยังคงใช้โฟลว์การอนุมัติใหม่แบบ explicit การอัปเกรดขอบเขต (จาก read เป็น write/admin) และการเปลี่ยน public key **ไม่มีสิทธิ์** ใช้การอนุมัติอัตโนมัติสำหรับ metadata-upgrade — ยังต้องเป็นคำขออนุมัติใหม่แบบ explicit

## ตัวช่วยการจับคู่ด้วย QR

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

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

## ความเป็นภายในเครื่องและ forwarded headers

Gateway pairing จะถือว่าการเชื่อมต่อเป็น loopback ก็ต่อเมื่อทั้ง raw socket
และหลักฐานจาก upstream proxy สอดคล้องกันเท่านั้น หากคำขอมาถึงบน loopback แต่
มี header `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto` ที่ชี้ไปยังต้นทางที่ไม่ใช่ภายในเครื่อง หลักฐานจาก forwarded header นั้นจะทำให้การอ้างว่าเป็น loopback ใช้ไม่ได้ เส้นทางการจับคู่จะต้องได้รับการอนุมัติแบบ explicit แทนที่จะถือเป็นการเชื่อมต่อจากเครื่องเดียวกันแบบเงียบ ๆ ดู [Trusted Proxy Auth](/th/gateway/trusted-proxy-auth) สำหรับกฎที่เทียบเท่ากันด้าน operator auth

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

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

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

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

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

- token เป็นข้อมูลลับ; ให้ถือว่า `paired.json` เป็นข้อมูลอ่อนไหว
- การหมุน token ต้องได้รับการอนุมัติใหม่ (หรือลบรายการ Node)

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

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