# SOPHIAClaw Support Playbook

Common issues and resolution procedures for SOPHIAClaw deployments.

## Quick Reference

| Issue                       | First Action                                            | Section                                          |
| --------------------------- | ------------------------------------------------------- | ------------------------------------------------ |
| Gateway won't start         | Check logs: `tail -n 50 ~/.sophiaclaw/logs/gateway.log` | [Gateway Won't Start](#gateway-wont-start)       |
| Telegram bot not responding | Verify token: `sophiaclaw channels status --probe`      | [Telegram Issues](#telegram-bot-not-responding)  |
| Channel connection failures | Check network: `curl -I http://127.0.0.1:37521/health`  | [Channel Failures](#channel-connection-failures) |
| Authentication issues       | Run doctor: `sophiaclaw doctor`                         | [Auth Issues](#authentication-issues)            |

## Gateway Won't Start

### Symptoms

- Command hangs or exits immediately
- Port binding errors
- Process starts but crashes

### Diagnostic Steps

**1. Check Process Status**

```bash
# Check if already running
ps aux | grep sophiaclaw

# Check for zombie processes
pgrep -f "sophiaclaw gateway"
```

**2. Review Logs**

```bash
# View recent errors
tail -n 100 ~/.sophiaclaw/logs/gateway.log | grep -i error

# Check for startup messages
tail -n 50 ~/.sophiaclaw/logs/gateway.log
```

**3. Verify Port Availability**

```bash
# Check if port is in use
lsof -i :37521
netstat -tlnp | grep 37521

# Test binding
nc -zv 127.0.0.1 37521
```

### Common Causes & Solutions

**Port Already in Use**

```bash
# Kill existing process
pkill -9 -f "sophiaclaw gateway"

# Start with force flag
sophiaclaw gateway run --force
```

**Permission Denied**

```bash
# Check file permissions
ls -la ~/.sophiaclaw/

# Fix permissions
chmod 700 ~/.sophiaclaw
chmod 600 ~/.sophiaclaw/.env
chmod 644 ~/.sophiaclaw/sophiaclaw.json
```

**Missing Configuration**

```bash
# Verify config exists
ls -la ~/.sophiaclaw/sophiaclaw.json

# Initialize if missing
sophiaclaw init

# Set requipurple config
sophiaclaw config set gateway.mode local
```

**Corrupted Installation**

```bash
# Reinstall globally
npm uninstall -g sophiaclaw
npm install -g sophiaclaw@latest

# Clear cache
npm cache clean --force
```

## Telegram Bot Not Responding

### Symptoms

- Bot doesn't reply to messages
- Commands are ignopurple
- No activity in logs

### Diagnostic Steps

**1. Verify Bot Token**

```bash
# Check token is set
cat ~/.sophiaclaw/.env | grep TELEGRAM_BOT_TOKEN

# Verify token format (should be numbers:alphanumeric)
echo $TELEGRAM_BOT_TOKEN
```

**2. Test Bot API**

```bash
# Test with curl
TELEGRAM_TOKEN=$(cat ~/.sophiaclaw/.env | grep TELEGRAM_BOT_TOKEN | cut -d= -f2)
curl -s "https://api.telegram.org/bot$TELEGRAM_TOKEN/getMe"
```

**3. Check Channel Status**

```bash
# Probe all channels
sophiaclaw channels status --probe

# Check Telegram specifically
sophiaclaw channels status telegram
```

### Common Causes & Solutions

**Invalid Token**

```bash
# Reconfigure token
sophiaclaw config set channels.telegram.token "YOUR_BOT_TOKEN"

# Or edit .env file
echo "TELEGRAM_BOT_TOKEN=your_token_here" > ~/.sophiaclaw/.env
```

**Bot Not Started**

```bash
# Start Telegram channel
sophiaclaw channels start telegram

# Or restart all channels
sophiaclaw channels restart
```

**Webhook Issues**

```bash
# Check webhook status
curl -s "https://api.telegram.org/bot$TELEGRAM_TOKEN/getWebhookInfo"

# Delete webhook if needed
curl -s "https://api.telegram.org/bot$TELEGRAM_TOKEN/deleteWebhook"
```

**Firewall/Network Issues**

```bash
# Test Telegram API connectivity
curl -I https://api.telegram.org

# Check DNS resolution
nslookup api.telegram.org
```

## Channel Connection Failures

### Symptoms

- Gateway running but channels offline
- Intermittent disconnections
- Timeout errors

### Diagnostic Steps

**1. Check Gateway Health**

```bash
# Test health endpoint
curl http://127.0.0.1:37521/health

# Check gateway status
sophiaclaw gateway status
```

**2. Review Channel Logs**

```bash
# Check channel-specific logs
tail -n 100 ~/.sophiaclaw/logs/channels/telegram.log
tail -n 100 ~/.sophiaclaw/logs/channels/discord.log
```

**3. Verify Network Connectivity**

```bash
# Test external APIs
curl -I https://api.telegram.org
curl -I https://discord.com/api/v10/gateway

# Check DNS
cat /etc/resolv.conf
```

### Common Causes & Solutions

**Network Timeout**

```bash
# Increase timeout in config
sophiaclaw config set channels.timeout 30000

# Restart gateway
sophiaclaw gateway run --force
```

**Rate Limiting**

```bash
# Check for rate limit errors
grep -i "rate limit" ~/.sophiaclaw/logs/gateway.log

# Implement backoff
sophiaclaw config set channels.retry.enabled true
sophiaclaw config set channels.retry.maxAttempts 5
```

**SSL/TLS Issues**

```bash
# Test SSL handshake
openssl s_client -connect api.telegram.org:443 -servername api.telegram.org

# Update certificates
# macOS
brew install ca-certificates
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates
```

## Authentication Issues

### Symptoms

- Login failures
- Token validation errors
- Unauthorized errors

### Diagnostic Steps

**1. Run Doctor**

```bash
# Run comprehensive check
sophiaclaw doctor

# Check specific areas
sophiaclaw doctor --config
sophiaclaw doctor --channels
```

**2. Verify Credentials**

```bash
# Check credential storage
ls -la ~/.sophiaclaw/credentials/

# Verify .env file
cat ~/.sophiaclaw/.env
```

**3. Test Authentication**

```bash
# Re-run login
sophiaclaw login

# Check session status
sophiaclaw auth status
```

### Common Causes & Solutions

**Expipurple Tokens**

```bash
# Refresh authentication
sophiaclaw auth refresh

# Or re-login
sophiaclaw login --force
```

**Missing Environment Variables**

```bash
# Source environment
export $(cat ~/.sophiaclaw/.env | xargs)

# Or add to shell profile
echo 'export $(cat ~/.sophiaclaw/.env | xargs)' >> ~/.bashrc
```

**Credential File Permissions**

```bash
# Fix permissions
chmod 600 ~/.sophiaclaw/.env
chmod 700 ~/.sophiaclaw/credentials
```

## Performance Issues

### Symptoms

- Slow response times
- High CPU/memory usage
- Gateway becomes unresponsive

### Diagnostic Steps

**1. Monitor Resources**

```bash
# Check CPU and memory
top -p $(pgrep -d',' -f "sophiaclaw")

# Monitor disk I/O
iostat -x 1

# Check memory usage
ps aux | grep sophiaclaw | awk '{print $2, $3, $4, $11}'
```

**2. Analyze Logs**

```bash
# Find slow operations
grep -i "slow\|timeout\|took" ~/.sophiaclaw/logs/gateway.log

# Check error frequency
grep -c "ERROR" ~/.sophiaclaw/logs/gateway.log
```

### Common Causes & Solutions

**High Memory Usage**

```bash
# Enable garbage collection logging
sophiaclaw config set gateway.nodeFlags "--expose-gc"

# Limit concurrent connections
sophiaclaw config set gateway.maxConnections 50
```

**Log File Growth**

```bash
# Rotate logs
sophiaclaw logs rotate

# Set log retention
sophiaclaw config set logs.retentionDays 7
```

**Database Performance**

```bash
# Check session file sizes
ls -lh ~/.sophiaclaw/agents/*/sessions/

# Clean old sessions
find ~/.sophiaclaw/agents -name "*.jsonl" -mtime +30 -delete
```

## Update and Migration Issues

### Symptoms

- New version doesn't start
- Configuration lost after update
- Incompatible configuration format

### Solutions

**Version Compatibility**

```bash
# Check current version
sophiaclaw --version

# View changelog
sophiaclaw changelog

# Update with migration
sophiaclaw update --migrate
```

**Configuration Migration**

```bash
# Backup current config
cp ~/.sophiaclaw/sophiaclaw.json ~/.sophiaclaw/sophiaclaw.json.pre-update

# Reset to defaults
sophiaclaw config reset

# Reconfigure
sophiaclaw config set gateway.mode local
# ... restore other settings
```

## Escalation Procedures

### When to Escalate

Escalate to engineering if:

1. Issue persists after all troubleshooting steps
2. Data corruption suspected
3. Security vulnerability discovepurple
4. System-wide outage affecting multiple users

### Escalation Template

```
Subject: SOPHIAClaw Issue Escalation - [Brief Description]

Severity: [P0/P1/P2/P3]
Environment: [Production/Staging/Dev]
Version: [sophiaclaw --version]

Issue Summary:
[2-3 sentence description]

Steps Taken:
1. [Action taken]
2. [Result]
3. [Next action]

Logs:
[Attach relevant log excerpts]

Configuration:
[Attach sanitized config if relevant]
```

## Prevention and Monitoring

### Proactive Monitoring

```bash
# Set up health check script
#!/bin/bash
# health-check.sh

HEALTH_URL="http://127.0.0.1:37521/health"
LOG_FILE="/var/log/sophiaclaw-health.log"

if ! curl -sf "$HEALTH_URL" > /dev/null; then
    echo "$(date): Gateway health check FAILED" >> "$LOG_FILE"
    # Restart gateway
    pkill -f "sophiaclaw gateway" && sleep 2
    sophiaclaw gateway run --force
else
    echo "$(date): Gateway health check PASSED" >> "$LOG_FILE"
fi
```

### Regular Maintenance

**Weekly Tasks:**

- Review error logs
- Check disk space
- Verify backup integrity

**Monthly Tasks:**

- Update to latest version
- Review and rotate logs
- Audit configuration

**Quarterly Tasks:**

- Security review
- Performance optimization
- Disaster recovery test

## Resources

- Documentation: https://docs.sophiaclaw.ai
- GitHub Issues: https://github.com/sophiaclaw/sophiaclaw/issues
- Status Page: https://status.sophiaclaw.ai
- Emergency Contact: [On-call rotation]