Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix Plugin SDK needs a backwards compatibility strategy for external plugins [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#55533•Fetched 2026-04-08 01:38:21
View on GitHub
Comments
0
Participants
1
Timeline
1
Reactions
0
Author
awsome-oawsome-o
Participants
awsome-oawsome-o
Timeline (top)
cross-referenced ×1

We maintain grafana-lens (17 agent tools). We worked around this by vendoring the affected utilities locally (v0.3.1), but the number of issues above suggests this is a recurring pain point for the external plugin community. Happy to help with any of these if there's interest.

Error Message

Support something like engines.openclaw in plugin package.json so the loader can warn on version mismatch instead of crashing with cryptic errors:

Root Cause

Several external plugins broke in the 2026.3.x cycle from the same root cause — exports removed from the root openclaw/plugin-sdk barrel without a deprecation period:

Code Example

[DEPRECATED] Importing 'jsonResult' from 'openclaw/plugin-sdk' is deprecated.
Use 'openclaw/plugin-sdk/param-readers' instead. Will be removed in 2026.4.x.

---

{ "engines": { "openclaw": ">=2026.2.0 <2026.4.0" } }
RAW_BUFFERClick to expand / collapse

The pattern

Several external plugins broke in the 2026.3.x cycle from the same root cause — exports removed from the root openclaw/plugin-sdk barrel without a deprecation period:

IssuePluginBroken symbol
#52842@supermemory/openclaw-supermemorystringEnum
#53003openclaw-larkresolveSenderCommandAuthorization
#52341openclaw-weixinMultiple
#53497openclaw-weixinresolvePreferredOpenClawTmpDir, buildChannelConfigSchema
#55080Third-party pluginsstringEnum
#53339memory-lancedb-prostringEnum
#53685External pluginsVarious (alias map)
(ours)openclaw-grafana-lensjsonResult, readStringParam

All trace back to f2bd76cd1a ("finalize plugin sdk legacy boundary cleanup"). Bundled extensions were migrated in the same commit, so the breakage was invisible internally — but external plugins broke on user machines.

What would help

1. Deprecate before removing

When an export moves from the root barrel to a subpath, keep it in root for one release cycle with a runtime warning:

[DEPRECATED] Importing 'jsonResult' from 'openclaw/plugin-sdk' is deprecated.
Use 'openclaw/plugin-sdk/param-readers' instead. Will be removed in 2026.4.x.

This gives external plugin authors time to migrate without their users hitting runtime crashes.

2. Plugin compatibility field

Support something like engines.openclaw in plugin package.json so the loader can warn on version mismatch instead of crashing with cryptic errors:

{ "engines": { "openclaw": ">=2026.2.0 <2026.4.0" } }

3. Changelog coverage for moved/removed exports

A dedicated section in the CHANGELOG (or release notes) listing every removed or moved plugin-sdk export with the new import path. #52842 noted that the stringEnum removal "was not documented in CHANGELOG.md or any migration guide" despite being intentional.

Context

We maintain grafana-lens (17 agent tools). We worked around this by vendoring the affected utilities locally (v0.3.1), but the number of issues above suggests this is a recurring pain point for the external plugin community. Happy to help with any of these if there's interest.

extent analysis

Fix Plan

To address the issue of broken external plugins due to removed exports from the openclaw/plugin-sdk barrel, we will implement the following steps:

  • Deprecate before removing: Add a runtime warning for deprecated imports.
  • Plugin compatibility field: Support an engines.openclaw field in plugin package.json to warn on version mismatch.
  • Changelog coverage: Document removed or moved exports in the CHANGELOG.

Code Changes

Deprecation Warning

// openclaw/plugin-sdk/index.js
const deprecatedExports = {
  jsonResult: 'openclaw/plugin-sdk/param-readers',
  readStringParam: 'openclaw/plugin-sdk/param-readers',
  // Add other deprecated exports here
};

Object.keys(deprecatedExports).forEach((exportName) => {
  exports[exportName] = function () {
    console.warn(`[DEPRECATED] Importing '${exportName}' from 'openclaw/plugin-sdk' is deprecated. Use '${deprecatedExports[exportName]}' instead. Will be removed in 2026.4.x.`);
    // Call the actual function or return the actual value
  };
});

Plugin Compatibility Field

// openclaw/loader.js
const packageJson = require(pluginPath + '/package.json');
const engines = packageJson.engines;

if (engines && engines.openclaw) {
  const versionRange = engines.openclaw;
  const currentVersion = require('../package.json').version;
  if (!satisfies(currentVersion, versionRange)) {
    console.warn(`Plugin compatibility warning: ${pluginPath} requires OpenClaw version ${versionRange}, but current version is ${currentVersion}.`);
  }
}

Changelog Coverage

Add a dedicated section to the CHANGELOG for removed or moved exports:

## Removed or Moved Exports

* `jsonResult`: Moved to `openclaw/plugin-sdk/param-readers`
* `readStringParam`: Moved to `openclaw/plugin-sdk/param-readers`
* `stringEnum`: Removed, use `openclaw/plugin-sdk/utils` instead

Verification

To verify that the fix worked, test the following scenarios:

  • Import a deprecated export and check for the runtime warning.
  • Create a plugin with an engines.openclaw field and test the version mismatch warning.
  • Check the CHANGELOG for documentation of removed or moved exports.

Extra Tips

  • Always deprecate before removing exports to give external plugin authors time to migrate.
  • Use a consistent naming convention for deprecated exports and their replacements.
  • Keep the CHANGELOG up-to-date with removed or moved exports to help plugin authors migrate.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#environment variable#network issue#logging issue#authentication issue#prompt issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix Plugin SDK needs a backwards compatibility strategy for external plugins [1 participants]