Configuration settings for non-capability plugins?

[worn fjord]

I've created a plugin with shape "non-capability" and I can't seem to get Openclaw to pass to it the configuration settings for the plugin that are in the openclaw.json configuration file. Is there something special about how Openclaw gets configuration settings to non-capability plugins that needs to be kept in mind when developing them?

[wispy maple]

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

[wooden marsh]

I checked the current docs/source. non-capability does not mean “no config”; it just means the plugin registers tools/commands/services/routes but no provider/channel/etc capability. For a native OpenClaw plugin, config is passed as api.pluginConfig during register(api).

The config needs to be under the plugin entry’s config object, keyed by the manifest/plugin id:

{
  plugins: {
    load: { paths: ["/path/to/plugin"] },
    entries: {
      "my-plugin-id": {
        enabled: true,
        config: {
          someSetting: "value"
        }
      }
    }

[wooden marsh]

  }
}

Common gotchas:

• The plugin manifest must have a configSchema; native plugins with no schema are treated as invalid/missing config schema.
• If your schema has additionalProperties: false, every configured field must be declared in properties, or the plugin won’t load with that config.
• Read it from api.pluginConfig, not from top-level api.config unless you’re intentionally resolving the raw config yourself.
• Config changes require a gateway restart: https://docs.openclaw.ai/gateway/configuration-reference#plugins
• If the plugin keeps a long-lived service/route and needs live config after startup, use the runtime helper pattern: resolveLivePluginConfigObject(api.runtime.config?.loadConfig, "my-plugin-id", api.pluginConfig).

For debugging, please share openclaw --version and the non-secret output of:

openclaw plugins inspect my-plugin-id

[wooden marsh]

Docs: https://docs.openclaw.ai/plugins/architecture#plugin-shapes and https://docs.openclaw.ai/cli/plugins#inspect

[worn fjord]

Thank you very much for the detailed response! This is exactly what I needed.

I was reading config from a dead register(api, config) second parameter, when I should have been reading from api.pluginConfig. Switching to api.pluginConfig solved the problem immediately — it's reading the configuration values both at startup and dynamically during the session.

Your note about the configSchema requirement also helped me confirm my manifest is properly structured. Much appreciated!

Which part of your reply would you prefer I mark as the solution to my question?

[wooden marsh]

Mark the message with the api.pluginConfig answer, especially the bit saying config belongs under plugins.entries.<id>.config and is passed as api.pluginConfig during register(api).

That’s the actual fix for future readers. Glad that solved it.