Repository navigation
Closed as not planned
Closed as not planned
Copy link
Labels
P2Normal backlog priority with limited blast radius.Normal backlog priority with limited blast radius.bugSomething isn't workingSomething isn't workingclawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.ClawSweeper marked this issue as needing maintainer review before automation.clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.ClawSweeper marked this issue as needing a product or behavior decision.clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.ClawSweeper does not recommend queueing a new automated fix PR for this issue.clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.ClawSweeper found a high-confidence source-level issue reproduction.impact:ux-frictionUser-facing flow adds avoidable confusion or support burden without fully blocking progress.User-facing flow adds avoidable confusion or support burden without fully blocking progress.issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.Very strong issue quality with high-confidence source-level or clear reproduction.
Description
Bug type
Regression (worked before, now fails)
Beta release blocker
No
Summary
In OpenClaw 2026.4.27 and earlier, plugins could dynamically register tools via api.registerTool() without declaring them in contracts.tools. After upgrading to 2026.5.2+, tool registration is silently rejected if contracts.tools is not declared in the manifest.
Steps to reproduce
Steps to reproduce:
- Create a plugin that calls
api.registerTool()at startup withoutcontracts.toolsin the manifest - Start OpenClaw
- Plugin logs show successful registration (e.g. "registered 12 tools")
- Open any agent session — the tools are not visible
- Cron jobs referencing these tools fail with:
No callable tools remain after resolving explicit tool allowlist; no registered tools matched
Expected behavior
Tools registered via api.registerTool() should be available to agents, consistent with behavior in 2026.4.27.
Actual behavior
registerTool() silently returns without registering the tool. The plugin code receives no error or warning. The only indication of failure is in the gateway logs:
plugin must declare contracts.tools before registering agent tools (plugin=xxx)
OpenClaw version
2026.5.2
Operating system
macOS
Install method
No response
Model
opus 4-6
Provider / routing chain
openclaw
Additional provider/model setup details
No response
Logs, screenshots, and evidence
Impact and severity
No response
Additional information
Why this is a bug (not just a breaking change):
- Silent failure —
api.registerTool()returns without throwing, giving the plugin no way to detect the failure - Misleading logs — the plugin's own success log fires after the failed
registerTool()calls, making it appear registration succeeded - No migration path for dynamic plugins — plugins that fetch tool definitions from external APIs at runtime cannot know tool names at manifest-write time, making
contracts.toolsimpossible to maintain statically
Environment:
- Broken since: 2026.5.2
- Last working version: 2026.4.27
- Current version: 2026.5.3-1
Suggested fix:
Either:
- Throw or return an error from
api.registerTool()whencontracts.toolsis missing, so plugins can detect and handle the failure - Support glob patterns in
contracts.tools(e.g."xxx_*") to accommodate dynamic tool namespaces - Provide a migration guide / deprecation warning in 2026.5.2 release notes
Reacted by clawsweeper
Reacted by clawsweeper
Metadata
Metadata
Assignees
Labels
P2Normal backlog priority with limited blast radius.Normal backlog priority with limited blast radius.bugSomething isn't workingSomething isn't workingclawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.ClawSweeper marked this issue as needing maintainer review before automation.clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.ClawSweeper marked this issue as needing a product or behavior decision.clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.ClawSweeper does not recommend queueing a new automated fix PR for this issue.clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.ClawSweeper found a high-confidence source-level issue reproduction.impact:ux-frictionUser-facing flow adds avoidable confusion or support burden without fully blocking progress.User-facing flow adds avoidable confusion or support burden without fully blocking progress.issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.Very strong issue quality with high-confidence source-level or clear reproduction.
Type
Fields
Priority
None yet
Activity
clawsweeper commentedon May 5, 2026
Codex review: this still needs some work.
Summary
Caller-visible registration rejection remains unresolved on current main and v2026.10.3; the same author's paired wildcard request also remains open.
Reproducibility: Current source and inspected loader tests establish that missing ownership records a diagnostic, returns normally, and registers no tool; no runtime reproduction was executed.
Root-cause cluster
Relationship:
canonicalCanonical: #77800
Summary: This issue owns caller-visible rejection; diagnostic correlation overlaps, while wildcard ownership is a separate capability choice.
Members:
same_root_cause: Tool silently dropped when manifest omits contracts.tools; plugin logs success before the contract gate rejects it #89215 - The open report describes the same rejection guard and requests caller feedback plus diagnostic correlation.partial_overlap: [Feature]: Support glob/wildcard patterns in contracts.tools #77797 - The same author's open paired request concerns dynamic namespace ownership rather than rejection feedback.partial_overlap: [AI-assisted] fix: throw on registerTool without contracts.tools instead of silent failure #77818 - The direct throw-based proposal closed without merging and remains historical design evidence.adjacent_distinct: fix: migrate plugin tool contracts in doctor #82565 - The merged migration repairs existing legacy declarations, not missing declarations or caller-visible rejection.Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.
Maintainer decision needed
Next step
Choose the public registration-rejection contract before implementing caller feedback and matching regression coverage.
Review details
Best possible solution:
Preserve manifest-first ownership while exposing a detectable rejection outcome with actionable diagnostics.
Do we have a high-confidence way to reproduce the issue?
Current source and inspected loader tests establish that missing ownership records a diagnostic, returns normally, and registers no tool; no runtime reproduction was executed.
Is this the best way to solve the issue?
Restoring undeclared registration conflicts with documented ownership; an explicit result appears safer than throwing because it can preserve unrelated plugin capabilities.
AGENTS.md: found and applied where relevant.
Remaining risk / open question:
Codex review notes: model internal, reasoning medium; reviewed against c3b63ff4c0ec.
Label changes
Label changes:
No label changes.
Label justifications:
P2: The failure affects plugin development and tool availability, with a documented manifest workaround and limited blast radius.impact:ux-friction: Independent human confirmation describes hours of diagnosis caused by normal caller returns and misleading plugin success logs.Evidence reviewed
What I checked:
src/plugins/registry-registrars-tools-hooks.ts:233, c3b63ff4c0ec)src/plugins/plugin-api.types.ts:239, c3b63ff4c0ec)docs/plugins/manifest/capabilities.md:94, c3b63ff4c0ec)src/plugins/registry-registrars-tools-hooks.ts:233, 59cb44796b0f)src/plugins/registry.ts, 7641783d6b0e)src/commands/doctor-plugin-manifests.ts:54, 7593ba8623c1)How this review workflow works
@clawsweeper re-reviewcomments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.@clawsweeper re-reviewor@clawsweeper re-runon an open PR or issue to request a fresh review only.@clawsweeper reviewto request a fresh review only.@clawsweeper explainto ask for more context, or@clawsweeper stopto stop active automation.Reviewed October 15, 2026, 7:40 PM ET / 23:40 UTC.
christian-lallo commentedon May 12, 2026
Adding user-side operational data for the maintainer discussion here.
Reproduction confirmed in 2026.5.7 + post-merge main: a custom workspace plugin calls
api.registerToolin its compiled output to register two tools. Manifest had nocontracts.toolsdeclaration. Registrations silently rejected at the registry; tools never appeared in the agent's callable surface. Adding the correspondingcontracts: { tools: [...] }entry to the manifest immediately fixed it.Diagnostic cost without a startup signal: ~3 hours of source spelunking before identifying the cause. The user-visible failure was "agent can't find the tool I registered," which sent the diagnostic down the wrong layer entirely (tool routing, agent surface registration, callable-tool resolution) before reaching the plugin loader.
Same pattern affects a sibling predicate. We hit a parallel failure with `manifest.activation.onStartup` — workspace plugins authored before that predicate tightened were silently excluded from `pluginLookUpTable.startup.pluginIds` at boot. Four custom workspace plugins disappeared from runtime entirely. Same "configured but not loaded" silent-exclusion shape, just at a different lifecycle stage.
Decoupled ask worth considering separately from the `registerTool` SDK question:
Regardless of how the maintainer team resolves the throw-vs-silent-vs-wildcard discussion for `registerTool` itself, a startup warning when any configured-and-enabled plugin is silently excluded due to manifest validation would convert this entire class of multi-hour diagnostics into 30-second fixes. The warning could be as simple as:
```
[plugins] WARN: plugin "X" is enabled in config but was not loaded.
Reason: manifest missing required field "contracts.tools" (or "activation.onStartup", etc.).
Fix: add the field to openclaw.plugin.json.
```
That's a small, additive change that doesn't preempt the bigger SDK design questions. It'd help every plugin author hitting either of these predicate-tightening events.
Happy to file the startup-warning request as a separate issue if maintainers think it's better decoupled from this one.
openclaw-barnacle commentedon May 31, 2026
This issue has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.
fix: preserve contracts after definePluginEntry() (#6)
2 remaining items
steipete commentedon Oct 24, 2026
Thanks for filing this. We're closing older issues that no longer look actionable on current
main.Declaring tools in the manifest's contracts.tools is the required plugin contract since 2026.5.2, and undeclared registrations are recorded as plugin diagnostics. Add the tool names to contracts.tools to fix registration.
OpenClaw has changed a lot since this was filed. If this still affects you on the latest release, please open a fresh issue with your version and repro steps (feel free to link back here).