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 useSolution:

Find process using port 18789:

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

Kill the process:
```
kill -9 <PID>
```
Or use a different port:
```
simpleclaw gateway run --port 18790
```

Permission denied

Error: EACCES: permission deniedSolution:

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

Config errors

Error: Config validation failedSolution:

Validate config syntax:
```
simpleclaw config validate
```
Check for missing required fields:
```
simpleclaw doctor
```

Reset to defaults if needed:

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

Gateway Running but Not Responding

Check Gateway Status

simpleclaw gateway status

Verify Port and Bind

simpleclaw config get gateway.port
simpleclaw config get gateway.bind

Test Local Connection

curl http://localhost:18789/health

Check Logs

simpleclaw gateway logs --tail 100

Channel Issues

WhatsApp Not Connecting

QR code not appearing

Ensure channel is enabled:

simpleclaw config get channels.whatsapp.enabled

Clear credentials and re-login:

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

Connection keeps dropping

Check for multiple devices using same credentials
Verify phone has stable internet connection

Check Gateway logs:

simpleclaw gateway logs | grep -i whatsapp

Messages not being received

Check allowlist:

simpleclaw config get channels.whatsapp.allowFrom

Verify DM policy:

simpleclaw config get channels.whatsapp.dmPolicy

Test with allowed number

Telegram Bot Issues

Bot not responding

Verify bot token:

simpleclaw config get channels.telegram.botToken

Test token with Telegram API:

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

Check Gateway logs for errors:

simpleclaw gateway logs | grep -i telegram

Can't find bot in Telegram

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

Discord Bot Issues

Bot offline

Check bot token:

simpleclaw config get channels.discord.token

Verify privileged intents are enabled in Discord Developer Portal
Check Gateway connection:
```
simpleclaw channels status --probe
```

Bot not seeing messages

Enable Message Content Intent in Discord Developer Portal
Verify bot has permission to read messages in the channel

Check Gateway logs:

simpleclaw gateway logs | grep -i discord

Agent Issues

Agent Not Responding

Model/provider errors

Check API keys:
```
simpleclaw config get providers
```
Verify model is configured:
```
simpleclaw config get agent.model
```
Test provider authentication:
```
simpleclaw login --provider anthropic
```
Check for rate limits in logs:
```
simpleclaw gateway logs --level error
```

Slow responses

Check thinking level:

simpleclaw config get agent.thinkingLevel

Switch to faster model:

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

Monitor token usage:

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

Agent using wrong model

Check session configuration:
```
simpleclaw sessions list
```

Update session model:

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

Or reset session:
```
simpleclaw sessions reset main
```

Tool Execution Errors

bash tool failing

Check shell environment:
```
simpleclaw config get shell.path
```

Test bash directly:

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

Check for command restrictions

browser tool not working

Verify browser is enabled:
```
simpleclaw config get browser.enabled
```

Check Chrome/Chromium installation:

which chromium-browser
# or
which google-chrome

See Browser Troubleshooting for Linux issues

Remote Access Issues

Can’t Connect to Remote Gateway

Tailscale connection failed

Verify Tailscale is running:
```
tailscale status
```

Check Tailscale Serve config:

simpleclaw config get gateway.tailscale

Test Tailscale URL:

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

SSH tunnel drops

Use autossh for persistence:

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

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

Host your-server
  ServerAliveInterval 60
  ServerAliveCountMax 3

Authentication errors

Check password is set (for public access):

simpleclaw config get gateway.auth.password

Verify auth mode:

simpleclaw config get gateway.auth.mode

Test authentication:

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

Installation Issues

npm Install Failures

Node version too old

Error: Unsupported engineSolution: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 deniedSolution: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

Check session count:
```
simpleclaw sessions list
```
Compact old sessions:
```
simpleclaw sessions compact --all
```

Delete unused sessions:

simpleclaw sessions delete <session-key>

High CPU Usage

Check for runaway agents:
```
ps aux | grep simpleclaw
```
Review active sessions:
```
simpleclaw sessions list
```
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

Setup Guides

Advanced

Troubleshooting

Troubleshooting Guide

Gateway Issues

Gateway Won’t Start

Gateway Running but Not Responding

Channel Issues

WhatsApp Not Connecting

Telegram Bot Issues

Discord Bot Issues

Agent Issues

Agent Not Responding

Tool Execution Errors

Remote Access Issues

Can’t Connect to Remote Gateway

Installation Issues

npm Install Failures

Performance Issues

High Memory Usage

High CPU Usage

Diagnostic Commands

Doctor Command

Status Commands

Log Commands

Getting Help

Discord Community

GitHub Issues

Documentation

FAQ

Debug Mode

Collecting Debug Information

Build docs developers (and LLMs) love

Setup Guides

Advanced

​Troubleshooting Guide

​Gateway Issues

​Gateway Won’t Start

​Gateway Running but Not Responding

​Channel Issues

​WhatsApp Not Connecting

​Telegram Bot Issues

​Discord Bot Issues

​Agent Issues

​Agent Not Responding

​Tool Execution Errors

​Remote Access Issues

​Can’t Connect to Remote Gateway

​Installation Issues

​npm Install Failures

​Performance Issues

​High Memory Usage

​High CPU Usage

​Diagnostic Commands

​Doctor Command

​Status Commands

​Log Commands

​Getting Help

Discord Community

GitHub Issues

Documentation

FAQ

​Debug Mode

​Collecting Debug Information

Build docs developers (and LLMs) love

Troubleshooting Guide

Gateway Issues

Gateway Won’t Start

Gateway Running but Not Responding

Channel Issues

WhatsApp Not Connecting

Telegram Bot Issues

Discord Bot Issues

Agent Issues

Agent Not Responding

Tool Execution Errors

Remote Access Issues

Can’t Connect to Remote Gateway

Installation Issues

npm Install Failures

Performance Issues

High Memory Usage

High CPU Usage

Diagnostic Commands

Doctor Command

Status Commands

Log Commands

Getting Help

Debug Mode

Collecting Debug Information