Troubleshooting

Common issues and how to fix them. Start with the simplest checks first.

Quick Fixes

Before You Start

Most issues can be resolved quickly. Follow the solutions below in order, starting with the simplest fix.

• Check your agent status first.
• Verify your AI credits balance.
• Try the simplest solution first.
• Wait 1 to 2 minutes after changes.

Helpful Resources

• OpenClaw documentation: complete setup guides, configuration options, and API reference.
• Integrations docs: platform-specific setup across chat channels and tools.

Common Issues & Solutions

Agent Not Responding

Your agent is not replying to messages or seems frozen.

1. Try Restarting Your Agent

When to use: Agent crashed, is in a deadlock, or stopped responding after working earlier.

In your My Agents page:

1. Click Stop, then Start.
2. Wait 30 to 60 seconds for the agent to restart fully.

2. Check Your AI Credits

When to use: Agent stopped suddenly or you see insufficient credits errors.

On the dashboard, check your AI Credits balance:

1. If balance is empty, click Top Up Credit.
2. Retry your message once credits are added.

Tip: Agent responses consume credits; monitor this balance regularly.

3. Reset Agent Configuration

When to use: Agent broke after configuration changes, fails to start, or behaves incorrectly.

1. Click Configure on the agent.
2. Scroll to Danger Zone.
3. Click Reset Configuration.

Note: This clears channel configuration and resets defaults. Workspace data remains safe.

4. Last Resort: Delete and Recreate

When to use: Nothing else works or the agent is fully broken.

1. Open the agent's Configure page.
2. Scroll to Danger Zone.
3. Click Delete Agent.
4. Create a new agent from My Agents.

Warning: This permanently deletes agent data, channel configuration, and conversations.

Messenger Connection Issues

Problems with Telegram, Discord, Signal, or WhatsApp.

Bot not appearing online

• Verify the bot token is correctly entered in Configure -> Channels.
• Confirm agent status is Running.
• Wait 1 to 2 minutes after saving channel configuration.
• Restart the agent after configuration changes.

Cannot send or receive messages

• Ensure bot permissions are correct (for Discord, check Message Content Intent if required).
• Check DM policy in channel configuration.
• For Telegram, complete pairing with the generated code.
• Verify your AI credits are available.

Lost connection to WhatsApp or Signal

• QR codes expire; generate a fresh one.
• Check Linked Devices in your messenger app.
• For Signal, ensure the linked device remains connected and powered on.
• Unlink and relink using a fresh QR code.

Slow or Delayed Responses

Agent responses may be slower depending on initialization and load.

Normal behavior:

• First response after restart: 10 to 30 seconds.
• Complex queries: 5 to 15 seconds.
• Simple questions: 2 to 5 seconds.

If consistently slower:

• Check if the agent is handling multiple conversations.
• Verify your plan and resource limits.
• Restart the agent to clear stuck processes.
• Upgrade plan/resources if performance remains constrained.

Still Need Help?

If none of these steps work:

• Check your status page for ongoing incidents.
• Contact support from top navigation.
• Include: agent name, error message, and steps already attempted.