Di chuyển Plugin SDK

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

Những gì đang thay đổi

Hệ thống Plugin cũ cung cấp hai bề mặt mở rộng, cho phép Plugin import bất cứ thứ gì chúng cần từ một điểm vào duy nhất:

• openclaw/plugin-sdk/compat - một import duy nhất re-export hàng chục helper. Nó được giới thiệu để giữ cho các Plugin dựa trên hook cũ tiếp tục hoạt động trong khi kiến trúc Plugin mới đang được xây dựng.
• openclaw/plugin-sdk/infra-runtime - một barrel helper runtime rộng, trộn lẫn sự kiện hệ thống, trạng thái Heartbeat, hàng đợi phân phối, helper fetch/proxy, helper tệp, kiểu phê duyệt và các tiện ích không liên quan.
• openclaw/plugin-sdk/config-runtime - một barrel tương thích cấu hình rộng vẫn mang các helper load/write trực tiếp đã bị ngừng khuyến nghị trong giai đoạn di chuyển.
• 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.
• api.registerEmbeddedExtensionFactory(...) - một hook tiện ích mở rộng bundled chỉ dành cho embedded-runner đã bị loại bỏ, từng có thể quan sát các sự kiện embedded-runner như tool_result.

Các bề mặt import rộng hiện đã bị ngừng khuyến nghị. Chúng vẫn hoạt động ở runtime, nhưng Plugin mới không được 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 major tiếp theo loại bỏ chúng. API đăng ký extension factory chỉ dành cho embedded-runner đã bị loại bỏ; hãy dùng middleware kết quả công cụ thay thế.

OpenClaw không loại bỏ hoặc diễn giải lại hành vi Plugin đã được ghi tài liệu trong cùng thay đổi giới thiệu phương án thay thế. Các thay đổi phá vỡ hợp đồng trước tiên phải đi qua bộ chuyển đổi tương thích, chẩn đoán, tài liệu và giai đoạn ngừng khuyến nghị. Điều đó áp dụng cho import SDK, trường manifest, API thiết lập, hook và hành vi đăng ký runtime.

Vì sao thay đổi này được thực hiện

Cách tiếp cận cũ gây ra các vấn đề:

• Khởi động chậm - import một helper đã load hàng chục mô-đun không liên quan
• Phụ thuộc vòng - các re-export rộng khiến việc tạo vòng import trở nên dễ dàng
• Bề mặt API không rõ ràng - không có cách nào biết export nào ổn định và export nào là 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 mô-đun nhỏ, tự chứa, có mục đích rõ ràng và hợp đồng được ghi tài liệu.

Các seam tiện ích provider legacy cho các kênh bundled cũng đã bị loại bỏ. Các seam helper mang thương hiệu kênh là lối tắt riêng của mono-repo, không phải hợp đồng Plugin ổn định. Hãy dùng các subpath SDK chung, hẹp thay thế. Bên trong workspace Plugin bundled, giữ các helper do provider sở hữu trong api.ts hoặc runtime-api.ts của chính Plugin đó.

Ví dụ provider bundled hiện tại:

• Anthropic giữ các helper stream dành riêng cho Claude trong seam api.ts / contract-api.ts của riêng nó
• OpenAI giữ provider builder, helper model mặc định và realtime provider builder trong api.ts của riêng nó
• OpenRouter giữ provider builder và helper onboarding/config trong api.ts của riêng nó

Kế hoạch di chuyển Talk và giọng nói realtime

Mã Talk cho giọng nói realtime, điện thoại, cuộc họp và trình duyệt đang chuyển từ ghi sổ lượt cục bộ theo bề mặt sang một bộ điều khiển phiên Talk dùng chung được export bởi openclaw/plugin-sdk/realtime-voice. Bộ điều khiển mới sở hữu envelope sự kiện Talk chung, trạng thái lượt đang hoạt động, trạng thái capture, trạng thái output-audio, lịch sử sự kiện gần đây và từ chối lượt đã cũ. Plugin provider nên tiếp tục sở hữu các phiên realtime đặc thù theo nhà cung cấp; Plugin bề mặt nên tiếp tục sở hữu capture, playback, điện thoại và các khác biệt riêng của cuộc họp.

Đợt di chuyển Talk này cố ý là breaking-clean:

1. Giữ controller/runtime primitive dùng chung trong plugin-sdk/realtime-voice.
2. Chuyển các bề mặt bundled sang controller dùng chung: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime và native push-to-talk.
3. Thay các họ RPC Talk cũ bằng API cuối cùng talk.session.* và talk.client.*.
4. Quảng bá một kênh sự kiện Talk live trong Gateway hello-ok.features.events: talk.event.
5. Xóa endpoint HTTP realtime cũ và mọi đường dẫn ghi đè instruction theo thời điểm request.

Mã mới không nên gọi trực tiếp createTalkEventSequencer(...) trừ khi nó đang triển khai một adapter cấp thấp hoặc fixture kiểm thử. Ưu tiên controller dùng chung để sự kiện theo phạm vi lượt không thể được phát ra nếu thiếu turn id, các lệnh gọi turnEnd / turnCancel đã cũ không thể xóa một lượt đang hoạt động mới hơn, và các sự kiện lifecycle output-audio luôn nhất quán trên điện thoại, cuộc họp, browser relay, managed-room handoff và client Talk native.

Hình dạng API công khai mục tiêu là:

// Gateway-owned Talk session API.await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // Client-owned provider session API.await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

Các phiên WebRTC/provider-websocket do trình duyệt sở hữu dùng talk.client.create, vì trình duyệt sở hữu thương lượng provider và transport media trong khi Gateway sở hữu thông tin xác thực, instruction và chính sách công cụ. talk.session.* là bề mặt chung do Gateway quản lý cho gateway-relay realtime, gateway-relay transcription và các phiên STT/TTS native managed-room.

Các cấu hình legacy đặt bộ chọn realtime cạnh talk.provider / talk.providers nên được sửa bằng openclaw doctor --fix; Talk runtime không diễn giải lại cấu hình provider speech/TTS thành cấu hình provider realtime.

Các tổ hợp talk.session.create được hỗ trợ được cố ý giữ nhỏ:

Bảng phương thức đã bị loại bỏ:

Từ vựng điều khiển hợp nhất cũng được cố ý giữ hẹp:

Không đưa các trường hợp đặc biệt theo nhà cung cấp hoặc nền tảng vào core để làm cho việc này hoạt động. Core sở hữu ngữ nghĩa phiên Talk. Plugin nhà cung cấp sở hữu thiết lập phiên của nhà cung cấp. Voice-call và Google Meet sở hữu các adapter điện thoại/họp. Trình duyệt và ứng dụng native sở hữu UX capture/playback của thiết bị.

Chính sách tương thích

Đối với Plugin bên ngoài, công việc tương thích tuân theo thứ tự này:

1. thêm hợp đồng mới
2. giữ hành vi cũ được nối qua một adapter tương thích
3. phát ra chẩn đoán hoặc cảnh báo nêu tên đường dẫn cũ và phần thay thế
4. bao phủ cả hai đường dẫn trong kiểm thử
5. ghi tài liệu về việc ngừng hỗ trợ và đường dẫn di chuyển
6. chỉ gỡ bỏ sau khoảng thời gian di chuyển đã công bố, thường trong một bản phát hành lớn

Maintainer có thể kiểm tra hàng đợi di chuyển hiện tại bằng pnpm plugins:boundary-report. Dùng pnpm plugins:boundary-report:summary để có số lượng cô đọng, --owner <id> cho một Plugin hoặc chủ sở hữu tương thích, và pnpm plugins:boundary-report:ci khi một cổng CI cần thất bại với các bản ghi tương thích đã đến hạn, import SDK dành riêng chéo chủ sở hữu, hoặc các subpath SDK dành riêng không dùng. Báo cáo nhóm các bản ghi tương thích đã ngừng hỗ trợ theo ngày gỡ bỏ, đếm các tham chiếu code/tài liệu cục bộ, nêu bật các import SDK dành riêng chéo chủ sở hữu, và tóm tắt cầu nối SDK memory-host riêng tư để việc dọn dẹp tương thích luôn rõ ràng thay vì dựa vào các tìm kiếm ad hoc. Các subpath SDK dành riêng phải có usage của chủ sở hữu được theo dõi; các helper export dành riêng không dùng nên được gỡ khỏi SDK công khai.

Nếu một trường manifest vẫn được chấp nhận, tác giả Plugin có thể tiếp tục dùng nó cho đến khi tài liệu và chẩn đoán nói khác. Code mới nên ưu tiên phần thay thế đã ghi tài liệu, nhưng các Plugin hiện có không nên bị hỏng trong các bản phát hành minor thông thường.

Cách di chuyển

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  allowShellFallback: true,});

grep -r "plugin-sdk/compat" my-plugin/grep -r "plugin-sdk/infra-runtime" my-plugin/grep -r "plugin-sdk/config-runtime" my-plugin/grep -r "openclaw/extension-api" my-plugin/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)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";

// Before (deprecated extension-api bridge)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Tham chiếu đường dẫn import

Bảng này cố ý chỉ là tập con di trú chung, không phải toàn bộ bề mặt SDK. Danh mục entrypoint của trình biên dịch nằm trong scripts/lib/plugin-sdk-entrypoints.json; các export của gói được tạo từ tập con công khai.

Các seam trợ giúp dành riêng cho Plugin đóng gói kèm đã được loại khỏi export map SDK công khai, ngoại trừ các facade tương thích được ghi rõ trong tài liệu, chẳng hạn shim plugin-sdk/discord đã ngừng khuyến nghị nhưng vẫn giữ cho gói @openclaw/discord@2026.3.13 đã phát hành. Các helper dành riêng cho owner nằm trong gói Plugin sở hữu chúng; hành vi host dùng chung nên đi qua các hợp đồng SDK chung như plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, và plugin-sdk/plugin-config-runtime.

Hãy dùng import hẹp nhất phù hợp với tác vụ. Nếu bạn không tìm thấy export, hãy kiểm tra nguồn tại src/plugin-sdk/ hoặc hỏi maintainer hợp đồng chung nào nên sở hữu nó.

Các mục ngừng hỗ trợ đang áp dụng

Các mục ngừng hỗ trợ hẹp hơn áp dụng trên SDK Plugin, hợp đồng provider, bề mặt runtime, và manifest. Mỗi mục vẫn hoạt động hôm nay nhưng sẽ bị loại bỏ trong một bản phát hành major trong tương lai. Dòng bên dưới mỗi mục ánh xạ API cũ sang phần thay thế chuẩn của nó.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

Lộ trình loại bỏ

Tất cả Plugin lõi đã được di chuyển. 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 thực hiện di chuyển:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Đây là lối thoát tạm thời, không phải giải pháp lâu dài.

Liên quan

• Bắt đầu - xây dựng Plugin đầu tiên của bạn
• Tổng quan SDK - tham chiếu đầy đủ về import đường dẫn con
• Plugin kênh - xây dựng Plugin kênh
• Plugin nhà cung cấp - xây dựng Plugin nhà cung cấp
• Nội bộ Plugin - tìm hiểu sâu về kiến trúc
• Tệp kê khai Plugin - tham chiếu schema tệp kê khai