openclaw "tool does not exists" error: What It Means and How to Fix It

TL;DR: OpenClaw’s “tool does not exist” error (“tool ‘read’ does not exists,” “tool ’exec’ does not exists,” “tool ‘write’ does not exists,” same error, different name) means the agent asked for a tool that isn’t available for that specific request. It doesn’t mean the tool is missing from OpenClaw generally. It means something filtered it out for this session: your tool profile, a tools.allow/tools.deny rule, or, on a sandboxed session, a separate sandbox tool policy. After any version upgrade, run openclaw doctor --fix first, since stale config is the single most common cause. If the error survives that, openclaw sandbox explain plus a raw-mode read of tools.profile/tools.allow/tools.deny will show you exactly which layer is blocking it.

Contents

• The Error
• What It Actually Means
• Why the Same Error Hits read, exec, and write
• The Causes, Most Likely First
• The Fix: Diagnose First, Then Change One Thing
• Why This Shows Up So Often on Telegram Channels
• Configuring Tool Availability On Purpose
• How to Prevent This
• Key Takeaways
• FAQ

The Error

You’ll see one of these, depending on which tool the agent reached for:

tool 'read' does not exists

tool 'exec' does not exists

tool 'write' does not exists

Same error, different tool name. The grammar is a little off (“does not exists” instead of “does not exist”), which is your first clue that you’re looking at raw error text rather than a message OpenClaw wrote for you. Whichever tool name shows up in yours, the underlying problem and the diagnostic path are identical, and we’ve now hit this with all three.

What It Actually Means

read, exec, and write are built-in OpenClaw tools. They’re not exotic. They’re the tools an agent uses to look at files, run commands, and edit things, which means when one goes missing, agents stop being able to do basic work.

The error doesn’t mean the tool was deleted from OpenClaw. It means the tool wasn’t included in the set OpenClaw actually sent to the model for that particular session. OpenClaw filters which tools a given request can see through a stack of config: a base tool profile, then tools.allow/tools.deny on top of that, and, if the session is sandboxed, a second and separate sandbox tool policy. The model then tries to call a tool it doesn’t know is off-limits, the request goes out without it, and whatever’s underneath OpenClaw (the model provider’s own tool-execution layer) reports back that the tool doesn’t exist. OpenClaw passes that report straight through to you, exactly like it received it.

That’s the honest version. We looked for the literal string in OpenClaw’s own error-handling code and didn’t find it: OpenClaw’s own recognized forms are things like “unknown tool: X” or “tool X not found,” and it actively rewrites one specific version of this problem (a sandbox tool policy block) into a clearer message. The “does not exists” phrasing you’re staring at isn’t one of those. It’s a raw, unrewritten report from underneath OpenClaw’s own message layer. That matters for diagnosis: since OpenClaw didn’t recognize and relabel this particular failure, you have to go find which config layer caused it yourself, which is what the rest of this post walks through.

Why the Same Error Hits read, exec, and write

This isn’t three separate bugs. It’s one filtering mechanism catching three common tools.

OpenClaw groups its built-in tools, and read, write, edit, and apply_patch all sit under group:fs. exec, process, and code_execution sit under group:runtime (bash is accepted as an alias for exec). Whether a given session gets those groups at all depends on tools.profile:

Set tools.profile to minimal or messaging, and neither group:fs nor group:runtime is in the base set. read, write, and exec are gone before tools.allow/tools.deny even runs. If a skill or a habit still assumes those tools are there, you get this error the moment the agent reaches for whichever one it needed first.

The same thing happens with tools.allow on its own. One rule worth knowing: if tools.allow is non-empty, everything not on that list is blocked. People set a short allow list to scope an agent down to a couple of tools, forget read/exec/write were implicitly available before, and don’t add them back explicitly. The agent runs fine for a while and then hits the first tool that isn’t on the list.

The Causes, Most Likely First

1. Tool profile or tools.allow/tools.deny excludes it. Covered above. Check tools.profile first, then tools.allow and tools.deny, both globally and per agent (agents.list[].tools.*). This is the most common cause we’ve traced down, and it’s almost always intentional config that just didn’t account for one of the three tools.

2. Sandbox tool policy blocks it specifically. This is a separate gate that only applies when the session is sandboxed: tools.sandbox.tools.allow/tools.sandbox.tools.deny (global or agents.list[].tools.sandbox.tools.*). A tool can be fully allowed at the top level and still get blocked here. Usually this case produces a clearer message (“Tool ‘X’ blocked by sandbox tool policy…”) rather than the raw “does not exists” text, so if you’re seeing the raw wording, this specific layer is a less likely culprit, but it’s still worth ruling out with openclaw sandbox explain.

3. Version-upgrade drift. A newer OpenClaw release renamed, restructured, or gated a config key your config still uses the old shape of. Our OpenClaw errors guide documents this pattern in general: openclaw doctor strips config keys your current version doesn’t recognize, and leftover legacy keys are a known source of silent tool and config failures after an upgrade.

4. A plugin-provided tool whose plugin didn’t load. This one applies when the missing tool comes from a plugin rather than a built-in, so it’s a likelier explanation for something like a browser or a custom tool than for read/exec/write. If the plugin that registers the tool fails to load at startup, the tool never enters the set at all, and any call to it reports the same “does not exists.” Plugins get rejected at load for concrete, checkable reasons: file ownership or permissions that don’t match what your version expects (some releases require the plugin’s files to be root-owned and will refuse a plugin owned by a normal user), or a failed peer-dependency link back to OpenClaw when the plugin’s openclaw peer resolves to the wrong path. Check openclaw logs from startup for a blocked or skipped plugin candidate, and confirm the plugin that provides your missing tool actually registered before you go digging through tools.allow/tools.deny. No allow/deny rule matters if the tool was never registered to begin with.

5. Wrong tool name. A typo, wrong casing (Read instead of read), or a skill/config referencing an old alias. A custom skill can also reference a tool that was never registered in that workspace at all, which produces the exact same error even though nothing “broke.”

6. Genuine model hallucination. Rare for well-known built-ins like read, exec, and write, more plausible for custom or plugin tool names the model half-remembers from training or from a different project’s tool set. OpenClaw treats this the same as any other unregistered tool call: after repeated consecutive misses on the same unavailable tool (10 by default, tools.loopDetection.unknownToolThreshold), it steps in and stops the model from looping on a dead end. If your agent keeps retrying the same missing tool instead of giving up after one or two tries, that guard is why it eventually stops rather than burning tokens forever.

The Fix: Diagnose First, Then Change One Thing

There’s no single command that fixes all six causes above, because they’re not the same failure. What’s constant is the diagnostic order:

1. Run openclaw sandbox explain. Scope it with --agent <id> or --session <key> if you know which agent hit the error. This prints the effective sandbox mode and the effective tool allow/deny for that exact session, and tells you whether a blocking rule came from the agent config, the global config, or the default. This is the fastest way to rule sandbox tool policy in or out.

2. Check tools.profile and tools.allow/tools.deny in raw config mode. Not form view. Our post on OpenClaw’s raw-mode config editor covers why: the form editor doesn’t render every key, and it will silently drop ones it doesn’t understand if you save from there. Confirm read, exec, and write are actually included in whatever profile and allow/deny combination your agent is running under.

3. Check openclaw logs for an agents/tool-policy entry. Every time a tool policy step removes a tool, or a sandbox rule blocks a call, OpenClaw logs the rule label, the config key responsible, and the affected tool name. This is the single fastest way to go from “a tool is missing” to “here’s the exact line in my config that did it.”

4. Run openclaw doctor --fix. This is where you land if the first three steps point at leftover config from an old version rather than a deliberate current restriction. See our complete openclaw doctor --fix guide for what it does and doesn’t touch. It fixes drift. It will not add a tool back to a profile you (or a template) intentionally restricted.

Change one layer at a time and re-test. Config with three overlapping gates (profile, allow/deny, sandbox policy) is easy to over-correct if you touch all three at once and lose track of which change actually fixed it.

Why This Shows Up So Often on Telegram Channels

If you’re hitting this specifically from a Telegram channel, there’s a structural reason, not a coincidence.

OpenClaw treats an agent’s interactive session as its one “main” session, with a fixed key (agent:<agentId>:main). Every messaging-channel session, Telegram groups and Telegram DMs included, gets its own session key and by definition is never main. Under OpenClaw’s non-main sandbox mode, which sandboxes every session except main, that means Telegram sessions get sandboxed by default. Sandboxed sessions are the only ones subject to sandbox tool policy (tools.sandbox.tools.allow/tools.sandbox.tools.deny), the layer a CLI session running as main never touches at all.

That’s why a tool can work fine when you test it interactively and then fail the moment the same agent runs it from a Telegram message: the two sessions sit on different tool-policy layers. If this is your situation, run openclaw sandbox explain --session <the Telegram session key> rather than testing from your main CLI session, since the main session will not reproduce the failure.

Configuring Tool Availability On Purpose

Sometimes the answer isn’t “fix the error,” it’s “I actually want this tool off, and I want to do it deliberately instead of by accident.” Three levers, in order of scope:

To disable a tool completely, everywhere: add it to tools.deny (global) or agents.list[].tools.deny (one agent). Deny always wins over allow, so this is the hard “off” switch.

To restrict an agent to a specific set of tools: use tools.allow. Remember the non-empty-list rule from earlier: list every tool you want the agent to keep, not just the new ones you’re adding, or you’ll recreate this exact error for yourself.

To set a sane starting point before allow/deny: use tools.profile. It’s a baseline, not a final answer. tools.allow/tools.deny still apply on top of whatever the profile includes.

For sandboxed sessions specifically: tools.sandbox.tools.allow/tools.sandbox.tools.deny is a fourth, independent gate. A tool allowed everywhere else can still be blocked only inside the sandbox, which is deliberate: it’s how OpenClaw lets you run a looser policy for trusted interactive sessions and a tighter one for everything else.

How to Prevent This

Run openclaw doctor --fix after every OpenClaw upgrade. Not “when something breaks.” After every upgrade, before you notice anything is wrong. It’s the fix for the single most common cause of this error, and it takes a minute.

Run openclaw sandbox explain any time you change tools.profile, tools.allow/tools.deny, or sandbox settings, before you assume the change did what you intended. It’s a read-only command. There’s no reason not to check.

Edit tool config in raw mode, not the form editor, once your config gets past the basics. We’ve covered why elsewhere: the form view drops keys it doesn’t understand, silently, on save.

Key Takeaways

• tool 'read'/'exec'/'write' does not exists is one bug, not three. All three tools are gated by the same tool profile, allow/deny, and sandbox tool policy mechanism.
• The tool isn’t gone from OpenClaw. It was filtered out for that specific session.
• The raw, slightly broken wording is a giveaway that you’re seeing unrewritten error text, not one of OpenClaw’s own curated messages.
• Run openclaw doctor --fix first. It fixes stale config from version upgrades, which is the most common cause.
• If doctor doesn’t fix it, run openclaw sandbox explain and read tools.profile/tools.allow/tools.deny in raw mode. openclaw logs will show you the exact rule that’s blocking the tool.
• Telegram (and other messaging-channel) sessions are never the agent’s main session, so they’re commonly sandboxed by default under non-main mode, which subjects them to a tool-policy layer your CLI testing session never hits.
• To disable a tool on purpose, use tools.deny. To restrict to a short list, use tools.allow, and remember to include every tool you still want.

For the broader OpenClaw error catalog, see our OpenClaw errors guide . For the doctor command in full, see our doctor –fix guide .

FAQ

What does “tool does not exists” mean in OpenClaw?

It means the agent tried to call a tool by name (read, exec, write, or any other built-in or plugin tool) that isn’t registered for that specific request. The tool can exist in OpenClaw generally and still be unavailable for one session, because tool availability is filtered per request by your tool profile, allow/deny rules, and, for sandboxed sessions, a separate sandbox tool policy. The raw wording, extra “s” and all, is error text passed through mostly unchanged rather than one of OpenClaw’s own rewritten messages, which is why it reads a little broken.

Why did it start after an upgrade?

Two separate things happen after upgrades. First, config drift: your tool profile or allow/deny list may reference a tool name or key that changed shape between versions, and openclaw doctor --fix strips config keys the current version no longer recognizes. Second, a custom skill or plugin may still call a tool under an old name that a newer release exposes differently. Run openclaw doctor --fix first. If the error is still there afterward, something in your current config is filtering the tool on purpose, not by accident.

How do I see which tools my instance has?

Run openclaw sandbox explain (add --agent <id> or --session <key> to scope it). It prints the effective sandbox mode and the effective tool allow/deny for that exact session, including whether a rule came from the agent config or the global default. For the non-sandboxed layer, check tools.profile and tools.allow/tools.deny in raw JSON config mode, since the form editor can hide these keys. openclaw logs also records an agents/tool-policy entry every time a tool policy step removes a tool or a sandbox rule blocks a call, with the exact rule and config key.

Is “tool ‘read’ does not exists” the same issue as “tool ’exec’ does not exists” or “tool ‘write’ does not exists”?

Yes. read and write belong to what OpenClaw calls group:fs, and exec belongs to group:runtime, but all three are gated by the same mechanism: tool profile, tools.allow/tools.deny, and sandbox tool policy. If your tools.profile is set to something restrictive, like minimal or messaging, neither of which includes group:fs or group:runtime, or your tools.allow list doesn’t include them, you’ll see this error for whichever of the three the agent reaches for first. Treat all of them as the same bug with a different tool name in the message.

Does openclaw doctor fix it?

openclaw doctor --fix resolves the version-drift cases: stale config keys and old tool names left over from an upgrade. It does not touch tool profiles, tools.allow/tools.deny, or sandbox tool policy, because those are settings you (or a config you copied) set on purpose. If doctor comes back clean and the error is still showing up, the tool is being deliberately filtered somewhere in your config, and openclaw sandbox explain plus a raw-mode read of tools.profile/tools.allow/tools.deny is what finds it.

Need help running OpenClaw in production?

Config with three overlapping tool-policy layers is easy to get wrong once, and easy to keep getting wrong if nobody’s diffing what changes on each upgrade. We run OpenClaw ourselves and have traced this exact error back to profile, allow/deny, and sandbox-policy causes in real deployments.

Two ways to get help:

• AI Tools Audit : a structured review of your stack, including OpenClaw configuration, tool policy, and sandbox setup. Independent, no vendor referral fees.
• AI agent development : for teams building on OpenClaw who want the setup done right the first time.

Or book a discovery call to scope a one-time audit.

Soli Deo Gloria