การผสานรวม Gateway สำหรับแอปภายนอก

แอปภายนอกสื่อสารกับ OpenClaw ผ่านโปรโตคอล Gateway ซึ่งประกอบด้วยการรับส่งข้อมูลผ่าน WebSocket และเมธอด RPC ใช้โปรโตคอลนี้เมื่อสคริปต์ แดชบอร์ด งาน CI ส่วนขยาย IDE หรือกระบวนการอื่นต้องการเริ่มการรันเอเจนต์ สตรีมเหตุการณ์ รอ ผลลัพธ์ ยกเลิกงาน หรือตรวจสอบทรัพยากรของ Gateway

สิ่งที่พร้อมใช้งานในปัจจุบัน

แนวทางที่แนะนำ

1. เรียกใช้หรือค้นหา Gateway
2. เชื่อมต่อผ่าน โปรโตคอล Gateway
3. เรียกเมธอด RPC ที่บันทึกไว้ใน เอกสารอ้างอิง RPC ของ Gateway
4. ตรึงเวอร์ชัน OpenClaw ที่ใช้ทดสอบ
5. ตรวจสอบเอกสารอ้างอิง RPC อีกครั้งเมื่ออัปเกรด OpenClaw

สำหรับการรันเอเจนต์ ให้เริ่มด้วย RPC agent และใช้ร่วมกับ agent.wait เพื่อรับ ผลลัพธ์สุดท้าย สำหรับสถานะการสนทนาที่คงทน ให้ใช้เมธอด sessions.* สำหรับการผสานรวม UI ให้สมัครรับเหตุการณ์ของ Gateway และเรนเดอร์เฉพาะตระกูลเหตุการณ์ ที่แอปของคุณเข้าใจ

การระงับโฮสต์แบบประสานงาน

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

1. หยุดรับทราฟฟิกขาเข้าภายนอกที่ควบคุมโดยโฮสต์
2. เรียก gateway.suspend.prepare ด้วย requestId ที่เสถียรและไม่ซ้ำกัน
3. หากการตอบกลับเป็น busy ให้กระบวนการทำงานต่อและลองใหม่ภายหลัง
4. หากเป็น ready ให้บันทึก suspensionId ที่ส่งคืน แล้วแช่แข็งหรือสร้างสแนปช็อต กระบวนการก่อน expiresAtMs
5. หลังเลิกแช่แข็ง หรือหากยกเลิกการระงับ ให้เรียก gateway.suspend.resume ด้วย suspensionId นั้นผ่าน WebSocket ที่มีอยู่หรือพาธควบคุม Admin HTTP

Gateway ที่เตรียมพร้อมแล้วจะปฏิเสธการจับมือ WebSocket ใหม่ ตัวควบคุม WebSocket ต้องรักษาการเชื่อมต่อที่ผ่านการยืนยันตัวตนไว้ตลอดการดำเนินการของโฮสต์ หาก ไม่สามารถรับประกันได้ ให้เปิดใช้และใช้งาน Plugin Admin HTTP RPC ก่อนเตรียมพร้อม หาก พาธควบคุมขาดหาย ให้รอให้สัญญาเช่าสองนาทีหมดอายุก่อน เชื่อมต่อใหม่ เมื่อหมดอายุ ระบบจะเปิดรับการเชื่อมต่ออีกครั้งโดยอัตโนมัติ

สัญญา RPC มีดังนี้:

• gateway.suspend.prepare — operator.admin; พารามิเตอร์ { "requestId": "stable-host-operation-id" }
• gateway.suspend.status — operator.read; พารามิเตอร์ { "suspensionId": "id-from-prepare" }
• gateway.suspend.resume — operator.admin; พารามิเตอร์ { "suspensionId": "id-from-prepare" }

ระบบจะตัดช่องว่างรอบ ID โดย ID ต้องมีอักขระที่ไม่ใช่ช่องว่างและมีความยาวไม่เกิน 128 อักขระ ผลลัพธ์การเตรียมพร้อมที่ไม่ว่างมี status: "busy", reason, retryAfterMs, activeCount และ blockers ผลลัพธ์ที่พร้อมมีรูปแบบดังนี้:

{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

สถานะจะส่งคืน {"status":"running"} หรือผลลัพธ์พร้อมที่มี expiresAtMs การดำเนินการต่อจะส่งคืน {"ok":true,"status":"running","resumed":true}; การทำซ้ำ หลังจากดำเนินการต่อสำเร็จจะส่งคืน resumed: false

ID คำขอที่แข่งขันกันหรือความล้มเหลวชั่วคราวในการดำเนินการต่อของตัวจัดกำหนดการจะส่งคืน UNAVAILABLE ที่ลองใหม่ได้พร้อม retryAfterMs ระหว่างการกู้คืนตัวจัดกำหนดการ การเตรียมพร้อม สถานะ และการดำเนินการต่อล้วนส่งคืนข้อผิดพลาดดังกล่าว Gateway จะยังไม่พร้อมและ ปิดกั้นเมื่อเกิดข้อผิดพลาด และโฮสต์ต้องไม่แช่แข็งหรือสร้างสแนปช็อต OpenClaw จะลองกู้คืน ตัวจัดกำหนดการโดยอัตโนมัติและเปิดรับการเชื่อมต่ออีกครั้งเมื่อกู้คืนสำเร็จเท่านั้น ID การดำเนินการต่อที่ไม่ตรงกันจะส่งคืน INVALID_REQUEST การเตรียมพร้อมใช้ โควตาการเขียนของระนาบควบคุม Gateway ร่วมกันที่สามครั้งต่อนาที โปรดปฏิบัติตาม ระยะเวลารอก่อนลองใหม่ที่ส่งคืน ไคลเอนต์ WebSocket จะแบ่งบักเก็ตตามอุปกรณ์และ IP ตัวควบคุม Admin HTTP จะแบ่งบักเก็ตตาม IP ไคลเอนต์ที่จำแนกแล้ว ดังนั้นตัวควบคุมที่อยู่หลังพร็อกซีเดียวกัน อาจใช้โควตาร่วมกัน

การเตรียมพร้อมทำได้เพียงปฏิเสธงาน: OpenClaw ปิดการรับงานใหม่ระดับรูท/เซสชัน/คำสั่ง หยุดรอบ cron อัตโนมัติชั่วคราว และตรวจสอบงานแบบซิงโครนัส หากมีสิ่งใด กำลังทำงาน ระบบจะดำเนินตัวจัดกำหนดการต่อและเปิดรับงานอีกครั้งก่อนส่งคืน busy; ระบบจะไม่ขัดจังหวะหรือรอให้งานนั้นเสร็จ สัญญาเช่าที่พร้อมมีอายุสอง นาที การเรียก prepare ซ้ำด้วย requestId เดิมจะต่ออายุสัญญาเช่า เมื่อหมดอายุ ระบบจะดำเนิน ตัวจัดกำหนดการต่อก่อนเปิดรับงานอีกครั้ง การส่งสัญญาณรีสตาร์ตที่ถึงกำหนดระหว่างสัญญาเช่าที่พร้อมจะรอจนกว่าสัญญาเช่าดำเนินการต่อ ส่วนการรีสตาร์ตที่กำลังดำเนินอยู่จะทำให้การเตรียมพร้อมส่งคืน busy

ขณะพร้อม /healthz ยังคงทำงานและ /readyz ส่งคืน 503 การตอบกลับ ความพร้อมภายในเครื่องหรือที่ผ่านการยืนยันตัวตนจะมี gateway-draining; โพรบระยะไกล ที่ไม่ผ่านการยืนยันตัวตนจะได้รับเฉพาะ { "ready": false } โพรบสุขภาพ HTTP เมธอดระงับบนการเชื่อมต่อ WebSocket ที่มีอยู่ และเส้นทาง Admin HTTP RPC ที่เปิดใช้อยู่แล้วยังคงพร้อมใช้งาน RPC อื่นจะส่งคืน UNAVAILABLE ที่ลองใหม่ได้ เส้นทาง HTTP ในตัวสำหรับงานผู้ใช้และเส้นทาง HTTP ทั่วไปของ Plugin รวมถึง API ที่เข้ากันได้กับ OpenAI การดำเนินการเครื่องมือ/เซสชัน การเฝ้าดู Node และ ฮุกที่กำหนดค่าไว้ จะส่งคืน 503 พร้อม error.code: "gateway_unavailable" การอัปเกรด WebSocket ใหม่ที่ Plugin เป็นเจ้าของจะส่งคืน 503 เช่นกัน ซึ่งครอบคลุม ความเป็นเจ้าของการอัปเกรด ไม่ใช่งานที่ดำเนินการภายหลังผ่านซ็อกเก็ต Plugin ที่สร้างการเชื่อมต่อแล้ว

การจับมือนี้ไม่คงข้อความขาเข้า ไม่หยุดการรับส่งของช่องทางบุคคลที่สาม และไม่ควบคุมแพลตฟอร์มโฮสติ้ง โฮสต์ต้องปิดกั้นทราฟฟิกขาเข้าของตน ก่อนเตรียมพร้อม และยังคงรับผิดชอบการปลุก การสร้างสแนปช็อต/การแช่แข็ง และ การหยุด activeCount คือจำนวนรวมของงานที่ติดตาม ส่วน blockers มีจำนวนหมวดหมู่ที่ไม่เป็นศูนย์และรายละเอียดงานแบบจำกัด นี่ไม่ใช่ แนวกั้นสำหรับการทำให้กระบวนการทั้งหมดสงบนิ่ง ตัวขัดขวาง background-exec เป็นข้อมูลรวม เท่านั้น ข้อความคำสั่ง ID กระบวนการ เอาต์พุต และตัวระบุเซสชันหรือขอบเขตจะไม่ ส่งผ่านโปรโตคอล สุขภาพของช่องทาง การบำรุงรักษา การรีเฟรชแคช เซสชัน WebSocket ของ Plugin ที่สร้างการเชื่อมต่อแล้ว และงานเบื้องหลังที่ Plugin เป็นเจ้าของซึ่งไม่ได้ลงทะเบียน อาจยังทำงานอยู่ แพลตฟอร์มโฮสติ้งต้องแช่แข็งหรือสร้างสแนปช็อตผังกระบวนการทั้งหมดและ ระบบไฟล์อย่างสอดคล้องกัน สัญญาฉบับแรกนี้ไม่สามารถพิสูจน์ได้ว่างานที่ไม่ได้ลงทะเบียน อยู่นิ่ง

โค้ดแอปเทียบกับโค้ด Plugin

ใช้ Gateway RPC เมื่อโค้ดอยู่ภายนอก OpenClaw:

• สคริปต์ Node ที่เริ่มหรือสังเกตการรันเอเจนต์
• งาน CI ที่เรียก Gateway
• แดชบอร์ดและแผงผู้ดูแลระบบ
• ส่วนขยาย IDE
• บริดจ์ภายนอกที่ไม่จำเป็นต้องเป็น Plugin ช่องทาง
• การทดสอบการผสานรวมที่ใช้การรับส่งข้อมูล Gateway จำลองหรือจริง

ใช้ Plugin SDK เมื่อโค้ดทำงานภายใน OpenClaw:

• Plugin ผู้ให้บริการ
• Plugin ช่องทาง
• ฮุกเครื่องมือหรือวงจรชีวิต
• Plugin ชุดควบคุมเอเจนต์
• ตัวช่วยรันไทม์ที่เชื่อถือได้

แอปภายนอกไม่ควรนำเข้า openclaw/plugin-sdk/*; พาธย่อยเหล่านั้นมีไว้สำหรับ Plugin ที่ OpenClaw โหลด

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

• การสร้างไคลเอนต์ Gateway
• การฝัง OpenClaw
• โปรโตคอล Gateway
• เอกสารอ้างอิง RPC ของ Gateway
• คำสั่งเอเจนต์ CLI
• คำสั่งข้อความ CLI
• ลูปเอเจนต์
• รันไทม์เอเจนต์
• เซสชัน
• งานเบื้องหลัง
• เอเจนต์ ACP
• ภาพรวม Plugin SDK