Debugging AI Agent Issues: Troubleshooting Guide

Systematic Debugging Approach

When your agent isn't working right:

Identify the symptom - What exactly is wrong?

Check the basics - Is it running? Connected? Configured?

Read the logs - What does the error say?

Isolate the problem - Which component is failing?

Fix and verify - Apply fix, confirm it works

Common Issues and Solutions

Agent Not Responding

Symptoms:

• Messages aren't being processed


• No response to commands


• Agent appears offline

Checklist:

# Check if gateway is running
clawdbot gateway status

# If not running, start it
clawdbot gateway start

# Check for errors in logs
clawdbot gateway logs --tail 50

Common causes:

• Gateway not running


• API key invalid or expired


• Network connectivity issues


• Channel disconnected

API Key Errors

Symptoms:

• "Invalid API key" errors


• "Authentication failed" messages


• 401 status codes

Solutions:

# Verify API key is set
clawdbot auth check

# Re-add if needed
clawdbot auth add anthropic
# Enter key when prompted

# Check environment variable
echo $ANTHROPIC_API_KEY

Tips:

• Keys can be rotated - check if still valid


• Environment variables might not be loaded


• Check for extra whitespace in key

Channel Connection Issues

Telegram not connecting:

# Verify token
clawdbot config get telegram.token

# Check bot status with BotFather
# Send /mybots to @BotFather

# Ensure allowFrom includes your user ID
clawdbot config get telegram.allowFrom

# Get your user ID (send message to @userinfobot)

Discord not connecting:

# Check token validity
clawdbot config get discord.token

# Verify bot is added to server with correct permissions
# Bot needs: Send Messages, Read Message History

# Check intents are enabled in Discord Developer Portal

Memory/Context Issues

Symptoms:

• Agent forgets things mid-conversation


• Losing context between sessions


• Memory files not being read

Solutions:

# Verify memory directory exists
ls -la memory/

# Check MEMORY.md exists and is readable
cat MEMORY.md

# Verify file permissions
chmod 644 MEMORY.md
chmod 755 memory/

Context window exceeded:

• Conversations too long


• Too much context loaded


• Solution: Summarize or truncate older content

Skill Not Working

Symptoms:

• Skill commands not recognized


• Skill errors in responses


• Missing capabilities

Checklist:

# List installed skills
clawdbot skills list

# Check skill files exist
ls -la skills/skill-name/

# Verify SKILL.md is valid
cat skills/skill-name/SKILL.md

# Check skill permissions/requirements

Common issues:

• SKILL.md syntax errors


• Missing dependencies


• Incorrect file paths

Rate Limiting

Symptoms:

• 429 errors


• "Rate limited" messages


• Requests failing intermittently

Solutions:

# Adjust rate limits in config
performance:
  maxRequestsPerMinute: 30
  retryDelay: 1000
  maxRetries: 3

Tips:

• Implement exponential backoff


• Check API provider limits


• Consider caching responses

Slow Responses

Symptoms:

• Long delays before responses


• Timeouts


• Poor performance

Diagnosis:

# Check system resources
top -l 1 | head -20

# Check network latency
ping api.anthropic.com

# Review logs for slow operations
clawdbot gateway logs | grep -i "slow\|timeout"

Optimizations:

• Use faster models for simple tasks


• Enable streaming


• Reduce context size


• Check for blocking operations

Unexpected Behavior

Symptoms:

• Agent doing things you didn't ask


• Wrong interpretations


• Inconsistent responses

Debugging:

• Review system prompt and configuration


• Check recent memory files for context


• Look for conflicting instructions


• Verify SOUL.md and AGENTS.md are consistent

Log Analysis

Reading Logs

# Full logs
clawdbot gateway logs

# Last N lines
clawdbot gateway logs --tail 100

# Filter for errors
clawdbot gateway logs | grep -i "error\|fail\|exception"

# Follow live
clawdbot gateway logs -f

Common Log Patterns

Successful request:

[INFO] Message received from user:123456
[INFO] Processing request...
[INFO] Response sent successfully

API error:

[ERROR] API request failed: 401 Unauthorized
[ERROR] Invalid API key

Rate limited:

[WARN] Rate limited (429). Retrying in 5s...
[INFO] Retry successful

Timeout:

[ERROR] Request timeout after 30000ms
[ERROR] Connection to api.anthropic.com timed out

Diagnostic Commands

Health Check

# Overall status
clawdbot status

# Gateway health
clawdbot gateway health

# Channel connectivity
clawdbot channels test

Configuration Verification

# Show effective config
clawdbot config show --effective

# Validate configuration
clawdbot config validate

# Check specific section
clawdbot config get telegram

Environment Check

# Node version
node --version

# Clawdbot version
clawdbot --version

# Environment variables
printenv | grep -i "anthropic\|clawdbot\|telegram"

Recovery Procedures

Full Restart

# Stop everything
clawdbot gateway stop

# Clear any cached state
clawdbot cache clear

# Start fresh
clawdbot gateway start

Reset Configuration

# Backup current config
cp ~/.clawdbot/config.yaml ~/.clawdbot/config.yaml.backup

# Reset to defaults
clawdbot config reset

# Reconfigure essentials
clawdbot auth add anthropic
clawdbot config set telegram.token YOUR_TOKEN
clawdbot config set telegram.allowFrom [YOUR_USER_ID]

Memory Recovery

If memory is corrupted:

# Backup corrupted files
mv memory/ memory-corrupted/

# Create fresh memory directory
mkdir memory/

# Create starter file
cat > memory/$(date +%Y-%m-%d).md << EOF
# $(date +%Y-%m-%d)

## Recovery
Memory directory recreated after corruption.
Previous files backed up to memory-corrupted/
EOF

Preventive Measures

Regular Maintenance

Daily:

• Check logs for errors


• Verify agent is responding

Weekly:

• Review memory files


• Check disk space


• Verify backups

Monthly:

• Update dependencies


• Review configuration


• Clean old logs

Monitoring Setup

# Add to config for better monitoring
logging:
  level: info
  file:
    enabled: true
    path: ./logs/clawdbot.log
    maxSize: 10MB
    maxFiles: 5

alerts:
  enabled: true
  onError: true
  onRateLimit: true

Getting Help

If you're stuck:

Check documentation - Many issues are documented

Search issues - GitHub issues often have solutions

Community - Discord or community forums

Minimal reproduction - Create smallest example that shows the problem

When asking for help, include:

• Clawdbot version


• Node version


• Operating system


• Error messages (full text)


• Steps to reproduce


• What you've already tried

---

Next: Performance Optimization - Making your agent faster