Plugin maintainer reference

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

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

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

สัญญาความเข้ากันได้ของ 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 ระเบียนเหล่านั้นครอบคลุม รูปแบบ config เก่า โครงร่างบัญชีรายการติดตั้ง และชิมสำหรับการซ่อมแซมที่อาจต้อง คงไว้หลังจากนำเส้นทางความเข้ากันได้ของรันไทม์ออกแล้ว

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

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

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

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

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

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

การตรวจสอบเดือนกรกฎาคม 2026 ได้นำ SDK ระดับราก, manifest, ผู้ให้บริการ, รันไทม์, แฟล็กรีจิสทรี และนามแฝง web-config ที่ Plugin เป็นเจ้าของซึ่งหมดอายุแล้วออก การย้ายข้อมูลของ Doctor ยังคง ได้รับการติดตามแยกต่างหาก เพื่อให้เส้นทางอัปเกรดที่รองรับยังสามารถซ่อมแซม config เก่าได้

ขอบเขตความเข้ากันได้ที่เหลืออยู่และมีกำหนดวันที่ ได้แก่:

ช่วงเวลาของเส้นทางย่อย SDK ในเดือนสิงหาคมและกันยายนที่ระบุไว้ในคู่มือการย้ายข้อมูล
นามแฝงฮุก api.on("deactivate", ...) และ api.on("subagent_spawning", ...)
การลงทะเบียน embedding เฉพาะหน่วยความจำและบริดจ์ session-store ของ beta.5
นามแฝง callback ขาเข้าของ WhatsApp ที่อธิบายไว้ด้านล่าง
การแยกวิเคราะห์เป้าหมายช่องทางแบบชัดเจนและ openclaw/plugin-sdk/messaging-targets
นามแฝงเอเจนต์ Pi แบบฝัง
นามแฝง SDK ของ agent-harness ที่เผยแพร่แล้ว ซึ่งการนำออกกำลังรอการตัดสินใจใหม่ เกี่ยวกับการย้ายข้อมูลที่จัดทำเป็นเอกสารภายนอก

ระเบียนรีจิสทรีที่ใช้งานอยู่และไม่มีกำหนดวันที่ครอบคลุมพฤติกรรมที่รองรับ ไม่ใช่ภาระจากการนำออก รวมถึงคำแนะนำการเปิดใช้งาน การดักจับของ Plugin การเปิดใช้งาน Plugin ที่รวมมาให้ และทางเลือกสำรองของ channel-config ที่สร้างขึ้น

นามแฝงแบบแบนของ callback ขาเข้า WhatsApp

callback รันไทม์ของ WhatsApp ส่ง WebInboundMessage: บริบทแบบซ้อนที่เป็นมาตรฐาน ได้แก่ event, payload, quote, group และ platform พร้อม นามแฝงแบบแบนที่เลิกใช้แล้วสำหรับฟิลด์ callback ที่เผยแพร่ โค้ด callback ใหม่ ควรอ่านบริบทแบบซ้อน โค้ดที่สร้างข้อความ callback แบบซ้อนที่สะอาด สามารถใช้ 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

ข้อความ callback ของ WhatsApp ที่ได้รับการยอมรับจะมี admission ซึ่งเป็นเอนเวโลป ที่ปลอดภัยสำหรับการเปิดเผยต่อสาธารณะเกี่ยวกับการตัดสินใจควบคุมการเข้าถึงที่อนุญาตให้รับข้อความ โค้ด callback ใหม่ควรอ่านข้อเท็จจริงการอนุญาตรับเข้าจาก 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/schema, เวอร์ชันความเข้ากันได้ ของสัญญาที่กำลังตรวจสอบ, การตรวจสอบเมทาดาทาการติดตั้ง/แหล่งที่มา, การตรวจสอบการนำเข้าบน เส้นทางที่ไม่ได้ใช้งานบ่อย และคำเตือนการเลิกใช้/ความเข้ากันได้ ใช้ --json สำหรับผลลัพธ์ ที่เครื่องอ่านได้และมีความคงที่ในคำอธิบายประกอบ CI ส่วนกลางของ OpenClaw ควรเปิดเผย สัญญาและฟิกซ์เจอร์ที่ตัวตรวจสอบนำไปใช้ได้ แต่ไม่ควรเผยแพร่ ไบนารีตัวตรวจสอบจากแพ็กเกจ openclaw หลัก

ช่องทางการยอมรับสำหรับผู้ดูแล

ใช้ Blacksmith Testbox ที่รองรับด้วย Crabbox สำหรับช่องทางการยอมรับ แพ็กเกจที่ติดตั้งได้ เมื่อตรวจสอบตัวตรวจสอบภายนอกกับแพ็กเกจ Plugin ของ OpenClaw ให้เรียกใช้จาก checkout ของ 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?