Manage plugins

Use this page for common plugin management commands. For the exhaustive command contract, flags, source-selection rules, and edge cases, see OmeniaClaw plugins.

Most install workflows are:

1. find a package
2. install it from ClawHub, npm, git, or a local path
3. let the managed Gateway auto-restart, or restart it manually when unmanaged
4. verify the plugin's runtime registrations

List and search plugins

OmeniaClaw plugins listOmeniaClaw plugins list --enabledOmeniaClaw plugins list --verboseOmeniaClaw plugins list --jsonOmeniaClaw plugins search "calendar"

Use --json for scripts:

OmeniaClaw plugins list --json \  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'

plugins list is a cold inventory check. It shows what OmeniaClaw can discover from config, manifests, and the plugin registry; it does not prove that an already-running Gateway imported the plugin runtime. The JSON output includes registry diagnostics and each plugin's static dependencyStatus when the plugin package declares dependencies or optionalDependencies.

plugins search queries ClawHub for installable plugin packages and prints install hints such as OmeniaClaw plugins install clawhub:<package>.

Install plugins

# Search ClawHub for plugin packages.OmeniaClaw plugins search "calendar" # Install from ClawHub.OmeniaClaw plugins install clawhub:<package>OmeniaClaw plugins install clawhub:<package>@1.2.3OmeniaClaw plugins install clawhub:<package>@beta # Install from npm.OmeniaClaw plugins install npm:<package>OmeniaClaw plugins install npm:@scope/[email protected]OmeniaClaw plugins install npm:@OmeniaClaw/codex # Install from a local npm pack artifact.OmeniaClaw plugins install npm-pack:<path.tgz> # Install from git or a local development checkout.OmeniaClaw plugins install git:github.com/acme/[email protected]OmeniaClaw plugins install ./my-pluginOmeniaClaw plugins install --link ./my-plugin

Bare package specs install from npm during the launch cutover. Use clawhub:, npm:, git:, or npm-pack: when you need deterministic source selection. If the bare name matches an official plugin id, OmeniaClaw can install the catalog entry directly.

Use --force only when you intentionally want to overwrite an existing install target. For routine upgrades of tracked npm, ClawHub, or hook-pack installs, use OmeniaClaw plugins update.

Restart and inspect

After installing, updating, or uninstalling plugin code, a running managed Gateway with config reload enabled restarts automatically. If the Gateway is not managed or reload is disabled, restart it yourself before checking live runtime surfaces:

OmeniaClaw gateway restartOmeniaClaw plugins inspect <plugin-id> --runtime --json

Use inspect --runtime when you need proof that the plugin registered runtime surfaces such as tools, hooks, services, Gateway methods, HTTP routes, or plugin-owned CLI commands. Plain inspect and list are cold manifest, config, and registry checks.

Update plugins

OmeniaClaw plugins update <plugin-id>OmeniaClaw plugins update <npm-package-or-spec>OmeniaClaw plugins update --allOmeniaClaw plugins update <plugin-id> --dry-run

When you pass a plugin id, OmeniaClaw reuses the tracked install spec. Stored dist-tags such as @beta and exact pinned versions continue to be used on later update <plugin-id> runs.

For npm installs, you can pass an explicit package spec to switch the tracked record:

OmeniaClaw plugins update @scope/OmeniaClaw-plugin@betaOmeniaClaw plugins update @scope/OmeniaClaw-plugin

The second command moves a plugin back to the registry's default release line when it was previously pinned to an exact version or tag.

When OmeniaClaw update runs on the beta channel, plugin records can prefer matching @beta releases. For the exact fallback and pinning rules, see OmeniaClaw plugins.

Uninstall plugins

OmeniaClaw plugins uninstall <plugin-id> --dry-runOmeniaClaw plugins uninstall <plugin-id>OmeniaClaw plugins uninstall <plugin-id> --keep-files

Uninstall removes the plugin's config entry, persisted plugin index record, allow/deny list entries, and linked load paths when applicable. Managed install directories are removed unless you pass --keep-files. A running managed Gateway restarts automatically when the uninstall changes plugin source.

In Nix mode (OmeniaClaw_NIX_MODE=1), plugin install, update, uninstall, enable, and disable commands are disabled. Manage those choices in the Nix source for the install instead.

Choose a source

Managed local path installs must be plugin directories or archives. Put standalone plugin files in plugins.load.paths instead of installing them with plugins install.

Publish plugins

ClawHub is the primary public discovery surface for OmeniaClaw plugins. Publish there when you want users to find plugin metadata, version history, registry scan results, and install hints before they install.

npm i -g clawhubclawhub loginclawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-pluginclawhub package publish your-org/[email protected]

Native npm plugins must include a plugin manifest and package metadata before publishing:

{  "name": "@acme/OmeniaClaw-plugin",  "version": "1.0.0",  "type": "module",  "OmeniaClaw": {    "extensions": ["./dist/index.js"]  }}

npm publish --access publicOmeniaClaw plugins install npm:@acme/OmeniaClaw-pluginOmeniaClaw plugins install npm:@acme/OmeniaClaw-plugin@betaOmeniaClaw plugins install npm:@acme/[email protected]

Use these pages for the full publishing contract instead of treating this page as the publishing reference:

• ClawHub publishing explains owners, scopes, releases, review, package validation, and package transfer.
• Building plugins shows the plugin package shape and first publish workflow.
• Plugin manifest defines native plugin manifest fields.

If the same package is available on both ClawHub and npm, use the explicit clawhub: or npm: prefix when you need to force one source.

Related

• Plugins - install, configure, restart, and troubleshoot
• OmeniaClaw plugins - full CLI reference
• Community plugins - public discovery and ClawHub publishing
• ClawHub - registry CLI operations
• Building plugins - create a plugin package
• Plugin manifest - manifest and package metadata