Summary

When Gateway starts, plugins are loaded twice with different preferSetupRuntimeForChannelPlugins values, causing different cacheKeys. This results in tool registration being skipped on the second load due to pluginRegistrationState not being reset.

Environment

• OpenClaw version: 2026.3.28
• Plugin: OpenViking (context-engine type)
• Node: v22.22.0
• OS: Linux (Debian 13)

Repro

1. Install OpenViking plugin:

   openclaw plugins install openviking

2. Configure plugins.slots.contextEngine and plugins.entries.openviking.enabled: true

3. Add tool names to agent allowlist:

   "agents": {
     "list": [{
       "id": "main",
       "tools": {
         "alsoAllow": ["memory_recall", "memory_store", "memory_forget"]
       }
     }]
   }

4. Restart gateway:

   openclaw gateway restart

5. Check logs:

   allowlist contains unknown entries (memory_recall, memory_store, memory_forget)
   

Expected

Plugin tools should be registered and available to the agent session.

Actual

• Context-engine is registered successfully
• Plugin tools are NOT registered
• Warning: allowlist contains unknown entries (memory_recall, memory_store, memory_forget)

Root Cause Analysis

Gateway Startup Flow

Gateway calls loadOpenClawPlugins twice:

1. First call: loadGatewayStartupPlugins({ preferSetupRuntimeForChannelPlugins: true })

   • cacheKey mode: "prefer-setup"
   • Plugin registers context-engine and tools
   • pluginRegistrationState: "idle" → "registering" → "registered"

2. Second call: reloadDeferredGatewayPlugins({}) (no preferSetupRuntimeForChannelPlugins)

   • cacheKey mode: "full"
   • Different cacheKey → cache miss → plugin loaded again
   • pluginRegistrationState already "registered"
   • beginPluginRegistration() returns null → tool registration skipped

CacheKey Calculation

const startupChannelMode = params.preferSetupRuntimeForChannelPlugins === true ? "prefer-setup" : "full";

The cacheKey differs between the two calls, causing the plugin to be loaded twice.

Plugin State Management

let pluginRegistrationState: PluginRegistrationState = "idle";

function beginPluginRegistration(api: OpenClawPluginApi): number | null {
  if (pluginRegistrationState !== "idle") {
    api.logger.info("plugin registration already active, skipping");
    return null;  // <-- Tool registration skipped on second load
  }
  pluginRegistrationState = "registering";
  // ...
}

The module-level pluginRegistrationState is not reset when the plugin is loaded again with a different cacheKey.

Evidence

Log Timeline

11:02:23 - weixin plugin loaded (setup-runtime mode)
11:02:25 - OpenViking: registered context-engine (first load)
11:02:27 - weixin plugin loaded (full mode)
11:02:27 - OpenViking: registered context-engine (second load)
11:02:43 - openviking: plugin registration already active, skipping duplicate registration
11:02:43 - allowlist contains unknown entries (memory_recall, memory_store, memory_forget)

Code Reference

• loadGatewayStartupPlugins(): calls with preferSetupRuntimeForChannelPlugins: deferredConfiguredChannelPluginIds.length > 0
• reloadDeferredGatewayPlugins(): does NOT pass preferSetupRuntimeForChannelPlugins
• buildCacheKey(): includes startupChannelMode which differs between calls

Potential Fixes

1. Pass consistent preferSetupRuntimeForChannelPlugins to both loadGatewayStartupPlugins and reloadDeferredGatewayPlugins

2. Reset pluginRegistrationState when loading with a different cacheKey

3. Use cacheKey-aware state management instead of module-level variables

Related

• Issue Plugin context engines can resolve before plugin registration (Lossless Claw / contextEngine slot) #40232: Similar timing issue with context-engine registration

Workaround

• Use autoCapture and autoRecall features instead of manual tool invocation
• Call OpenViking API directly via HTTP