Chuyển đến nội dung chính

​
Di chuyển Plugin SDK

OpenClaw đã chuyển từ lớp tương thích ngược rộng sang kiến trúc plugin hiện đại với các import có mục đích rõ ràng và được tài liệu hóa. Nếu plugin của bạn được xây dựng trước khi có kiến trúc mới, hướng dẫn này sẽ giúp bạn di chuyển.

​
Thay đổi là gì

Hệ thống plugin cũ cung cấp hai bề mặt rộng mở cho phép plugin import bất kỳ thứ gì cần thiết từ một điểm nhập duy nhất:
  • openclaw/plugin-sdk/compat — một import duy nhất tái xuất hàng chục helper. Nó được giới thiệu để giữ cho các plugin dựa trên hook cũ hoạt động trong khi kiến trúc plugin mới đang được xây dựng.
  • openclaw/extension-api — một cầu nối cho phép plugin truy cập trực tiếp vào các helper phía host như trình chạy agent nhúng.
Cả hai bề mặt này hiện đã bị ngừng sử dụng. Chúng vẫn hoạt động trong runtime, nhưng plugin mới không được sử dụng chúng, và các plugin hiện có nên di chuyển trước khi bản phát hành chính tiếp theo loại bỏ chúng.
Lớp tương thích ngược sẽ bị loại bỏ trong bản phát hành chính tiếp theo. Các plugin vẫn import từ các bề mặt này sẽ bị lỗi khi điều đó xảy ra.

​
Tại sao thay đổi này xảy ra

Cách tiếp cận cũ gây ra nhiều vấn đề:
  • Khởi động chậm — import một helper tải hàng chục module không liên quan
  • Phụ thuộc vòng tròn — tái xuất rộng làm dễ tạo ra vòng lặp import
  • Bề mặt API không rõ ràng — không có cách nào để biết export nào là ổn định so với nội bộ
SDK plugin hiện đại khắc phục điều này: mỗi đường dẫn import (openclaw/plugin-sdk/\<subpath\>) là một module nhỏ, tự chứa với mục đích rõ ràng và hợp đồng được tài liệu hóa.

​
Cách di chuyển

1

Tìm các import đã ngừng sử dụng

Tìm kiếm trong plugin của bạn các import từ bất kỳ bề mặt nào đã ngừng sử dụng:
grep -r "plugin-sdk/compat" my-plugin/
grep -r "openclaw/extension-api" my-plugin/
2

Thay thế bằng các import có mục đích rõ ràng

Mỗi export từ bề mặt cũ ánh xạ tới một đường dẫn import hiện đại cụ thể:
// Trước (lớp tương thích ngược đã ngừng sử dụng)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// Sau (import có mục đích rõ ràng hiện đại)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
Đối với các helper phía host, sử dụng runtime plugin được tiêm thay vì import trực tiếp:
// Trước (cầu nối extension-api đã ngừng sử dụng)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// Sau (runtime được tiêm)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
Mẫu tương tự áp dụng cho các helper cầu nối cũ khác:
Import cũTương đương hiện đại
resolveAgentDirapi.runtime.agent.resolveAgentDir
resolveAgentWorkspaceDirapi.runtime.agent.resolveAgentWorkspaceDir
resolveAgentIdentityapi.runtime.agent.resolveAgentIdentity
resolveThinkingDefaultapi.runtime.agent.resolveThinkingDefault
resolveAgentTimeoutMsapi.runtime.agent.resolveAgentTimeoutMs
ensureAgentWorkspaceapi.runtime.agent.ensureAgentWorkspace
helper lưu trữ sessionapi.runtime.agent.session.*
3

Xây dựng và kiểm tra

pnpm build
pnpm test -- my-plugin/

​
Tham khảo đường dẫn import

Đường dẫn importMục đíchCác export chính
plugin-sdk/plugin-entryHelper nhập plugin chuẩndefinePluginEntry
plugin-sdk/coreĐịnh nghĩa nhập kênh, trình tạo kênh, kiểu cơ bảndefineChannelPluginEntry, createChatChannelPlugin
plugin-sdk/channel-setupBộ điều hợp wizard thiết lậpcreateOptionalChannelSetupSurface
plugin-sdk/channel-pairingNguyên thủy ghép đôi DMcreateChannelPairingController
plugin-sdk/channel-reply-pipelineTiền tố trả lời + dây gõcreateChannelReplyPipeline
plugin-sdk/channel-config-helpersNhà máy điều hợp cấu hìnhcreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaTrình tạo schema cấu hìnhKiểu schema cấu hình kênh
plugin-sdk/channel-policyGiải quyết chính sách nhóm/DMresolveChannelGroupRequireMention
plugin-sdk/channel-lifecycleTheo dõi trạng thái tài khoảncreateAccountStatusSink
plugin-sdk/channel-runtimeHelper dây runtimeTiện ích runtime kênh
plugin-sdk/channel-send-resultKiểu kết quả gửiKiểu kết quả trả lời
plugin-sdk/runtime-storeLưu trữ plugin bền vữngcreatePluginRuntimeStore
plugin-sdk/allow-fromĐịnh dạng danh sách cho phépformatAllowFromLowercase
plugin-sdk/allowlist-resolutionÁnh xạ đầu vào danh sách cho phépmapAllowlistResolutionInputs
plugin-sdk/command-authGating lệnhresolveControlCommandGate
plugin-sdk/secret-inputPhân tích đầu vào bí mậtHelper đầu vào bí mật
plugin-sdk/webhook-ingressHelper yêu cầu webhookTiện ích mục tiêu webhook
plugin-sdk/reply-payloadKiểu trả lời tin nhắnKiểu payload trả lời
plugin-sdk/provider-onboardBản vá onboarding nhà cung cấpHelper cấu hình onboarding
plugin-sdk/keyed-async-queueHàng đợi async có thứ tựKeyedAsyncQueue
plugin-sdk/testingTiện ích kiểm traHelper và mock kiểm tra
Sử dụng import hẹp nhất phù hợp với công việc. Nếu không tìm thấy export, kiểm tra nguồn tại src/plugin-sdk/ hoặc hỏi trong Discord.

​
Lịch trình loại bỏ

Khi nàoĐiều gì xảy ra
Hiện tạiCác bề mặt đã ngừng sử dụng phát ra cảnh báo runtime
Bản phát hành chính tiếp theoCác bề mặt đã ngừng sử dụng sẽ bị loại bỏ; các plugin vẫn sử dụng chúng sẽ bị lỗi
Tất cả các plugin cốt lõi đã được di chuyển. Các plugin bên ngoài nên di chuyển trước bản phát hành chính tiếp theo.

​
Tạm thời tắt cảnh báo

Đặt các biến môi trường này trong khi bạn làm việc trên việc di chuyển: 
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
Đây là một giải pháp tạm thời, không phải là giải pháp lâu dài.

​
Liên quan

Last modified on March 22, 2026