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

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

```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` ของอุปกรณ์: เปลี่ยนแปลง `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`
- ระดับขอบเขตผู้ปฏิบัติการและการตรวจสอบตอนอนุมัติสรุปไว้ใน
  [ขอบเขตผู้ปฏิบัติการ](/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>
การจับคู่โหนดเป็นขั้นตอนความน่าเชื่อถือและอัตลักษณ์พร้อมการออกโทเค็น ขั้นตอนนี้ **ไม่ได้** ตรึงพื้นผิวคำสั่งสดของโหนดแบบรายโหนด

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

</Warning>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## พฤติกรรม Transport

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

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

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