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

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

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

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

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

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

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

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

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

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

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

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

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

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

# แผน migration สำหรับ Talk และเสียง realtime

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

migration ของ Talk นี้ตั้งใจให้ breaking-clean:

1. เก็บ controller/runtime primitive ร่วมไว้ใน 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. ประกาศ channel event สดของ Talk หนึ่งรายการใน Gateway hello-ok.features.events: talk.event
5. ลบ endpoint HTTP realtime เดิมและ path ใดๆ สำหรับ request-time instruction override

โค้ดใหม่ไม่ควรเรียก createTalkEventSequencer(...) โดยตรง เว้นแต่กำลัง implement adapter ระดับต่ำหรือ test fixture ให้ใช้ controller ร่วมเป็นหลัก เพื่อให้ event ที่ผูกกับ turn ไม่สามารถถูก emit โดยไม่มี turn id, การเรียก stale turnEnd / turnCancel ไม่สามารถล้าง active turn ที่ใหม่กว่าได้ และ event lifecycle ของ output-audio สอดคล้องกันใน telephony, meetings, 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 });
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 ที่ browser เป็นเจ้าของใช้ talk.client.create เพราะ browser เป็นเจ้าของการเจรจากับ provider และ media transport ขณะที่ Gateway เป็นเจ้าของ credentials, instructions และ tool policy talk.session.* คือ พื้นผิวร่วมที่ Gateway จัดการสำหรับ gateway-relay realtime, gateway-relay transcription และ session native STT/TTS ของ managed-room

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

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

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

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

อย่าเพิ่ม special case เฉพาะ provider หรือ platform ใน core เพื่อทำให้สิ่งนี้ทำงาน Core เป็นเจ้าของ semantics ของ Talk session Plugin ของ provider เป็นเจ้าของการตั้งค่า session ของ vendor Voice-call และ Google Meet เป็นเจ้าของ adapter สำหรับ telephony/meeting Browser และ native app เป็นเจ้าของ UX สำหรับ device capture/playback

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

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

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

Maintainers can audit the current migration queue with pnpm plugins:boundary-report. Use pnpm plugins:boundary-report:summary for compact counts, --owner <id> for one plugin or compatibility owner, and pnpm plugins:boundary-report:ci when a CI gate should fail on due compatibility records, cross-owner reserved SDK imports, or unused reserved SDK subpaths. The report groups deprecated compatibility records by removal date, counts local code/docs references, surfaces cross-owner reserved SDK imports, and summarizes the private memory-host SDK bridge so compatibility cleanup stays explicit instead of relying on ad hoc searches. Reserved SDK subpaths must have tracked owner usage; unused reserved helper exports should be removed from the public SDK.

If a manifest field is still accepted, plugin authors can keep using it until the docs and diagnostics say otherwise. New code should prefer the documented replacement, but existing plugins should not break during ordinary minor releases.

# How to migrate

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

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

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

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

pnpm build
pnpm test -- my-plugin/

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

ตารางนี้ตั้งใจให้เป็นชุดย่อยการย้ายระบบที่ใช้ร่วมกัน ไม่ใช่พื้นผิว SDK ทั้งหมด รายการ entrypoint ทั้งหมดกว่า 200 รายการอยู่ใน scripts/lib/plugin-sdk-entrypoints.json

seam ตัวช่วยของ bundled-plugin ที่สงวนไว้ถูกเลิกใช้จาก export map ของ SDK สาธารณะแล้ว ยกเว้น facade ความเข้ากันได้ที่มีเอกสารกำกับไว้อย่างชัดเจน เช่น shim plugin-sdk/discord ที่เลิกใช้แล้วแต่ยังคงไว้สำหรับแพ็กเกจ @openclaw/[email protected] ที่เผยแพร่แล้ว ตัวช่วยเฉพาะเจ้าของอยู่ภายในแพ็กเกจ 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 เดิมกับ ตัวแทนที่เป็น canonical

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

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

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

# ไทม์ไลน์การนำออก

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

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

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

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

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

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

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