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

Core gateway (src/)
├── Plugin SDK (src/plugin-sdk/)  ← stable, importable as `openclaw/plugin-sdk`
├── Plugins (loaded in-process)   ← tools, channels, providers, hooks, routes
└── Standalone hooks (HOOK.md)    ← side-effect automation on coarse events
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(...).

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

LayerTechnology
LanguageTypeScript 5.9, strict ESM
RuntimeNode.js 24+
Package managerpnpm 10.23
Buildtsdown + post-build tsx scripts
Type checkerpnpm tsgo (native TS checker)
TestsVitest v4 + V8 coverage
LinterOxlint v1.50

​
Plugin scopes

  • @wednesdayai/* — new extensions built for this fork. Use this for anything new.
  • @openclaw/* — inherited extensions from the fork base. Publish only if the package already exists under this scope on npm.

​
Getting started

1

Clone the repo

git clone https://github.com/ExpansionX/WednesdayAI-core.git
cd WednesdayAI-core
pnpm install
pnpm build
2

Run the tests

pnpm test:fast    # unit tests (fast)
pnpm test         # full suite
3

Build your first plugin

Follow Your first plugin for a worked example.

​
Design principles

  1. Lean core — if a capability can live in a plugin, it should.
  2. Stable contracts — plugins import from openclaw/plugin-sdk, never core internals.
  3. Pin to the fork base — plugins pin openclaw to exactly 2026.3.2.
  4. No workspace:* in dependencies — npm install --omit=dev in plugin dirs must work.
  5. Naming — user-facing text uses WednesdayAI; code, config keys, and imports use openclaw.
  6. No any in SDK exports — the plugin SDK surface must be fully typed.

​
Contributing

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