Skip to content

Plugin emits 'must declare contracts.tools' warnings on OpenClaw v2026.5.2 #40

Description

@groksrc

Summary

After upgrading the OpenClaw gateway from v2026.4.11 to v2026.5.2, the openclaw-basic-memory plugin (v0.2.1) emits a stream of warnings at startup:

plugin must declare contracts.tools before registering agent tools (plugin=openclaw-basic-memory, source=/Users/felix/openclaw-basic-memory/index.ts)

The warning fires once per api.registerTool(...) call — 28 occurrences during a single gateway boot. The plugin still loads and registers tools (registered composited memory_search + memory_get appears in the gateway log), but the new SDK contract added in v2026.5.x requires contracts.tools in the manifest to declare ownership before runtime registration.

Environment

  • OpenClaw gateway: v2026.5.2 (npm)
  • Node: v24.15.0 (lts/krypton, via nvm)
  • Plugin: @basicmemory/openclaw-basic-memory v0.2.1
  • Plugin source: local install at /Users/felix/openclaw-basic-memory/
  • Plugin manifest peerDependencies: openclaw: >=2026.3.7
  • Platform: macOS 15.7.2 (arm64)

Reproduction

  1. Install openclaw@2026.5.2 and @basicmemory/openclaw-basic-memory@0.2.1
  2. Configure the plugin in openclaw.json and start the gateway
  3. Watch ~/.openclaw/logs/gateway.err.log — the warning appears once per registered tool

Root cause

The current openclaw.plugin.json declares id, kind: "memory", skills, uiHints, and configSchema, but no contracts block. Per OpenClaw plugin manifest docs, as of v2026.5.x:

Runtime api.registerTool(...) registrations must match contracts.tools. Tool discovery uses this list to load only the plugin runtimes that can own the requested tools.

The OpenClaw loader source (dist/loader-CiaemmFD.js:1370) emits the warning whenever registerTool is called from a plugin whose manifest lacks contracts.tools.

Proposed fix

Add contracts.tools to openclaw.plugin.json listing all 14 tools the plugin registers via api.registerTool(...):

{
  "id": "openclaw-basic-memory",
  "kind": "memory",
  "contracts": {
    "tools": [
      "build_context",
      "delete_note",
      "edit_note",
      "list_memory_projects",
      "list_workspaces",
      "memory_get",
      "memory_search",
      "move_note",
      "read_note",
      "schema_diff",
      "schema_infer",
      "schema_validate",
      "search_notes",
      "write_note"
    ]
  },
  "skills": [...],
  "uiHints": {...},
  "configSchema": {...}
}

Tool names sourced by grepping api.registerTool({ name: "..." }) across tools/*.ts and tools/memory-provider.ts.

While there, consider:

  • Bumping peerDependencies.openclaw to >=2026.5.0 (or whichever version first introduced the contracts.tools enforcement) so older gateways that don't understand the field aren't surprised.
  • Optionally adding toolMetadata for the search/read tools so OpenClaw can avoid loading the plugin runtime when memory is not actively in use (perf optimization called out in the docs).

Impact

  • Severity: low — cosmetic warning, plugin still functions correctly
  • Frequency: every gateway startup, once per registered tool (28 lines per boot)
  • Side effects: none observed; memory_search and memory_get still register and basic-memory CLI integration is healthy

Reference

  • OpenClaw v2026.5.2 changelog (relevant entry): "Tools/plugins: add a platform-level tool descriptor planner for descriptor-first visibility, generic availability checks, and executor references, and cache plugin tool descriptors captured from api.registerTool(...) so repeated prompt-time planning can skip plugin runtime loading while execution still loads the live plugin tool. (#76079)"
  • Bundled memory-wiki plugin manifest (correct shape) at dist/extensions/memory-wiki/openclaw.plugin.json

Activity

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

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions