Bot Troubleshooting Guide

Solutions for bot-related issues including connectivity problems, message delivery failures, and performance degradation.

Bot Not Responding

Symptoms

• Bot shows online in Telegram but doesn't reply
• Messages sent but no response received
• Bot worked before, stopped suddenly

Diagnostic Steps

1. Check Bot Status

const response = await fetch(`/api/bots/${botId}/status`, {
  credentials: 'include'
});
 
const { status, liveStatus, health } = await response.json();
 
console.log('Bot status:', status);
console.log('Webhook connected:', health.webhookConnected);
console.log('Last message:', health.lastMessageReceived);

2. Verify Dashboard Status

Navigate to Portal > Bots > [Your Bot]:

• Status indicator should be green (Active)
• Webhook status should show connected
• No error badges visible

3. Check Recent Logs

Portal > Bots > [Your Bot] > Logs:

• Look for webhook delivery failures
• Check for skill execution errors
• Identify timeout messages

Common Causes & Solutions

Cause: Bot Status Not "Running"

// Check current status
const { bot } = await fetch(`/api/bots/${botId}`, {
  credentials: 'include'
}).then(r => r.json());
 
if (bot.status === 'stopped') {
  // Start the bot
  await fetch(`/api/bots/${botId}/start`, {
    method: 'POST',
    credentials: 'include'
  });
} else if (bot.status === 'provisioning') {
  // Wait for provisioning to complete
  console.log('Bot still provisioning, wait 2-5 minutes');
} else if (bot.status === 'error') {
  // Restart to recover
  await fetch(`/api/bots/${botId}/restart`, {
    method: 'POST',
    credentials: 'include'
  });
}

Cause: Webhook Connection Lost

Solution:

1. Restart bot to re-establish webhook
2. Check Cloud Run service logs in GCP console
3. Verify Telegram API not blocking requests
4. Contact support if persists >30 minutes

Cause: Quota Exceeded

// Check quota status
const quota = await fetch('/api/usage/quota', {
  credentials: 'include'
}).then(r => r.json());
 
if (quota.messages.percentUsed >= 100) {
  console.error('Monthly message quota exceeded');
  // Solution: Upgrade tier or wait for reset
}

Cause: Configuration Error

Solution:

1. Review bot configuration in Portal
2. Check enabled skills are valid
3. Verify no conflicting settings
4. Reset to default config and test

---

Connection Errors

Symptoms

• "Webhook delivery failed" in logs
• Bot status shows "degraded" or "offline"
• Intermittent message processing

Diagnostic Steps

1. Test Webhook Connectivity

const testResult = await fetch('/api/telegram/test', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ botId })
}).then(r => r.json());
 
console.log('Webhook test:', testResult);

2. Check Cloud Run Service Health

Via GCP Console:

1. Navigate to Cloud Run services
2. Find service openclaw-bot-{botId}
3. Check service status and revision health
4. Review error logs for HTTP failures

3. Verify Network Connectivity

Common issues:

• GCP network outage (check status.cloud.google.com)
• Telegram API throttling
• SSL certificate expiration
• DNS resolution failures

Common Causes & Solutions

Cause: Cloud Run Service Not Ready

const { liveStatus } = await fetch(`/api/bots/${botId}`, {
  credentials: 'include'
}).then(r => r.json());
 
if (!liveStatus.ready) {
  console.log('Service not ready, latest revision:', liveStatus.latestRevision);
  // Solution: Wait 2-5 minutes or restart bot
}

Cause: Telegram Webhook Limits

Telegram allows 1 webhook per bot. If webhook set elsewhere:

Solution:

1. Verify no other services using same bot token
2. Delete bot token from other platforms
3. Restart OpenClaw bot to reclaim webhook

Cause: Rate Limiting from Telegram

Symptoms: 429 errors in logs

Solution:

1. Reduce message processing frequency
2. Implement exponential backoff
3. Contact Telegram support if persistent
4. Upgrade bot limits via BotFather

Cause: SSL Certificate Issues

Solution:

1. Verify domain SSL valid (webhook URLs must use HTTPS)
2. Check Cloud Run managed certificates
3. Contact support if certificate expired

---

Bot Stuck in Provisioning

Symptoms

• Bot status stays "provisioning" >10 minutes
• No error messages in logs
• Can't interact with bot

Diagnostic Steps

1. Check Provisioning Age

const { bot } = await fetch(`/api/bots/${botId}`, {
  credentials: 'include'
}).then(r => r.json());
 
const createdAt = new Date(bot.createdAt);
const ageMinutes = (Date.now() - createdAt) / 1000 / 60;
 
console.log(`Bot provisioning for ${ageMinutes.toFixed(1)} minutes`);

2. Review GCP Deployment Logs

GCP Console > Cloud Run > Service > Logs:

• Look for "service deployed" messages
• Check for quota exceeded errors
• Verify container image pulled successfully

Common Causes & Solutions

Cause: GCP Quota Limits

Error in logs: "Quota exceeded for resource"

Solution:

1. Check GCP quota usage in console
2. Request quota increase via GCP support
3. Delete unused Cloud Run services
4. Contact OpenClaw support for assistance

Cause: Docker Image Pull Failure

Error in logs: "Failed to pull container image"

Solution:

1. Verify GCP Artifact Registry accessible
2. Check service account permissions
3. Contact OpenClaw support (infrastructure issue)

Cause: Telegram Token Invalid

Error in logs: "Unauthorized: invalid token"

Solution:

1. Verify bot token in BotFather
2. Check token wasn't revoked
3. Delete and recreate bot with valid token

Timeout - Normal Wait Times

• Expected: 2-5 minutes for first deployment
• Maximum: 10 minutes under heavy load
• Action: If >15 minutes, delete and recreate

---

Quota Exceeded Errors

Symptoms

• "Quota exceeded" error messages
• Bot processing throttled or stopped
• Dashboard shows 100% quota used

Diagnostic Steps

Check Quota Status

const quota = await fetch('/api/usage/quota', {
  credentials: 'include'
}).then(r => r.json());
 
console.log('Messages:', `${quota.messages.used}/${quota.messages.limit}`);
console.log('Tokens:', `${quota.tokens.used}/${quota.tokens.limit}`);
console.log('Reset date:', quota.resetDate);
 
quota.warnings.forEach(warning => {
  console.warn(warning.message);
});

Solutions

Immediate Actions

1. Wait for monthly reset - Quota resets on 1st of each month
2. Upgrade subscription tier - Higher limits available
3. Optimize usage - Disable expensive skills

Upgrade Tier

// Create upgrade checkout
const response = await fetch('/api/billing/checkout', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tier: 'pro' }) // or 'ultra'
});
 
const { checkoutUrl } = await response.json();
window.location.href = checkoutUrl;

Optimize Usage

// Review per-bot usage
const usage = await fetch('/api/usage?period=monthly', {
  credentials: 'include'
}).then(r => r.json());
 
// Identify high-usage bots
const highUsageBots = usage.byBot
  .filter(bot => bot.tokens > 100000)
  .sort((a, b) => b.tokens - a.tokens);
 
console.log('High usage bots:', highUsageBots);
// Consider disabling or optimizing these bots

Prevention

• Monitor quota dashboard daily
• Set up alerts at 80% threshold
• Review usage trends weekly
• Plan tier upgrades in advance

---

Performance Issues

Symptoms

• Slow bot responses (>3 seconds)
• Timeout errors in logs
• High latency in usage stats

Diagnostic Steps

Check Performance Metrics

const usage = await fetch(`/api/usage/${botId}?period=weekly`, {
  credentials: 'include'
}).then(r => r.json());
 
console.log('Average latency:', usage.summary.avgLatency, 'ms');
console.log('Success rate:', usage.summary.successRate, '%');
 
// Identify slow skills
usage.bySkill.forEach(skill => {
  if (skill.avgLatency > 2000) {
    console.warn(`Slow skill: ${skill.skill} (${skill.avgLatency}ms)`);
  }
});

Common Causes & Solutions

Cause: Too Many Skills Enabled

Solution:

// Disable unused skills
await fetch(`/api/bots/${botId}`, {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    skills: ['conversational-ai'] // Only essential skills
  })
});
 
// Restart to apply
await fetch(`/api/bots/${botId}/restart`, {
  method: 'POST',
  credentials: 'include'
});

Cause: AI Model Overload

Solution:

1. Reduce max tokens in bot config
2. Use faster model variants
3. Implement response caching
4. Upgrade to Pro/Ultra for better resources

Cause: Network Latency

Solution:

1. Check Cloud Run region (should be closest to users)
2. Verify Telegram API response times normal
3. Contact support to optimize routing

Cause: High Concurrency

Solution:

1. Upgrade tier for more compute resources
2. Implement message queueing
3. Add rate limiting on client side
4. Contact support for scaling assistance

---

Bot Randomly Stops

Symptoms

• Bot works, then stops without warning
• Status changes to "stopped" or "error"
• No user action triggered stop

Diagnostic Steps

Review Error Logs

Portal > Bots > [Your Bot] > Logs:

• Filter by "error" severity
• Look for crash signatures
• Check for out-of-memory errors
• Identify uncaught exceptions

Check Subscription Status

const billing = await fetch('/api/billing', {
  credentials: 'include'
}).then(r => r.json());
 
if (!billing.hasSubscription) {
  console.error('No active subscription');
} else if (billing.subscription.status === 'past_due') {
  console.error('Payment failed, subscription at risk');
}

Common Causes & Solutions

Cause: Payment Failure

Solution:

1. Update payment method in Polar.sh
2. Resolve past due status
3. Bots automatically restart on payment success

Cause: Memory Limits

Solution:

1. Review Cloud Run memory usage in GCP console
2. Optimize bot configuration (reduce caching)
3. Upgrade tier for more memory
4. Contact support for custom resource allocation

Cause: Uncaught Exceptions

Solution:

1. Review error logs for exception details
2. Disable problematic skills
3. Report bug to support with logs
4. Restart bot as temporary fix

Cause: Health Check Failures

Solution:

1. Check Cloud Run health check settings
2. Verify bot responding to health endpoints
3. Contact support if health checks misconfigured

---

Error Messages Reference

Common Bot Errors

Error	Cause	Solution
"Invalid bot token"	Token invalid or revoked	Get new token from BotFather
"Webhook failed"	Can't reach webhook URL	Check Cloud Run service, restart bot
"Unauthorized"	Missing session cookie	Re-login to Portal
"Bot not found"	Invalid bot ID or deleted	Verify bot exists
"Provisioning timeout"	Deployment took too long	Delete and recreate bot
"Cloud Run unavailable"	GCP service issue	Check GCP status, wait or contact support
"Rate limit exceeded"	Too many API calls	Wait 60 seconds, implement backoff
"Quota exceeded"	Monthly limit reached	Upgrade tier or wait for reset

Telegram API Errors

Error	Cause	Solution
"Bad Request: message text is empty"	Sending empty message	Always include message text
"Bad Request: message is too long"	Message >4096 chars	Split into multiple messages
"Forbidden: bot was blocked by user"	User blocked bot	Can't send messages to this user
"Too Many Requests"	Rate limit hit	Wait retry_after seconds
"Bad Gateway"	Telegram API down	Wait and retry, check Telegram status

---

Advanced Debugging

Enable Debug Logging

Contact support to enable verbose logging for your bot. Include:

• Bot ID
• Time range to monitor
• Specific issue to debug

Direct GCP Console Access

For Pro/Ultra customers:

1. Request GCP console access from support
2. View real-time logs and metrics
3. Access Cloud Run service directly
4. Debug container instances

Network Traces

For connection issues:

# Test webhook endpoint (support provides URL)
curl -X POST https://openclaw-bot-{id}-uc.a.run.app/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

---

When to Contact Support

Contact support@openclaw.ai if:

• Bot stuck provisioning >15 minutes
• Frequent crashes (>5 per day)
• Persistent webhook failures (>1 hour)
• Performance degradation (latency >5s)
• Unknown error messages
• Security concerns

Include in support request:

• Bot ID
• Error messages (exact text)
• Timestamps of issues
• Steps to reproduce
• Recent configuration changes

Prevention Best Practices

Daily Monitoring

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

Weekly Reviews

• Analyze performance trends
• Review error logs for patterns
• Check quota consumption
• Test bot interactions manually

Configuration Management

• Document all configuration changes
• Test in development bot first
• Keep backup of working configs
• Use gradual rollout for updates

Next Steps

• Billing Troubleshooting
• Troubleshooting Overview
• Bot Management Guide
• Contact Support