Why is my OpenClaw tool call failing?
The four most common reasons an OpenClaw tool call fails — expired connection, placeholder arguments, missing permissions, schema not loaded — and the quick fix for each.
The most common causes, in order: the app's login has expired and the connection needs a reconnect; the agent passed a placeholder or wrongly formatted argument; the connected account is missing a permission the tool needs; or the tool's schema hadn't loaded when the call was made. Each has a quick fix below.
1. The connection needs a re-login
OAuth tokens expire or get revoked — after a password change, a security review, or simply time. When that happens every call to that app fails with an authorization error until you reconnect. Open your dashboard, find the app marked as needing attention, and reconnect it; the agent picks the fresh connection up on its next call.
2. The agent sent a placeholder argument
Models sometimes fill an ID field with a placeholder — <channel_id>,
YOUR_EMAIL, {user_id} — instead of looking up the real value. The app then
returns a confusing error (often a permissions-looking 403) even though the
connection is fine. If a call fails oddly, check the arguments first: ask the
agent to list or search for the real item, then retry with the actual ID.
3. The account is missing a permission
A tool can exist in the catalog and still fail because the connected account can't perform that action — a scope the token doesn't include, a feature your plan doesn't have, or a workspace you're not a member of. Quick test: can you do the same action in the app's own UI with that account? If not, no agent setup will make it work. More background in OAuth for AI agents.
4. The tool's schema hasn't loaded yet
Right after connecting a new app, the first call can race the tool catalog. If the error says the tool isn't loaded yet, it's transient: retry, or start a fresh chat so the agent reloads its tool list.
Still stuck?
If you're using ClawLink, the logs page in your dashboard shows every tool call with its exact error — usually enough to spot which case you're in. The general mechanics are covered in tool calling for AI agents, and support is one message away from the dashboard.