Ikhtisar SDK Plugin

Plugin SDK adalah kontrak bertipe antara plugin dan core. Halaman ini adalah referensi untuk apa yang harus diimpor dan apa yang dapat Anda daftarkan.

Konvensi impor

Selalu impor dari subpath tertentu:

Setiap subpath adalah modul kecil yang mandiri. Ini menjaga startup tetap cepat dan mencegah masalah dependensi melingkar. Untuk helper entri/build khusus channel, utamakan openclaw/plugin-sdk/channel-core; gunakan openclaw/plugin-sdk/core untuk permukaan payung yang lebih luas dan helper bersama seperti buildChannelConfigSchema.

Untuk konfigurasi channel, publikasikan JSON Schema milik channel melalui openclaw.plugin.json#channelConfigs. Subpath plugin-sdk/channel-config-schema ditujukan untuk primitif skema bersama dan builder generik. Plugin bawaan OpenClaw menggunakan plugin-sdk/bundled-channel-config-schema untuk skema channel bawaan yang dipertahankan. Ekspor kompatibilitas yang deprecated tetap ada di plugin-sdk/channel-config-schema-legacy; tidak ada subpath skema bawaan yang menjadi pola untuk plugin baru.

Referensi subpath

Plugin SDK diekspos sebagai sekumpulan subpath sempit yang dikelompokkan berdasarkan area (entri plugin, channel, provider, auth, runtime, capability, memory, dan helper plugin bawaan yang dicadangkan). Untuk katalog lengkap, yang dikelompokkan dan ditautkan, lihat Subpath Plugin SDK.

Inventaris entrypoint compiler berada di scripts/lib/plugin-sdk-entrypoints.json; ekspor paket dihasilkan dari subset publik setelah mengurangi subpath pengujian/internal lokal repo yang tercantum di scripts/lib/plugin-sdk-private-local-only-subpaths.json. Jalankan pnpm plugin-sdk:surface untuk mengaudit jumlah ekspor publik. Subpath publik deprecated yang sudah cukup lama dan tidak digunakan oleh kode produksi ekstensi bawaan dilacak di scripts/lib/plugin-sdk-deprecated-public-subpaths.json; barrel re-export deprecated yang luas dilacak di scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API pendaftaran

Callback register(api) menerima objek OpenClawPluginApi dengan metode berikut:

Pendaftaran capability

Alat dan perintah

Perintah plugin dapat menetapkan agentPromptGuidance saat agen memerlukan petunjuk routing singkat milik perintah. Pertahankan teks tersebut tentang perintah itu sendiri; jangan tambahkan kebijakan khusus provider atau plugin ke builder prompt core.

Infrastruktur

Hook host untuk plugin workflow

Hook host adalah seam SDK untuk plugin yang perlu berpartisipasi dalam siklus hidup host, bukan hanya menambahkan provider, channel, atau alat. Hook ini adalah kontrak generik; Plan Mode dapat menggunakannya, begitu juga workflow persetujuan, gate kebijakan workspace, monitor latar belakang, wizard setup, dan plugin pendamping UI.

Gunakan namespace yang dikelompokkan untuk kode plugin baru:

• 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(...)

Metode flat yang setara tetap tersedia sebagai alias kompatibilitas deprecated untuk plugin yang sudah ada. Jangan tambahkan kode plugin baru yang memanggil 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, atau api.unscheduleSessionTurnsByTag secara langsung.

scheduleSessionTurn(...) adalah kemudahan dalam cakupan sesi di atas penjadwal Cron Gateway. Cron memiliki pengaturan waktu dan membuat catatan tugas latar belakang saat turn berjalan; Plugin SDK hanya membatasi sesi target, penamaan milik Plugin, dan pembersihan. Gunakan api.runtime.tasks.managedFlows di dalam turn terjadwal ketika pekerjaan itu sendiri membutuhkan status Task Flow multi-langkah yang tahan lama.

Kontrak sengaja memisahkan otoritas:

• Plugin eksternal dapat memiliki ekstensi sesi, deskriptor UI, perintah, metadata alat, injeksi turn berikutnya, dan hook normal.
• Kebijakan alat tepercaya berjalan sebelum hook before_tool_call biasa dan hanya bawaan karena ikut serta dalam kebijakan keselamatan host.
• Kepemilikan perintah cadangan hanya untuk bawaan. Plugin eksternal harus menggunakan nama perintah atau alias mereka sendiri.
• allowPromptInjection=false menonaktifkan hook yang mengubah prompt termasuk agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, field prompt dari before_agent_start lama, dan enqueueNextTurnInjection.

Contoh konsumen non-Plan:

Pendaftaran penemuan Gateway

api.registerGatewayDiscoveryService(...) memungkinkan Plugin mengiklankan Gateway aktif pada transport penemuan lokal seperti mDNS/Bonjour. OpenClaw memanggil layanan selama startup Gateway ketika penemuan lokal diaktifkan, meneruskan port Gateway saat ini dan data petunjuk TXT non-rahasia, lalu memanggil handler stop yang dikembalikan saat shutdown 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 penemuan Gateway tidak boleh memperlakukan nilai TXT yang diiklankan sebagai rahasia atau autentikasi. Penemuan adalah petunjuk routing; autentikasi Gateway dan penyematan TLS tetap memiliki kepercayaan.

Metadata pendaftaran CLI

api.registerCli(registrar, opts?) menerima dua jenis metadata perintah:

• commands: nama perintah eksplisit yang dimiliki oleh registrar
• descriptors: deskriptor perintah waktu-parse yang digunakan untuk bantuan CLI, routing, dan pendaftaran CLI Plugin lazy
• parentPath: jalur perintah induk opsional untuk grup perintah bersarang, seperti ["nodes"]

Untuk fitur node berpasangan, lebih baik gunakan api.registerNodeCliFeature(registrar, opts?). Ini adalah wrapper kecil di sekitar api.registerCli(..., { parentPath: ["nodes"] }) dan membuat perintah seperti openclaw nodes canvas menjadi fitur node eksplisit milik Plugin.

Jika Anda ingin perintah Plugin tetap dimuat lazy di jalur CLI root normal, sediakan descriptors yang mencakup setiap root perintah tingkat atas yang diekspos oleh registrar tersebut.

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

Perintah bersarang menerima perintah induk yang telah diresolve sebagai 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,      },    ],  },);

Gunakan commands saja hanya ketika Anda tidak membutuhkan pendaftaran CLI root lazy. Jalur kompatibilitas eager itu tetap didukung, tetapi tidak memasang placeholder berbasis deskriptor untuk pemuatan lazy waktu-parse.

Pendaftaran backend CLI

api.registerCliBackend(...) memungkinkan Plugin memiliki konfigurasi default untuk backend CLI AI lokal seperti codex-cli.

• id backend menjadi prefiks penyedia dalam referensi model seperti codex-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 membutuhkan penulisan ulang kompatibilitas setelah penggabungan (misalnya menormalkan bentuk flag lama).
• Gunakan resolveExecutionArgs untuk penulisan ulang argv bercakupan permintaan yang termasuk dialek CLI, seperti memetakan tingkat berpikir OpenClaw ke flag effort native.

Untuk panduan penulisan menyeluruh, lihat Plugin backend CLI.

Slot eksklusif

Adapter embedding memori

• 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 menjangkau tata letak privat Plugin memori tertentu.
• registerMemoryPromptSection, registerMemoryFlushPlan, dan registerMemoryRuntime adalah API Plugin memori eksklusif yang kompatibel lama.
• MemoryFlushPlan.model dapat menyematkan turn flush ke referensi provider/model persis, seperti ollama/qwen3:8b, tanpa mewarisi rantai fallback aktif.
• registerMemoryEmbeddingProvider memungkinkan Plugin memori aktif mendaftarkan satu atau beberapa id adapter embedding (misalnya openai, gemini, atau id kustom yang ditentukan Plugin).
• Konfigurasi pengguna seperti agents.defaults.memorySearch.provider dan agents.defaults.memorySearch.fallback diresolve terhadap id adapter yang terdaftar tersebut.

Peristiwa dan siklus hidup

Lihat Hook Plugin untuk contoh, nama hook umum, dan semantik guard.

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 threadId bertipe ketika Anda membutuhkan routing thread/topik masuk. Pertahankan metadata untuk tambahan khusus kanal.
• message_sending: gunakan field routing bertipe replyToId / threadId sebelum fallback ke metadata khusus kanal.
• 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

Di dalam plugin Anda, gunakan berkas barrel lokal untuk impor internal:

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)

Permukaan publik Plugin bawaan yang dimuat melalui facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts, dan berkas entri publik serupa) lebih mengutamakan snapshot konfigurasi runtime aktif saat OpenClaw sudah berjalan. Jika belum ada snapshot runtime, permukaan tersebut melakukan fallback ke berkas konfigurasi yang di-resolve di disk. Facade Plugin bawaan yang dipaketkan harus dimuat melalui pemuat facade Plugin OpenClaw; impor langsung dari dist/extensions/... melewati pemeriksaan manifest dan sidecar runtime yang digunakan instalasi paket untuk kode milik Plugin.

Plugin penyedia dapat mengekspos barrel kontrak lokal Plugin yang sempit saat sebuah helper sengaja bersifat khusus penyedia dan belum pantas berada di subjalur SDK generik. Contoh bawaan:

• Anthropic: seam publik api.ts / contract-api.ts untuk helper stream header beta 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 beserta helper onboarding/konfigurasi.

Terkait