Building Custom Plugins: The Complete OpenClaw Plugin SDK v2 Guide

Understanding the Plugin Architecture

OpenClaw plugins (called "skills") are modular units of functionality that extend the agent's capabilities. The SDK v2, released in v2026.3.28, introduced a completely redesigned architecture based on three principles: sandbox-first security, declarative manifests, and lifecycle hooks.

According to the OpenClaw developer documentation, the plugin system processes over 2.3 million skill invocations per day across the community. The most popular categories are productivity (28%), development tools (22%), smart home (18%), and data analysis (15%).

Each plugin consists of three components:

Skill Manifest (skill.json)

Declares the plugin's name, description, version, permissions, and capabilities. This is what OpenClaw reads to understand what your plugin can do.

Handler Functions

The actual code that executes when the plugin is invoked. Can be TypeScript, JavaScript, or Python.

Context API

The interface provided by OpenClaw that gives your plugin access to memory, LLM, user data, and system capabilities.

Building Your First Plugin

# Scaffold a new plugin
mkdir -p ~/.openclaw/workspace/skills/my-weather-plugin   # then write SKILL.md
cd my-weather-plugin

# Generated structure:
# my-weather-plugin/
# ├── skill.json          # Manifest
# ├── index.ts            # Main handler
# ├── test/
# │   └── index.test.ts   # Tests
# └── README.md

The skill manifest defines your plugin's identity and permissions:

// skill.json — Plugin manifest
{
  "name": "my-weather-plugin",
  "version": "1.0.0",
  "description": "Get real-time weather for any city",
  "author": "your-username",
  "permissions": ["network"],    // Requires network access
  "triggers": {
    "commands": ["weather", "forecast"],
    "patterns": ["what.*weather", "temperature in (.+)"]
  },
  "config": {
    "api_key": {
      "type": "string",
      "required": true,
      "description": "OpenWeatherMap API key"
    }
  }
}

The handler function receives the full context API:

// index.ts — Plugin handler
import { SkillContext, SkillResult } from '@openclaw/sdk';

export default async function handler(
  ctx: SkillContext
): Promise<SkillResult> {
  const city = ctx.args[0] || ctx.memory.get('user.location');
  
  if (!city) {
    return ctx.reply("Which city would you like weather for?");
  }

  const apiKey = ctx.config.get('api_key');
  const res = await ctx.fetch(
    `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`
  );
  const data = await res.json();

  // Store in memory for future reference
  await ctx.memory.set('last_weather_query', {
    city, temp: data.main.temp, time: Date.now()
  });

  return ctx.reply(
    `🌡️ **${city}**: ${data.main.temp}°C, ${data.weather[0].description}\n` +
    `💧 Humidity: ${data.main.humidity}% | 💨 Wind: ${data.wind.speed} m/s`
  );
}

The Context API Reference

API	Description	Permission
ctx.reply(text)	Send a response back to the user	None
ctx.memory.get(key)	Read from agent's long-term memory	None
ctx.memory.set(key, val)	Write to agent's long-term memory	None
ctx.fetch(url)	Make HTTP requests (sandboxed)	network
ctx.llm.complete(prompt)	Call the configured LLM for sub-tasks	None
ctx.fs.read(path)	Read files from allowed directories	filesystem
ctx.fs.write(path, data)	Write files to allowed directories	filesystem
ctx.schedule(cron, fn)	Schedule recurring tasks	cron
ctx.user	Current user info (name, platform, channel)	None
ctx.config.get(key)	Read plugin configuration values	None

Testing and Publishing

# Test locally
openclaw agent --message "use the my-weather-plugin skill"
openclaw agent --message "weather in Tokyo"

# Validate manifest
openclaw skill validate

# Install locally for integration testing
openclaw skills install ./my-weather-plugin

# Publish to community registry
clawhub skill publish
# → Submits for review (typically approved in 24-48 hours)

The OpenClaw skill registry at skills.openclaw.dev provides analytics for published plugins including install counts, usage frequency, and user ratings. Top plugins receive featured placement and contributor badges on the community forum.

Frequently Asked Questions

What languages can I use to write OpenClaw plugins?

Plugins can be written in TypeScript/JavaScript (primary), Python, or any language that can run as a subprocess. The SDK v2 provides first-class TypeScript types and Python bindings.

How do I publish a plugin to the registry?

Use 'clawhub skill publish' after testing. This submits your plugin for community review. Once approved, it appears in the official skill registry (skills.openclaw.dev) searchable by all users.

Can plugins access the internet?

By default, plugins run in a sandboxed environment with no network access. To enable network access, declare 'permissions: ["network"]' in your skill manifest and the user must explicitly approve it.

How many plugins does the OpenClaw ecosystem have?

As of May 2026, there are 700+ community-contributed skills in the official registry, covering productivity, development, smart home, finance, health tracking, and more.

Key Takeaways

700+ community plugins

The OpenClaw skill registry is thriving with plugins covering productivity, dev tools, smart home, and more.

Sandbox-first security

Plugins run in isolated environments by default. Network and filesystem access requires explicit permission declarations.

30-minute build time

From scaffold to working plugin in under 30 minutes with the SDK v2 CLI tools.

2.3M daily invocations

The plugin system is battle-tested with millions of daily executions across the community.

▶ Continue Reading

Guide

Custom Skill Development Guide

In-depth guide to building production-quality skills.

Read Article

Guide

Production Plugins Handbook

Best practices for publishing and maintaining plugins.

Read Article

Blog

MCP Server Guide

Complement plugins with MCP server integrations.

Read Article

Last updated: May 2, 2026 · Sources: OpenClaw Plugin SDK v2 docs, skills.openclaw.dev registry statistics, OpenClaw developer community

Understanding the Plugin Architecture

Each plugin consists of three components:

Skill Manifest (skill.json)

Declares the plugin's name, description, version, permissions, and capabilities. This is what OpenClaw reads to understand what your plugin can do.

Handler Functions

The actual code that executes when the plugin is invoked. Can be TypeScript, JavaScript, or Python.

Context API

The interface provided by OpenClaw that gives your plugin access to memory, LLM, user data, and system capabilities.

Building Your First Plugin

# Scaffold a new plugin
mkdir -p ~/.openclaw/workspace/skills/my-weather-plugin   # then write SKILL.md
cd my-weather-plugin

# Generated structure:
# my-weather-plugin/
# ├── skill.json          # Manifest
# ├── index.ts            # Main handler
# ├── test/
# │   └── index.test.ts   # Tests
# └── README.md

The skill manifest defines your plugin's identity and permissions:

// skill.json — Plugin manifest
{
  "name": "my-weather-plugin",
  "version": "1.0.0",
  "description": "Get real-time weather for any city",
  "author": "your-username",
  "permissions": ["network"],    // Requires network access
  "triggers": {
    "commands": ["weather", "forecast"],
    "patterns": ["what.*weather", "temperature in (.+)"]
  },
  "config": {
    "api_key": {
      "type": "string",
      "required": true,
      "description": "OpenWeatherMap API key"
    }
  }
}

The handler function receives the full context API:

// index.ts — Plugin handler
import { SkillContext, SkillResult } from '@openclaw/sdk';

export default async function handler(
  ctx: SkillContext
): Promise<SkillResult> {
  const city = ctx.args[0] || ctx.memory.get('user.location');
  
  if (!city) {
    return ctx.reply("Which city would you like weather for?");
  }

  const apiKey = ctx.config.get('api_key');
  const res = await ctx.fetch(
    `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`
  );
  const data = await res.json();

  // Store in memory for future reference
  await ctx.memory.set('last_weather_query', {
    city, temp: data.main.temp, time: Date.now()
  });

  return ctx.reply(
    `🌡️ **${city}**: ${data.main.temp}°C, ${data.weather[0].description}\n` +
    `💧 Humidity: ${data.main.humidity}% | 💨 Wind: ${data.wind.speed} m/s`
  );
}

The Context API Reference

API	Description	Permission
ctx.reply(text)	Send a response back to the user	None
ctx.memory.get(key)	Read from agent's long-term memory	None
ctx.memory.set(key, val)	Write to agent's long-term memory	None
ctx.fetch(url)	Make HTTP requests (sandboxed)	network
ctx.llm.complete(prompt)	Call the configured LLM for sub-tasks	None
ctx.fs.read(path)	Read files from allowed directories	filesystem
ctx.fs.write(path, data)	Write files to allowed directories	filesystem
ctx.schedule(cron, fn)	Schedule recurring tasks	cron
ctx.user	Current user info (name, platform, channel)	None
ctx.config.get(key)	Read plugin configuration values	None

Testing and Publishing

# Test locally
openclaw agent --message "use the my-weather-plugin skill"
openclaw agent --message "weather in Tokyo"

# Validate manifest
openclaw skill validate

# Install locally for integration testing
openclaw skills install ./my-weather-plugin

# Publish to community registry
clawhub skill publish
# → Submits for review (typically approved in 24-48 hours)

Frequently Asked Questions

What languages can I use to write OpenClaw plugins?

Plugins can be written in TypeScript/JavaScript (primary), Python, or any language that can run as a subprocess. The SDK v2 provides first-class TypeScript types and Python bindings.

How do I publish a plugin to the registry?

Use 'clawhub skill publish' after testing. This submits your plugin for community review. Once approved, it appears in the official skill registry (skills.openclaw.dev) searchable by all users.

Can plugins access the internet?

By default, plugins run in a sandboxed environment with no network access. To enable network access, declare 'permissions: ["network"]' in your skill manifest and the user must explicitly approve it.

How many plugins does the OpenClaw ecosystem have?

As of May 2026, there are 700+ community-contributed skills in the official registry, covering productivity, development, smart home, finance, health tracking, and more.