ภาพรวม 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.

​

ข้อตกลงการ import

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

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

​

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

​

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

​

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

​

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

​

ฮุกโฮสต์สำหรับ 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(...)

• 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

​

การลงทะเบียนการค้นพบ 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() };
  },
});

​

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

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

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,
      },
    ],
  },
);

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,
      },
    ],
  },
);

​

การลงทะเบียนแบ็กเอนด์ 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

​

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

​

อะแดปเตอร์ 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

• 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

​

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

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)

• 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/คอนฟิก

​

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