การย้ายไปใช้ Plugin SDK

OpenClaw ได้ย้ายจากเลเยอร์ความเข้ากันได้ย้อนหลังแบบกว้าง ไปสู่สถาปัตยกรรม Plugin สมัยใหม่ที่มีการนำเข้าแบบเจาะจงและมีเอกสารกำกับ หาก Plugin ของคุณถูกสร้างก่อน สถาปัตยกรรมใหม่ คู่มือนี้จะช่วยคุณย้ายระบบ

สิ่งที่กำลังเปลี่ยนแปลง

ระบบ Plugin เดิมมีพื้นผิวแบบเปิดกว้างสองส่วนที่ให้ Plugin นำเข้า ทุกอย่างที่ต้องใช้ได้จากจุดเข้าถึงเดียว:

• openclaw/plugin-sdk/compat - การนำเข้าเดียวที่ส่งออกตัวช่วยซ้ำหลายสิบรายการ ถูกเพิ่มเข้ามาเพื่อให้ Plugin รุ่นเก่าที่อิง hook ยังทำงานได้ระหว่างที่ สถาปัตยกรรม Plugin ใหม่กำลังถูกสร้าง
• openclaw/plugin-sdk/infra-runtime - barrel ตัวช่วยรันไทม์แบบกว้างที่ ผสมเหตุการณ์ระบบ สถานะ Heartbeat คิวการส่งมอบ ตัวช่วย fetch/proxy ตัวช่วยไฟล์ ชนิด approval และยูทิลิตีที่ไม่เกี่ยวข้องกัน
• openclaw/plugin-sdk/config-runtime - barrel ความเข้ากันได้ของคอนฟิกแบบกว้าง ที่ยังคงพกตัวช่วย load/write โดยตรงที่เลิกแนะนำแล้วในช่วงหน้าต่างการย้ายระบบ
• openclaw/extension-api - สะพานที่ให้ Plugin เข้าถึงตัวช่วยฝั่งโฮสต์โดยตรง เช่น agent runner แบบฝัง
• api.registerEmbeddedExtensionFactory(...) - hook ส่วนขยายแบบ bundled สำหรับ embedded-runner เท่านั้นที่ถูกลบแล้ว ซึ่งเคยสังเกตเหตุการณ์ของ embedded-runner เช่น tool_result

พื้นผิวการนำเข้าแบบกว้างตอนนี้ถูกเลิกแนะนำแล้ว พื้นผิวเหล่านี้ยังทำงานได้ในรันไทม์ แต่ Plugin ใหม่ต้องไม่ใช้ และ Plugin ที่มีอยู่ควรย้ายระบบก่อน รุ่น major ถัดไปที่จะลบพื้นผิวเหล่านี้ออก API การลงทะเบียน extension factory สำหรับ embedded-runner เท่านั้นถูกลบแล้ว ให้ใช้ middleware ของผลลัพธ์เครื่องมือแทน

OpenClaw จะไม่ลบหรือตีความพฤติกรรม Plugin ที่มีเอกสารกำกับใหม่ใน การเปลี่ยนแปลงเดียวกับที่เพิ่มสิ่งทดแทน การเปลี่ยนแปลงสัญญาที่ทำให้แตกหักต้องผ่าน adapter ความเข้ากันได้ การวินิจฉัย เอกสาร และหน้าต่างการเลิกใช้งานก่อน ข้อกำหนดนี้ใช้กับการนำเข้า SDK, ฟิลด์ manifest, API การตั้งค่า, hook และพฤติกรรม การลงทะเบียนในรันไทม์

เหตุผลของการเปลี่ยนแปลงนี้

แนวทางเดิมก่อให้เกิดปัญหา:

• การเริ่มต้นช้า - การนำเข้าตัวช่วยหนึ่งตัวโหลดโมดูลที่ไม่เกี่ยวข้องหลายสิบรายการ
• การพึ่งพาแบบวนรอบ - การส่งออกซ้ำแบบกว้างทำให้สร้างวงจรการนำเข้าได้ง่าย
• พื้นผิว API ไม่ชัดเจน - ไม่มีวิธีบอกว่า export ใดเสถียรและ export ใดเป็นภายใน

SDK ของ Plugin สมัยใหม่แก้ปัญหานี้: แต่ละพาธนำเข้า (openclaw/plugin-sdk/\<subpath\>) เป็นโมดูลขนาดเล็กที่เป็นเอกเทศ มีวัตถุประสงค์ชัดเจนและมีสัญญาที่มีเอกสารกำกับ

seam อำนวยความสะดวกของ provider รุ่นเก่าสำหรับช่องทาง bundled ก็ถูกลบแล้วเช่นกัน seam ตัวช่วยที่ผูกกับแบรนด์ช่องทางเป็นทางลัดส่วนตัวใน mono-repo ไม่ใช่ สัญญา Plugin ที่เสถียร ให้ใช้ subpath ของ SDK แบบทั่วไปที่แคบแทน ภายใน workspace ของ Plugin แบบ bundled ให้เก็บตัวช่วยที่ provider เป็นเจ้าของไว้ใน api.ts หรือ runtime-api.ts ของ Plugin นั้นเอง

ตัวอย่าง provider แบบ bundled ปัจจุบัน:

• Anthropic เก็บตัวช่วยสตรีมเฉพาะ Claude ไว้ใน seam api.ts / contract-api.ts ของตนเอง
• OpenAI เก็บ provider builder, ตัวช่วยโมเดลเริ่มต้น และ realtime provider builder ไว้ใน api.ts ของตนเอง
• OpenRouter เก็บ provider builder และตัวช่วย onboarding/config ไว้ใน api.ts ของตนเอง

แผนการย้าย Talk และเสียงเรียลไทม์

โค้ดเสียงเรียลไทม์ โทรศัพท์ การประชุม และ Talk บนเบราว์เซอร์กำลังย้ายจาก การจดบันทึก turn เฉพาะแต่ละพื้นผิว ไปยังตัวควบคุม session ของ Talk แบบใช้ร่วมกันที่ส่งออกโดย openclaw/plugin-sdk/realtime-voice ตัวควบคุมใหม่เป็นเจ้าของ envelope เหตุการณ์ Talk ร่วมกัน สถานะ turn ที่ active สถานะ capture สถานะ output-audio ประวัติเหตุการณ์ล่าสุด และการปฏิเสธ stale-turn Plugin provider ควรยังคงเป็นเจ้าของ session เรียลไทม์ เฉพาะผู้ขาย ส่วน Plugin พื้นผิวควรยังคงเป็นเจ้าของ capture, playback, telephony และความเฉพาะตัวของการประชุม

การย้าย Talk นี้ตั้งใจให้เป็นการล้างที่ทำให้แตกหักอย่างชัดเจน:

1. เก็บ primitive ของตัวควบคุม/รันไทม์ที่ใช้ร่วมกันไว้ใน plugin-sdk/realtime-voice
2. ย้ายพื้นผิว bundled ไปยังตัวควบคุมที่ใช้ร่วมกัน: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime และ native push-to-talk
3. แทนที่ตระกูล RPC Talk เดิมด้วย API สุดท้าย talk.session.* และ talk.client.*
4. ประกาศช่องเหตุการณ์ Talk แบบ live หนึ่งช่องใน Gateway hello-ok.features.events: talk.event
5. ลบ endpoint HTTP เรียลไทม์เดิมและพาธ override คำสั่งขณะรับคำขอทั้งหมด

โค้ดใหม่ไม่ควรเรียก createTalkEventSequencer(...) โดยตรง เว้นแต่ว่าโค้ดนั้น กำลังทำ adapter ระดับต่ำหรือ fixture ทดสอบ ให้ใช้ตัวควบคุมที่ใช้ร่วมกันแทน เพื่อไม่ให้เหตุการณ์ที่ผูกกับ turn ถูกส่งออกโดยไม่มี turn id, เพื่อไม่ให้การเรียก turnEnd / turnCancel ที่ล้าสมัยล้าง turn ที่ active ใหม่กว่าได้ และเพื่อให้เหตุการณ์ lifecycle ของ output-audio สอดคล้องกันในโทรศัพท์ การประชุม browser relay, managed-room handoff และไคลเอนต์ Talk แบบ native

รูปทรง API สาธารณะเป้าหมายคือ:

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

session WebRTC/provider-websocket ที่เบราว์เซอร์เป็นเจ้าของใช้ talk.client.create เพราะเบราว์เซอร์เป็นเจ้าของการเจรจากับ provider และการขนส่งสื่อ ในขณะที่ Gateway เป็นเจ้าของ credential, คำสั่ง และนโยบายเครื่องมือ talk.session.* คือ พื้นผิวร่วมที่ Gateway จัดการสำหรับ gateway-relay realtime, gateway-relay transcription และ session STT/TTS แบบ native ของ managed-room

คอนฟิกรุ่นเก่าที่วางตัวเลือกเรียลไทม์ไว้ข้าง talk.provider / talk.providers ควรถูกซ่อมด้วย openclaw doctor --fix; Talk ในรันไทม์ จะไม่ตีความคอนฟิก provider speech/TTS เป็นคอนฟิก provider เรียลไทม์ใหม่

ชุดค่าผสม talk.session.create ที่รองรับตั้งใจให้มีขนาดเล็ก:

แผนที่ method ที่ถูกลบ:

คำศัพท์ควบคุมแบบรวมศูนย์ยังตั้งใจให้แคบเช่นกัน:

อย่าเพิ่มกรณีพิเศษของผู้ให้บริการหรือแพลตฟอร์มใน core เพื่อให้สิ่งนี้ทำงานได้ Core เป็นเจ้าของความหมายของเซสชัน Talk ส่วน Plugin ผู้ให้บริการเป็นเจ้าของการตั้งค่าเซสชันของผู้ขาย Voice-call และ Google Meet เป็นเจ้าของอะแดปเตอร์โทรศัพท์/การประชุม ส่วนเบราว์เซอร์และแอป native เป็นเจ้าของ UX การจับเสียง/เล่นเสียงของอุปกรณ์

นโยบายความเข้ากันได้

สำหรับ Plugin ภายนอก งานด้านความเข้ากันได้ทำตามลำดับนี้:

1. เพิ่มสัญญาใหม่
2. คงพฤติกรรมเดิมไว้โดยเชื่อมผ่านอะแดปเตอร์ความเข้ากันได้
3. ส่ง diagnostic หรือคำเตือนที่ระบุพาธเดิมและตัวแทนที่ใช้แทน
4. ครอบคลุมทั้งสองพาธในเทสต์
5. จัดทำเอกสารการเลิกใช้และพาธการย้าย
6. ลบเฉพาะหลังจากช่วงเวลาการย้ายที่ประกาศไว้ ซึ่งมักอยู่ในรีลีส major

ผู้ดูแลสามารถ audit คิวการย้ายปัจจุบันได้ด้วย pnpm plugins:boundary-report ใช้ pnpm plugins:boundary-report:summary สำหรับ จำนวนแบบกะทัดรัด, --owner <id> สำหรับ Plugin เดียวหรือเจ้าของความเข้ากันได้หนึ่งราย และ pnpm plugins:boundary-report:ci เมื่อ gate ของ CI ควรล้มเหลวจากระเบียน ความเข้ากันได้ที่ครบกำหนด, การนำเข้า SDK แบบ reserved ข้ามเจ้าของ หรือ subpath ของ SDK แบบ reserved ที่ไม่ได้ใช้ รายงานจะจัดกลุ่มระเบียน ความเข้ากันได้ที่เลิกใช้แล้วตามวันที่ลบ, นับการอ้างอิงในโค้ด/เอกสารภายใน, แสดงการนำเข้า SDK แบบ reserved ข้ามเจ้าของ และสรุป bridge ของ SDK memory-host แบบ private เพื่อให้การ cleanup ความเข้ากันได้ยังคงชัดเจนแทนที่จะ พึ่งพาการค้นหาเฉพาะกิจ subpath ของ SDK แบบ reserved ต้องมีการติดตามการใช้งานตามเจ้าของ; export ของ helper แบบ reserved ที่ไม่ได้ใช้ควรถูกลบออกจาก SDK สาธารณะ

หากฟิลด์ manifest ยังถูกยอมรับอยู่ ผู้เขียน Plugin สามารถใช้ต่อไปได้จนกว่า เอกสารและ diagnostic จะระบุเป็นอย่างอื่น โค้ดใหม่ควรเลือกใช้ตัวแทนที่จัดทำเอกสารไว้ แต่ Plugin ที่มีอยู่ไม่ควรพังระหว่างรีลีส minor ตามปกติ

วิธีการย้าย

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";

// ก่อนหน้า (สะพาน extension-api ที่เลิกใช้แล้ว)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // หลังจากนั้น (runtime ที่ถูกฉีดเข้ามา)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

ข้อมูลอ้างอิงพาธ import

ตารางนี้ตั้งใจให้เป็นชุดย่อยสำหรับการย้ายที่ใช้ร่วมกัน ไม่ใช่พื้นผิว SDK ทั้งหมด รายการ entrypoint ของ compiler อยู่ใน scripts/lib/plugin-sdk-entrypoints.json; package exports ถูกสร้างจาก ชุดย่อยสาธารณะ

seams ตัวช่วยสำหรับ bundled-plugin ที่สงวนไว้ถูกปลดระวางจาก export map ของ SDK สาธารณะแล้ว ยกเว้น facade ความเข้ากันได้ที่มีการบันทึกไว้อย่างชัดเจน เช่น shim plugin-sdk/discord ที่เลิกใช้แล้วซึ่งยังคงไว้สำหรับแพ็กเกจ @openclaw/discord@2026.3.13 ที่เผยแพร่แล้ว ตัวช่วยเฉพาะ owner อยู่ภายใน แพ็กเกจ Plugin ที่เป็นเจ้าของ; พฤติกรรม host ที่ใช้ร่วมกันควรย้ายผ่าน contract SDK ทั่วไป เช่น plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, และ plugin-sdk/plugin-config-runtime

ใช้ import ที่แคบที่สุดซึ่งตรงกับงาน หากหา export ไม่พบ ให้ตรวจสอบซอร์สที่ src/plugin-sdk/ หรือถาม maintainers ว่า contract ทั่วไปใด ควรเป็นเจ้าของสิ่งนั้น

การเลิกใช้งานที่มีผลอยู่

การเลิกใช้งานที่แคบลงซึ่งมีผลทั่วทั้ง plugin SDK, provider contract, runtime surface, และ manifest แต่ละรายการยังใช้งานได้ในวันนี้ แต่จะถูกลบออก ใน major release ในอนาคต รายการใต้แต่ละข้อจะจับคู่ API เดิมกับสิ่งทดแทน ที่เป็น canonical

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

ไทม์ไลน์การลบ

Plugin หลักทั้งหมดได้รับการย้ายแล้ว Plugin ภายนอกควรย้าย ก่อนรุ่นหลักถัดไป

การระงับคำเตือนชั่วคราว

ตั้งค่าตัวแปรสภาพแวดล้อมเหล่านี้ระหว่างที่คุณกำลังย้าย:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

นี่เป็นทางออกชั่วคราว ไม่ใช่วิธีแก้ปัญหาถาวร

ที่เกี่ยวข้อง

• เริ่มต้นใช้งาน - สร้าง Plugin แรกของคุณ
• ภาพรวม SDK - ข้อมูลอ้างอิงการนำเข้า subpath ฉบับเต็ม
• Channel Plugins - การสร้าง channel plugins
• Provider Plugins - การสร้าง provider plugins
• Plugin Internals - เจาะลึกสถาปัตยกรรม
• Plugin Manifest - ข้อมูลอ้างอิงสคีมา manifest