Plugin HTTP RPC สำหรับผู้ดูแลระบบ

Plugin admin-http-rpc ที่มาพร้อมชุดเผยแพร่เปิดเผยเมธอด control-plane ของ Gateway ที่เลือกไว้ผ่าน HTTP สำหรับระบบอัตโนมัติบนโฮสต์ที่เชื่อถือได้ซึ่งไม่สามารถใช้ไคลเอนต์ RPC ผ่าน WebSocket ของ Gateway ตามปกติได้

Plugin นี้รวมมากับ OpenClaw แต่ปิดไว้โดยค่าเริ่มต้น เมื่อปิดใช้งาน เส้นทางจะไม่ถูกลงทะเบียน เมื่อเปิดใช้งาน จะเพิ่ม:

• POST /api/v1/admin/rpc
• listener เดียวกับ Gateway: http://<gateway-host>:<port>/api/v1/admin/rpc

เปิดใช้งานเฉพาะสำหรับเครื่องมือโฮสต์ส่วนตัว ระบบอัตโนมัติบน tailnet หรือ ingress ภายในที่เชื่อถือได้เท่านั้น อย่าเปิดเผยเส้นทางนี้โดยตรงต่ออินเทอร์เน็ตสาธารณะ

ก่อนเปิดใช้งาน

RPC ผู้ดูแลผ่าน HTTP เป็นพื้นผิว control-plane สำหรับผู้ปฏิบัติการแบบเต็มรูปแบบ ผู้เรียกใดก็ตามที่ผ่านการยืนยันตัวตน HTTP ของ Gateway สามารถเรียกเมธอดใน allowlist บนหน้านี้ได้

ใช้เมื่อเงื่อนไขทั้งหมดนี้เป็นจริง:

• ผู้เรียกได้รับความไว้วางใจให้ปฏิบัติการ Gateway
• ผู้เรียกไม่สามารถใช้ไคลเอนต์ RPC ผ่าน WebSocket ได้
• เส้นทางเข้าถึงได้เฉพาะบน loopback, tailnet หรือ ingress ส่วนตัวที่ยืนยันตัวตนแล้ว
• คุณได้ตรวจสอบเมธอดที่อนุญาตแล้ว และเมธอดเหล่านั้นตรงกับระบบอัตโนมัติที่คุณวางแผนจะรัน

ใช้เส้นทาง RPC ผ่าน WebSocket สำหรับไคลเอนต์ OpenClaw และเครื่องมือแบบโต้ตอบที่สามารถคงการเชื่อมต่อ WebSocket ของ Gateway ไว้ได้

เปิดใช้งาน

เปิดใช้งาน Plugin ที่มาพร้อมชุดเผยแพร่:

openclaw plugins enable admin-http-rpcopenclaw gateway restart

{  plugins: {    entries: {      "admin-http-rpc": { enabled: true },    },  },}

เส้นทางจะถูกลงทะเบียนระหว่างการเริ่มต้น Plugin รีสตาร์ท Gateway หลังจากเปลี่ยนการกำหนดค่า Plugin

ปิดใช้งานเมื่อคุณไม่ต้องการพื้นผิว HTTP อีกต่อไป:

openclaw plugins disable admin-http-rpcopenclaw gateway restart

ตรวจสอบเส้นทาง

ใช้ health เป็นคำขอที่ปลอดภัยที่สุดและเล็กที่สุด:

curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \  -H 'Authorization: Bearer <gateway-token>' \  -H 'Content-Type: application/json' \  -d '{"method":"health","params":{}}'

การตอบกลับที่สำเร็จมี ok: true:

{  "id": "generated-request-id",  "ok": true,  "payload": {    "status": "ok"  }}

เมื่อ Plugin ถูกปิดใช้งาน เส้นทางจะส่งคืน 404 เพราะไม่ได้ลงทะเบียนไว้

การยืนยันตัวตน

เส้นทางของ Plugin ใช้การยืนยันตัวตน HTTP ของ Gateway

เส้นทางการยืนยันตัวตนที่พบบ่อย:

• การยืนยันตัวตนด้วย shared-secret (gateway.auth.mode="token" หรือ "password"): Authorization: Bearer <token-or-password>
• การยืนยันตัวตน HTTP ที่มีตัวตนที่เชื่อถือได้ (gateway.auth.mode="trusted-proxy"): ส่งผ่านพร็อกซีที่รับรู้ตัวตนตามที่กำหนดค่าไว้ และให้พร็อกซีนั้นฉีดส่วนหัวตัวตนที่จำเป็น
• การยืนยันตัวตนแบบเปิดสำหรับ ingress ส่วนตัว (gateway.auth.mode="none"): ไม่ต้องมีส่วนหัวการยืนยันตัวตน

โมเดลความปลอดภัย

ปฏิบัติต่อ Plugin นี้เป็นพื้นผิวผู้ปฏิบัติการ Gateway แบบเต็มรูปแบบ

• การเปิดใช้งาน Plugin จงใจให้เข้าถึงเมธอด RPC ผู้ดูแลใน allowlist ที่ /api/v1/admin/rpc
• Plugin ประกาศสัญญา manifest ที่สงวนไว้ contracts.gatewayMethodDispatch: ["authenticated-request"] เพื่อให้เส้นทาง HTTP ที่ยืนยันตัวตนกับ Gateway แล้วสามารถ dispatch เมธอด control-plane ภายในโปรเซสได้
• การยืนยันตัวตน bearer ด้วย shared-secret พิสูจน์การครอบครองความลับผู้ปฏิบัติการของ gateway
• สำหรับการยืนยันตัวตนแบบ token และ password ส่วนหัว x-openclaw-scopes ที่แคบกว่าจะถูกละเว้น และค่าเริ่มต้นผู้ปฏิบัติการเต็มรูปแบบตามปกติจะถูกคืนค่า
• โหมด HTTP ที่มีตัวตนที่เชื่อถือได้จะเคารพ x-openclaw-scopes เมื่อมีอยู่
• gateway.auth.mode="none" หมายความว่าเส้นทางนี้ไม่มีการยืนยันตัวตนหาก Plugin เปิดใช้งานอยู่ ใช้เฉพาะหลัง ingress ส่วนตัวที่คุณเชื่อถืออย่างเต็มที่เท่านั้น
• คำขอ dispatch ผ่านตัวจัดการเมธอด Gateway และการตรวจสอบ scope เดียวกับ RPC ผ่าน WebSocket หลังจากการยืนยันตัวตนของเส้นทาง Plugin ผ่านแล้ว
• เก็บเส้นทางนี้ไว้บน loopback, tailnet หรือ ingress ส่วนตัวที่เชื่อถือได้ อย่าเปิดเผยโดยตรงต่ออินเทอร์เน็ตสาธารณะ
• สัญญา manifest ของ Plugin ไม่ใช่ sandbox สัญญาเหล่านี้ป้องกันการใช้ตัวช่วย SDK ที่สงวนไว้โดยไม่ตั้งใจ Plugin ที่เชื่อถือได้ยังคงรันในโปรเซส Gateway

ใช้ gateway แยกกันเมื่อผู้เรียกข้ามขอบเขตความไว้วางใจ

คำขอ

POST /api/v1/admin/rpcAuthorization: Bearer <gateway-token>Content-Type: application/json

{  "id": "optional-request-id",  "method": "health",  "params": {}}

ฟิลด์:

• id (สตริง, ไม่บังคับ): คัดลอกเข้าไปในการตอบกลับ UUID จะถูกสร้างเมื่อไม่ระบุ
• method (สตริง, จำเป็น): ชื่อเมธอด Gateway ที่อนุญาต
• params (ค่าใดก็ได้, ไม่บังคับ): params เฉพาะเมธอด

ขนาดเนื้อหาคำขอสูงสุดเริ่มต้นคือ 1 MB

การตอบกลับ

การตอบกลับที่สำเร็จใช้รูปแบบ RPC ของ Gateway:

{  "id": "optional-request-id",  "ok": true,  "payload": {}}

ข้อผิดพลาดของเมธอด Gateway ใช้:

{  "id": "optional-request-id",  "ok": false,  "error": {    "code": "INVALID_REQUEST",    "message": "bad params"  }}

สถานะ HTTP จะตามข้อผิดพลาดของ Gateway เมื่อเป็นไปได้ ตัวอย่างเช่น INVALID_REQUEST ส่งคืน 400 และ UNAVAILABLE ส่งคืน 503

เมธอดที่อนุญาต

• การค้นพบ: commands.list ส่งคืนชื่อเมธอด RPC ผ่าน HTTP ที่ Plugin นี้อนุญาต
• gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request
• การกำหนดค่า: config.get, config.schema, config.schema.lookup, config.set, config.patch, config.apply
• ช่องทาง: channels.status, channels.start, channels.stop, channels.logout
• เว็บ: web.login.start, web.login.wait
• โมเดล: models.list, models.authStatus
• เอเจนต์: agents.list, agents.create, agents.update, agents.delete
• การอนุมัติ: exec.approvals.get, exec.approvals.set, exec.approvals.node.get, exec.approvals.node.set
• Cron: cron.status, cron.list, cron.get, cron.runs, cron.add, cron.update, cron.remove, cron.run
• อุปกรณ์: device.pair.list, device.pair.approve, device.pair.reject, device.pair.remove
• โหนด: node.list, node.describe, node.pair.list, node.pair.approve, node.pair.reject, node.pair.remove, node.rename
• งาน: tasks.list, tasks.get, tasks.cancel
• การวินิจฉัย: doctor.memory.status, update.status

เมธอด Gateway อื่นจะถูกบล็อกจนกว่าจะถูกเพิ่มอย่างตั้งใจ

การเปรียบเทียบกับ WebSocket

เส้นทาง RPC ผ่าน WebSocket ของ Gateway ตามปกติยังคงเป็น API control-plane ที่แนะนำสำหรับไคลเอนต์ OpenClaw ใช้ RPC ผู้ดูแลผ่าน HTTP เฉพาะสำหรับเครื่องมือโฮสต์ที่ต้องการพื้นผิว HTTP แบบคำขอ/การตอบกลับ

ไคลเอนต์ WebSocket แบบ shared-token ที่ไม่มีตัวตนอุปกรณ์ที่เชื่อถือได้ไม่สามารถประกาศ scope ผู้ดูแลด้วยตนเองระหว่างการเชื่อมต่อได้ RPC ผู้ดูแลผ่าน HTTP ตั้งใจทำตามโมเดลผู้ปฏิบัติการ HTTP ที่เชื่อถือได้ที่มีอยู่: เมื่อ Plugin เปิดใช้งาน การยืนยันตัวตน bearer ด้วย shared-secret จะถือเป็นการเข้าถึงแบบผู้ปฏิบัติการเต็มรูปแบบสำหรับพื้นผิวผู้ดูแลนี้

การแก้ไขปัญหา

404 Not Found

: Plugin ถูกปิดใช้งาน, Gateway ยังไม่ได้รีสตาร์ทหลังเปิดใช้งาน หรือคำขอถูกส่งไปยังโปรเซส Gateway อื่น

401 Unauthorized

: คำขอไม่ผ่านการยืนยันตัวตน HTTP ของ Gateway ตรวจสอบ bearer token หรือส่วนหัวตัวตนของ trusted-proxy

400 INVALID_REQUEST

: เนื้อหาคำขอไม่ใช่ JSON ที่ถูกต้อง, ฟิลด์ method หายไป หรือเมธอดไม่ได้อยู่ใน allowlist ของ Plugin

503 UNAVAILABLE

: ตัวจัดการเมธอด Gateway ไม่พร้อมใช้งาน ตรวจสอบบันทึก Gateway แล้วลองใหม่หลัง Gateway เริ่มต้นเสร็จ

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

• Scope ผู้ปฏิบัติการ
• ความปลอดภัยของ Gateway
• การเข้าถึงระยะไกล
• Manifest ของ Plugin
• Subpath ของ SDK