Plugins

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

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

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

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

แต่ละระเบียนมี:

รหัสความเข้ากันได้ที่เสถียร
สถานะ: active, deprecated, removal-pending หรือ removed
เจ้าของ: SDK, การกำหนดค่า, การตั้งค่า, ช่องทาง, ผู้ให้บริการ, การเรียกใช้ Plugin, รันไทม์ของเอเจนต์, หรือแกนหลัก
วันที่เริ่มใช้และวันที่เลิกสนับสนุนเมื่อเกี่ยวข้อง
คำแนะนำการแทนที่
เอกสาร การวินิจฉัย และการทดสอบที่ครอบคลุมพฤติกรรมเดิมและใหม่

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

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

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

แพ็กเกจ Plugin inspector

Plugin inspector ควรอยู่ภายนอก repo แกนหลักของ OpenClaw ในฐานะแพ็กเกจ/repository แยกต่างหากที่อิงกับสัญญาความเข้ากันได้และแมนิเฟสต์ที่มีเวอร์ชัน

CLI วันแรกควรเป็น:

openclaw-plugin-inspector ./my-plugin

ควรแสดงผล:

การตรวจสอบแมนิเฟสต์/สคีมา
เวอร์ชันความเข้ากันได้ของสัญญาที่กำลังตรวจ
การตรวจสอบเมทาดาทาการติดตั้ง/แหล่งที่มา
การตรวจสอบการอิมพอร์ตเส้นทางเย็น
คำเตือนการเลิกสนับสนุนและความเข้ากันได้

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

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

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

blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "pnpm install && pnpm build && npm exec --yes @openclaw/[email protected] -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- <clawhub-plugin-dir> --json"
blacksmith testbox stop <tbx_id>

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

นโยบายการเลิกสนับสนุน

OpenClaw ไม่ควรนำสัญญา Plugin ที่มีเอกสารออกในรุ่นเดียวกับที่เพิ่มสิ่งแทนที่

ลำดับการย้ายข้อมูลคือ:

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

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

พื้นที่ความเข้ากันได้ปัจจุบัน

ระเบียนความเข้ากันได้ปัจจุบันประกอบด้วย:

การอิมพอร์ต SDK แบบกว้างรุ่นเก่า เช่น openclaw/plugin-sdk/compat
รูปทรง Plugin แบบ hook-only รุ่นเก่าและ before_agent_start
จุดเข้า Plugin รุ่นเก่า activate(api) ระหว่างที่ Plugin ย้ายไปใช้ register(api)
alias ของ SDK รุ่นเก่า เช่น openclaw/extension-api, openclaw/plugin-sdk/channel-runtime, ตัวสร้างสถานะ openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/test-utils (แทนที่ด้วยเส้นทางย่อยทดสอบ openclaw/plugin-sdk/* ที่เจาะจง) และ alias ชนิด ClawdbotConfig / OpenClawSchemaType
allowlist ของ Plugin ที่ bundled และพฤติกรรมการเปิดใช้
เมทาดาทาแมนิเฟสต์ env-var ของผู้ให้บริการ/ช่องทางรุ่นเก่า
hook ของ Plugin ผู้ให้บริการรุ่นเก่าและ alias ชนิดระหว่างที่ผู้ให้บริการย้ายไปใช้ hook แค็ตตาล็อก การตรวจสอบสิทธิ์ การคิด การเล่นซ้ำ และการขนส่งที่ชัดเจน
alias รันไทม์รุ่นเก่า เช่น api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt และ api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...) ที่เลิกสนับสนุนแล้ว
การลงทะเบียนแบบแยกของ memory-plugin รุ่นเก่า ระหว่างที่ Plugin หน่วยความจำย้ายไปใช้ registerMemoryCapability
helper ของ SDK ช่องทางรุ่นเก่าสำหรับสคีมาข้อความเนทีฟ การควบคุม mention, การจัดรูปแบบซอง inbound และการซ้อนความสามารถการอนุมัติ
alias ของคีย์เส้นทางช่องทางและ helper comparable-target รุ่นเก่า ระหว่างที่ Plugin ย้ายไปใช้ openclaw/plugin-sdk/channel-route
hint การเปิดใช้งานที่กำลังถูกแทนที่ด้วยความเป็นเจ้าของ contribution ในแมนิเฟสต์
fallback รันไทม์ setup-api ระหว่างที่ตัวอธิบายการตั้งค่าย้ายไปใช้เมทาดาทาเย็น setup.requiresRuntime: false
hook discovery ของผู้ให้บริการ ระหว่างที่ hook แค็ตตาล็อกผู้ให้บริการย้ายไปใช้ catalog.run(...)
เมทาดาทา showConfigured / showInSetup ของช่องทาง ระหว่างที่แพ็กเกจช่องทางย้ายไปใช้ openclaw.channel.exposure
คีย์การกำหนดค่า runtime-policy รุ่นเก่า ระหว่างที่ doctor ย้ายผู้ปฏิบัติงานไปใช้ agentRuntime
fallback เมทาดาทาการกำหนดค่าช่องทางที่ bundled และสร้างขึ้น ระหว่างที่เมทาดาทาแบบ registry-first channelConfigs ลงจอด
แฟล็ก env สำหรับปิดใช้รีจิสทรี Plugin ที่ persist ไว้และการย้ายข้อมูลการติดตั้ง ระหว่างที่โฟลว์ซ่อมแซมย้ายผู้ปฏิบัติงานไปใช้ openclaw plugins registry --refresh และ openclaw doctor --fix
เส้นทางการกำหนดค่า web search, web fetch และ x_search ที่ Plugin เป็นเจ้าของรุ่นเก่า ระหว่างที่ doctor ย้ายไปยัง plugins.entries.<plugin>.config
การกำหนดค่าที่เขียนด้วย plugins.installs รุ่นเก่าและ alias เส้นทางโหลดของ Plugin ที่ bundled ระหว่างที่เมทาดาทาการติดตั้งย้ายไปยังบัญชีแยกประเภท Plugin ที่จัดการโดยสถานะ

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

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

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

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

# แพ็กเกจ Plugin inspector

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

# นโยบายการเลิกสนับสนุน

# พื้นที่ความเข้ากันได้ปัจจุบัน