Di chuyển Plugin SDK

OpenClaw đã chuyển từ mộ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 tập trung và có 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 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ứ 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 tải/ghi trực tiếp đã bị phản đối trong cửa sổ di chuyển.
• openclaw/extension-api - một cầu nối cho 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 extension đóng gói chỉ dành cho Pi đã bị loại bỏ, 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ị phản đối. Chúng vẫn hoạt động lúc runtime, nhưng plugin mới không được dùng chúng, và plugin hiện có nên di chuyển trước khi bản phát hành lớn tiếp theo loại bỏ chúng. API đăng ký embedded extension factory chỉ dành cho Pi đã 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 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 tiên phải đi qua adapter tương thích, chẩn đoán, tài liệu và cửa sổ phản đối. Điều đó áp dụng cho các 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 sẽ tải 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 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 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 kế thừa cho các kênh đóng gói cũng đã bị loại bỏ. Các seam helper gắn thương hiệu kênh là lối tắt mono-repo riêng tư, 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 không gian làm việc plugin đóng gói, hãy 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 đóng gói 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ữ các provider builder, helper mô hình mặc định và realtime provider builder trong api.ts của riêng nó
• OpenRouter giữ provider builder và helper onboarding/cấu hình 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 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 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à loại bỏ lượt đã cũ. Plugin provider nên tiếp tục sở hữu các phiên realtime dành riêng cho 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 khác biệt riêng của cuộc họp.

Quá trình di chuyển Talk này cố ý phá vỡ sạch:

1. Giữ các primitive controller/runtime dùng chung trong plugin-sdk/realtime-voice.
2. Chuyển các bề mặt đóng gói sang bộ điều khiển 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 talk.session.* và talk.client.* cuối cùng.
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 override chỉ dẫn tại 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 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ời gọi turnEnd / turnCancel đã cũ không thể xóa một lượt 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, 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 });
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 quá trình đàm phán provider và transport media, trong khi Gateway sở hữu thông tin xác thực, chỉ 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, transcription gateway-relay và STT/TTS native managed-room.

Các cấu hình kế thừa đặt selector realtime bên 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 đã loại bỏ:

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

Không giới thiệu các trường hợp đặc biệt theo provider hoặc nền tảng trong core để làm việc này hoạt động. Core sở hữu ngữ nghĩa phiên Talk. Plugin provider sở hữu thiết lập phiên vendor. Voice-call và Google Meet sở hữu adapter điện thoại/cuộc họp. Trình duyệt và ứng dụng native sở hữu UX capture/phát lại 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 theo thứ tự này:

1. thêm hợp đồng mới
2. giữ hành vi cũ được nối qua 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. tài liệu hóa việc phản đối và đường dẫn di chuyển
6. chỉ loại bỏ sau cửa sổ di chuyển đã công bố, thường trong một bản phát hành lớn

Người bảo trì 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 để xem số liệu thu 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 cổng CI cần thất bại trên các bản ghi tương thích đã đến hạn, các import SDK dành riêng xuyên chủ sở hữu, hoặc các đường dẫn con SDK dành riêng không dùng đến. Báo cáo nhóm các bản ghi tương thích đã ngừng khuyến nghị theo ngày gỡ bỏ, đếm các tham chiếu mã/tài liệu cục bộ, hiển thị các import SDK dành riêng 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 rõ ràng thay vì dựa vào các tìm kiếm tùy biến. Các đường dẫn con SDK dành riêng phải có mức sử dụng theo chủ sở hữu được theo dõi; các export helper dành riêng không dùng đến 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 trường đó cho đến khi tài liệu và chẩn đoán 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 tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 build
pnpm 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 sách đầy đủ hơn 200 entrypoint nằm trong scripts/lib/plugin-sdk-entrypoints.json.

Các seam trợ giúp dành riêng cho Plugin đi kèm đã được loại bỏ 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 vẫn được giữ lại cho gói đã phát hành @openclaw/[email protected]. Helper theo từng chủ sở hữu nằm bên trong gói Plugin sở hữu nó; 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.

Dùng import hẹp nhất phù hợp với công việc. 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 maintainers hợp đồng chung nào nên sở hữu nó.

# Các mục ngừng dùng đang hoạt động

Các mục ngừng dùng hẹp hơn áp dụng trên toà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ị 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ế chính thức.

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

# Lộ trình gỡ bỏ

Tất cả Plugin lõi đã được di trú. Plugin bên ngoài nên di trú trước bản phát hành major 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 di trú:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_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 - tài liệu tham khảo 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 - phân tích sâu kiến trúc
• Manifest Plugin - tài liệu tham khảo schema manifest