nyrn
/
openclaw
mirror of https://github.com/openclaw/openclaw.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs(plugins): add SDK reference and how-to guide pages (#52366) 

* docs(plugins): add SDK reference and how-to guide pages

Create 7 new plugin SDK documentation pages:
- sdk-overview: import map, registration API reference
- sdk-entrypoints: definePluginEntry/defineChannelPluginEntry reference
- sdk-runtime: api.runtime namespace reference
- sdk-setup: packaging, manifests, config schemas reference
- sdk-channel-plugins: step-by-step channel plugin how-to
- sdk-provider-plugins: step-by-step provider plugin how-to
- sdk-testing: test utilities and patterns reference

Restructure plugin docs navigation with nested groups:
- Top-level: user-facing pages (Install, Community, Bundles)
- Building Plugins: Getting Started, Channel, Provider
- SDK Reference: Overview, Entry Points, Runtime, Setup, Testing, Migration, Manifest, Internals

Revise existing pages for new IA:
- building-plugins.md: tightened as quick-start, routes to detailed guides
- architecture.md: updated info box with links to new guides
- sdk-migration.md: expanded Related section

* docs(plugins): add Mintlify components (Steps, CodeGroup, Tabs, Accordion, CardGroup)

- Channel plugin guide: wrap walkthrough in Steps, use CodeGroup for
  package.json/manifest, Accordion for createChatChannelPlugin details,
  CardGroup for advanced topics
- Provider plugin guide: wrap walkthrough in Steps, use CodeGroup for
  package files, Tabs for hook examples, Accordion for all-hooks reference
- Getting started: use CardGroup for plugin-type picker and next steps,
  CodeGroup for package/manifest
- SDK Overview: wrap subpath tables in AccordionGroup for scannability

* fix(docs): address PR review feedback on plugin SDK pages

- Remove nonexistent api.runtime.channel.handleInboundMessage call,
  replace with realistic webhook pattern and note about channel-specific
  inbound handling (issue a)
- Fix registrationMode values: 'setup' -> 'setup-only' and 'setup-runtime'
  matching actual PluginRegistrationMode type (issue b)
- Fix createOptionalChannelSetupSurface params: channelId -> channel,
  add required label field (issue c)
- Fix broken anchor links: #multi-capability-providers ->
  #step-5-add-extra-capabilities, #plugin-kinds -> #registration-api (issue d)
- Add missing acmeChatApi import in channel plugin example (issue e)
- Fix undefined provider variable in provider test example (issue f)

* fix(docs): use correct createProviderApiKeyAuthMethod options

Replace incorrect params (provider, validate) with actual required fields
(providerId, methodId, optionKey, flagName, promptMessage) matching
src/plugins/provider-api-key-auth.ts.

* fix(docs): address second round of PR review feedback

- Add required model fields (reasoning, input, cost, contextWindow,
  maxTokens) to catalog example (issue b)
- Fix buildChannelConfigSchema to take a Zod schema argument (issue c)
- Replace fabricated setupWizard steps/run with real ChannelSetupWizard
  contract (channel, status, credentials) (issue d)
- Add required sessionFile/workspaceDir to runEmbeddedPiAgent (issue e)
- Fix wrapStreamFn to return StreamFn from ctx.streamFn (issue f)
This commit is contained in:
Vincent Koc 2026-03-22 11:35:53 -07:00 committed by GitHub
parent 1ed40cdf54
commit 28838802d4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 1982 additions and 1170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/docs.json
View File

@ -1037,24 +1037,29 @@
"group": "Plugins",
"pages": [
"tools/plugin",
"plugins/building-plugins",
"plugins/community",
"plugins/bundles",
"plugins/manifest",
"plugins/sdk-migration",
"plugins/architecture"
]
},
{
"group": "Plugin SDK",
"pages": [
"plugins/sdk-overview",
"plugins/sdk-entrypoints",
"plugins/sdk-runtime",
"plugins/sdk-setup",
"plugins/sdk-channel-plugins",
"plugins/sdk-provider-plugins",
"plugins/sdk-testing"
{
"group": "Building Plugins",
"pages": [
"plugins/building-plugins",
"plugins/sdk-channel-plugins",
"plugins/sdk-provider-plugins"
]
},
{
"group": "SDK Reference",
"pages": [
"plugins/sdk-overview",
"plugins/sdk-entrypoints",
"plugins/sdk-runtime",
"plugins/sdk-setup",
"plugins/sdk-testing",
"plugins/sdk-migration",
"plugins/manifest",
"plugins/architecture"
]
}
]
},
{

9
docs/plugins/architecture.md
View File

@ -12,9 +12,12 @@ sidebarTitle: "Internals"
# Plugin Internals
<Info>
This page is for **plugin developers and contributors**. If you just want to
install and use plugins, see [Plugins](/tools/plugin). If you want to build
a plugin, see [Building Plugins](/plugins/building-plugins).
This is the **deep architecture reference**. For practical guides, see:
- [Install and use plugins](/tools/plugin) — user guide
- [Getting Started](/plugins/building-plugins) — first plugin tutorial
- [Channel Plugins](/plugins/sdk-channel-plugins) — build a messaging channel
- [Provider Plugins](/plugins/sdk-provider-plugins) — build a model provider
- [SDK Overview](/plugins/sdk-overview) — import map and registration API
</Info>
This page covers the internal architecture of the OpenClaw plugin system.

426
docs/plugins/building-plugins.md
View File

@ -1,337 +1,179 @@
---
title: "Building Plugins"
sidebarTitle: "Building Plugins"
summary: "Step-by-step guide for creating OpenClaw plugins with any combination of capabilities"
sidebarTitle: "Getting Started"
summary: "Create your first OpenClaw plugin in minutes"
read_when:
- You want to create a new OpenClaw plugin
- You need to understand the plugin SDK import patterns
- You need a quick-start for plugin development
- You are adding a new channel, provider, tool, or other capability to OpenClaw
---
# Building Plugins
Plugins extend OpenClaw with new capabilities: channels, model providers, speech,
image generation, web search, agent tools, or any combination. A single plugin
can register multiple capabilities.
image generation, web search, agent tools, or any combination.
OpenClaw encourages **external plugin development**. You do not need to add your
plugin to the OpenClaw repository. Publish your plugin on npm, and users install
it with `openclaw plugins install <npm-spec>`. OpenClaw also maintains a set of
core plugins in-repo, but the plugin system is designed for independent ownership
and distribution.
You do not need to add your plugin to the OpenClaw repository. Publish on npm
and users install with `openclaw plugins install <npm-spec>`.
## Prerequisites
- Node >= 22 and a package manager (npm or pnpm)
- Familiarity with TypeScript (ESM)
- For in-repo plugins: OpenClaw repository cloned and `pnpm install` done
- For in-repo plugins: repository cloned and `pnpm install` done
## Plugin capabilities
## What kind of plugin?
A plugin can register one or more capabilities. The capability you register
determines what your plugin provides to OpenClaw:
<CardGroup cols={3}>
<Card title="Channel plugin" icon="message" href="/plugins/sdk-channel-plugins">
Connect OpenClaw to a messaging platform (Discord, IRC, etc.)
</Card>
<Card title="Provider plugin" icon="microchip" href="/plugins/sdk-provider-plugins">
Add a model provider (LLM, proxy, or custom endpoint)
</Card>
<Card title="Tool / hook plugin" icon="wrench">
Register agent tools, event hooks, or services — continue below
</Card>
</CardGroup>
| Capability | Registration method | What it adds |
| ------------------- | --------------------------------------------- | ------------------------------ |
| Text inference | `api.registerProvider(...)` | Model provider (LLM) |
| Channel / messaging | `api.registerChannel(...)` | Chat channel (e.g. Slack, IRC) |
| Speech | `api.registerSpeechProvider(...)` | Text-to-speech / STT |
| Media understanding | `api.registerMediaUnderstandingProvider(...)` | Image/audio/video analysis |
| Image generation | `api.registerImageGenerationProvider(...)` | Image generation |
| Web search | `api.registerWebSearchProvider(...)` | Web search provider |
| Agent tools | `api.registerTool(...)` | Tools callable by the agent |
## Quick start: tool plugin
A plugin that registers zero capabilities but provides hooks or services is a
**hook-only** plugin. That pattern is still supported.
## Plugin structure
Plugins follow this layout (whether in-repo or standalone):
```
my-plugin/
├── package.json # npm metadata + openclaw config
├── openclaw.plugin.json # Plugin manifest
├── index.ts # Entry point
├── setup-entry.ts # Setup wizard (optional)
├── api.ts # Public exports (optional)
├── runtime-api.ts # Internal exports (optional)
└── src/
├── provider.ts # Capability implementation
├── runtime.ts # Runtime wiring
└── *.test.ts # Colocated tests
```
## Create a plugin
This walkthrough creates a minimal plugin that registers an agent tool. Channel
and provider plugins have dedicated guides linked above.
<Steps>
<Step title="Create the package">
Create `package.json` with the `openclaw` metadata block. The structure
depends on what capabilities your plugin provides.
**Channel plugin example:**
```json
<Step title="Create the package and manifest">
<CodeGroup>
```json package.json
{
"name": "@myorg/openclaw-my-channel",
"name": "@myorg/openclaw-my-plugin",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./index.ts"],
"channel": {
"id": "my-channel",
"label": "My Channel",
"blurb": "Short description of the channel."
}
"extensions": ["./index.ts"]
}
}
```
**Provider plugin example:**
```json
```json openclaw.plugin.json
{
"name": "@myorg/openclaw-my-provider",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./index.ts"],
"providers": ["my-provider"]
"id": "my-plugin",
"name": "My Plugin",
"description": "Adds a custom tool to OpenClaw",
"configSchema": {
"type": "object",
"additionalProperties": false
}
}
```
</CodeGroup>
The `openclaw` field tells the plugin system what your plugin provides.
A plugin can declare both `channel` and `providers` if it provides multiple
capabilities.
Every plugin needs a manifest, even with no config. See
[Manifest](/plugins/manifest) for the full schema.
</Step>
<Step title="Define the entry point">
The entry point registers your capabilities with the plugin API.
**Channel plugin:**
```typescript
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
export default defineChannelPluginEntry({
id: "my-channel",
name: "My Channel",
description: "Connects OpenClaw to My Channel",
plugin: {
// Channel adapter implementation
},
});
```
**Provider plugin:**
<Step title="Write the entry point">
```typescript
// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";
export default definePluginEntry({
id: "my-provider",
name: "My Provider",
id: "my-plugin",
name: "My Plugin",
description: "Adds a custom tool to OpenClaw",
register(api) {
api.registerProvider({
// Provider implementation
api.registerTool({
name: "my_tool",
description: "Do a thing",
parameters: Type.Object({ input: Type.String() }),
async execute(_id, params) {
return { content: [{ type: "text", text: `Got: ${params.input}` }] };
},
});
},
});
```
**Multi-capability plugin** (provider + tool):
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
export default definePluginEntry({
id: "my-plugin",
name: "My Plugin",
register(api) {
api.registerProvider({ /* ... */ });
api.registerTool({ /* ... */ });
api.registerImageGenerationProvider({ /* ... */ });
},
});
```
Use `defineChannelPluginEntry` from `plugin-sdk/core` for channel plugins
and `definePluginEntry` from `plugin-sdk/plugin-entry` for everything else.
A single plugin can register as many capabilities as needed.
For chat-style channels, `plugin-sdk/core` also exposes
`createChatChannelPlugin(...)` so you can compose common DM security,
text pairing, reply threading, and attached outbound send results without
wiring each adapter separately.
`definePluginEntry` is for non-channel plugins. For channels, use
`defineChannelPluginEntry` — see [Channel Plugins](/plugins/sdk-channel-plugins).
For full entry point options, see [Entry Points](/plugins/sdk-entrypoints).
</Step>
<Step title="Import from focused SDK subpaths">
Always import from specific `openclaw/plugin-sdk/\<subpath\>` paths. The old
monolithic import is deprecated (see [SDK Migration](/plugins/sdk-migration)).
<Step title="Test and publish">
If older plugin code still imports `openclaw/extension-api`, treat that as a
temporary compatibility bridge only. New code should use injected runtime
helpers such as `api.runtime.agent.*` instead of importing host-side agent
helpers directly.
```typescript
// Correct: focused subpaths
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { buildOauthProviderAuthResult } from "openclaw/plugin-sdk/provider-auth";
// Wrong: monolithic root (lint will reject this)
import { ... } from "openclaw/plugin-sdk";
// Deprecated: legacy host bridge
import { runEmbeddedPiAgent } from "openclaw/extension-api";
```
<Accordion title="Common subpaths reference">
| Subpath | Purpose |
| --- | --- |
| `plugin-sdk/plugin-entry` | Canonical `definePluginEntry` helper + provider/plugin entry types |
| `plugin-sdk/core` | Channel entry helpers, channel builders, and shared base types |
| `plugin-sdk/runtime-store` | Safe module-level runtime storage |
| `plugin-sdk/setup` | Shared setup-wizard helpers |
| `plugin-sdk/channel-setup` | Channel setup adapters |
| `plugin-sdk/channel-pairing` | DM pairing primitives |
| `plugin-sdk/channel-actions` | Shared `message` tool schema helpers |
| `plugin-sdk/channel-contract` | Pure channel types |
| `plugin-sdk/secret-input` | Secret input parsing/helpers |
| `plugin-sdk/webhook-ingress` | Webhook request/target helpers |
| `plugin-sdk/reply-payload` | Message reply types |
| `plugin-sdk/provider-auth` | Provider auth and OAuth helpers |
| `plugin-sdk/provider-onboard` | Provider onboarding config patches |
| `plugin-sdk/provider-models` | Model catalog helpers |
| `plugin-sdk/testing` | Test utilities |
</Accordion>
Use the narrowest subpath that matches the job. For the curated map and
examples, see [Plugin SDK Overview](/plugins/sdk-overview).
</Step>
<Step title="Use local modules for internal imports">
Within your plugin, create local module files for internal code sharing
instead of re-importing through the plugin SDK:
```typescript
// api.ts — public exports for this plugin
export { MyConfig } from "./src/config.js";
export { MyRuntime } from "./src/runtime.js";
// runtime-api.ts — internal-only exports
export { internalHelper } from "./src/helpers.js";
```
<Warning>
Never import your own plugin back through its published SDK path from
production files. Route internal imports through local files like `./api.ts`
or `./runtime-api.ts`. The SDK path is for external consumers only.
</Warning>
</Step>
<Step title="Add a plugin manifest">
Create `openclaw.plugin.json` in your plugin root:
```json
{
"id": "my-plugin",
"kind": "provider",
"name": "My Plugin",
"description": "Adds My Provider to OpenClaw"
}
```
For channel plugins, set `"kind": "channel"` and add `"channels": ["my-channel"]`.
See [Plugin Manifest](/plugins/manifest) for the full schema.
</Step>
<Step title="Test your plugin">
**External plugins:** run your own test suite against the plugin SDK contracts.
**In-repo plugins:** OpenClaw runs contract tests against all registered plugins:
```bash
pnpm test:contracts:channels # channel plugins
pnpm test:contracts:plugins # provider plugins
```
For unit tests, import test helpers from the testing surface:
```typescript
import { createWindowsCmdShimFixture } from "openclaw/plugin-sdk/testing";
```
</Step>
<Step title="Publish and install">
**External plugins:** publish to npm, then install:
**External plugins:**
```bash
npm publish
openclaw plugins install @myorg/openclaw-my-plugin
```
**In-repo plugins:** place the plugin under `extensions/` and it is
automatically discovered during build.
Users can browse and install community plugins with:
**In-repo plugins:** place under `extensions/` — automatically discovered.
```bash
openclaw plugins search <query>
openclaw plugins install <npm-spec>
pnpm test -- extensions/my-plugin/
```
</Step>
</Steps>
## Plugin capabilities
A single plugin can register any number of capabilities via the `api` object:
| Capability | Registration method | Detailed guide |
| -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
| Text inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins) |
| Channel / messaging | `api.registerChannel(...)` | [Channel Plugins](/plugins/sdk-channel-plugins) |
| Speech (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Media understanding | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Image generation | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Agent tools | `api.registerTool(...)` | Below |
| Custom commands | `api.registerCommand(...)` | [Entry Points](/plugins/sdk-entrypoints) |
| Event hooks | `api.registerHook(...)` | [Entry Points](/plugins/sdk-entrypoints) |
| HTTP routes | `api.registerHttpRoute(...)` | [Internals](/plugins/architecture#gateway-http-routes) |
| CLI subcommands | `api.registerCli(...)` | [Entry Points](/plugins/sdk-entrypoints) |
For the full registration API, see [SDK Overview](/plugins/sdk-overview#registration-api).
## Registering agent tools
Plugins can register **agent tools** — typed functions the LLM can call. Tools
can be required (always available) or optional (users opt in via allowlists).
Tools are typed functions the LLM can call. They can be required (always
available) or optional (user opt-in):
```typescript
import { Type } from "@sinclair/typebox";
register(api) {
// Required tool — always available
api.registerTool({
name: "my_tool",
description: "Do a thing",
parameters: Type.Object({ input: Type.String() }),
async execute(_id, params) {
return { content: [{ type: "text", text: params.input }] };
},
});
export default definePluginEntry({
id: "my-plugin",
name: "My Plugin",
register(api) {
// Required tool (always available)
api.registerTool({
name: "my_tool",
description: "Do a thing",
parameters: Type.Object({ input: Type.String() }),
// Optional tool — user must add to allowlist
api.registerTool(
{
name: "workflow_tool",
description: "Run a workflow",
parameters: Type.Object({ pipeline: Type.String() }),
async execute(_id, params) {
return { content: [{ type: "text", text: params.input }] };
return { content: [{ type: "text", text: params.pipeline }] };
},
});
// Optional tool (user must add to allowlist)
api.registerTool(
{
name: "workflow_tool",
description: "Run a workflow",
parameters: Type.Object({ pipeline: Type.String() }),
async execute(_id, params) {
return { content: [{ type: "text", text: params.pipeline }] };
},
},
{ optional: true },
);
},
});
},
{ optional: true },
);
}
```
Enable optional tools in config:
Users enable optional tools in config:
```json5
{
@ -339,46 +181,56 @@ Enable optional tools in config:
}
```
Tips:
- Tool names must not clash with core tool names (conflicts are skipped)
- Use `optional: true` for tools that trigger side effects or require extra binaries
- Tool names must not clash with core tools (conflicts are skipped)
- Use `optional: true` for tools with side effects or extra binary requirements
- Users can enable all tools from a plugin by adding the plugin id to `tools.allow`
## Lint enforcement (in-repo plugins)
## Import conventions
Three scripts enforce SDK boundaries for plugins in the OpenClaw repository:
Always import from focused `openclaw/plugin-sdk/<subpath>` paths:
1. **No monolithic root imports** — `openclaw/plugin-sdk` root is rejected
2. **No direct src/ imports** — plugins cannot import `../../src/` directly
3. **No self-imports** — plugins cannot import their own `plugin-sdk/\<name\>` subpath
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
Run `pnpm check` to verify all boundaries before committing.
// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";
```
External plugins are not subject to these lint rules, but following the same
patterns is strongly recommended.
For the full subpath reference, see [SDK Overview](/plugins/sdk-overview).
Within your plugin, use local barrel files (`api.ts`, `runtime-api.ts`) for
internal imports — never import your own plugin through its SDK path.
## Pre-submission checklist
<Check>**package.json** has correct `openclaw` metadata</Check>
<Check>**openclaw.plugin.json** manifest is present and valid</Check>
<Check>Entry point uses `defineChannelPluginEntry` or `definePluginEntry`</Check>
<Check>All imports use focused `plugin-sdk/\<subpath\>` paths</Check>
<Check>All imports use focused `plugin-sdk/<subpath>` paths</Check>
<Check>Internal imports use local modules, not SDK self-imports</Check>
<Check>`openclaw.plugin.json` manifest is present and valid</Check>
<Check>Tests pass</Check>
<Check>Tests pass (`pnpm test -- extensions/my-plugin/`)</Check>
<Check>`pnpm check` passes (in-repo plugins)</Check>
## Related
## Next steps
- [Plugin SDK Migration](/plugins/sdk-migration) — migrating from deprecated compat surfaces
- [Plugin SDK Overview](/plugins/sdk-overview) — public SDK map and subpath guidance
- [Plugin Entry Points](/plugins/sdk-entrypoints) — `definePluginEntry` and `defineChannelPluginEntry`
- [Plugin Runtime](/plugins/sdk-runtime) — injected runtime and runtime-store
- [Plugin Setup](/plugins/sdk-setup) — setup, channel setup, and secret input helpers
- [Channel Plugin SDK](/plugins/sdk-channel-plugins) — channel contracts and actions
- [Provider Plugin SDK](/plugins/sdk-provider-plugins) — provider auth, onboarding, and catalogs
- [Plugin SDK Testing](/plugins/sdk-testing) — public test helpers
- [Plugin Architecture](/plugins/architecture) — internals and capability model
- [Plugin Manifest](/plugins/manifest) — full manifest schema
- [Plugin Agent Tools](/plugins/building-plugins#registering-agent-tools) — adding agent tools in a plugin
- [Community Plugins](/plugins/community) — listing and quality bar
<CardGroup cols={2}>
<Card title="Channel Plugins" icon="message" href="/plugins/sdk-channel-plugins">
Build a messaging channel plugin
</Card>
<Card title="Provider Plugins" icon="microchip" href="/plugins/sdk-provider-plugins">
Build a model provider plugin
</Card>
<Card title="SDK Overview" icon="book" href="/plugins/sdk-overview">
Import map and registration API reference
</Card>
<Card title="Runtime Helpers" icon="gear" href="/plugins/sdk-runtime">
TTS, search, subagent via api.runtime
</Card>
<Card title="Testing" icon="flask" href="/plugins/sdk-testing">
Test utilities and patterns
</Card>
<Card title="Plugin Manifest" icon="file-code" href="/plugins/manifest">
Full manifest schema reference
</Card>
</CardGroup>

467
docs/plugins/sdk-channel-plugins.md
View File

@ -1,161 +1,370 @@
---
title: "Channel Plugin SDK"
title: "Building Channel Plugins"
sidebarTitle: "Channel Plugins"
summary: "Contracts and helpers for native messaging channel plugins, including actions, routing, pairing, and setup"
summary: "Step-by-step guide to building a messaging channel plugin for OpenClaw"
read_when:
- You are building a native channel plugin
- You need to implement the shared `message` tool for a channel
- You need pairing, setup, or routing helpers for a channel
- You are building a new messaging channel plugin
- You want to connect OpenClaw to a messaging platform
- You need to understand the ChannelPlugin adapter surface
---
# Channel Plugin SDK
# Building Channel Plugins
Channel plugins use `defineChannelPluginEntry(...)` from
`openclaw/plugin-sdk/core` and implement the `ChannelPlugin` contract.
This guide walks through building a channel plugin that connects OpenClaw to a
messaging platform. By the end you will have a working channel with DM security,
pairing, reply threading, and outbound messaging.
## Minimal channel entry
<Info>
If you have not built any OpenClaw plugin before, read
[Getting Started](/plugins/building-plugins) first for the basic package
structure and manifest setup.
</Info>
```ts
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
import { exampleChannelPlugin } from "./src/channel.js";
import { setExampleRuntime } from "./src/runtime.js";
## How channel plugins work
export default defineChannelPluginEntry({
id: "example-channel",
name: "Example Channel",
description: "Example native channel plugin",
plugin: exampleChannelPlugin,
setRuntime: setExampleRuntime,
});
```
Channel plugins do not need their own send/edit/react tools. OpenClaw keeps one
shared `message` tool in core. Your plugin owns:
## `ChannelPlugin` shape
- **Config** — account resolution and setup wizard
- **Security** — DM policy and allowlists
- **Pairing** — DM approval flow
- **Outbound** — sending text, media, and polls to the platform
- **Threading** — how replies are threaded
Important sections of the contract:
Core owns the shared message tool, prompt wiring, session bookkeeping, and
dispatch.
- `meta`: docs, labels, and picker metadata
- `capabilities`: replies, polls, reactions, threads, media, and chat types
- `config` and `configSchema`: account resolution and config parsing
- `setup` and `setupWizard`: onboarding/setup flow
- `security`: DM policy and allowlist behavior
- `messaging`: target parsing and outbound session routing
- `actions`: shared `message` tool discovery and execution
- `pairing`, `threading`, `status`, `lifecycle`, `groups`, `directory`
## Walkthrough
For pure types, import from `openclaw/plugin-sdk/channel-contract`.
<Steps>
<Step title="Package and manifest">
Create the standard plugin files. The `channel` field in `package.json` is
what makes this a channel plugin:
## Shared `message` tool
<CodeGroup>
```json package.json
{
"name": "@myorg/openclaw-acme-chat",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./index.ts"],
"setupEntry": "./setup-entry.ts",
"channel": {
"id": "acme-chat",
"label": "Acme Chat",
"blurb": "Connect OpenClaw to Acme Chat."
}
}
}
```
Channel plugins own their channel-specific part of the shared `message` tool
through `ChannelMessageActionAdapter`.
```json openclaw.plugin.json
{
"id": "acme-chat",
"kind": "channel",
"channels": ["acme-chat"],
"name": "Acme Chat",
"description": "Acme Chat channel plugin",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"acme-chat": {
"type": "object",
"properties": {
"token": { "type": "string" },
"allowFrom": {
"type": "array",
"items": { "type": "string" }
}
}
}
}
}
}
```
</CodeGroup>
```ts
import { Type } from "@sinclair/typebox";
import { createMessageToolButtonsSchema } from "openclaw/plugin-sdk/channel-actions";
</Step>
export const exampleActions = {
describeMessageTool() {
return {
actions: ["send", "edit"],
capabilities: ["buttons"],
schema: {
visibility: "current-channel",
properties: {
buttons: createMessageToolButtonsSchema(),
threadId: Type.String(),
},
},
<Step title="Build the channel plugin object">
The `ChannelPlugin` interface has many optional adapter surfaces. Start with
the minimum — `id` and `setup` — and add adapters as you need them.
Create `src/channel.ts`:
```typescript src/channel.ts
import {
createChatChannelPlugin,
createChannelPluginBase,
} from "openclaw/plugin-sdk/core";
import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
import { acmeChatApi } from "./client.js"; // your platform API client
type ResolvedAccount = {
accountId: string | null;
token: string;
allowFrom: string[];
dmPolicy: string | undefined;
};
},
async handleAction(ctx) {
if (ctx.action === "send") {
function resolveAccount(
cfg: OpenClawConfig,
accountId?: string | null,
): ResolvedAccount {
const section = (cfg.channels as Record<string, any>)?.["acme-chat"];
const token = section?.token;
if (!token) throw new Error("acme-chat: token is required");
return {
content: [{ type: "text", text: `send to ${String(ctx.params.to)}` }],
accountId: accountId ?? null,
token,
allowFrom: section?.allowFrom ?? [],
dmPolicy: section?.dmSecurity,
};
}
return {
content: [{ type: "text", text: `unsupported action: ${ctx.action}` }],
};
},
};
```
export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
base: createChannelPluginBase({
id: "acme-chat",
setup: {
resolveAccount,
inspectAccount(cfg, accountId) {
const section =
(cfg.channels as Record<string, any>)?.["acme-chat"];
return {
enabled: Boolean(section?.token),
configured: Boolean(section?.token),
tokenStatus: section?.token ? "available" : "missing",
};
},
},
}),
Key types:
// DM security: who can message the bot
security: {
dm: {
channelKey: "acme-chat",
resolvePolicy: (account) => account.dmPolicy,
resolveAllowFrom: (account) => account.allowFrom,
defaultPolicy: "allowlist",
},
},
- `ChannelMessageActionAdapter`
- `ChannelMessageActionContext`
- `ChannelMessageActionDiscoveryContext`
- `ChannelMessageToolDiscovery`
// Pairing: approval flow for new DM contacts
pairing: {
text: {
idLabel: "Acme Chat username",
message: "Send this code to verify your identity:",
notify: async ({ target, code }) => {
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
},
},
},
## Outbound routing helpers
// Threading: how replies are delivered
threading: { topLevelReplyToMode: "reply" },
When a channel plugin needs custom outbound routing, implement
`messaging.resolveOutboundSessionRoute(...)`.
Use `buildChannelOutboundSessionRoute(...)` from `plugin-sdk/core` to return the
standard route payload:
```ts
import { buildChannelOutboundSessionRoute } from "openclaw/plugin-sdk/core";
const messaging = {
resolveOutboundSessionRoute({ cfg, agentId, accountId, target }) {
return buildChannelOutboundSessionRoute({
cfg,
agentId,
channel: "example-channel",
accountId,
peer: { kind: "direct", id: target },
chatType: "direct",
from: accountId ?? "default",
to: target,
// Outbound: send messages to the platform
outbound: {
attachedResults: {
sendText: async (params) => {
const result = await acmeChatApi.sendMessage(
params.to,
params.text,
);
return { messageId: result.id };
},
},
base: {
sendMedia: async (params) => {
await acmeChatApi.sendFile(params.to, params.filePath);
},
},
},
});
},
};
```
<Accordion title="What createChatChannelPlugin does for you">
Instead of implementing low-level adapter interfaces manually, you pass
declarative options and the builder composes them:
| Option | What it wires |
| --- | --- |
| `security.dm` | Scoped DM security resolver from config fields |
| `pairing.text` | Text-based DM pairing flow with code exchange |
| `threading` | Reply-to-mode resolver (fixed, account-scoped, or custom) |
| `outbound.attachedResults` | Send functions that return result metadata (message IDs) |
You can also pass raw adapter objects instead of the declarative options
if you need full control.
</Accordion>
</Step>
<Step title="Wire the entry point">
Create `index.ts`:
```typescript index.ts
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
import { acmeChatPlugin } from "./src/channel.js";
export default defineChannelPluginEntry({
id: "acme-chat",
name: "Acme Chat",
description: "Acme Chat channel plugin",
plugin: acmeChatPlugin,
registerFull(api) {
api.registerCli(
({ program }) => {
program
.command("acme-chat")
.description("Acme Chat management");
},
{ commands: ["acme-chat"] },
);
},
});
```
`defineChannelPluginEntry` handles the setup/full registration split
automatically. See
[Entry Points](/plugins/sdk-entrypoints#definechannelpluginentry) for all
options.
</Step>
<Step title="Add a setup entry">
Create `setup-entry.ts` for lightweight loading during onboarding:
```typescript setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
import { acmeChatPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(acmeChatPlugin);
```
OpenClaw loads this instead of the full entry when the channel is disabled
or unconfigured. It avoids pulling in heavy runtime code during setup flows.
See [Setup and Config](/plugins/sdk-setup#setup-entry) for details.
</Step>
<Step title="Handle inbound messages">
Your plugin needs to receive messages from the platform and forward them to
OpenClaw. The typical pattern is a webhook that verifies the request and
dispatches it through your channel's inbound handler:
```typescript
registerFull(api) {
api.registerHttpRoute({
path: "/acme-chat/webhook",
auth: "plugin", // plugin-managed auth (verify signatures yourself)
handler: async (req, res) => {
const event = parseWebhookPayload(req);
// Your inbound handler dispatches the message to OpenClaw.
// The exact wiring depends on your platform SDK —
// see a real example in extensions/msteams or extensions/googlechat.
await handleAcmeChatInbound(api, event);
res.statusCode = 200;
res.end("ok");
return true;
},
});
}
```
<Note>
Inbound message handling is channel-specific. Each channel plugin owns
its own inbound pipeline. Look at bundled channel plugins
(e.g. `extensions/msteams`, `extensions/googlechat`) for real patterns.
</Note>
</Step>
<Step title="Test">
Write colocated tests in `src/channel.test.ts`:
```typescript src/channel.test.ts
import { describe, it, expect } from "vitest";
import { acmeChatPlugin } from "./channel.js";
describe("acme-chat plugin", () => {
it("resolves account from config", () => {
const cfg = {
channels: {
"acme-chat": { token: "test-token", allowFrom: ["user1"] },
},
} as any;
const account = acmeChatPlugin.setup!.resolveAccount(cfg, undefined);
expect(account.token).toBe("test-token");
});
it("inspects account without materializing secrets", () => {
const cfg = {
channels: { "acme-chat": { token: "test-token" } },
} as any;
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
expect(result.configured).toBe(true);
expect(result.tokenStatus).toBe("available");
});
it("reports missing config", () => {
const cfg = { channels: {} } as any;
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
expect(result.configured).toBe(false);
});
});
```
```bash
pnpm test -- extensions/acme-chat/
```
For shared test helpers, see [Testing](/plugins/sdk-testing).
</Step>
</Steps>
## File structure
```
extensions/acme-chat/
├── package.json # openclaw.channel metadata
├── openclaw.plugin.json # Manifest with config schema
├── index.ts # defineChannelPluginEntry
├── setup-entry.ts # defineSetupPluginEntry
├── api.ts # Public exports (optional)
├── runtime-api.ts # Internal runtime exports (optional)
└── src/
├── channel.ts # ChannelPlugin via createChatChannelPlugin
├── channel.test.ts # Tests
├── client.ts # Platform API client
└── runtime.ts # Runtime store (if needed)
```
## Pairing helpers
## Advanced topics
Use `plugin-sdk/channel-pairing` for DM approval flows:
<CardGroup cols={2}>
<Card title="Threading options" href="/plugins/sdk-entrypoints#registration-mode">
Fixed, account-scoped, or custom reply modes
</Card>
<Card title="Message tool integration" href="/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool and action discovery
</Card>
<Card title="Target resolution" href="/plugins/architecture#channel-target-resolution">
inferTargetChatType, looksLikeId, resolveTarget
</Card>
<Card title="Runtime helpers" href="/plugins/sdk-runtime">
TTS, STT, media, subagent via api.runtime
</Card>
</CardGroup>
```ts
import { createChannelPairingController } from "openclaw/plugin-sdk/channel-pairing";
## Next steps
const pairing = createChannelPairingController({
core: runtime,
channel: "example-channel",
accountId: "default",
});
const result = pairing.issueChallenge({
agentId: "assistant",
requesterId: "user-123",
});
```
That surface also gives you scoped access to pairing storage helpers such as
allowlist reads and request upserts.
## Channel setup helpers
Use:
- `plugin-sdk/channel-setup` for optional or installable channels
- `plugin-sdk/setup` for setup adapters, DM policy, and allowlist prompts
- `plugin-sdk/webhook-ingress` for plugin-owned webhook routes
## Channel plugin guidance
- Keep transport-specific execution inside the channel package.
- Use `channel-contract` types in tests and local helpers.
- Keep `describeMessageTool(...)` and `handleAction(...)` aligned.
- Keep session routing in `messaging`, not in ad-hoc command handlers.
- Prefer focused subpaths over broad runtime coupling.
## Related
- [Plugin SDK Overview](/plugins/sdk-overview)
- [Plugin Entry Points](/plugins/sdk-entrypoints)
- [Plugin Setup](/plugins/sdk-setup)
- [Plugin Internals](/plugins/architecture)
- [Provider Plugins](/plugins/sdk-provider-plugins) — if your plugin also provides models
- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
- [SDK Testing](/plugins/sdk-testing) — test utilities and contract tests
- [Plugin Manifest](/plugins/manifest) — full manifest schema

214
docs/plugins/sdk-entrypoints.md
View File

@ -1,159 +1,161 @@
---
title: "Plugin Entry Points"
sidebarTitle: "Entry Points"
summary: "How to define plugin entry files for provider, tool, channel, and setup plugins"
summary: "Reference for definePluginEntry, defineChannelPluginEntry, and defineSetupPluginEntry"
read_when:
- You are writing a plugin `index.ts`
- You need to choose between `definePluginEntry` and `defineChannelPluginEntry`
- You are adding a separate `setup-entry.ts`
- You need the exact type signature of definePluginEntry or defineChannelPluginEntry
- You want to understand registration mode (full vs setup)
- You are looking up entry point options
---
# Plugin Entry Points
OpenClaw has two main entry helpers:
Every plugin exports a default entry object. The SDK provides three helpers for
creating them.
- `definePluginEntry(...)` for general plugins
- `defineChannelPluginEntry(...)` for native messaging channels
<Tip>
**Looking for a walkthrough?** See [Channel Plugins](/plugins/sdk-channel-plugins)
or [Provider Plugins](/plugins/sdk-provider-plugins) for step-by-step guides.
</Tip>
There is also `defineSetupPluginEntry(...)` for a separate setup-only module.
## `definePluginEntry`
## `definePluginEntry(...)`
**Import:** `openclaw/plugin-sdk/plugin-entry`
Use this for providers, tools, commands, services, memory plugins, and context
engines.
For provider plugins, tool plugins, hook plugins, and anything that is **not**
a messaging channel.
```ts
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
export default definePluginEntry({
id: "example-tools",
name: "Example Tools",
description: "Adds a command and a tool",
register(api: OpenClawPluginApi) {
api.registerCommand({
name: "example",
description: "Show plugin status",
handler: async () => ({ text: "example ok" }),
id: "my-plugin",
name: "My Plugin",
description: "Short summary",
register(api) {
api.registerProvider({
/* ... */
});
api.registerTool({
name: "example_lookup",
description: "Look up Example data",
parameters: {
type: "object",
properties: {
query: { type: "string" },
},
required: ["query"],
},
async execute(_callId, params) {
return {
content: [{ type: "text", text: `lookup: ${String(params.query)}` }],
};
},
/* ... */
});
},
});
```
## `defineChannelPluginEntry(...)`
### Options
Use this for a plugin that registers a `ChannelPlugin`.
| Field | Type | Required | Default |
| -------------- | ---------------------------------------------------------------- | -------- | ------------------- |
| `id` | `string` | Yes | — |
| `name` | `string` | Yes | — |
| `description` | `string` | Yes | — |
| `kind` | `string` | No | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | No | Empty object schema |
| `register` | `(api: OpenClawPluginApi) => void` | Yes | — |
```ts
- `id` must match your `openclaw.plugin.json` manifest.
- `kind` is for exclusive slots: `"memory"` or `"context-engine"`.
- `configSchema` can be a function for lazy evaluation.
## `defineChannelPluginEntry`
**Import:** `openclaw/plugin-sdk/core`
Wraps `definePluginEntry` with channel-specific wiring. Automatically calls
`api.registerChannel({ plugin })` and gates `registerFull` on registration mode.
```typescript
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
import { channelPlugin } from "./src/channel.js";
import { setRuntime } from "./src/runtime.js";
export default defineChannelPluginEntry({
id: "example-channel",
name: "Example Channel",
description: "Example messaging plugin",
plugin: channelPlugin,
setRuntime,
id: "my-channel",
name: "My Channel",
description: "Short summary",
plugin: myChannelPlugin,
setRuntime: setMyRuntime,
registerFull(api) {
api.registerTool({
name: "example_channel_status",
description: "Inspect Example Channel state",
parameters: { type: "object", properties: {} },
async execute() {
return { content: [{ type: "text", text: "ok" }] };
},
});
api.registerCli(/* ... */);
api.registerGatewayMethod(/* ... */);
},
});
```
### Why `registerFull(...)` exists
### Options
OpenClaw can load plugins in setup-focused registration modes. `registerFull`
lets a channel plugin skip extra runtime-only registrations such as tools while
still registering the channel capability itself.
| Field | Type | Required | Default |
| -------------- | ---------------------------------------------------------------- | -------- | ------------------- |
| `id` | `string` | Yes | — |
| `name` | `string` | Yes | — |
| `description` | `string` | Yes | — |
| `plugin` | `ChannelPlugin` | Yes | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | No | Empty object schema |
| `setRuntime` | `(runtime: PluginRuntime) => void` | No | — |
| `registerFull` | `(api: OpenClawPluginApi) => void` | No | — |
Use it for:
- `setRuntime` is called during registration so you can store the runtime reference
(typically via `createPluginRuntimeStore`).
- `registerFull` only runs when `api.registrationMode === "full"`. It is skipped
during setup-only loading.
- agent tools
- gateway-only routes
- runtime-only commands
## `defineSetupPluginEntry`
Do not use it for the actual `ChannelPlugin`; that belongs in `plugin: ...`.
**Import:** `openclaw/plugin-sdk/core`
## `defineSetupPluginEntry(...)`
For the lightweight `setup-entry.ts` file. Returns just `{ plugin }` with no
runtime or CLI wiring.
Use this when a channel ships a second module for setup flows.
```ts
```typescript
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
import { exampleSetupPlugin } from "./src/channel.setup.js";
export default defineSetupPluginEntry(exampleSetupPlugin);
export default defineSetupPluginEntry(myChannelPlugin);
```
This keeps the setup entry shape explicit and matches the bundled channel
pattern used in OpenClaw.
OpenClaw loads this instead of the full entry when a channel is disabled,
unconfigured, or when deferred loading is enabled. See
[Setup and Config](/plugins/sdk-setup#setup-entry) for when this matters.
## One plugin, many capabilities
## Registration mode
A single entry file can register multiple capabilities:
`api.registrationMode` tells your plugin how it was loaded:
```ts
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
| Mode | When | What to register |
| ----------------- | --------------------------------- | ----------------------------- |
| `"full"` | Normal gateway startup | Everything |
| `"setup-only"` | Disabled/unconfigured channel | Channel registration only |
| `"setup-runtime"` | Setup flow with runtime available | Channel + lightweight runtime |
export default definePluginEntry({
id: "example-hybrid",
name: "Example Hybrid",
description: "Provider plus tools",
register(api: OpenClawPluginApi) {
api.registerProvider({
id: "example",
label: "Example",
auth: [],
});
`defineChannelPluginEntry` handles this split automatically. If you use
`definePluginEntry` directly for a channel, check mode yourself:
api.registerTool({
name: "example_ping",
description: "Simple health check",
parameters: { type: "object", properties: {} },
async execute() {
return { content: [{ type: "text", text: "pong" }] };
},
});
},
});
```typescript
register(api) {
api.registerChannel({ plugin: myPlugin });
if (api.registrationMode !== "full") return;
// Heavy runtime-only registrations
api.registerCli(/* ... */);
api.registerService(/* ... */);
}
```
## Entry-file checklist
## Plugin shapes
- Give the plugin a stable `id`.
- Keep `name` and `description` human-readable.
- Put schema at the entry level when the plugin has config.
- Register only public capabilities inside `register(api)`.
- Keep channel plugins on `plugin-sdk/core`.
- Keep non-channel plugins on `plugin-sdk/plugin-entry`.
OpenClaw classifies loaded plugins by their registration behavior:
| Shape | Description |
| --------------------- | -------------------------------------------------- |
| **plain-capability** | One capability type (e.g. provider-only) |
| **hybrid-capability** | Multiple capability types (e.g. provider + speech) |
| **hook-only** | Only hooks, no capabilities |
| **non-capability** | Tools/commands/services but no capabilities |
Use `openclaw plugins inspect <id>` to see a plugin's shape.
## Related
- [Plugin SDK Overview](/plugins/sdk-overview)
- [Plugin Runtime](/plugins/sdk-runtime)
- [Channel Plugin SDK](/plugins/sdk-channel-plugins)
- [Provider Plugin SDK](/plugins/sdk-provider-plugins)
- [SDK Overview](/plugins/sdk-overview) — registration API and subpath reference
- [Runtime Helpers](/plugins/sdk-runtime) — `api.runtime` and `createPluginRuntimeStore`
- [Setup and Config](/plugins/sdk-setup) — manifest, setup entry, deferred loading
- [Channel Plugins](/plugins/sdk-channel-plugins) — building the `ChannelPlugin` object
- [Provider Plugins](/plugins/sdk-provider-plugins) — provider registration and hooks

10
docs/plugins/sdk-migration.md
View File

@ -164,7 +164,9 @@ This is a temporary escape hatch, not a permanent solution.
## Related
- [Building Plugins](/plugins/building-plugins)
- [Plugin SDK Overview](/plugins/sdk-overview)
- [Plugin Internals](/plugins/architecture)
- [Plugin Manifest](/plugins/manifest)
- [Getting Started](/plugins/building-plugins) — build your first plugin
- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
- [Channel Plugins](/plugins/sdk-channel-plugins) — building channel plugins
- [Provider Plugins](/plugins/sdk-provider-plugins) — building provider plugins
- [Plugin Internals](/plugins/architecture) — architecture deep dive
- [Plugin Manifest](/plugins/manifest) — manifest schema reference

329
docs/plugins/sdk-overview.md
View File

@ -1,175 +1,196 @@
---
title: "Plugin SDK Overview"
sidebarTitle: "SDK Overview"
summary: "How the OpenClaw plugin SDK is organized, which subpaths are stable, and how to choose the right import"
summary: "Import map, registration API reference, and SDK architecture"
read_when:
- You are starting a new OpenClaw plugin
- You need to choose the right plugin-sdk subpath
- You are replacing deprecated compat imports
- You need to know which SDK subpath to import from
- You want a reference for all registration methods on OpenClawPluginApi
- You are looking up a specific SDK export
---
# Plugin SDK Overview
The OpenClaw plugin SDK is split into **small public subpaths** under
`openclaw/plugin-sdk/<subpath>`.
The plugin SDK is the typed contract between plugins and core. This page is the
reference for **what to import** and **what you can register**.
Use the narrowest import that matches the job. That keeps plugin dependencies
small, avoids circular imports, and makes it clear which contract you depend on.
<Tip>
**Looking for a how-to guide?**
- First plugin? Start with [Getting Started](/plugins/building-plugins)
- Channel plugin? See [Channel Plugins](/plugins/sdk-channel-plugins)
- Provider plugin? See [Provider Plugins](/plugins/sdk-provider-plugins)
</Tip>
## Rules first
## Import convention
- Use focused imports such as `openclaw/plugin-sdk/plugin-entry`.
- Do not import the root `openclaw/plugin-sdk` barrel in new code.
- Do not import `openclaw/extension-api` in new code.
- Do not import `src/**` from plugin packages.
- Inside a plugin package, route internal imports through local files such as
`./api.ts` or `./runtime-api.ts`, not through the published SDK path for that
same plugin.
Always import from a specific subpath:
## SDK map
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
| Job | Subpath | Next page |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Define plugin entry modules | `plugin-sdk/plugin-entry`, `plugin-sdk/core` | [Plugin Entry Points](/plugins/sdk-entrypoints) |
| Use injected runtime helpers | `plugin-sdk/runtime`, `plugin-sdk/runtime-store` | [Plugin Runtime](/plugins/sdk-runtime) |
| Build setup/configure flows | `plugin-sdk/setup`, `plugin-sdk/channel-setup`, `plugin-sdk/secret-input` | [Plugin Setup](/plugins/sdk-setup) |
| Build channel plugins | `plugin-sdk/core`, `plugin-sdk/channel-contract`, `plugin-sdk/channel-actions`, `plugin-sdk/channel-pairing` | [Channel Plugin SDK](/plugins/sdk-channel-plugins) |
| Build provider plugins | `plugin-sdk/plugin-entry`, `plugin-sdk/provider-auth`, `plugin-sdk/provider-onboard`, `plugin-sdk/provider-models`, `plugin-sdk/provider-usage` | [Provider Plugin SDK](/plugins/sdk-provider-plugins) |
| Test plugin code | `plugin-sdk/testing` | [Plugin SDK Testing](/plugins/sdk-testing) |
// Deprecated — will be removed in the next major release
import { definePluginEntry } from "openclaw/plugin-sdk";
```
## Typical plugin layout
Each subpath is a small, self-contained module. This keeps startup fast and
prevents circular dependency issues.
```text
## Subpath reference
The most commonly used subpaths, grouped by purpose. The full list of 100+
subpaths is in `scripts/lib/plugin-sdk-entrypoints.json`.
### Plugin entry
| Subpath | Key exports |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
<AccordionGroup>
<Accordion title="Channel subpaths">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface` |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Channel config schema types |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/channel-inbound` | Debounce, mention matching, envelope helpers |
| `plugin-sdk/channel-send-result` | Reply result types |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | Target parsing/matching helpers |
| `plugin-sdk/channel-contract` | Channel contract types |
| `plugin-sdk/channel-feedback` | Feedback/reaction wiring |
</Accordion>
<Accordion title="Provider subpaths">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
| `plugin-sdk/provider-models` | `normalizeModelCompat` |
| `plugin-sdk/provider-catalog` | Catalog type re-exports |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` and similar |
| `plugin-sdk/provider-stream` | Stream wrapper types |
| `plugin-sdk/provider-onboard` | Onboarding config patch helpers |
</Accordion>
<Accordion title="Auth and security subpaths">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate` |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/secret-input` | Secret input parsing helpers |
| `plugin-sdk/webhook-ingress` | Webhook request/target helpers |
</Accordion>
<Accordion title="Runtime and storage subpaths">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/config-runtime` | Config load/write helpers |
| `plugin-sdk/infra-runtime` | System event/heartbeat helpers |
| `plugin-sdk/agent-runtime` | Agent dir/identity/workspace helpers |
| `plugin-sdk/directory-runtime` | Config-backed directory query/dedup |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Capability and testing subpaths">
| Subpath | Key exports |
| --- | --- |
| `plugin-sdk/image-generation` | Image generation provider types |
| `plugin-sdk/media-understanding` | Media understanding provider types |
| `plugin-sdk/speech` | Speech provider types |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
</AccordionGroup>
## Registration API
The `register(api)` callback receives an `OpenClawPluginApi` object with these
methods:
### Capability registration
| Method | What it registers |
| --------------------------------------------- | ------------------------------ |
| `api.registerProvider(...)` | Text inference (LLM) |
| `api.registerChannel(...)` | Messaging channel |
| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis |
| `api.registerMediaUnderstandingProvider(...)` | Image/audio/video analysis |
| `api.registerImageGenerationProvider(...)` | Image generation |
| `api.registerWebSearchProvider(...)` | Web search |
### Tools and commands
| Method | What it registers |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Agent tool (required or `{ optional: true }`) |
| `api.registerCommand(def)` | Custom command (bypasses the LLM) |
### Infrastructure
| Method | What it registers |
| ---------------------------------------------- | --------------------- |
| `api.registerHook(events, handler, opts?)` | Event hook |
| `api.registerHttpRoute(params)` | Gateway HTTP endpoint |
| `api.registerGatewayMethod(name, handler)` | Gateway RPC method |
| `api.registerCli(registrar, opts?)` | CLI subcommand |
| `api.registerService(service)` | Background service |
| `api.registerInteractiveHandler(registration)` | Interactive handler |
### Exclusive slots
| Method | What it registers |
| ------------------------------------------ | ------------------------------------- |
| `api.registerContextEngine(id, factory)` | Context engine (one active at a time) |
| `api.registerMemoryPromptSection(builder)` | Memory prompt section builder |
### Events and lifecycle
| Method | What it does |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Typed lifecycle hook |
| `api.onConversationBindingResolved(handler)` | Conversation binding callback |
### API object fields
| Field | Type | Description |
| ------------------------ | ------------------------- | --------------------------------------------------------- |
| `api.id` | `string` | Plugin id |
| `api.name` | `string` | Display name |
| `api.config` | `OpenClawConfig` | Current config snapshot |
| `api.pluginConfig` | `Record<string, unknown>` | Plugin-specific config from `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Runtime helpers](/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Scoped logger (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | `"full"`, `"setup-only"`, or `"setup-runtime"` |
| `api.resolvePath(input)` | `(string) => string` | Resolve path relative to plugin root |
## Internal module convention
Within your plugin, use local barrel files for internal imports:
```
my-plugin/
├── package.json
├── openclaw.plugin.json
├── index.ts
├── setup-entry.ts
├── api.ts
├── runtime-api.ts
└── src/
├── provider.ts
├── setup.ts
└── provider.test.ts
api.ts # Public exports for external consumers
runtime-api.ts # Internal-only runtime exports
index.ts # Plugin entry point
setup-entry.ts # Lightweight setup-only entry (optional)
```
```ts
// api.ts
export {
definePluginEntry,
type OpenClawPluginApi,
type ProviderAuthContext,
type ProviderAuthResult,
} from "openclaw/plugin-sdk/plugin-entry";
```
## What belongs where
### Entry helpers
- `plugin-sdk/plugin-entry` is the default entry surface for providers, tools,
commands, services, memory plugins, and context engines.
- `plugin-sdk/core` adds channel-focused helpers such as
`defineChannelPluginEntry(...)`.
### Runtime helpers
- Use `api.runtime.*` for trusted in-process helpers that OpenClaw injects at
registration time.
- Use `plugin-sdk/runtime-store` when plugin modules need a mutable runtime slot
that is initialized later.
### Setup helpers
- `plugin-sdk/setup` contains shared setup-wizard helpers and config patch
helpers.
- `plugin-sdk/channel-setup` contains channel-specific setup adapters.
- `plugin-sdk/secret-input` exposes the shared secret-input schema helpers.
### Channel helpers
- `plugin-sdk/channel-contract` exports pure channel types.
- `plugin-sdk/channel-actions` covers shared `message` tool schema helpers.
- `plugin-sdk/channel-pairing` covers pairing approval flows.
- `plugin-sdk/webhook-ingress` covers plugin-owned webhook routes.
### Provider helpers
- `plugin-sdk/provider-auth` covers auth flows and credential helpers.
- `plugin-sdk/provider-onboard` covers config patches after auth/setup.
- `plugin-sdk/provider-models` covers catalog and model-definition helpers.
- `plugin-sdk/provider-usage` covers usage snapshot helpers.
- `plugin-sdk/provider-setup` and `plugin-sdk/self-hosted-provider-setup`
cover self-hosted and local-model onboarding.
## Example: mixing subpaths in one plugin
```ts
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth";
import { applyProviderConfigWithDefaultModel } from "openclaw/plugin-sdk/provider-onboard";
import { buildSecretInputSchema } from "openclaw/plugin-sdk/secret-input";
export default definePluginEntry({
id: "example-provider",
name: "Example Provider",
description: "Small provider plugin example",
configSchema: {
jsonSchema: {
type: "object",
additionalProperties: false,
properties: {
apiKey: { type: "string" },
},
},
safeParse(value) {
return buildSecretInputSchema().safeParse((value as { apiKey?: unknown })?.apiKey);
},
},
register(api: OpenClawPluginApi) {
api.registerProvider({
id: "example",
label: "Example",
auth: [
createProviderApiKeyAuthMethod({
providerId: "example",
methodId: "api-key",
label: "Example API key",
optionKey: "exampleApiKey",
flagName: "--example-api-key",
envVar: "EXAMPLE_API_KEY",
promptMessage: "Enter Example API key",
profileId: "example:default",
defaultModel: "example/default",
applyConfig: (cfg) =>
applyProviderConfigWithDefaultModel(cfg, "example", {
id: "default",
name: "Default",
}),
}),
],
});
},
});
```
## Choose the smallest public seam
If a helper exists on a focused subpath, prefer that over a broader runtime
surface.
- Prefer `plugin-sdk/provider-auth` over reaching into unrelated provider files.
- Prefer `plugin-sdk/channel-contract` for types in tests and helper modules.
- Prefer `plugin-sdk/runtime-store` over custom mutable globals.
- Prefer `plugin-sdk/testing` for shared test fixtures.
<Warning>
Never import your own plugin through `openclaw/plugin-sdk/<your-plugin>`
from production code. Route internal imports through `./api.ts` or
`./runtime-api.ts`. The SDK path is the external contract only.
</Warning>
## Related
- [Building Plugins](/plugins/building-plugins)
- [Plugin Entry Points](/plugins/sdk-entrypoints)
- [Plugin Runtime](/plugins/sdk-runtime)
- [Plugin Setup](/plugins/sdk-setup)
- [Channel Plugin SDK](/plugins/sdk-channel-plugins)
- [Provider Plugin SDK](/plugins/sdk-provider-plugins)
- [Plugin SDK Testing](/plugins/sdk-testing)
- [Plugin SDK Migration](/plugins/sdk-migration)
- [Entry Points](/plugins/sdk-entrypoints) — `definePluginEntry` and `defineChannelPluginEntry` options
- [Runtime Helpers](/plugins/sdk-runtime) — full `api.runtime` namespace reference
- [Setup and Config](/plugins/sdk-setup) — packaging, manifests, config schemas
- [Testing](/plugins/sdk-testing) — test utilities and lint rules
- [SDK Migration](/plugins/sdk-migration) — migrating from deprecated surfaces
- [Plugin Internals](/plugins/architecture) — deep architecture and capability model

520
docs/plugins/sdk-provider-plugins.md
View File

@ -1,184 +1,370 @@
---
title: "Provider Plugin SDK"
title: "Building Provider Plugins"
sidebarTitle: "Provider Plugins"
summary: "Contracts and helper subpaths for model-provider plugins, including auth, onboarding, catalogs, and usage"
summary: "Step-by-step guide to building a model provider plugin for OpenClaw"
read_when:
- You are building a model provider plugin
- You need auth helpers for API keys or OAuth
- You need onboarding config patches or catalog helpers
- You are building a new model provider plugin
- You want to add an OpenAI-compatible proxy or custom LLM to OpenClaw
- You need to understand provider auth, catalogs, and runtime hooks
---
# Provider Plugin SDK
# Building Provider Plugins
Provider plugins use `definePluginEntry(...)` and call `api.registerProvider(...)`
with a `ProviderPlugin` definition.
This guide walks through building a provider plugin that adds a model provider
(LLM) to OpenClaw. By the end you will have a provider with a model catalog,
API key auth, and dynamic model resolution.
## Minimal provider entry
<Info>
If you have not built any OpenClaw plugin before, read
[Getting Started](/plugins/building-plugins) first for the basic package
structure and manifest setup.
</Info>
```ts
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
## Walkthrough
export default definePluginEntry({
id: "example-provider",
name: "Example Provider",
description: "Example text-inference provider plugin",
register(api: OpenClawPluginApi) {
api.registerProvider({
id: "example",
label: "Example",
auth: [],
<Steps>
<Step title="Package and manifest">
<CodeGroup>
```json package.json
{
"name": "@myorg/openclaw-acme-ai",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./index.ts"],
"providers": ["acme-ai"]
}
}
```
```json openclaw.plugin.json
{
"id": "acme-ai",
"name": "Acme AI",
"description": "Acme AI model provider",
"providers": ["acme-ai"],
"providerAuthEnvVars": {
"acme-ai": ["ACME_AI_API_KEY"]
},
"providerAuthChoices": [
{
"provider": "acme-ai",
"method": "api-key",
"choiceId": "acme-ai-api-key",
"choiceLabel": "Acme AI API key",
"groupId": "acme-ai",
"groupLabel": "Acme AI",
"cliFlag": "--acme-ai-api-key",
"cliOption": "--acme-ai-api-key <key>",
"cliDescription": "Acme AI API key"
}
],
"configSchema": {
"type": "object",
"additionalProperties": false
}
}
```
</CodeGroup>
The manifest declares `providerAuthEnvVars` so OpenClaw can detect
credentials without loading your plugin runtime.
</Step>
<Step title="Register the provider">
A minimal provider needs an `id`, `label`, `auth`, and `catalog`:
```typescript index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth";
export default definePluginEntry({
id: "acme-ai",
name: "Acme AI",
description: "Acme AI model provider",
register(api) {
api.registerProvider({
id: "acme-ai",
label: "Acme AI",
docsPath: "/providers/acme-ai",
envVars: ["ACME_AI_API_KEY"],
auth: [
createProviderApiKeyAuthMethod({
providerId: "acme-ai",
methodId: "api-key",
label: "Acme AI API key",
hint: "API key from your Acme AI dashboard",
optionKey: "acmeAiApiKey",
flagName: "--acme-ai-api-key",
envVar: "ACME_AI_API_KEY",
promptMessage: "Enter your Acme AI API key",
defaultModel: "acme-ai/acme-large",
}),
],
catalog: {
order: "simple",
run: async (ctx) => {
const apiKey =
ctx.resolveProviderApiKey("acme-ai").apiKey;
if (!apiKey) return null;
return {
provider: {
baseUrl: "https://api.acme-ai.com/v1",
apiKey,
api: "openai-completions",
models: [
{
id: "acme-large",
name: "Acme Large",
reasoning: true,
input: ["text", "image"],
cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
contextWindow: 200000,
maxTokens: 32768,
},
{
id: "acme-small",
name: "Acme Small",
reasoning: false,
input: ["text"],
cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
contextWindow: 128000,
maxTokens: 8192,
},
],
},
};
},
},
});
},
});
},
});
```
That is a working provider. Users can now
`openclaw onboard --acme-ai-api-key <key>` and select
`acme-ai/acme-large` as their model.
</Step>
<Step title="Add dynamic model resolution">
If your provider accepts arbitrary model IDs (like a proxy or router),
add `resolveDynamicModel`:
```typescript
api.registerProvider({
// ... id, label, auth, catalog from above
resolveDynamicModel: (ctx) => ({
id: ctx.modelId,
name: ctx.modelId,
provider: "acme-ai",
api: "openai-completions",
baseUrl: "https://api.acme-ai.com/v1",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 8192,
}),
});
```
If resolving requires a network call, use `prepareDynamicModel` for async
warm-up — `resolveDynamicModel` runs again after it completes.
</Step>
<Step title="Add runtime hooks (as needed)">
Most providers only need `catalog` + `resolveDynamicModel`. Add hooks
incrementally as your provider requires them.
<Tabs>
<Tab title="Token exchange">
For providers that need a token exchange before each inference call:
```typescript
prepareRuntimeAuth: async (ctx) => {
const exchanged = await exchangeToken(ctx.apiKey);
return {
apiKey: exchanged.token,
baseUrl: exchanged.baseUrl,
expiresAt: exchanged.expiresAt,
};
},
```
</Tab>
<Tab title="Custom headers">
For providers that need custom request headers or body modifications:
```typescript
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
wrapStreamFn: (ctx) => {
if (!ctx.streamFn) return undefined;
const inner = ctx.streamFn;
return async (params) => {
params.headers = {
...params.headers,
"X-Acme-Version": "2",
};
return inner(params);
};
},
```
</Tab>
<Tab title="Usage and billing">
For providers that expose usage/billing data:
```typescript
resolveUsageAuth: async (ctx) => {
const auth = await ctx.resolveOAuthToken();
return auth ? { token: auth.token } : null;
},
fetchUsageSnapshot: async (ctx) => {
return await fetchAcmeUsage(ctx.token, ctx.timeoutMs);
},
```
</Tab>
</Tabs>
<Accordion title="All 21 available hooks">
OpenClaw calls hooks in this order. Most providers only use 2-3:
| # | Hook | When to use |
| --- | --- | --- |
| 1 | `catalog` | Model catalog or base URL defaults |
| 2 | `resolveDynamicModel` | Accept arbitrary upstream model IDs |
| 3 | `prepareDynamicModel` | Async metadata fetch before resolving |
| 4 | `normalizeResolvedModel` | Transport rewrites before the runner |
| 5 | `capabilities` | Transcript/tooling metadata |
| 6 | `prepareExtraParams` | Default request params |
| 7 | `wrapStreamFn` | Custom headers/body wrappers |
| 8 | `formatApiKey` | Custom runtime token shape |
| 9 | `refreshOAuth` | Custom OAuth refresh |
| 10 | `buildAuthDoctorHint` | Auth repair guidance |
| 11 | `isCacheTtlEligible` | Prompt cache TTL gating |
| 12 | `buildMissingAuthMessage` | Custom missing-auth hint |
| 13 | `suppressBuiltInModel` | Hide stale upstream rows |
| 14 | `augmentModelCatalog` | Synthetic forward-compat rows |
| 15 | `isBinaryThinking` | Binary thinking on/off |
| 16 | `supportsXHighThinking` | `xhigh` reasoning support |
| 17 | `resolveDefaultThinkingLevel` | Default `/think` policy |
| 18 | `isModernModelRef` | Live/smoke model matching |
| 19 | `prepareRuntimeAuth` | Token exchange before inference |
| 20 | `resolveUsageAuth` | Custom usage credential parsing |
| 21 | `fetchUsageSnapshot` | Custom usage endpoint |
For detailed descriptions and real-world examples, see
[Internals: Provider Runtime Hooks](/plugins/architecture#provider-runtime-hooks).
</Accordion>
</Step>
<Step title="Add extra capabilities (optional)">
A provider plugin can register speech, media understanding, image
generation, and web search alongside text inference:
```typescript
register(api) {
api.registerProvider({ id: "acme-ai", /* ... */ });
api.registerSpeechProvider({
id: "acme-ai",
label: "Acme Speech",
isConfigured: ({ config }) => Boolean(config.messages?.tts),
synthesize: async (req) => ({
audioBuffer: Buffer.from(/* PCM data */),
outputFormat: "mp3",
fileExtension: ".mp3",
voiceCompatible: false,
}),
});
api.registerMediaUnderstandingProvider({
id: "acme-ai",
capabilities: ["image", "audio"],
describeImage: async (req) => ({ text: "A photo of..." }),
transcribeAudio: async (req) => ({ text: "Transcript..." }),
});
api.registerImageGenerationProvider({
id: "acme-ai",
label: "Acme Images",
generate: async (req) => ({ /* image result */ }),
});
}
```
OpenClaw classifies this as a **hybrid-capability** plugin. This is the
recommended pattern for company plugins (one plugin per vendor). See
[Internals: Capability Ownership](/plugins/architecture#capability-ownership-model).
</Step>
<Step title="Test">
```typescript src/provider.test.ts
import { describe, it, expect } from "vitest";
// Export your provider config object from index.ts or a dedicated file
import { acmeProvider } from "./provider.js";
describe("acme-ai provider", () => {
it("resolves dynamic models", () => {
const model = acmeProvider.resolveDynamicModel!({
modelId: "acme-beta-v3",
} as any);
expect(model.id).toBe("acme-beta-v3");
expect(model.provider).toBe("acme-ai");
});
it("returns catalog when key is available", async () => {
const result = await acmeProvider.catalog!.run({
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
} as any);
expect(result?.provider?.models).toHaveLength(2);
});
it("returns null catalog when no key", async () => {
const result = await acmeProvider.catalog!.run({
resolveProviderApiKey: () => ({ apiKey: undefined }),
} as any);
expect(result).toBeNull();
});
});
```
</Step>
</Steps>
## File structure
```
extensions/acme-ai/
├── package.json # openclaw.providers metadata
├── openclaw.plugin.json # Manifest with providerAuthEnvVars
├── index.ts # definePluginEntry + registerProvider
└── src/
├── provider.test.ts # Tests
└── usage.ts # Usage endpoint (optional)
```
## Provider subpaths
## Catalog order reference
| Subpath | Use it for |
| --------------------------------------- | ---------------------------------------------- |
| `plugin-sdk/provider-auth` | API key, OAuth, auth-profile, and PKCE helpers |
| `plugin-sdk/provider-onboard` | Config patches after setup/auth |
| `plugin-sdk/provider-models` | Model-definition and catalog helpers |
| `plugin-sdk/provider-setup` | Shared local/self-hosted setup flows |
| `plugin-sdk/self-hosted-provider-setup` | OpenAI-compatible self-hosted providers |
| `plugin-sdk/provider-usage` | Usage snapshot fetch helpers |
## API key auth
`createProviderApiKeyAuthMethod(...)` is the standard helper for API-key
`catalog.order` controls when your catalog merges relative to built-in
providers:
```ts
import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth";
import { applyProviderConfigWithDefaultModel } from "openclaw/plugin-sdk/provider-onboard";
| Order | When | Use case |
| --------- | ------------- | ----------------------------------------------- |
| `simple` | First pass | Plain API-key providers |
| `profile` | After simple | Providers gated on auth profiles |
| `paired` | After profile | Synthesize multiple related entries |
| `late` | Last pass | Override existing providers (wins on collision) |
const auth = [
createProviderApiKeyAuthMethod({
providerId: "example",
methodId: "api-key",
label: "Example API key",
optionKey: "exampleApiKey",
flagName: "--example-api-key",
envVar: "EXAMPLE_API_KEY",
promptMessage: "Enter Example API key",
profileId: "example:default",
defaultModel: "example/default",
applyConfig: (cfg) =>
applyProviderConfigWithDefaultModel(cfg, "example", {
id: "default",
name: "Default",
}),
}),
];
```
## Next steps
## OAuth auth
`buildOauthProviderAuthResult(...)` builds the standard auth result payload for
OAuth-style providers:
```ts
import { buildOauthProviderAuthResult } from "openclaw/plugin-sdk/provider-auth";
async function runOAuthLogin() {
return buildOauthProviderAuthResult({
providerId: "example-portal",
defaultModel: "example-portal/default",
access: "access-token",
refresh: "refresh-token",
email: "user@example.com",
notes: ["Tokens auto-refresh when the provider supports refresh tokens."],
});
}
```
## Catalog and discovery hooks
Provider plugins usually implement either `catalog` or the legacy `discovery`
alias. `catalog` is preferred.
```ts
api.registerProvider({
id: "example",
label: "Example",
auth,
catalog: {
order: "simple",
async run(ctx) {
const apiKey = ctx.resolveProviderApiKey("example").apiKey;
if (!apiKey) {
return null;
}
return {
provider: {
api: "openai",
baseUrl: "https://api.example.com/v1",
apiKey,
models: [
{
id: "default",
name: "Default",
input: ["text"],
},
],
},
};
},
},
});
```
## Onboarding config patches
`plugin-sdk/provider-onboard` keeps post-auth config writes consistent.
Common helpers:
- `applyProviderConfigWithDefaultModel(...)`
- `applyProviderConfigWithDefaultModels(...)`
- `applyProviderConfigWithModelCatalog(...)`
- `applyAgentDefaultModelPrimary(...)`
- `ensureModelAllowlistEntry(...)`
## Self-hosted and local model setup
Use `plugin-sdk/provider-setup` or
`plugin-sdk/self-hosted-provider-setup` when the provider is an OpenAI-style
backend, Ollama, SGLang, or vLLM.
Examples from the shared setup surfaces:
- `promptAndConfigureOllama(...)`
- `configureOllamaNonInteractive(...)`
- `promptAndConfigureOpenAICompatibleSelfHostedProvider(...)`
- `discoverOpenAICompatibleSelfHostedProvider(...)`
These helpers keep setup behavior aligned with built-in provider flows.
## Usage snapshots
If the provider owns quota or usage endpoints, use `resolveUsageAuth(...)` and
`fetchUsageSnapshot(...)`.
`plugin-sdk/provider-usage` includes shared fetch helpers such as:
- `fetchClaudeUsage(...)`
- `fetchCodexUsage(...)`
- `fetchGeminiUsage(...)`
- `fetchMinimaxUsage(...)`
- `fetchZaiUsage(...)`
## Provider guidance
- Keep auth logic in `provider-auth`.
- Keep config mutation in `provider-onboard`.
- Keep catalog/model helpers in `provider-models`.
- Keep usage logic in `provider-usage`.
- Use `catalog`, not `discovery`, in new plugins.
## Related
- [Plugin SDK Overview](/plugins/sdk-overview)
- [Plugin Entry Points](/plugins/sdk-entrypoints)
- [Plugin Setup](/plugins/sdk-setup)
- [Plugin Internals](/plugins/architecture#provider-runtime-hooks)
- [Channel Plugins](/plugins/sdk-channel-plugins) — if your plugin also provides a channel
- [SDK Runtime](/plugins/sdk-runtime) — `api.runtime` helpers (TTS, search, subagent)
- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
- [Plugin Internals](/plugins/architecture#provider-runtime-hooks) — hook details and bundled examples

427
docs/plugins/sdk-runtime.md
View File

@ -1,156 +1,345 @@
---
title: "Plugin Runtime"
sidebarTitle: "Runtime"
summary: "How `api.runtime` works, when to use it, and how to manage plugin runtime state safely"
title: "Plugin SDK Runtime"
sidebarTitle: "Runtime Helpers"
summary: "api.runtime -- the injected runtime helpers available to plugins"
read_when:
- You need to call runtime helpers from a plugin
- You are deciding between hooks and injected runtime
- You need a safe module-level runtime store
- You need to call core helpers from a plugin (TTS, STT, image gen, web search, subagent)
- You want to understand what api.runtime exposes
- You are accessing config, agent, or media helpers from plugin code
---
# Plugin Runtime
# Plugin Runtime Helpers
Native OpenClaw plugins receive a trusted runtime through `api.runtime`.
Reference for the `api.runtime` object injected into every plugin during
registration. Use these helpers instead of importing host internals directly.
Use it for **host-owned operations** that should stay inside OpenClaw’s runtime:
<Tip>
**Looking for a walkthrough?** See [Channel Plugins](/plugins/sdk-channel-plugins)
or [Provider Plugins](/plugins/sdk-provider-plugins) for step-by-step guides
that show these helpers in context.
</Tip>
- reading and writing config
- agent/session helpers
- system commands with OpenClaw timeouts
- media, speech, image-generation, and web-search runtime calls
- channel-owned helpers for bundled channel plugins
## When to use runtime vs focused SDK helpers
- Use focused SDK helpers when a public subpath already models the job.
- Use `api.runtime.*` when the host owns the operation or state.
- Prefer hooks for loose integrations that do not need tight in-process access.
```typescript
register(api) {
const runtime = api.runtime;
}
```
## Runtime namespaces
| Namespace | What it covers |
| -------------------------------- | -------------------------------------------------- |
| `api.runtime.config` | Load and persist OpenClaw config |
| `api.runtime.agent` | Agent workspace, identity, timeouts, session store |
| `api.runtime.system` | System events, heartbeats, command execution |
| `api.runtime.media` | File/media loading and transforms |
| `api.runtime.tts` | Speech synthesis and voice listing |
| `api.runtime.mediaUnderstanding` | Image/audio/video understanding |
| `api.runtime.imageGeneration` | Image generation providers |
| `api.runtime.webSearch` | Runtime web-search execution |
| `api.runtime.modelAuth` | Resolve model/provider credentials |
| `api.runtime.subagent` | Spawn, wait, inspect, and delete subagent sessions |
| `api.runtime.channel` | Channel-heavy helpers for native channel plugins |
### `api.runtime.agent`
## Example: read and persist config
Agent identity, directories, and session management.
```ts
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
```typescript
// Resolve the agent's working directory
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
export default definePluginEntry({
id: "talk-settings",
name: "Talk Settings",
description: "Example runtime config write",
register(api: OpenClawPluginApi) {
api.registerCommand({
name: "talk-mode",
description: "Enable talk mode",
handler: async () => {
const cfg = api.runtime.config.loadConfig();
const nextConfig = {
...cfg,
talk: {
...cfg.talk,
enabled: true,
},
};
await api.runtime.config.writeConfigFile(nextConfig);
return { text: "talk mode enabled" };
},
});
},
// Resolve agent workspace
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
// Get agent identity
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
// Get default thinking level
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);
// Get agent timeout
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
// Ensure workspace exists
await api.runtime.agent.ensureAgentWorkspace(cfg);
// Run an embedded Pi agent (requires sessionFile + workspaceDir at minimum)
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedPiAgent({
sessionId: "my-plugin:task-1",
sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
prompt: "Summarize the latest changes",
});
```
## Example: use a runtime service owned by OpenClaw
**Session store helpers** are under `api.runtime.agent.session`:
```ts
const cfg = api.runtime.config.loadConfig();
```typescript
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
const store = api.runtime.agent.session.loadSessionStore(cfg);
await api.runtime.agent.session.saveSessionStore(cfg, store);
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);
```
### `api.runtime.agent.defaults`
Default model and provider constants:
```typescript
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"
```
### `api.runtime.subagent`
Launch and manage background subagent runs.
```typescript
// Start a subagent run
const { runId } = await api.runtime.subagent.run({
sessionKey: "agent:main:subagent:search-helper",
message: "Expand this query into focused follow-up searches.",
provider: "openai", // optional override
model: "gpt-4.1-mini", // optional override
deliver: false,
});
// Wait for completion
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });
// Read session messages
const { messages } = await api.runtime.subagent.getSessionMessages({
sessionKey: "agent:main:subagent:search-helper",
limit: 10,
});
// Delete a session
await api.runtime.subagent.deleteSession({
sessionKey: "agent:main:subagent:search-helper",
});
```
<Warning>
Model overrides (`provider`/`model`) require operator opt-in via
`plugins.entries.<id>.subagent.allowModelOverride: true` in config.
Untrusted plugins can still run subagents, but override requests are rejected.
</Warning>
### `api.runtime.tts`
Text-to-speech synthesis.
```typescript
// Standard TTS
const clip = await api.runtime.tts.textToSpeech({
text: "Hello from OpenClaw",
cfg: api.config,
});
// Telephony-optimized TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
text: "Hello from OpenClaw",
cfg: api.config,
});
// List available voices
const voices = await api.runtime.tts.listVoices({
provider: "elevenlabs",
cfg: api.config,
});
```
Uses core `messages.tts` configuration and provider selection. Returns PCM audio
buffer + sample rate.
### `api.runtime.mediaUnderstanding`
Image, audio, and video analysis.
```typescript
// Describe an image
const image = await api.runtime.mediaUnderstanding.describeImageFile({
filePath: "/tmp/inbound-photo.jpg",
cfg: api.config,
agentDir: "/tmp/agent",
});
// Transcribe audio
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
filePath: "/tmp/inbound-audio.ogg",
cfg: api.config,
mime: "audio/ogg", // optional, for when MIME cannot be inferred
});
// Describe a video
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
filePath: "/tmp/inbound-video.mp4",
cfg: api.config,
});
// Generic file analysis
const result = await api.runtime.mediaUnderstanding.runFile({
filePath: "/tmp/inbound-file.pdf",
cfg: api.config,
});
```
Returns `{ text: undefined }` when no output is produced (e.g. skipped input).
<Info>
`api.runtime.stt.transcribeAudioFile(...)` remains as a compatibility alias
for `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
</Info>
### `api.runtime.imageGeneration`
Image generation.
```typescript
const result = await api.runtime.imageGeneration.generate({
prompt: "A robot painting a sunset",
cfg: api.config,
});
const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });
```
### `api.runtime.webSearch`
Web search.
```typescript
const providers = api.runtime.webSearch.listProviders({ config: api.config });
const result = await api.runtime.webSearch.search({
config: api.config,
args: { query: "OpenClaw plugin SDK", count: 5 },
});
```
### `api.runtime.media`
Low-level media utilities.
```typescript
const webMedia = await api.runtime.media.loadWebMedia(url);
const mime = await api.runtime.media.detectMime(buffer);
const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "image"
const isVoice = api.runtime.media.isVoiceCompatibleAudio(filePath);
const metadata = await api.runtime.media.getImageMetadata(filePath);
const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });
```
### `api.runtime.config`
Config load and write.
```typescript
const cfg = await api.runtime.config.loadConfig();
await api.runtime.config.writeConfigFile(cfg);
```
### `api.runtime.system`
System-level utilities.
```typescript
await api.runtime.system.enqueueSystemEvent(event);
api.runtime.system.requestHeartbeatNow();
const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
const hint = api.runtime.system.formatNativeDependencyHint(pkg);
```
### `api.runtime.events`
Event subscriptions.
```typescript
api.runtime.events.onAgentEvent((event) => {
/* ... */
});
api.runtime.events.onSessionTranscriptUpdate((update) => {
/* ... */
});
```
### `api.runtime.logging`
Logging.
```typescript
const verbose = api.runtime.logging.shouldLogVerbose();
const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });
```
### `api.runtime.modelAuth`
Model and provider auth resolution.
```typescript
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
provider: "openai",
cfg,
});
return {
text: voices.map((voice) => `${voice.name ?? voice.id}: ${voice.id}`).join("\n"),
};
```
## `createPluginRuntimeStore(...)`
### `api.runtime.state`
Plugin modules often need a small mutable slot for runtime-backed helpers. Use
`plugin-sdk/runtime-store` instead of an unguarded `let runtime`.
State directory resolution.
```ts
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
```typescript
const stateDir = api.runtime.state.resolveStateDir();
```
### `api.runtime.tools`
Memory tool factories and CLI.
```typescript
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);
```
### `api.runtime.channel`
Channel-specific runtime helpers (available when a channel plugin is loaded).
## Storing runtime references
Use `createPluginRuntimeStore` to store the runtime reference for use outside
the `register` callback:
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { channelPlugin } from "./src/channel.js";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
const runtimeStore = createPluginRuntimeStore<{
logger: { info(message: string): void };
}>("Example Channel runtime not initialized");
export function setExampleRuntime(runtime: { logger: { info(message: string): void } }) {
runtimeStore.setRuntime(runtime);
}
export function getExampleRuntime() {
return runtimeStore.getRuntime();
}
const store = createPluginRuntimeStore<PluginRuntime>("my-plugin runtime not initialized");
// In your entry point
export default defineChannelPluginEntry({
id: "example-channel",
name: "Example Channel",
description: "Example runtime store usage",
plugin: channelPlugin,
setRuntime: setExampleRuntime,
id: "my-plugin",
name: "My Plugin",
description: "Example",
plugin: myPlugin,
setRuntime: store.setRuntime,
});
// In other files
export function getRuntime() {
return store.getRuntime(); // throws if not initialized
}
export function tryGetRuntime() {
return store.tryGetRuntime(); // returns null if not initialized
}
```
`createPluginRuntimeStore(...)` gives you:
## Other top-level `api` fields
- `setRuntime(next)`
- `clearRuntime()`
- `tryGetRuntime()`
- `getRuntime()`
Beyond `api.runtime`, the API object also provides:
`getRuntime()` throws with your custom message if the runtime was never set.
## Channel runtime note
`api.runtime.channel.*` is the heaviest namespace. It exists for native channel
plugins that need tight coupling with the OpenClaw messaging stack.
Prefer narrower subpaths such as:
- `plugin-sdk/channel-pairing`
- `plugin-sdk/channel-actions`
- `plugin-sdk/channel-feedback`
- `plugin-sdk/channel-lifecycle`
Use `api.runtime.channel.*` when the operation is clearly host-owned and there
is no smaller public seam.
## Runtime safety guidelines
- Do not cache config snapshots longer than needed.
- Prefer `createPluginRuntimeStore(...)` for shared module state.
- Keep runtime-backed code behind small local helpers.
- Avoid reaching into runtime namespaces you do not need.
| Field | Type | Description |
| ------------------------ | ------------------------- | --------------------------------------------------------- |
| `api.id` | `string` | Plugin id |
| `api.name` | `string` | Plugin display name |
| `api.config` | `OpenClawConfig` | Current config snapshot |
| `api.pluginConfig` | `Record<string, unknown>` | Plugin-specific config from `plugins.entries.<id>.config` |
| `api.logger` | `PluginLogger` | Scoped logger (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | `"full"`, `"setup-only"`, or `"setup-runtime"` |
| `api.resolvePath(input)` | `(string) => string` | Resolve a path relative to the plugin root |
## Related
- [Plugin SDK Overview](/plugins/sdk-overview)
- [Plugin Entry Points](/plugins/sdk-entrypoints)
- [Plugin Setup](/plugins/sdk-setup)
- [Channel Plugin SDK](/plugins/sdk-channel-plugins)
- [SDK Overview](/plugins/sdk-overview) -- subpath reference
- [SDK Entry Points](/plugins/sdk-entrypoints) -- `definePluginEntry` options
- [Plugin Internals](/plugins/architecture) -- capability model and registry

414
docs/plugins/sdk-setup.md
View File

@ -1,132 +1,324 @@
---
title: "Plugin Setup"
sidebarTitle: "Setup"
summary: "Shared setup-wizard helpers for channel plugins, provider plugins, and secret inputs"
title: "Plugin SDK Setup"
sidebarTitle: "Setup and Config"
summary: "Setup wizards, setup-entry.ts, config schemas, and package.json metadata"
read_when:
- You are building a setup or onboarding flow
- You need shared allowlist or DM policy setup helpers
- You need the shared secret-input schema
- You are adding a setup wizard to a plugin
- You need to understand setup-entry.ts vs index.ts
- You are defining plugin config schemas or package.json openclaw metadata
---
# Plugin Setup
# Plugin Setup and Config
OpenClaw exposes shared setup helpers so plugin setup flows behave like the
built-in ones.
Reference for plugin packaging (`package.json` metadata), manifests
(`openclaw.plugin.json`), setup entries, and config schemas.
Main subpaths:
<Tip>
**Looking for a walkthrough?** The how-to guides cover packaging in context:
[Channel Plugins](/plugins/sdk-channel-plugins#step-1-package-and-manifest) and
[Provider Plugins](/plugins/sdk-provider-plugins#step-1-package-and-manifest).
</Tip>
- `openclaw/plugin-sdk/setup`
- `openclaw/plugin-sdk/channel-setup`
- `openclaw/plugin-sdk/secret-input`
## Package metadata
## Channel setup helpers
Your `package.json` needs an `openclaw` field that tells the plugin system what
your plugin provides:
Use `plugin-sdk/channel-setup` when a channel plugin needs the standard setup
adapter and setup wizard shapes.
**Channel plugin:**
### Optional channel plugins
If a channel is installable but not always present, use
`createOptionalChannelSetupSurface(...)`:
```ts
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
export const optionalExampleSetup = createOptionalChannelSetupSurface({
channel: "example",
label: "Example Channel",
npmSpec: "@openclaw/example-channel",
docsPath: "/channels/example",
});
```
That returns:
- `setupAdapter`
- `setupWizard`
Both surfaces produce a consistent “install this plugin first” experience.
## Shared setup helpers
`plugin-sdk/setup` re-exports the setup primitives used by bundled channels.
Common helpers:
- `applySetupAccountConfigPatch(...)`
- `createPatchedAccountSetupAdapter(...)`
- `createEnvPatchedAccountSetupAdapter(...)`
- `createTopLevelChannelDmPolicy(...)`
- `setSetupChannelEnabled(...)`
- `promptResolvedAllowFrom(...)`
- `promptSingleChannelSecretInput(...)`
### Example: patch channel config in setup
```ts
import {
DEFAULT_ACCOUNT_ID,
createPatchedAccountSetupAdapter,
setSetupChannelEnabled,
} from "openclaw/plugin-sdk/setup";
export const exampleSetupAdapter = createPatchedAccountSetupAdapter({
resolveAccountId: ({ accountId }) => accountId ?? DEFAULT_ACCOUNT_ID,
applyPatch: ({ nextConfig, accountId }) => {
const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
return setSetupChannelEnabled({
nextConfig,
channel: "example",
accountId: resolvedAccountId,
enabled: true,
});
},
});
```
## Secret input schema
Use `plugin-sdk/secret-input` instead of rolling your own secret-input parser.
```ts
import {
buildOptionalSecretInputSchema,
buildSecretInputArraySchema,
buildSecretInputSchema,
hasConfiguredSecretInput,
} from "openclaw/plugin-sdk/secret-input";
const ApiKeySchema = buildSecretInputSchema();
const OptionalApiKeySchema = buildOptionalSecretInputSchema();
const ExtraKeysSchema = buildSecretInputArraySchema();
const parsed = OptionalApiKeySchema.safeParse(process.env.EXAMPLE_API_KEY);
if (parsed.success && hasConfiguredSecretInput(parsed.data)) {
// ...
```json
{
"name": "@myorg/openclaw-my-channel",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./index.ts"],
"setupEntry": "./setup-entry.ts",
"channel": {
"id": "my-channel",
"label": "My Channel",
"blurb": "Short description of the channel."
}
}
}
```
## Provider setup note
**Provider plugin:**
Provider-specific onboarding helpers live on provider-focused subpaths:
```json
{
"name": "@myorg/openclaw-my-provider",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./index.ts"],
"providers": ["my-provider"]
}
}
```
- `plugin-sdk/provider-auth`
- `plugin-sdk/provider-onboard`
- `plugin-sdk/provider-setup`
- `plugin-sdk/self-hosted-provider-setup`
### `openclaw` fields
See [Provider Plugin SDK](/plugins/sdk-provider-plugins).
| Field | Type | Description |
| ------------ | ---------- | ------------------------------------------------------------------------------------------ |
| `extensions` | `string[]` | Entry point files (relative to package root) |
| `setupEntry` | `string` | Lightweight setup-only entry (optional) |
| `channel` | `object` | Channel metadata: `id`, `label`, `blurb`, `selectionLabel`, `docsPath`, `order`, `aliases` |
| `providers` | `string[]` | Provider ids registered by this plugin |
| `install` | `object` | Install hints: `npmSpec`, `localPath`, `defaultChoice` |
| `startup` | `object` | Startup behavior flags |
## Setup guidance
### Deferred full load
- Keep setup input schemas strict and small.
- Reuse OpenClaw’s allowlist, DM-policy, and secret-input helpers.
- Keep setup-entry modules thin; move behavior into `src/`.
- Link docs from setup flows when install or auth steps are manual.
Channel plugins can opt into deferred loading with:
```json
{
"openclaw": {
"extensions": ["./index.ts"],
"setupEntry": "./setup-entry.ts",
"startup": {
"deferConfiguredChannelFullLoadUntilAfterListen": true
}
}
}
```
When enabled, OpenClaw loads only `setupEntry` during the pre-listen startup
phase, even for already-configured channels. The full entry loads after the
gateway starts listening.
<Warning>
Only enable deferred loading when your `setupEntry` registers everything the
gateway needs before it starts listening (channel registration, HTTP routes,
gateway methods). If the full entry owns required startup capabilities, keep
the default behavior.
</Warning>
## Plugin manifest
Every native plugin must ship an `openclaw.plugin.json` in the package root.
OpenClaw uses this to validate config without executing plugin code.
```json
{
"id": "my-plugin",
"name": "My Plugin",
"description": "Adds My Plugin capabilities to OpenClaw",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"webhookSecret": {
"type": "string",
"description": "Webhook verification secret"
}
}
}
}
```
For channel plugins, add `kind` and `channels`:
```json
{
"id": "my-channel",
"kind": "channel",
"channels": ["my-channel"],
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}
```
Even plugins with no config must ship a schema. An empty schema is valid:
```json
{
"id": "my-plugin",
"configSchema": {
"type": "object",
"additionalProperties": false
}
}
```
See [Plugin Manifest](/plugins/manifest) for the full schema reference.
## Setup entry
The `setup-entry.ts` file is a lightweight alternative to `index.ts` that
OpenClaw loads when it only needs setup surfaces (onboarding, config repair,
disabled channel inspection).
```typescript
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
This avoids loading heavy runtime code (crypto libraries, CLI registrations,
background services) during setup flows.
**When OpenClaw uses `setupEntry` instead of the full entry:**
- The channel is disabled but needs setup/onboarding surfaces
- The channel is enabled but unconfigured
- Deferred loading is enabled (`deferConfiguredChannelFullLoadUntilAfterListen`)
**What `setupEntry` must register:**
- The channel plugin object (via `defineSetupPluginEntry`)
- Any HTTP routes required before gateway listen
- Any gateway methods needed during startup
**What `setupEntry` should NOT include:**
- CLI registrations
- Background services
- Heavy runtime imports (crypto, SDKs)
- Gateway methods only needed after startup
## Config schema
Plugin config is validated against the JSON Schema in your manifest. Users
configure plugins via:
```json5
{
plugins: {
entries: {
"my-plugin": {
config: {
webhookSecret: "abc123",
},
},
},
},
}
```
Your plugin receives this config as `api.pluginConfig` during registration.
For channel-specific config, use the channel config section instead:
```json5
{
channels: {
"my-channel": {
token: "bot-token",
allowFrom: ["user1", "user2"],
},
},
}
```
### Building channel config schemas
Use `buildChannelConfigSchema` from `openclaw/plugin-sdk/core` to convert a
Zod schema into the `ChannelConfigSchema` wrapper that OpenClaw validates:
```typescript
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/core";
const accountSchema = z.object({
token: z.string().optional(),
allowFrom: z.array(z.string()).optional(),
accounts: z.object({}).catchall(z.any()).optional(),
defaultAccount: z.string().optional(),
});
const configSchema = buildChannelConfigSchema(accountSchema);
```
## Setup wizards
Channel plugins can provide interactive setup wizards for `openclaw onboard`.
The wizard is a `ChannelSetupWizard` object on the `ChannelPlugin`:
```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
const setupWizard: ChannelSetupWizard = {
channel: "my-channel",
status: {
configuredLabel: "Connected",
unconfiguredLabel: "Not configured",
resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
},
credentials: [
{
inputKey: "token",
providerHint: "my-channel",
credentialLabel: "Bot token",
preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
keepPrompt: "Keep current token?",
inputPrompt: "Enter your bot token:",
inspect: ({ cfg, accountId }) => {
const token = (cfg.channels as any)?.["my-channel"]?.token;
return {
accountConfigured: Boolean(token),
hasConfiguredValue: Boolean(token),
};
},
},
],
};
```
The `ChannelSetupWizard` type supports `credentials`, `textInputs`,
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`, and more.
See bundled plugins (e.g. `extensions/discord/src/channel.setup.ts`) for
full examples.
For optional setup surfaces that should only appear in certain contexts, use
`createOptionalChannelSetupSurface` from `openclaw/plugin-sdk/channel-setup`:
```typescript
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
const setupSurface = createOptionalChannelSetupSurface({
channel: "my-channel",
label: "My Channel",
npmSpec: "@myorg/openclaw-my-channel",
docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }
```
## Publishing and installing
**External plugins:**
```bash
npm publish
openclaw plugins install @myorg/openclaw-my-plugin
```
**In-repo plugins:** place under `extensions/` and they are automatically
discovered during build.
**Users can browse and install:**
```bash
openclaw plugins search <query>
openclaw plugins install <npm-spec>
```
<Info>
`openclaw plugins install` runs `npm install --ignore-scripts` (no lifecycle
scripts). Keep plugin dependency trees pure JS/TS and avoid packages that
require `postinstall` builds.
</Info>
## Related
- [Plugin SDK Overview](/plugins/sdk-overview)
- [Plugin Entry Points](/plugins/sdk-entrypoints)
- [Provider Plugin SDK](/plugins/sdk-provider-plugins)
- [Plugin Manifest](/plugins/manifest)
- [SDK Entry Points](/plugins/sdk-entrypoints) -- `definePluginEntry` and `defineChannelPluginEntry`
- [Plugin Manifest](/plugins/manifest) -- full manifest schema reference
- [Building Plugins](/plugins/building-plugins) -- step-by-step getting started guide

299
docs/plugins/sdk-testing.md
View File

@ -1,112 +1,263 @@
---
title: "Plugin SDK Testing"
title: "SDK Testing"
sidebarTitle: "Testing"
summary: "How to test plugin code with the public testing helpers and small local test doubles"
summary: "Testing utilities and patterns for OpenClaw plugins"
read_when:
- You are writing tests for a plugin
- You need fixtures for Windows command shims or shared routing failures
- You want to know what the public testing surface includes
- You need test utilities from the plugin SDK
- You want to understand contract tests for bundled plugins
---
# Plugin SDK Testing
# Plugin Testing
OpenClaw keeps the public testing surface intentionally small.
Reference for test utilities, patterns, and lint enforcement for OpenClaw
plugins.
Use `openclaw/plugin-sdk/testing` for helpers that are stable enough to support
for plugin authors, and build small plugin-local doubles for everything else.
<Tip>
**Looking for test examples?** The how-to guides include worked test examples:
[Channel plugin tests](/plugins/sdk-channel-plugins#step-6-test) and
[Provider plugin tests](/plugins/sdk-provider-plugins#step-6-test).
</Tip>
## Public testing helpers
## Test utilities
Current helpers include:
**Import:** `openclaw/plugin-sdk/testing`
- `createWindowsCmdShimFixture(...)`
- `installCommonResolveTargetErrorCases(...)`
- `shouldAckReaction(...)`
- `removeAckReactionAfterReply(...)`
The testing subpath exports a narrow set of helpers for plugin authors:
The testing surface also re-exports some shared types:
```typescript
import {
installCommonResolveTargetErrorCases,
shouldAckReaction,
removeAckReactionAfterReply,
} from "openclaw/plugin-sdk/testing";
```
- `OpenClawConfig`
- `PluginRuntime`
- `RuntimeEnv`
- `ChannelAccountSnapshot`
- `ChannelGatewayContext`
### Available exports
## Example: Windows command shim fixture
| Export | Purpose |
| -------------------------------------- | ------------------------------------------------------ |
| `installCommonResolveTargetErrorCases` | Shared test cases for target resolution error handling |
| `shouldAckReaction` | Check whether a channel should add an ack reaction |
| `removeAckReactionAfterReply` | Remove ack reaction after reply delivery |
```ts
import { createWindowsCmdShimFixture } from "openclaw/plugin-sdk/testing";
import { describe, expect, it } from "vitest";
### Types
describe("example CLI integration", () => {
it("creates a command shim", async () => {
await createWindowsCmdShimFixture({
shimPath: "/tmp/example.cmd",
scriptPath: "/tmp/example.js",
shimLine: 'node "%~dp0\\example.js" %*',
});
The testing subpath also re-exports types useful in test files:
expect(true).toBe(true);
```typescript
import type {
ChannelAccountSnapshot,
ChannelGatewayContext,
OpenClawConfig,
PluginRuntime,
RuntimeEnv,
MockFn,
} from "openclaw/plugin-sdk/testing";
```
## Testing target resolution
Use `installCommonResolveTargetErrorCases` to add standard error cases for
channel target resolution:
```typescript
import { describe } from "vitest";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing";
describe("my-channel target resolution", () => {
installCommonResolveTargetErrorCases({
resolveTarget: ({ to, mode, allowFrom }) => {
// Your channel's target resolution logic
return myChannelResolveTarget({ to, mode, allowFrom });
},
implicitAllowFrom: ["user1", "user2"],
});
// Add channel-specific test cases
it("should resolve @username targets", () => {
// ...
});
});
```
## Example: shared target-resolution failures
## Testing patterns
```ts
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing";
### Unit testing a channel plugin
installCommonResolveTargetErrorCases({
implicitAllowFrom: ["user-1"],
resolveTarget({ to, mode, allowFrom }) {
if (!to?.trim()) {
return { ok: false, error: new Error("missing target") };
}
if (mode === "implicit" && allowFrom.length > 0 && to === "invalid-target") {
return { ok: false, error: new Error("invalid target") };
}
return { ok: true, to };
},
```typescript
import { describe, it, expect, vi } from "vitest";
describe("my-channel plugin", () => {
it("should resolve account from config", () => {
const cfg = {
channels: {
"my-channel": {
token: "test-token",
allowFrom: ["user1"],
},
},
};
const account = myPlugin.setup.resolveAccount(cfg, undefined);
expect(account.token).toBe("test-token");
});
it("should inspect account without materializing secrets", () => {
const cfg = {
channels: {
"my-channel": { token: "test-token" },
},
};
const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
expect(inspection.configured).toBe(true);
expect(inspection.tokenStatus).toBe("available");
// No token value exposed
expect(inspection).not.toHaveProperty("token");
});
});
```
## Runtime doubles
### Unit testing a provider plugin
There is no catch-all `createTestRuntime()` export on the public SDK today.
Instead:
```typescript
import { describe, it, expect } from "vitest";
- use the public testing helpers where they fit
- use `plugin-sdk/runtime` for small runtime adapters
- build tiny plugin-local runtime doubles for the rest
describe("my-provider plugin", () => {
it("should resolve dynamic models", () => {
const model = myProvider.resolveDynamicModel({
modelId: "custom-model-v2",
// ... context
});
Example:
expect(model.id).toBe("custom-model-v2");
expect(model.provider).toBe("my-provider");
expect(model.api).toBe("openai-completions");
});
```ts
import { createLoggerBackedRuntime } from "openclaw/plugin-sdk/runtime";
it("should return catalog when API key is available", async () => {
const result = await myProvider.catalog.run({
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
// ... context
});
const logs: string[] = [];
const runtime = createLoggerBackedRuntime({
logger: {
info(message) {
logs.push(`info:${message}`);
},
error(message) {
logs.push(`error:${message}`);
},
},
expect(result?.provider?.models).toHaveLength(2);
});
});
```
## Test guidance
### Mocking the plugin runtime
- Prefer focused unit tests over giant end-to-end harnesses.
- Import pure types from focused SDK subpaths in tests.
- Keep plugin-local test doubles small and explicit.
- Avoid depending on non-exported OpenClaw test internals.
For code that uses `createPluginRuntimeStore`, mock the runtime in tests:
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
const store = createPluginRuntimeStore<PluginRuntime>("test runtime not set");
// In test setup
const mockRuntime = {
agent: {
resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
// ... other mocks
},
config: {
loadConfig: vi.fn(),
writeConfigFile: vi.fn(),
},
// ... other namespaces
} as unknown as PluginRuntime;
store.setRuntime(mockRuntime);
// After tests
store.clearRuntime();
```
### Testing with per-instance stubs
Prefer per-instance stubs over prototype mutation:
```typescript
// Preferred: per-instance stub
const client = new MyChannelClient();
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
// Avoid: prototype mutation
// MyChannelClient.prototype.sendMessage = vi.fn();
```
## Contract tests (in-repo plugins)
Bundled plugins have contract tests that verify registration ownership:
```bash
pnpm test -- src/plugins/contracts/
```
These tests assert:
- Which plugins register which providers
- Which plugins register which speech providers
- Registration shape correctness
- Runtime contract compliance
### Running scoped tests
For a specific plugin:
```bash
pnpm test -- extensions/my-channel/
```
For contract tests only:
```bash
pnpm test -- src/plugins/contracts/shape.contract.test.ts
pnpm test -- src/plugins/contracts/auth.contract.test.ts
pnpm test -- src/plugins/contracts/runtime.contract.test.ts
```
## Lint enforcement (in-repo plugins)
Three rules are enforced by `pnpm check` for in-repo plugins:
1. **No monolithic root imports** -- `openclaw/plugin-sdk` root barrel is rejected
2. **No direct `src/` imports** -- plugins cannot import `../../src/` directly
3. **No self-imports** -- plugins cannot import their own `plugin-sdk/<name>` subpath
External plugins are not subject to these lint rules, but following the same
patterns is recommended.
## Test configuration
OpenClaw uses Vitest with V8 coverage thresholds. For plugin tests:
```bash
# Run all tests
pnpm test
# Run specific plugin tests
pnpm test -- extensions/my-channel/src/channel.test.ts
# Run with a specific test name filter
pnpm test -- extensions/my-channel/ -t "resolves account"
# Run with coverage
pnpm test:coverage
```
If local runs cause memory pressure:
```bash
OPENCLAW_TEST_PROFILE=low OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test
```
## Related
- [Building Plugins](/plugins/building-plugins)
- [Plugin SDK Overview](/plugins/sdk-overview)
- [Plugin Runtime](/plugins/sdk-runtime)
- [SDK Overview](/plugins/sdk-overview) -- import conventions
- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- channel plugin interface
- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- provider plugin hooks
- [Building Plugins](/plugins/building-plugins) -- getting started guide