---
title: "OpenClaw AI Assistant Context"
description: "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."
type: context
domain: productivity
tags: [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:**

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# List pending pairing requests
openclaw pairing list discord

# Approve pairing
openclaw pairing approve discord <code>

# Revoke access
openclaw pairing revoke discord <user_id>
```

### Diagnostics
```bash
# 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
```bash
# 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):
   ```bash
   # 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:**
   ```bash
   # 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:

```bash
# 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`:
```json5
{
  "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
