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

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

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

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

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

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

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

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