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

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

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

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

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

พื้นผิว import แบบกว้างเหล่านี้ตอนนี้ เลิกใช้แล้ว ยังทำงานได้ที่ runtime แต่ Plugin ใหม่ต้องไม่ใช้ และ Plugin ที่มีอยู่ควรย้ายออกก่อน release major ถัดไปจะนำออก API สำหรับลงทะเบียน embedded extension factory เฉพาะ Pi ถูกนำออกแล้ว; ให้ใช้ tool-result middleware แทน

OpenClaw จะไม่ลบหรือตีความพฤติกรรม Plugin ที่มีเอกสารกำกับใหม่ใน change เดียวกับ ที่เพิ่มสิ่งทดแทน การเปลี่ยนแปลง contract ที่ทำให้ใช้งานร่วมกันไม่ได้ต้องผ่าน compatibility adapter, diagnostics, เอกสาร และช่วง deprecation ก่อน หลักการนี้ใช้กับ SDK imports, manifest fields, setup APIs, hooks และพฤติกรรม การลงทะเบียน runtime

เหตุผลที่เปลี่ยนแปลง

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

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

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

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

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

• Anthropic เก็บตัวช่วย stream เฉพาะ Claude ไว้ใน seam api.ts / contract-api.ts ของตัวเอง
• OpenAI เก็บ provider builders, ตัวช่วย default-model และ realtime provider builders ไว้ใน api.ts ของตัวเอง
• OpenRouter เก็บ provider builder และตัวช่วย onboarding/config ไว้ใน api.ts ของตัวเอง

แผน migration สำหรับ Talk และเสียงเรียลไทม์

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

migration ของ Talk นี้ตั้งใจให้เป็นการเปลี่ยนแบบ breaking-clean:

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

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

รูปทรง 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 });

session ของ WebRTC/provider-websocket ที่เบราว์เซอร์เป็นเจ้าของใช้ talk.client.create เพราะเบราว์เซอร์เป็นเจ้าของการ negotiate กับ provider และ media transport ขณะที่ Gateway เป็นเจ้าของ credentials, instructions และ tool policy talk.session.* เป็น surface ร่วมที่ Gateway จัดการสำหรับ gateway-relay realtime, gateway-relay transcription และ session STT/TTS แบบ native ของ managed-room

config รุ่นเก่าที่วาง realtime selectors ไว้ข้าง talk.provider / talk.providers ควรถูกซ่อมด้วย openclaw doctor --fix; runtime Talk จะไม่ตีความ config provider ของ speech/TTS เป็น config provider ของ realtime

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

แผนที่ method ที่ถูกนำออก:

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

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

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

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

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

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

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

วิธีการย้าย

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/

ข้อมูลอ้างอิงเส้นทาง import

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

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

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

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

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

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

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

Plugin core ทั้งหมดถูกย้ายแล้ว Plugin ภายนอกควรย้ายก่อน major release ถัดไป

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

ตั้ง environment variables เหล่านี้ขณะทำงานย้าย:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

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

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