Common "gotchas" when creating Openclaw plugins

[solar ginkgo]

Whenever I develop a new plugin for Openclaw, I always seem to run into a minor issue that stands in the way of finishing the plugin and takes a long time to figure out. I think it happens, in part, because documentation for Openclaw is still evolving and there is not a lot of public information out there related to plugin development.
For that reason, I thought I would ask: What are the most common "gotchas" that people run into when developing plugins?
I'm thinking of issues that people don't often think about but when you know about them, plugin development is a lot easier.
I guess another way of putting it is common mistakes people make, and how to solve them.

[hot sun]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[ashen quiver]

A few high-leverage gotchas I’d keep on a checklist. I checked these against the current local docs/source, but plugin APIs move fast, so for a specific failure always include openclaw --version plus openclaw plugins inspect <id>.

1. Native plugins need two bits of metadata, not just code:
   openclaw.plugin.json in the plugin root, and package.json.openclaw. The manifest is read before plugin code runs, and it must include id + configSchema, even if the schema is empty. The manifest id also needs to match the entrypoint id.

2. Config validation is strict by design.
   If your schema says additionalProperties: false, stray keys in plugins.entries.<id>.config will make the plugin invalid. That is good, but it can feel mysterious if you forget a field or rename one.

3. “Installed” and “enabled” are separate.
   External/local plugins can be discovered but not loaded. Check:
   openclaw plugins list --verbose
openclaw plugins inspect <id>
   Then enable/configure under plugins.entries.<id>. Config changes generally need a Gateway restart, though normal gateway config-watch paths often restart automatically.

4. Local dev paths can lose to precedence or stale installs.
   Discovery has an order, and first match wins. If you have a globally installed copy plus a local dev copy, inspect the plugin origin. For local development, openclaw plugins install -l ./my-plugin is usually less confusing than copying builds around.

[ashen quiver]

5. Use focused SDK imports.
   Prefer things like:
   openclaw/plugin-sdk/plugin-entry
openclaw/plugin-sdk/channel-core
openclaw/plugin-sdk/runtime-store
   Avoid the old monolithic openclaw/plugin-sdk root import and avoid importing OpenClaw host internals directly. For host services, use api.runtime.

6. Channel plugins have different loading phases.
   For channels, use defineChannelPluginEntry, and if setup/onboarding needs to work before the full runtime loads, add a lightweight setup-entry.ts. Keep heavy SDKs, long-lived services, and client bootstrapping out of setup-only paths. api.registrationMode matters.

7. Tool allowlisting is easy to mix up.
   Optional agent tools should be registered with { optional: true }. Users enable optional tools through tools.allow, not plugins.allow. Tool names also cannot clash with core tools; conflicts get skipped.

8. Package runtime entries matter for published plugins.
   For installed npm/ClawHub packages, prefer built JS entries via runtimeExtensions / runtimeSetupEntry so users do not depend on runtime TypeScript compilation. Source extensions are fine for workspace/git checkout dev.

9. install, update, and --force are different paths.

[ashen quiver]

If the plugin id is already installed, normal upgrades should use openclaw plugins update <id-or-spec>. Use install --force only when intentionally overwriting the install source. Bare package specs try ClawHub first, then npm.

10. Debug with plugin-native commands first.
    My usual loop would be:
    openclaw --version
openclaw plugins list --verbose
openclaw plugins inspect <id>
openclaw doctor
openclaw logs --follow

Docs worth bookmarking:
https://docs.openclaw.ai/plugins/building-plugins
https://docs.openclaw.ai/plugins/manifest
https://docs.openclaw.ai/plugins/sdk-entrypoints
https://docs.openclaw.ai/plugins/sdk-runtime
https://docs.openclaw.ai/cli/plugins

[ashen quiver]

For “what have people actually hit in the wild?” this thread is a good start, but also ask in #users-helping-users. That’s better for real human war stories than just docs-derived gotchas.

[solar ginkgo]

Thank you! As always, very useful feedback.
Any preference on which of your posts I mark as the solution?

[ashen quiver]

Mark the longer gotchas checklist if you can. That’s the one future readers will actually want indexed.