claude-home/productivity/openclaw/CONTEXT.md

title	description	type	domain	tags
OpenClaw AI Assistant Context	Technical context for OpenClaw personal AI assistant on LXC 224. Covers gateway architecture, npm installation, MiniMax M2.1 integration, Discord bot configuration, Homebrew skill dependencies, systemd service management, and security model.	context	productivity	openclaw ai-assistant minimax discord lxc homebrew nodejs systemd

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) Installation Method: npm global installation (not Docker) Status: Active Primary Use: Personal automation, task management, Discord integration

Architecture

Deployment Model

Installation: OpenClaw installed globally via npm on LXC host (not containerized)

• Installed to: /usr/lib/node_modules/openclaw/
• Binary symlink: /usr/bin/openclaw -> ../lib/node_modules/openclaw/openclaw.mjs
• Service management: systemd user service (openclaw-gateway.service)
• Running as: root user (PID varies, check with ps aux | grep openclaw-gateway)

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 for skill code execution
3. Persistent Workspace - ~/.openclaw/ for configuration, agents, and memory
4. Configuration Layer - ~/.openclaw/openclaw.json + environment variables

System Users and Package Management

User Accounts

• root: System administration, Docker operations, service management
• openclaw: Non-root user for Homebrew package management (UID 1000)
  • Member of sudo and docker groups
  • Password: openclaw
  • Home directory: /home/openclaw

Homebrew Installation

OpenClaw skills often depend on system binaries distributed via Homebrew. Following OpenClaw's official recommendations, Homebrew is installed for the openclaw user.

Location: /home/linuxbrew/.linuxbrew/ User: openclaw (non-root, as required by Homebrew)

Critical: Homebrew Wrapper for Root Access

Since OpenClaw gateway runs as root but Homebrew refuses to run as root, we use a transparent wrapper:

• Real brew binary: /home/linuxbrew/.linuxbrew/bin/brew.real
• Wrapper script: /home/linuxbrew/.linuxbrew/bin/brew
• Behavior: When root runs brew, wrapper automatically delegates to openclaw user
• Result: OpenClaw can auto-install skill dependencies without "running as root" errors

Usage Patterns:

# OpenClaw auto-installs skill dependencies (uses wrapper automatically)
# No manual intervention needed when installing skills from web UI

# Manual installation as root (uses wrapper)
brew install <package>
brew list

# Manual installation as openclaw user (direct)
su - openclaw
brew install <package>
brew list

# Legacy helper script (still available)
brew-as-openclaw install <package>

Helper Script: /usr/local/bin/brew-as-openclaw

• Legacy wrapper script for explicit openclaw user delegation
• Still available but unnecessary due to transparent wrapper at brew binary location
• Usage: brew-as-openclaw <command> [args]

PATH Configuration:

• System-wide: /etc/profile.d/homebrew.sh adds Homebrew to PATH
• User-specific: openclaw user's ~/.bashrc includes Homebrew shellenv
• Binaries available at /home/linuxbrew/.linuxbrew/bin/
• All users can access Homebrew-installed binaries

Package Management Strategy

1. System packages: Install via apt as root (Docker, git, curl, etc.)
2. Skill dependencies: Install via Homebrew as openclaw user
3. Node packages: Install via npm within OpenClaw workspace

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

Process Isolation

• Gateway Process: Runs as root user on LXC host (systemd service)
• Skill Execution: Code sandboxed in Docker containers spawned by gateway
• Docker Access: Gateway has access to Docker socket for skill sandboxing
• Container Isolation: Skills run in isolated containers, not on host

Secrets Management

• Storage: ~/.openclaw/openclaw.json (JSON5 format)
• Environment Variables: Can be referenced via ${VAR_NAME} syntax
• Credentials Directory: ~/.openclaw/credentials/ for sensitive data
• Permissions: Files owned by root (gateway user)

Network Security

• Exposed Ports: 18789 (gateway web UI) accessible on LXC network
• Outbound: Requires internet access for AI API calls (MiniMax, etc.)
• LXC Network: 10.10.0.224 on internal homelab network
• Discord: WebSocket connection to Discord API for bot integration

Operational Patterns

Standard Operations

# Start OpenClaw gateway
openclaw gateway start

# Stop OpenClaw gateway
openclaw gateway stop

# Restart gateway (picks up config changes)
openclaw gateway restart

# Check service status
systemctl --user status openclaw-gateway.service
ps aux | grep openclaw-gateway

Viewing Logs

# Follow gateway logs
journalctl --user -u openclaw-gateway.service -f

# View recent logs
journalctl --user -u openclaw-gateway.service -n 100

# Check startup logs
journalctl --user -u openclaw-gateway.service --since "10 minutes ago"

Pairing Management

# List pending pairing requests
openclaw pairing list discord

# Approve pairing
openclaw pairing approve discord <code>

# Revoke access
openclaw pairing revoke discord <user_id>

Diagnostics

# Full system health check
openclaw doctor

# Channel status (Discord, etc.)
openclaw channels status --probe

# Model configuration
openclaw models list
openclaw models get minimax/MiniMax-M2.1

# Check which user is running gateway
ps aux | grep openclaw-gateway | grep -v grep

Configuration Updates

# Edit configuration
nano ~/.openclaw/openclaw.json

# Restart to apply changes
openclaw gateway restart

# Verify changes via logs
journalctl --user -u openclaw-gateway.service -n 50 | grep -i "config\|error"

# Check if gateway is running
ps aux | grep openclaw-gateway | grep -v grep

Skills Management

OpenClaw skills extend the assistant's capabilities with specialized tools and integrations.

Skill Installation Methods:

1. ClawHub Registry (recommended):

   # SSH to LXC as openclaw user
   ssh openclaw@10.10.0.224
   cd /opt/openclaw/workspace
   
   # Install specific skill
   clawhub install <skill-slug>
   
   # Sync all configured skills
   clawhub sync --all
   
   # Update existing skills
   clawhub update --all
   

2. Manual Installation:

   # Create skill directory
   mkdir -p /opt/openclaw/workspace/skills/<skill-name>
   
   # Create SKILL.md file
   nano /opt/openclaw/workspace/skills/<skill-name>/SKILL.md
   

Skill Locations (priority order):

1. /opt/openclaw/workspace/skills/ (workspace skills, highest priority)
2. ~/.openclaw/skills/ (user skills, shared across agents)
3. Bundled skills (shipped with OpenClaw)

Installing Skill Dependencies:

Many skills require system binaries. Install dependencies using Homebrew:

# From root shell on LXC
brew-as-openclaw install jq          # JSON processing
brew-as-openclaw install ffmpeg      # Media processing
brew-as-openclaw install imagemagick # Image manipulation

# Or as openclaw user
su - openclaw
brew install <package-name>

Enabling Skills:

Configure in openclaw.json:

{
  "skills": {
    "entries": {
      "skill-name": {
        "enabled": true,
        "apiKey": "${SKILL_API_KEY}",  // If needed
        "env": {
          "CUSTOM_VAR": "value"
        }
      }
    }
  }
}

Security Note: Always review third-party skill code before enabling. Skills run with full OpenClaw privileges.

Common Skills:

• browser - Web automation via Playwright
• shell - Execute shell commands in sandbox
• file-manager - Advanced file operations
• code-editor - Code editing and refactoring
• git - Git repository operations

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