Langsung ke konten utama

​
Ringkasan Plugin SDK

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

​
Konvensi impor

Selalu impor dari subpath tertentu: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Setiap subpath adalah modul kecil yang mandiri. Ini menjaga startup tetap cepat dan mencegah masalah circular dependency. 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. Jangan tambahkan atau bergantung pada seam kemudahan bernama provider seperti openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp, atau seam helper bermerek channel. Plugin bawaan harus menyusun subpath SDK generik di dalam barrel api.ts atau runtime-api.ts mereka sendiri, dan core harus menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik yang sempit ketika kebutuhannya benar-benar lintas channel. Peta ekspor yang dihasilkan masih berisi sejumlah kecil seam helper plugin bawaan seperti plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup, dan plugin-sdk/matrix*. Subpath tersebut ada hanya untuk pemeliharaan dan kompatibilitas plugin bawaan; subpath itu sengaja dihilangkan dari tabel umum di bawah ini dan bukan jalur impor yang direkomendasikan untuk plugin pihak ketiga yang baru.

​
Referensi subpath

Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap lebih dari 200 subpath yang dihasilkan ada di scripts/lib/plugin-sdk-entrypoints.json. Subpath helper plugin bawaan yang dicadangkan masih muncul di daftar hasil generate tersebut. Perlakukan itu sebagai detail implementasi/permukaan kompatibilitas kecuali halaman dokumen secara eksplisit mempromosikannya sebagai publik.

​
Entri plugin

SubpathEkspor utama
plugin-sdk/plugin-entrydefinePluginEntry
plugin-sdk/coredefineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema
plugin-sdk/config-schemaOpenClawSchema
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
SubpathEkspor utama
plugin-sdk/channel-coredefineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/config-schemaEkspor skema Zod root openclaw.json (OpenClawSchema)
plugin-sdk/channel-setupcreateOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, ditambah DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/setupHelper wizard setup bersama, prompt allowlist, pembuat status setup
plugin-sdk/setup-runtimecreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
plugin-sdk/account-coreHelper config multi-akun/action-gate, helper fallback akun default
plugin-sdk/account-idDEFAULT_ACCOUNT_ID, helper normalisasi account-id
plugin-sdk/account-resolutionPencarian akun + helper fallback default
plugin-sdk/account-helpersHelper sempit untuk daftar akun/aksi akun
plugin-sdk/channel-pairingcreateChannelPairingController
plugin-sdk/channel-reply-pipelinecreateChannelReplyPipeline
plugin-sdk/channel-config-helperscreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaTipe skema config channel
plugin-sdk/telegram-command-configHelper normalisasi/validasi custom-command Telegram dengan fallback kontrak bawaan
plugin-sdk/channel-policyresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclecreateAccountStatusSink
plugin-sdk/inbound-envelopeHelper bersama untuk route inbound + pembuat envelope
plugin-sdk/inbound-reply-dispatchHelper bersama untuk pencatatan dan dispatch inbound
plugin-sdk/messaging-targetsHelper parsing/pencocokan target
plugin-sdk/outbound-mediaHelper bersama pemuatan media outbound
plugin-sdk/outbound-runtimeHelper identitas outbound/send delegate
plugin-sdk/thread-bindings-runtimeSiklus hidup thread-binding dan helper adapter
plugin-sdk/agent-media-payloadPembuat payload media agen lama
plugin-sdk/conversation-runtimeHelper binding percakapan/thread, pairing, dan configured-binding
plugin-sdk/runtime-config-snapshotHelper snapshot config runtime
plugin-sdk/runtime-group-policyHelper resolusi group-policy runtime
plugin-sdk/channel-statusHelper snapshot/ringkasan status channel bersama
plugin-sdk/channel-config-primitivesPrimitive sempit skema config channel
plugin-sdk/channel-config-writesHelper otorisasi penulisan config channel
plugin-sdk/channel-plugin-commonEkspor prelude plugin channel bersama
plugin-sdk/allowlist-config-editHelper edit/baca config allowlist
plugin-sdk/group-accessHelper keputusan akses grup bersama
plugin-sdk/direct-dmHelper auth/guard direct-DM bersama
plugin-sdk/interactive-runtimeHelper normalisasi/reduksi payload balasan interaktif
plugin-sdk/channel-inboundHelper debounce inbound, pencocokan mention, helper mention-policy, dan helper envelope
plugin-sdk/channel-send-resultTipe hasil balasan
plugin-sdk/channel-actionscreateMessageToolButtonsSchema, createMessageToolCardSchema
plugin-sdk/channel-targetsHelper parsing/pencocokan target
plugin-sdk/channel-contractTipe kontrak channel
plugin-sdk/channel-feedbackWiring feedback/reaksi
plugin-sdk/channel-secret-runtimeHelper kontrak rahasia yang sempit seperti collectSimpleChannelFieldAssignments, getChannelSurface, pushAssignment, dan tipe target rahasia
SubpathEkspor utama
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
plugin-sdk/provider-setupHelper setup provider lokal/self-hosted yang dikurasi
plugin-sdk/self-hosted-provider-setupHelper setup provider self-hosted yang kompatibel dengan OpenAI dan terfokus
plugin-sdk/cli-backendDefault backend CLI + konstanta watchdog
plugin-sdk/provider-auth-runtimeHelper resolusi API key runtime untuk plugin provider
plugin-sdk/provider-auth-api-keyHelper onboarding/penulisan profil API key seperti upsertApiKeyProfile
plugin-sdk/provider-auth-resultPembuat hasil auth OAuth standar
plugin-sdk/provider-auth-loginHelper login interaktif bersama untuk plugin provider
plugin-sdk/provider-env-varsHelper pencarian env var auth provider
plugin-sdk/provider-authcreateProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile, upsertApiKeyProfile, writeOAuthCredentials
plugin-sdk/provider-model-sharedProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, pembuat replay-policy bersama, helper endpoint provider, dan helper normalisasi model-id seperti normalizeNativeXaiModelId
plugin-sdk/provider-catalog-sharedfindCatalogTemplate, buildSingleProviderApiKeyCatalog, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat
plugin-sdk/provider-httpHelper generic kemampuan HTTP/endpoint provider
plugin-sdk/provider-web-fetch-contractHelper kontrak config/seleksi web-fetch yang sempit seperti enablePluginInConfig dan WebFetchProviderPlugin
plugin-sdk/provider-web-fetchHelper registrasi/cache provider web-fetch
plugin-sdk/provider-web-search-contractHelper kontrak config/kredensial web-search yang sempit seperti enablePluginInConfig, resolveProviderWebSearchPluginConfig, dan setter/getter kredensial terlingkup
plugin-sdk/provider-web-searchHelper registrasi/cache/runtime provider web-search
plugin-sdk/provider-toolsProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, pembersihan skema Gemini + diagnostik, dan helper kompatibilitas xAI seperti resolveXaiModelCompatPatch / applyXaiModelCompat
plugin-sdk/provider-usagefetchClaudeUsage dan yang serupa
plugin-sdk/provider-streamProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, tipe wrapper stream, dan helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot
plugin-sdk/provider-onboardHelper patch config onboarding
plugin-sdk/global-singletonHelper singleton/map/cache lokal proses
SubpathEkspor utama
plugin-sdk/command-authresolveControlCommandGate, helper registry command, helper otorisasi pengirim
plugin-sdk/approval-auth-runtimeHelper resolusi approver dan action-auth dalam chat yang sama
plugin-sdk/approval-client-runtimeHelper profil/filter persetujuan exec native
plugin-sdk/approval-delivery-runtimeAdapter kemampuan/pengiriman persetujuan native
plugin-sdk/approval-gateway-runtimeHelper bersama resolusi gateway persetujuan
plugin-sdk/approval-handler-adapter-runtimeHelper pemuatan adapter persetujuan native yang ringan untuk entrypoint channel panas
plugin-sdk/approval-handler-runtimeHelper runtime approval handler yang lebih luas; utamakan seam adapter/gateway yang lebih sempit jika sudah cukup
plugin-sdk/approval-native-runtimeHelper target persetujuan native + account-binding
plugin-sdk/approval-reply-runtimeHelper payload balasan persetujuan exec/plugin
plugin-sdk/command-auth-nativeHelper auth command native + session-target native
plugin-sdk/command-detectionHelper deteksi command bersama
plugin-sdk/command-surfaceNormalisasi isi command dan helper permukaan command
plugin-sdk/allow-fromformatAllowFromLowercase
plugin-sdk/channel-secret-runtimeHelper pengumpulan kontrak rahasia yang sempit untuk permukaan rahasia channel/plugin
plugin-sdk/secret-ref-runtimeHelper sempit coerceSecretRef dan pengetikan SecretRef untuk parsing kontrak/config rahasia
plugin-sdk/security-runtimeHelper bersama untuk trust, gating DM, konten eksternal, dan pengumpulan rahasia
plugin-sdk/ssrf-policyHelper allowlist host dan kebijakan SSRF jaringan privat
plugin-sdk/ssrf-runtimeHelper pinned-dispatcher, fetch dengan penjagaan SSRF, dan kebijakan SSRF
plugin-sdk/secret-inputHelper parsing input rahasia
plugin-sdk/webhook-ingressHelper request/target webhook
plugin-sdk/webhook-request-guardsHelper ukuran isi request/timeout
SubpathEkspor utama
plugin-sdk/runtimeHelper runtime/logging/backup/instalasi plugin yang luas
plugin-sdk/runtime-envHelper sempit untuk env runtime, logger, timeout, retry, dan backoff
plugin-sdk/channel-runtime-contextHelper registrasi dan pencarian runtime-context channel generik
plugin-sdk/runtime-storecreatePluginRuntimeStore
plugin-sdk/plugin-runtimeHelper bersama untuk command/hook/http/interaktif plugin
plugin-sdk/hook-runtimeHelper pipeline webhook/internal hook bersama
plugin-sdk/lazy-runtimeHelper impor/binding runtime lazy seperti createLazyRuntimeModule, createLazyRuntimeMethod, dan createLazyRuntimeSurface
plugin-sdk/process-runtimeHelper process exec
plugin-sdk/cli-runtimeHelper formatting CLI, wait, dan versi
plugin-sdk/gateway-runtimeHelper client gateway dan patch status channel
plugin-sdk/config-runtimeHelper pemuatan/penulisan config
plugin-sdk/telegram-command-configNormalisasi nama/deskripsi command Telegram dan pemeriksaan duplikasi/konflik, bahkan ketika permukaan kontrak Telegram bawaan tidak tersedia
plugin-sdk/approval-runtimeHelper persetujuan exec/plugin, pembuat approval-capability, helper auth/profile, helper routing/runtime native
plugin-sdk/reply-runtimeHelper runtime inbound/balasan bersama, chunking, dispatch, heartbeat, perencana balasan
plugin-sdk/reply-dispatch-runtimeHelper sempit untuk dispatch/finalisasi balasan
plugin-sdk/reply-historyHelper bersama reply-history jendela pendek seperti buildHistoryContext, recordPendingHistoryEntry, dan clearHistoryEntriesIfEnabled
plugin-sdk/reply-referencecreateReplyReferencePlanner
plugin-sdk/reply-chunkingHelper sempit chunking teks/markdown
plugin-sdk/session-store-runtimeHelper path session store + updated-at
plugin-sdk/state-pathsHelper path direktori state/OAuth
plugin-sdk/routingHelper binding route/kunci sesi/akun seperti resolveAgentRoute, buildAgentSessionKey, dan resolveDefaultAgentBoundAccountId
plugin-sdk/status-helpersHelper bersama ringkasan status channel/akun, default status runtime, dan helper metadata masalah
plugin-sdk/target-resolver-runtimeHelper target resolver bersama
plugin-sdk/string-normalization-runtimeHelper normalisasi slug/string
plugin-sdk/request-urlEkstrak URL string dari input yang mirip fetch/request
plugin-sdk/run-commandRunner command bertimer dengan hasil stdout/stderr yang dinormalisasi
plugin-sdk/param-readersPembaca param tool/CLI umum
plugin-sdk/tool-sendEkstrak field target pengiriman kanonis dari argumen tool
plugin-sdk/temp-pathHelper bersama untuk path unduhan sementara
plugin-sdk/logging-coreHelper logger subsistem dan redaksi
plugin-sdk/markdown-table-runtimeHelper mode tabel Markdown
plugin-sdk/json-storeHelper kecil baca/tulis state JSON
plugin-sdk/file-lockHelper file-lock re-entrant
plugin-sdk/persistent-dedupeHelper cache dedupe berbasis disk
plugin-sdk/acp-runtimeHelper ACP runtime/sesi dan reply-dispatch
plugin-sdk/agent-config-primitivesPrimitive sempit skema config runtime agen
plugin-sdk/boolean-paramPembaca param boolean longgar
plugin-sdk/dangerous-name-runtimeHelper resolusi pencocokan nama berbahaya
plugin-sdk/device-bootstrapHelper bootstrap perangkat dan token pairing
plugin-sdk/extension-sharedPrimitive helper bersama untuk passive-channel, status, dan ambient proxy
plugin-sdk/models-provider-runtimeHelper balasan command/provider /models
plugin-sdk/skill-commands-runtimeHelper daftar skill command
plugin-sdk/native-command-registryHelper registrasi/build/serialisasi command native
plugin-sdk/provider-zai-endpointHelper deteksi endpoint Z.A.I
plugin-sdk/infra-runtimeHelper system event/heartbeat
plugin-sdk/collection-runtimeHelper cache kecil yang dibatasi
plugin-sdk/diagnostic-runtimeHelper flag dan event diagnostik
plugin-sdk/error-runtimeGraph error, formatting, helper klasifikasi error bersama, isApprovalNotFoundError
plugin-sdk/fetch-runtimeHelper fetch terbungkus, proxy, dan pinned lookup
plugin-sdk/host-runtimeHelper normalisasi hostname dan host SCP
plugin-sdk/retry-runtimeHelper config retry dan runner retry
plugin-sdk/agent-runtimeHelper direktori/identitas/workspace agen
plugin-sdk/directory-runtimeQuery/dedup direktori berbasis config
plugin-sdk/keyed-async-queueKeyedAsyncQueue
SubpathEkspor utama
plugin-sdk/media-runtimeHelper bersama fetch/transform/store media plus pembuat payload media
plugin-sdk/media-generation-runtimeHelper bersama failover pembuatan media, pemilihan kandidat, dan pesan model yang hilang
plugin-sdk/media-understandingTipe provider pemahaman media plus ekspor helper gambar/audio untuk provider
plugin-sdk/text-runtimeHelper bersama teks/markdown/logging seperti penghapusan teks yang terlihat oleh asisten, helper render/chunking/table markdown, helper redaksi, helper directive-tag, dan utilitas safe-text
plugin-sdk/text-chunkingHelper chunking teks outbound
plugin-sdk/speechTipe provider ucapan plus helper directive, registry, dan validasi untuk provider
plugin-sdk/speech-coreTipe provider ucapan bersama, registry, directive, dan helper normalisasi
plugin-sdk/realtime-transcriptionTipe provider transkripsi realtime dan helper registry
plugin-sdk/realtime-voiceTipe provider suara realtime dan helper registry
plugin-sdk/image-generationTipe provider pembuatan gambar
plugin-sdk/image-generation-coreTipe pembuatan gambar bersama, failover, auth, dan helper registry
plugin-sdk/music-generationTipe provider/request/result pembuatan musik
plugin-sdk/music-generation-coreTipe pembuatan musik bersama, helper failover, pencarian provider, dan parsing model-ref
plugin-sdk/video-generationTipe provider/request/result pembuatan video
plugin-sdk/video-generation-coreTipe pembuatan video bersama, helper failover, pencarian provider, dan parsing model-ref
plugin-sdk/webhook-targetsHelper registry target webhook dan instalasi route
plugin-sdk/webhook-pathHelper normalisasi path webhook
plugin-sdk/web-mediaHelper bersama pemuatan media remote/lokal
plugin-sdk/zodzod yang diekspor ulang untuk konsumen Plugin SDK
plugin-sdk/testinginstallCommonResolveTargetErrorCases, shouldAckReaction
SubpathEkspor utama
plugin-sdk/memory-corePermukaan helper memory-core bawaan untuk helper manager/config/file/CLI
plugin-sdk/memory-core-engine-runtimeFasad runtime indeks/pencarian memori
plugin-sdk/memory-core-host-engine-foundationEkspor engine fondasi host memori
plugin-sdk/memory-core-host-engine-embeddingsEkspor engine embedding host memori
plugin-sdk/memory-core-host-engine-qmdEkspor engine QMD host memori
plugin-sdk/memory-core-host-engine-storageEkspor engine penyimpanan host memori
plugin-sdk/memory-core-host-multimodalHelper multimodal host memori
plugin-sdk/memory-core-host-queryHelper query host memori
plugin-sdk/memory-core-host-secretHelper rahasia host memori
plugin-sdk/memory-core-host-eventsHelper jurnal event host memori
plugin-sdk/memory-core-host-statusHelper status host memori
plugin-sdk/memory-core-host-runtime-cliHelper runtime CLI host memori
plugin-sdk/memory-core-host-runtime-coreHelper runtime core host memori
plugin-sdk/memory-core-host-runtime-filesHelper file/runtime host memori
plugin-sdk/memory-host-coreAlias netral-vendor untuk helper runtime core host memori
plugin-sdk/memory-host-eventsAlias netral-vendor untuk helper jurnal event host memori
plugin-sdk/memory-host-filesAlias netral-vendor untuk helper file/runtime host memori
plugin-sdk/memory-host-markdownHelper managed-markdown bersama untuk plugin yang berdekatan dengan memori
plugin-sdk/memory-host-searchFasad runtime memori aktif untuk akses search-manager
plugin-sdk/memory-host-statusAlias netral-vendor untuk helper status host memori
plugin-sdk/memory-lancedbPermukaan helper memory-lancedb bawaan
FamilySubpath saat iniTujuan penggunaan
Browserplugin-sdk/browser-cdp, plugin-sdk/browser-config-runtime, plugin-sdk/browser-config-support, plugin-sdk/browser-control-auth, plugin-sdk/browser-node-runtime, plugin-sdk/browser-profiles, plugin-sdk/browser-security-runtime, plugin-sdk/browser-setup-tools, plugin-sdk/browser-supportHelper dukungan plugin browser bawaan (browser-support tetap menjadi compatibility barrel)
Matrixplugin-sdk/matrix, plugin-sdk/matrix-helper, plugin-sdk/matrix-runtime-heavy, plugin-sdk/matrix-runtime-shared, plugin-sdk/matrix-runtime-surface, plugin-sdk/matrix-surface, plugin-sdk/matrix-thread-bindingsPermukaan helper/runtime Matrix bawaan
Lineplugin-sdk/line, plugin-sdk/line-core, plugin-sdk/line-runtime, plugin-sdk/line-surfacePermukaan helper/runtime LINE bawaan
IRCplugin-sdk/irc, plugin-sdk/irc-surfacePermukaan helper IRC bawaan
Helper khusus channelplugin-sdk/googlechat, plugin-sdk/zalouser, plugin-sdk/bluebubbles, plugin-sdk/bluebubbles-policy, plugin-sdk/mattermost, plugin-sdk/mattermost-policy, plugin-sdk/feishu-conversation, plugin-sdk/msteams, plugin-sdk/nextcloud-talk, plugin-sdk/nostr, plugin-sdk/tlon, plugin-sdk/twitchSeam kompatibilitas/helper channel bawaan
Helper auth/plugin khususplugin-sdk/github-copilot-login, plugin-sdk/github-copilot-token, plugin-sdk/diagnostics-otel, plugin-sdk/diffs, plugin-sdk/llm-task, plugin-sdk/thread-ownership, plugin-sdk/voice-callSeam helper fitur/plugin bawaan; plugin-sdk/github-copilot-token saat ini mengekspor DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken, dan resolveCopilotApiToken

​
API registrasi

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

​
Registrasi capability

MetodeYang didaftarkan
api.registerProvider(...)Inferensi teks (LLM)
api.registerCliBackend(...)Backend inferensi CLI lokal
api.registerChannel(...)Channel pesan
api.registerSpeechProvider(...)Sintesis text-to-speech / STT
api.registerRealtimeTranscriptionProvider(...)Transkripsi realtime streaming
api.registerRealtimeVoiceProvider(...)Sesi suara realtime duplex
api.registerMediaUnderstandingProvider(...)Analisis gambar/audio/video
api.registerImageGenerationProvider(...)Pembuatan gambar
api.registerMusicGenerationProvider(...)Pembuatan musik
api.registerVideoGenerationProvider(...)Pembuatan video
api.registerWebFetchProvider(...)Provider fetch / scrape web
api.registerWebSearchProvider(...)Pencarian web

​
Tools dan command

MetodeYang didaftarkan
api.registerTool(tool, opts?)Tool agen (wajib atau { optional: true })
api.registerCommand(def)Command kustom (melewati LLM)

​
Infrastruktur

MetodeYang didaftarkan
api.registerHook(events, handler, opts?)Event hook
api.registerHttpRoute(params)Endpoint HTTP gateway
api.registerGatewayMethod(name, handler)Metode RPC gateway
api.registerCli(registrar, opts?)Subcommand CLI
api.registerService(service)Layanan background
api.registerInteractiveHandler(registration)Interactive handler
api.registerMemoryPromptSupplement(builder)Bagian prompt tambahan yang berdekatan dengan memori
api.registerMemoryCorpusSupplement(adapter)Korpus pencarian/baca memori tambahan
Namespace admin core yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) selalu tetap operator.admin, bahkan jika plugin mencoba menetapkan scope metode gateway yang lebih sempit. Utamakan prefiks khusus plugin untuk metode milik plugin.

​
Metadata registrasi CLI

api.registerCli(registrar, opts?) menerima dua jenis metadata tingkat atas:
  • commands: root command eksplisit yang dimiliki registrar
  • descriptors: descriptor command saat parse yang digunakan untuk bantuan CLI root, routing, dan registrasi CLI plugin lazy
Jika Anda ingin command plugin tetap lazy-loaded di jalur CLI root normal, sediakan descriptors yang mencakup setiap root command 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,
      },
    ],
  },
);
Gunakan commands saja hanya ketika Anda tidak memerlukan registrasi CLI root lazy. Jalur kompatibilitas eager itu tetap didukung, tetapi jalur tersebut tidak memasang placeholder berbasis descriptor untuk lazy loading saat parse time.

​
Registrasi backend CLI

api.registerCliBackend(...) memungkinkan plugin memiliki config default untuk backend CLI AI lokal seperti codex-cli.
  • id backend menjadi prefiks provider dalam model ref seperti codex-cli/gpt-5.
  • config backend menggunakan bentuk yang sama seperti agents.defaults.cliBackends.<id>.
  • Config 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).

​
Slot eksklusif

MetodeYang didaftarkan
api.registerContextEngine(id, factory)Context engine (satu aktif pada satu waktu)
api.registerMemoryCapability(capability)Capability memori terpadu
api.registerMemoryPromptSection(builder)Pembuat bagian prompt memori
api.registerMemoryFlushPlan(resolver)Resolver rencana flush memori
api.registerMemoryRuntime(runtime)Adapter runtime memori

​
Adapter embedding memori

MetodeYang didaftarkan
api.registerMemoryEmbeddingProvider(adapter)Adapter embedding memori untuk plugin aktif
  • registerMemoryCapability adalah API plugin memori eksklusif yang diutamakan.
  • 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 layout privat plugin memori tertentu.
  • registerMemoryPromptSection, registerMemoryFlushPlan, dan registerMemoryRuntime adalah API plugin memori eksklusif yang kompatibel dengan versi lama.
  • registerMemoryEmbeddingProvider memungkinkan plugin memori aktif mendaftarkan satu atau lebih id adapter embedding (misalnya openai, gemini, atau id khusus yang didefinisikan plugin).
  • Config pengguna seperti agents.defaults.memorySearch.provider dan agents.defaults.memorySearch.fallback diresolusikan terhadap id adapter terdaftar tersebut.

​
Event dan siklus hidup

MetodeFungsinya
api.on(hookName, handler, opts?)Lifecycle hook bertipe
api.onConversationBindingResolved(handler)Callback binding percakapan

​
Semantik keputusan hook

  • before_tool_call: mengembalikan { block: true } bersifat terminal. Setelah ada handler yang menetapkannya, handler prioritas lebih rendah dilewati.
  • before_tool_call: mengembalikan { block: false } diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan block), bukan sebagai override.
  • before_install: mengembalikan { block: true } bersifat terminal. Setelah ada handler yang menetapkannya, handler prioritas lebih rendah dilewati.
  • before_install: mengembalikan { block: false } diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan block), bukan sebagai override.
  • reply_dispatch: mengembalikan { handled: true, ... } bersifat terminal. Setelah ada handler yang mengklaim dispatch, handler prioritas lebih rendah dan jalur dispatch model default dilewati.
  • message_sending: mengembalikan { cancel: true } bersifat terminal. Setelah ada handler yang menetapkannya, handler prioritas lebih rendah dilewati.
  • message_sending: mengembalikan { cancel: false } diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan cancel), bukan sebagai override.

​
Field objek API

FieldTipeDeskripsi
api.idstringId plugin
api.namestringNama tampilan
api.versionstring?Versi plugin (opsional)
api.descriptionstring?Deskripsi plugin (opsional)
api.sourcestringPath sumber plugin
api.rootDirstring?Direktori root plugin (opsional)
api.configOpenClawConfigSnapshot config saat ini (snapshot runtime in-memory aktif jika tersedia)
api.pluginConfigRecord<string, unknown>Config khusus plugin dari plugins.entries.<id>.config
api.runtimePluginRuntimeHelper runtime
api.loggerPluginLoggerLogger terlingkup (debug, info, warn, error)
api.registrationModePluginRegistrationModeMode pemuatan saat ini; "setup-runtime" adalah jendela startup/setup ringan sebelum full-entry
api.resolvePath(input)(string) => stringMenyelesaikan path relatif terhadap root plugin

​
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 ringan khusus setup (opsional)
Jangan pernah mengimpor plugin Anda sendiri melalui openclaw/plugin-sdk/<your-plugin> dari kode production. Arahkan impor internal melalui ./api.ts atau ./runtime-api.ts. Jalur SDK adalah kontrak eksternal saja.
Permukaan publik plugin bawaan yang dimuat melalui facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts, dan file entri publik serupa) kini mengutamakan snapshot config runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada snapshot runtime, permukaan tersebut akan kembali ke file config yang telah diresolusikan di disk. Plugin provider juga dapat mengekspos barrel kontrak lokal plugin yang sempit ketika helper memang bersifat khusus provider dan belum layak dimasukkan ke subpath SDK generik. Contoh bawaan saat ini: provider Anthropic menyimpan helper stream Claude di seam publik api.ts / contract-api.ts miliknya sendiri alih-alih mendorong logika header beta Anthropic dan service_tier ke kontrak plugin-sdk/* generik. Contoh bawaan lain saat ini:
  • @openclaw/openai-provider: api.ts mengekspor builder provider, helper model default, dan builder provider realtime
  • @openclaw/openrouter-provider: api.ts mengekspor builder provider plus helper onboarding/config
Kode production extension juga harus menghindari impor openclaw/plugin-sdk/<other-plugin>. Jika sebuah helper benar-benar bersifat bersama, pindahkan ke subpath SDK netral seperti openclaw/plugin-sdk/speech, .../provider-model-shared, atau permukaan berorientasi capability lainnya alih-alih menggabungkan dua plugin secara erat.

​
Terkait