Skip to main content

Developer overview

WednesdayAI is built to be extended. The core is intentionally lean; new capabilities belong in plugins, hooks, and channel adapters rather than in core.

Architecture

Key principle: everything that can be a plugin, should be. Plugins and hooks interact with the gateway through the stable SDK contract; they do not import from core internals.

What a plugin can register

A plugin’s register(api) function can attach any of the following. Each has a dedicated api.register* (or api.on) method on the OpenClawPluginApi:

Agent tools

Actions the AI can invoke. api.registerTool(...).

Lifecycle hooks

Typed runtime callbacks — transform LLM input/output, gate tools, shape context. api.on(...).

Context engine hooks

Collect, project, and prune per-turn context. api.on("context.collect", ...) and friends.

Channel adapters

A new messaging platform. api.registerChannel(...).

Providers

Model providers and their auth methods. api.registerProvider(...).

HTTP routes + gateway methods

Custom endpoints and RPC methods. api.registerHttpRoute(...) / api.registerGatewayMethod(...).

Commands

Chat commands that bypass the LLM, and CLI commands. api.registerCommand(...) / api.registerCli(...).

Services

Start/stop background services. api.registerService(...).

Storage + search providers

Session store backends and web-search providers. api.registerSessionStoreAdapter(...) / api.registerWebSearchProvider(...).
Standalone HOOK.md hooks are a separate, simpler system for side-effect automation on coarse events (/new, /reset, gateway start).

api.runtime

Plugins reach vetted runtime capabilities through api.runtime instead of importing core internals. Highlights:
  • runtime.analysis — focused plugin-owned LLM analysis (guide)
  • runtime.signals — Agent Signals for non-user stimuli (guide)
  • runtime.state.resolveStateDir() — resolve the plugin state directory
  • runtime.config, runtime.media, runtime.tts / runtime.stt, runtime.system, runtime.events, runtime.logging
See the Plugin SDK reference for the full surface.

Plugin discovery and precedence

The gateway scans for plugins in this order, and the first match for a given id wins (lower-precedence copies are ignored):
  1. Config paths — plugins.load.paths (file or directory)
  2. Workspace extensions — <workspace>/.openclaw/extensions/
  3. Global extensions — ~/.openclaw/extensions/ (where managed installs live)
  4. Bundled extensions — shipped with WednesdayAI, disabled by default
Bundled plugins must be enabled explicitly (openclaw plugins enable <id>). Plugins installed via openclaw plugins install land in the global extensions directory and are enabled by default.
Never add the bundled extension path to plugins.load.paths. The bundled copy has no runtime dependencies installed; only the managed copy under ~/.openclaw/extensions/ does.

Tech stack and getting started

See Coding style for the toolchain, and Contributing for setup and the PR workflow. To build a plugin, follow Your first plugin.

Design principles

  1. Lean core — if a capability can live in a plugin, it should.
  2. Stable contracts — plugins import from wednesdayai/plugin-sdk (alias openclaw/plugin-sdk), never core internals.
  3. No workspace:* in dependencies — npm install --omit=dev in plugin dirs must work.
  4. No any in SDK exports — the plugin SDK surface must be fully typed.
Fork-base pinning, package scopes, and naming conventions are covered in Contributing.

Contributing

See Contributing for the full workflow, PR checklist, and maintainer guidelines.