---
read_when:
    - คุณดูแลรักษา Plugin ของ OpenClaw
    - คุณเห็นคำเตือนเกี่ยวกับความเข้ากันได้ของ Plugin
    - คุณกำลังวางแผนการย้าย Plugin SDK หรือแมนิเฟสต์
summary: สัญญาความเข้ากันได้ของ Plugin, เมตาดาต้าการเลิกใช้งาน และความคาดหวังในการย้ายระบบ
title: ความเข้ากันได้ของ Plugin
x-i18n:
    generated_at: "2026-05-02T10:22:45Z"
    model: gpt-5.5
    provider: openai
    source_hash: eecf94743cf34c5b773bfa8066164f90b7c8a75667c43f3f1002d32ec1d04902
    source_path: plugins/compatibility.md
    workflow: 16
---

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 วันแรกควรเป็น:

```sh
openclaw-plugin-inspector ./my-plugin
```

ควรแสดงผล:

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

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

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

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

```sh
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/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <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 ที่มีเอกสารออกในรุ่นเดียวกับที่เพิ่มสิ่งแทนที่

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

1. เพิ่มสัญญาใหม่
2. คงพฤติกรรมเดิมไว้โดยเชื่อมผ่านอะแดปเตอร์ความเข้ากันได้ที่มีชื่อ
3. แสดงการวินิจฉัยหรือคำเตือนเมื่อผู้เขียน Plugin สามารถดำเนินการได้
4. จัดทำเอกสารสิ่งแทนที่และไทม์ไลน์
5. ทดสอบทั้งเส้นทางเดิมและเส้นทางใหม่
6. รอให้พ้นช่วงเวลาการย้ายข้อมูลที่ประกาศไว้
7. นำออกเฉพาะเมื่อได้รับการอนุมัติการปล่อยเวอร์ชันที่มีการเปลี่ยนแปลงแบบ 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`
