การย้าย Plugin SDK

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

การย้าย Talk นี้ตั้งใจให้ตัดของเก่าอย่างสะอาด:

1. เก็บ controller/runtime primitives ร่วมไว้ใน plugin-sdk/realtime-voice
2. ย้ายพื้นผิว bundled ไปใช้ 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. ประกาศช่องเหตุการณ์ Talk แบบ live หนึ่งช่องใน Gateway hello-ok.features.events: talk.event
5. ลบ endpoint HTTP เรียลไทม์เก่าและ path override คำสั่งขณะมีคำขอทั้งหมด

โค้ดใหม่ไม่ควรเรียก createTalkEventSequencer(...) โดยตรง เว้นแต่กำลัง สร้าง adapter ระดับล่างหรือ test fixture ให้เลือกใช้ controller ร่วม เพื่อให้เหตุการณ์ที่อยู่ในขอบเขต turn ไม่สามารถถูกปล่อยโดยไม่มี turn id, การเรียก turnEnd / turnCancel ที่หมดอายุไม่สามารถล้าง turn ที่ใหม่กว่าและทำงานอยู่ได้ และเหตุการณ์ 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" });

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

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

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

แผนที่เมธอดที่ถูกลบ:

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

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

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

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

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

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

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

วิธีการย้าย

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

// 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 buildpnpm test -- my-plugin/

อ้างอิงพาธอิมพอร์ต

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

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

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

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

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

// 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 - เอกสารอ้างอิงการนำเข้าพาธย่อยทั้งหมด
• Plugin ช่องทาง - การสร้าง Plugin ช่องทาง
• Plugin ผู้ให้บริการ - การสร้าง Plugin ผู้ให้บริการ
• ภายในของ Plugin - เจาะลึกสถาปัตยกรรม
• ไฟล์กำกับ Plugin - เอกสารอ้างอิงสคีมาไฟล์กำกับ