---
read_when:
    - การดีบักข้อผิดพลาดขอบเขตของโอเปอเรเตอร์ที่หายไป
    - กำลังตรวจสอบการอนุมัติการจับคู่ device หรือ node
    - การเพิ่มหรือจัดประเภทเมธอด RPC ของ Gateway
summary: บทบาทของผู้ปฏิบัติการ ขอบเขต และการตรวจสอบ ณ เวลาการอนุมัติสำหรับไคลเอนต์ Gateway
title: ขอบเขตของผู้ปฏิบัติการ
x-i18n:
    generated_at: "2026-06-27T17:36:33Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: dc59453ae1a73b52276185de2cedd1ed4da027111168eda8107d6ba0b74aec2f
    source_path: gateway/operator-scopes.md
    workflow: 16
---

ขอบเขตของผู้ปฏิบัติการกำหนดว่าไคลเอนต์ Gateway ทำอะไรได้บ้างหลังจากยืนยันตัวตนแล้ว
ขอบเขตเหล่านี้เป็น guardrail ของ control-plane ภายในโดเมนผู้ปฏิบัติการ Gateway ที่เชื่อถือได้หนึ่งโดเมน
ไม่ใช่การแยกแบบ multi-tenant ที่ป้องกันผู้ไม่หวังดี หากคุณต้องการการแยกที่เข้มงวดระหว่าง
บุคคล ทีม หรือเครื่อง ให้รัน Gateway แยกกันภายใต้ผู้ใช้ OS หรือ
โฮสต์ที่แยกกัน

ที่เกี่ยวข้อง: [ความปลอดภัย](/th/gateway/security), [โปรโตคอล Gateway](/th/gateway/protocol),
[การจับคู่ Gateway](/th/gateway/pairing), [CLI อุปกรณ์](/th/cli/devices).

## บทบาท

ไคลเอนต์ Gateway WebSocket เชื่อมต่อด้วยบทบาทหนึ่งบทบาท:

- `operator`: ไคลเอนต์ control-plane เช่น CLI, Control UI, ระบบอัตโนมัติ และ
  กระบวนการช่วยเหลือที่เชื่อถือได้
- `node`: โฮสต์ความสามารถ เช่น macOS, iOS, Android หรือ Node แบบ headless ที่
  เปิดเผยคำสั่งผ่าน `node.invoke`

เมธอด RPC ของผู้ปฏิบัติการต้องใช้บทบาท `operator` เมธอดที่มีต้นทางจาก Node
ต้องใช้บทบาท `node`

## ระดับขอบเขต

| ขอบเขต                   | ความหมาย                                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operator.read`         | สถานะ รายการ แคตตาล็อก บันทึก การอ่านเซสชัน และการเรียก control-plane อื่นๆ ที่ไม่เปลี่ยนแปลงข้อมูลแบบอ่านอย่างเดียว                                                                                    |
| `operator.write`        | การกระทำของผู้ปฏิบัติการที่เปลี่ยนแปลงข้อมูลตามปกติ เช่น การส่งข้อความ การเรียกใช้เครื่องมือ การอัปเดตการตั้งค่า talk/voice และการส่งต่อคำสั่ง Node รวมถึงทำให้ผ่าน `operator.read` ด้วย                      |
| `operator.admin`        | การเข้าถึง control-plane ระดับผู้ดูแล ทำให้ผ่านทุกขอบเขต `operator.*` จำเป็นสำหรับการเปลี่ยนแปลง config, การอัปเดต, native hooks, namespace ที่สงวนไว้และอ่อนไหว และการอนุมัติที่มีความเสี่ยงสูง |
| `operator.pairing`      | การจัดการการจับคู่อุปกรณ์และ Node รวมถึงการแสดงรายการ การอนุมัติ การปฏิเสธ การลบ การหมุนเวียน และการเพิกถอนระเบียนการจับคู่หรือโทเค็นอุปกรณ์                                       |
| `operator.approvals`    | API การอนุมัติ Exec และ Plugin                                                                                                                                                        |
| `operator.talk.secrets` | การอ่านการกำหนดค่า Talk พร้อมรวม secrets                                                                                                                                     |

ขอบเขต `operator.*` ในอนาคตที่ไม่รู้จักต้องตรงกันแบบเป๊ะ เว้นแต่ว่าผู้เรียกมี
`operator.admin`

## ขอบเขตของเมธอดเป็นเพียงด่านแรก

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

ตัวอย่าง:

- `device.pair.approve` เข้าถึงได้ด้วย `operator.pairing` แต่การอนุมัติ
  อุปกรณ์ operator สามารถออกหรือคงไว้ได้เฉพาะขอบเขตที่ผู้เรียกมีอยู่แล้ว
- `node.pair.approve` เข้าถึงได้ด้วย `operator.pairing` จากนั้นจะอนุมาน
  ขอบเขตการอนุมัติเพิ่มเติมจากรายการคำสั่ง Node ที่รอดำเนินการ
- `chat.send` โดยปกติเป็นเมธอดที่อยู่ในขอบเขต write แต่ `/config set`
  และ `/config unset` แบบถาวรต้องใช้ `operator.admin` ที่ระดับคำสั่ง

สิ่งนี้ทำให้ผู้ปฏิบัติการที่มีขอบเขตต่ำกว่าสามารถดำเนินการจับคู่ที่มีความเสี่ยงต่ำได้
โดยไม่ต้องทำให้การอนุมัติการจับคู่ทั้งหมดเป็น admin-only

## การอนุมัติการจับคู่อุปกรณ์

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

เมื่ออนุมัติคำขออุปกรณ์:

- คำขอที่ไม่มีบทบาท operator ไม่ต้องมีการอนุมัติขอบเขตโทเค็น operator
- คำขอสำหรับบทบาทอุปกรณ์ที่ไม่ใช่ operator เช่น `node` ต้องใช้
  `operator.admin` แม้ว่า `device.pair.approve` จะเข้าถึงได้ด้วย
  `operator.pairing`
- คำขอสำหรับ `operator.read`, `operator.write`, `operator.approvals`,
  `operator.pairing` หรือ `operator.talk.secrets` ต้องให้ผู้เรียกมี
  ขอบเขตเหล่านั้น หรือมี `operator.admin`
- คำขอสำหรับ `operator.admin` ต้องใช้ `operator.admin`
- คำขอ repair ที่ไม่มีขอบเขตระบุชัดเจนสามารถสืบทอดขอบเขตโทเค็น operator
  ที่มีอยู่ได้ หากโทเค็นที่มีอยู่นั้นอยู่ในขอบเขต admin การอนุมัติก็ยังต้องใช้
  `operator.admin`

เซสชัน shared-secret และ trusted-proxy ที่ไม่ใช่ admin สามารถอนุมัติคำขออุปกรณ์ operator
ได้เฉพาะภายในขอบเขต operator ที่ประกาศไว้เองเท่านั้น การอนุมัติบทบาทที่ไม่ใช่ operator
เป็น admin-only แม้ว่าเซสชันเหล่านั้นจะสามารถใช้
`operator.pairing` ได้ในกรณีอื่น

สำหรับเซสชันโทเค็นอุปกรณ์ที่จับคู่แล้ว การจัดการก็จำกัดอยู่กับตัวเองเช่นกัน เว้นแต่ว่า
ผู้เรียกมี `operator.admin`: ผู้เรียกที่ไม่ใช่ admin จะเห็นเฉพาะรายการการจับคู่
ของตัวเอง อนุมัติหรือปฏิเสธได้เฉพาะคำขอที่รอดำเนินการของตัวเอง และหมุนเวียน
เพิกถอน หรือลบได้เฉพาะรายการอุปกรณ์ของตัวเอง

## การอนุมัติการจับคู่ Node

`node.pair.*` แบบเดิมใช้ store การจับคู่ Node แยกต่างหากที่ Gateway เป็นเจ้าของ Node แบบ WS
ใช้การจับคู่อุปกรณ์ด้วย `role: node` แต่ใช้ชุดคำศัพท์ระดับการอนุมัติเดียวกัน

`node.pair.approve` ใช้รายการคำสั่งของคำขอที่รอดำเนินการเพื่ออนุมาน
ขอบเขตที่ต้องใช้เพิ่มเติม:

- คำขอที่ไม่มีคำสั่ง: `operator.pairing`
- คำสั่ง Node ที่ไม่ใช่ exec: `operator.pairing` + `operator.write`
- `system.run`, `system.run.prepare` หรือ `system.which`:
  `operator.pairing` + `operator.admin`

การจับคู่ Node สร้างตัวตนและความเชื่อถือ แต่ไม่ได้แทนที่นโยบาย
การอนุมัติ exec `system.run` ของ Node เอง

## การยืนยันตัวตนด้วย shared-secret

การยืนยันตัวตนด้วยโทเค็น/รหัสผ่าน Gateway แบบ shared จะถูกถือเป็นการเข้าถึงของผู้ปฏิบัติการที่เชื่อถือได้สำหรับ
Gateway นั้น พื้นผิว HTTP ที่เข้ากันได้กับ OpenAI, `/tools/invoke` และ endpoint ประวัติเซสชัน HTTP
จะคืนค่าชุดขอบเขตเริ่มต้นของผู้ปฏิบัติการแบบเต็มตามปกติสำหรับการยืนยันตัวตน bearer แบบ shared-secret
แม้ว่าผู้เรียกจะส่งขอบเขตที่ประกาศไว้แคบกว่าก็ตาม

โหมดที่มีตัวตนประกอบอยู่ เช่น การยืนยันตัวตนแบบ trusted proxy หรือ private-ingress `none`
ยังคงสามารถเคารพขอบเขตที่ประกาศไว้อย่างชัดเจนได้ ใช้ Gateway แยกกันสำหรับการแยก
ขอบเขตความเชื่อถือจริง