Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

openclaw.plugin.json declares "contracts": { "tools": true }, but registerTool still fails with "plugin must declare contracts.tools before registering agent tools". The plugin loads (status: loaded) but no tools appear.

Steps to reproduce

1. Create a native plugin with openclaw.plugin.json containing:
   {
   "id": "my-plugin",
   "entry": "./dist/index.js",
   "configSchema": { "type": "object", "properties": {} },
   "contracts": { "tools": true }
   }

2. In dist/index.js, export a register function that calls api.registerTool({ name: "test", description: "...", parameters: { type: "object", properties: {} }, handler: async () => {} })

3. Install plugin: openclaw plugins install

4. Enable plugin: openclaw plugins enable my-plugin

5. Restart gateway: openclaw gateway restart

6. Inspect: openclaw plugins inspect my-plugin --runtime --json

Expected behavior

api.registerTool should succeed. tools array should contain the registered tool. No error should appear in diagnostics.

Actual behavior

openclaw plugins inspect --runtime --json returns:

• status: "loaded"
• tools: []
• error: "plugin must declare contracts.tools before registering agent tools"

OpenClaw version

2026.5.7

Operating system

Windows 10

Install method

npm install -g openclaw

Model

NOT_ENOUGH_INFO

Provider / routing chain

NOT_ENOUGH_INFO

Additional provider/model setup details

NOT_ENOUGH_INFO

Logs, screenshots, and evidence

Full diagnostics output from openclaw plugins inspect anime-characters --runtime --json:

"status": "loaded"
"tools": []
"error": "plugin must declare contracts.tools before registering agent tools"

The openclaw.plugin.json file (verified via type command):
{
  "id": "anime-characters",
  "entry": "./dist/index.js",
  "configSchema": { "type": "object", "properties": {} },
  "contracts": { "tools": true }
}

Impact and severity

Blocks all plugin developers from registering agent tools via the native plugin format. Any plugin that needs to expose tools to agents cannot function. Affects: plugin developers. Severity: blocks workflow. Frequency: always.

Additional information

Also tested registerCommand and registerCli — both have similar documentation gaps. registerCommand succeeds (commands appear in inspect output) but commands are not routable from chat channels (Feishu). registerCli fails with "cli registration missing explicit commands metadata". The plugin SDK docs at https://docs.openclaw.ai/tools/plugin do not mention contracts.tools or its required location.