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
Package name. Use the @openclaw/ scope for official plugins:
@openclaw/my-plugin (official)openclaw-plugin-my-plugin (community)@yourscope/openclaw-my-plugin (scoped)
Version number following semver:
1.0.0 - Initial release1.1.0 - New features (backward compatible)2.0.0 - Breaking changes
Module type. Set to "module" for ESM.
Entry point. Use index.ts or dist/index.js (if compiled).
Keywords for npm search. Include "openclaw" and "plugin".
Runtime dependencies. Include only what your plugin needs at runtime.
Development dependencies. Include openclaw for type imports.
Specify compatible OpenClaw versions:{
"openclaw": ">=2026.2.0"
}
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 should use descriptive names:
openclaw-plugin-slack-advancedopenclaw-jira-integration@yourname/openclaw-custom-tool
Channel Plugins
Channel plugins should clearly indicate the platform:
@openclaw/rocketchatopenclaw-plugin-zulip
Tool plugins should describe their capability:
openclaw-plugin-githubopenclaw-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:
4. Test the package
Verify what will be published:
5. Publish
For scoped packages:
npm publish --access public
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:
-
Tag the release:
git tag v1.0.1
git push --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
latest - Stable releases (default)beta - Beta releasesnext - Development releasescanary - 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}}
# 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
