การสร้างไคลเอนต์ Gateway

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

สำหรับรูปแบบเฟรม การจับมือ ข้อผิดพลาด และชุดเมธอดทั้งหมด โปรดอ่าน ข้อกำหนดโปรโตคอล Gateway

ติดตั้งแพ็กเกจ

npm install @openclaw/gateway-client @openclaw/gateway-protocol

• @openclaw/gateway-protocol มีสคีมา ตัวตรวจสอบความถูกต้องขณะรันไทม์ ชนิด TypeScript รีจิสทรีข้อมูลประจำตัวและ ความสามารถของไคลเอนต์ ตัวอ่านข้อผิดพลาดแบบมีโครงสร้าง และค่าคงที่เวอร์ชันโปรโตคอล tarball บน npm ยังมีสัญญาที่เครื่องอ่านได้ซึ่งสร้างขึ้นเป็น protocol.schema.json
• @openclaw/gateway-client เป็นการใช้งานการเชื่อมต่ออ้างอิง ให้นำเข้าจากรากของแพ็กเกจสำหรับไคลเอนต์ Node และ @openclaw/gateway-client/browser สำหรับโปรโตคอลที่ปลอดภัยสำหรับเบราว์เซอร์ ตัวช่วยการยืนยันตัวตนของอุปกรณ์ และตัวช่วยการเชื่อมต่อใหม่

จุดเข้า Node จัดการการขนส่ง WebSocket ของตนเอง โฮสต์เบราว์เซอร์จะจัดหาอะแดปเตอร์ WebSocket พร้อมพื้นที่จัดเก็บถาวรและคอลแบ็กการลงนามสำหรับข้อมูลประจำตัวของอุปกรณ์และ โทเค็นอุปกรณ์

เลือกขอบเขตและจับคู่อุปกรณ์

ไคลเอนต์แชตแบบโต้ตอบเต็มรูปแบบที่แสดงข้อความแจ้งการอนุมัติด้วยควรร้องขอ role: "operator" พร้อมขอบเขตเหล่านี้:

เพิ่ม operator.questions เฉพาะเมื่อไคลเอนต์จัดการคำถามแบบโต้ตอบ เพิ่ม operator.pairing เฉพาะเมื่อไคลเอนต์จัดการอุปกรณ์หรือ Node ที่จับคู่แล้ว และ เพิ่ม operator.admin เฉพาะสำหรับการดำเนินการด้านการดูแล เช่น config.patch ข้อมูลอ้างอิงขอบเขตผู้ปฏิบัติงาน กำหนดกฎทั้งหมดสำหรับเมธอดและช่วงเวลาการอนุมัติ

อย่าสร้าง bearer token แยกสำหรับแต่ละไคลเอนต์ด้วยการแก้ไข openclaw.json ด้วยตนเอง ให้กำหนดค่า การยืนยันตัวตนเริ่มต้นที่ใช้ร่วมกันของ Gateway ด้วย openclaw configure --section gateway หรือตัวเลือก openclaw onboard --gateway-auth ... จากนั้นให้การจับคู่ อุปกรณ์ออกโทเค็นของไคลเอนต์:

1. จัดเก็บข้อมูลประจำตัวอุปกรณ์ Ed25519 แบบถาวรในไคลเอนต์
2. รอ connect.challenge ลงนามเพย์โหลดอุปกรณ์ที่ผูกกับชาเลนจ์ และส่ง connect พร้อมบทบาทผู้ปฏิบัติงาน ขอบเขตที่ร้องขอ และโทเค็น Gateway หรือรหัสผ่านที่ใช้ร่วมกันสำหรับการยืนยันตัวตนเริ่มต้น
3. หาก Gateway ส่งคืนรายละเอียด PAIRING_REQUIRED แบบมีโครงสร้าง ให้แสดง ID คำขอ และหยุดชั่วคราวหรือลองใหม่ตาม error.details.recommendedNextStep
4. บนโฮสต์ Gateway ให้ตรวจสอบคำขอด้วย openclaw devices list จากนั้น อนุมัติคำขอปัจจุบันนั้นโดยตรงด้วย openclaw devices approve <requestId>
5. เชื่อมต่อใหม่และจัดเก็บ hello-ok.auth.deviceToken แบบถาวรพร้อมบทบาทและ ขอบเขตที่เจรจาแล้ว ใช้โทเค็นอุปกรณ์นั้นสำหรับการเชื่อมต่อในภายหลัง

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

ประกาศความสามารถของไคลเอนต์

connect.params.caps อธิบายลักษณะการทำงานทางเลือกที่ไคลเอนต์สามารถใช้ได้ แต่ ไม่ได้มอบสิทธิ์ ให้นำเข้าชื่อจาก GATEWAY_CLIENT_CAPS แทนการ เขียนลิเทอรัลสตริงซ้ำ:

 const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

รีจิสทรีปัจจุบันประกอบด้วย approvals, exec-approvals, inline-widgets, run-tool-bindings, session-scoped-events, plugin-approvals, task-suggestions, terminal-offset-seq, tool-events และ ui-commands ประกาศเฉพาะความสามารถที่ไคลเอนต์ใช้งานจริงเท่านั้น

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

กู้คืนสถานะหลังเชื่อมต่อใหม่

ให้ถือว่าทุกการเชื่อมต่อใหม่ที่สำเร็จเป็นการฉายภาพใหม่จากประวัติที่คงทนและ สถานะการรันในหน่วยความจำปัจจุบัน:

1. สร้าง sessions.subscribe และการสมัครรับ sessions.messages.subscribe ของเซสชันที่เลือกขึ้นใหม่
2. เรียก chat.history สำหรับ sessionKey ที่เลือก และแทนที่แถวที่จัดเก็บ ภายในเครื่องด้วยการฉายภาพ messages ที่ส่งคืน
3. หากมี inFlightRun ให้รับ runId, text ที่บัฟเฟอร์ไว้ และ plan ซึ่งเป็นทางเลือก ให้รับการรันแม้ว่า text จะว่างเปล่า
4. อ่าน sessionInfo.hasActiveRun และ sessionInfo.activeRunIds ให้ใช้การเป็นสมาชิก ใน activeRunIds ที่ตรงกันทุกประการเป็นหลัก เมื่อตัดสินว่าการรันที่เก็บไว้ยังคงเป็นเจ้าของ UI การสตรีมหรือไม่ ค่า hasActiveRun ที่เป็นจริงแต่ไม่มี ID ในรายการอาจแสดงถึง การฉายภาพรันไทม์อื่นที่กำลังทำงาน
5. กระทบยอดเหตุการณ์ agent ที่ตามมาโดยใช้ payload.runId และ payload.seq รักษาลำดับสูงสุดที่ยอมรับแยกกันสำหรับแต่ละการรัน ละเว้นลำดับที่เห็นแล้วหรือ ต่ำกว่า และถือว่าช่องว่างไปข้างหน้าเป็นเหตุผลให้โหลดประวัติจากแหล่งข้อมูลที่เชื่อถือได้ใหม่

เฟรมเหตุการณ์ชั้นนอกยังมี seq ซึ่งเป็นทางเลือกและใช้จัดลำดับเหตุการณ์บน การเชื่อมต่อ WebSocket ปัจจุบัน ค่านี้จะรีเซ็ตเมื่อมีการเชื่อมต่อใหม่ ส่วน seq ภายใน เพย์โหลดเหตุการณ์ agent จะถูกกำหนดแยกต่อการรัน และจัดลำดับวงจรชีวิต ผู้ช่วย แผน เครื่องมือ และเหตุการณ์สตรีมอื่นๆ ของการรันนั้น

ใช้ข้อมูลเมตาของประวัติและจุดยึดที่เสถียร

แถวที่ chat.history ส่งคืนสามารถมีซองข้อมูลเมตา __openclaw:

• id คือข้อมูลประจำตัวของรายการทรานสคริปต์ ใช้สำหรับคำขอประวัติแบบมีจุดยึด แต่ห้ามใช้เป็นคีย์แถวแสดงผลที่ไม่ซ้ำกัน
• seq คือลำดับระเบียนทรานสคริปต์ที่เป็นจำนวนบวก ระเบียนหนึ่งที่จัดเก็บไว้อาจฉายภาพ เป็นแถวแสดงผลมากกว่าหนึ่งแถว ดังนั้นให้เก็บแถวที่เกี่ยวข้องซึ่งมี id และลำดับเดียวกัน ไว้ด้วยกัน
• kind ระบุแถวสังเคราะห์ ขอบเขต Compaction ใช้ kind: "compaction" และอาจมี tokensBefore และ tokensAfter เมื่อ จุดตรวจที่ตรงกันบันทึกเมตริกเหล่านั้นไว้

แบ่งหน้าไปย้อนหลังด้วยค่า hasMore และ nextOffset ของการตอบกลับ ออฟเซ็ตตัวเลข อธิบายการฉายภาพทรานสคริปต์ปัจจุบัน ดังนั้นอย่าจัดเก็บเป็นบุ๊กมาร์กระยะยาว ข้ามการรีเซ็ตหรือ Compaction ให้จัดเก็บ __openclaw.id แทน หากต้องการคืนค่าบริเวณรอบแถวที่ทราบ ให้เรียก chat.history พร้อม messageId และ sessionId ที่ส่งแถวนั้นคืนมา Gateway สามารถแก้ไขจุดยึดนั้นจากประวัติที่เก็บถาวร หลังการรีเซ็ตได้ การตอบกลับแบบมีจุดยึดจะละเว้นข้อมูลเมตาการแบ่งหน้าแบบตัวเลขโดยตั้งใจ

สมัครรับข้อมูลแทนการสำรวจการใช้งานเป็นระยะ

โหลดแค็ตตาล็อกเริ่มต้นด้วย sessions.list จากนั้นเรียก sessions.subscribe หนึ่งครั้ง ต่อการเชื่อมต่อ ผสานเหตุการณ์ sessions.changed โดยใช้ sessionKey เพย์โหลดการเปลี่ยนแปลง ของเซสชันสามารถมี inputTokens, outputTokens, totalTokens, totalTokensFresh, contextTokens, estimatedCostUsd แบบสด การตั้งค่าการใช้งาน ของการตอบกลับ และสถานะการรันที่ทำงานอยู่

การแจ้งเตือนการเปลี่ยนแปลงบางอย่างเป็นเพียงสัญญาณว่าข้อมูลใช้ไม่ได้แล้ว หากเหตุการณ์ละเว้น ฟิลด์แถวที่มุมมองต้องใช้ ให้รีเฟรช sessions.list อย่าสำรวจ usage.cost หรือ sessions.usage เป็นระยะเพื่อทำให้รายการเซสชันสดเป็นปัจจุบัน ให้สงวนเมธอดเหล่านั้นไว้สำหรับ รายงานรวมโดยเรียกใช้เมื่อต้องการหรือรายงานโดยละเอียด

เติมข้อมูลย้อนหลังสำหรับการอนุมัติ exec

ไคลเอนต์ที่มี operator.approvals ควรติดตั้งตัวรับฟังเหตุการณ์ทันทีที่ hello-ok เสร็จสมบูรณ์ จากนั้นเรียก exec.approval.list เพื่อเติมคำขอที่ เกิดก่อนการเชื่อมต่อ กระทบยอดรายการและเหตุการณ์สด exec.approval.requested / exec.approval.resolved โดยใช้ ID การอนุมัติ เพื่อไม่ให้ การเปลี่ยนสถานะที่เกิดพร้อมกับคำขอรายการสูญหายหรือถูกกู้คืนอย่างไม่ถูกต้อง

ติดตามเวอร์ชันโปรโตคอล

เวอร์ชันการสื่อสารผ่านสายในปัจจุบันคือ 4 ไคลเอนต์ผู้ปฏิบัติงานทั่วไปและ WebChat ต้อง เจรจาเวอร์ชันปัจจุบันที่ตรงกันทุกประการด้วย minProtocol: 4 และ maxProtocol: 4 เฉพาะไคลเอนต์ Node ที่ยืนยันตัวตนแล้วและโพรบน้ำหนักเบาเท่านั้นที่มีช่วงการยอมรับ N-1 ซึ่งปัจจุบันคือโปรโตคอล 3 ถึง 4

การเปลี่ยนแปลงโปรโตคอลจะเป็นแบบเพิ่มเติมก่อน protocol.schema.json มีข้อมูลเมตา since ของรุ่นที่เผยแพร่และข้อมูลเมตาขอบเขตที่จำเป็นสำหรับเมธอดแกนหลัก แต่การเพิ่มเวอร์ชันการสื่อสารผ่านสายยังคงเป็นเหตุการณ์ที่ทำให้เกิดความไม่เข้ากันอย่างชัดเจนสำหรับไคลเอนต์ บุคคลที่สาม ให้ตรึงเวอร์ชันแพ็กเกจที่ทดสอบ อัปเกรดไคลเอนต์และ Gateway พร้อมกันเมื่อเวอร์ชัน การสื่อสารผ่านสายเปลี่ยนแปลง และตรวจสอบ บันทึกการเปลี่ยนแปลง OpenClaw ก่อนการอัปเกรดแต่ละครั้ง

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

• โปรโตคอล Gateway
• การฝัง OpenClaw
• ข้อมูลอ้างอิง RPC ของ Gateway
• การผสานรวม Gateway สำหรับแอปภายนอก