OpenClaw Plugin Development — Expert Reference

🛡️ Security, Privacy & Trust

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.

• Data Privacy: This skill does not collect or transmit user data.
• External Calls: No hidden background network requests.
• Trust Statement: This skill follows OpenClaw's security best practices for plugin development.

What can a plugin do?

Plugins run in-process with the Gateway (via jiti, TypeScript loaded at runtime). They extend OpenClaw with:

Treat plugins as trusted code — they run with full Gateway access.

Plugin formats

This skill covers native plugins. For bundles see the Bundles docs.

Step 1 — File structure

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/<your-plugin>. Route internal imports through ./api.ts.

Step 2 — package.json

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:

Step 3 — openclaw.plugin.json (Manifest)

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

Step 4 — Entry Points

Import rules (CRITICAL)

// ✅ 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

Tool / Hook / Provider plugin (definePluginEntry)

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}`);
    });
  },
});

Channel plugin (defineChannelPluginEntry)

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 (channels only)

// 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.

One plugin, many capabilities

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", /* ... */ });
  },
});

Step 5 — Runtime helpers (api.runtime)

// 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

createPluginRuntimeStore

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()

Step 6 — openclaw.yml config

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"

Step 7 — Discovery precedence (first match wins)

1. plugins.load.paths — explicit paths in config
2. <workspace>/.openclaw/<plugin-root>/ — workspace-local (disabled by default, must explicitly enable)
3. ~/.openclaw/<plugin-root>/ — global user extensions
4. Bundled plugins — shipped with OpenClaw (many enabled by default)

Conflict rule: If multiple plugins try to own the same channel/tool id, first match wins, others are skipped with a warning.

Step 8 — CLI commands

# 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

Step 9 — Testing

# 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

Security rules (MUST follow)

• Dependencies installed with npm install --ignore-scripts — no lifecycle scripts
• Keep deps "pure JS/TS" — avoid packages with postinstall builds
• Plugin entries must resolve inside the plugin directory (symlink escapes are rejected)
• Non-bundled plugins without plugins.allow entry emit a startup warning
• plugins.deny always wins over plugins.allow
• Use optional: true for tools with side effects or extra binary requirements
• Treat all plugin code as trusted — review before installing from unknown sources

Pre-submission checklist

• package.json has "type": "module" and correct openclaw.extensions
• openclaw.plugin.json present with valid id and configSchema (even if empty)
• Entry uses definePluginEntry (tools/providers) or defineChannelPluginEntry (channels)
• All imports use openclaw/plugin-sdk/<subpath> — never the root barrel
• Internal imports go through ./api.ts or ./runtime-api.ts, not SDK self-imports
• No scripts in dependency packages (security)
• Optional tools marked { optional: true }
• uiHints.sensitive: true on any API key / secret config fields
• Gateway restarted: openclaw gateway restart
• Tests pass: pnpm test -- extensions/my-plugin/

Publishing

# 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

Reference files (read when needed)

• 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