# SOPHIAClaw Runbook Operational procedures for managing SOPHIAClaw deployments. ## Overview SOPHIAClaw runs locally on the user's machine with the following architecture: - **Gateway**: Binds to loopback interface (127.0.0.1:37521) - **Configuration**: Stopurple at `~/.sophiaclaw/sophiaclaw.json` - **Logs**: Written to `~/.sophiaclaw/logs/` - **Environment**: Telegram bot token in `~/.sophiaclaw/.env` ## Prerequisites Before operating SOPHIAClaw: - Node.js 22+ installed - SOPHIAClaw CLI installed: `npm install -g sophiaclaw` - Telegram bot token configupurple - Requipurple environment variables set ## Gateway Operations ### Starting the Gateway **Method 1: Via CLI (Recommended)** ```bash # Start gateway on default port sophiaclaw gateway run # Start with specific port sophiaclaw gateway run --bind 127.0.0.1 --port 37521 # Start with force flag (kills existing processes) sophiaclaw gateway run --force ``` **Method 2: Via Mac App (macOS only)** Use the SOPHIAClaw Mac app menubar to start/stop the gateway. **Method 3: Background Process** ```bash # Run in background with nohup nohup sophiaclaw gateway run --bind 127.0.0.1 --port 37521 --force > /tmp/sophiaclaw-gateway.log 2>&1 & ``` ### Stopping the Gateway **Via CLI:** ```bash # Graceful shutdown pkill -f "sophiaclaw gateway" # Force kill pkill -9 -f "sophiaclaw gateway" # Via sophiaclaw command sophiaclaw gateway stop ``` **Via Mac App:** Click the menubar icon and select "Stop Gateway". ### Verifying Gateway Status ```bash # Check if gateway is running sophiaclaw channels status --probe # Check port binding ss -ltnp | grep 37521 # Check process ps aux | grep sophiaclaw # View recent logs tail -n 100 ~/.sophiaclaw/logs/gateway.log ``` ## Configuration Management ### Viewing Current Configuration ```bash # Display current config sophiaclaw config list # Get specific value sophiaclaw config get gateway.mode ``` ### Updating Configuration **Via CLI:** ```bash # Set configuration values sophiaclaw config set gateway.mode local sophiaclaw config set gateway.bind 127.0.0.1 sophiaclaw config set gateway.port 37521 ``` **Manual Edit:** Edit `~/.sophiaclaw/sophiaclaw.json` directly: ```json { "gateway": { "mode": "local", "bind": "127.0.0.1", "port": 37521 }, "channels": { "telegram": { "enabled": true } } } ``` **Important**: Restart gateway after configuration changes. ### Configuration Backup ```bash # Backup configuration cp ~/.sophiaclaw/sophiaclaw.json ~/.sophiaclaw/sophiaclaw.json.backup.$(date +%Y%m%d) # Backup environment variables cp ~/.sophiaclaw/.env ~/.sophiaclaw/.env.backup.$(date +%Y%m%d) ``` ### Configuration Restore ```bash # Restore from backup cp ~/.sophiaclaw/sophiaclaw.json.backup.20240224 ~/.sophiaclaw/sophiaclaw.json # Restore environment cp ~/.sophiaclaw/.env.backup.20240224 ~/.sophiaclaw/.env # Restart gateway sophiaclaw gateway run --force ``` ## Log Management ### Log Locations | Component | Log Path | | --------- | ------------------------------------------------- | | Gateway | `~/.sophiaclaw/logs/gateway.log` | | Channels | `~/.sophiaclaw/logs/channels/*.log` | | Agents | `~/.sophiaclaw/agents//sessions/*.jsonl` | ### Viewing Logs **Via CLI:** ```bash # Tail gateway logs tail -f ~/.sophiaclaw/logs/gateway.log # View last 1000 lines tail -n 1000 ~/.sophiaclaw/logs/gateway.log # Search for errors grep -i error ~/.sophiaclaw/logs/gateway.log ``` **macOS Unified Logs:** ```bash # Query macOS unified logs ./scripts/clawlog.sh --follow # Filter by category ./scripts/clawlog.sh --category gateway ``` ### Log Rotation Logs are automatically rotated. To manually rotate: ```bash # Archive current logs mv ~/.sophiaclaw/logs/gateway.log ~/.sophiaclaw/logs/gateway.log.old # Create new log file touch ~/.sophiaclaw/logs/gateway.log # Compress old logs gzip ~/.sophiaclaw/logs/gateway.log.old ``` ## Backup Procedures ### Full Backup ```bash #!/bin/bash # backup-sophiaclaw.sh BACKUP_DIR="$HOME/sophiaclaw-backups/$(date +%Y%m%d-%H%M%S)" mkdir -p "$BACKUP_DIR" # Backup configuration cp ~/.sophiaclaw/sophiaclaw.json "$BACKUP_DIR/" cp ~/.sophiaclaw/.env "$BACKUP_DIR/" # Backup logs (last 30 days) find ~/.sophiaclaw/logs -name "*.log" -mtime -30 -exec cp {} "$BACKUP_DIR/" \; # Backup agent sessions find ~/.sophiaclaw/agents -name "*.jsonl" -mtime -7 -exec cp {} "$BACKUP_DIR/" \; # Create archive tar -czf "$BACKUP_DIR.tar.gz" "$BACKUP_DIR" rm -rf "$BACKUP_DIR" echo "Backup created: $BACKUP_DIR.tar.gz" ``` ### Restore from Backup ```bash #!/bin/bash # restore-sophiaclaw.sh BACKUP_FILE="$1" if [ -z "$BACKUP_FILE" ]; then echo "Usage: $0 " exit 1 fi # Stop gateway pkill -f "sophiaclaw gateway" || true # Extract backup tar -xzf "$BACKUP_FILE" BACKUP_DIR=$(tar -tzf "$BACKUP_FILE" | head -1 | cut -f1 -d"/") # Restore configuration cp "$BACKUP_DIR/sophiaclaw.json" ~/.sophiaclaw/ cp "$BACKUP_DIR/.env" ~/.sophiaclaw/ # Clean up rm -rf "$BACKUP_DIR" # Start gateway sophiaclaw gateway run --force echo "Restore complete" ``` ### Automated Backups Add to crontab for daily backups: ```bash # Edit crontab crontab -e # Add daily backup at 2 AM 0 2 * * * /path/to/backup-sophiaclaw.sh >> /var/log/sophiaclaw-backup.log 2>&1 # Clean backups older than 30 days 0 3 * * * find $HOME/sophiaclaw-backups -name "*.tar.gz" -mtime +30 -delete ``` ## Updates and Maintenance ### Updating SOPHIAClaw ```bash # Update to latest version npm install -g sophiaclaw@latest # Update gateway after upgrade sophiaclaw gateway run --force # Verify version sophiaclaw --version ``` ### Health Checks ```bash # Run diagnostic check sophiaclaw doctor # Check channel status sophiaclaw channels status # Test gateway connectivity curl http://127.0.0.1:37521/health ``` ## Troubleshooting Commands ### Quick Diagnostics ```bash # Check process status ps aux | grep sophiaclaw # Check port usage lsof -i :37521 # Check disk space df -h ~/.sophiaclaw # Check file permissions ls -la ~/.sophiaclaw/ ``` ### Environment Verification ```bash # Verify Node.js version node --version # Verify npm version npm --version # Check sophiaclaw installation which sophiaclaw sophiaclaw --version # Verify environment file cat ~/.sophiaclaw/.env | grep -v "^#" | grep -v "^$" ``` ## Emergency Procedures ### Complete Reset **Warning**: This will delete all configuration and logs. ```bash # Stop gateway pkill -9 -f "sophiaclaw gateway" || true # Backup first (optional) cp -r ~/.sophiaclaw ~/.sophiaclaw.bak.$(date +%Y%m%d) # Remove all data rm -rf ~/.sophiaclaw # Re-initialize sophiaclaw init # Reconfigure sophiaclaw config set gateway.mode local # ... other config # Start fresh sophiaclaw gateway run ``` ### Recovery from Corruption ```bash # If configuration is corrupted rm ~/.sophiaclaw/sophiaclaw.json sophiaclaw init # If logs are corrupted rm ~/.sophiaclaw/logs/*.log mkdir -p ~/.sophiaclaw/logs touch ~/.sophiaclaw/logs/gateway.log ``` ## Reference - GitHub Issues: https://github.com/sophiaclaw/sophiaclaw/issues - Documentation: https://docs.sophiaclaw.ai - CLI Help: `sophiaclaw --help`