c8eab36020
* refactor: remove TypeScript 6 from plugin runtime and tooling Keep source plugin loading on Jiti and native module transforms, move development analysis and declaration builds to TypeScript 7, and preserve captured loader and input ownership contracts. Scaffolds compile to the same entry path without shipping a compiler in production. * refactor: use native checker for restart preflight detection * fix: keep test-directory docs out of native helper scans * fix: preserve native compiler tooling across CI runtimes Keep compiler-backed tests on the supported Node transport, preserve declared Windows aliases and partial-source analysis, and bind relocated SDK reports to their installed compiler. Retain strict package input admission and the existing fixture assertions. * test: compare messaging guard diagnostics without sorting * fix: bound native tooling memory and preserve bootstrap loading * fix: bound native declaration builds with tsdown scheduling * fix: retire compiler-only helpers from installed packages * test: migrate routing import scan to native parser * test(ui): wait for recovered model catalog receipt
4.3 KiB
| summary | title | read_when | ||
|---|---|---|---|---|
| Scaffold, build, validate, and pack an OpenClaw plugin with `openclaw plugins init` | Author plugins |
|
This page covers the authoring commands: plugins init, plugins build,
plugins validate, and plugins pack, plus the tool, feature, and provider
scaffolds they generate.
Author
openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate
plugins init creates a minimal TypeScript tool plugin by default. The first
argument is the plugin id; --name sets the display name. OpenClaw uses the
id for the default output directory and package naming. Tool scaffolds use
defineToolPlugin and generate package.json scripts plugin:build and
plugin:validate that build then call openclaw plugins build/validate.
plugins build imports the built entry, reads its static tool metadata, writes
openclaw.plugin.json, and keeps package.json's openclaw.extensions aligned.
plugins validate checks that the generated manifest, package metadata, and
current entry export still agree. Pass --json for a machine-readable
validation result. See Tool Plugins for the full
authoring workflow.
The scaffold writes TypeScript source but generates metadata from the built
./dist/index.js entry, so the workflow also works with the published CLI. Use
--entry <path> when the entry is not the default package entry. Use
plugins build --check in CI to fail when generated metadata is stale without
rewriting files.
Tool and provider scaffolds compile src/index.ts and its imported modules into
dist, leaving independent test files out of the package. Feature scaffolds also
include their separate browser entry in TypeScript checks. All scaffolds pin
TypeScript 7.0.2 and set rootDir to src, keeping the compiled entry at
dist/index.js.
Feature scaffold and artifacts
Use --type feature for a typed backend operation, agent tool, native page,
and composer replacement. Run npm install, npm run build, and
npm run validate in the generated project. Its browser source is declared in
package.json.openclaw.controlUi; plugins build writes immutable bundled
assets and their manifest declaration.
Plugin APIs are experimental. To load the scaffold's native browser UI, enable Settings → Labs → Custom plugin UI, then restart the Gateway and reload the browser. See Enable custom plugin UI.
plugins pack validates a built project, bundles its backend dependencies, and
writes an archive containing compiled code and UI with no install scripts or
runtime package dependencies. --json returns its absolute path, SHA-256 digest,
and exact plugin_activate_artifact request. The output file must not exist.
The default filename is <plugin-id>.tgz in the project root, with / replaced
by __ for scoped ids (for example, @author__tools.tgz). Use --out to choose
another path. Packing follows the package's runtime entry selection, including
runtimeExtensions, and bundles a declared setup entry separately. Source/runtime
entry paths are rewritten to the compiled files included in the archive.
See Feature plugins for activation approval, reload,
view lifecycle, and recovery.
Provider scaffold
openclaw plugins init acme-models --name "Acme Models" --type provider
cd acme-models
npm install
npm run build
npm test
npm run validate
Provider scaffolds create a generic OpenAI-compatible model provider plugin
with API-key auth plumbing, a npm run validate script that runs
clawhub package validate, ClawHub package metadata, and a manually
dispatched GitHub Actions workflow for future trusted publishing via GitHub
OIDC. Provider scaffolds do not generate skills and do not use
openclaw plugins build/validate; those commands are for the tool
scaffold's generated-metadata path.
Before publishing, replace the placeholder API base URL, model catalog, docs route, credential text, and README copy with real provider details. Use the generated README for first-time ClawHub publishing and trusted-publisher setup.