Troubleshooting

Common issues and solutions for SimpleClaw

Troubleshooting Guide

Common issues and their solutions for SimpleClaw Gateway, channels, and agents.

Gateway Issues

Gateway Won’t Start

Port already in use

Error: EADDRINUSE: address already in use

Solution:

1. Find process using port 18789:

   lsof -i :18789
   # or on Linux:
   sudo netstat -tlnp | grep 18789
   

2. Kill the process:

   kill -9 <PID>
   

3. Or use a different port:

   simpleclaw gateway run --port 18790
   

Permission denied

Error: EACCES: permission denied

Solution:

1. Don’t use privileged ports (below 1024) without sudo
2. Use default port 18789 (no sudo needed)
3. Check file permissions:
   ls -la ~/.simpleclaw
   

Config errors

Error: Config validation failed

Solution:

1. Validate config syntax:

   simpleclaw config validate
   

2. Check for missing required fields:

   simpleclaw doctor
   

3. Reset to defaults if needed:

   mv ~/.simpleclaw/simpleclaw.json ~/.simpleclaw/simpleclaw.json.backup
   simpleclaw onboard
   

Gateway Running but Not Responding

1. Check Gateway Status

   simpleclaw gateway status
   
2. Verify Port and Bind

   simpleclaw config get gateway.port
   simpleclaw config get gateway.bind
   
3. Test Local Connection

   curl http://localhost:18789/health
   
4. Check Logs

   simpleclaw gateway logs --tail 100
   

Channel Issues

WhatsApp Not Connecting

QR code not appearing

1. Ensure channel is enabled:

   simpleclaw config get channels.whatsapp.enabled
   

2. Clear credentials and re-login:

   rm -rf ~/.simpleclaw/credentials/whatsapp
   simpleclaw channels login --channel whatsapp
   

Connection keeps dropping

1. Check for multiple devices using same credentials
2. Verify phone has stable internet connection
3. Check Gateway logs:
   simpleclaw gateway logs | grep -i whatsapp
   

Messages not being received

1. Check allowlist:

   simpleclaw config get channels.whatsapp.allowFrom
   

2. Verify DM policy:

   simpleclaw config get channels.whatsapp.dmPolicy
   

3. Test with allowed number

Telegram Bot Issues

Bot not responding

1. Verify bot token:

   simpleclaw config get channels.telegram.botToken
   

2. Test token with Telegram API:

   curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
   

3. Check Gateway logs for errors:

   simpleclaw gateway logs | grep -i telegram
   

Can't find bot in Telegram

1. Check bot username with BotFather
2. Send /start to activate bot
3. Verify bot isn’t blocked in your account

Discord Bot Issues

Bot offline

1. Check bot token:

   simpleclaw config get channels.discord.token
   

2. Verify privileged intents are enabled in Discord Developer Portal

3. Check Gateway connection:

   simpleclaw channels status --probe
   

Bot not seeing messages

1. Enable Message Content Intent in Discord Developer Portal
2. Verify bot has permission to read messages in the channel
3. Check Gateway logs:
   simpleclaw gateway logs | grep -i discord
   

Agent Issues

Agent Not Responding

Model/provider errors

1. Check API keys:

   simpleclaw config get providers
   

2. Verify model is configured:

   simpleclaw config get agent.model
   

3. Test provider authentication:

   simpleclaw login --provider anthropic
   

4. Check for rate limits in logs:

   simpleclaw gateway logs --level error
   

Slow responses

1. Check thinking level:

   simpleclaw config get agent.thinkingLevel
   

2. Switch to faster model:

   simpleclaw config set agent.model '"anthropic/claude-sonnet-4"' --json
   

3. Monitor token usage:

   simpleclaw agent --message "test" --usage full
   

Agent using wrong model

1. Check session configuration:

   simpleclaw sessions list
   

2. Update session model:

   simpleclaw sessions patch main --model "anthropic/claude-opus-4-6"
   

3. Or reset session:

   simpleclaw sessions reset main
   

Tool Execution Errors

bash tool failing

1. Check shell environment:

   simpleclaw config get shell.path
   

2. Test bash directly:

   simpleclaw agent --message "Run: echo test" --tool bash
   

3. Check for command restrictions

browser tool not working

1. Verify browser is enabled:

   simpleclaw config get browser.enabled
   

2. Check Chrome/Chromium installation:

   which chromium-browser
   # or
   which google-chrome
   

3. See Browser Troubleshooting for Linux issues

Remote Access Issues

Can’t Connect to Remote Gateway

Tailscale connection failed

1. Verify Tailscale is running:

   tailscale status
   

2. Check Tailscale Serve config:

   simpleclaw config get gateway.tailscale
   

3. Test Tailscale URL:

   curl https://<hostname>.tailnet.ts.net/health
   

SSH tunnel drops

1. Use autossh for persistence:

   autossh -M 0 -L 18789:127.0.0.1:18789 user@server -N
   

2. Check SSH keep-alive settings in ~/.ssh/config:

   Host your-server
     ServerAliveInterval 60
     ServerAliveCountMax 3
   

Authentication errors

1. Check password is set (for public access):

   simpleclaw config get gateway.auth.password
   

2. Verify auth mode:

   simpleclaw config get gateway.auth.mode
   

3. Test authentication:

   curl -u :password https://gateway.example.com/health
   

Installation Issues

npm Install Failures

Node version too old

Error: Unsupported engine

Solution:

Install Node.js 22+:

# Using nvm
nvm install 22
nvm use 22

# Or via package manager
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Permission errors during install

Error: EACCES: permission denied

Solution:

Use npm prefix to install globally without sudo:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g simpleclaw@latest

Performance Issues

High Memory Usage

1. Check session count:

   simpleclaw sessions list
   

2. Compact old sessions:

   simpleclaw sessions compact --all
   

3. Delete unused sessions:

   simpleclaw sessions delete <session-key>
   

High CPU Usage

1. Check for runaway agents:

   ps aux | grep simpleclaw
   

2. Review active sessions:

   simpleclaw sessions list
   

3. Restart Gateway:

   simpleclaw gateway restart
   

Diagnostic Commands

Doctor Command

Run comprehensive health check:

simpleclaw doctor

This checks:

• Config validity
• Channel setup
• Model configuration
• DM policy safety
• Dependency versions

Status Commands

# Gateway status
simpleclaw gateway status

# Channel status
simpleclaw channels status --probe

# Agent status
simpleclaw agents list

# Session status
simpleclaw sessions list

Log Commands

# Tail all logs
simpleclaw gateway logs --tail 50 --follow

# Error logs only
simpleclaw gateway logs --level error

# Filter by channel
simpleclaw gateway logs | grep -i telegram

# Systemd logs (Linux)
sudo journalctl -u simpleclaw-gateway -f

Getting Help

If you’re still stuck:

Discord Community

Ask for help in the SimpleClaw Discord

GitHub Issues

Report bugs or request features

Documentation

Search the full documentation

FAQ

Common questions and answers

Debug Mode

Enable verbose logging:

# Temporary (current session)
export SIMPLECLAW_LOG_LEVEL=debug
simpleclaw gateway run

# Permanent (config)
simpleclaw config set logging.level '"debug"' --json

Collecting Debug Information

When reporting issues, include:

# Version info
simpleclaw --version
node --version

# System info
uname -a  # Linux/macOS

# Config (redact secrets!)
simpleclaw config get | jq 'del(.providers, .channels.*.token, .channels.*.apiKey)'

# Recent logs
simpleclaw gateway logs --tail 100 > debug.log

# Channel status
simpleclaw channels status --probe > channels.log