Internal arsitektur Plugin

​

Pipeline pemuatan

1. menemukan root Plugin kandidat
2. membaca manifes bundle native atau kompatibel serta metadata package
3. menolak kandidat yang tidak aman
4. menormalkan config Plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. memutuskan pengaktifan untuk setiap kandidat
6. memuat modul native yang diaktifkan: modul bawaan yang sudah dibangun menggunakan loader native; Plugin native yang belum dibangun menggunakan jiti
7. memanggil hook native register(api) dan mengumpulkan pendaftaran ke registry Plugin
8. mengekspos registry ke permukaan perintah/runtime

​

Perilaku manifest-first

• mengidentifikasi Plugin
• menemukan channel/Skills/skema config yang dideklarasikan atau kemampuan bundle
• memvalidasi plugins.entries.<id>.config
• menambah label/placeholder UI Control
• menampilkan metadata instalasi/katalog
• mempertahankan deskriptor aktivasi dan setup yang murah tanpa memuat runtime Plugin

• Pemuatan CLI dipersempit ke Plugin yang memiliki perintah utama yang diminta
• Resolusi setup/channel Plugin dipersempit ke Plugin yang memiliki id channel yang diminta
• Resolusi setup/runtime provider eksplisit dipersempit ke Plugin yang memiliki id provider yang diminta

​

Apa yang di-cache oleh loader

• hasil penemuan
• data registry manifes
• registry Plugin yang dimuat

• Setel OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 atau OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 untuk menonaktifkan cache ini.
• Sesuaikan jendela cache dengan OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS dan OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Model registry

• record Plugin (identitas, sumber, origin, status, diagnostik)
• alat
• hook legacy dan hook bertipe
• channel
• provider
• handler RPC Gateway
• rute HTTP
• registrar CLI
• layanan latar belakang
• perintah milik Plugin

• modul Plugin -> pendaftaran registry
• runtime inti -> konsumsi registry

​

Callback binding percakapan

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" atau "denied"
• decision: "allow-once", "allow-always", atau "deny"
• binding: binding hasil resolusi untuk permintaan yang disetujui
• request: ringkasan permintaan asli, petunjuk detach, id pengirim, dan metadata percakapan

​

Hook runtime provider

• Metadata manifes untuk lookup pra-runtime yang murah: providerAuthEnvVars, providerAuthAliases, providerAuthChoices, dan channelEnvVars.
• Hook saat config: catalog (legacy discovery) plus applyConfigDefaults.
• Hook runtime: 40+ hook opsional yang mencakup auth, resolusi model, pembungkusan stream, thinking levels, kebijakan replay, dan endpoint penggunaan. Lihat daftar lengkap di Hook order and usage.

​

Urutan hook dan penggunaan

​

Contoh provider

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Contoh bawaan

​

Helper runtime

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech mengembalikan payload output TTS inti normal untuk permukaan file/voice-note.
• Menggunakan konfigurasi inti messages.tts dan pemilihan provider.
• Mengembalikan buffer audio PCM + sample rate. Plugin harus melakukan resample/encode untuk provider.
• listVoices bersifat opsional per provider. Gunakan untuk picker suara atau alur setup milik vendor.
• Daftar suara dapat menyertakan metadata yang lebih kaya seperti locale, gender, dan tag personality untuk picker yang sadar-provider.
• OpenAI dan ElevenLabs mendukung telephony saat ini. Microsoft tidak.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Pertahankan kebijakan TTS, fallback, dan pengiriman balasan di inti.
• Gunakan provider speech untuk perilaku sintesis milik vendor.
• Input legacy Microsoft edge dinormalisasi ke id provider microsoft.
• Model kepemilikan yang disukai berorientasi perusahaan: satu Plugin vendor dapat memiliki provider teks, speech, gambar, dan media masa depan saat OpenClaw menambahkan kontrak kemampuan tersebut.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Pertahankan orkestrasi, fallback, config, dan wiring channel di inti.
• Pertahankan perilaku vendor di Plugin provider.
• Ekspansi aditif seharusnya tetap bertipe: metode opsional baru, field hasil opsional baru, kemampuan opsional baru.
• Pembuatan video sudah mengikuti pola yang sama:
  • inti memiliki kontrak kemampuan dan helper runtime
  • Plugin vendor mendaftarkan api.registerVideoGenerationProvider(...)
  • Plugin fitur/channel mengonsumsi api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* adalah permukaan bersama yang disukai untuk pemahaman gambar/audio/video.
• Menggunakan konfigurasi audio media-understanding inti (tools.media.audio) dan urutan fallback provider.
• Mengembalikan { text: undefined } saat tidak ada output transkripsi yang dihasilkan (misalnya input dilewati/tidak didukung).
• api.runtime.stt.transcribeAudioFile(...) tetap ada sebagai alias kompatibilitas.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider dan model adalah override per-run opsional, bukan perubahan sesi persisten.
• OpenClaw hanya menghormati field override tersebut untuk pemanggil tepercaya.
• Untuk run fallback milik Plugin, operator harus memilihnya secara opt-in dengan plugins.entries.<id>.subagent.allowModelOverride: true.
• Gunakan plugins.entries.<id>.subagent.allowedModels untuk membatasi Plugin tepercaya ke target kanonis provider/model tertentu, atau "*" untuk mengizinkan target apa pun secara eksplisit.
• Run subagen Plugin yang tidak tepercaya tetap berfungsi, tetapi permintaan override ditolak alih-alih diam-diam fallback.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Pertahankan pemilihan provider, resolusi kredensial, dan semantik permintaan bersama di inti.
• Gunakan provider web-search untuk transport pencarian khusus vendor.
• api.runtime.webSearch.* adalah permukaan bersama yang disukai untuk Plugin fitur/channel yang membutuhkan perilaku pencarian tanpa bergantung pada wrapper alat agen.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): hasilkan gambar menggunakan rantai provider image-generation yang dikonfigurasi.
• listProviders(...): daftar provider image-generation yang tersedia dan kemampuannya.

​

Rute HTTP Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: path rute di bawah server HTTP gateway.
• auth: wajib. Gunakan "gateway" untuk mewajibkan auth gateway normal, atau "plugin" untuk auth/verifikasi Webhook yang dikelola Plugin.
• match: opsional. "exact" (default) atau "prefix".
• replaceExisting: opsional. Memungkinkan Plugin yang sama mengganti pendaftaran rute miliknya sendiri yang sudah ada.
• handler: kembalikan true saat rute menangani permintaan.

• api.registerHttpHandler(...) telah dihapus dan akan menyebabkan galat pemuatan Plugin. Gunakan api.registerHttpRoute(...) sebagai gantinya.
• Rute Plugin harus mendeklarasikan auth secara eksplisit.
• Konflik path + match yang persis ditolak kecuali replaceExisting: true, dan satu Plugin tidak dapat mengganti rute milik Plugin lain.
• Rute yang tumpang tindih dengan level auth berbeda ditolak. Pertahankan rantai fallthrough exact/prefix hanya pada level auth yang sama.
• Rute auth: "plugin" tidak menerima scope runtime operator secara otomatis. Rute ini ditujukan untuk Webhook/verifikasi tanda tangan yang dikelola Plugin, bukan pemanggilan helper Gateway yang berhak istimewa.
• Rute auth: "gateway" berjalan di dalam scope runtime permintaan Gateway, tetapi scope itu sengaja konservatif:
  • auth bearer shared-secret (gateway.auth.mode = "token" / "password") mempertahankan scope runtime rute-Plugin tetap dipaku ke operator.write, bahkan jika pemanggil mengirim x-openclaw-scopes
  • mode HTTP tepercaya pembawa identitas (misalnya trusted-proxy atau gateway.auth.mode = "none" pada ingress privat) menghormati x-openclaw-scopes hanya saat header itu memang ada secara eksplisit
  • jika x-openclaw-scopes tidak ada pada permintaan rute-Plugin pembawa identitas tersebut, scope runtime fallback ke operator.write
• Aturan praktis: jangan menganggap rute Plugin ber-auth gateway sebagai permukaan admin implisit. Jika rute Anda membutuhkan perilaku khusus admin, wajibkan mode auth pembawa identitas dan dokumentasikan kontrak header x-openclaw-scopes yang eksplisit.

​

Path impor SDK Plugin

• index.js — entry Plugin bawaan
• api.js — barrel helper/tipe
• runtime-api.js — barrel khusus runtime
• setup-entry.js — entry Plugin setup

​

Skema message tool

• presentation untuk blok presentasi semantik (text, context, divider, buttons, select)
• delivery-pin untuk permintaan pengiriman yang dipin

​

Resolusi target channel

• messaging.inferTargetChatType({ to }) memutuskan apakah target ternormalisasi seharusnya diperlakukan sebagai direct, group, atau channel sebelum lookup direktori.
• messaging.targetResolver.looksLikeId(raw, normalized) memberi tahu core apakah suatu input harus langsung melompat ke resolusi mirip-id alih-alih pencarian direktori.
• messaging.targetResolver.resolveTarget(...) adalah fallback Plugin ketika core membutuhkan resolusi akhir milik provider setelah normalisasi atau setelah miss direktori.
• messaging.resolveOutboundSessionRoute(...) memiliki konstruksi rute sesi khusus provider setelah target diresolusikan.

• Gunakan inferTargetChatType untuk keputusan kategori yang seharusnya terjadi sebelum mencari peer/grup.
• Gunakan looksLikeId untuk pemeriksaan “perlakukan ini sebagai id target eksplisit/native”.
• Gunakan resolveTarget untuk fallback normalisasi khusus provider, bukan untuk pencarian direktori yang luas.
• Pertahankan id native provider seperti id chat, id thread, JID, handle, dan id room di dalam nilai target atau parameter khusus provider, bukan di field SDK generik.

​

Direktori berbasis config

• peer DM yang didorong allowlist
• peta channel/grup yang dikonfigurasi
• fallback direktori statis yang dibatasi akun

• pemfilteran kueri
• penerapan batas
• helper dedupe/normalisasi
• membangun ChannelDirectoryEntry[]

​

Katalog provider

• { provider } untuk satu entri provider
• { providers } untuk beberapa entri provider

• simple: provider biasa berbasis API-key atau env
• profile: provider yang muncul saat profil auth ada
• paired: provider yang mensintesis beberapa entri provider terkait
• late: lintasan terakhir, setelah provider implisit lain

• discovery tetap berfungsi sebagai alias legacy
• jika catalog dan discovery keduanya terdaftar, OpenClaw menggunakan catalog

​

Inspeksi channel hanya-baca

• resolveAccount(...) adalah jalur runtime. Jalur ini boleh mengasumsikan kredensial sudah sepenuhnya termaterialisasi dan dapat gagal cepat ketika secret yang diperlukan hilang.
• Jalur perintah hanya-baca seperti openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, dan alur perbaikan doctor/config seharusnya tidak perlu mematerialisasi kredensial runtime hanya untuk mendeskripsikan konfigurasi.

• Kembalikan hanya state akun yang deskriptif.
• Pertahankan enabled dan configured.
• Sertakan field sumber/status kredensial bila relevan, seperti:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Anda tidak perlu mengembalikan nilai token mentah hanya untuk melaporkan ketersediaan baca-saja. Mengembalikan tokenStatus: "available" (dan field sumber yang cocok) sudah cukup untuk perintah bergaya status.
• Gunakan configured_unavailable ketika kredensial dikonfigurasi melalui SecretRef tetapi tidak tersedia di jalur perintah saat ini.

​

Pack package

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• pendaftaran channel itu sendiri
• rute HTTP apa pun yang harus tersedia sebelum gateway mulai listening
• metode gateway, alat, atau layanan apa pun yang harus ada selama jendela yang sama

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Metadata katalog channel

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: label sekunder untuk permukaan katalog/status yang lebih kaya
• docsLabel: override teks tautan untuk tautan dokumentasi
• preferOver: id Plugin/channel prioritas lebih rendah yang seharusnya dikalahkan entri katalog ini
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: kontrol salinan permukaan pemilihan
• markdownCapable: menandai channel sebagai mampu Markdown untuk keputusan pemformatan keluar
• exposure.configured: sembunyikan channel dari permukaan daftar channel yang dikonfigurasi saat disetel ke false
• exposure.setup: sembunyikan channel dari picker setup/configure interaktif saat disetel ke false
• exposure.docs: tandai channel sebagai internal/pribadi untuk permukaan navigasi dokumentasi
• showConfigured / showInSetup: alias legacy masih diterima demi kompatibilitas; pilih exposure
• quickstartAllowFrom: memilih channel ini ke alur quickstart allowFrom standar
• forceAccountBinding: mewajibkan binding akun eksplisit bahkan ketika hanya ada satu akun
• preferSessionLookupForAnnounceTarget: memilih lookup sesi saat meresolusikan target announce

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugin mesin konteks

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", () => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Menambahkan kemampuan baru

1. definisikan kontrak inti Tentukan perilaku bersama apa yang seharusnya dimiliki core: kebijakan, fallback, penggabungan config, siklus hidup, semantik yang menghadap channel, dan bentuk helper runtime.
2. tambahkan permukaan pendaftaran/runtime Plugin yang bertipe Perluas OpenClawPluginApi dan/atau api.runtime dengan permukaan kemampuan bertipe yang paling kecil namun berguna.
3. wire konsumen core + channel/fitur Channel dan Plugin fitur seharusnya mengonsumsi kemampuan baru melalui core, bukan dengan mengimpor implementasi vendor secara langsung.
4. daftarkan implementasi vendor Plugin vendor lalu mendaftarkan backend mereka terhadap kemampuan tersebut.
5. tambahkan cakupan kontrak Tambahkan pengujian agar kepemilikan dan bentuk pendaftaran tetap eksplisit seiring waktu.

​

Checklist kemampuan

• tipe kontrak inti di src/<capability>/types.ts
• runner/helper runtime inti di src/<capability>/runtime.ts
• permukaan pendaftaran API Plugin di src/plugins/types.ts
• wiring registry Plugin di src/plugins/registry.ts
• eksposur runtime Plugin di src/plugins/runtime/* saat Plugin fitur/channel perlu mengonsumsinya
• helper capture/test di src/test-utils/plugin-registration.ts
• penegasan kepemilikan/kontrak di src/plugins/contracts/registry.ts
• dokumentasi operator/Plugin di docs/

​

Template kemampuan

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• core memiliki kontrak kemampuan + orkestrasi
• Plugin vendor memiliki implementasi vendor
• Plugin fitur/channel mengonsumsi helper runtime
• pengujian kontrak menjaga kepemilikan tetap eksplisit

​

Terkait

• Plugin architecture — model dan bentuk kemampuan publik
• Plugin SDK subpaths
• Plugin SDK setup
• Building plugins