This skill is purely instructional and does not execute remote code, access external endpoints (other than documentation), or modify system files without explicit user direction. All generated code should be reviewed before execution.
Plugins run in-process with the Gateway (via jiti, TypeScript loaded at runtime). They extend OpenClaw with:
| Capability | Registration method |
|---|---|
| Messaging channel | api.registerChannel(...) |
| LLM / model provider | api.registerProvider(...) |
| Agent tool (LLM-callable) | api.registerTool(tool, opts?) |
| Text-to-speech / STT | api.registerSpeechProvider(...) |
| Image generation | api.registerImageGenerationProvider(...) |
| Media understanding | api.registerMediaUnderstandingProvider(...) |
| Web search | api.registerWebSearchProvider(...) |
| Custom CLI command | api.registerCommand(def) |
| Event hook | api.registerHook(events, handler, opts?) |
| Gateway HTTP route | api.registerHttpRoute(params) |
| Gateway RPC method | api.registerGatewayMethod(name, handler) |
| CLI subcommand | api.registerCli(registrar, opts?) |
| Background service | api.registerService(service) |
| Interactive handler | api.registerInteractiveHandler(registration) |
| Context engine (exclusive) | api.registerContextEngine(id, factory) |
| Memory prompt section | api.registerMemoryPromptSection(builder) |
> Treat plugins as trusted code — they run with full Gateway access.
| Format | How it works |
|---|---|
| Native | openclaw.plugin.json + TypeScript module — official plugins, npm packages |
| Bundle | Codex/Claude/Cursor-compatible layout (.codex-plugin/, .claude-plugin/, .cursor-plugin/) |
This skill covers native plugins. For bundles see the Bundles docs.
my-plugin/
├── openclaw.plugin.json ← REQUIRED manifest
├── package.json ← npm package + openclaw metadata
├── index.ts ← main entry point
├── setup-entry.ts ← lightweight setup-only entry (optional, channels)
└── src/
├── channel.ts ← channel plugin object (if channel plugin)
├── runtime.ts ← createPluginRuntimeStore (if needed)
├── tools.ts
└── provider.test.ts
Internal barrel convention:
api.ts ← public exports for external consumers
runtime-api.ts ← internal-only runtime exports
Never import your own plugin through openclaw/plugin-sdk/. Route internal imports through ./api.ts.
Tool / provider plugin:
{
"name": "@myorg/openclaw-my-plugin",
"version": "1.0.0",
"type": "module",
"openclaw": {
"extensions": ["./index.ts"],
"providers": ["my-provider"]
}
}
Channel plugin:
{
"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 shown in onboarding."
},
"startup": {
"deferConfiguredChannelFullLoadUntilAfterListen": true
}
}
}
openclaw field reference:
| Field | Type | Description |
|---|---|---|
| extensions | string[] | Entry point files (relative paths) |
| 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 |
> Every native plugin MUST have this file. OpenClaw validates config from it WITHOUT executing plugin code.
Minimal (no config):
{
"id": "my-plugin",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}
Full example (provider with auth):
{
"id": "my-provider",
"name": "My Provider",
"description": "Adds My Provider LLM to OpenClaw",
"version": "1.0.0",
"providers": ["my-provider"],
"providerAuthEnvVars": {
"my-provider": ["MY_PROVIDER_API_KEY"]
},
"providerAuthChoices": [
{
"provider": "my-provider",
"method": "api-key",
"choiceId": "my-provider-api-key",
"choiceLabel": "My Provider API key",
"optionKey": "myProviderApiKey",
"cliFlag": "--my-provider-api-key",
"cliOption": "--my-provider-api-key <key>",
"cliDescription": "My Provider API key",
"onboardingScopes": ["text-inference"]
}
],
"uiHints": {
"apiKey": {
"label": "API Key",
"placeholder": "sk-...",
"sensitive": true,
"help": "From your My Provider dashboard"
}
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"apiKey": { "type": "string" }
},
"required": ["apiKey"]
}
}
Full manifest field reference → see references/manifest.md
// ✅ ALWAYS use focused subpaths
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
// ❌ NEVER use monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";
Full subpath reference → see references/sdk-subpaths.md
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";
export default definePluginEntry({
id: "my-plugin",
name: "My Plugin",
description: "Human-readable description",
register(api: OpenClawPluginApi) {
// Access plugin config (from plugins.entries.my-plugin.config)
const config = api.pluginConfig as { apiKey: string };
// Required tool — always available to LLM
api.registerTool({
name: "my_tool", // must not clash with core tools
description: "Does something useful",
parameters: Type.Object({
input: Type.String({ description: "The input" }),
count: Type.Optional(Type.Number()),
}),
async execute(_callId, params) {
return {
content: [{ type: "text", text: `Result: ${params.input}` }],
};
},
});
// Optional tool — user must add to tools.allow
api.registerTool(
{
name: "advanced_tool",
description: "Side-effect tool (opt-in)",
parameters: Type.Object({ pipeline: Type.String() }),
async execute(_callId, params) {
return { content: [{ type: "text", text: params.pipeline }] };
},
},
{ optional: true },
);
// Command — runs without going through LLM
api.registerCommand({
name: "my-plugin-status",
description: "Show plugin status",
handler: async () => ({ text: "Plugin is running" }),
});
// Event hook
api.registerHook(["message.received"], async (event) => {
api.logger.info(`Received message: ${event.type}`);
});
},
});
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
import { channelPlugin } from "./src/channel.js";
import { setMyRuntime } from "./src/runtime.js";
export default defineChannelPluginEntry({
id: "my-channel",
name: "My Channel",
description: "Connects OpenClaw to MyPlatform",
plugin: channelPlugin,
setRuntime: setMyRuntime,
// registerFull: only for tools/routes that should NOT load in setup-only mode
registerFull(api) {
api.registerTool({
name: "my_channel_status",
description: "Check channel connection",
parameters: { type: "object", properties: {} },
async execute() {
return { content: [{ type: "text", text: "connected" }] };
},
});
},
});
// setup-entry.ts — lightweight, no heavy imports
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
import { channelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(channelPlugin);
When OpenClaw uses setupEntry: channel is disabled/unconfigured, or deferred loading is on.
Must include: channel registration, HTTP routes needed before listen, gateway methods for startup.
Must NOT include: CLI registrations, background services, heavy runtime imports.
export default definePluginEntry({
id: "my-hybrid",
name: "My Hybrid Plugin",
register(api) {
api.registerProvider({ id: "my-provider", /* ... */ });
api.registerSpeechProvider({ id: "my-speech", /* ... */ });
api.registerTool({ name: "my_tool", /* ... */ });
api.registerCommand({ name: "my-cmd", /* ... */ });
},
});
// Read/write config
const cfg = api.runtime.config.loadConfig();
await api.runtime.config.writeConfigFile({ ...cfg, talk: { enabled: true } });
// TTS (telephony)
const result = await api.runtime.tts.textToSpeechTelephony({
text: "Hello from OpenClaw",
cfg: api.config,
});
// Returns PCM audio buffer + sample rate. Edge TTS NOT supported for telephony.
// List voices
const voices = await api.runtime.tts.listVoices({ provider: "openai", cfg });
// Web search
const results = await api.runtime.webSearch.search({ query: "...", maxResults: 5 });
// Spawn subagent
const session = await api.runtime.subagent.spawn({ /* ... */ });
Full runtime namespace reference → see references/runtime.md
For shared mutable state across module imports (the correct pattern):
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
const runtimeStore = createPluginRuntimeStore<{
client: MyPlatformClient;
logger: Logger;
}>("My Channel runtime not initialized");
export const setMyRuntime = (rt: { client: MyPlatformClient; logger: Logger }) =>
runtimeStore.setRuntime(rt);
export const getMyRuntime = () => runtimeStore.getRuntime();
// Also: tryGetRuntime(), clearRuntime()
plugins:
enabled: true
allow:
- my-plugin
deny: []
load:
paths:
- ~/Projects/my-plugin # for dev/local plugins
entries:
my-plugin:
enabled: true
config:
apiKey: "sk-..."
timeout: 60
# Enable optional tools
tools:
allow:
- advanced_tool # specific tool
- my-plugin # all tools from plugin
# Plugin slots (exclusive categories)
plugins:
slots:
memory: memory-lancedb # or "memory-core" or "none"
contextEngine: my-engine # or "legacy"
# Channel config (for channel plugins)
channels:
my-channel:
enabled: true
token: "bot-token"
allowFrom:
- "user-id-1"
plugins.load.paths — explicit paths in config
/.openclaw// ~/.openclaw// — global user extensions
Conflict rule: If multiple plugins try to own the same channel/tool id, first match wins, others are skipped with a warning.
# Discovery
openclaw plugins list
openclaw plugins list --enabled --verbose
openclaw plugins list --json
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
openclaw plugins doctor
# Install
openclaw plugins install @myorg/my-plugin # ClawHub first, npm fallback
openclaw plugins install clawhub:@myorg/my-plugin # ClawHub only
openclaw plugins install ./my-plugin # local path
openclaw plugins install -l ./my-plugin # link (dev, no copy)
openclaw plugins install <spec> --force # overwrite existing
openclaw plugins install <spec> --pin # record exact npm spec
openclaw plugins install <spec> --marketplace https://github.com/<owner>/<repo>
# Manage
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --keep-files
openclaw plugins registry --refresh # refresh metadata after changes
# Fix
openclaw doctor --fix # auto-remove stale entries
openclaw gateway restart # REQUIRED after any plugin change
# Run plugin tests (vitest)
pnpm test -- extensions/my-plugin/
# With coverage
pnpm test:coverage
# Scoped
pnpm test -- extensions/my-plugin/src/channel.test.ts -t "resolves account"
# Low-memory mode
OPENCLAW_TEST_PROFILE=low OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test
Full testing patterns → see references/testing.md
npm install --ignore-scripts — no lifecycle scripts
plugins.allow entry emit a startup warning
plugins.deny always wins over plugins.allow
optional: true for tools with side effects or extra binary requirements
package.json has "type": "module" and correct openclaw.extensions
openclaw.plugin.json present with valid id and configSchema (even if empty)
definePluginEntry (tools/providers) or defineChannelPluginEntry (channels)
openclaw/plugin-sdk/ — never the root barrel
./api.ts or ./runtime-api.ts, not SDK self-imports
scripts in dependency packages (security)
{ optional: true }
uiHints.sensitive: true on any API key / secret config fields
openclaw gateway restart
pnpm test -- extensions/my-plugin/
# Publish to npm (ClawHub auto-indexes npm)
npm publish --access public
# Users install with:
openclaw plugins install @myorg/my-plugin
# OpenClaw tries ClawHub first, npm fallback automatically
references/manifest.md — complete openclaw.plugin.json field reference
references/sdk-subpaths.md — all 100+ SDK import subpaths grouped by purpose
references/channel-plugin.md — full channel plugin walkthrough (ChannelPlugin shape, pairing, actions, setup wizard)
references/provider-plugin.md — full provider plugin (all 22 hooks, auth, catalog, dynamic models, multi-capability)
references/runtime.md — all api.runtime namespaces with examples
references/testing.md — unit testing patterns, mocking, contract tests
共 1 个版本