> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Khả năng tương thích của Plugin

OpenClaw duy trì kết nối các hợp đồng plugin cũ thông qua các bộ điều hợp tương thích
có tên trước khi loại bỏ chúng. Điều này bảo vệ các plugin đi kèm và bên ngoài hiện có
trong khi các hợp đồng SDK, manifest, thiết lập, cấu hình và môi trường chạy agent
phát triển.

## Registry tương thích

Các hợp đồng tương thích plugin được theo dõi trong registry lõi tại
`src/plugins/compat/registry.ts`. Mỗi bản ghi có:

* một mã tương thích ổn định
* trạng thái: `active`, `deprecated`, `removal-pending`, hoặc `removed`
* chủ sở hữu: `sdk`, `config`, `setup`, `channel`, `provider`, `plugin-execution`,
  `agent-runtime`, hoặc `core`
* ngày giới thiệu và ngừng hỗ trợ khi áp dụng
* hướng dẫn thay thế
* tài liệu, chẩn đoán và kiểm thử bao quát hành vi cũ và mới

Registry là nguồn phục vụ việc lập kế hoạch của người bảo trì và các bước kiểm tra
trình kiểm tra plugin trong tương lai. Nếu một hành vi dành cho plugin thay đổi, hãy
thêm hoặc cập nhật bản ghi tương thích trong cùng thay đổi bổ sung bộ điều hợp.

Khả năng tương thích của việc sửa chữa và di chuyển bằng Doctor được theo dõi riêng tại
`src/commands/doctor/shared/deprecation-compat.ts`. Các bản ghi đó bao quát các
cấu trúc cấu hình cũ, bố cục sổ cái cài đặt và các shim sửa chữa có thể cần
tiếp tục khả dụng sau khi đường dẫn tương thích của môi trường chạy bị loại bỏ.

Các đợt rà soát bản phát hành nên kiểm tra cả hai registry. Không xóa một bản di chuyển
của Doctor chỉ vì bản ghi tương thích môi trường chạy hoặc cấu hình tương ứng
đã hết hạn; trước tiên hãy xác minh rằng không có đường dẫn nâng cấp được hỗ trợ nào vẫn
cần việc sửa chữa đó. Đồng thời xác thực lại từng chú thích thay thế trong quá trình lập kế hoạch
bản phát hành, vì quyền sở hữu plugin và phạm vi cấu hình có thể thay đổi khi các nhà cung cấp
và kênh được chuyển ra khỏi lõi.

## Chính sách ngừng hỗ trợ

OpenClaw không nên loại bỏ một hợp đồng plugin đã được ghi trong tài liệu trong cùng bản phát hành
giới thiệu hợp đồng thay thế. Trình tự di chuyển:

1. Thêm hợp đồng mới.
2. Duy trì kết nối hành vi cũ thông qua một bộ điều hợp tương thích có tên.
3. Phát chẩn đoán hoặc cảnh báo khi tác giả plugin có thể xử lý.
4. Ghi tài liệu về giải pháp thay thế và tiến trình thời gian.
5. Kiểm thử cả đường dẫn cũ và mới.
6. Chờ hết khoảng thời gian di chuyển đã công bố.
7. Chỉ loại bỏ khi có phê duyệt rõ ràng cho bản phát hành phá vỡ tương thích.

Các bản ghi đã ngừng hỗ trợ phải bao gồm ngày bắt đầu cảnh báo, giải pháp thay thế, liên kết
tài liệu và ngày loại bỏ cuối cùng không quá ba tháng sau khi cảnh báo
bắt đầu. Không thêm đường dẫn tương thích đã ngừng hỗ trợ với khoảng thời gian
loại bỏ không xác định, trừ khi người bảo trì quyết định rõ ràng rằng đó là khả năng tương thích
vĩnh viễn và đánh dấu là `active`.

## Các khu vực tương thích hiện tại

Đợt rà soát tháng 7 năm 2026 đã loại bỏ các bí danh SDK gốc, manifest, nhà cung cấp, môi trường chạy,
cờ registry và cấu hình web thuộc sở hữu plugin đã hết hạn. Các bản di chuyển của Doctor vẫn được
theo dõi riêng để các đường dẫn nâng cấp được hỗ trợ vẫn có thể sửa cấu hình cũ.

Các khu vực tương thích còn lại có ngày cụ thể là:

* các khoảng thời gian đường dẫn con SDK trong tháng 8 và tháng 9 được liệt kê trong hướng dẫn di chuyển
* các bí danh hook `api.on("deactivate", ...)` và `api.on("subagent_spawning", ...)`
* đăng ký embedding dành riêng cho bộ nhớ và cầu nối kho phiên beta.5
* các bí danh callback đầu vào WhatsApp được mô tả bên dưới
* phân tích đích kênh rõ ràng và `openclaw/plugin-sdk/messaging-targets`
* các bí danh agent Pi nhúng
* các bí danh SDK bộ khung agent đã phát hành, việc loại bỏ chúng đang chờ một quyết định
  di chuyển mới được ghi tài liệu bên ngoài

Các bản ghi registry đang hoạt động, không có ngày cụ thể bao quát hành vi được hỗ trợ thay vì khoản nợ
loại bỏ, bao gồm gợi ý kích hoạt, thu nhận plugin, bật plugin đi kèm
và cơ chế dự phòng cấu hình kênh được tạo.

### Các bí danh phẳng của callback đầu vào WhatsApp

Các callback môi trường chạy WhatsApp cung cấp `WebInboundMessage`: các ngữ cảnh
lồng nhau chuẩn tắc `event`, `payload`, `quote`, `group` và `platform`, cùng
các bí danh phẳng đã ngừng hỗ trợ cho những trường callback đã phát hành. Mã callback mới
nên đọc các ngữ cảnh lồng nhau. Mã tạo thông điệp callback lồng nhau sạch
có thể dùng `WebInboundCallbackMessage`; các trình lắng nghe tương thích vẫn
chèn thông điệp kiểm thử hoặc plugin phẳng cũ nên dùng
`LegacyFlatWebInboundMessage` hoặc `WebInboundMessageInput`.

Các bí danh phẳng vẫn khả dụng đến **2026-08-30**; khoảng thời gian này chỉ áp dụng
cho việc truy cập bí danh phẳng, không áp dụng cho cấu trúc lồng nhau, vốn là hợp đồng
môi trường chạy chuẩn tắc. Chú thích TypeScript `@deprecated` của từng bí danh phẳng
nêu rõ mục thay thế lồng nhau chính xác. Các ví dụ phổ biến:

* `id`, `timestamp` và `isBatched` chuyển vào `event`.
* `body`, `mediaPath`, `mediaType`, `mediaFileName`, `mediaUrl`, `location`
  và `untrustedStructuredContext` chuyển vào `payload`.
* `to`, `chatId`, các trường người gửi/bản thân, `sendComposing`, `reply(...)` và
  `sendMedia(...)` chuyển vào `platform`.
* các trường `replyTo*` chuyển vào `quote`; các trường chủ đề nhóm/người tham gia/lượt đề cập
  chuyển vào `group`.

`payload.untrustedStructuredContext` được trích xuất từ các tải trọng đầu vào của nhà cung cấp.
Plugin nên kiểm tra `label`, `source` và `type` trước khi
coi `payload` của nó là có thẩm quyền.

### Các trường chấp nhận đầu vào WhatsApp

Các thông điệp callback WhatsApp được chấp nhận mang theo `admission`, một phong bì
an toàn để công khai cho quyết định kiểm soát truy cập đã chấp nhận thông điệp. Mã
callback mới nên đọc các dữ kiện chấp nhận từ `msg.admission` thay vì
các trường chấp nhận cấp cao nhất cũ hơn.

Các trường cấp cao nhất vẫn khả dụng đến **2026-08-30**. Chú thích
TypeScript `@deprecated` của từng trường nêu rõ mục thay thế:

* `from` và `conversationId` chuyển đến `admission.conversation.id`.
* `accountId` chuyển đến `admission.accountId`.
* `accessControlPassed` là một dạng xem tương thích được suy ra từ
  `admission.ingress.decision === "allow"`; trên các thông điệp đã mang theo
  `admission`, việc ghi giá trị boolean cũ không viết lại đồ thị
  đầu vào.
* `chatType` chuyển đến `admission.conversation.kind`.

## Gói trình kiểm tra plugin

Trình kiểm tra plugin nên nằm ngoài repo OpenClaw lõi dưới dạng một
gói/repository riêng biệt, dựa trên các hợp đồng tương thích và
manifest có phiên bản. CLI ban đầu nên là:

```sh theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw-plugin-inspector ./my-plugin
```

Nó nên xuất kết quả xác thực manifest/schema, phiên bản tương thích hợp đồng
đang được kiểm tra, các bước kiểm tra siêu dữ liệu cài đặt/nguồn, các bước kiểm tra nhập
đường dẫn nguội và cảnh báo ngừng hỗ trợ/tương thích. Dùng `--json` để có đầu ra
ổn định mà máy có thể đọc trong các chú thích CI. Lõi OpenClaw nên công khai
các hợp đồng và fixture mà trình kiểm tra có thể sử dụng, nhưng không nên phát hành
tệp nhị phân của trình kiểm tra từ gói `openclaw` chính.

### Làn nghiệm thu dành cho người bảo trì

Dùng Blacksmith Testbox dựa trên Crabbox cho làn nghiệm thu gói có thể cài đặt
khi xác thực trình kiểm tra bên ngoài đối với các gói plugin OpenClaw.
Chạy làn này từ một bản checkout OpenClaw sạch sau khi gói được dựng:

```sh theme={"theme":{"light":"min-light","dark":"min-dark"}}
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"
```

Giữ làn này ở chế độ tùy chọn tham gia dành cho người bảo trì, vì nó cài đặt một gói npm
bên ngoài và có thể kiểm tra các gói plugin được sao chép bên ngoài repo. Các biện pháp bảo vệ
repo cục bộ bao quát sơ đồ xuất SDK, siêu dữ liệu registry tương thích,
việc loại bỏ dần các lệnh nhập SDK đã ngừng hỗ trợ và các ranh giới nhập của tiện ích mở rộng đi kèm;
bằng chứng từ trình kiểm tra trên Testbox bao quát gói theo cách các tác giả plugin bên ngoài
sử dụng nó.

## Ghi chú phát hành

Ghi chú phát hành nên bao gồm các đợt ngừng hỗ trợ plugin sắp tới cùng ngày mục tiêu
và liên kết đến tài liệu di chuyển, trước khi một đường dẫn tương thích chuyển sang
`removal-pending` hoặc `removed`.