The stable API surface for WednesdayAI plugins: the register entry, api.register* methods, api.runtime sub-APIs, and typed exports.
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:
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";export default function register(api: OpenClawPluginApi): void { // register tools, hooks, channels, routes, etc.}
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:
Member
Purpose
api.id, api.name, api.version
Plugin identity
api.source
Source/origin of this plugin (e.g. npm package name or local path)
api.description
Optional human-readable plugin description
api.config
The resolved OpenClawConfig
api.pluginConfig
This plugin’s config (Record<string, unknown> | undefined)
Use stringEnum / optionalStringEnum (exported from the SDK) for string enumerations.
Never use format as a raw property name.
import { Type } from "openclaw/plugin-sdk";import { stringEnum, optionalStringEnum } from "openclaw/plugin-sdk";const parameters = Type.Object({ mode: stringEnum(["fast", "thorough"]), region: optionalStringEnum(["us", "eu"]),});
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.
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.
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk"// Returns a Typebox schema validating as an empty object — use when your plugin has no config
File log utilities
import { appendFileLog, createFileLogWriter } from "openclaw/plugin-sdk"// Types used by these utilities (imported the same way if needed):// FileLogAppendOptions, FileLogAppendResult// Append a single line:appendFileLog(line: string, options: FileLogAppendOptions): Promise<FileLogAppendResult> | FileLogAppendResult// Create a writer for repeated use:const writer = createFileLogWriter({ file: string, profileId: string })// Note: rotation is controlled by maxFileBytes/maxBackups in the logging config, not here.writer.append(line: string): Promise<FileLogAppendResult> | FileLogAppendResultwriter.diagnostics(): unknown
AgentAvailability
interface AgentAvailability { available: boolean reason?: string // shown to users when unavailable nextAvailableAt?: string // ISO-8601 timezone?: string}
import type { PluginHookMessageReceivedEvent, PluginHookBeforeContextSendEvent, PluginHookBeforeContextSendResult, PluginHookStorageAfterAppendEvent, PluginHookCompactionPlanEvent, PluginHookCompactionPlanResult, PluginHookContextCollectEvent, PluginHookContextCollectResult, PluginHookContextProjectEvent, PluginHookContextProjectResult, PluginHookContextPruneEvent, PluginHookContextPruneResult, PluginHookTransformLlmInputEvent, PluginHookTransformLlmInputResult, PluginHookTransformLlmOutputEvent, PluginHookTransformLlmOutputResult, PluginHookModelCallEndedEvent, PluginHookAgentEndEvent, // ... event and result types for all 33 hook points are exported} from "openclaw/plugin-sdk"// PluginHookSubagentSpawningEvent is NOT exported from openclaw/plugin-sdk.// Import it from core types directly, or derive it:// type SpawningEvent = Parameters<Parameters<typeof api.on<"subagent_spawning">>[1]>[0]
Provider plugin family
// Abridged — shows the most commonly used fields.interface ProviderPlugin { id: string label: string auth: ProviderAuthMethod[] // required — authentication methods the provider supports docsPath?: string aliases?: string[] hookAliases?: string[] // hook-name aliases for this provider envVars?: string[] models?: ModelProviderConfig // model listing / capability metadata // Functional extension points (omitted here for brevity): // prepareExtraParams?, createStreamFn?, wrapStreamFn?}
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:
Do not import it from core internals — that creates a hard coupling that breaks on upgrade.
Open an issue or PR to add it to src/plugin-sdk/ with documentation.