20e0ed521c
docs/cli/plugins.md was 55,872 characters and 11 H2 sections mixing a CLI
synopsis, an authoring how-to, install-policy explanation, lifecycle
reference, diagnostics, and marketplace feed trust. It is now a short index
over six children, one per reader job:
- cli/plugins/authoring Author, Feature scaffold, Provider scaffold
- cli/plugins/install Install, Marketplace shorthand
- cli/plugins/list List, Plugin index
- cli/plugins/uninstall-and-update Uninstall, Update
- cli/plugins/inspect-and-diagnose Inspect, Doctor, Registry
- cli/plugins/marketplace Marketplace
The index keeps the intro, the CardGroup, the full `## Commands` synopsis with
its trace/Nix/bundled notes, and `## Related`.
Anchor strategy: per-anchor redirects are impossible, because redirectSource()
in scripts/lib/docs-redirects.mjs throws on any source containing [?#]. Every
original anchor therefore stays alive on the parent index as an authored
<a id="..." /> stub pointing at its new home. Ids were computed with
parseDocsDocument, not a slug approximation, so the nine Accordion titles, the
two Tab titles, and the three ParamField ids are covered alongside the
headings. 34 pre-split ids: 32 stubbed, 2 (commands, related) still published
by the index itself, so no duplicate authored/canonical ID is raised. All 34
verified to resolve on /cli/plugins, and all 32 stub targets verified to
resolve on their child page. Collisions are empty on the index and on each of
the six children.
Losslessness, asserted mechanically against the pre-split file:
- index prefix + the six children (frontmatter and lede removed) + index
suffix reassemble byte-identically, sha256
c462b672a341344fca6dc46d623f6136f337844080b97bd469faffacb12265f8
- fences 17 -> 17, every one identical on info string and body sha256
- table rows 6 -> 14 (+8 = the new index page table)
- links: 27/27 original targets retained
- words 7,266 -> 8,023 (+757 = index page table, anchor map, child ledes)
- index 55,872 -> 8,662 chars; children 3,935-22,363 chars
No prose was rewritten and no prose exception was needed. The page had zero
intra-page anchor links and zero self-route links, and the one directional
reference the orphan check finds ("the trusted plugin id replacement above")
keeps its target on the same child page.
Closes audit findings: r3-0126, r3-1163 (partially: the accordions keep their
authored anchors and are no longer buried under a 2,065-word H2)
4 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.
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.