OpenClaw Says Tool Not Found? Fix It in 10 Minutes

You ask your OpenClaw agent to check the weather, pull up a file, or send a message, and instead of doing the job it answers with something like “tool not found” or “I don’t have access to that tool.” Frustrating, right? The agent is supposed to handle this stuff for you.

Here is the good news: this is one of the most common OpenClaw errors, and it is almost never a sign that something is deeply broken. In nearly every case, the tool exists but your agent simply cannot see it. The fix is a configuration problem, not a reinstall problem.

In this guide I will walk you through exactly why OpenClaw reports a missing tool and how to fix it in about 10 minutes. You will learn how to check what your agent actually sees, verify your skills, confirm your MCP servers and plugins are running, and clean up the config that controls everything. By the end, your agent will be back to using every tool it is supposed to have.

Why OpenClaw Says “Tool Not Found”

OpenClaw does not give your agent access to every tool on your machine by default. Tools are exposed through a few different channels, and each one has to be present and working for the agent to use it:

• Skills. Folders with a SKILL.md file that teach your agent how to do specific tasks. If a skill folder is missing, renamed, or malformed, its tools vanish. If you are new to OpenClaw, start with our step-by-step setup guide to understand how skills work from the ground up.
• Plugins. Optional integrations that add tools like web search, messaging, or browser control. A disabled plugin means a disabled toolset.
• MCP servers. External servers that expose tools to the agent. If the server is down, unauthenticated, or misconfigured, the tools it provides show up as not found.
• Config allowlists. Your openclaw.json can explicitly allow or deny tools. A deny rule or a missing allow entry hides tools even when everything else is fine.

So when you see “tool not found,” your job is to figure out which of these four layers is blocking you. That is what the next steps do, and they take about 10 minutes total.

Step 1: Check What Tools Your Agent Actually Sees

Before you change anything, find out what your agent can see right now. OpenClaw gives you a couple of quick ways to do this.

Ask your agent to list its tools

In your OpenClaw chat, type something like:

List all the tools you currently have access to.

The agent will enumerate its available tools. Compare that list against the tools you expect it to have. If the missing tool is not in the list, you have confirmed the problem and you can move on to the next step. If the tool is in the list but still fails when called, the issue is likely the tool’s backend (an MCP server or plugin), not the tool registration itself.

Check the logs

OpenClaw writes detailed logs to its log directory. Look for the latest run and search for lines containing the tool name or the words “not found,” “denied,” or “unavailable.” The logs will often tell you which layer rejected the call, which saves you a lot of guessing.

This step alone fixes a surprising number of cases. Sometimes the agent is running from a different working directory or a different profile, and the skill you installed lives somewhere it is not looking. Listing tools exposes that mismatch immediately.

Step 2: Verify Your Skills Are Installed Correctly

If the missing tool belongs to a skill, the most common cause is a skill that is not installed where OpenClaw expects it. This is also closely related to agent memory and context issues, since tools and memory both depend on the agent loading the right state at startup.

Check the skills directory

OpenClaw looks for skills in your skills directory (typically a skills/ folder under your OpenClaw workspace, plus any plugin-provided skills). Each skill needs its own folder with a SKILL.md file at the top level. If the file is nested deeper, has the wrong name, or is missing entirely, OpenClaw skips the skill and every tool it defines.

Open the folder for the affected skill and confirm SKILL.md is there. If it is missing, restore it from your backup or reinstall the skill. This is the fix for most “tool not found” reports tied to skills.

Check file permissions

On macOS and Linux, OpenClaw needs read permission on the skill folder and its files. If you copied a skill in from a zip or a git clone, permissions can end up too restrictive. Fix them with:

chmod -R u+rwX /path/to/your/skills/folder

Then restart the gateway so OpenClaw re-scans the skills directory.

Re-read the skill

OpenClaw loads skills when it starts. If you added or edited a skill while the gateway was running, the agent may still be operating on the old state. A simple restart is often all it takes.

Step 3: Confirm Plugins and MCP Servers Are Running

Tools that come from plugins and MCP servers fail with “tool not found” when the underlying integration is down. These are the two most common culprits in practice, so check them carefully.

Plugins

Open your OpenClaw config and check which plugins are enabled. If a plugin that provides the missing tool is disabled, enable it and restart. Also check for plugin updates: a plugin and an OpenClaw version can drift out of sync, and the plugin silently stops registering its tools until it is updated.

MCP servers

MCP servers are configured in the MCP section of your config, usually with a command, a URL, and sometimes authentication details. When OpenClaw starts, it connects to each server and imports its tools. If the server process crashed, the URL is wrong, or the API key expired, the tools never get imported.

Test the server directly. For a local server, run the command from your terminal and see if it starts cleanly. For a remote server, hit its URL and confirm it responds. Then double-check that the authentication values in your config match what the server expects. Expired tokens are a very common reason MCP tools disappear, especially for services that rotate keys.

Step 4: Fix the Config Allowlist and Restart

If skills, plugins, and MCP servers all check out, the problem is in the config file itself. OpenClaw lets you control exactly which tools the agent can call, and a restrictive allowlist will hide tools even when they are perfectly installed. Much like fixing runaway token costs, most config issues come down to a quick edit and a restart.

Look for allow and deny rules

Open your openclaw.json and search for the tool permission settings. If you see a deny list, check whether the missing tool is on it. If you see an allow list, check whether the tool is missing from it. Either way, edit the list so the tool is permitted, save the file, and restart the gateway.

Also check per-agent or per-session overrides. OpenClaw supports different tool sets for different agents and sessions. A tool that works in one chat might be blocked in another because of a narrower override. If the error only happens in one session, that is your clue.

Restart the gateway

After any config change, restart the OpenClaw gateway. Config and skills are loaded at startup, so a restart is required for changes to take effect. This step is easy to skip and it is the reason many people think their fix “didn’t work.”

Once it is back up, ask your agent to list its tools again. The missing tool should be there, and you can move on to using it.

Common Mistakes

I see the same few mistakes over and over when people hit this error. Avoid them and you will save yourself most of the troubleshooting time.

• Skipping the restart. You edit a skill or config and test immediately, without restarting the gateway. OpenClaw does not hot-reload everything, so nothing changed. Restart first, then test.
• Editing the wrong config. If you run multiple OpenClaw instances or profiles, make sure you are editing the config the running agent actually uses. Check the config path shown at startup.
• Ignoring session-specific overrides. A tool blocked in one channel or session but fine in another points to an override, not a missing install. Check before you reinstall anything.
• Reinstalling instead of diagnosing. Removing and re-adding a skill or plugin rarely fixes a config or permission problem, and it can wipe your customizations. Diagnose first, reinstall only as a last resort.
• Forgetting MCP authentication. An MCP tool that worked last month and vanished today usually means an expired token or a changed URL. Check credentials before you blame OpenClaw.

FAQ

Final Thoughts

“Tool not found” in OpenClaw is almost always a visibility problem, not a broken installation. Your agent can only use the tools it loads at startup from skills, plugins, MCP servers, and config rules. When one of those layers is stale, misconfigured, or blocked, the tool disappears even though it is sitting right there on your machine.

The fix is a short checklist: confirm what your agent actually sees, verify your skills and their permissions, check that plugins and MCP servers are up with valid credentials, then clean up the config allowlist and restart. Run through it in that order and you will usually be back up in under 10 minutes.

Once your tools are working again, take a minute to think about which skills and integrations you actually rely on. Keeping that set small and well maintained means fewer things to break, and less time spent debugging when they do.

About The Author

Marcus Li

Marcus Li is a web designer and marketing specialist based in Vancouver, BC. After years of helping clients build their online presence, he discovered how AI tools could level the playing field for everyday entrepreneurs. He shares what actually works, no fluff, no hype.

See author's posts