Migrasi SDK Plugin

​

Yang berubah

• openclaw/plugin-sdk dan openclaw/plugin-sdk/compat - mengekspor ulang puluhan helper selama SDK terfokus sedang dibangun. Kedua root tersebut kini telah dihapus; gunakan subpath terdokumentasi sebagai gantinya.
• openclaw/plugin-sdk/infra-runtime - barrel luas yang mencampurkan event sistem, status heartbeat, antrean pengiriman, helper fetch/proxy, helper file, tipe persetujuan, dan utilitas yang tidak terkait.
• openclaw/plugin-sdk/config-runtime - barrel konfigurasi luas yang dipertahankan hanya untuk jendela kompatibilitas berikutnya; helper langsung untuk memuat/menulis saat runtime telah dihapus.
• openclaw/extension-api - bridge yang telah dihapus dan memberi plugin akses langsung ke helper sisi host seperti runner agen tertanam.
• api.registerEmbeddedExtensionFactory(...) - hook khusus runner tertanam yang telah dihapus dan mengamati event runner tertanam seperti tool_result. Gunakan middleware hasil alat agen sebagai gantinya (lihat Migrasikan ekstensi hasil alat tertanam ke middleware).

​

Alasannya

• Startup lambat - mengimpor satu helper memuat puluhan modul yang tidak terkait.
• Dependensi melingkar - ekspor ulang yang luas memudahkan terbentuknya siklus impor.
• Permukaan API yang tidak jelas - tidak ada cara untuk membedakan ekspor stabil dari ekspor internal.

• Anthropic menyimpan helper stream khusus Claude di seam api.ts / contract-api.ts miliknya sendiri.
• OpenAI menyimpan builder provider, helper model default, dan builder provider realtime di api.ts miliknya sendiri.
• OpenRouter menyimpan builder provider serta helper onboarding/konfigurasi di api.ts miliknya sendiri.

​

Kebijakan kompatibilitas

1. Tambahkan kontrak baru.
2. Pertahankan perilaku lama yang terhubung melalui adaptor kompatibilitas.
3. Keluarkan diagnostik atau peringatan yang menyebutkan path lama dan penggantinya.
4. Cakup kedua path dalam pengujian.
5. Dokumentasikan penghentian dan jalur migrasinya.
6. Hapus hanya setelah jendela migrasi yang diumumkan, biasanya dalam rilis mayor.

​

Cara melakukan migrasi

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

// Alat runtime OpenClaw dan alat dinamis runtime Codex (hasil dapat
// ditransformasi). Hasil alat native Codex juga diteruskan untuk pengamatan,
// tetapi output yang ditransformasi tidak pernah mencapai model: kontrak hook
// PostToolUse Codex tidak dapat menggantikan respons alat native.
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

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

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

// Sesudah
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Tetapkan ini hanya untuk pemanggil kompatibilitas tepercaya yang secara sengaja
  // menerima fallback yang dimediasi shell.
  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/

// Sebelum (lapisan kompatibilitas mundur yang tidak digunakan lagi)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// Setelah (impor terfokus modern)
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";

// Sebelum (jembatan extension-api yang tidak digunakan lagi)
import { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// Setelah (runtime yang diinjeksi)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test my-plugin/

​

Referensi jalur impor

​

Permukaan kompatibilitas yang dihapus

​

Publikasi penyedia API global proses

​

Barrel pengujian privat

​

Referensi migrasi

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

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

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

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

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

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

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

// Sebelumnya
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// Sesudahnya
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Sebelumnya
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// Sesudahnya
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

​

Migrasi Talk dan suara waktu nyata

// API sesi Talk milik Gateway.
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 });

// API sesi penyedia milik klien.
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" });

​

Linimasa penghapusan

​

Menonaktifkan peringatan untuk sementara

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

​

Terkait

• Memulai - buat Plugin pertama Anda
• Ikhtisar SDK - referensi lengkap impor subpath
• Plugin Saluran - membuat Plugin saluran
• Plugin Penyedia - membuat Plugin penyedia
• Internal Plugin - pembahasan mendalam tentang arsitektur
• Manifes Plugin - referensi skema manifes