Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix bug(plugins): plugin tools unavailable in sub-agent sessions due to lifecycle ordering [3 pull requests, 2 comments, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#56208•Fetched 2026-04-08 01:43:33
View on GitHub
Comments
2
Participants
1
Timeline
9
Reactions
0
Author
GodsBoyGodsBoy
Participants
GodsBoyGodsBoy
Timeline (top)
cross-referenced ×4commented ×2closed ×1locked ×1

Plugin-registered tools are unavailable in sub-agent sessions because createOpenClawTools() runs before loadOpenClawPlugins() completes for the sub-agent's execution context. Tools work correctly in the initial gateway session and after a gateway restart.

Error Message

05:30:27 warn tools — tools.profile (coding) allowlist contains unknown entries 05:30:27 warn tools — tools.allow allowlist contains unknown entries

Root Cause

In the sub-agent initialization path, createOpenClawTools() (which calls resolvePluginTools() → buildPluginToolGroups() → stripPluginOnlyAllowlist()) executes before loadOpenClawPlugins() has called the plugin's register() function. The fresh plugin registry is empty when tool resolution happens.

Fix Action

Workaround

Gateway restart makes all tools available. No plugin-side workaround exists.

PR fix notes

PR #34: docs: tool registration scope investigation (upstream bug)

Description (problem / solution / changelog)

Summary

  • Investigated why Honcho tools are unavailable in sub-agent sessions until gateway restart
  • Root cause is in OpenClaw core: sub-agent initialization resolves tools (createOpenClawTools()) before loading plugins (loadOpenClawPlugins())
  • No plugin-side workaround exists — the SDK has no static tool declaration mechanism

Investigation Findings

Timeline for sub-agent sessions:

  1. Sub-agent starts → createOpenClawTools() queries empty registry → tools NOT found (05:30:27)
  2. loadOpenClawPlugins() runs → register() called → tools registered (05:30:50, 23s too late)

Plugin code verified correct:

  • register() is synchronous, registers all 5 tools via api.registerTool()
  • No async gaps, no errors, no early returns

SDK limitations:

  • No tools field in openclaw.plugin.json manifest
  • No toolNames on definePluginEntry()
  • No scope/global flag on registerTool()

Related Issues

  • Upstream: openclaw/openclaw#56208
  • Tracking: plastic-labs/openclaw-honcho#33

Workaround

Gateway restart makes all tools available to subsequent sessions.

Changed files

  • TASK.md (added, +130/-0)

PR #56238: fix(plugins): reuse active registry for sub-agent tool resolution

Description (problem / solution / changelog)

Summary

When a sub-agent session starts, createOpenClawTools() resolves the tool list before loadOpenClawPlugins() has run for that session context. Plugin-registered tools (e.g. honcho memory tools) miss the resolution window entirely and appear as "unknown entries" in the allowlist.

The gateway start flow works correctly because plugins load during gateway_start before any session resolves tools — the active registry already has everything.

Root Cause

resolveRuntimePluginRegistry() compares cache keys to decide whether to reuse the active registry. Sub-agent callers pass different options (no onlyPluginIds, no coreGatewayHandlers) which produces a different cache key — so the active registry is bypassed and a fresh loadOpenClawPlugins() is triggered too late.

Fix

Add an isGatewayScopedLoad() check: when the caller does not restrict the plugin set with gateway-specific fields (onlyPluginIds, coreGatewayHandlers, includeSetupOnlyChannelPlugins, preferSetupRuntimeForChannelPlugins), the active registry set during gateway startup is a safe superset. Reuse it directly instead of falling through to a redundant load.

This is the minimal change — one new predicate function and a fallback path in resolveRuntimePluginRegistry().

Changes

  • src/plugins/loader.ts — add isGatewayScopedLoad() helper; update resolveRuntimePluginRegistry() to fall back to active registry for non-gateway-scoped callers
  • src/plugins/loader.test.ts — two new test cases covering the fallback and the non-fallback paths

Test Plan

  • pnpm tsgo — 0 type errors
  • pnpm lint — 0 warnings/errors
  • pnpm build — clean

Fixes #56208

Changed files

  • src/plugins/loader.test.ts (modified, +69/-0)
  • src/plugins/loader.ts (modified, +33/-1)

PR #56240: fix(plugins): reuse active registry for sub-agent tool resolution

Description (problem / solution / changelog)

Summary

When a sub-agent session starts, createOpenClawTools() resolves the tool list before loadOpenClawPlugins() has run for that session context. Plugin-registered tools (e.g. honcho memory tools) miss the resolution window entirely and appear as "unknown entries" in the allowlist.

The gateway start flow works correctly because plugins load during gateway_start before any session resolves tools — the active registry already has everything.

Root Cause

resolveRuntimePluginRegistry() compares cache keys to decide whether to reuse the active registry. Sub-agent callers pass different options (no onlyPluginIds, no coreGatewayHandlers) which produces a different cache key — so the active registry is bypassed and a fresh loadOpenClawPlugins() is triggered too late.

Fix

Add an isGatewayScopedLoad() check: when the caller does not restrict the plugin set with gateway-specific fields (onlyPluginIds, coreGatewayHandlers, includeSetupOnlyChannelPlugins, preferSetupRuntimeForChannelPlugins), the active registry set during gateway startup is a safe superset. Reuse it directly instead of falling through to a redundant load.

This is the minimal change — one new predicate function and a fallback path in resolveRuntimePluginRegistry().

Changes

  • src/plugins/loader.ts — add isGatewayScopedLoad() helper; update resolveRuntimePluginRegistry() to fall back to active registry for non-gateway-scoped callers
  • src/plugins/loader.test.ts — two new test cases covering the fallback and the non-fallback paths

Test Plan

  • pnpm tsgo — 0 type errors
  • pnpm lint — 0 warnings/errors
  • pnpm build — clean

Fixes #56208

Changed files

  • src/plugins/tools.optional.test.ts (modified, +37/-1)
  • src/plugins/tools.ts (modified, +20/-7)

Code Example

# Primary session — tools register correctly:
05:26:22 info gateway — Honcho memory plugin loaded
05:26:25 info gateway — Honcho memory ready

# Sub-agent session — tool resolver runs BEFORE plugin loads:
05:30:27 warn tools — tools.profile (coding) allowlist contains unknown entries
  (honcho_search_conclusions, honcho_search_messages, honcho_ask, honcho_context, honcho_session)
05:30:27 warn tools — tools.allow allowlist contains unknown entries
  (honcho_search_conclusions, honcho_search_messages, honcho_ask, honcho_context, honcho_session)

# Plugin loads 23 seconds AFTER tool resolution:
05:30:50 info plugins — Honcho memory plugin loaded
RAW_BUFFERClick to expand / collapse

Summary

Plugin-registered tools are unavailable in sub-agent sessions because createOpenClawTools() runs before loadOpenClawPlugins() completes for the sub-agent's execution context. Tools work correctly in the initial gateway session and after a gateway restart.

Reproduction

  1. Configure a plugin that registers tools via api.registerTool() in its register() function (e.g., @honcho-ai/openclaw-honcho)
  2. Add the plugin's tool names to an agent profile's tools.allow or tools.profile allowlist
  3. Start the gateway — tools work in the primary session
  4. Spawn a sub-agent session — tools are reported as unknown

Log Evidence

# Primary session — tools register correctly:
05:26:22 info gateway — Honcho memory plugin loaded
05:26:25 info gateway — Honcho memory ready

# Sub-agent session — tool resolver runs BEFORE plugin loads:
05:30:27 warn tools — tools.profile (coding) allowlist contains unknown entries
  (honcho_search_conclusions, honcho_search_messages, honcho_ask, honcho_context, honcho_session)
05:30:27 warn tools — tools.allow allowlist contains unknown entries
  (honcho_search_conclusions, honcho_search_messages, honcho_ask, honcho_context, honcho_session)

# Plugin loads 23 seconds AFTER tool resolution:
05:30:50 info plugins — Honcho memory plugin loaded

Root Cause

In the sub-agent initialization path, createOpenClawTools() (which calls resolvePluginTools() → buildPluginToolGroups() → stripPluginOnlyAllowlist()) executes before loadOpenClawPlugins() has called the plugin's register() function. The fresh plugin registry is empty when tool resolution happens.

Code Path (pi-embedded-BaSvmUpW.js)

  1. Tool resolution (line ~115963): applyToolPolicyPipeline() validates allowlist entries against pluginGroups built from currently instantiated tools
  2. Plugin loading (line ~147194): loadOpenClawPlugins() creates registry, calls register() on each plugin
  3. The gap: Step 1 happens before step 2 for sub-agent sessions

Plugin SDK Limitation

The plugin SDK has no static tool declaration mechanism:

  • openclaw.plugin.json manifest has no tools or toolNames field
  • definePluginEntry() only supports register() for tool registration
  • registerTool() options (name, names, optional) don't include a scope or global flag

Expected Behavior

Plugin tools registered during register() should be available to all sessions, including sub-agents spawned after initial gateway startup.

Workaround

Gateway restart makes all tools available. No plugin-side workaround exists.

Suggested Fix

Ensure loadOpenClawPlugins() completes before createOpenClawTools() for sub-agent execution contexts. Alternatively, add a static tool declaration mechanism to the plugin manifest so tool names can be pre-registered before register() runs.

Environment

  • OpenClaw: >=2026.3.22
  • Plugin: @honcho-ai/openclaw-honcho v1.2.1
  • Plugin kind: memory

extent analysis

Fix Plan

To fix the issue, we need to ensure that loadOpenClawPlugins() completes before createOpenClawTools() for sub-agent execution contexts. Here are the steps:

  • Modify the loadOpenClawPlugins() function to return a promise that resolves when all plugins have been loaded.
  • Modify the createOpenClawTools() function to wait for the promise returned by loadOpenClawPlugins() to resolve before proceeding.
  • Update the sub-agent initialization path to wait for the promise returned by createOpenClawTools() to resolve before starting the session.

Example code:

// Load plugins and return a promise that resolves when all plugins have been loaded
function loadOpenClawPlugins() {
  return new Promise((resolve, reject) => {
    // Load plugins...
    resolve();
  });
}

// Wait for plugins to load before creating tools
function createOpenClawTools() {
  return loadOpenClawPlugins().then(() => {
    // Create tools...
  });
}

// Update sub-agent initialization path to wait for tools to be created
function initSubAgent() {
  return createOpenClawTools().then(() => {
    // Start sub-agent session...
  });
}

Verification

To verify that the fix worked, follow these steps:

  • Restart the gateway and verify that plugin tools are available in the primary session.
  • Spawn a sub-agent session and verify that plugin tools are available.
  • Check the logs to ensure that loadOpenClawPlugins() completes before createOpenClawTools() for sub-agent execution contexts.

Extra Tips

  • Consider adding a static tool declaration mechanism to the plugin manifest to allow tool names to be pre-registered before register() runs.
  • Review the plugin SDK documentation to ensure that the fix is compatible with the latest version of the SDK.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#agent execution#retriever error#indexing error#inference speed

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING