Once you’ve built a plugin, you can share it with the community by publishing to npm. This guide covers packaging, versioning, and publishing OpenClaw plugins.

Package Structure

A publishable plugin should have this structure:

my-plugin/
  package.json
  index.ts          # Entry point
  src/              # Plugin source
  README.md         # Documentation
  LICENSE           # License file
  .npmignore        # npm publish exclusions

package.json

Configure your package.json for publishing:

{
  "name": "@openclaw/my-plugin",
  "version": "1.0.0",
  "description": "My OpenClaw plugin",
  "type": "module",
  "main": "index.ts",
  "keywords": ["openclaw", "plugin", "ai", "gateway"],
  "author": "Your Name <you@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/openclaw-plugin-my-plugin"
  },
  "bugs": {
    "url": "https://github.com/yourusername/openclaw-plugin-my-plugin/issues"
  },
  "homepage": "https://github.com/yourusername/openclaw-plugin-my-plugin#readme",
  "dependencies": {
    "@sinclair/typebox": "0.34.48"
  },
  "devDependencies": {
    "openclaw": "latest"
  },
  "peerDependencies": {
    "openclaw": ">=2026.2.0"
  },
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

Key Fields

string

required

Package name. Use the @openclaw/ scope for official plugins:

@openclaw/my-plugin (official)
openclaw-plugin-my-plugin (community)
@yourscope/openclaw-my-plugin (scoped)

string

required

Version number following semver:

1.0.0 - Initial release
1.1.0 - New features (backward compatible)
2.0.0 - Breaking changes

string

required

Module type. Set to "module" for ESM.

string

required

Entry point. Use index.ts or dist/index.js (if compiled).

array

Keywords for npm search. Include "openclaw" and "plugin".

object

Runtime dependencies. Include only what your plugin needs at runtime.

object

Development dependencies. Include openclaw for type imports.

object

Specify compatible OpenClaw versions:

{
  "openclaw": ">=2026.2.0"
}

object

required

OpenClaw metadata:

{
  "extensions": ["./index.ts"],
  "channel": {
    "id": "my-channel",
    "label": "My Channel"
  }
}

Naming Conventions

Official Plugins

Official plugins use the @openclaw/ scope:

@openclaw/matrix
@openclaw/msteams
@openclaw/voice-call

Community Plugins

Community plugins should use descriptive names:

openclaw-plugin-slack-advanced
openclaw-jira-integration
@yourname/openclaw-custom-tool

Channel Plugins

Channel plugins should clearly indicate the platform:

@openclaw/rocketchat
openclaw-plugin-zulip

Tool Plugins

Tool plugins should describe their capability:

openclaw-plugin-github
openclaw-tool-database
@yourname/openclaw-crm

README

Include a comprehensive README:

# @openclaw/my-plugin

Brief description of what your plugin does.

## Installation

```bash
openclaw plugins install @openclaw/my-plugin

Configuration

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "enabled": true,
        "config": {
          "apiKey": "your-api-key"
        }
      }
    }
  }
}

Usage

Examples of how to use your plugin.

License

MIT

## .npmignore

Exclude unnecessary files from the package:

Development files

*.test.ts *.spec.ts tsconfig.json vitest.config.ts .eslintrc .prettierrc

Build artifacts

*.log .DS_Store node_modules/

CI/CD

.github/ .gitlab-ci.yml

Documentation

docs/ examples/

## Versioning

Follow [semantic versioning](https://semver.org/):

### Major Version (X.0.0)

Breaking changes:
- Changed API signatures
- Removed features
- Incompatible with previous versions

### Minor Version (1.X.0)

New features (backward compatible):
- New tools or capabilities
- New configuration options
- Enhanced functionality

### Patch Version (1.0.X)

Bug fixes:
- Fixed bugs
- Documentation updates
- Performance improvements

## Publishing to npm

### 1. Create npm account

Sign up at [npmjs.com](https://www.npmjs.com/) if you don't have an account.

### 2. Login to npm

Enter your credentials:

```bash
npm login

3. Build your plugin (if needed)

If you compile TypeScript:

npm run build

4. Test the package

Verify what will be published:

npm pack --dry-run

5. Publish

For scoped packages:

npm publish --access public

For unscoped packages:

npm publish

Publishing Updates

To publish updates:

Update version:

npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

Publish:
npm publish
Tag the release:
git tag v1.0.1 git push --tags

Distribution Tags

Use distribution tags for pre-releases:

# Publish beta version
npm version 1.1.0-beta.1
npm publish --tag beta

# Users install with:
# openclaw plugins install @openclaw/my-plugin@beta

Common tags:

latest - Stable releases (default)
beta - Beta releases
next - Development releases
canary - Nightly builds

Plugin Registry

Official plugins are listed in OpenClaw’s plugin registry. To submit your plugin:

Publish to npm
Open an issue at openclaw/openclaw
Include:
- Plugin name and npm package
- Description
- Documentation link
- Example configuration

Best Practices

1. Documentation

Provide clear documentation:

Installation instructions
Configuration examples
Usage examples
API reference
Troubleshooting

2. Testing

Include tests:

{
  "scripts": {
    "test": "vitest"
  },
  "devDependencies": {
    "vitest": "latest"
  }
}

3. TypeScript Types

Include type definitions:

{
  "types": "dist/index.d.ts",
  "files": [
    "dist/",
    "index.ts",
    "src/"
  ]
}

4. Changelog

Maintain a CHANGELOG.md:

# Changelog

## [1.1.0] - 2026-02-19
### Added
- New feature X
- Support for Y

### Fixed
- Bug in Z

## [1.0.0] - 2026-02-01
- Initial release

5. License

Include a LICENSE file. Popular choices:

MIT (permissive)
Apache 2.0 (permissive with patent grant)
GPL (copyleft)

6. CI/CD

Automate testing and publishing:

# .github/workflows/publish.yml
name: Publish
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org/
      - run: npm ci
      - run: npm test
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

Example: Publishing a Tool Plugin

# 1. Initialize project
mkdir openclaw-plugin-github
cd openclaw-plugin-github
npm init -y

# 2. Install dependencies
npm install @sinclair/typebox
npm install --save-dev openclaw typescript

# 3. Write plugin (index.ts)
# 4. Write README.md
# 5. Create LICENSE

# 6. Test locally
openclaw plugins install ./

# 7. Publish
npm login
npm publish --access public

# 8. Install from npm
openclaw plugins install openclaw-plugin-github

Next Steps

Plugin SDK Reference - Complete API documentation
Examples - Real-world plugin examples
Built-in Extensions - Explore existing plugins

Overview

SDK Reference

Extensions

Publishing Plugins

Package Structure

package.json

Key Fields

Naming Conventions

Official Plugins

Community Plugins

Channel Plugins

Tool Plugins

README

Configuration

Usage

License

Development files

Build artifacts

CI/CD

Documentation

3. Build your plugin (if needed)

4. Test the package

5. Publish

Publishing Updates

Distribution Tags

Plugin Registry

Best Practices

1. Documentation

2. Testing

3. TypeScript Types

4. Changelog

5. License

6. CI/CD

Example: Publishing a Tool Plugin

Next Steps

​Package Structure

​package.json

​Key Fields

​Naming Conventions

​Official Plugins

​Community Plugins

​Channel Plugins

​Tool Plugins

​README

​Configuration

​Usage

​License

​Development files

​Build artifacts

​CI/CD

​Documentation

​3. Build your plugin (if needed)

​4. Test the package

​5. Publish

​Publishing Updates

​Distribution Tags

​Plugin Registry

​Best Practices

​1. Documentation

​2. Testing

​3. TypeScript Types

​4. Changelog

​5. License

​6. CI/CD

​Example: Publishing a Tool Plugin

​Next Steps

Package Structure

package.json

Key Fields

Naming Conventions

Official Plugins

Community Plugins

Channel Plugins

Tool Plugins

README

Configuration

Usage

License

Development files

Build artifacts

CI/CD

Documentation

3. Build your plugin (if needed)

4. Test the package

5. Publish

Publishing Updates

Distribution Tags

Plugin Registry

Best Practices

1. Documentation

2. Testing

3. TypeScript Types

4. Changelog

5. License

6. CI/CD

Example: Publishing a Tool Plugin

Next Steps