Plugin maintainer reference

ความเข้ากันได้ของ Plugin

OpenClaw ยังคงเชื่อมต่อสัญญา Plugin รุ่นเก่าผ่านอะแดปเตอร์ความเข้ากันได้ที่มีชื่อกำกับก่อนนำสัญญาเหล่านั้นออก วิธีนี้ช่วยปกป้อง Plugin ที่มาพร้อมระบบและ Plugin ภายนอกที่มีอยู่ ขณะที่สัญญาของ SDK, ไฟล์ manifest, การตั้งค่าเริ่มต้น, การกำหนดค่า และรันไทม์ของเอเจนต์มีการพัฒนา

รีจิสทรีความเข้ากันได้

สัญญาความเข้ากันได้ของ Plugin ได้รับการติดตามในรีจิสทรีแกนหลักที่ src/plugins/compat/registry.ts แต่ละระเบียนประกอบด้วย:

รหัสความเข้ากันได้ที่คงที่
สถานะ: active, deprecated, removal-pending หรือ removed
เจ้าของ: sdk, config, setup, channel, provider, plugin-execution, agent-runtime หรือ core
วันที่เริ่มใช้และวันที่เลิกใช้เมื่อเกี่ยวข้อง
แนวทางสำหรับสิ่งทดแทน
เอกสาร การวินิจฉัย และการทดสอบที่ครอบคลุมพฤติกรรมทั้งเก่าและใหม่

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

ความเข้ากันได้ของการซ่อมแซมและการย้ายข้อมูลโดยคำสั่ง doctor จะถูกติดตามแยกต่างหากที่ src/commands/doctor/shared/deprecation-compat.ts ระเบียนเหล่านั้นครอบคลุมรูปแบบการกำหนดค่าเก่า โครงสร้างบัญชีรายการการติดตั้ง และชิมสำหรับการซ่อมแซมที่อาจต้องคงให้ใช้งานได้หลังจากนำเส้นทางความเข้ากันได้ของรันไทม์ออกแล้ว

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

นโยบายการเลิกใช้

OpenClaw ไม่ควรนำสัญญา Plugin ที่มีเอกสารกำกับออกในรุ่นเดียวกับที่เปิดตัวสิ่งทดแทน ลำดับการย้ายข้อมูล:

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

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

ขอบเขตความเข้ากันได้ปัจจุบัน

ปัจจุบันรีจิสทรีติดตามรหัสความเข้ากันได้ประมาณ 70 รหัสในขอบเขตต่อไปนี้ โค้ด Plugin ใหม่ควรใช้สิ่งทดแทนในแต่ละขอบเขตและในคู่มือการย้ายข้อมูลเฉพาะ ส่วน Plugin ที่มีอยู่สามารถใช้เส้นทางความเข้ากันได้ต่อไปได้จนกว่าเอกสาร ข้อมูลวินิจฉัย และบันทึกประจำรุ่นจะประกาศช่วงเวลานำออก

การนำเข้า SDK แบบกว้างรุ่นเก่า เช่น openclaw/plugin-sdk/compat
รูปแบบ Plugin รุ่นเก่าที่มีเฉพาะฮุกและ before_agent_start
ชื่อฮุกล้างข้อมูลรุ่นเก่า api.on("deactivate", ...) ระหว่างที่ Plugin ย้ายไปใช้ gateway_stop
จุดเข้าของ Plugin รุ่นเก่า activate(api) ระหว่างที่ Plugin ย้ายไปใช้ register(api)
นามแฝง SDK รุ่นเก่า เช่น openclaw/extension-api, openclaw/plugin-sdk/channel-runtime, ตัวสร้างสถานะ openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/test-utils (แทนที่ด้วยเส้นทางย่อยสำหรับการทดสอบแบบเฉพาะเจาะจง openclaw/plugin-sdk/*) และนามแฝงชนิด ClawdbotConfig / OpenClawSchemaType
รายการอนุญาตและพฤติกรรมการเปิดใช้งาน Plugin ที่มาพร้อมระบบ
เมทาดาทา env-var ในไฟล์ manifest ของผู้ให้บริการ/ช่องทางรุ่นเก่า
ฮุกและนามแฝงชนิดของ Plugin ผู้ให้บริการรุ่นเก่า ระหว่างที่ผู้ให้บริการย้ายไปใช้ฮุกแค็ตตาล็อก การยืนยันตัวตน การคิด การเล่นซ้ำ และการส่งผ่านที่ระบุไว้อย่างชัดเจน
นามแฝงรันไทม์รุ่นเก่า เช่น api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt และ api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...) ที่เลิกใช้แล้ว
ฟิลด์คอลแบ็กแบบแบนของ WebInboundMessage สำหรับ WhatsApp (ดูด้านล่าง)
ฟิลด์การอนุญาตให้รับเข้าระดับบนสุดของ WebInboundMessage สำหรับ WhatsApp (ดูด้านล่าง)
การลงทะเบียนแบบแยกส่วนของ Plugin หน่วยความจำรุ่นเก่า ระหว่างที่ Plugin หน่วยความจำย้ายไปใช้ registerMemoryCapability
การลงทะเบียนผู้ให้บริการการฝังเวกเตอร์ที่เฉพาะเจาะจงกับหน่วยความจำรุ่นเก่า ระหว่างที่ผู้ให้บริการการฝังเวกเตอร์ย้ายไปใช้ api.registerEmbeddingProvider(...) และ contracts.embeddingProviders
ตัวช่วย SDK ของช่องทางรุ่นเก่าสำหรับสคีมาข้อความเนทีฟ การควบคุมด้วยการกล่าวถึง การจัดรูปแบบซองข้อมูลขาเข้า และการซ้อนความสามารถในการอนุมัติ
นามแฝงคีย์เส้นทางช่องทางและตัวช่วยเปรียบเทียบเป้าหมายรุ่นเก่า ระหว่างที่ Plugin ย้ายไปใช้ openclaw/plugin-sdk/channel-route
คำแนะนำการเปิดใช้งานที่กำลังถูกแทนที่ด้วยความเป็นเจ้าของส่วนสนับสนุนจากไฟล์ manifest
เส้นทางสำรองรันไทม์ setup-api ระหว่างที่ตัวอธิบายการตั้งค่าเริ่มต้นย้ายไปใช้เมทาดาทาแบบไม่ใช้รันไทม์ setup.requiresRuntime: false
ฮุก discovery ของผู้ให้บริการ ระหว่างที่ฮุกแค็ตตาล็อกผู้ให้บริการย้ายไปใช้ catalog.run(...)
เมทาดาทา showConfigured / showInSetup ของช่องทาง ระหว่างที่แพ็กเกจช่องทางย้ายไปใช้ openclaw.channel.exposure
คีย์การกำหนดค่านโยบายรันไทม์รุ่นเก่า ระหว่างที่ doctor ย้ายผู้ปฏิบัติงานไปใช้ agentRuntime
เส้นทางสำรองของเมทาดาทาการกำหนดค่าช่องทางที่มาพร้อมระบบซึ่งสร้างขึ้นอัตโนมัติ ระหว่างที่เมทาดาทา channelConfigs แบบใช้รีจิสทรีก่อนเริ่มนำมาใช้
แฟล็กสภาพแวดล้อมสำหรับการปิดใช้รีจิสทรี Plugin ที่คงอยู่และการย้ายข้อมูลการติดตั้ง ระหว่างที่โฟลว์การซ่อมแซมย้ายผู้ปฏิบัติงานไปใช้ openclaw plugins registry --refresh และ openclaw doctor --fix
เส้นทางการกำหนดค่าการค้นหาเว็บ การดึงข้อมูลเว็บ และ x_search ที่ Plugin เป็นเจ้าของแบบเก่า ระหว่างที่ doctor ย้ายข้อมูลเหล่านั้นไปยัง plugins.entries.<plugin>.config
การกำหนดค่า plugins.installs รุ่นเก่าที่เขียนขึ้นเองและนามแฝงเส้นทางโหลด Plugin ที่มาพร้อมระบบ ระหว่างที่เมทาดาทาการติดตั้งย้ายไปยังบัญชีรายการ Plugin ที่จัดการโดยสถานะ

นามแฝงแบบแบนของคอลแบ็กขาเข้า WhatsApp

คอลแบ็กรันไทม์ของ WhatsApp ส่งมอบ WebInboundMessage ซึ่งประกอบด้วยบริบท event, payload, quote, group และ platform แบบซ้อนที่เป็นมาตรฐาน รวมถึงนามแฝงแบบแบนที่เลิกใช้แล้วสำหรับฟิลด์คอลแบ็กที่เผยแพร่ไปแล้ว โค้ดคอลแบ็กใหม่ควรอ่านบริบทแบบซ้อน โค้ดที่สร้างข้อความคอลแบ็กแบบซ้อนที่สะอาดสามารถใช้ WebInboundCallbackMessage ส่วนตัวรับฟังเพื่อความเข้ากันได้ที่ยังคงแทรกข้อความทดสอบหรือข้อความ Plugin แบบแบนรุ่นเก่าควรใช้ LegacyFlatWebInboundMessage หรือ WebInboundMessageInput

นามแฝงแบบแบนจะยังคงใช้งานได้จนถึง 2026-08-30 ช่วงเวลานี้ใช้เฉพาะกับการเข้าถึงนามแฝงแบบแบน ไม่ครอบคลุมรูปแบบแบบซ้อน ซึ่งเป็นสัญญารันไทม์มาตรฐาน คำอธิบาย TypeScript @deprecated ของนามแฝงแบบแบนแต่ละรายการระบุสิ่งทดแทนแบบซ้อนที่แน่นอน ตัวอย่างทั่วไป:

id, timestamp และ isBatched ย้ายไปอยู่ภายใต้ event
body, mediaPath, mediaType, mediaFileName, mediaUrl, location และ untrustedStructuredContext ย้ายไปอยู่ภายใต้ payload
to, chatId, ฟิลด์ผู้ส่ง/ตนเอง, sendComposing, reply(...) และ sendMedia(...) ย้ายไปอยู่ภายใต้ platform
ฟิลด์ replyTo* ย้ายไปอยู่ภายใต้ quote ส่วนฟิลด์หัวข้อกลุ่ม/ผู้เข้าร่วม/การกล่าวถึงย้ายไปอยู่ภายใต้ group

payload.untrustedStructuredContext ถูกแยกออกจากเพย์โหลดขาเข้าของผู้ให้บริการ Plugin ควรตรวจสอบ label, source และ type ก่อนถือว่า payload ภายในเป็นข้อมูลที่เชื่อถือได้

ฟิลด์การอนุญาตให้รับเข้าของ WhatsApp

ข้อความคอลแบ็ก WhatsApp ที่ยอมรับแล้วจะมี admission ซึ่งเป็นซองข้อมูลที่ปลอดภัยสำหรับเปิดเผยต่อสาธารณะของผลการตัดสินใจควบคุมการเข้าถึงที่อนุญาตให้รับข้อความ โค้ดคอลแบ็กใหม่ควรอ่านข้อเท็จจริงการอนุญาตให้รับเข้าจาก msg.admission แทนฟิลด์การอนุญาตให้รับเข้าระดับบนสุดแบบเก่า

ฟิลด์ระดับบนสุดจะยังคงใช้งานได้จนถึง 2026-08-30 คำอธิบาย TypeScript @deprecated ของแต่ละฟิลด์ระบุสิ่งทดแทน:

from และ conversationId ย้ายไปยัง admission.conversation.id
accountId ย้ายไปยัง admission.accountId
accessControlPassed เป็นมุมมองความเข้ากันได้ที่คำนวณจาก admission.ingress.decision === "allow" สำหรับข้อความที่มี admission อยู่แล้ว การเขียนค่าบูลีนรุ่นเก่าจะไม่เขียนกราฟขาเข้าใหม่
chatType ย้ายไปยัง admission.conversation.kind

แพ็กเกจเครื่องมือตรวจสอบ Plugin

เครื่องมือตรวจสอบ Plugin ควรอยู่นอกรีโพซิทอรีแกนหลักของ OpenClaw โดยเป็นแพ็กเกจ/รีโพซิทอรีแยกต่างหากที่อิงตามสัญญาความเข้ากันได้และไฟล์ manifest ที่มีการกำหนดเวอร์ชัน CLI สำหรับวันแรกควรเป็น:

openclaw-plugin-inspector ./my-plugin

เครื่องมือควรแสดงผลการตรวจสอบไฟล์ manifest/สคีมา เวอร์ชันความเข้ากันได้ของสัญญาที่กำลังตรวจสอบ การตรวจสอบเมทาดาทาการติดตั้ง/แหล่งที่มา การตรวจสอบการนำเข้าในเส้นทางที่ไม่ใช้รันไทม์ และคำเตือนการเลิกใช้/ความเข้ากันได้ ใช้ --json เพื่อให้ได้ผลลัพธ์ที่เครื่องอ่านได้อย่างคงที่สำหรับคำอธิบายประกอบใน CI แกนหลักของ OpenClaw ควรเปิดเผยสัญญาและฟิกซ์เจอร์ที่เครื่องมือตรวจสอบสามารถใช้ได้ แต่ไม่ควรเผยแพร่ไบนารีของเครื่องมือตรวจสอบจากแพ็กเกจหลัก openclaw

เลนการยอมรับสำหรับผู้ดูแล

ใช้ Blacksmith Testbox ที่ทำงานผ่าน Crabbox สำหรับเลนการยอมรับแพ็กเกจที่ติดตั้งได้ เมื่อตรวจสอบเครื่องมือตรวจสอบภายนอกกับแพ็กเกจ Plugin ของ OpenClaw ให้เรียกใช้จากเช็กเอาต์ OpenClaw ที่สะอาดหลังจากสร้างแพ็กเกจแล้ว:

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"

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

บันทึกประจำรุ่น

บันทึกประจำรุ่นควรรวมการเลิกใช้ Plugin ที่กำลังจะเกิดขึ้น พร้อมวันที่เป้าหมายและลิงก์ไปยังเอกสารการย้ายข้อมูล ก่อนที่เส้นทางความเข้ากันได้จะเปลี่ยนเป็น removal-pending หรือ removed

Was this useful?