Troubleshooting Guide

Quick solutions for common OpenClaw issues. If you can't find a solution, contact support at support@openclaw.ai.

Quick Diagnostics

Check System Status

Before troubleshooting, verify OpenClaw services are operational:

1. Visit status.openclaw.ai
2. Check your bot status in Portal dashboard
3. Review recent error logs in Portal > Bot > Logs

Common Issue Categories

• Bot Issues - Bot not responding, connection errors, webhook failures
• Billing Issues - Payment failures, subscription problems, invoice questions
• API Issues - Authentication errors, rate limits, invalid requests
• Performance Issues - Slow responses, timeouts, high latency

Most Common Issues

Bot Not Responding

Symptoms: Bot online but doesn't reply to messages

Quick Fixes:

1. Check bot status: GET /api/bots/:id/status
2. Verify webhook connection in Portal dashboard
3. Review error logs for exceptions
4. Restart bot: POST /api/bots/:id/restart

Full bot troubleshooting guide →

---

Payment Failed

Symptoms: Subscription shows "past_due" status

Quick Fixes:

1. Check payment method in Polar.sh dashboard
2. Verify card hasn't expired
3. Ensure sufficient funds available
4. Update payment method and retry

Full billing troubleshooting guide →

---

Quota Exceeded

Symptoms: Bots stop processing, "quota exceeded" errors

Quick Fixes:

1. Check quota status: GET /api/usage/quota
2. Upgrade tier if consistently hitting limits
3. Wait for monthly reset
4. Review usage patterns: GET /api/usage

---

Unauthorized API Errors

Symptoms: 401 errors on API requests

Quick Fixes:

1. Verify logged in to OpenClaw Portal
2. Include credentials: 'include' in fetch calls
3. Check session hasn't expired
4. Clear cookies and re-login

---

Bot Stuck in Provisioning

Symptoms: Bot status stays "provisioning" for >5 minutes

Quick Fixes:

1. Wait up to 10 minutes (Cloud Run deployment)
2. Check GCP quota limits in account
3. Review bot creation logs in Portal
4. Delete and recreate bot if stuck >15 minutes

---

Error Code Reference

HTTP Status Codes

Code	Meaning	Common Causes
400	Bad Request	Invalid parameters, missing required fields
401	Unauthorized	Not logged in, session expired
403	Forbidden	Insufficient permissions, quota exceeded
404	Not Found	Bot doesn't exist, invalid ID
409	Conflict	Bot username already exists
429	Rate Limit	Too many requests, wait before retry
500	Server Error	Internal error, contact support

Application Error Codes

Code	Description	Solution
INVALID_TOKEN	Telegram bot token invalid	Verify token from BotFather
BOT_LIMIT_REACHED	Max bots for tier	Upgrade subscription or delete unused bots
QUOTA_EXCEEDED	Monthly quota exhausted	Upgrade tier or wait for reset
WEBHOOK_FAILED	Telegram webhook setup failed	Check bot token, verify permissions
PROVISIONING_FAILED	Cloud Run deployment error	Check GCP limits, retry creation
SUBSCRIPTION_REQUIRED	No active subscription	Subscribe to a plan

Debugging Steps

Step 1: Gather Information

Collect details before investigating:

// Get bot details
const bot = await fetch(`/api/bots/${botId}`, {
  credentials: 'include'
}).then(r => r.json());
 
// Get live status
const status = await fetch(`/api/bots/${botId}/status`, {
  credentials: 'include'
}).then(r => r.json());
 
// Get recent usage
const usage = await fetch(`/api/usage/${botId}?period=daily`, {
  credentials: 'include'
}).then(r => r.json());
 
console.log({ bot, status, usage });

Step 2: Check Logs

Review error logs in Portal dashboard:

1. Navigate to Portal > Bots > [Your Bot]
2. Click "Logs" tab
3. Filter by error severity
4. Look for patterns in timestamps

Step 3: Test Connectivity

Verify bot can reach Telegram API:

// Test webhook connectivity
const testResponse = await fetch('/api/telegram/test', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ botId })
});
 
const result = await testResponse.json();
console.log('Webhook test:', result);

Step 4: Restart Services

Restart bot to clear transient issues:

// Restart bot
await fetch(`/api/bots/${botId}/restart`, {
  method: 'POST',
  credentials: 'include'
});
 
// Wait for provisioning
await new Promise(resolve => setTimeout(resolve, 5000));
 
// Check status
const newStatus = await fetch(`/api/bots/${botId}/status`, {
  credentials: 'include'
}).then(r => r.json());
 
console.log('New status:', newStatus);

Performance Optimization

Slow Response Times

Symptoms: Bot responses taking >3 seconds

Solutions:

1. Review enabled skills (disable unused)
2. Check avgLatency in usage stats
3. Optimize message processing logic
4. Consider upgrading to Pro/Ultra tier

High Error Rates

Symptoms: Success rate below 95% in usage stats

Solutions:

1. Review error logs for patterns
2. Check Telegram API limits
3. Verify bot token still valid
4. Ensure webhook URL accessible

Memory/Resource Issues

Symptoms: Bot crashes, automatic restarts

Solutions:

1. Review Cloud Run logs in GCP console
2. Check for memory leaks in custom skills
3. Upgrade to higher tier for more resources
4. Contact support for resource limit increase

Getting Help

Self-Service Resources

• Bot Issues Guide - Detailed bot troubleshooting
• Billing Issues Guide - Payment and subscription help
• Portal Guide - Portal feature documentation
• Community Forum - Ask community for help

Contact Support

When contacting support, include:

1. Bot ID (if bot-related)
2. Error messages (exact text)
3. Timestamps (when issue occurred)
4. Steps to reproduce (what triggered issue)
5. Expected vs actual behavior

Support Channels:

• Email: support@openclaw.ai
• Discord: discord.gg/openclaw
• Priority support (Pro/Ultra): Live chat in Portal

Known Issues

Current Known Issues

Bot Restarts During High Load (Investigating)

• Affects: Basic tier users during peak hours
• Workaround: Upgrade to Pro tier
• ETA: Fix deployed by Feb 2026

Webhook Delays (Acknowledged)

• Affects: All tiers during Telegram API outages
• Workaround: None, Telegram-side issue
• Status: Monitoring Telegram status

Recently Resolved

• Bot provisioning timeout (Fixed Jan 15, 2025)
• Invoice PDF generation errors (Fixed Jan 10, 2025)
• Dashboard analytics lag (Fixed Jan 5, 2025)

Maintenance Windows

Scheduled maintenance announced 48 hours in advance:

• Time: Tuesdays, 2-4 AM UTC
• Frequency: Monthly (first Tuesday)
• Impact: Portal read-only, bots continue running
• Notifications: Email + Portal banner

Preventive Measures

Regular Checks

Daily:

• Monitor bot status indicators
• Check error notification count
• Review message processing success rate

Weekly:

• Analyze usage trends
• Review performance metrics
• Check quota consumption

Monthly:

• Audit active bots
• Review billing and invoices
• Update bot configurations
• Test disaster recovery

Best Practices

1. Test changes in development bot first
2. Monitor alerts for quota warnings
3. Keep payment method up to date
4. Review logs regularly for anomalies
5. Document custom configurations

Emergency Procedures

Bot Completely Down

1. Check status.openclaw.ai
2. Verify subscription active: GET /api/billing
3. Check bot exists: GET /api/bots/:id
4. Review GCP console for service status
5. Contact emergency support (Pro/Ultra only)

Data Loss Concern

1. OpenClaw doesn't store message history (Telegram does)
2. Bot configuration backed up automatically
3. Contact support for disaster recovery
4. Review backup retention (30 days for deleted bots)

Security Incident

1. Immediately revoke bot token in BotFather
2. Delete bot in OpenClaw Portal
3. Contact security@openclaw.ai
4. Monitor account activity logs
5. Reset account password

Next Steps

• Bot Troubleshooting Guide
• Billing Troubleshooting Guide
• Contact Support