---
read_when:
    - คุณดูแล Plugin ของ OpenClaw
    - คุณเห็นคำเตือนเกี่ยวกับความเข้ากันได้ของ Plugin
    - คุณกำลังวางแผนการย้าย SDK ของ Plugin หรือไฟล์แมนิเฟสต์
summary: สัญญาความเข้ากันได้ของ Plugin, ข้อมูลเมตาการเลิกใช้งาน และข้อกำหนดในการย้ายระบบ
title: ความเข้ากันได้ของ Plugin
x-i18n:
    generated_at: "2026-07-12T16:28:25Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 26f737e40175652cb24327c91d2af9dbf72b1b254011115f5b512a309707711c
    source_path: plugins/compatibility.md
    workflow: 16
---

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 ที่มีเอกสารกำกับออกในรุ่นเดียวกับที่เปิดตัวสิ่งทดแทน ลำดับการย้ายข้อมูล:

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

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

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

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

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

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

```sh
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`