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 tập trung, có tài liệu rõ ràng. 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.

Điều gì đang thay đổi

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

• openclaw/plugin-sdk/compat - một import duy nhất tái xuất hàng chục trình trợ giúp. Nó được giới thiệu để giữ cho các Plugin cũ dựa trên hook 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 trình trợ giúp 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, trình trợ giúp fetch/proxy, trình trợ giúp 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 trình trợ giúp load/write trực tiếp đã bị loại bỏ 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 trình trợ giúp phía host như trình chạy agent nhúng.
• api.registerEmbeddedExtensionFactory(...) - một hook extension đóng gói chỉ dành cho Pi đã bị gỡ 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ị loại bỏ. 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 lớn tiếp theo gỡ bỏ chúng. API đăng ký embedded extension factory chỉ dành cho Pi đã bị gỡ bỏ; hãy dùng middleware kết quả công cụ thay thế.

OpenClaw không gỡ bỏ hoặc diễn giải lại hành vi Plugin đã được tài liệu hóa trong cùng thay đổi giới thiệu phần thay thế. Các thay đổi phá vỡ hợp đồng trước hết phải đi qua adapter tương thích, chẩn đoán, tài liệu và giai đoạn loại bỏ. Đ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 trình trợ giúp đã load hàng chục mô-đun không liên quan
• Phụ thuộc vòng - các tái xuất 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 tài liệu hóa.

Các seam tiện ích provider cũ cho các kênh đóng gói sẵn cũng đã bị gỡ bỏ. Các seam trình trợ giúp mang thương hiệu kênh là lối tắt riêng trong 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 đóng gói sẵn, giữ các trình trợ giúp do provider sở hữu trong api.ts hoặc runtime-api.ts của chính Plugin đó.

Ví dụ provider đóng gói sẵn hiện tại:

• Anthropic giữ các trình trợ giúp stream dành riêng cho Claude trong seam api.ts / contract-api.ts của chính nó
• OpenAI giữ các provider builder, trình trợ giúp mô hình mặc định và realtime provider builder trong api.ts của chính nó
• OpenRouter giữ provider builder và trình trợ giúp onboarding/cấu hình trong chính api.ts của 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 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 phong bì sự kiện Talk chung, trạng thái lượt đang hoạt động, trạng thái capture, trạng thái âm thanh đầu ra, 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 phiên realtime đặc thù của vendor; Plugin bề mặt nên tiếp tục sở hữu capture, phát lại, điện thoại và các đặc thù cuộc họp.

Đợt di chuyển Talk này có chủ ý làm sạch bằng thay đổi phá vỡ:

1. Giữ các primitive runtime/bộ điều khiển dùng chung trong plugin-sdk/realtime-voice.
2. Chuyển các bề mặt đóng gói sẵn sang bộ điều khiển dùng chung: relay trình duyệt, handoff phòng được quản lý, realtime cuộc gọi thoại, STT streaming cuộc gọi thoại, Google Meet realtime và native push-to-talk.
3. Thay thế 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 trực tiếp trong Gateway hello-ok.features.events: talk.event.
5. Xóa endpoint HTTP realtime cũ và mọi đường dẫn ghi đè hướng dẫn theo thời điểm yêu cầu.

Mã mới không nên gọi trực tiếp createTalkEventSequencer(...) trừ khi nó đang triển khai adapter cấp thấp hoặc fixture kiểm thử. Ưu tiên bộ điều khiển dùng chung để các sự kiện theo phạm vi lượt không thể được phát ra khi không có id lượt, 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 vòng đời âm thanh đầu ra luôn nhất quán trên điện thoại, cuộc họp, relay trình duyệt, handoff phòng được quản lý 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 });

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 việc thương lượng provider và truyền tải media trong khi Gateway sở hữu thông tin xác thực, hướng dẫn và chính sách công cụ. talk.session.* là bề mặt chung do Gateway quản lý cho các phiên realtime gateway-relay, phiên phiên âm gateway-relay và phiên STT/TTS native của phòng được quản lý.

Các cấu hình cũ đặ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ản đồ phương thức đã gỡ 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 việc này. Core sở hữu ngữ nghĩa phiên Talk. Các plugin nhà cung cấp sở hữu việc thiết lập phiên của vendor. Voice-call và Google Meet sở hữu các adapter điện thoại/cuộc họp. Trình duyệt và ứng dụng native sở hữu UX thu/phát thiết bị.

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

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

1. thêm contract mới
2. giữ hành vi cũ được nối qua một adapter tương thích
3. phát ra diagnostic 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 trú
6. chỉ gỡ bỏ sau cửa sổ di trú đã công bố, thường trong một bản phát hành major

Maintainer có thể kiểm tra hàng đợi di trú hiện tại bằng pnpm plugins:boundary-report. Dùng pnpm plugins:boundary-report:summary để có số đếm gọn, --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 trên các bản ghi tương thích đã đến hạn, import SDK dự trữ xuyên chủ sở hữu, hoặc các subpath SDK dự trữ 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 tham chiếu mã/tài liệu cục bộ, hiển thị các import SDK dự trữ xuyên 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 tường minh thay vì dựa vào các tìm kiếm ad hoc. Các subpath SDK dự trữ phải có mức sử dụng của chủ sở hữu được theo dõi; các export helper dự trữ 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à diagnostic nói khác. Mã mới nên ưu tiên phần thay thế đã được 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 trú

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

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ 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 chuyển 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; package exports được tạo từ tập con công khai.

Các seam trợ giúp Plugin đi kèm đã dành riêng đã được loại khỏi export map SDK công khai, ngoại trừ các facade tương thích được ghi tài liệu rõ ràng như shim plugin-sdk/discord đã lỗi thời nhưng được giữ lại cho gói đã phát hành @openclaw/[email protected]. Các helper dành riêng cho chủ sở hữu nằm bên 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 khớp với công việc. Nếu bạn không tìm thấy một export, hãy kiểm tra mã 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 hoạt động

Các mục ngừng hỗ trợ hẹp hơn áp dụng trên toàn bộ 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ị gỡ 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";

{  "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ịch trình gỡ 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 major tiếp theo.

Tạm thời chặn các 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 import subpath đầy đủ
• Plugin kênh - xây dựng Plugin kênh
• Plugin provider - xây dựng Plugin provider
• Nội bộ Plugin - đào sâu kiến trúc
• Manifest Plugin - tham chiếu schema manifest