ภาพรวม Plugin SDK

SDK ของ Plugin คือสัญญาแบบมีชนิดข้อมูลระหว่าง Plugin กับแกนหลัก หน้านี้เป็น เอกสารอ้างอิงสำหรับ สิ่งที่ควรนำเข้า และ สิ่งที่คุณสามารถลงทะเบียนได้

รูปแบบการนำเข้า

ให้นำเข้าจากพาธย่อยที่เฉพาะเจาะจงเสมอ:

แต่ละพาธย่อยเป็นโมดูลขนาดเล็กที่สมบูรณ์ในตัวเอง ซึ่งช่วยให้การเริ่มต้นทำงานรวดเร็วและ ป้องกันปัญหาการพึ่งพาแบบวนซ้ำ สำหรับตัวช่วยด้านจุดเริ่มต้น/การบิลด์ที่เฉพาะกับช่องทาง ให้เลือกใช้ openclaw/plugin-sdk/channel-core และเก็บ openclaw/plugin-sdk/core ไว้สำหรับ พื้นผิวรวมที่กว้างกว่าและตัวช่วยที่ใช้ร่วมกัน เช่น buildChannelConfigSchema

สำหรับการกำหนดค่าช่องทาง ให้เผยแพร่ JSON Schema ที่ช่องทางเป็นเจ้าของผ่าน openclaw.plugin.json#channelConfigs พาธย่อย plugin-sdk/channel-config-schema มีไว้สำหรับองค์ประกอบพื้นฐานของสคีมาที่ใช้ร่วมกันและตัวสร้างทั่วไป Plugin ที่รวมมากับ OpenClaw ใช้ plugin-sdk/bundled-channel-config-schema สำหรับสคีมาช่องทางแบบรวม ที่ยังคงรองรับอยู่ การส่งออกเพื่อความเข้ากันได้ที่เลิกแนะนำแล้วยังคงอยู่ที่ plugin-sdk/channel-config-schema-legacy โดยพาธย่อยของสคีมาแบบรวมทั้งสองแบบไม่ใช่ รูปแบบสำหรับ Plugin ใหม่

เอกสารอ้างอิงพาธย่อย

SDK ของ Plugin เปิดให้ใช้เป็นชุดพาธย่อยที่มีขอบเขตแคบ โดยจัดกลุ่มตามพื้นที่ (จุดเริ่มต้น ของ Plugin, ช่องทาง, ผู้ให้บริการ, การยืนยันตัวตน, รันไทม์, ความสามารถ, หน่วยความจำ และ ตัวช่วยที่สงวนไว้สำหรับ Plugin ที่รวมมาให้) สำหรับรายการทั้งหมดที่จัดกลุ่มและเชื่อมโยงแล้ว โปรดดู พาธย่อยของ SDK สำหรับ Plugin

รายการจุดเริ่มต้นของคอมไพเลอร์อยู่ใน scripts/lib/plugin-sdk-entrypoints.json ส่วนการส่งออกของแพ็กเกจสร้างขึ้นจาก ชุดสาธารณะหลังหักพาธย่อยสำหรับการทดสอบ/ภายในที่ใช้เฉพาะในรีโพซิทอรี ซึ่งระบุไว้ใน scripts/lib/plugin-sdk-private-local-only-subpaths.json เรียกใช้ pnpm plugin-sdk:surface เพื่อตรวจสอบจำนวนการส่งออกสาธารณะ พาธย่อยสาธารณะที่ เลิกแนะนำแล้วและมีอายุเก่าพอ รวมทั้งไม่ได้ถูกใช้โดยโค้ดโปรดักชันของส่วนขยายที่รวมมาให้ จะถูกติดตามใน scripts/lib/plugin-sdk-deprecated-public-subpaths.json ส่วน barrel การส่งออกซ้ำแบบกว้างที่เลิกแนะนำแล้วจะถูกติดตามใน scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json

API การลงทะเบียน

คอลแบ็ก register(api) จะได้รับออบเจ็กต์ OpenClawPluginApi ที่มี เมธอดต่อไปนี้:

การลงทะเบียนความสามารถ

ผู้ให้บริการเวิร์กเกอร์ต้องประกาศรหัสของตนใน contracts.workerProviders ด้วย แกนหลักจะบันทึกเจตนาที่คงทนก่อนเรียก provision(profile, operationId) ผู้ให้บริการต้องตรวจสอบการตั้งค่าก่อนจัดสรรทรัพยากรภายนอก และส่ง WorkerProviderError สำหรับการปฏิเสธโปรไฟล์อย่างถาวร provision ต้องรับช่วงสิทธิ์เช่าเดิมเมื่อรหัสการดำเนินการซ้ำ แกนหลักจะบันทึกการตั้งค่าโปรไฟล์ที่ตรวจสอบแล้วพร้อมสิทธิ์เช่า และส่งสแนปช็อตนั้นให้ destroy({ leaseId, profile }) ซึ่งต้องเรียกซ้ำได้โดยให้ผลเหมือนเดิม และ inspect({ leaseId, profile }) ซึ่งคืนค่า active, destroyed หรือ unknown วิธีนี้ช่วยให้ผู้ให้บริการกำหนดเส้นทางการเรียกวงจรชีวิตหลังจาก Gateway เริ่มใหม่หรือมีการลบโปรไฟล์ที่ตั้งชื่อไว้ ปลายทาง SSH ใช้ SecretRef สำหรับ keyRef ห้ามใส่เนื้อหาคีย์โดยตรง และต้องมี hostKey จากผลลัพธ์การจัดเตรียมที่เชื่อถือได้ในรูปแบบ algorithm base64 เท่านั้น โดยไม่มีชื่อโฮสต์หรือหมายเหตุ แกนหลักจะตรึง hostKey และไม่เชื่อถือคีย์จากการเชื่อมต่อครั้งแรก ผู้ให้บริการที่สร้าง keyRef แบบไดนามิกสามารถใช้ resolveSshIdentity({ leaseId, profile, keyRef }) ได้ เมื่อมีตัวแก้ไขนี้ ตัวแก้ไขดังกล่าวถือเป็นแหล่งอ้างอิงหลัก ส่วนผู้ให้บริการที่ไม่มีตัวแก้ไขนี้จะใช้ตัวแก้ไขข้อมูลลับทั่วไปที่กำหนดค่าไว้ ผู้ให้บริการที่มีสิทธิ์เช่าซึ่งต่ออายุได้สามารถใช้ renew(leaseId) เพิ่มเติมได้ inspect ต้องส่งข้อผิดพลาดเมื่อเกิดความล้มเหลวชั่วคราวหรือไม่สามารถระบุผลได้ และคืนค่า unknown เฉพาะเมื่อยืนยันได้ว่าไม่มีอยู่เท่านั้น แกนหลักจะทำเครื่องหมายเรคคอร์ดภายในเครื่องที่ยังทำงานอยู่ว่าไม่มีเจ้าของ หรือถือว่าการไม่มีอยู่หมายถึงการรื้อถอนเสร็จสมบูรณ์แล้วหลังจากมีคำขอทำลายที่บันทึกไว้

ผู้ให้บริการเวกเตอร์ฝังตัวที่ลงทะเบียนด้วย api.registerEmbeddingProvider(...) ต้อง ระบุไว้ใน contracts.embeddingProviders ของไฟล์ manifest ของ Plugin ด้วย นี่คือ พื้นผิวการฝังตัวแบบทั่วไปสำหรับการสร้างเวกเตอร์ที่นำกลับมาใช้ใหม่ได้ การค้นหาหน่วยความจำ สามารถใช้พื้นผิวผู้ให้บริการทั่วไปนี้ได้ จุดเชื่อมต่อรุ่นเก่า api.registerMemoryEmbeddingProvider(...) และ contracts.memoryEmbeddingProviders เป็นความเข้ากันได้ที่เลิกแนะนำแล้ว ระหว่างที่ ผู้ให้บริการเฉพาะหน่วยความจำเดิมกำลังย้ายระบบ

ผู้ให้บริการเฉพาะหน่วยความจำที่ยังคงเปิดเผย batchEmbed(...) ในรันไทม์ จะยังใช้ สัญญาการประมวลผลแบบกลุ่มต่อไฟล์ที่มีอยู่ เว้นแต่รันไทม์จะตั้งค่า sourceWideBatchEmbed: true ไว้อย่างชัดเจน การเลือกใช้นี้ช่วยให้โฮสต์หน่วยความจำ ส่งชิ้นข้อมูลจากไฟล์หน่วยความจำที่เปลี่ยนแปลงหลายไฟล์และแหล่งที่เปิดใช้งานหลายแหล่ง ในการเรียก batchEmbed(...) ครั้งเดียวได้ โดยไม่เกินขีดจำกัดขนาดกลุ่มของโฮสต์ อะแดปเตอร์แบบกลุ่มที่อัปโหลดไฟล์คำขอ JSONL ต้องแบ่งงานของผู้ให้บริการก่อนถึง ขีดจำกัดขนาดการอัปโหลดและขีดจำกัดจำนวนคำขอ ผู้ให้บริการต้องคืนค่าเวกเตอร์ฝังตัว หนึ่งรายการต่อชิ้นข้อมูลนำเข้า โดยเรียงลำดับเดียวกับ batch.chunks ให้ละเว้นแฟล็กนี้ เมื่อผู้ให้บริการคาดหวังกลุ่มเฉพาะภายในไฟล์ หรือไม่สามารถรักษาลำดับข้อมูลนำเข้า ในงานขนาดใหญ่ที่ครอบคลุมทั้งแหล่งข้อมูลได้

เครื่องมือและคำสั่ง

ใช้ defineToolPlugin สำหรับ Plugin ที่มีเฉพาะเครื่องมือแบบง่าย และมีชื่อเครื่องมือคงที่ ใช้ api.registerTool(...) โดยตรงสำหรับ Plugin แบบผสม หรือการลงทะเบียนเครื่องมือแบบไดนามิกเต็มรูปแบบ

คำสั่งของ Plugin สามารถตั้งค่า agentPromptGuidance ได้ เมื่อเอเจนต์ต้องการ คำแนะนำการกำหนดเส้นทางสั้น ๆ ที่คำสั่งเป็นเจ้าของ ให้ข้อความนั้นกล่าวถึงตัวคำสั่งเอง และอย่าเพิ่มนโยบายเฉพาะผู้ให้บริการหรือ Plugin ลงในตัวสร้างพรอมต์ของแกนหลัก

รายการคำแนะนำอาจเป็นสตริงแบบเดิม ซึ่งใช้กับพื้นผิวพรอมต์ทุกแบบ หรือ เป็นรายการแบบมีโครงสร้าง:

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

surfaces แบบมีโครงสร้างอาจประกอบด้วย openclaw_main, codex_app_server, cli_backend, acp_backend หรือ subagent โดย pi_main ยังคงเป็นนามแฝง ที่เลิกแนะนำแล้วสำหรับ openclaw_main ให้ละเว้น surfaces เมื่อตั้งใจให้คำแนะนำ ใช้กับทุกพื้นผิว อย่าส่งอาร์เรย์ surfaces ว่าง ระบบจะปฏิเสธเพื่อป้องกันไม่ให้ การสูญเสียขอบเขตโดยไม่ตั้งใจกลายเป็นข้อความพรอมต์ส่วนกลาง

คำสั่งสำหรับนักพัฒนาของเซิร์ฟเวอร์แอป Codex แบบเนทีฟมีข้อกำหนดเข้มงวดกว่า พื้นผิวพรอมต์อื่น มีเพียงคำแนะนำที่กำหนดขอบเขตเป็น codex_app_server อย่างชัดเจน เท่านั้นที่จะถูกเลื่อนไปยังช่องทางที่มีลำดับความสำคัญสูงกว่า คำแนะนำแบบสตริงเดิม และคำแนะนำแบบมีโครงสร้างที่ไม่ได้กำหนดขอบเขตจะยังคงใช้ได้กับพื้นผิวพรอมต์ ที่ไม่ใช่ Codex เพื่อความเข้ากันได้

คำสั่งโฮสต์ Node ทำงานบนโฮสต์ Node ที่เชื่อมต่อ ไม่ได้ทำงานภายในโปรเซส Gateway หากมี agentTool อยู่ Node จะเผยแพร่ตัวอธิบายหลังจากเชื่อมต่อ Gateway สำเร็จ โดย Gateway จะเปิดให้การทำงานของเอเจนต์ใช้งานได้เฉพาะขณะที่ Node นั้นเชื่อมต่ออยู่ และเฉพาะเมื่อ command ของตัวอธิบายอยู่ในพื้นผิวคำสั่ง ที่ได้รับอนุมัติของ Node เท่านั้น ตั้งค่า agentTool.defaultPlatforms เพื่อเพิ่ม คำสั่งที่ไม่เป็นอันตรายลงในรายการอนุญาตคำสั่งเริ่มต้นของ Node มิฉะนั้นต้องกำหนด gateway.nodes.allowCommands อย่างชัดเจนหรือนโยบายการเรียกใช้จาก Node agentTool.name ต้องปลอดภัยสำหรับผู้ให้บริการ: ขึ้นต้นด้วยตัวอักษร ใช้เฉพาะ ตัวอักษร ตัวเลข ขีดล่าง หรือขีดกลาง และมีความยาวไม่เกิน 64 อักขระ เครื่องมือ Node ที่มี MCP รองรับสามารถตั้งค่าข้อมูลเมตา agentTool.mcp เพื่อให้พื้นผิว แค็ตตาล็อกและการค้นหาเครื่องมือแสดงข้อมูลประจำตัวของเซิร์ฟเวอร์/เครื่องมือ MCP ระยะไกลได้ แต่การดำเนินการยังคงผ่านคำสั่ง Node ที่ประกาศไว้

โครงสร้างพื้นฐาน

ตัวสร้างส่วนเสริมพรอมป์หน่วยความจำจะได้รับบริบท agentId, agentSessionKey และ sandboxed ซึ่งเป็นทางเลือก การเรียก search และ get ของส่วนเสริมคลังข้อมูลหน่วยความจำจะได้รับบริบท agentId และ sandboxed ซึ่งเป็นทางเลือก Plugin ที่มีพื้นที่จัดเก็บซึ่งเอเจนต์เป็นเจ้าของ ควรแก้ไขตำแหน่งพื้นที่จัดเก็บนั้นสำหรับแต่ละการเรียก แทนการเก็บพาธส่วนกลาง เพียงพาธเดียวไว้ระหว่างการลงทะเบียน หากจำเป็นต้องมีรหัสเอเจนต์แต่ไม่มีให้ ในการดำเนินการแบบหลายเอเจนต์ ให้ปฏิเสธอย่างปลอดภัยแทนการเลือกเอเจนต์ ใดเอเจนต์หนึ่งโดยพลการ

ตัวจัดการแบบโต้ตอบของ Telegram สามารถส่งคืน { submitText } เพื่อส่งข้อความ ผ่านเส้นทางเอเจนต์ขาเข้าปกติของ Telegram หลังจากตัวจัดการทำงานสำเร็จ OpenClaw จะคงปุ่มเรียกกลับไว้เมื่อข้อความถูกข้ามโดยนโยบายขาเข้าหรือการประมวลผลล้มเหลว เพื่อให้ผู้ใช้ลองใหม่ได้หลังจากเงื่อนไขที่ขัดขวางเปลี่ยนไป ฟิลด์ผลลัพธ์นี้ใช้เฉพาะ Telegram ส่วนช่องทางอื่นจะคงสัญญาผลลัพธ์แบบโต้ตอบของตนเอง

ฮุกโฮสต์สำหรับ Plugin เวิร์กโฟลว์

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

ตัวอธิบาย surface: "tab" จะเพิ่มแท็บแถบด้านข้างลงใน UI ควบคุม ตัวอธิบายแท็บ ของ Plugin ที่ใช้งานอยู่จะถูกประกาศให้ไคลเอนต์แดชบอร์ดทราบในคำทักทายของ Gateway (controlUiTabs) ดังนั้นแท็บจะแสดงเฉพาะขณะที่เปิดใช้งาน Plugin อยู่ Plugin ที่รวมมากับระบบอาจจัดส่งมุมมองแดชบอร์ดระดับเฟิร์สคลาสสำหรับแท็บของตน ส่วน Plugin อื่นสามารถตั้งค่า path เป็นเส้นทาง HTTP ของ Plugin (ดู api.registerHttpRoute(...)) ซึ่งแดชบอร์ดจะแสดงในเฟรมแบบแซนด์บ็อกซ์ icon คือคำใบ้ชื่อไอคอนแดชบอร์ด group ใช้เลือกส่วนของแถบด้านข้าง (control หรือ agent) order ใช้เรียงลำดับระหว่างแท็บของ Plugin และ requiredScopes จะซ่อนแท็บจากการเชื่อมต่อที่ไม่มีขอบเขตสิทธิ์ของผู้ปฏิบัติงานเหล่านั้น:

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

ใช้เนมสเปซแบบจัดกลุ่มสำหรับโค้ด Plugin ใหม่:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

เมธอดแบบแบนที่เทียบเท่ายังคงพร้อมใช้งานในฐานะนามแฝงเพื่อความเข้ากันได้ ที่เลิกแนะนำแล้วสำหรับ Plugin ที่มีอยู่ อย่าเพิ่มโค้ด Plugin ใหม่ที่เรียก api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn หรือ api.unscheduleSessionTurnsByTag โดยตรง

scheduleSessionTurn(...) เป็นเครื่องมืออำนวยความสะดวกระดับเซสชันที่ครอบ ตัวกำหนดเวลา Cron ของ Gateway โดย Cron เป็นเจ้าของการกำหนดเวลาและสร้าง ระเบียนงานเบื้องหลังเมื่อรอบทำงาน ส่วน Plugin SDK จำกัดเฉพาะเซสชันเป้าหมาย การตั้งชื่อที่ Plugin เป็นเจ้าของ และการทำความสะอาด ใช้ api.runtime.tasks.managedFlows ภายในรอบตามกำหนดเวลาเมื่อตัวงานต้องการ สถานะ Task Flow หลายขั้นตอนที่คงทน

สัญญาเหล่านี้จงใจแยกอำนาจออกจากกัน:

• Plugin ภายนอกสามารถเป็นเจ้าของส่วนขยายเซสชัน ตัวอธิบาย UI คำสั่ง ข้อมูลเมตา เครื่องมือ การแทรกในรอบถัดไป และฮุกทั่วไป
• นโยบายเครื่องมือที่เชื่อถือได้ทำงานก่อนฮุก before_tool_call ทั่วไป และได้รับ ความเชื่อถือจากโฮสต์ นโยบายที่รวมมากับระบบจะทำงานก่อน ส่วนนโยบายของ Plugin ที่ติดตั้งต้องเปิดใช้งานอย่างชัดเจนพร้อมกับรหัสภายในของนโยบายเหล่านั้นใน contracts.trustedToolPolicies และจะทำงานถัดไปตามลำดับการโหลด Plugin รหัสนโยบายถูกจำกัดขอบเขตไว้ที่ Plugin ที่ลงทะเบียน
• การเป็นเจ้าของคำสั่งที่สงวนไว้จำกัดเฉพาะ Plugin ที่รวมมากับระบบ Plugin ภายนอก ควรใช้ชื่อคำสั่งหรือนามแฝงของตนเอง
• allowPromptInjection=false ปิดใช้งานฮุกที่เปลี่ยนแปลงพรอมป์ รวมถึง agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, ฟิลด์พรอมป์จาก before_agent_start แบบเดิม และ enqueueNextTurnInjection

ตัวอย่างผู้ใช้งานที่ไม่ใช่โหมดแผน:

การลงทะเบียนการค้นหา Gateway

api.registerGatewayDiscoveryService(...) ช่วยให้ Plugin ประกาศ Gateway ที่กำลังทำงานอยู่ผ่านการขนส่งเพื่อการค้นหาภายในเครื่อง เช่น mDNS/Bonjour OpenClaw จะเรียกใช้บริการระหว่างการเริ่มต้น Gateway เมื่อเปิดใช้งานการค้นหา ภายในเครื่อง ส่งพอร์ต Gateway ปัจจุบันและข้อมูลคำใบ้ TXT ที่ไม่เป็นความลับ และเรียกตัวจัดการ stop ที่ส่งคืนมาระหว่างการปิด Gateway

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

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

เมทาดาทาการลงทะเบียน CLI

api.registerCli(registrar, opts?) รองรับเมทาดาทาคำสั่งสองประเภท:

• commands: ชื่อคำสั่งที่ชัดเจนซึ่งรีจิสตราร์เป็นเจ้าของ
• descriptors: ตัวอธิบายคำสั่งขณะวิเคราะห์สำหรับความช่วยเหลือของ CLI, การกำหนดเส้นทาง และการลงทะเบียน CLI ของ Plugin แบบโหลดเมื่อจำเป็น
• parentPath: เส้นทางคำสั่งแม่แบบไม่บังคับสำหรับกลุ่มคำสั่งซ้อน เช่น ["nodes"]

สำหรับฟีเจอร์ Node ที่จับคู่แล้ว ควรใช้ api.registerNodeCliFeature(registrar, opts?) ซึ่งเป็นตัวห่อขนาดเล็กรอบ api.registerCli(..., { parentPath: ["nodes"] }) และทำให้คำสั่งอย่าง openclaw nodes canvas เป็นฟีเจอร์ Node ที่ Plugin เป็นเจ้าของอย่างชัดเจน

หากต้องการให้คำสั่งของ Plugin ยังคงโหลดเมื่อจำเป็นในเส้นทาง CLI รากมาตรฐาน ให้ระบุ descriptors ที่ครอบคลุมรากคำสั่งระดับบนสุดทุกคำสั่งที่รีจิสตราร์นั้น เปิดเผย

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

คำสั่งซ้อนจะได้รับคำสั่งแม่ที่แปลงค่าแล้วในรูป program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

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

การลงทะเบียนแบ็กเอนด์ CLI

api.registerCliBackend(...) ช่วยให้ Plugin เป็นเจ้าของการกำหนดค่าเริ่มต้น สำหรับแบ็กเอนด์ CLI ของ AI ภายในเครื่อง เช่น claude-cli หรือ my-cli

• id ของแบ็กเอนด์จะกลายเป็นคำนำหน้าผู้ให้บริการในการอ้างอิงโมเดล เช่น my-cli/gpt-5
• config ของแบ็กเอนด์ใช้โครงสร้างเดียวกับ agents.defaults.cliBackends.<id>
• การกำหนดค่าของผู้ใช้ยังคงมีลำดับความสำคัญสูงกว่า OpenClaw จะผสาน agents.defaults.cliBackends.<id> ทับค่าเริ่มต้นของ Plugin ก่อนเรียกใช้ CLI
• ใช้ normalizeConfig เมื่อแบ็กเอนด์ต้องเขียนรูปแบบใหม่เพื่อความเข้ากันได้ หลังการผสาน (เช่น การปรับรูปแบบแฟล็กเก่าให้เป็นมาตรฐาน)
• ใช้ resolveExecutionArgs สำหรับการเขียน argv ใหม่ที่จำกัดขอบเขตตามคำขอ และเป็นส่วนหนึ่งของรูปแบบภาษา CLI เช่น การแมประดับการคิดของ OpenClaw ไปเป็นแฟล็กระดับความพยายามแบบเนทีฟ Hook จะได้รับ ctx.executionMode; ใช้ "side-question" เพื่อเพิ่มแฟล็กการแยกแบบเนทีฟของแบ็กเอนด์สำหรับ การเรียก /btw ชั่วคราว หากแฟล็กเหล่านั้นปิดใช้งานเครื่องมือเนทีฟได้ อย่างเชื่อถือได้สำหรับ CLI ที่ปกติเปิดเครื่องมือตลอดเวลา ให้ประกาศ sideQuestionToolMode: "disabled" ด้วย
• แบ็กเอนด์ที่สามารถปิดใช้งานเครื่องมือเนทีฟทั้งหมดสำหรับการเรียกใช้เฉพาะครั้ง อาจประกาศ nativeToolMode: "selectable" การเรียกแบบจำกัดจะส่งทูเพิล ctx.toolAvailability.native ที่ว่าง พร้อมรายการอนุญาต MCP ที่แยกจากโฮสต์ อย่างเคร่งครัด; resolveExecutionArgs ต้องบังคับใช้ทั้งสองอย่างกับ argv สุดท้ายสำหรับการเรียกใหม่หรือเรียกต่อ OpenClaw จะปฏิเสธโดยค่าเริ่มต้น หากแบ็กเอนด์ไม่สามารถดำเนินการดังกล่าวได้

สำหรับคู่มือการสร้างแบบครบวงจร โปรดดู Plugin แบ็กเอนด์ CLI

ช่องเฉพาะ

อะแดปเตอร์การฝังหน่วยความจำที่เลิกใช้แล้ว

• registerMemoryCapability เป็น API แบบเฉพาะสำหรับ Plugin หน่วยความจำที่แนะนำ
• registerMemoryCapability ยังอาจเปิดเผย publicArtifacts.listArtifacts(...) เพื่อให้ Plugin คู่หูใช้สิ่งประดิษฐ์หน่วยความจำที่ส่งออกผ่าน openclaw/plugin-sdk/memory-host-core แทนการเข้าถึงโครงสร้างภายในของ Plugin หน่วยความจำเฉพาะโดยตรง
• registerMemoryPromptSection, registerMemoryFlushPlan และ registerMemoryRuntime เป็น API แบบเฉพาะสำหรับ Plugin หน่วยความจำ ที่รองรับความเข้ากันได้แบบเดิม
• MemoryFlushPlan.model สามารถปักหมุดรอบการล้างไว้กับการอ้างอิง provider/model ที่แน่นอน เช่น ollama/qwen3:8b โดยไม่สืบทอดสายโซ่ สำรองที่ใช้งานอยู่
• registerMemoryEmbeddingProvider เลิกใช้แล้ว ผู้ให้บริการการฝังรายใหม่ ควรใช้ api.registerEmbeddingProvider(...) และ contracts.embeddingProviders
• ผู้ให้บริการเฉพาะหน่วยความจำที่มีอยู่ยังคงทำงานต่อไปในช่วงการย้ายระบบ แต่การตรวจสอบ Plugin จะรายงานสิ่งนี้เป็นภาระด้านความเข้ากันได้สำหรับ Plugin ที่ไม่ได้รวมมาในระบบ

เหตุการณ์และวงจรชีวิต

ดูตัวอย่าง ชื่อ Hook ที่ใช้ทั่วไป และความหมายของตัวควบคุมได้ที่ Hooks ของ Plugin

ความหมายของการตัดสินใจใน Hook

before_install เป็น Hook วงจรชีวิตรันไทม์ของ Plugin ไม่ใช่พื้นผิวนโยบาย การติดตั้งของผู้ดำเนินการ ใช้ security.installPolicy เมื่อการตัดสินใจ อนุญาต/บล็อกต้องครอบคลุมเส้นทางการติดตั้งหรืออัปเดตผ่าน CLI และ Gateway

• before_tool_call: การคืนค่า { block: true } ถือเป็นจุดสิ้นสุด เมื่อแฮนด์เลอร์ใดตั้งค่านี้แล้ว ระบบจะข้ามแฮนด์เลอร์ที่มีลำดับความสำคัญต่ำกว่า
• before_tool_call: การคืนค่า { block: false } ถือว่าไม่มีการตัดสินใจ (เหมือนกับการละเว้น block) ไม่ใช่การเขียนทับ
• before_install: การคืนค่า { block: true } ถือเป็นจุดสิ้นสุด เมื่อแฮนด์เลอร์ใดตั้งค่านี้แล้ว ระบบจะข้ามแฮนด์เลอร์ที่มีลำดับความสำคัญต่ำกว่า
• before_install: การคืนค่า { block: false } ถือว่าไม่มีการตัดสินใจ (เหมือนกับการละเว้น block) ไม่ใช่การเขียนทับ
• reply_dispatch: การคืนค่า { handled: true, ... } ถือเป็นจุดสิ้นสุด เมื่อแฮนด์เลอร์ใดรับช่วงการส่งต่อแล้ว ระบบจะข้ามแฮนด์เลอร์ที่มีลำดับความสำคัญต่ำกว่าและเส้นทางการส่งต่อไปยังโมเดลเริ่มต้น
• message_sending: การคืนค่า { cancel: true } ถือเป็นจุดสิ้นสุด เมื่อแฮนด์เลอร์ใดตั้งค่านี้แล้ว ระบบจะข้ามแฮนด์เลอร์ที่มีลำดับความสำคัญต่ำกว่า
• message_sending: การคืนค่า { cancel: false } ถือว่าไม่มีการตัดสินใจ (เหมือนกับการละเว้น cancel) ไม่ใช่การเขียนทับ
• message_received: ใช้ฟิลด์ threadId แบบมีชนิดข้อมูลเมื่อคุณต้องกำหนดเส้นทางเธรด/หัวข้อขาเข้า เก็บ metadata ไว้สำหรับข้อมูลเพิ่มเติมเฉพาะช่องทาง
• message_sending: ใช้ฟิลด์กำหนดเส้นทาง replyToId / threadId แบบมีชนิดข้อมูลก่อนย้อนกลับไปใช้ metadata เฉพาะช่องทาง
• gateway_start: ใช้ ctx.config, ctx.workspaceDir และ ctx.getCron?.() สำหรับสถานะเริ่มต้นที่ Gateway เป็นเจ้าของ แทนการพึ่งพาฮุกภายใน gateway:startup ณ จุดนี้ Cron อาจยังโหลดไม่เสร็จ
• cron_reconciled: สร้างการฉายภาพ Cron ภายนอกแบบสมบูรณ์ขึ้นใหม่หลังเริ่มต้นหรือโหลดตัวกำหนดตารางเวลาใหม่ โดยมี reason และสถานะ enabled ที่มีผล รวมถึง enabled: false ขณะที่ ctx.getCron?.() จะคืนค่าตัวกำหนดตารางเวลาที่ผ่านการกระทบยอดอย่างถูกต้อง ส่ง ctx.abortSignal เข้าไปในงานฉายภาพแบบคงทน โดยสัญญาณจะยกเลิกเมื่อสแนปช็อตตัวกำหนดตารางเวลานั้นถูกแทนที่หรือ Gateway ปิด
• cron_changed: เฝ้าสังเกตการเปลี่ยนแปลงวงจรชีวิต Cron ที่ Gateway เป็นเจ้าของ เหตุการณ์ scheduled และ removed เป็นคำใบ้การกระทบยอดหลังคอมมิต ไม่ใช่บันทึกเดลตาตามลำดับ event.nextRunAtMs ของเหตุการณ์ scheduled จะไม่มีอยู่เมื่องานไม่มีเวลาปลุกครั้งถัดไป ส่วนเหตุการณ์ removed ยังคงมีสแนปช็อตของงานที่ถูกลบ

ตัวกำหนดตารางเวลาปลุกภายนอกควรหน่วงหรือรวมเหตุการณ์ cron_changed จากนั้นอ่านมุมมองแบบคงทนทั้งหมดอีกครั้งจากตัวกำหนดตารางเวลาที่ cron_reconciled บันทึกไว้ล่าสุด อย่านำตัวกำหนดตารางเวลาจากบริบท cron_changed มาใช้: คำใบ้ที่แยกออกมาจากตัวกำหนดตารางเวลารุ่นเก่าอาจทับซ้อนกับการโหลดใหม่ในภายหลัง

ใช้ cron_reconciled เป็นตัวกระตุ้นสแนปช็อตแบบสมบูรณ์สำหรับสถานะแบบคงทนที่โหลดเมื่อ Gateway เริ่มต้นหรือเมื่อตัวกำหนดตารางเวลาถูกแทนที่ เหตุการณ์นี้จะไม่ถูกเล่นซ้ำสำหรับการ โหลดใหม่แบบร้อนเฉพาะ Plugin แฮนด์เลอร์การสังเกตทำงานแบบขนาน และการส่งแบบ เริ่มแล้วไม่รอผลอาจทับซ้อนกันได้ ดังนั้นผู้ใช้งานต้องไม่พึ่งพาลำดับการเสร็จสิ้นของเหตุการณ์ ให้ OpenClaw เป็นแหล่งข้อมูลจริงสำหรับการตรวจสอบกำหนดเวลาและการดำเนินการ

สำหรับอะแดปเตอร์ที่ทำงานได้ครั้งละหนึ่งรายการ พร้อมการแทนที่แบบคงทน การลองใหม่/หน่วงเวลาแบบถอยหลัง และการ ปิดระบบอย่างเรียบร้อย โปรดดู การฉายภาพ Cron ภายนอกอย่างปลอดภัย

ฟิลด์อ็อบเจ็กต์ API

ข้อตกลงโมดูลภายใน

ภายใน Plugin ของคุณ ให้ใช้ไฟล์รวมการส่งออกภายในเครื่องสำหรับการนำเข้าภายใน:

my-plugin/  api.ts            # การส่งออกสาธารณะสำหรับผู้ใช้ภายนอก  runtime-api.ts    # การส่งออกรันไทม์สำหรับใช้ภายในเท่านั้น  index.ts          # จุดเริ่มต้นของ Plugin  setup-entry.ts    # จุดเริ่มต้นสำหรับการตั้งค่าเท่านั้นแบบเบา (ไม่บังคับ)

พื้นผิวสาธารณะของ Plugin แบบรวมที่โหลดผ่านฟาซาด (api.ts, runtime-api.ts, index.ts, setup-entry.ts และไฟล์รายการสาธารณะที่คล้ายกัน) จะเลือกใช้ สแนปช็อตการกำหนดค่ารันไทม์ที่ทำงานอยู่เมื่อ OpenClaw กำลังทำงานอยู่ หากยังไม่มีสแนปช็อต รันไทม์ ระบบจะย้อนกลับไปใช้ไฟล์การกำหนดค่าบนดิสก์ที่แก้ไขแล้ว ควรโหลดฟาซาดของ Plugin แบบรวมที่แพ็กเกจแล้วผ่านตัวโหลดฟาซาด Plugin ของ OpenClaw การนำเข้าโดยตรงจาก dist/extensions/... จะข้ามการตรวจสอบแมนิเฟสต์ และไซด์คาร์รันไทม์ที่การติดตั้งแบบแพ็กเกจใช้กับโค้ดที่ Plugin เป็นเจ้าของ

Plugin ผู้ให้บริการสามารถเปิดเผยไฟล์รวมสัญญาภายใน Plugin แบบจำกัดได้ เมื่อ ตัวช่วยนั้นเจาะจงกับผู้ให้บริการโดยตั้งใจและยังไม่เหมาะที่จะอยู่ในพาธย่อย SDK ทั่วไป ตัวอย่างแบบรวม:

• Anthropic: จุดเชื่อมต่อสาธารณะ api.ts / contract-api.ts สำหรับตัวช่วยสตรีม ส่วนหัวเบต้าของ Claude และ service_tier
• @openclaw/openai-provider: api.ts ส่งออกตัวสร้างผู้ให้บริการ ตัวช่วยโมเดลเริ่มต้น และตัวสร้างผู้ให้บริการแบบเรียลไทม์
• @openclaw/openrouter-provider: api.ts ส่งออกตัวสร้างผู้ให้บริการ พร้อมตัวช่วยเริ่มต้นใช้งาน/การกำหนดค่า

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