Skip to content

[Bug]: Breaking change: api.registerTool() silently fails without contracts.tools since 2026.5.2 #77800

Closed as not planned

Description

@lyf571321556

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:

  1. Create a plugin that calls api.registerTool() at startup without contracts.tools in the manifest
  2. Start OpenClaw
  3. Plugin logs show successful registration (e.g. "registered 12 tools")
  4. Open any agent session — the tools are not visible
  5. 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):

  1. Silent failure — api.registerTool() returns without throwing, giving the plugin no way to detect the failure
  2. Misleading logs — the plugin's own success log fires after the failed registerTool() calls, making it appear registration succeeded
  3. 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.tools impossible 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() when contracts.tools is 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

Activity

  1. clawsweeper commented on May 5, 2026

    @clawsweeper
    Contributor

    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: canonical
    Canonical: #77800
    Summary: This issue owns caller-visible rejection; diagnostic correlation overlaps, while wildcard ownership is a separate capability choice.

    Members:

    Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

    Maintainer decision needed

    • Question: Should registerTool report rejection through an explicit result or throw and fail the plugin registration pass?
    • Recommendation: Return an explicit result: Expose accepted or rejected registration without discarding unrelated plugin capabilities, and document remediation.
    • Why: Current types and tests implement diagnostic-only rejection, and no recorded maintainer decision selects replacement semantics.

    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:

    • Throwing on rejection fails the plugin registration pass and rolls back its other contributions; an explicit return result requires a documented SDK contract.

    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:

    How this review workflow works
    • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
    • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
    • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
    • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
    • Maintainers can also comment @clawsweeper review to request a fresh review only.
    • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge; those execution lanes are retired.
    • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

    Reviewed October 15, 2026, 7:40 PM ET / 23:40 UTC.

  2. christian-lallo commented on May 12, 2026

    @christian-lallo
    Contributor

    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.registerTool in its compiled output to register two tools. Manifest had no contracts.tools declaration. Registrations silently rejected at the registry; tools never appeared in the agent's callable surface. Adding the corresponding contracts: { 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.

  3. openclaw-barnacle commented on May 31, 2026

    @openclaw-barnacle

    This issue has been automatically marked as stale due to inactivity.
    Please add updates or it will be closed.

  4. added
    P2Normal backlog priority with limited blast radius.
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.
    clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.
    clawsweeper:linked-pr-openClawSweeper found an open linked pull request for this issue.
    clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.
    clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.
    on Jun 2, 2026
  5. 2 remaining items

  6. added
    clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    and removed
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.
    on Jun 26, 2026
  7. added
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    and removed
    clawsweeper:linked-pr-openClawSweeper found an open linked pull request for this issue.
    on Aug 1, 2026
  8. added
    impact:ux-frictionUser-facing flow adds avoidable confusion or support burden without fully blocking progress.
    and removed
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    on Sep 22, 2026
  9. steipete commented on Oct 24, 2026

    @steipete
    Contributor

    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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Normal backlog priority with limited blast radius.bugSomething isn't workingclawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.clawsweeper:needs-product-decisionClawSweeper 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:source-reproClawSweeper found a high-confidence source-level issue reproduction.impact:ux-frictionUser-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.

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions