Ikhtisar Plugin SDK

SDK Plugin adalah kontrak bertipe antara plugin dan core. Halaman ini adalah referensi untuk apa yang perlu 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 entry/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 retained channel bawaan. Ekspor kompatibilitas yang sudah usang tetap ada di plugin-sdk/channel-config-schema-legacy; tidak satu pun subpath skema bawaan merupakan pola untuk plugin baru.

Referensi subpath

SDK plugin diekspos sebagai serangkaian subpath sempit yang dikelompokkan menurut area (entry plugin, channel, provider, auth, runtime, kapabilitas, memori, dan helper plugin bawaan yang dicadangkan). Untuk katalog lengkap yang dikelompokkan dan ditautkan, lihat Subpath SDK Plugin.

Inventaris entrypoint compiler berada di scripts/lib/plugin-sdk-entrypoints.json; ekspor paket dihasilkan dari subset publik setelah mengurangkan 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 usang 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 usang yang luas dilacak di scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API pendaftaran

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

Pendaftaran kapabilitas

Provider embedding yang didaftarkan dengan api.registerEmbeddingProvider(...) juga harus dicantumkan dalam contracts.embeddingProviders di manifes plugin. Ini adalah permukaan embedding generik untuk pembuatan vektor yang dapat digunakan ulang. Pencarian memori dapat memakai permukaan provider generik ini. Seam api.registerMemoryEmbeddingProvider(...) dan contracts.memoryEmbeddingProviders yang lebih lama adalah kompatibilitas usang sementara provider khusus memori yang ada bermigrasi.

Provider khusus memori yang masih mengekspos runtime batchEmbed(...) tetap berada pada kontrak batching per-file yang ada kecuali runtime-nya secara eksplisit mengatur sourceWideBatchEmbed: true. Opt-in tersebut memungkinkan host memori mengirim chunk dari beberapa file memori dirty dan sumber yang diaktifkan dalam satu panggilan batchEmbed(...) hingga batas batch host. Adapter batch yang mengunggah file permintaan JSONL harus membagi tugas provider sebelum batas ukuran unggah serta batas jumlah permintaannya. Provider harus mengembalikan satu embedding per chunk input dalam urutan yang sama dengan batch.chunks; hilangkan flag ini ketika provider mengharapkan batch lokal-file atau tidak dapat mempertahankan urutan input di seluruh tugas source-wide yang lebih besar.

Alat dan perintah

Gunakan defineToolPlugin untuk plugin sederhana khusus alat dengan nama alat tetap. Gunakan api.registerTool(...) secara langsung untuk plugin campuran atau pendaftaran alat yang sepenuhnya dinamis.

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

Entri panduan dapat berupa string legacy, yang berlaku untuk setiap permukaan prompt, atau entri terstruktur:

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

surfaces terstruktur dapat mencakup openclaw_main, codex_app_server, cli_backend, acp_backend, atau subagent. pi_main tetap menjadi alias usang untuk openclaw_main. Hilangkan surfaces untuk panduan semua permukaan yang disengaja. Jangan meneruskan array surfaces kosong; itu ditolak agar hilangnya cakupan secara tidak sengaja tidak menjadi teks prompt global.

Instruksi developer app-server Codex native lebih ketat daripada permukaan prompt lainnya: hanya panduan yang secara eksplisit dicakupkan ke codex_app_server yang dipromosikan ke lane berprioritas lebih tinggi tersebut. Panduan string legacy dan panduan terstruktur tanpa cakupan tetap tersedia untuk permukaan prompt non-Codex demi kompatibilitas.

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, tetapi begitu juga workflow persetujuan, gate kebijakan workspace, monitor latar belakang, wizard penyiapan, dan plugin pendamping UI.

Gunakan namespace berkelompok 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 yang tidak digunakan lagi 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 berlingkup sesi di atas penjadwal Cron Gateway. Cron memiliki pewaktuan dan membuat rekaman tugas latar belakang saat giliran berjalan; Plugin SDK hanya membatasi sesi target, penamaan milik Plugin, dan pembersihan. Gunakan api.runtime.tasks.managedFlows di dalam giliran terjadwal saat pekerjaan itu sendiri memerlukan status Task Flow multi-langkah yang tahan lama.

Kontrak sengaja memisahkan otoritas:

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

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 saat penemuan lokal diaktifkan, meneruskan port Gateway saat ini dan data petunjuk TXT non-rahasia, serta memanggil handler stop yang dikembalikan selama 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 perutean; auth Gateway dan pinning TLS tetap memiliki kepercayaan.

Metadata pendaftaran CLI

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

• 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"]

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

Jika Anda ingin perintah Plugin tetap dimuat malas 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 di-resolve 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 saat Anda tidak memerlukan pendaftaran CLI root malas. Jalur kompatibilitas eager itu tetap didukung, tetapi tidak memasang placeholder berbasis deskriptor untuk pemuatan malas waktu-parse.

Pendaftaran backend CLI

api.registerCliBackend(...) memungkinkan Plugin memiliki konfigurasi default untuk backend CLI AI lokal seperti claude-cli atau my-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.

Untuk panduan penulisan end-to-end, lihat Plugin backend CLI.

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

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

Semantik keputusan hook

before_install adalah hook siklus hidup runtime-plugin, bukan permukaan kebijakan instal operator. Gunakan security.installPolicy ketika keputusan izinkan/blokir harus mencakup jalur instal atau pembaruan yang didukung CLI dan Gateway.

• 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

Di dalam plugin Anda, gunakan file barrel lokal untuk impor 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)

Permukaan publik plugin bundel yang dimuat facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts, dan file entri publik serupa) lebih memilih snapshot konfigurasi runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada snapshot runtime, permukaan tersebut fallback ke file konfigurasi yang di-resolve di disk. Facade plugin bundel yang dipaketkan harus dimuat melalui loader facade plugin OpenClaw; impor langsung dari dist/extensions/... melewati pemeriksaan manifest dan sidecar runtime yang digunakan instalasi terpaket untuk kode milik plugin.

Plugin penyedia dapat mengekspos barrel kontrak lokal-plugin yang sempit ketika helper memang khusus penyedia dan belum seharusnya berada di subjalur SDK generik. Contoh bundel:

• 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