Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.claw-link.dev/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw lobster logo “Tool not found” is one of those errors that sounds precise while telling you almost nothing useful. It feels specific. In practice, it is usually a label slapped onto several different failure modes. If OpenClaw says “Tool not found”, do not assume there is one universal fix. That error usually means one of these:
  • the current chat is using a stale tool catalog
  • the gateway/runtime state changed after an update or restart
  • plugin-backed tools are no longer surfacing correctly
  • the expected tool path is missing in the currently active runtime
  • a version or config mismatch made previously available tools disappear
This page is the diagnostic version, not the fairy-tale version.
Search icon Fast rule: if this started after an update or restart, suspect stale session or runtime/tool registry drift before anything more exotic.

​
Search icon At a glance

  • Tool not found is usually a multi-cause symptom.
  • Start with openclaw status and openclaw gateway status --json.
  • Always retry in a fresh chat before assuming the tool is gone globally.
  • If the issue began after a restart or update, prioritize tool catalog and runtime-state checks.

​
What this error usually means

Users usually hit this in one of these ways:
  • a workflow that used to work now fails with Tool not found
  • a plugin-backed tool no longer appears callable
  • the assistant references tool execution, but the runtime rejects it
  • the error started after a gateway restart, update, or rollback
That means the useful question is not:
“Where is the missing tool?”
It is:
“Why does the current runtime think that tool does not exist?”

​
Fastest troubleshooting flow

Use this order.

​
1) Check overall status first

Run: 
openclaw status
Then: 
openclaw gateway status --json
You are looking for clues like:
  • plugin/runtime load issues
  • unhealthy gateway state
  • config validation failures
  • weirdness introduced by update/rollback drift
If status is already unhealthy, fix that first. Do not over-focus on the tool name.

​
2) Retry the exact same task in a fresh chat

This matters more than people want it to. A stale chat can keep an old tool catalog alive even when the runtime has changed. So if you see Tool not found:
  • start a new chat
  • retry the same exact task
If the new chat works, the “missing tool” was probably not globally missing at all. The old session was stale.

​
3) Ask whether this started after a restart, update, or rollback

This is one of the highest-signal branches. If the error began after:
  • openclaw gateway restart
  • an OpenClaw upgrade
  • a rollback to an older version
  • plugin/config changes
…then runtime or config drift is a prime suspect. That is especially true if tools worked before and disappeared suddenly.

​
4) Check whether the missing tool depends on plugin state

Some Tool not found cases are really plugin surfacing problems. Ask:
  • is the tool from a plugin-backed path?
  • did plugin config or allowlist change?
  • did the gateway reload after installation or config edits?
  • is the current chat older than the plugin state now running?
If yes, also read:
  • Plugin Installed but Tools Don’t Appear in OpenClaw

​
5) Inspect config/version mismatch if the error followed a rollback or upgrade

A newer version can write config that an older version does not fully understand. Or a version change can leave runtime expectations out of sync with what the current process actually exposes. If that sounds plausible, inspect: 
~/.openclaw/openclaw.json
And verify it still matches the version/runtime you are actually running.

​
Common root causes

​
Root cause 1: stale session / stale tool catalog

Symptoms:
  • old chat throws Tool not found
  • fresh chat behaves normally
  • issue appeared after updates, plugin changes, or runtime reloads
Fix:
  • start a fresh chat
  • retry the exact task there

​
Root cause 2: runtime or gateway registry drift after restart

Symptoms:
  • tools worked before restart
  • after restart, tool lookup fails
  • runtime appears alive, but tool calls break
Fix:
  • check openclaw status
  • check openclaw gateway status --json
  • restart cleanly again if needed
  • re-test in a fresh chat

​
Root cause 3: post-update version/config mismatch

Symptoms:
  • issue started after upgrading or rolling back
  • some tools vanished unexpectedly
  • status or startup hints at config mismatch
Fix:
  • inspect ~/.openclaw/openclaw.json
  • confirm config matches the running version
  • review the post-update troubleshooting flow

​
Root cause 4: plugin-backed tools stopped surfacing

Symptoms:
  • tool belongs to plugin-backed behavior
  • install looks fine, but the runtime does not expose it
  • fresh session behavior differs from older chat behavior
Fix:
  • verify plugin config or allowlist
  • restart the gateway
  • test in a fresh chat

​
Root cause 5: wrong runtime expectation

Symptoms:
  • user expects a tool path that is not active in the current setup
  • plugin, ACP, and normal assistant tool paths are getting mixed together
Fix:
  • confirm which runtime path the workflow actually depends on
  • debug that path specifically instead of the error label

​
Practical checklist

Use this order:

​
1. Run openclaw status

​
2. Run openclaw gateway status --json

​
3. Retry the same task in a fresh chat

​
4. Check whether the issue started after restart/update/rollback

​
5. If plugin-backed, verify plugin config and reload state

​
6. Inspect config drift if version mismatch is plausible

​
How to tell whether this is really a stale-session problem

It probably is if:
  • the error appears only in an older chat
  • the issue started after updating, restarting, or changing plugins
  • a fresh chat behaves differently
It is probably not only stale-session if:
  • status is broadly unhealthy
  • all contexts fail the same way
  • startup/config validation is already broken

​
Common mistakes

​
Treating Tool not found as one bug with one fix

It is not. That is the whole trick.

​
Restarting things without checking whether the current chat is stale

Very common waste of time.

​
Assuming the tool disappeared globally because one workflow failed

Maybe. But maybe the old session is lying to you.

​
Ignoring update or rollback timing

If the timing lines up, pay attention.

​
Final thought

Tool not found is usually not a mystery about the tool. It is a mismatch between:
  • the tool catalog the session thinks exists
  • the runtime state currently loaded
  • the plugin/config/version state actually running
Once you look at it that way, the error gets a lot less mystical and a lot more fixable.
  • OpenClaw Not Responding? Start Here
  • OpenClaw Not Responding After an Update? Start Here
  • Plugin Installed but Tools Don’t Appear in OpenClaw
  • Why OpenClaw Says It Will Act but Doesn’t Complete the Task