Langsung ke konten utama

​
Ikhtisar 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 dependensi melingkar. Untuk helper entri/build yang spesifik channel, utamakan openclaw/plugin-sdk/channel-core; simpan openclaw/plugin-sdk/core untuk permukaan payung yang lebih luas dan helper bersama seperti buildChannelConfigSchema. Jangan tambahkan atau bergantung pada seam praktis 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 milik 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 sekumpulan 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 hanya ada 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 200+ subpath yang dihasilkan ada di scripts/lib/plugin-sdk-entrypoints.json. Subpath helper plugin bawaan yang dicadangkan masih muncul dalam daftar yang dihasilkan itu. 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, plus 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/action-gate multi-akun, helper fallback akun default
plugin-sdk/account-idDEFAULT_ACCOUNT_ID, helper normalisasi account-id
plugin-sdk/account-resolutionHelper lookup akun + fallback default
plugin-sdk/account-helpersHelper sempit daftar-aksi akun/akun
plugin-sdk/channel-pairingcreateChannelPairingController
plugin-sdk/channel-reply-pipelinecreateChannelReplyPipeline
plugin-sdk/channel-config-helperscreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaTipe skema konfigurasi 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 rute masuk + pembuat envelope bersama
plugin-sdk/inbound-reply-dispatchHelper record-and-dispatch masuk bersama
plugin-sdk/messaging-targetsHelper parsing/pencocokan target
plugin-sdk/outbound-mediaHelper pemuatan media keluar bersama
plugin-sdk/outbound-runtimeHelper identitas/delegasi kirim keluar
plugin-sdk/thread-bindings-runtimeLifecycle thread-binding dan helper adapter
plugin-sdk/agent-media-payloadPembuat payload media agen lama
plugin-sdk/conversation-runtimeBinding percakapan/thread, pairing, dan helper binding terkonfigurasi
plugin-sdk/runtime-config-snapshotHelper snapshot konfigurasi 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 konfigurasi channel
plugin-sdk/channel-config-writesHelper otorisasi penulisan konfigurasi channel
plugin-sdk/channel-plugin-commonEkspor prelude plugin channel bersama
plugin-sdk/allowlist-config-editHelper edit/baca konfigurasi allowlist
plugin-sdk/group-accessHelper keputusan group-access bersama
plugin-sdk/direct-dmHelper auth/guard DM langsung bersama
plugin-sdk/interactive-runtimeHelper normalisasi/reduksi payload balasan interaktif
plugin-sdk/channel-inboundDebounce, pencocokan mention, 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-feedbackPengkabelan feedback/reaksi
SubpathEkspor utama
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
plugin-sdk/provider-setupHelper setup provider lokal/self-hosted yang terkurasi
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
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 lookup env-var auth provider
plugin-sdk/provider-authcreateProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile
plugin-sdk/provider-model-sharedProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, builder 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 kemampuan endpoint/HTTP provider generik
plugin-sdk/provider-web-fetchHelper pendaftaran/cache provider web-fetch
plugin-sdk/provider-web-searchHelper pendaftaran/cache/konfigurasi 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 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot bersama
plugin-sdk/provider-onboardHelper patch konfigurasi onboarding
plugin-sdk/global-singletonHelper singleton/map/cache lokal-proses
SubpathEkspor utama
plugin-sdk/command-authresolveControlCommandGate, helper registri perintah, helper otorisasi pengirim
plugin-sdk/approval-auth-runtimeHelper resolusi approver dan same-chat action-auth
plugin-sdk/approval-client-runtimeHelper profil/filter persetujuan exec native
plugin-sdk/approval-delivery-runtimeAdapter kemampuan/pengiriman persetujuan native
plugin-sdk/approval-native-runtimeHelper target persetujuan native + account-binding
plugin-sdk/approval-reply-runtimeHelper payload balasan persetujuan exec/plugin
plugin-sdk/command-auth-nativeAuth perintah native + helper session-target native
plugin-sdk/command-detectionHelper deteksi perintah bersama
plugin-sdk/command-surfaceNormalisasi isi perintah dan helper permukaan perintah
plugin-sdk/allow-fromformatAllowFromLowercase
plugin-sdk/security-runtimeHelper trust, DM gating, external-content, dan pengumpulan secret bersama
plugin-sdk/ssrf-policyHelper host allowlist dan kebijakan SSRF jaringan private
plugin-sdk/ssrf-runtimeHelper pinned-dispatcher, fetch yang dijaga SSRF, dan kebijakan SSRF
plugin-sdk/secret-inputHelper parsing input secret
plugin-sdk/webhook-ingressHelper permintaan/target webhook
plugin-sdk/webhook-request-guardsHelper ukuran body/timeout permintaan
SubpathEkspor utama
plugin-sdk/runtimeHelper runtime/logging/backup/install-plugin yang luas
plugin-sdk/runtime-envHelper env runtime, logger, timeout, retry, dan backoff yang sempit
plugin-sdk/runtime-storecreatePluginRuntimeStore
plugin-sdk/plugin-runtimeHelper perintah/hook/http/interaktif plugin bersama
plugin-sdk/hook-runtimeHelper pipeline webhook/hook internal bersama
plugin-sdk/lazy-runtimeHelper impor/binding runtime lazy seperti createLazyRuntimeModule, createLazyRuntimeMethod, dan createLazyRuntimeSurface
plugin-sdk/process-runtimeHelper exec proses
plugin-sdk/cli-runtimeHelper formatting, wait, dan versi CLI
plugin-sdk/gateway-runtimeHelper klien gateway dan patch channel-status
plugin-sdk/config-runtimeHelper muat/tulis konfigurasi
plugin-sdk/telegram-command-configNormalisasi nama/deskripsi perintah Telegram dan pemeriksaan duplikat/konflik, bahkan saat permukaan kontrak Telegram bawaan tidak tersedia
plugin-sdk/approval-runtimeHelper persetujuan exec/plugin, builder kemampuan persetujuan, helper auth/profil, helper routing/runtime native
plugin-sdk/reply-runtimeHelper runtime masuk/balasan bersama, chunking, dispatch, heartbeat, perencana balasan
plugin-sdk/reply-dispatch-runtimeHelper dispatch/finalisasi balasan yang sempit
plugin-sdk/reply-historyHelper reply-history jendela pendek bersama seperti buildHistoryContext, recordPendingHistoryEntry, dan clearHistoryEntriesIfEnabled
plugin-sdk/reply-referencecreateReplyReferencePlanner
plugin-sdk/reply-chunkingHelper chunking teks/markdown yang sempit
plugin-sdk/session-store-runtimeHelper path session store + updated-at
plugin-sdk/state-pathsHelper path direktori state/OAuth
plugin-sdk/routingHelper rute/kunci sesi/account binding seperti resolveAgentRoute, buildAgentSessionKey, dan resolveDefaultAgentBoundAccountId
plugin-sdk/status-helpersHelper ringkasan status channel/akun bersama, default runtime-state, dan helper metadata issue
plugin-sdk/target-resolver-runtimeHelper target resolver bersama
plugin-sdk/string-normalization-runtimeHelper normalisasi slug/string
plugin-sdk/request-urlEkstrak URL string dari input mirip fetch/request
plugin-sdk/run-commandRunner perintah bertimer dengan hasil stdout/stderr yang dinormalisasi
plugin-sdk/param-readersPembaca param tool/CLI umum
plugin-sdk/tool-sendEkstrak field target kirim kanonis dari argumen tool
plugin-sdk/temp-pathHelper path unduhan sementara bersama
plugin-sdk/logging-coreHelper logger subsystem dan redaksi
plugin-sdk/markdown-table-runtimeHelper mode tabel Markdown
plugin-sdk/json-storeHelper baca/tulis state JSON kecil
plugin-sdk/file-lockHelper file-lock re-entrant
plugin-sdk/persistent-dedupeHelper cache dedupe berbasis disk
plugin-sdk/acp-runtimeHelper runtime/sesi ACP
plugin-sdk/agent-config-primitivesPrimitive sempit skema konfigurasi 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 channel pasif dan status bersama
plugin-sdk/models-provider-runtimeHelper balasan perintah/provider /models
plugin-sdk/skill-commands-runtimeHelper daftar perintah skill
plugin-sdk/native-command-registryHelper registri/build/serialize perintah native
plugin-sdk/provider-zai-endpointHelper deteksi endpoint Z.AI
plugin-sdk/infra-runtimeHelper event/heartbeat sistem
plugin-sdk/collection-runtimeHelper cache berbatas kecil
plugin-sdk/diagnostic-runtimeHelper flag dan event diagnostik
plugin-sdk/error-runtimeHelper grafik error, formatting, 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 konfigurasi retry dan retry runner
plugin-sdk/agent-runtimeHelper direktori/identitas/workspace agen
plugin-sdk/directory-runtimeQuery/dedup direktori berbasis konfigurasi
plugin-sdk/keyed-async-queueKeyedAsyncQueue
SubpathEkspor utama
plugin-sdk/media-runtimeHelper fetch/transform/store media bersama plus builder payload media
plugin-sdk/media-understandingTipe provider pemahaman media plus ekspor helper gambar/audio yang menghadap provider
plugin-sdk/text-runtimeHelper teks/markdown/logging bersama seperti penghapusan assistant-visible-text, helper render/chunking/table markdown, helper redaksi, helper directive-tag, dan utilitas safe-text
plugin-sdk/text-chunkingHelper chunking teks keluar
plugin-sdk/speechTipe provider speech plus helper directive, registri, dan validasi yang menghadap provider
plugin-sdk/speech-coreTipe provider speech bersama, registri, directive, dan helper normalisasi
plugin-sdk/realtime-transcriptionTipe provider transkripsi realtime dan helper registri
plugin-sdk/realtime-voiceTipe provider suara realtime dan helper registri
plugin-sdk/image-generationTipe provider pembuatan gambar
plugin-sdk/image-generation-coreTipe pembuatan gambar bersama, failover, auth, dan helper registri
plugin-sdk/video-generationTipe provider/permintaan/hasil pembuatan video
plugin-sdk/video-generation-coreTipe pembuatan video bersama, helper failover, lookup provider, dan parsing model-ref
plugin-sdk/webhook-targetsRegistri target webhook dan helper pemasangan rute
plugin-sdk/webhook-pathHelper normalisasi path webhook
plugin-sdk/web-mediaHelper pemuatan media remote/lokal bersama
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 index/search memori
plugin-sdk/memory-core-host-engine-foundationEkspor engine foundation 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 secret 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 inti host memori
plugin-sdk/memory-core-host-runtime-filesHelper file/runtime host memori
plugin-sdk/memory-lancedbPermukaan helper memory-lancedb bawaan
FamilySubpath saat iniPenggunaan yang dimaksud
Browserplugin-sdk/browser-config-support, plugin-sdk/browser-supportHelper dukungan plugin browser bawaan
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-spesifikplugin-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 pendaftaran

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

​
Pendaftaran kapabilitas

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

​
Tool dan perintah

MetodeYang didaftarkan
api.registerTool(tool, opts?)Tool agen (wajib atau { optional: true })
api.registerCommand(def)Perintah 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?)Subperintah CLI
api.registerService(service)Layanan latar belakang
api.registerInteractiveHandler(registration)Handler interaktif
Namespace admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) selalu tetap operator.admin, bahkan jika plugin mencoba menetapkan cakupan metode gateway yang lebih sempit. Utamakan prefix khusus plugin untuk metode milik plugin.

​
Metadata pendaftaran CLI

api.registerCli(registrar, opts?) menerima dua jenis metadata tingkat atas:
  • commands: root perintah eksplisit yang dimiliki registrar
  • descriptors: deskriptor perintah pada waktu parse yang digunakan untuk bantuan CLI root, routing, dan pendaftaran CLI plugin lazy
Jika Anda ingin perintah plugin tetap dimuat secara lazy pada jalur CLI root normal, berikan 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: "Kelola akun Matrix, verifikasi, perangkat, dan state profil",
        hasSubcommands: true,
      },
    ],
  },
);
Gunakan commands saja hanya saat Anda tidak membutuhkan pendaftaran CLI root yang lazy. Jalur kompatibilitas eager itu tetap didukung, tetapi tidak memasang placeholder berbasis descriptor untuk lazy loading pada waktu parse.

​
Pendaftaran backend CLI

api.registerCliBackend(...) memungkinkan plugin memiliki konfigurasi default untuk backend CLI AI lokal seperti claude-cli atau codex-cli.
  • id backend menjadi prefix provider dalam ref model seperti claude-cli/opus.
  • config backend menggunakan bentuk yang sama seperti agents.defaults.cliBackends.<id>.
  • Konfigurasi pengguna tetap menang. OpenClaw menggabungkan agents.defaults.cliBackends.<id> di atas default plugin sebelum menjalankan CLI.
  • Gunakan normalizeConfig saat backend memerlukan penulisan ulang kompatibilitas setelah penggabungan (misalnya menormalisasi bentuk flag lama).

​
Slot eksklusif

MetodeYang didaftarkan
api.registerContextEngine(id, factory)Context engine (satu aktif sekaligus)
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
  • registerMemoryPromptSection, registerMemoryFlushPlan, dan registerMemoryRuntime bersifat eksklusif untuk plugin memori.
  • registerMemoryEmbeddingProvider memungkinkan plugin memori aktif mendaftarkan satu atau lebih id adapter embedding (misalnya openai, gemini, atau id kustom yang didefinisikan plugin).
  • Konfigurasi pengguna seperti agents.defaults.memorySearch.provider dan agents.defaults.memorySearch.fallback di-resolve terhadap id adapter yang terdaftar tersebut.

​
Event dan lifecycle

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

​
Semantik keputusan hook

  • before_tool_call: mengembalikan { block: true } bersifat terminal. Setelah handler mana pun 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 handler mana pun menetapkannya, handler prioritas lebih rendah dilewati.
  • before_install: mengembalikan { block: false } diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan block), bukan sebagai override.
  • message_sending: mengembalikan { cancel: true } bersifat terminal. Setelah handler mana pun 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 konfigurasi saat ini (snapshot runtime dalam memori yang aktif bila tersedia)
api.pluginConfigRecord<string, unknown>Konfigurasi khusus plugin dari plugins.entries.<id>.config
api.runtimePluginRuntimeRuntime helpers
api.loggerPluginLoggerLogger berscope (debug, info, warn, error)
api.registrationModePluginRegistrationModeMode pemuatan saat ini; "setup-runtime" adalah jendela startup/setup ringan sebelum entri penuh
api.resolvePath(input)(string) => stringResolve 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 internal saja
  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 produksi. Arahkan impor internal melalui ./api.ts atau ./runtime-api.ts. Jalur SDK hanya merupakan kontrak eksternal.
Permukaan publik plugin bawaan yang dimuat melalui fasad (api.ts, runtime-api.ts, index.ts, setup-entry.ts, dan file entri publik serupa) sekarang mengutamakan snapshot konfigurasi runtime aktif saat OpenClaw sudah berjalan. Jika belum ada snapshot runtime, mereka fallback ke file konfigurasi di disk yang telah di-resolve. Plugin provider juga dapat mengekspos barrel kontrak lokal plugin yang sempit saat sebuah helper memang spesifik provider dan belum cocok ditempatkan dalam subpath SDK generik. Contoh bawaan saat ini: provider Anthropic menyimpan helper stream Claude-nya di seam publik api.ts / contract-api.ts miliknya sendiri alih-alih mempromosikan 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/konfigurasi
Kode produksi extension juga harus menghindari impor openclaw/plugin-sdk/<other-plugin>. Jika sebuah helper benar-benar dibagikan, promosikan ke subpath SDK netral seperti openclaw/plugin-sdk/speech, .../provider-model-shared, atau permukaan berorientasi kapabilitas lainnya alih-alih mengikat dua plugin bersama.

​
Terkait