Ikhtisar Plugin SDK

​

Konvensi impor

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

​

Referensi subpath

​

API pendaftaran

​

Pendaftaran kapabilitas

​

Alat dan perintah

agentPromptGuidance: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

Infrastruktur

​

Hook host untuk plugin workflow

• 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 eksternal dapat memiliki ekstensi sesi, deskriptor UI, perintah, metadata alat, injeksi giliran berikutnya, dan hook normal.
• Kebijakan alat tepercaya berjalan sebelum hook before_tool_call biasa dan dipercaya host. Kebijakan bawaan berjalan lebih dulu; kebijakan Plugin terpasang memerlukan pengaktifan eksplisit plus id lokalnya di contracts.trustedToolPolicies, dan berjalan berikutnya dalam urutan pemuatan Plugin. Id kebijakan berlingkup pada Plugin yang mendaftarkannya.
• Kepemilikan perintah yang dicadangkan hanya untuk bawaan. Plugin eksternal sebaiknya menggunakan nama perintah atau aliasnya sendiri.
• allowPromptInjection=false menonaktifkan hook yang mengubah prompt termasuk agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, bidang prompt dari before_agent_start lama, dan enqueueNextTurnInjection.

​

Pendaftaran penemuan 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() };
  },
});

​

Metadata pendaftaran CLI

• commands: nama perintah eksplisit yang dimiliki registrar
• descriptors: deskriptor perintah waktu-parse yang digunakan untuk bantuan CLI, perutean, dan pendaftaran CLI Plugin secara malas
• parentPath: jalur perintah induk opsional untuk grup perintah bersarang, seperti ["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,
      },
    ],
  },
);

​

Pendaftaran backend CLI

• id backend menjadi prefiks penyedia dalam ref model seperti my-cli/gpt-5.
• config backend menggunakan bentuk yang sama dengan agents.defaults.cliBackends.<id>.
• Konfigurasi pengguna tetap menang. OpenClaw menggabungkan agents.defaults.cliBackends.<id> di atas default plugin sebelum menjalankan CLI.
• Gunakan normalizeConfig ketika backend memerlukan penulisan ulang kompatibilitas setelah penggabungan (misalnya menormalkan bentuk flag lama).
• Gunakan resolveExecutionArgs untuk penulisan ulang argv bercakupan permintaan yang menjadi bagian dari dialek CLI, seperti memetakan level berpikir OpenClaw ke flag upaya native. Hook menerima ctx.executionMode; gunakan "side-question" untuk menambahkan flag isolasi native-backend bagi panggilan /btw sementara. Jika flag tersebut secara andal menonaktifkan tool native untuk CLI yang sebaliknya selalu aktif, deklarasikan sideQuestionToolMode: "disabled" juga.

​

Slot eksklusif

​

Adapter embedding memori yang tidak digunakan lagi

• registerMemoryCapability adalah API Plugin memori eksklusif yang disarankan.
• registerMemoryCapability juga dapat mengekspos publicArtifacts.listArtifacts(...) sehingga plugin pendamping dapat menggunakan artefak memori yang diekspor melalui openclaw/plugin-sdk/memory-host-core alih-alih masuk ke tata letak privat plugin memori tertentu.
• registerMemoryPromptSection, registerMemoryFlushPlan, dan registerMemoryRuntime adalah API Plugin memori eksklusif yang kompatibel dengan legacy.
• MemoryFlushPlan.model dapat menyematkan giliran flush ke referensi provider/model persis, seperti ollama/qwen3:8b, tanpa mewarisi rantai fallback aktif.
• registerMemoryEmbeddingProvider tidak digunakan lagi. Penyedia embedding baru harus menggunakan api.registerEmbeddingProvider(...) dan contracts.embeddingProviders.
• Penyedia khusus memori yang sudah ada tetap berfungsi selama jendela migrasi, tetapi laporan inspeksi plugin menandai ini sebagai utang kompatibilitas untuk plugin yang tidak dibundel.

​

Event dan siklus hidup

​

Semantik keputusan hook

• before_tool_call: mengembalikan { block: true } bersifat terminal. Setelah handler mana pun menetapkannya, handler berprioritas lebih rendah dilewati.
• before_tool_call: mengembalikan { block: false } diperlakukan sebagai tanpa keputusan (sama seperti menghilangkan block), bukan sebagai override.
• before_install: mengembalikan { block: true } bersifat terminal. Setelah handler mana pun menetapkannya, handler berprioritas lebih rendah dilewati.
• before_install: mengembalikan { block: false } diperlakukan sebagai tanpa keputusan (sama seperti menghilangkan block), bukan sebagai override.
• reply_dispatch: mengembalikan { handled: true, ... } bersifat terminal. Setelah handler mana pun mengklaim dispatch, handler berprioritas lebih rendah dan jalur dispatch model default dilewati.
• message_sending: mengembalikan { cancel: true } bersifat terminal. Setelah handler mana pun menetapkannya, handler berprioritas lebih rendah dilewati.
• message_sending: mengembalikan { cancel: false } diperlakukan sebagai tanpa keputusan (sama seperti menghilangkan cancel), bukan sebagai override.
• message_received: gunakan field bertipe threadId ketika Anda membutuhkan routing thread/topik masuk. Simpan metadata untuk tambahan khusus channel.
• message_sending: gunakan field routing bertipe replyToId / threadId sebelum fallback ke metadata khusus channel.
• gateway_start: gunakan ctx.config, ctx.workspaceDir, dan ctx.getCron?.() untuk status startup milik gateway alih-alih bergantung pada hook internal gateway:startup.
• cron_changed: amati perubahan siklus hidup Cron milik gateway. Gunakan event.job?.state?.nextRunAtMs dan ctx.getCron?.() saat menyinkronkan penjadwal bangun eksternal, dan pertahankan OpenClaw sebagai sumber kebenaran untuk pemeriksaan jatuh tempo dan eksekusi.

​

Field objek API

​

Konvensi modul internal

my-plugin/
  api.ts            # Ekspor publik untuk konsumen eksternal
  runtime-api.ts    # Ekspor runtime khusus internal
  index.ts          # Titik masuk plugin
  setup-entry.ts    # Entri khusus setup ringan (opsional)

• Anthropic: seam publik api.ts / contract-api.ts untuk helper stream beta-header Claude dan service_tier.
• @openclaw/openai-provider: api.ts mengekspor builder penyedia, helper model default, dan builder penyedia realtime.
• @openclaw/openrouter-provider: api.ts mengekspor builder penyedia plus helper onboarding/konfigurasi.

​

Terkait