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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

• 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 และเสียงเรียลไทม์

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 ทั้งหมด

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

​

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

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

​

วิธีการย้าย

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

​

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

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

​

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

​

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

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

​

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

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