# SysOps Agent Profile

## Overview
This document contains everything a SysOps Agent needs to operate autonomously within the Clawdbot ecosystem. It covers system architecture, operational procedures, security protocols, and troubleshooting guides.

## System Architecture

### Core Components
- **Gateway**: Central WebSocket server (port 18789) that manages all channel connections and agent communications
- **Agents**: AI models (Pi, Opus, Kimi, DeepSeek) that process requests and execute tools
- **Channels**: WhatsApp, Telegram, Discord, iMessage, Mattermost connections
- **Nodes**: Paired devices (iOS/Android/macOS) that extend capabilities
- **Canvas**: File server (port 18793) for hosting web surfaces and A2UI

### Service Management
```bash
# Gateway service control
clawdbot gateway status          # Check service status
clawdbot gateway start           # Start service
clawdbot gateway stop            # Stop service
clawdbot gateway restart         # Restart service
clawdbot gateway install         # Install systemd service
clawdbot gateway uninstall       # Remove service

# View logs
clawdbot logs --follow           # Tail gateway logs
```

### Configuration
- Main config: `~/.clawdbot/clawdbot.json`
- State directory: `~/.clawdbot/`
- Dev profile: `~/.clawdbot-dev/` (use `--dev` flag)
- Profile isolation: `~/.clawdbot-<name>/` (use `--profile <name>`)

## Operational Procedures

### Daily Operations
1. **Health Checks** (9 AM UTC)
   - Run: `clawdbot health --json`
   - Check gateway connectivity
   - Verify model availability
   - Review cron job status

2. **Security Audit** (Daily)
   ```bash
   clawdbot security audit
   clawdbot security audit --deep    # Deep scan
   clawdbot security audit --fix     # Auto-fix issues
   ```

3. **Log Review**
   - Check for errors: `clawdbot logs --follow | grep ERROR`
   - Monitor resource usage
   - Review session activity

### Cron Job Management
```bash
# List all jobs
clawdbot cron list

# Add a job
clawdbot cron add \
  --name "Job Name" \
  --cron "0 9 * * *" \
  --tz "UTC" \
  --session isolated \
  --message "Task prompt" \
  --deliver \
  --channel whatsapp \
  --to "+1234567890"

# Edit job
clawdbot cron edit <jobId> --message "New prompt"

# Run job manually
clawdbot cron run <jobId> --force

# View run history
clawdbot cron runs --id <jobId> --limit 50
```

### Model Management
- **Primary**: Anthropic Claude Opus 4.5 (most reliable)
- **Fallbacks**: Kimi, DeepSeek (cost-effective)
- **Configuration**: Set in `clawdbot.json` under `agents.defaults.model`
- **Health monitoring**: Models may timeout during peak hours (AU/US evenings)

### VPS Monitoring (DigitalOcean)
```bash
# Disk usage
df -h
# Alert if >80% full

# Memory usage
free -h
# Alert if >90% used

# System load
uptime
# Alert if load >2.0 for 2vCPU

# Gateway process
ps aux | grep clawdbot-gateway
```

## Security Protocols

### Access Control
1. **DM Policy**: Default to "pairing" for unknown contacts
2. **Group Policy**: Require mentions in groups (`@clawd`)
3. **Gateway Auth**: Always use token auth for non-loopback binds
4. **Browser Control**: Use dedicated profile, avoid personal sessions

### Security Checklist
- [ ] Gateway auth token configured
- [ ] DM policy set to "pairing" or "allowlist"
- [ ] Group mentions required
- [ ] File permissions: `~/.clawdbot/` → 700, config → 600
- [ ] No open DMs/groups without explicit "*" allowlist
- [ ] Browser control uses tailnet + token auth
- [ ] Secrets not in git repositories

### Incident Response
1. **Stop blast radius**: `clawdbot gateway stop`
2. **Lock down access**: Set policies to "disabled"
3. **Rotate secrets**: Gateway token, browser token, API keys
4. **Review logs**: Check for unauthorized access
5. **Run audit**: `clawdbot security audit --deep`

## Available Tools

### Core Tools
- **exec**: Run shell commands (sandboxed by default)
- **process**: Manage background sessions
- **read/write/edit**: File operations
- **web_search/web_fetch**: Web research
- **browser**: Chrome automation
- **canvas**: Node canvas rendering
- **message**: Cross-platform messaging
- **cron**: Job scheduling
- **nodes**: Paired device control

### Tool Groups
- `group:fs`: read, write, edit, apply_patch
- `group:runtime`: exec, bash, process
- `group:web`: web_search, web_fetch
- `group:ui`: browser, canvas
- `group:messaging`: message
- `group:automation`: cron, gateway

### Tool Profiles
- `minimal`: session_status only
- `coding`: fs + runtime + sessions + memory + image
- `messaging`: messaging + session tools
- `full`: no restrictions

## Troubleshooting

### Common Issues

1. **Gateway won't start**
   ```bash
   # Check port conflict
   lsof -i :18789
   
   # Force restart
   clawdbot gateway --force
   ```

2. **Model timeouts**
   - Use Opus for critical decisions
   - Check server load: `uptime`
   - Consider timing (peak hours)

3. **WhatsApp not connecting**
   ```bash
   # Re-authenticate
   clawdbot channels login whatsapp
   
   # Check status
   clawdbot health --json | jq .linkChannel
   ```

4. **Browser control issues**
   - Ensure Chrome is installed
   - Check browser profile status
   - Verify control URL accessibility

### Log Locations
- Gateway logs: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log`
- Session transcripts: `~/.clawdbot/agents/<agentId>/sessions/`
- Cron history: `~/.clawdbot/cron/runs/`

### Recovery Procedures

1. **Complete reset**
   ```bash
   clawdbot gateway stop
   clawdbot reset --hard
   clawdbot onboard --install-daemon
   ```

2. **Config corruption**
   ```bash
   # Backup current config
   cp ~/.clawdbot/clawdbot.json ~/.clawdbot/clawdbot.json.backup
   
   # Reset to defaults
   clawdbot config unset --all
   clawdbot onboard
   ```

3. **Service recovery**
   ```bash
   # Systemd user service
   systemctl --user restart clawdbot-gateway.service
   
   # Check service logs
   journalctl --user -u clawdbot-gateway -f
   ```

## Best Practices

### Performance
- Use model fallbacks for cost optimization
- Enable sandboxing for untrusted input
- Batch operations when possible
- Monitor memory usage on VPS

### Security
- Regular security audits (weekly)
- Principle of least privilege for tools
- Separate bot number from personal
- Never expose gateway publicly without auth

### Maintenance
- Update regularly: `clawdbot update`
- Clean old sessions: `clawdbot sessions prune`
- Monitor disk usage
- Backup config before changes

### Automation
- Use cron for scheduled tasks
- Set up health check alerts
- Automate security audits
- Monitor model performance

## Emergency Contacts
- Gateway issues: Check `clawdbot gateway status`
- Security incidents: Run audit, rotate secrets
- Model failures: Switch to Opus
- System overload: Check VPS resources

---

*Last updated: 2025-01-28*
*Version: 1.0*