OpenClaw Troubleshooting: Common Issues and How to Fix Them

Something is not working. Your agent is down, slow, giving wrong answers, or just behaving strangely. Do not panic. Most issues with OpenClaw agents have straightforward causes and fixes.

This guide is organized by symptom. Find the issue you are experiencing, follow the diagnostic steps, and apply the fix. We cover the most common problems across deployment, runtime, integrations, skills, and performance.

Bookmark this page. You will come back to it.

Deployment Issues

Agent Stuck on "Creating" Status

Symptom: You clicked deploy, but the agent has been in "Creating" status for more than 5 minutes.

Possible causes:

1. Railway provisioning delay: Occasionally, Railway's infrastructure takes longer than usual to provision a new container.
2. Configuration error: An invalid setting is preventing the agent from starting.
3. Platform issue: A temporary issue with EZClaws or Railway.

Fix:

1. Wait 10 minutes. Some deployments take longer during peak usage periods.
2. If still stuck after 10 minutes, delete the agent and redeploy. This often resolves transient provisioning issues.
3. If the problem persists, check if there is a known issue with Railway's status page or EZClaws.
4. Double-check that all required fields were filled in correctly during deployment.

Agent Immediately Shows "Error" After Deploy

Symptom: The agent deploys but immediately transitions from "Creating" to "Error".

Possible causes:

1. Invalid API key: The most common cause. The key is wrong, expired, or for the wrong service.
2. Billing not enabled: Your model provider account does not have a payment method on file.
3. Model not available: You requested a model that your account does not have access to.

Fix:

1. Click on the agent to see the event log. The error message will usually tell you exactly what went wrong.
2. Verify your API key:
   • For OpenAI: Go to platform.openai.com/api-keys and confirm the key is active.
   • For Anthropic: Go to console.anthropic.com and confirm the key is active.
   • For Google: Go to aistudio.google.com and confirm the key is active.
3. Verify billing is set up on your model provider account.
4. Try creating a new API key and updating the agent settings.
5. Restart the agent.

See the API keys guide for detailed key management instructions.

Agent Deploys But Gateway URL Returns Nothing

Symptom: The agent shows "Running" but accessing the gateway URL in a browser returns an error or blank page.

Possible causes:

1. Agent is still initializing: The status shows Running but the OpenClaw process has not fully started yet.
2. Port configuration issue: The agent is running but not listening on the expected port.

Fix:

1. Wait 30 seconds after the status shows Running, then try again.
2. Try sending a POST request to the gateway URL's API endpoint instead of accessing it in a browser (GET requests to the root may not return anything by design).
3. If it still does not work after a minute, restart the agent from the dashboard.

Runtime Issues

Agent Running But Not Responding to Messages

Symptom: The agent shows "Running" on the dashboard, but when you send it a message (via Telegram, Discord, or direct API), you get no response.

Diagnostic steps:

1. Check usage credits: Go to /app/billing. If credits are exhausted, the agent stops processing messages. Purchase more credits or wait for the billing cycle reset.

2. Test directly: Send a request directly to the gateway URL using curl:

   curl -X POST https://your-agent.up.railway.app/api/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "Hello"}'
   

   If this works but your integration does not, the issue is with the integration, not the agent.

3. Check the integration: If using Telegram, verify the bot token is correct. If using Discord, verify the bot token and intents. If using a webhook, verify the webhook URL is pointing to the correct endpoint.

4. Check the event log: Look for any error events that coincide with when messages stopped working.

5. Restart the agent: Sometimes a restart resolves transient issues.

Agent Responds With Errors

Symptom: The agent responds, but with an error message instead of a helpful answer.

Common error messages and fixes:

"I'm sorry, I'm having trouble processing your request right now."

This usually means the model provider returned an error. Check:

• Model provider API status (status.openai.com, etc.)
• Your API key validity
• Your model provider billing status
• Rate limits (you may be sending too many requests too quickly)

"I don't have enough context to answer that."

The agent's conversation context may have been reset. This can happen after a restart or if the conversation timeout was reached. The user may need to restate their question with context.

"This skill encountered an error."

A skill failed to execute. Check the event log for skill-specific error messages. Common causes:

• The external API the skill depends on is down
• The skill's environment variables are not configured
• The skill received unexpected input

Agent Gives Wrong or Hallucinated Answers

Symptom: The agent provides incorrect information or makes up facts.

Causes and fixes:

1. Vague system prompt: If your system prompt does not clearly define what the agent knows, it may attempt to answer questions outside its knowledge. Add explicit knowledge boundaries. See the configuration guide.

2. No knowledge base skill: Without a knowledge base, the agent relies entirely on the model's training data, which may be outdated or incorrect for your specific domain. Install a knowledge base skill from the marketplace.

3. Model limitations: Some models hallucinate more than others. Claude models hallucinate less than GPT models in general. Consider switching models. See the model comparison.

4. Conflicting instructions: If your system prompt has contradictory instructions, the model may resolve the contradiction unpredictably. Review and simplify.

Agent Personality Drifts Over Long Conversations

Symptom: The agent starts conversations with the right tone and behavior but gradually drifts to a different personality over many exchanges.

Causes and fixes:

1. Context window too large: With a large context window, older messages can influence behavior. Reduce the context window to the last 10 messages.

2. System prompt being outweighed: In very long conversations, the accumulated conversation history can outweigh the system prompt. Add conversation timeout settings to periodically reset context.

3. Model-specific behavior: GPT-4 models are more prone to personality drift than Claude models. If this is a persistent issue, consider switching to Claude.

Integration Issues

Telegram Bot Not Receiving Messages

Symptom: Your Telegram bot shows as online but does not respond to messages.

Fix:

1. Verify the bot token is correct. Go to @BotFather on Telegram, select your bot, and check the token.
2. Make sure you have not set up the bot with another service. Telegram only allows one webhook or polling connection per bot. If another service is connected, disconnect it first.
3. Check that the webhook URL is correctly set. The EZClaws agent should set this automatically, but it can fail if the agent had issues during startup.
4. Send /start to the bot. Some bots require this before they respond to regular messages.
5. Restart the agent from the EZClaws dashboard.

Discord Bot Offline

Symptom: The Discord bot appears offline in the server member list.

Fix:

1. Verify the Discord bot token is correct in your agent settings.
2. Make sure you enabled the required intents in the Discord Developer Portal:
   • Message Content Intent (required for reading messages)
   • Server Members Intent (if your bot needs member info)
   • Presence Intent (if your bot tracks online status)
3. Check that the bot was properly invited to the server with correct permissions.
4. Restart the agent.

For a complete Discord setup guide, see the Discord bot guide.

Webhook Verification Failing

Symptom: When configuring webhooks (WhatsApp, custom integrations), the verification step fails.

Fix:

1. Confirm your agent is in "Running" status before attempting verification.
2. Verify the webhook URL is exactly correct. Common mistakes:
   • Missing https:// prefix
   • Trailing slash that should not be there (or missing one that should)
   • Wrong path after the domain
3. Ensure the verify token matches exactly between your agent configuration and the platform's webhook settings.
4. Check that the agent's HTTPS certificate is valid (EZClaws handles this automatically, but check if there is a platform issue).

For WhatsApp-specific webhook issues, see the WhatsApp guide.

Skill Issues

Skill Installation Fails

Symptom: You click "Install" on a skill in the marketplace but it does not install or shows an error.

Fix:

1. Check that your agent is in "Running" status. Some skill installations require the agent to be running.
2. Verify that all required environment variables for the skill are provided. Check the skill's documentation for required configuration.
3. Try refreshing the dashboard and attempting installation again.
4. Check if the skill has compatibility requirements (specific model provider, minimum agent version) that your setup does not meet.

Installed Skill Not Triggering

Symptom: A skill is installed but does not seem to activate when it should.

Fix:

1. Check the skill's trigger conditions. Does the user's message match the skill's keyword or pattern triggers? Test with an exact match first.
2. Verify skill priority. If multiple skills have overlapping triggers, a higher-priority skill may be handling the request instead.
3. Check the event log for skill execution events. The log will show if the skill was triggered but returned no results.
4. Review the skill's configuration. Some skills require additional setup (API keys, configuration values) beyond initial installation.

Skill Returns Errors

Symptom: The skill triggers but returns an error instead of useful data.

Fix:

1. Check the event log for the specific error message.
2. Common causes:
   • External API down: The API the skill depends on is unavailable. Check the API's status page.
   • Invalid credentials: The skill's API key or credentials are wrong or expired.
   • Rate limiting: The external API is rate-limiting your requests.
   • Data format change: The external API changed its response format, breaking the skill's parser.
3. If the skill is from the marketplace, check if there is an updated version that fixes the issue.
4. If it is a custom skill, review the error details and debug accordingly. See the skills development guide.

Performance Issues

Slow Response Times

Symptom: The agent takes more than 5 seconds to respond.

Diagnostic steps:

1. Check model provider latency: The AI model API call is usually the biggest contributor to latency. If OpenAI or Anthropic is experiencing high load, responses will be slower.

2. Check context window size: A large context window (20+ messages) means more tokens per request, which takes longer to process. Reduce to 10 messages if latency is critical. See the configuration guide.

3. Check skills: Skills that make external API calls add latency. If a skill calls a slow API, the total response time increases. Review installed skills and their execution times in the event log.

4. Check the model: Larger models are slower. If response speed is critical, consider switching to a faster model:

   • GPT-4 (slow) -> GPT-4o (fast) -> GPT-4o-mini (very fast)
   • Claude Opus (slow) -> Claude Sonnet (fast) -> Claude Haiku (very fast)

   See the model comparison for speed benchmarks.

5. Check response length: If the model is generating very long responses, it takes longer. Set a max token limit in the configuration.

High Credit Consumption

Symptom: Usage credits are being consumed faster than expected.

Diagnostic steps:

1. Check message volume: Is your agent receiving more messages than expected? A traffic spike from a new integration or viral content can increase consumption dramatically.

2. Check model costs: Higher-tier models consume more credits per request. If you recently upgraded from GPT-4o-mini to GPT-4, costs increase significantly.

3. Check context window: A large context window includes more tokens per request, increasing cost. Reducing from 20 to 10 messages can cut token consumption by 40%.

4. Check for loops: A misconfigured integration might be sending repeated messages, consuming credits rapidly. Check the event log for unusual patterns.

5. Check skills: Some skills generate additional model calls (e.g., a summarization skill that uses the AI to summarize conversation context). These add to credit consumption.

Optimization: See the cost optimization section in the model comparison guide and the performance tuning section in the configuration guide.

Visit /pricing to review credit allocations and purchase additional credits if needed.

API Key Issues

"Authentication Failed" Error

Fix: Your API key is invalid. Possible reasons:

• The key was copied incorrectly (check for extra spaces or missing characters)
• The key has been deleted or revoked
• You are using a key for the wrong provider (e.g., an OpenAI key in the Anthropic field)

Generate a new key from your provider and update it in agent settings. See the API keys guide.

"Rate Limit Exceeded" Error

Fix: You are making too many requests too quickly. This can happen with:

• New accounts that have low rate limits
• High-traffic agents without rate limiting configured
• Multiple agents sharing the same API key

Solutions:

• Wait a few minutes for the rate limit to reset
• Configure rate limiting on your agent
• Use separate API keys per agent
• Request a rate limit increase from your provider (based on spending history)

"Insufficient Quota" Error

Fix: Your spending limit has been reached or your prepaid credits are exhausted.

• OpenAI: Increase your spending limit in Settings > Billing > Usage limits
• Anthropic: Purchase additional prepaid credits
• Google: Check your Google Cloud billing status

Common Misconceptions

"My agent is broken because it gave a bad answer"

Usually, this is a configuration issue, not a technical problem. Bad answers almost always come from:

• A vague or incomplete system prompt
• Missing knowledge base data
• Using a model that is not capable enough for the task

Fix: Invest time in refining your system prompt. See the configuration guide.

"The agent was working yesterday but not today"

The most common causes of overnight failures:

• API key billing ran out of funds
• Model provider had an outage
• Usage credits were exhausted
• A connected external service (for a skill) went down

Check the event log for the specific error. It almost always has a clear message.

"I need to restart my agent frequently"

If you find yourself restarting your agent often, there is likely an underlying issue:

• Memory leaks from a misbehaving skill
• Intermittent API key issues
• Network instability

Investigate the root cause rather than relying on restarts as a workaround.

Preventive Measures

Before Making Changes

1. Note your current configuration
2. Make one change at a time
3. Test after each change
4. Keep the previous working configuration available for quick revert

Regular Maintenance

1. Check the dashboard daily (30 seconds)
2. Review event logs weekly (5 minutes)
3. Sample conversations weekly (10 minutes)
4. Review and update system prompt monthly
5. Rotate API keys every 90 days

For a complete monitoring routine, see the monitoring guide.

When to Ask for Help

If you have:

• Checked the event log for error messages
• Verified API key validity and billing
• Confirmed usage credits are available
• Tried restarting the agent
• Reviewed this troubleshooting guide

And the issue persists, it may be a platform-level issue. Check EZClaws status channels and community forums for known issues.

Quick Reference: Error to Fix

Error	Most Likely Cause	Fix
Agent shows "Error"	Invalid API key	Update API key, restart
No response	Credits exhausted	Purchase credits
Slow responses	Model too large	Switch to faster model
Wrong answers	Poor system prompt	Refine system prompt
Skill not working	Missing config	Check skill env vars
Bot offline (Telegram/Discord)	Wrong token	Update integration token
High costs	Large context window	Reduce context size
Webhook verification fails	Agent not running	Start agent, then verify

Conclusion

Most OpenClaw agent issues fall into a few predictable categories: API key problems, credit exhaustion, integration misconfiguration, and system prompt quality. With this guide and the event log in the EZClaws dashboard, you can diagnose and fix most issues in minutes.

The best troubleshooting strategy is prevention: monitor your agent regularly, keep your API keys healthy, and invest in a thorough system prompt. An agent that is well-configured from the start rarely needs troubleshooting at all.

For more guidance, explore our other guides: deployment tutorial, configuration deep dive, API keys, and monitoring.