What does 'Tool not found' mean in OpenClaw?

It means the agent attempted to use a tool that is not permitted for that specific session or is not available in its current environment due to configuration restrictions.

Why are tools not working in Telegram?

Telegram sessions often default to or inherit restrictive tool profiles that disable advanced tools. The most common fix is setting the global `tools.profile` to `coding`.

Can I set tool profiles per-agent or per-session?

Yes, while the global `tools.profile` is the primary setting, you can also define tool allowances within individual agent configurations (`agents.list[].tools.allow`) or session-specific configurations for more granular control.

Fix OpenClaw "Tool not found" or Timeout Errors in Telegram

TL;DR — Quick Fix

Tools fail with "Tool not found" or timeouts in Telegram because the session is running under a restricted tool profile; switch your global tools.profile to 'coding' and restart the gateway.

Run Diagnostics

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Error Signal

Tool not foundtimeout errors

What's Happening

You're seeing "Tool not found" or timeout errors when trying to use tools like exec, read, write, or browser within Telegram sessions. Your agent can only reply with text, and file/terminal operations are blocked.

The Fix

This is almost always due to a restricted global tool profile. Run these commands on your gateway host:

Check your current global tool profile:

openclaw config get tools.profile --json

If it's set to "minimal" or "messaging", switch it to "coding":
```
openclaw config set tools.profile coding
```
Restart the gateway:
```
openclaw gateway restart
```

After these steps, try your Telegram session again.

Why This Occurs

OpenClaw has several global tool profiles (minimal, messaging, coding, etc.) that define default tool access. The messaging and minimal profiles are intentionally restrictive and disable powerful tools like exec, read, and browser to prevent accidental misuse in chat contexts. When a Telegram session is started, it inherits this restrictive profile, leading to the "Tool not found" errors. The coding profile is a good baseline that includes most standard tools.

Prevention

Always ensure your global tools.profile is set to a suitable level before starting agent sessions, especially if you intend to use advanced tools. The coding profile is generally recommended for development and file interaction. Regularly check your configuration, particularly after OpenClaw updates or system restarts, to avoid inheriting unintended restrictions.

Last Updated: March 2026

Did this guide solve your problem?