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