Di chuyển Plugin SDK

​

Những gì đang thay đổi

• 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.

​

Vì sao thay đổi này được thực hiệ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ộ

• 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

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.

// 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" });

​

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

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

​

Cách di chuyển

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

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

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "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 { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

​

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

​

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

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

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

// Before
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// After
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Before
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// After
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

{
  "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 loại bỏ

​

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

​

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