Plugin architecture internals

For the public capability model, plugin shapes, and ownership/execution contracts, see Plugin architecture. This page is the reference for the internal mechanics: load pipeline, registry, runtime hooks, Gateway HTTP routes, import paths, and schema tables.

Load pipeline

At startup, OpenClaw does roughly this:

1. discover candidate plugin roots
2. read native or compatible bundle manifests and package metadata
3. reject unsafe candidates
4. normalize plugin config (
   text

   Copy

   plugins.enabled
   ,
   text

   Copy

   allow
   ,
   text

   Copy

   deny
   ,
   text

   Copy

   entries
   ,
   text

   Copy

   slots
   ,
   text

   Copy

   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
   text

   Copy

   register(api)
   hooks and collect registrations into the plugin registry
8. expose the registry to commands/runtime surfaces

The safety gates happen before runtime execution. Candidates are blocked when the entry escapes the plugin root, the path is world-writable, or path ownership looks suspicious for non-bundled plugins.

Manifest-first behavior

The manifest is the control-plane source of truth. OpenClaw uses it to:

• identify the plugin
• discover declared channels/skills/config schema or bundle capabilities
• validate
  text

  Copy

  plugins.entries.<id>.config
• augment Control UI labels/placeholders
• show install/catalog metadata
• preserve cheap activation and setup descriptors without loading plugin runtime

For native plugins, the runtime module is the data-plane part. It registers actual behavior such as hooks, tools, commands, or provider flows.

Optional manifest

and blocks stay on the control plane. They are metadata-only descriptors for activation planning and setup discovery; they do not replace runtime registration, , or . The first live activation consumers now use manifest command, channel, and provider hints to narrow plugin loading before broader registry materialization:

• 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
• Gateway startup planning uses
  text

  Copy

  activation.onStartup
  for explicit startup imports and startup opt-outs; every plugin should declare it as OpenClaw moves away from implicit startup imports, while plugins without static capability metadata and without
  text

  Copy

  activation.onStartup
  still use the deprecated implicit startup sidecar fallback for compatibility

The activation planner exposes both an ids-only API for existing callers and a plan API for new diagnostics. Plan entries report why a plugin was selected, separating explicit

planner hints from manifest ownership fallback such as , , , , , and hooks. That reason split is the compatibility boundary: existing plugin metadata keeps working, while new code can detect broad hints or fallback behavior without changing runtime loading semantics.

Setup discovery now prefers descriptor-owned ids such as

and to narrow candidate plugins before it falls back to for plugins that still need setup-time runtime hooks. Provider setup lists use manifest , descriptor-derived setup choices, and install-catalog metadata without loading provider runtime. Explicit is a descriptor-only cutoff; omitted keeps the legacy setup-api fallback for compatibility. If more than one discovered plugin claims the same normalized setup provider or CLI backend id, setup lookup refuses the ambiguous owner instead of relying on discovery order. When setup runtime does execute, registry diagnostics report drift between / and the providers or CLI backends registered by setup-api without blocking legacy plugins.

Plugin cache boundary

OpenClaw does not cache plugin discovery results or direct manifest registry data behind wall-clock windows. Installs, manifest edits, and load-path changes must become visible on the next explicit metadata read or snapshot rebuild. The manifest file parser may keep a bounded file-signature cache keyed by the opened manifest path, inode, size, and timestamps; that cache only avoids re-parsing unchanged bytes and must not cache discovery, registry, owner, or policy answers.

The safe metadata fast path is explicit object ownership, not a hidden cache. Gateway startup hot paths should pass the current

, the derived , or an explicit manifest registry through the call chain. Config validation, startup auto-enable, plugin bootstrap, and provider selection can reuse those objects while they represent the current config and plugin inventory. Setup lookup still reconstructs manifest metadata on demand unless the specific setup path receives an explicit manifest registry; keep that as a cold-path fallback rather than adding hidden lookup caches. When the input changes, rebuild and replace the snapshot instead of mutating it or keeping historical copies. Views over the active plugin registry and bundled channel bootstrap helpers should be recomputed from the current registry/root. Short-lived maps are fine inside one call to dedupe work or guard reentry; they must not become process metadata caches.

For plugin loading, the persistent cache layer is runtime loading. It may reuse loader state when code or installed artifacts are actually loaded, such as:

• text

  Copy

  PluginLoaderCacheState
  and compatible active runtime registries
• jiti/module caches and public-surface loader caches used to avoid importing the same runtime surface repeatedly
• runtime dependency mirrors and filesystem caches for installed plugin artifacts
• short-lived per-call maps for path normalization or duplicate resolution

Those caches are data-plane implementation details. They must not answer control-plane questions such as "which plugin owns this provider?" unless the caller deliberately asked for runtime loading.

Do not add persistent or wall-clock caches for:

• discovery results
• direct manifest registries
• manifest registries reconstructed from the installed plugin index
• provider owner lookup, model suppression, provider policy, or public-artifact metadata
• any other manifest-derived answer where a changed manifest, installed index, or load path should be visible on the next metadata read

Callers that rebuild manifest metadata from the persisted installed plugin index reconstruct that registry on demand. The installed index is durable source-plane state; it is not a hidden in-process metadata cache.

Registry model

Loaded plugins do not directly mutate random core globals. They register into a central plugin registry.

The registry tracks:

• 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

Core features then read from that registry instead of talking to plugin modules directly. This keeps loading one-way:

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

That separation matters for maintainability. It means most core surfaces only need one integration point: "read the registry", not "special-case every plugin module".

Conversation binding callbacks

Plugins that bind a conversation can react when an approval is resolved.

Use

to receive a callback after a bind request is approved or denied:

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

Callback payload fields:

• text

  Copy

  status
  :
  text

  Copy

  "approved"
  or
  text

  Copy

  "denied"
• text

  Copy

  decision
  :
  text

  Copy

  "allow-once"
  ,
  text

  Copy

  "allow-always"
  , or
  text

  Copy

  "deny"
• text

  Copy

  binding
  : the resolved binding for approved requests
• text

  Copy

  request
  : the original request summary, detach hint, sender id, and conversation metadata

This callback is notification-only. It does not change who is allowed to bind a conversation, and it runs after core approval handling finishes.

Provider runtime hooks

Provider plugins have three layers:

• Manifest metadata for cheap pre-runtime lookup:
  text

  Copy

  setup.providers[].envVars
  , deprecated compatibility
  text

  Copy

  providerAuthEnvVars
  ,
  text

  Copy

  providerAuthAliases
  ,
  text

  Copy

  providerAuthChoices
  , and
  text

  Copy

  channelEnvVars
  .
• Config-time hooks:
  text

  Copy

  catalog
  (legacy
  text

  Copy

  discovery
  ) plus
  text

  Copy

  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.

OpenClaw still owns the generic agent loop, failover, transcript handling, and tool policy. These hooks are the extension surface for provider-specific behavior without needing a whole custom inference transport.

Use manifest

when the provider has env-based credentials that generic auth/status/model-picker paths should see without loading plugin runtime. Deprecated is still read by the compatibility adapter during the deprecation window, and non-bundled plugins that use it receive a manifest diagnostic. Use manifest when one provider id should reuse another provider id's env vars, auth profiles, config-backed auth, and API-key onboarding choice. Use manifest when onboarding/auth-choice CLI surfaces should know the provider's choice id, group labels, and simple one-flag auth wiring without loading provider runtime. Keep provider runtime for operator-facing hints such as onboarding labels or OAuth client-id/client-secret setup vars.

Use manifest

when a channel has env-driven auth or setup that generic shell-env fallback, config/status checks, or setup prompts should see without loading channel runtime.

Hook order and usage

For model/provider plugins, OpenClaw calls hooks in this rough order. The "When to use" column is the quick decision guide. Compatibility-only provider fields that OpenClaw no longer calls, such as

and , are intentionally not listed here.

, , and first check the matched provider plugin, then fall through other hook-capable provider plugins until one actually changes the model id or transport/config. That keeps alias/compat provider shims working without requiring the caller to know which bundled plugin owns the rewrite. If no provider hook rewrites a supported Google-family config entry, the bundled Google config normalizer still applies that compatibility cleanup.

If the provider needs a fully custom wire protocol or custom request executor, that is a different class of extension. These hooks are for provider behavior that still runs on OpenClaw's normal inference loop.

Provider example

ts
Copy
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

Bundled provider plugins combine the hooks above to fit each vendor's catalog, auth, thinking, replay, and usage needs. The authoritative hook set lives with each plugin under

; this page illustrates the shapes rather than mirroring the list.

Pass-through catalog providers

OAuth and usage endpoint providers

Replay and transcript cleanup families

Catalog-only providers

Anthropic-specific stream helpers

Runtime helpers

Plugins can access selected core helpers via

. For TTS:

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

Notes:

• text

  Copy

  textToSpeech
  returns the normal core TTS output payload for file/voice-note surfaces.
• Uses core
  text

  Copy

  messages.tts
  configuration and provider selection.
• Returns PCM audio buffer + sample rate. Plugins must resample/encode for providers.
• text

  Copy

  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.

Plugins can also register speech providers via

.

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

Notes:

• Keep TTS policy, fallback, and reply delivery in core.
• Use speech providers for vendor-owned synthesis behavior.
• Legacy Microsoft
  text

  Copy

  edge
  input is normalized to the
  text

  Copy

  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.

For image/audio/video understanding, plugins register one typed media-understanding provider instead of a generic key/value bag:

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

Notes:

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

    Copy

    api.registerVideoGenerationProvider(...)
  • feature/channel plugins consume
    text

    Copy

    api.runtime.videoGeneration.*

For media-understanding runtime helpers, plugins can call:

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

For audio transcription, plugins can use either the media-understanding runtime or the older STT alias:

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

Notes:

• text

  Copy

  api.runtime.mediaUnderstanding.*
  is the preferred shared surface for image/audio/video understanding.
• Uses core media-understanding audio configuration (
  text

  Copy

  tools.media.audio
  ) and provider fallback order.
• Returns
  text

  Copy

  { text: undefined }
  when no transcription output is produced (for example skipped/unsupported input).
• text

  Copy

  api.runtime.stt.transcribeAudioFile(...)
  remains as a compatibility alias.

Plugins can also launch background subagent runs through

:

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

Notes:

• text

  Copy

  provider
  and
  text

  Copy

  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
  text

  Copy

  plugins.entries.<id>.subagent.allowModelOverride: true
  .
• Use
  text

  Copy

  plugins.entries.<id>.subagent.allowedModels
  to restrict trusted plugins to specific canonical
  text

  Copy

  provider/model
  targets, or
  text

  Copy

  "*"
  to allow any target explicitly.
• Untrusted plugin subagent runs still work, but override requests are rejected instead of silently falling back.
• Plugin-created subagent sessions are tagged with the creating plugin id. Fallback
  text

  Copy

  api.runtime.subagent.deleteSession(...)
  may delete those owned sessions only; arbitrary session deletion still requires an admin-scoped Gateway request.

For web search, plugins can consume the shared runtime helper instead of reaching into the agent tool wiring:

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

Plugins can also register web-search providers via

.

Notes:

• Keep provider selection, credential resolution, and shared request semantics in core.
• Use web-search providers for vendor-specific search transports.
• text

  Copy

  api.runtime.webSearch.*
  is the preferred shared surface for feature/channel plugins that need search behavior without depending on the agent tool wrapper.

text

Copy

api.runtime.imageGeneration

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

• text

  Copy

  generate(...)
  : generate an image using the configured image-generation provider chain.
• text

  Copy

  listProviders(...)
  : list available image-generation providers and their capabilities.

Gateway HTTP routes

Plugins can expose HTTP endpoints with

.

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

Route fields:

• text

  Copy

  path
  : route path under the gateway HTTP server.
• text

  Copy

  auth
  : required. Use
  text

  Copy

  "gateway"
  to require normal gateway auth, or
  text

  Copy

  "plugin"
  for plugin-managed auth/webhook verification.
• text

  Copy

  match
  : optional.
  text

  Copy

  "exact"
  (default) or
  text

  Copy

  "prefix"
  .
• text

  Copy

  replaceExisting
  : optional. Allows the same plugin to replace its own existing route registration.
• text

  Copy

  handler
  : return
  text

  Copy

  true
  when the route handled the request.

Notes:

• text

  Copy

  api.registerHttpHandler(...)
  was removed and will cause a plugin-load error. Use
  text

  Copy

  api.registerHttpRoute(...)
  instead.
• Plugin routes must declare
  text

  Copy

  auth
  explicitly.
• Exact
  text

  Copy

  path + match
  conflicts are rejected unless
  text

  Copy

  replaceExisting: true
  , and one plugin cannot replace another plugin's route.
• Overlapping routes with different
  text

  Copy

  auth
  levels are rejected. Keep
  text

  Copy

  exact
  /
  text

  Copy

  prefix
  fallthrough chains on the same auth level only.
• text

  Copy

  auth: "plugin"
  routes do not receive operator runtime scopes automatically. They are for plugin-managed webhooks/signature verification, not privileged Gateway helper calls.
• text

  Copy

  auth: "gateway"
  routes run inside a Gateway request runtime scope, but that scope is intentionally conservative:
  • shared-secret bearer auth (
    text

    Copy

    gateway.auth.mode = "token"
    /
    text

    Copy

    "password"
    ) keeps plugin-route runtime scopes pinned to
    text

    Copy

    operator.write
    , even if the caller sends
    text

    Copy

    x-openclaw-scopes
  • trusted identity-bearing HTTP modes (for example
    text

    Copy

    trusted-proxy
    or
    text

    Copy

    gateway.auth.mode = "none"
    on a private ingress) honor
    text

    Copy

    x-openclaw-scopes
    only when the header is explicitly present
  • if
    text

    Copy

    x-openclaw-scopes
    is absent on those identity-bearing plugin-route requests, runtime scope falls back to
    text

    Copy

    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
  text

  Copy

  x-openclaw-scopes
  header contract.

Plugin SDK import paths

Use narrow SDK subpaths instead of the monolithic

root barrel when authoring new plugins. Core subpaths:

Channel plugins pick from a family of narrow seams —

, , , , , , , , , , , , , , and . Approval behavior should consolidate on one contract rather than mixing across unrelated plugin fields. See Channel plugins.

Runtime and config helpers live under matching focused

subpaths (, , , , , , , , , etc.). Prefer , , , and instead of the broad compatibility barrel.

Repo-internal entry points (per bundled plugin package root):

• text

  Copy

  index.js
  — bundled plugin entry
• text

  Copy

  api.js
  — helper/types barrel
• text

  Copy

  runtime-api.js
  — runtime-only barrel
• text

  Copy

  setup-entry.js
  — setup plugin entry

External plugins should only import

subpaths. Never import another plugin package's from core or from another plugin. Facade-loaded entry points prefer the active runtime config snapshot when one exists, then fall back to the resolved config file on disk.

Capability-specific subpaths such as

, , and exist because bundled plugins use them today. They are not automatically long-term frozen external contracts — check the relevant SDK reference page when relying on them.

Message tool schemas

Plugins should own channel-specific

schema contributions for non-message primitives such as reactions, reads, and polls. Shared send presentation should use the generic contract instead of provider-native button, component, block, or card fields. See Message Presentation for the contract, fallback rules, provider mapping, and plugin author checklist.

Send-capable plugins declare what they can render through message capabilities:

• text

  Copy

  presentation
  for semantic presentation blocks (
  text

  Copy

  text
  ,
  text

  Copy

  context
  ,
  text

  Copy

  divider
  ,
  text

  Copy

  buttons
  ,
  text

  Copy

  select
  )
• text

  Copy

  delivery-pin
  for pinned-delivery requests

Core decides whether to render the presentation natively or degrade it to text. Do not expose provider-native UI escape hatches from the generic message tool. Deprecated SDK helpers for legacy native schemas remain exported for existing third-party plugins, but new plugins should not use them.

Channel target resolution

Channel plugins should own channel-specific target semantics. Keep the shared outbound host generic and use the messaging adapter surface for provider rules:

• text

  Copy

  messaging.inferTargetChatType({ to })
  decides whether a normalized target should be treated as
  text

  Copy

  direct
  ,
  text

  Copy

  group
  , or
  text

  Copy

  channel
  before directory lookup.
• text

  Copy

  messaging.targetResolver.looksLikeId(raw, normalized)
  tells core whether an input should skip straight to id-like resolution instead of directory search.
• text

  Copy

  messaging.targetResolver.resolveTarget(...)
  is the plugin fallback when core needs a final provider-owned resolution after normalization or after a directory miss.
• text

  Copy

  messaging.resolveOutboundSessionRoute(...)
  owns provider-specific session route construction once a target is resolved.

Recommended split:

• Use
  text

  Copy

  inferTargetChatType
  for category decisions that should happen before searching peers/groups.
• Use
  text

  Copy

  looksLikeId
  for "treat this as an explicit/native target id" checks.
• Use
  text

  Copy

  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
  text

  Copy

  target
  values or provider-specific params, not in generic SDK fields.

Config-backed directories

Plugins that derive directory entries from config should keep that logic in the plugin and reuse the shared helpers from

.

Use this when a channel needs config-backed peers/groups such as:

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

The shared helpers in

only handle generic operations:

• query filtering
• limit application
• deduping/normalization helpers
• building
  text

  Copy

  ChannelDirectoryEntry[]

Channel-specific account inspection and id normalization should stay in the plugin implementation.

Provider catalogs

Provider plugins can define model catalogs for inference with

.

returns the same shape OpenClaw writes into :

• text

  Copy

  { provider }
  for one provider entry
• text

  Copy

  { providers }
  for multiple provider entries

Use

when the plugin owns provider-specific model ids, base URL defaults, or auth-gated model metadata.

controls when a plugin's catalog merges relative to OpenClaw's built-in implicit providers:

• text

  Copy

  simple
  : plain API-key or env-driven providers
• text

  Copy

  profile
  : providers that appear when auth profiles exist
• text

  Copy

  paired
  : providers that synthesize multiple related provider entries
• text

  Copy

  late
  : last pass, after other implicit providers

Later providers win on key collision, so plugins can intentionally override a built-in provider entry with the same provider id.

Compatibility:

• text

  Copy

  discovery
  still works as a legacy alias
• if both
  text

  Copy

  catalog
  and
  text

  Copy

  discovery
  are registered, OpenClaw uses
  text

  Copy

  catalog

Read-only channel inspection

If your plugin registers a channel, prefer implementing

alongside .

Why:

• text

  Copy

  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
  text

  Copy

  openclaw status
  ,
  text

  Copy

  openclaw status --all
  ,
  text

  Copy

  openclaw channels status
  ,
  text

  Copy

  openclaw channels resolve
  , and doctor/config repair flows should not need to materialize runtime credentials just to describe configuration.

Recommended

behavior:

• Return descriptive account state only.
• Preserve
  text

  Copy

  enabled
  and
  text

  Copy

  configured
  .
• Include credential source/status fields when relevant, such as:
  • text

    Copy

    tokenSource
    ,
    text

    Copy

    tokenStatus
  • text

    Copy

    botTokenSource
    ,
    text

    Copy

    botTokenStatus
  • text

    Copy

    appTokenSource
    ,
    text

    Copy

    appTokenStatus
  • text

    Copy

    signingSecretSource
    ,
    text

    Copy

    signingSecretStatus
• You do not need to return raw token values just to report read-only availability. Returning
  text

  Copy

  tokenStatus: "available"
  (and the matching source field) is enough for status-style commands.
• Use
  text

  Copy

  configured_unavailable
  when a credential is configured via SecretRef but unavailable in the current command path.

This lets read-only commands report "configured but unavailable in this command path" instead of crashing or misreporting the account as not configured.

Package packs

A plugin directory may include a

with :

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

Each entry becomes a plugin. If the pack lists multiple extensions, the plugin id becomes

.

If your plugin imports npm deps, install them in that directory so

is available ( / ).

Security guardrail: every

entry must stay inside the plugin directory after symlink resolution. Entries that escape the package directory are rejected.

Security note:

installs plugin dependencies with a project-local (no lifecycle scripts, no dev dependencies at runtime), ignoring inherited global npm install settings. Keep plugin dependency trees "pure JS/TS" and avoid packages that require builds.

Optional:

can point at a lightweight setup-only module. When OpenClaw needs setup surfaces for a disabled channel plugin, or when a channel plugin is enabled but still unconfigured, it loads instead of the full plugin entry. This keeps startup and setup lighter when your main plugin entry also wires tools, hooks, or other runtime-only code.

Optional:

can opt a channel plugin into the same path during the gateway's pre-listen startup phase, even when the channel is already configured.

Use this only when

fully covers the startup surface that must exist before the gateway starts listening. In practice, that means the setup entry must register every channel-owned capability that startup depends on, such as:

• 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

If your full entry still owns any required startup capability, do not enable this flag. Keep the plugin on the default behavior and let OpenClaw load the full entry during startup.

Bundled channels can also publish setup-only contract-surface helpers that core can consult before the full channel runtime is loaded. The current setup promotion surface is:

• text

  Copy

  singleAccountKeysToMove
• text

  Copy

  namedAccountPromotionKeys
• text

  Copy

  resolveSingleAccountPromotionTarget(...)

Core uses that surface when it needs to promote a legacy single-account channel config into

without loading the full plugin entry. Matrix is the current bundled example: it moves only auth/bootstrap keys into a named promoted account when named accounts already exist, and it can preserve a configured non-canonical default-account key instead of always creating .

Those setup patch adapters keep bundled contract-surface discovery lazy. Import time stays light; the promotion surface is loaded only on first use instead of re-entering bundled channel startup on module import.

When those startup surfaces include gateway RPC methods, keep them on a plugin-specific prefix. Core admin namespaces (

, , , ) remain reserved and always resolve to , even if a plugin requests a narrower scope.

Example:

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

Channel catalog metadata

Channel plugins can advertise setup/discovery metadata via

and install hints via . This keeps the core catalog data-free.

Example:

json
Copy
{
  "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"
    }
  }
}

Useful

fields beyond the minimal example:

• text

  Copy

  detailLabel
  : secondary label for richer catalog/status surfaces
• text

  Copy

  docsLabel
  : override link text for the docs link
• text

  Copy

  preferOver
  : lower-priority plugin/channel ids this catalog entry should outrank
• text

  Copy

  selectionDocsPrefix
  ,
  text

  Copy

  selectionDocsOmitLabel
  ,
  text

  Copy

  selectionExtras
  : selection-surface copy controls
• text

  Copy

  markdownCapable
  : marks the channel as markdown-capable for outbound formatting decisions
• text

  Copy

  exposure.configured
  : hide the channel from configured-channel listing surfaces when set to
  text

  Copy

  false
• text

  Copy

  exposure.setup
  : hide the channel from interactive setup/configure pickers when set to
  text

  Copy

  false
• text

  Copy

  exposure.docs
  : mark the channel as internal/private for docs navigation surfaces
• text

  Copy

  showConfigured
  /
  text

  Copy

  showInSetup
  : legacy aliases still accepted for compatibility; prefer
  text

  Copy

  exposure
• text

  Copy

  quickstartAllowFrom
  : opt the channel into the standard quickstart
  text

  Copy

  allowFrom
  flow
• text

  Copy

  forceAccountBinding
  : require explicit account binding even when only one account exists
• text

  Copy

  preferSessionLookupForAnnounceTarget
  : prefer session lookup when resolving announce targets

OpenClaw can also merge external channel catalogs (for example, an MPM registry export). Drop a JSON file at one of:

• text

  Copy

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

  Copy

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

  Copy

  ~/.openclaw/plugins/catalog.json

Or point

(or ) at one or more JSON files (comma/semicolon/-delimited). Each file should contain . The parser also accepts or as legacy aliases for the key.

Generated channel catalog entries and provider install catalog entries expose normalized install-source facts next to the raw

block. The normalized facts identify whether the npm spec is an exact version or floating selector, whether expected integrity metadata is present, and whether a local source path is also available. When the catalog/package identity is known, the normalized facts warn if the parsed npm package name drifts from that identity. They also warn when is invalid or points at a source that is not available, and when npm integrity metadata is present without a valid npm source. Consumers should treat as an additive optional field so hand-built entries and catalog shims do not have to synthesize it. This lets onboarding and diagnostics explain source-plane state without importing plugin runtime.

Official external npm entries should prefer an exact

plus . Bare package names and dist-tags still work for compatibility, but they surface source-plane warnings so the catalog can move toward pinned, integrity-checked installs without breaking existing plugins. When onboarding installs from a local catalog path, it records a managed plugin plugin index entry with and a workspace-relative when possible. The absolute operational load path stays in ; the install record avoids duplicating local workstation paths into long-lived config. This keeps local development installs visible to source-plane diagnostics without adding a second raw filesystem-path disclosure surface. The persisted plugin index is the install source of truth and can be refreshed without loading plugin runtime modules. Its map is durable even when a plugin manifest is missing or invalid; its array is a rebuildable manifest view.

Context engine plugins

Context engine plugins own session context orchestration for ingest, assembly, and compaction. Register them from your plugin with

, then select the active engine with .

Use this when your plugin needs to replace or extend the default context pipeline rather than just add memory search or hooks.

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

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    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 };
    },
  }));
}

The factory

exposes optional , , and values for construction-time initialization.

If your engine does not own the compaction algorithm, keep

implemented and delegate it explicitly:

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

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    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

When a plugin needs behavior that does not fit the current API, do not bypass the plugin system with a private reach-in. Add the missing capability.

Recommended sequence:

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
   text

   Copy

   OpenClawPluginApi
   and/or
   text

   Copy

   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.

This is how OpenClaw stays opinionated without becoming hardcoded to one provider's worldview. See the Capability Cookbook for a concrete file checklist and worked example.

Capability checklist

When you add a new capability, the implementation should usually touch these surfaces together:

• core contract types in
  text

  Copy

  src/<capability>/types.ts
• core runner/runtime helper in
  text

  Copy

  src/<capability>/runtime.ts
• plugin API registration surface in
  text

  Copy

  src/plugins/types.ts
• plugin registry wiring in
  text

  Copy

  src/plugins/registry.ts
• plugin runtime exposure in
  text

  Copy

  src/plugins/runtime/*
  when feature/channel plugins need to consume it
• capture/test helpers in
  text

  Copy

  src/test-utils/plugin-registration.ts
• ownership/contract assertions in
  text

  Copy

  src/plugins/contracts/registry.ts
• operator/plugin docs in
  text

  Copy

  docs/

If one of those surfaces is missing, that is usually a sign the capability is not fully integrated yet.

Capability template

Minimal pattern:

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

Contract test pattern:

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

That keeps the rule simple:

• 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