openclaw - 💡(How to fix) Fix [Bug]: External plugin tools register in metadata but are not surfaced to agent sessions [1 comments, 1 participants]

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

Tools registered via api.registerTool() in external (non-bundled) plugins appear in openclaw plugins inspect output but are never exposed to agent sessions via openclaw agent. Bundled plugin tools (e.g. memory_search from memory-core) work correctly.

There are two compounding issues when installing external plugins from a local folder via openclaw plugins install ./path:

1. Plugin fails to load at all — the jiti alias resolver walks up from ~/.openclaw/extensions/<plugin>/ to find the OpenClaw package root, but never reaches /usr/lib/node_modules/openclaw. This causes Cannot find module 'openclaw/plugin-sdk/core'. Workaround: symlink the global openclaw package into the plugin's node_modules/.
2. Tools don't surface to agents — even after the symlink workaround makes the plugin load successfully, and tools register into the plugin registry (confirmed via plugins inspect), they are not wired into the agent's callable tool surface. Only bundled plugin tools (Origin: bundled) appear in agent sessions.

Steps to reproduce

1. Create a minimal external plugin:

  // test-plugin/index.ts
  const plugin = {
    id: "test-tool-plugin",
    name: "Test Tool Plugin",
    description: "Minimal plugin to test tool registration",
    register(api: any) {
      api.registerTool(
        (_ctx: any) => ({
          name: "test_hello",
          description: "A simple test tool that returns a greeting",
          parameters: { type: "object", properties: {}, additionalProperties: false },
          async execute() {
            return { content: [{ type: "text", text: "Hello from test-tool-plugin!" }] };
          },
        }),
        { name: "test_hello" },
      );
      api.logger.info("[test-tool-plugin] Tool registered");
    },
  };
  export default plugin;

  // test-plugin/package.json
  { "name": "test-tool-plugin", "version": "1.0.0", "type": "module",
    "openclaw": { "extensions": ["./index.ts"] } }

  // test-plugin/openclaw.plugin.json
  { "id": "test-tool-plugin", "configSchema": { "type": "object", "additionalProperties": false, "properties": {} } }

2. Install from local folder:

openclaw plugins install ./test-plugin

This produces:

test-tool-plugin failed to load from ~/.openclaw/extensions/test-tool-plugin/index.ts:
Error: Cannot find module 'openclaw/plugin-sdk/core'

3. Apply symlink workaround to fix loading:

mkdir -p ~/.openclaw/extensions/test-tool-plugin/node_modules
ln -sf /usr/lib/node_modules/openclaw ~/.openclaw/extensions/test-tool-plugin/node_modules/openclaw
openclaw config set plugins.allow '["test-tool-plugin"]'
openclaw gateway restart

4. Verify plugin loads and tool is registered:

$ openclaw plugins inspect test-tool-plugin
# Output includes:
# Status: loaded
# Tools:
# test_hello

5. Check agent tool availability:

$ openclaw agent --agent main --message "list all your tools"
# Output lists read, write, edit, exec, process, web_search, web_fetch,
# cron, sessions_*, memory_search, memory_get
# BUT NOT test_hello

Logs confirm registration runs: [plugins] [test-tool-plugin] Tool registered

Expected behavior

test_hello should appear in the agent's callable tool list, just like memory_search does from the bundled memory-core plugin.

Actual behavior

Actual behavior

• Without symlink: plugin fails to load entirely (Cannot find module 'openclaw/plugin-sdk/...')
• With symlink: plugin loads, tool registers in metadata (visible via plugins inspect), but the tool is not wired into the agent's tool resolution surface. The agent cannot see or call it.

OpenClaw version

2026.3.28

Operating system

Linux (Ubuntu, x64)

Install method

curl -fsSL https://openclaw.ai/install.sh | bash

Model

GPT5.4

Provider / routing chain

codex token

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Impact and severity

No response

Additional information

Key observations

• Bundled plugin tools (e.g. memory_search from memory-core, Origin: bundled) work correctly
• External plugin tools (Origin: global, installed from local folder) register but don't surface
• Both static tool objects and factory functions (_ctx) => tool exhibit the same behavior
• The plugin's register() function runs successfully (confirmed via logger output)
• Updating from 2026.3.23-2 to 2026.3.24 did not fix the issue
• Issue 1 (loading failure) is likely the same root cause as #53685 — buildPluginLoaderAliasMap doesn't pass argv1 through to resolveLoaderPluginSdkPackageRoot
• Issue 2 (tools not surfacing) may be a separate bug in the agent tool resolver that only picks up tools from bundled plugins

Environment

• OpenClaw 2026.3.24 (also 2026.3.23-2)
• Node v22.22.0
• Linux (Ubuntu, x64)
• Plugin installed via openclaw plugins install ./local-path
• Global install at /usr/lib/node_modules/openclaw