ภาพรวม Plugin SDK

Plugin SDK คือสัญญาแบบมีชนิดข้อมูลระหว่าง Plugin กับแกนหลัก หน้านี้คือ เอกสารอ้างอิงสำหรับ สิ่งที่ต้อง import และ สิ่งที่คุณสามารถลงทะเบียนได้

ข้อตกลงการ import

ให้ import จาก subpath ที่เฉพาะเจาะจงเสมอ:

แต่ละ subpath เป็นโมดูลขนาดเล็กที่อยู่ได้ด้วยตัวเอง วิธีนี้ช่วยให้การเริ่มต้นรวดเร็วและ ป้องกันปัญหา dependency แบบวนซ้ำ สำหรับ helper การเข้าใช้งาน/การสร้างเฉพาะช่องทาง ให้เลือกใช้ openclaw/plugin-sdk/channel-core; เก็บ openclaw/plugin-sdk/core ไว้สำหรับ พื้นผิวรวมที่กว้างกว่าและ helper ที่ใช้ร่วมกัน เช่น buildChannelConfigSchema

สำหรับ config ของช่องทาง ให้เผยแพร่ JSON Schema ที่ช่องทางเป็นเจ้าของผ่าน openclaw.plugin.json#channelConfigs subpath plugin-sdk/channel-config-schema มีไว้สำหรับ primitive ของ schema ที่ใช้ร่วมกันและตัวสร้างทั่วไป Plugin ที่มาพร้อมกับ OpenClaw ใช้ plugin-sdk/bundled-channel-config-schema สำหรับ schema ของช่องทางที่มาพร้อมระบบซึ่งยังคงเก็บไว้ export เพื่อความเข้ากันได้ที่เลิกใช้แล้วยังคงอยู่บน plugin-sdk/channel-config-schema-legacy; subpath schema ที่มาพร้อมระบบทั้งสองไม่ใช่ รูปแบบสำหรับ Plugin ใหม่

เอกสารอ้างอิง subpath

Plugin SDK ถูกเปิดเผยเป็นชุด subpath แบบแคบที่จัดกลุ่มตามพื้นที่ (การเข้าใช้งาน Plugin, ช่องทาง, ผู้ให้บริการ, การยืนยันตัวตน, runtime, ความสามารถ, หน่วยความจำ และ helper ของ Plugin ที่มาพร้อมระบบที่สงวนไว้) สำหรับแค็ตตาล็อกทั้งหมด ซึ่งจัดกลุ่มและลิงก์ไว้แล้ว โปรดดู subpath ของ Plugin SDK

บัญชีรายการ entrypoint ของคอมไพเลอร์อยู่ใน scripts/lib/plugin-sdk-entrypoints.json; package export ถูกสร้างจาก ชุดสาธารณะหลังจากลบ subpath สำหรับทดสอบ/ภายในที่ใช้เฉพาะใน repo ซึ่งระบุไว้ใน scripts/lib/plugin-sdk-private-local-only-subpaths.json เรียกใช้ pnpm plugin-sdk:surface เพื่อตรวจนับจำนวน export สาธารณะ subpath สาธารณะที่เลิกใช้แล้ว ซึ่งเก่าพอและไม่ได้ถูกใช้โดยโค้ด production ของส่วนขยายที่มาพร้อมระบบ จะถูกติดตามใน scripts/lib/plugin-sdk-deprecated-public-subpaths.json; barrel re-export ที่เลิกใช้แล้วแบบกว้างจะถูกติดตามใน scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json

API การลงทะเบียน

callback register(api) ได้รับอ็อบเจ็กต์ OpenClawPluginApi พร้อมเมธอดเหล่านี้:

การลงทะเบียนความสามารถ

เครื่องมือและคำสั่ง

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

โครงสร้างพื้นฐาน

ฮุกโฮสต์สำหรับ Plugin เวิร์กโฟลว์

ฮุกโฮสต์คือ seam ของ SDK สำหรับ Plugin ที่ต้องเข้าร่วมในวงจรชีวิตของโฮสต์ แทนที่จะเพิ่มเพียงผู้ให้บริการ ช่องทาง หรือเครื่องมือเท่านั้น สิ่งเหล่านี้เป็น สัญญาทั่วไป; Plan Mode ใช้งานได้ และเวิร์กโฟลว์การอนุมัติ, ประตูควบคุมนโยบาย workspace, ตัวตรวจสอบเบื้องหลัง, wizard การตั้งค่า และ Plugin คู่ข้าง UI ก็ใช้งานได้เช่นกัน

ใช้ namespace ที่จัดกลุ่มไว้สำหรับโค้ด Plugin ใหม่:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

เมธอดแบบ flat ที่เทียบเท่ากันยังคงใช้งานได้เป็น alias เพื่อความเข้ากันได้ ที่เลิกใช้แล้วสำหรับ Plugin ที่มีอยู่ อย่าเพิ่มโค้ด Plugin ใหม่ที่เรียก api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn, หรือ api.unscheduleSessionTurnsByTag โดยตรง

scheduleSessionTurn(...) เป็นตัวช่วยระดับเซสชันบนตัวจัดกำหนดการ Cron ของ Gateway Cron เป็นเจ้าของเวลาและสร้างเรกคอร์ดงานเบื้องหลังเมื่อ turn ทำงาน ส่วน Plugin SDK เพียงจำกัดเซสชันเป้าหมาย การตั้งชื่อที่ Plugin เป็นเจ้าของ และการล้างข้อมูล ใช้ api.runtime.tasks.managedFlows ภายใน turn ที่ถูกจัดกำหนดการไว้เมื่องานนั้นเองต้องมีสถานะ TaskFlow หลายขั้นตอนที่คงทน

สัญญาแยกอำนาจโดยตั้งใจ:

• Plugin ภายนอกสามารถเป็นเจ้าของส่วนขยายเซสชัน ตัวอธิบาย UI คำสั่ง เมทาดาต้าเครื่องมือ การฉีด next-turn และ hook ปกติ
• นโยบายเครื่องมือที่เชื่อถือได้ทำงานก่อน hook before_tool_call ทั่วไป และเป็น bundled-only เพราะนโยบายเหล่านี้มีส่วนร่วมในนโยบายความปลอดภัยของโฮสต์
• ความเป็นเจ้าของคำสั่งที่สงวนไว้เป็น bundled-only Plugin ภายนอกควรใช้ชื่อคำสั่ง หรือ alias ของตนเอง
• allowPromptInjection=false ปิดใช้งาน hook ที่แก้ไข prompt รวมถึง agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, ฟิลด์ prompt จาก before_agent_start แบบเดิม และ enqueueNextTurnInjection

ตัวอย่างของผู้ใช้ที่ไม่ใช่ Plan:

การลงทะเบียนการค้นพบ Gateway

api.registerGatewayDiscoveryService(...) ช่วยให้ Plugin โฆษณา Gateway ที่ใช้งานอยู่ บนการขนส่งการค้นพบภายในเครื่อง เช่น mDNS/Bonjour OpenClaw เรียกบริการนี้ ระหว่างการเริ่มต้น Gateway เมื่อเปิดใช้การค้นพบภายในเครื่อง ส่งพอร์ต Gateway ปัจจุบันและข้อมูล hint TXT ที่ไม่ใช่ความลับ และเรียก handler stop ที่ส่งคืน ระหว่างการปิด Gateway

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Plugin การค้นพบ Gateway ต้องไม่ถือว่าค่า TXT ที่โฆษณาเป็นความลับหรือ การยืนยันตัวตน การค้นพบเป็นเพียง hint สำหรับการกำหนดเส้นทาง ส่วนความเชื่อถือยังคงอยู่ภายใต้ การยืนยันตัวตนของ Gateway และการ pin TLS

เมทาดาต้าการลงทะเบียน CLI

api.registerCli(registrar, opts?) รับเมทาดาต้าคำสั่งสองประเภท:

• commands: ชื่อคำสั่งแบบชัดเจนที่ registrar เป็นเจ้าของ
• descriptors: ตัวอธิบายคำสั่งในช่วง parse ที่ใช้สำหรับความช่วยเหลือของ CLI การกำหนดเส้นทาง และการลงทะเบียน CLI ของ Plugin แบบ lazy
• parentPath: path คำสั่งแม่แบบไม่บังคับสำหรับกลุ่มคำสั่งซ้อน เช่น ["nodes"]

สำหรับฟีเจอร์ paired-node ควรใช้ api.registerNodeCliFeature(registrar, opts?) ซึ่งเป็น wrapper ขนาดเล็กรอบ api.registerCli(..., { parentPath: ["nodes"] }) และทำให้คำสั่งอย่าง openclaw nodes canvas เป็นฟีเจอร์ node ที่ Plugin เป็นเจ้าของอย่างชัดเจน

หากต้องการให้คำสั่ง Plugin โหลดแบบ lazy ใน path CLI รากปกติ ให้ระบุ descriptors ที่ครอบคลุมรากคำสั่งระดับบนทั้งหมดที่ registrar นั้นเปิดเผย

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

คำสั่งซ้อนจะได้รับคำสั่งแม่ที่ resolve แล้วเป็น program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

ใช้ commands เพียงอย่างเดียวเฉพาะเมื่อไม่ต้องการการลงทะเบียน CLI รากแบบ lazy เส้นทางความเข้ากันได้แบบ eager นั้นยังรองรับอยู่ แต่จะไม่ติดตั้ง placeholder ที่อิง descriptor สำหรับการโหลดแบบ lazy ในช่วง parse

การลงทะเบียนแบ็กเอนด์ CLI

api.registerCliBackend(...) ช่วยให้ Plugin เป็นเจ้าของค่า config เริ่มต้นสำหรับแบ็กเอนด์ AI CLI ภายในเครื่อง เช่น codex-cli

• id ของแบ็กเอนด์จะกลายเป็นคำนำหน้า provider ใน model ref อย่าง codex-cli/gpt-5
• config ของแบ็กเอนด์ใช้รูปทรงเดียวกับ agents.defaults.cliBackends.<id>
• config ของผู้ใช้ยังคงชนะ OpenClaw จะ merge agents.defaults.cliBackends.<id> ทับ ค่าเริ่มต้นของ Plugin ก่อนเรียกใช้ CLI
• ใช้ normalizeConfig เมื่อแบ็กเอนด์ต้องเขียนความเข้ากันได้ใหม่หลัง merge (เช่น normalize รูปทรง flag เก่า)
• ใช้ resolveExecutionArgs สำหรับการเขียน argv ใหม่ตามขอบเขตคำขอที่เป็นของ dialect ของ CLI เช่น การแมประดับ thinking ของ OpenClaw ไปยัง flag effort แบบ native

สำหรับคู่มือการเขียนแบบครบวงจร ดู Plugin แบ็กเอนด์ CLI

ช่องพิเศษเฉพาะ

อะแดปเตอร์ embedding ของหน่วยความจำ

• registerMemoryCapability คือ API Plugin หน่วยความจำแบบ exclusive ที่แนะนำ
• registerMemoryCapability อาจเปิดเผย publicArtifacts.listArtifacts(...) ด้วย เพื่อให้ Plugin คู่ขนานใช้ artifact หน่วยความจำที่ export ผ่าน openclaw/plugin-sdk/memory-host-core แทนการเข้าถึง layout ส่วนตัวของ Plugin หน่วยความจำเฉพาะโดยตรง
• registerMemoryPromptSection, registerMemoryFlushPlan, และ registerMemoryRuntime เป็น API Plugin หน่วยความจำแบบ exclusive ที่เข้ากันได้กับแบบเดิม
• MemoryFlushPlan.model สามารถ pin turn สำหรับ flush ไปยัง reference provider/model ที่แน่นอน เช่น ollama/qwen3:8b โดยไม่สืบทอด fallback chain ที่ใช้งานอยู่
• registerMemoryEmbeddingProvider ช่วยให้ Plugin หน่วยความจำที่ใช้งานอยู่ลงทะเบียน id อะแดปเตอร์ embedding ได้หนึ่งรายการหรือมากกว่า (เช่น openai, gemini หรือ id แบบกำหนดเองโดย Plugin)
• config ของผู้ใช้ เช่น agents.defaults.memorySearch.provider และ agents.defaults.memorySearch.fallback จะ resolve กับ id อะแดปเตอร์ที่ลงทะเบียนไว้เหล่านั้น

เหตุการณ์และวงจรชีวิต

ดู hook ของ Plugin สำหรับตัวอย่าง ชื่อ hook ทั่วไป และ ความหมายของ guard

ความหมายของการตัดสินใจใน hook

• before_tool_call: การส่งคืน { block: true } เป็นจุดสิ้นสุด เมื่อ handler ใดตั้งค่าแล้ว handler ที่มี priority ต่ำกว่าจะถูกข้าม
• before_tool_call: การส่งคืน { block: false } จะถือว่าไม่มีการตัดสินใจ (เหมือนกับการละ block) ไม่ใช่การ override
• before_install: การส่งคืน { block: true } เป็นจุดสิ้นสุด เมื่อ handler ใดตั้งค่าแล้ว handler ที่มี priority ต่ำกว่าจะถูกข้าม
• before_install: การส่งคืน { block: false } จะถือว่าไม่มีการตัดสินใจ (เหมือนกับการละ block) ไม่ใช่การ override
• reply_dispatch: การส่งคืน { handled: true, ... } เป็นจุดสิ้นสุด เมื่อ handler ใด claim dispatch แล้ว handler ที่มี priority ต่ำกว่าและเส้นทาง dispatch โมเดลเริ่มต้นจะถูกข้าม
• message_sending: การส่งคืน { cancel: true } เป็นจุดสิ้นสุด เมื่อ handler ใดตั้งค่าแล้ว handler ที่มี priority ต่ำกว่าจะถูกข้าม
• message_sending: การส่งคืน { cancel: false } จะถือว่าไม่มีการตัดสินใจ (เหมือนกับการละ cancel) ไม่ใช่การ override
• message_received: ใช้ฟิลด์ threadId แบบมีชนิดเมื่อคุณต้องการ routing ของ thread/topic ขาเข้า เก็บ metadata ไว้สำหรับข้อมูลเสริมเฉพาะ channel
• message_sending: ใช้ฟิลด์ routing replyToId / threadId แบบมีชนิดก่อน fallback ไปยัง metadata เฉพาะ channel
• gateway_start: ใช้ ctx.config, ctx.workspaceDir และ ctx.getCron?.() สำหรับสถานะเริ่มต้นที่ Gateway เป็นเจ้าของ แทนการพึ่งพา hook gateway:startup ภายใน
• cron_changed: สังเกตการเปลี่ยนแปลงวงจรชีวิต Cron ที่ gateway เป็นเจ้าของ ใช้ event.job?.state?.nextRunAtMs และ ctx.getCron?.() เมื่อซิงค์ตัวจัดกำหนดการ wake ภายนอก และให้ OpenClaw เป็นแหล่งความจริงสำหรับการตรวจสอบกำหนดเวลาและการดำเนินงาน

ฟิลด์ของออบเจ็กต์ API

แบบแผนโมดูลภายใน

ภายใน Plugin ของคุณ ให้ใช้ไฟล์ barrel แบบโลคัลสำหรับการนำเข้าภายใน:

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

พื้นผิวสาธารณะของ bundled plugin ที่โหลดผ่าน facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts และไฟล์เอนทรีสาธารณะลักษณะเดียวกัน) จะเลือกใช้ สแนปชอตคอนฟิกรันไทม์ที่ใช้งานอยู่เมื่อ OpenClaw กำลังทำงานอยู่ หากยังไม่มีสแนปชอตรันไทม์ ก็จะย้อนกลับไปใช้ไฟล์คอนฟิกที่แก้พาธแล้วบนดิสก์ facade ของ packaged bundled plugin ควรถูกโหลดผ่านตัวโหลด facade ของ Plugin ของ OpenClaw; การนำเข้าโดยตรงจาก dist/extensions/... จะข้ามการตรวจสอบ manifest และ runtime sidecar ที่การติดตั้งแบบแพ็กเกจใช้กับโค้ดที่ Plugin เป็นเจ้าของ

Provider plugins สามารถเปิดเผย barrel สัญญาแบบแคบที่เป็นโลคัลของ Plugin ได้ เมื่อ ตัวช่วยนั้นตั้งใจให้เฉพาะกับ provider และยังไม่ควรอยู่ใน subpath SDK แบบทั่วไป ตัวอย่างที่ bundled มา:

• Anthropic: seam สาธารณะ api.ts / contract-api.ts สำหรับตัวช่วยสตรีมของ Claude beta-header และ service_tier
• @openclaw/openai-provider: api.ts ส่งออกตัวสร้าง provider, ตัวช่วยโมเดลเริ่มต้น และตัวสร้าง provider แบบเรียลไทม์
• @openclaw/openrouter-provider: api.ts ส่งออกตัวสร้าง provider พร้อมตัวช่วย onboarding/คอนฟิก

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