Skip to main content

Plugin SDK

The plugin SDK is the stable API surface for WednesdayAI extensions. Plugins import from openclaw/plugin-sdk — never from core internals or relative paths into src/.

Installation

Add openclaw as a dev/peer dependency. Use wednesdayai (the primary package name) or openclaw (the backward-compatible alias — both resolve to the same package):
Never add openclaw to dependencies — the gateway provides it at runtime.

The plugin entry

A plugin module exports a default register function (sync or async) that receives the OpenClawPluginApi:
A plugin may instead export an OpenClawPluginDefinition object with a register (or activate) method and optional id / name / configSchema / ownsCompaction fields. Both forms are accepted.

The api object

OpenClawPluginApi is what your register function receives. Key fields and methods:

api.runtime sub-APIs

api.runtime exposes vetted runtime capabilities so plugins never reach into core internals:
resolveStateDir is no longer exported as a top-level SDK symbol. Resolve the state directory via api.runtime.state.resolveStateDir() instead.

Tool parameter schemas (typebox)

Tool parameters use @sinclair/typebox. Pin it to exactly 0.34.48:
Schema constraints:
  • No Type.Union, anyOf, oneOf, or allOf.
  • Use Type.Optional(...) instead of ... | null.
  • Use stringEnum / optionalStringEnum (exported from the SDK) for string enumerations.
  • Never use format as a raw property name.

Commonly used exports

These are exported from openclaw/plugin-sdk and are safe to depend on:
  • Types — OpenClawPluginApi, OpenClawPluginDefinition, AnyAgentTool, ChannelPlugin (and the Channel*Adapter family), PluginRuntime, OpenClawConfig, the Analysis* types, the AgentSignal* types, AgentAvailability, RealtimeVoiceProviderPlugin, RealtimeVoiceBridge (direct return type of createBridge()), RealtimeVoiceBridgeSession, ProviderPlugin, GatewayRequestHandler, GatewayRequestHandlerOptions, RespondFn, WebSearchProviderPlugin, WebSearchProviderToolDefinition, WebSearchProviderContext.
  • Hook payload types — PluginHookMessageReceivedEvent, PluginHookBeforeContextSendEvent, PluginHookBeforeContextSendResult, PluginHookStorageAfterAppendEvent, PluginHookCompactionPlanEvent, PluginHookCompactionPlanResult, PluginHookContextCollectEvent, PluginHookContextCollectResult, PluginHookContextProjectEvent, PluginHookContextProjectResult, PluginHookContextPruneEvent, PluginHookContextPruneResult, PluginHookTransformLlmInputEvent, PluginHookTransformLlmInputResult, PluginHookTransformLlmOutputEvent, PluginHookTransformLlmOutputResult, PluginHookModelCallEndedEvent, PluginHookAgentEndEvent, and more. The SDK exports event and result types for most of the 33 hook points. Exception: PluginHookSubagentSpawningEvent is not exported from openclaw/plugin-sdk; use import type from core types directly, or derive the type with the Parameters<...> pattern.
  • Tool helpers — jsonResult, readStringParam, readNumberParam, readReactionParams, createActionGate, ToolAuthorizationError.
  • Schema helpers — stringEnum, optionalStringEnum, emptyPluginConfigSchema.
  • Logging — createSubsystemLogger, getChildLogger, appendFileLog, createFileLogWriter.
  • Config/secrets — loadConfig, isSecretRef, SecretInput / SecretRef types.
  • HTTP/webhooks — registerPluginHttpRoute, registerWebhookTarget, registerWebhookTargetWithPluginRoute (standalone function — not an api method), request-guard helpers (fetchWithSsrFGuard, GuardedFetchOptions, GuardedFetchResult).
  • Diagnostics builders — taskDiagnostic, dreamDiagnostic (input-shaped; no ts/seq). Prefer these over casting loose objects into emitDiagnosticEvent. Live fields: passId (not passName), attempts (not attempt). OTel exports openclaw.task.* / openclaw.dream.* spans when diagnostics-otel is enabled.
ToolDefinition, inputSchema, run(), HookContext, and PluginDefinition.tools[] do not exist in this SDK. Tools are AnyAgentTool objects with parameters and execute(_id, params), registered via api.registerTool(...). Hooks are registered via api.on(...).

Type reference

Full definitions for types introduced in this SDK. Import all of these from openclaw/plugin-sdk.

Plugin registration types

Config helpers

File log utilities

AgentAvailability

Gateway types

Web search provider types

Hook payload types

Provider plugin family

Manifest vs package.json key

Two related-but-distinct things both use the word “openclaw”:
  • openclaw.plugin.json — the manifest at the plugin root. Carries id and configSchema and is used to validate config without executing plugin code. Required for every plugin. See the manifest reference.
  • package.json "openclaw" key — used for workspace/pack discovery (for example the id, or extensions for a multi-plugin pack).
A typical published plugin ships both: the package.json "openclaw" key for discovery, and openclaw.plugin.json for config validation.

Extending the SDK surface

When you need a type or contract that is not yet exported:
  1. Do not import it from core internals — that creates a hard coupling that breaks on upgrade.
  2. Open an issue or PR to add it to src/plugin-sdk/ with documentation.
  3. Keep exports typed. No any in the SDK surface.
See Contributing for the workflow.

What’s next