Plugin architecture internals

​

Load pipeline

1. discover candidate plugin roots
2. read native or compatible bundle manifests and package metadata
3. reject unsafe candidates
4. normalize plugin config (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decide enablement for each candidate
6. load enabled native modules: built bundled modules use a native loader; unbuilt native plugins use jiti
7. call native register(api) hooks and collect registrations into the plugin registry
8. expose the registry to commands/runtime surfaces

​

Manifest-first behavior

• identify the plugin
• discover declared channels/skills/config schema or bundle capabilities
• validate plugins.entries.<id>.config
• augment Control UI labels/placeholders
• show install/catalog metadata
• preserve cheap activation and setup descriptors without loading plugin runtime

• CLI loading narrows to plugins that own the requested primary command
• channel setup/plugin resolution narrows to plugins that own the requested channel id
• explicit provider setup/runtime resolution narrows to plugins that own the requested provider id

​

What the loader caches

• discovery results
• manifest registry data
• loaded plugin registries

• Set OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 or OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 to disable these caches.
• Tune cache windows with OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS and OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Registry model

• plugin records (identity, source, origin, status, diagnostics)
• tools
• legacy hooks and typed hooks
• channels
• providers
• gateway RPC handlers
• HTTP routes
• CLI registrars
• background services
• plugin-owned commands

• plugin module -> registry registration
• core runtime -> registry consumption

​

Conversation binding callbacks

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" or "denied"
• decision: "allow-once", "allow-always", or "deny"
• binding: the resolved binding for approved requests
• request: the original request summary, detach hint, sender id, and conversation metadata

​

Provider runtime hooks

• Manifest metadata for cheap pre-runtime lookup: providerAuthEnvVars, providerAuthAliases, providerAuthChoices, and channelEnvVars.
• Config-time hooks: catalog (legacy discovery) plus applyConfigDefaults.
• Runtime hooks: 40+ optional hooks covering auth, model resolution, stream wrapping, thinking levels, replay policy, and usage endpoints. See the full list under Hook order and usage.

​

Hook order and usage

​

Provider example

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

​

Built-in examples

​

Runtime helpers

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 returns the normal core TTS output payload for file/voice-note surfaces.
• Uses core messages.tts configuration and provider selection.
• Returns PCM audio buffer + sample rate. Plugins must resample/encode for providers.
• listVoices is optional per provider. Use it for vendor-owned voice pickers or setup flows.
• Voice listings can include richer metadata such as locale, gender, and personality tags for provider-aware pickers.
• OpenAI and ElevenLabs support telephony today. Microsoft does not.

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

• Keep TTS policy, fallback, and reply delivery in core.
• Use speech providers for vendor-owned synthesis behavior.
• Legacy Microsoft edge input is normalized to the microsoft provider id.
• The preferred ownership model is company-oriented: one vendor plugin can own text, speech, image, and future media providers as OpenClaw adds those capability contracts.

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

• Keep orchestration, fallback, config, and channel wiring in core.
• Keep vendor behavior in the provider plugin.
• Additive expansion should stay typed: new optional methods, new optional result fields, new optional capabilities.
• Video generation already follows the same pattern:
  • core owns the capability contract and runtime helper
  • vendor plugins register api.registerVideoGenerationProvider(...)
  • feature/channel plugins consume 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.* is the preferred shared surface for image/audio/video understanding.
• Uses core media-understanding audio configuration (tools.media.audio) and provider fallback order.
• Returns { text: undefined } when no transcription output is produced (for example skipped/unsupported input).
• api.runtime.stt.transcribeAudioFile(...) remains as a compatibility alias.

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 and model are optional per-run overrides, not persistent session changes.
• OpenClaw only honors those override fields for trusted callers.
• For plugin-owned fallback runs, operators must opt in with plugins.entries.<id>.subagent.allowModelOverride: true.
• Use plugins.entries.<id>.subagent.allowedModels to restrict trusted plugins to specific canonical provider/model targets, or "*" to allow any target explicitly.
• Untrusted plugin subagent runs still work, but override requests are rejected instead of silently falling back.

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

• Keep provider selection, credential resolution, and shared request semantics in core.
• Use web-search providers for vendor-specific search transports.
• api.runtime.webSearch.* is the preferred shared surface for feature/channel plugins that need search behavior without depending on the agent tool wrapper.

​

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(...): generate an image using the configured image-generation provider chain.
• listProviders(...): list available image-generation providers and their capabilities.

​

Gateway HTTP routes

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

• path: route path under the gateway HTTP server.
• auth: required. Use "gateway" to require normal gateway auth, or "plugin" for plugin-managed auth/webhook verification.
• match: optional. "exact" (default) or "prefix".
• replaceExisting: optional. Allows the same plugin to replace its own existing route registration.
• handler: return true when the route handled the request.

• api.registerHttpHandler(...) was removed and will cause a plugin-load error. Use api.registerHttpRoute(...) instead.
• Plugin routes must declare auth explicitly.
• Exact path + match conflicts are rejected unless replaceExisting: true, and one plugin cannot replace another plugin’s route.
• Overlapping routes with different auth levels are rejected. Keep exact/prefix fallthrough chains on the same auth level only.
• auth: "plugin" routes do not receive operator runtime scopes automatically. They are for plugin-managed webhooks/signature verification, not privileged Gateway helper calls.
• auth: "gateway" routes run inside a Gateway request runtime scope, but that scope is intentionally conservative:
  • shared-secret bearer auth (gateway.auth.mode = "token" / "password") keeps plugin-route runtime scopes pinned to operator.write, even if the caller sends x-openclaw-scopes
  • trusted identity-bearing HTTP modes (for example trusted-proxy or gateway.auth.mode = "none" on a private ingress) honor x-openclaw-scopes only when the header is explicitly present
  • if x-openclaw-scopes is absent on those identity-bearing plugin-route requests, runtime scope falls back to operator.write
• Practical rule: do not assume a gateway-auth plugin route is an implicit admin surface. If your route needs admin-only behavior, require an identity-bearing auth mode and document the explicit x-openclaw-scopes header contract.

​

Plugin SDK import paths

• index.js — bundled plugin entry
• api.js — helper/types barrel
• runtime-api.js — runtime-only barrel
• setup-entry.js — setup plugin entry

​

Message tool schemas

• presentation for semantic presentation blocks (text, context, divider, buttons, select)
• delivery-pin for pinned-delivery requests

​

Channel target resolution

• messaging.inferTargetChatType({ to }) decides whether a normalized target should be treated as direct, group, or channel before directory lookup.
• messaging.targetResolver.looksLikeId(raw, normalized) tells core whether an input should skip straight to id-like resolution instead of directory search.
• messaging.targetResolver.resolveTarget(...) is the plugin fallback when core needs a final provider-owned resolution after normalization or after a directory miss.
• messaging.resolveOutboundSessionRoute(...) owns provider-specific session route construction once a target is resolved.

• Use inferTargetChatType for category decisions that should happen before searching peers/groups.
• Use looksLikeId for “treat this as an explicit/native target id” checks.
• Use resolveTarget for provider-specific normalization fallback, not for broad directory search.
• Keep provider-native ids like chat ids, thread ids, JIDs, handles, and room ids inside target values or provider-specific params, not in generic SDK fields.

​

Config-backed directories

• allowlist-driven DM peers
• configured channel/group maps
• account-scoped static directory fallbacks

• query filtering
• limit application
• deduping/normalization helpers
• building ChannelDirectoryEntry[]

​

Provider catalogs

• { provider } for one provider entry
• { providers } for multiple provider entries

• simple: plain API-key or env-driven providers
• profile: providers that appear when auth profiles exist
• paired: providers that synthesize multiple related provider entries
• late: last pass, after other implicit providers

• discovery still works as a legacy alias
• if both catalog and discovery are registered, OpenClaw uses catalog

​

Read-only channel inspection

• resolveAccount(...) is the runtime path. It is allowed to assume credentials are fully materialized and can fail fast when required secrets are missing.
• Read-only command paths such as openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, and doctor/config repair flows should not need to materialize runtime credentials just to describe configuration.

• Return descriptive account state only.
• Preserve enabled and configured.
• Include credential source/status fields when relevant, such as:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• You do not need to return raw token values just to report read-only availability. Returning tokenStatus: "available" (and the matching source field) is enough for status-style commands.
• Use configured_unavailable when a credential is configured via SecretRef but unavailable in the current command path.

​

Package packs

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

• channel registration itself
• any HTTP routes that must be available before the gateway starts listening
• any gateway methods, tools, or services that must exist during that same window

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Channel catalog metadata

{
  "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: secondary label for richer catalog/status surfaces
• docsLabel: override link text for the docs link
• preferOver: lower-priority plugin/channel ids this catalog entry should outrank
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: selection-surface copy controls
• markdownCapable: marks the channel as markdown-capable for outbound formatting decisions
• exposure.configured: hide the channel from configured-channel listing surfaces when set to false
• exposure.setup: hide the channel from interactive setup/configure pickers when set to false
• exposure.docs: mark the channel as internal/private for docs navigation surfaces
• showConfigured / showInSetup: legacy aliases still accepted for compatibility; prefer exposure
• quickstartAllowFrom: opt the channel into the standard quickstart allowFrom flow
• forceAccountBinding: require explicit account binding even when only one account exists
• preferSessionLookupForAnnounceTarget: prefer session lookup when resolving announce targets

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

​

Context engine plugins

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

​

Adding a new capability

1. define the core contract Decide what shared behavior core should own: policy, fallback, config merge, lifecycle, channel-facing semantics, and runtime helper shape.
2. add typed plugin registration/runtime surfaces Extend OpenClawPluginApi and/or api.runtime with the smallest useful typed capability surface.
3. wire core + channel/feature consumers Channels and feature plugins should consume the new capability through core, not by importing a vendor implementation directly.
4. register vendor implementations Vendor plugins then register their backends against the capability.
5. add contract coverage Add tests so ownership and registration shape stay explicit over time.

​

Capability checklist

• core contract types in src/<capability>/types.ts
• core runner/runtime helper in src/<capability>/runtime.ts
• plugin API registration surface in src/plugins/types.ts
• plugin registry wiring in src/plugins/registry.ts
• plugin runtime exposure in src/plugins/runtime/* when feature/channel plugins need to consume it
• capture/test helpers in src/test-utils/plugin-registration.ts
• ownership/contract assertions in src/plugins/contracts/registry.ts
• operator/plugin docs in docs/

​

Capability template

// 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 owns the capability contract + orchestration
• vendor plugins own vendor implementations
• feature/channel plugins consume runtime helpers
• contract tests keep ownership explicit

​

Related

• Plugin architecture — public capability model and shapes
• Plugin SDK subpaths
• Plugin SDK setup
• Building plugins