claude-home/productivity/openclaw/CONTEXT.md

# OpenClaw Personal AI Assistant - Technology Context

## Overview

OpenClaw is an open-source personal AI assistant that runs locally with autonomous agent capabilities. Originally created as "Clawdbot" by Peter Steinberger, now community-maintained as OpenClaw.

**Deployment:** LXC 224 (10.10.0.224)
**Status:** Deployment in progress
**Primary Use:** Personal automation, task management, Discord integration

## Architecture

### Gateway-Centric Design
- **Gateway Daemon:** Single control plane for all operations
- **Messaging:** Handles chat platform integrations (Discord, Telegram, etc.)
- **Tool Execution:** Sandboxed code execution via nested Docker containers
- **Client Connections:** WebSocket and HTTP API for external integrations

### Key Components
1. **OpenClaw Gateway** - Node.js application, port 18789
2. **Docker-in-Docker Sandbox** - Isolated execution environment
3. **Persistent Workspace** - `/workspace` for file operations and memory
4. **Configuration Layer** - `openclaw.json` + environment variables

## AI Provider Integration

**Current Provider:** MiniMax M2.1
- **Model:** MiniMax-M2.1 (200K context window)
- **API Type:** Anthropic-compatible messages API
- **Endpoint:** https://api.minimax.io/anthropic
- **Authentication:** Bearer token via `MINIMAX_API_KEY`

**Model Selection:**
- Primary: `minimax/MiniMax-M2.1` (standard, balanced performance)
- Fast variant: `minimax/MiniMax-M2.1-lightning` (lower latency, lower cost)

**Pricing (per 1M tokens):**
- M2.1: $0.50 input / $1.50 output
- M2.1 Lightning: $0.30 input / $0.90 output

## Discord Integration

**Bot Configuration:**
- **Policy:** DM pairing (secure by default)
- **Intents Required:** Message Content + Server Members
- **Permissions:** View/Send/History + Embeds + Files + Reactions

**Access Control:**
- DMs: Pairing code required (1-hour expiry)
- Guild channels: Can be enabled per-server with allowlists
- Mention requirement: Optional gating for shared channels

**Message Handling:**
- History context: 20 messages (configurable)
- File uploads: 8MB max (configurable)
- Response format: Markdown with embeds

## Security Model

### Sandboxing
- **Docker-in-Docker:** Code execution isolated in nested containers
- **AppArmor:** Unconfined profile required for container nesting
- **UID:** Runs as non-root `node` user (UID 1000) inside container

### Secrets Management
- **Storage:** Environment variables via `.env` file
- **Interpolation:** `${VAR_NAME}` syntax in openclaw.json
- **Scope:** Secrets only accessible to gateway process

### Network Isolation
- **Bridge Network:** `openclaw-net` isolates from other services
- **Exposed Ports:** Only 18789 (gateway) accessible on host network
- **Outbound:** Requires internet access for AI API calls

## Operational Patterns

### Standard Operations
```bash
# Start OpenClaw
docker compose up -d

# View logs
docker compose logs -f openclaw-gateway

# Restart after config changes
docker compose restart openclaw-gateway

# Stop service
docker compose down
```

### Pairing Management
```bash
# List pending pairing requests
docker compose exec openclaw-gateway openclaw pairing list discord

# Approve pairing
docker compose exec openclaw-gateway openclaw pairing approve discord <code>

# Revoke access
docker compose exec openclaw-gateway openclaw pairing revoke discord <user_id>
```

### Diagnostics
```bash
# Health check
docker compose exec openclaw-gateway openclaw doctor

# Channel status
docker compose exec openclaw-gateway openclaw channels status --probe

# Model configuration
docker compose exec openclaw-gateway openclaw models list
```

### Configuration Updates
```bash
# Edit configuration
nano openclaw.json

# Restart to apply changes
docker compose restart openclaw-gateway

# Verify changes
docker compose logs openclaw-gateway | grep "Configuration loaded"
```

## Resource Usage Patterns

**Expected Baseline:**
- Idle: ~200MB RAM, <5% CPU
- Active chat: ~500MB RAM, 10-20% CPU
- Browser automation: ~1GB RAM, 30-50% CPU
- Concurrent operations: Up to 2GB RAM

**Disk Usage:**
- Application: ~500MB
- Workspace files: Variable (user-dependent)
- Logs: ~50MB/week (with rotation)
- Docker images: ~1GB

**Network:**
- AI API calls: ~10-100KB per request
- Discord: WebSocket connection (minimal bandwidth)
- File uploads: Up to 8MB per message

## Integration Points

### Current Integrations
- **Discord:** DM-based personal assistant
- **MiniMax API:** AI model provider
- **Docker:** Sandboxed execution environment

### Potential Future Integrations
- **n8n:** Workflow automation triggers (not currently configured)
- **Home Assistant:** Smart home control via API
- **Additional chat platforms:** Telegram, Signal, WhatsApp
- **Browser automation skills:** Web scraping, form filling

## Troubleshooting Quick Reference

| Issue | Solution |
|-------|----------|
| Gateway won't start | Check `docker compose logs` for errors; verify .env secrets |
| Discord not connecting | Verify `DISCORD_BOT_TOKEN` and intents enabled |
| "Used disallowed intents" error | Enable Message Content Intent in Discord portal |
| Pairing code not working | Check expiry (1 hour), regenerate if needed |
| High memory usage | Check for stuck browser automation processes |
| MiniMax API errors | Verify `MINIMAX_API_KEY`, check API quota |

## References

- **Official Docs:** https://docs.openclaw.ai/
- **GitHub:** https://github.com/openclaw/openclaw
- **Discord Setup:** https://docs.openclaw.ai/channels/discord
- **MiniMax Provider:** https://docs.openclaw.ai/providers/minimax
- **MiniMax Platform:** https://platform.minimax.io/

## Maintenance Notes

**Update Strategy:**
- Auto-updates: Gateway pulls `:latest` tag on restart
- Breaking changes: Check release notes before updating
- Rollback: Pin specific version tag if needed

**Backup Strategy:**
- Configuration: `openclaw.json` + `.env` (version controlled template)
- Workspace: `/opt/openclaw/workspace` (contains agent memory/files)
- Logs: Optional retention for debugging

**Monitoring:**
- Health check: HTTP endpoint at http://10.10.0.224:18789/health
- Discord connectivity: Verify bot status in server member list
- Resource usage: Monitor via Proxmox dashboard