การผสานรวม 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 จะถูกตัดช่องว่างหัวท้าย ต้องมีอักขระที่ไม่ใช่ช่องว่าง และจำกัดความยาวไว้ที่ 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 ปิดการรับงาน root/เซสชัน/คำสั่งใหม่ หยุดรอบ 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
• ข้อมูลอ้างอิง RPC ของ Gateway
• คำสั่งเอเจนต์ CLI
• คำสั่งข้อความ CLI
• ลูปเอเจนต์
• รันไทม์เอเจนต์
• เซสชัน
• งานเบื้องหลัง
• เอเจนต์ ACP
• ภาพรวม Plugin SDK