913 lines
30 KiB
Markdown
913 lines
30 KiB
Markdown
# OpenClaw Architecture, Deployment Modes, and Ollama Integration
|
|
|
|
## Research Report for Timmy Time Dashboard Project
|
|
|
|
**Issue:** #721 — [Kimi Research] OpenClaw architecture, deployment modes, and Ollama integration
|
|
**Date:** 2026-03-21
|
|
**Author:** Kimi (Moonshot AI)
|
|
**Status:** Complete
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
OpenClaw is an open-source AI agent framework that bridges messaging platforms (WhatsApp, Telegram, Slack, Discord, iMessage) to AI coding agents through a centralized gateway. Originally known as Clawdbot and Moltbot, it was rebranded to OpenClaw in early 2026. This report provides a comprehensive analysis of OpenClaw's architecture, deployment options, Ollama integration capabilities, and suitability for deployment on resource-constrained VPS environments like the Hermes DigitalOcean droplet (2GB RAM / 1 vCPU).
|
|
|
|
**Key Finding:** Running OpenClaw with local LLMs on a 2GB RAM VPS is **not recommended**. The absolute minimum for a text-only agent with external API models is 4GB RAM. For local model inference via Ollama, 8-16GB RAM is the practical minimum. A hybrid approach using OpenRouter as the primary provider with Ollama as fallback is the most viable configuration for small VPS deployments.
|
|
|
|
---
|
|
|
|
## 1. Architecture Overview
|
|
|
|
### 1.1 Core Components
|
|
|
|
OpenClaw follows a **hub-and-spoke (轴辐式)** architecture optimized for multi-agent task execution:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ OPENCLAW ARCHITECTURE │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ WhatsApp │ │ Telegram │ │ Discord │ │
|
|
│ │ Channel │ │ Channel │ │ Channel │ │
|
|
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
|
│ │ │ │ │
|
|
│ └────────────────────┼────────────────────┘ │
|
|
│ ▼ │
|
|
│ ┌──────────────────┐ │
|
|
│ │ Gateway │◄─────── WebSocket/API │
|
|
│ │ (Port 18789) │ Control Plane │
|
|
│ └────────┬─────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────┼──────────────┐ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Agent A │ │ Agent B │ │ Pi Agent│ │
|
|
│ │ (main) │ │ (coder) │ │(delegate)│ │
|
|
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
|
│ │ │ │ │
|
|
│ └──────────────┼──────────────┘ │
|
|
│ ▼ │
|
|
│ ┌────────────────────────┐ │
|
|
│ │ LLM Router │ │
|
|
│ │ (Primary/Fallback) │ │
|
|
│ └───────────┬────────────┘ │
|
|
│ │ │
|
|
│ ┌─────────────────┼─────────────────┐ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ Ollama │ │ OpenAI │ │Anthropic│ │
|
|
│ │(local) │ │(cloud) │ │(cloud) │ │
|
|
│ └─────────┘ └─────────┘ └─────────┘ │
|
|
│ │ ┌─────┐ │
|
|
│ └────────────────────────────────────────────────────►│ MCP │ │
|
|
│ │Tools│ │
|
|
│ └─────┘ │
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Memory │ │ Skills │ │ Workspace │ │
|
|
│ │ (SOUL.md) │ │ (SKILL.md) │ │ (sessions) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.2 Component Deep Dive
|
|
|
|
| Component | Purpose | Configuration File |
|
|
|-----------|---------|-------------------|
|
|
| **Gateway** | Central control plane, WebSocket/API server, session management | `gateway` section in `openclaw.json` |
|
|
| **Pi Agent** | Core agent runner, "指挥中心" - schedules LLM calls, tool execution, error handling | `agents` section in `openclaw.json` |
|
|
| **Channels** | Messaging platform integrations (Telegram, WhatsApp, Slack, Discord, iMessage) | `channels` section in `openclaw.json` |
|
|
| **SOUL.md** | Agent persona definition - personality, communication style, behavioral guidelines | `~/.openclaw/workspace/SOUL.md` |
|
|
| **AGENTS.md** | Multi-agent configuration, routing rules, agent specialization definitions | `~/.openclaw/workspace/AGENTS.md` |
|
|
| **Workspace** | File system for agent state, session data, temporary files | `~/.openclaw/workspace/` |
|
|
| **Skills** | Bundled tools, prompts, configurations that teach agents specific tasks | `~/.openclaw/workspace/skills/` |
|
|
| **Sessions** | Conversation history, context persistence between interactions | `~/.openclaw/agents/<agent>/sessions/` |
|
|
| **MCP Tools** | Model Context Protocol integration for external tool access | Via `mcporter` or native MCP |
|
|
|
|
### 1.3 Agent Runner Execution Flow
|
|
|
|
According to OpenClaw documentation, a complete agent run follows these stages:
|
|
|
|
1. **Queuing** - Session-level queue (serializes same-session requests) → Global queue (controls total concurrency)
|
|
2. **Preparation** - Parse workspace, provider/model, thinking level parameters
|
|
3. **Plugin Loading** - Load relevant skills based on task context
|
|
4. **Memory Retrieval** - Fetch relevant context from SOUL.md and conversation history
|
|
5. **LLM Inference** - Send prompt to configured provider with tool definitions
|
|
6. **Tool Execution** - Execute any tool calls returned by the LLM
|
|
7. **Response Generation** - Format and return final response to the channel
|
|
8. **Memory Storage** - Persist conversation and results to session storage
|
|
|
|
---
|
|
|
|
## 2. Deployment Modes
|
|
|
|
### 2.1 Comparison Matrix
|
|
|
|
| Deployment Mode | Best For | Setup Complexity | Resource Overhead | Stability |
|
|
|----------------|----------|------------------|-------------------|-----------|
|
|
| **npm global** | Development, quick testing | Low | Minimal (~200MB) | Moderate |
|
|
| **Docker** | Production, isolation, reproducibility | Medium | Higher (~2.5GB base image) | High |
|
|
| **Docker Compose** | Multi-service stacks, complex setups | Medium-High | Higher | High |
|
|
| **Bare metal/systemd** | Maximum performance, dedicated hardware | High | Minimal | Moderate |
|
|
|
|
### 2.2 NPM Global Installation (Recommended for Quick Start)
|
|
|
|
```bash
|
|
# One-line installer
|
|
curl -fsSL https://openclaw.ai/install.sh | bash
|
|
|
|
# Or manual npm install
|
|
npm install -g openclaw
|
|
|
|
# Initialize configuration
|
|
openclaw onboard
|
|
|
|
# Start gateway
|
|
openclaw gateway
|
|
```
|
|
|
|
**Pros:**
|
|
- Fastest setup (~30 seconds)
|
|
- Direct access to host resources
|
|
- Easy updates via `npm update -g openclaw`
|
|
|
|
**Cons:**
|
|
- Node.js 22+ dependency required
|
|
- No process isolation
|
|
- Manual dependency management
|
|
|
|
### 2.3 Docker Deployment (Recommended for Production)
|
|
|
|
```bash
|
|
# Pull and run
|
|
docker pull openclaw/openclaw:latest
|
|
docker run -d \
|
|
--name openclaw \
|
|
-p 127.0.0.1:18789:18789 \
|
|
-v ~/.openclaw:/root/.openclaw \
|
|
-e ANTHROPIC_API_KEY=sk-ant-... \
|
|
openclaw/openclaw:latest
|
|
|
|
# Or with Docker Compose
|
|
docker compose -f compose.yml --env-file .env up -d --build
|
|
```
|
|
|
|
**Docker Compose Configuration (production-ready):**
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
services:
|
|
openclaw:
|
|
image: openclaw/openclaw:latest
|
|
container_name: openclaw
|
|
restart: unless-stopped
|
|
ports:
|
|
- "127.0.0.1:18789:18789" # Never expose to 0.0.0.0
|
|
volumes:
|
|
- ./openclaw-data:/root/.openclaw
|
|
- ./workspace:/root/.openclaw/workspace
|
|
environment:
|
|
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
|
|
- OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
|
|
- OLLAMA_API_KEY=ollama-local
|
|
networks:
|
|
- openclaw-net
|
|
# Resource limits for small VPS
|
|
deploy:
|
|
resources:
|
|
limits:
|
|
cpus: '1.5'
|
|
memory: 3G
|
|
reservations:
|
|
cpus: '0.5'
|
|
memory: 1G
|
|
|
|
networks:
|
|
openclaw-net:
|
|
driver: bridge
|
|
```
|
|
|
|
### 2.4 Bare Metal / Systemd Installation
|
|
|
|
For running as a system service on Linux:
|
|
|
|
```bash
|
|
# Create systemd service
|
|
sudo tee /etc/systemd/system/openclaw.service > /dev/null <<EOF
|
|
[Unit]
|
|
Description=OpenClaw Gateway
|
|
After=network.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=openclaw
|
|
Group=openclaw
|
|
WorkingDirectory=/home/openclaw
|
|
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
|
|
Environment="NODE_ENV=production"
|
|
Environment="ANTHROPIC_API_KEY=sk-ant-..."
|
|
ExecStart=/usr/local/bin/openclaw gateway
|
|
Restart=always
|
|
RestartSec=10
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
EOF
|
|
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable openclaw
|
|
sudo systemctl start openclaw
|
|
```
|
|
|
|
### 2.5 Recommended Deployment for 2GB RAM VPS
|
|
|
|
**⚠️ Critical Finding:** OpenClaw's official minimum is 4GB RAM. On a 2GB VPS:
|
|
|
|
1. **Do NOT run local LLMs** - Use external API providers exclusively
|
|
2. **Use npm installation** - Docker overhead is too heavy
|
|
3. **Disable browser automation** - Chromium requires 2-4GB alone
|
|
4. **Enable swap** - Critical for preventing OOM kills
|
|
5. **Use OpenRouter** - Cheap/free tier models reduce costs
|
|
|
|
**Setup script for 2GB VPS:**
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# openclaw-minimal-vps.sh
|
|
# Setup for 2GB RAM VPS - EXTERNAL API ONLY
|
|
|
|
# Create 4GB swap
|
|
sudo fallocate -l 4G /swapfile
|
|
sudo chmod 600 /swapfile
|
|
sudo mkswap /swapfile
|
|
sudo swapon /swapfile
|
|
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
|
|
|
|
# Install Node.js 22
|
|
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
|
|
sudo apt-get install -y nodejs
|
|
|
|
# Install OpenClaw
|
|
npm install -g openclaw
|
|
|
|
# Configure for minimal resource usage
|
|
mkdir -p ~/.openclaw
|
|
cat > ~/.openclaw/openclaw.json <<'EOF'
|
|
{
|
|
"gateway": {
|
|
"bind": "127.0.0.1",
|
|
"port": 18789,
|
|
"mode": "local"
|
|
},
|
|
"agents": {
|
|
"defaults": {
|
|
"model": {
|
|
"primary": "openrouter/google/gemma-3-4b-it:free",
|
|
"fallbacks": [
|
|
"openrouter/meta/llama-3.1-8b-instruct:free"
|
|
]
|
|
},
|
|
"maxIterations": 15,
|
|
"timeout": 120
|
|
}
|
|
},
|
|
"channels": {
|
|
"telegram": {
|
|
"enabled": true,
|
|
"dmPolicy": "pairing"
|
|
}
|
|
}
|
|
}
|
|
EOF
|
|
|
|
# Set OpenRouter API key
|
|
export OPENROUTER_API_KEY="sk-or-v1-..."
|
|
|
|
# Start gateway
|
|
openclaw gateway &
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Ollama Integration
|
|
|
|
### 3.1 Architecture
|
|
|
|
OpenClaw integrates with Ollama through its native `/api/chat` endpoint, supporting both streaming responses and tool calling simultaneously:
|
|
|
|
```
|
|
┌──────────────┐ HTTP/JSON ┌──────────────┐ GGUF/CPU/GPU ┌──────────┐
|
|
│ OpenClaw │◄───────────────────►│ Ollama │◄────────────────────►│ Local │
|
|
│ Gateway │ /api/chat │ Server │ Model inference │ LLM │
|
|
│ │ Port 11434 │ Port 11434 │ │ │
|
|
└──────────────┘ └──────────────┘ └──────────┘
|
|
```
|
|
|
|
### 3.2 Configuration
|
|
|
|
**Basic Ollama Setup:**
|
|
|
|
```bash
|
|
# Install Ollama
|
|
curl -fsSL https://ollama.com/install.sh | sh
|
|
|
|
# Start server
|
|
ollama serve
|
|
|
|
# Pull a tool-capable model
|
|
ollama pull qwen2.5-coder:7b
|
|
ollama pull llama3.1:8b
|
|
|
|
# Configure OpenClaw
|
|
export OLLAMA_API_KEY="ollama-local" # Any non-empty string works
|
|
```
|
|
|
|
**OpenClaw Configuration for Ollama:**
|
|
|
|
```json
|
|
{
|
|
"models": {
|
|
"providers": {
|
|
"ollama": {
|
|
"baseUrl": "http://localhost:11434",
|
|
"apiKey": "ollama-local",
|
|
"api": "ollama",
|
|
"models": [
|
|
{
|
|
"id": "qwen2.5-coder:7b",
|
|
"name": "Qwen 2.5 Coder 7B",
|
|
"contextWindow": 32768,
|
|
"maxTokens": 8192,
|
|
"cost": { "input": 0, "output": 0 }
|
|
},
|
|
{
|
|
"id": "llama3.1:8b",
|
|
"name": "Llama 3.1 8B",
|
|
"contextWindow": 128000,
|
|
"maxTokens": 8192,
|
|
"cost": { "input": 0, "output": 0 }
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"agents": {
|
|
"defaults": {
|
|
"model": {
|
|
"primary": "ollama/qwen2.5-coder:7b",
|
|
"fallbacks": ["ollama/llama3.1:8b"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.3 Context Window Requirements
|
|
|
|
**⚠️ Critical Requirement:** OpenClaw requires a minimum **64K token context window** for reliable multi-step task execution.
|
|
|
|
| Model | Parameters | Context Window | Tool Support | OpenClaw Compatible |
|
|
|-------|-----------|----------------|--------------|---------------------|
|
|
| **llama3.1** | 8B | 128K | ✅ Yes | ✅ Yes |
|
|
| **qwen2.5-coder** | 7B | 32K | ✅ Yes | ⚠️ Below minimum |
|
|
| **qwen2.5-coder** | 32B | 128K | ✅ Yes | ✅ Yes |
|
|
| **gpt-oss** | 20B | 128K | ✅ Yes | ✅ Yes |
|
|
| **glm-4.7-flash** | - | 128K | ✅ Yes | ✅ Yes |
|
|
| **deepseek-coder-v2** | 33B | 128K | ✅ Yes | ✅ Yes |
|
|
| **mistral-small3.1** | - | 128K | ✅ Yes | ✅ Yes |
|
|
|
|
**Context Window Configuration:**
|
|
|
|
For models that don't report context window via Ollama's API:
|
|
|
|
```bash
|
|
# Create custom Modelfile with extended context
|
|
cat > ~/qwen-custom.modelfile <<EOF
|
|
FROM qwen2.5-coder:7b
|
|
PARAMETER num_ctx 65536
|
|
PARAMETER temperature 0.7
|
|
EOF
|
|
|
|
# Create custom model
|
|
ollama create qwen2.5-coder-64k -f ~/qwen-custom.modelfile
|
|
```
|
|
|
|
### 3.4 Models for Small VPS (≤8B Parameters)
|
|
|
|
For resource-constrained environments (2-4GB RAM):
|
|
|
|
| Model | Quantization | RAM Required | VRAM Required | Performance |
|
|
|-------|-------------|--------------|---------------|-------------|
|
|
| **Llama 3.1 8B** | Q4_K_M | ~5GB | ~6GB | Good |
|
|
| **Llama 3.2 3B** | Q4_K_M | ~2.5GB | ~3GB | Basic |
|
|
| **Qwen 2.5 7B** | Q4_K_M | ~5GB | ~6GB | Good |
|
|
| **Qwen 2.5 3B** | Q4_K_M | ~2.5GB | ~3GB | Basic |
|
|
| **DeepSeek 7B** | Q4_K_M | ~5GB | ~6GB | Good |
|
|
| **Phi-4 4B** | Q4_K_M | ~3GB | ~4GB | Moderate |
|
|
|
|
**⚠️ Verdict for 2GB VPS:** Running local LLMs is **NOT viable**. Use external APIs only.
|
|
|
|
---
|
|
|
|
## 4. OpenRouter Integration (Fallback Strategy)
|
|
|
|
### 4.1 Overview
|
|
|
|
OpenRouter provides a unified API gateway to multiple LLM providers, enabling:
|
|
- Single API key access to 200+ models
|
|
- Automatic failover between providers
|
|
- Free tier models for cost-conscious deployments
|
|
- Unified billing and usage tracking
|
|
|
|
### 4.2 Configuration
|
|
|
|
**Environment Variable Setup:**
|
|
|
|
```bash
|
|
export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
```
|
|
|
|
**OpenClaw Configuration:**
|
|
|
|
```json
|
|
{
|
|
"models": {
|
|
"providers": {
|
|
"openrouter": {
|
|
"apiKey": "${OPENROUTER_API_KEY}",
|
|
"baseUrl": "https://openrouter.ai/api/v1"
|
|
}
|
|
}
|
|
},
|
|
"agents": {
|
|
"defaults": {
|
|
"model": {
|
|
"primary": "openrouter/anthropic/claude-sonnet-4-6",
|
|
"fallbacks": [
|
|
"openrouter/google/gemini-3.1-pro",
|
|
"openrouter/meta/llama-3.3-70b-instruct",
|
|
"openrouter/google/gemma-3-4b-it:free"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.3 Recommended Free/Cheap Models on OpenRouter
|
|
|
|
For cost-conscious VPS deployments:
|
|
|
|
| Model | Cost | Context | Best For |
|
|
|-------|------|---------|----------|
|
|
| **google/gemma-3-4b-it:free** | Free | 128K | General tasks, simple automation |
|
|
| **meta/llama-3.1-8b-instruct:free** | Free | 128K | General tasks, longer contexts |
|
|
| **deepseek/deepseek-chat-v3.2** | $0.53/M | 64K | Code generation, reasoning |
|
|
| **xiaomi/mimo-v2-flash** | $0.40/M | 128K | Fast responses, basic tasks |
|
|
| **qwen/qwen3-coder-next** | $1.20/M | 128K | Code-focused tasks |
|
|
|
|
### 4.4 Hybrid Configuration (Recommended for Timmy)
|
|
|
|
A production-ready configuration for the Hermes VPS:
|
|
|
|
```json
|
|
{
|
|
"models": {
|
|
"providers": {
|
|
"openrouter": {
|
|
"apiKey": "${OPENROUTER_API_KEY}",
|
|
"models": [
|
|
{
|
|
"id": "google/gemma-3-4b-it:free",
|
|
"name": "Gemma 3 4B (Free)",
|
|
"contextWindow": 131072,
|
|
"maxTokens": 8192,
|
|
"cost": { "input": 0, "output": 0 }
|
|
},
|
|
{
|
|
"id": "deepseek/deepseek-chat-v3.2",
|
|
"name": "DeepSeek V3.2",
|
|
"contextWindow": 64000,
|
|
"maxTokens": 8192,
|
|
"cost": { "input": 0.00053, "output": 0.00053 }
|
|
}
|
|
]
|
|
},
|
|
"ollama": {
|
|
"baseUrl": "http://localhost:11434",
|
|
"apiKey": "ollama-local",
|
|
"models": [
|
|
{
|
|
"id": "llama3.2:3b",
|
|
"name": "Llama 3.2 3B (Local Fallback)",
|
|
"contextWindow": 128000,
|
|
"maxTokens": 4096,
|
|
"cost": { "input": 0, "output": 0 }
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"agents": {
|
|
"defaults": {
|
|
"model": {
|
|
"primary": "openrouter/google/gemma-3-4b-it:free",
|
|
"fallbacks": [
|
|
"openrouter/deepseek/deepseek-chat-v3.2",
|
|
"ollama/llama3.2:3b"
|
|
]
|
|
},
|
|
"maxIterations": 10,
|
|
"timeout": 90
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Hardware Constraints & VPS Viability
|
|
|
|
### 5.1 System Requirements Summary
|
|
|
|
| Component | Minimum | Recommended | Notes |
|
|
|-----------|---------|-------------|-------|
|
|
| **CPU** | 2 vCPU | 4 vCPU | Dedicated preferred over shared |
|
|
| **RAM** | 4 GB | 8 GB | 2GB causes OOM with external APIs |
|
|
| **Storage** | 40 GB SSD | 80 GB NVMe | Docker images are ~10-15GB |
|
|
| **Network** | 100 Mbps | 1 Gbps | For API calls and model downloads |
|
|
| **OS** | Ubuntu 22.04/Debian 12 | Ubuntu 24.04 LTS | Linux required for production |
|
|
|
|
### 5.2 2GB RAM VPS Analysis
|
|
|
|
**Can it work?** Yes, with severe limitations:
|
|
|
|
✅ **What works:**
|
|
- Text-only agents with external API providers
|
|
- Single Telegram/Discord channel
|
|
- Basic file operations and shell commands
|
|
- No browser automation
|
|
|
|
❌ **What doesn't work:**
|
|
- Local LLM inference via Ollama
|
|
- Browser automation (Chromium needs 2-4GB)
|
|
- Multiple concurrent channels
|
|
- Python environment-heavy skills
|
|
|
|
**Required mitigations for 2GB VPS:**
|
|
|
|
```bash
|
|
# 1. Create substantial swap
|
|
sudo fallocate -l 4G /swapfile
|
|
sudo chmod 600 /swapfile
|
|
sudo mkswap /swapfile
|
|
sudo swapon /swapfile
|
|
|
|
# 2. Configure swappiness
|
|
echo 'vm.swappiness=60' | sudo tee -a /etc/sysctl.conf
|
|
sudo sysctl -p
|
|
|
|
# 3. Limit Node.js memory
|
|
export NODE_OPTIONS="--max-old-space-size=1536"
|
|
|
|
# 4. Use external APIs only - NO OLLAMA
|
|
# 5. Disable browser skills
|
|
# 6. Set conservative concurrency limits
|
|
```
|
|
|
|
### 5.3 4-bit Quantization Viability
|
|
|
|
**Qwen 2.5 7B Q4_K_M on 2GB VPS:**
|
|
- Model size: ~4.5GB
|
|
- RAM required at runtime: ~5-6GB
|
|
- **Verdict:** Will cause immediate OOM on 2GB VPS
|
|
- **Even with 4GB VPS:** Marginal, heavy swap usage, poor performance
|
|
|
|
**Viable models for 4GB VPS with Ollama:**
|
|
- Llama 3.2 3B Q4_K_M (~2.5GB RAM)
|
|
- Qwen 2.5 3B Q4_K_M (~2.5GB RAM)
|
|
- Phi-4 4B Q4_K_M (~3GB RAM)
|
|
|
|
---
|
|
|
|
## 6. Security Configuration
|
|
|
|
### 6.1 Network Ports
|
|
|
|
| Port | Purpose | Exposure |
|
|
|------|---------|----------|
|
|
| **18789/tcp** | OpenClaw Gateway (WebSocket/HTTP) | **NEVER expose to internet** |
|
|
| **11434/tcp** | Ollama API (if running locally) | Localhost only |
|
|
| **22/tcp** | SSH | Restrict to known IPs |
|
|
|
|
**⚠️ CRITICAL:** Never expose port 18789 to the public internet. Use Tailscale or SSH tunnels for remote access.
|
|
|
|
### 6.2 Tailscale Integration
|
|
|
|
Tailscale provides zero-configuration VPN mesh for secure remote access:
|
|
|
|
```bash
|
|
# Install Tailscale
|
|
curl -fsSL https://tailscale.com/install.sh | sh
|
|
sudo tailscale up
|
|
|
|
# Get Tailscale IP
|
|
tailscale ip
|
|
# Returns: 100.x.y.z
|
|
|
|
# Configure OpenClaw to bind to Tailscale
|
|
cat > ~/.openclaw/openclaw.json <<EOF
|
|
{
|
|
"gateway": {
|
|
"bind": "tailnet",
|
|
"port": 18789
|
|
},
|
|
"tailscale": {
|
|
"mode": "on",
|
|
"resetOnExit": false
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
**Tailscale vs SSH Tunnel:**
|
|
|
|
| Feature | Tailscale | SSH Tunnel |
|
|
|---------|-----------|------------|
|
|
| Setup | Very easy | Moderate |
|
|
| Persistence | Automatic | Requires autossh |
|
|
| Multiple devices | Built-in | One tunnel per connection |
|
|
| NAT traversal | Works | Requires exposed SSH |
|
|
| Access control | Tailscale ACL | SSH keys |
|
|
|
|
### 6.3 Firewall Configuration (UFW)
|
|
|
|
```bash
|
|
# Default deny
|
|
sudo ufw default deny incoming
|
|
sudo ufw default allow outgoing
|
|
|
|
# Allow SSH
|
|
sudo ufw allow 22/tcp
|
|
|
|
# Allow Tailscale only (if using)
|
|
sudo ufw allow in on tailscale0 to any port 18789
|
|
|
|
# Block public access to OpenClaw
|
|
# (bind is 127.0.0.1, so this is defense in depth)
|
|
|
|
sudo ufw enable
|
|
```
|
|
|
|
### 6.4 Authentication Configuration
|
|
|
|
```json
|
|
{
|
|
"gateway": {
|
|
"bind": "127.0.0.1",
|
|
"port": 18789,
|
|
"auth": {
|
|
"mode": "token",
|
|
"token": "your-64-char-hex-token-here"
|
|
},
|
|
"controlUi": {
|
|
"allowedOrigins": [
|
|
"http://localhost:18789",
|
|
"https://your-domain.tailnet-name.ts.net"
|
|
],
|
|
"allowInsecureAuth": false,
|
|
"dangerouslyDisableDeviceAuth": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Generate secure token:**
|
|
|
|
```bash
|
|
openssl rand -hex 32
|
|
```
|
|
|
|
### 6.5 Sandboxing Considerations
|
|
|
|
OpenClaw executes arbitrary shell commands and file operations by default. For production:
|
|
|
|
1. **Run as non-root user:**
|
|
```bash
|
|
sudo useradd -r -s /bin/false openclaw
|
|
sudo mkdir -p /home/openclaw/.openclaw
|
|
sudo chown -R openclaw:openclaw /home/openclaw
|
|
```
|
|
|
|
2. **Use Docker for isolation:**
|
|
```bash
|
|
docker run --security-opt=no-new-privileges \
|
|
--cap-drop=ALL \
|
|
--read-only \
|
|
--tmpfs /tmp:noexec,nosuid,size=100m \
|
|
openclaw/openclaw:latest
|
|
```
|
|
|
|
3. **Enable dmPolicy for channels:**
|
|
```json
|
|
{
|
|
"channels": {
|
|
"telegram": {
|
|
"dmPolicy": "pairing" // Require one-time code for new contacts
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. MCP (Model Context Protocol) Tools
|
|
|
|
### 7.1 Overview
|
|
|
|
MCP is an open standard created by Anthropic (donated to Linux Foundation in Dec 2025) that lets AI applications connect to external tools through a universal interface. Think of it as "USB-C for AI."
|
|
|
|
### 7.2 MCP vs OpenClaw Skills
|
|
|
|
| Aspect | MCP | OpenClaw Skills |
|
|
|--------|-----|-----------------|
|
|
| **Protocol** | Standardized (Anthropic) | OpenClaw-specific |
|
|
| **Isolation** | Process-isolated | Runs in agent context |
|
|
| **Security** | Higher (sandboxed) | Lower (full system access) |
|
|
| **Discovery** | Automatic via protocol | Manual via SKILL.md |
|
|
| **Ecosystem** | 10,000+ servers | 5400+ skills |
|
|
|
|
**Note:** OpenClaw currently has limited native MCP support. Use `mcporter` tool for MCP integration.
|
|
|
|
### 7.3 Using MCPorter (MCP Bridge)
|
|
|
|
```bash
|
|
# Install mcporter
|
|
clawhub install mcporter
|
|
|
|
# Configure MCP server
|
|
mcporter config add github \
|
|
--url "https://api.github.com/mcp" \
|
|
--token "ghp_..."
|
|
|
|
# List available tools
|
|
mcporter list
|
|
|
|
# Call MCP tool
|
|
mcporter call github.list_repos --owner "rockachopa"
|
|
```
|
|
|
|
### 7.4 Popular MCP Servers
|
|
|
|
| Server | Purpose | Integration |
|
|
|--------|---------|-------------|
|
|
| **GitHub** | Repo management, PRs, issues | `mcp-github` |
|
|
| **Slack** | Messaging, channel management | `mcp-slack` |
|
|
| **PostgreSQL** | Database queries | `mcp-postgres` |
|
|
| **Filesystem** | File operations (sandboxed) | `mcp-filesystem` |
|
|
| **Brave Search** | Web search | `mcp-brave` |
|
|
|
|
---
|
|
|
|
## 8. Recommendations for Timmy Time Dashboard
|
|
|
|
### 8.1 Deployment Strategy for Hermes VPS (2GB RAM)
|
|
|
|
Given the hardware constraints, here's the recommended approach:
|
|
|
|
**Option A: External API Only (Recommended)**
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ Hermes VPS (2GB RAM) │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ OpenClaw Gateway │ │
|
|
│ │ (npm global install) │ │
|
|
│ └─────────────┬───────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ OpenRouter API (Free Tier) │ │
|
|
│ │ google/gemma-3-4b-it:free │ │
|
|
│ └─────────────────────────────────┘ │
|
|
│ │
|
|
│ NO OLLAMA - insufficient RAM │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
**Option B: Hybrid with External Ollama**
|
|
```
|
|
┌──────────────────────┐ ┌──────────────────────────┐
|
|
│ Hermes VPS (2GB) │ │ Separate Ollama Host │
|
|
│ ┌────────────────┐ │ │ ┌────────────────────┐ │
|
|
│ │ OpenClaw │ │◄────►│ │ Ollama Server │ │
|
|
│ │ (external API) │ │ │ │ (8GB+ RAM required)│ │
|
|
│ └────────────────┘ │ │ └────────────────────┘ │
|
|
└──────────────────────┘ └──────────────────────────┘
|
|
```
|
|
|
|
### 8.2 Configuration Summary
|
|
|
|
```json
|
|
{
|
|
"gateway": {
|
|
"bind": "127.0.0.1",
|
|
"port": 18789,
|
|
"auth": {
|
|
"mode": "token",
|
|
"token": "GENERATE_WITH_OPENSSL_RAND"
|
|
}
|
|
},
|
|
"models": {
|
|
"providers": {
|
|
"openrouter": {
|
|
"apiKey": "${OPENROUTER_API_KEY}",
|
|
"models": [
|
|
{
|
|
"id": "google/gemma-3-4b-it:free",
|
|
"contextWindow": 131072,
|
|
"maxTokens": 4096
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"agents": {
|
|
"defaults": {
|
|
"model": {
|
|
"primary": "openrouter/google/gemma-3-4b-it:free"
|
|
},
|
|
"maxIterations": 10,
|
|
"timeout": 90,
|
|
"maxConcurrent": 2
|
|
}
|
|
},
|
|
"channels": {
|
|
"telegram": {
|
|
"enabled": true,
|
|
"dmPolicy": "pairing"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 8.3 Migration Path (Future)
|
|
|
|
When upgrading to a larger VPS (4-8GB RAM):
|
|
|
|
1. **Phase 1:** Enable Ollama with Llama 3.2 3B as fallback
|
|
2. **Phase 2:** Add browser automation skills (requires 4GB+ RAM)
|
|
3. **Phase 3:** Enable multi-agent routing with specialized agents
|
|
4. **Phase 4:** Add MCP server integration for external tools
|
|
|
|
---
|
|
|
|
## 9. References
|
|
|
|
1. OpenClaw Official Documentation: https://docs.openclaw.ai
|
|
2. Ollama Integration Guide: https://docs.ollama.com/integrations/openclaw
|
|
3. OpenRouter Documentation: https://openrouter.ai/docs
|
|
4. MCP Specification: https://modelcontextprotocol.io
|
|
5. OpenClaw Community Discord: https://discord.gg/openclaw
|
|
6. GitHub Repository: https://github.com/openclaw/openclaw
|
|
|
|
---
|
|
|
|
## 10. Appendix: Quick Command Reference
|
|
|
|
```bash
|
|
# Installation
|
|
curl -fsSL https://openclaw.ai/install.sh | bash
|
|
|
|
# Configuration
|
|
openclaw onboard # Interactive setup
|
|
openclaw configure # Edit config
|
|
openclaw config set <key> <value> # Set specific value
|
|
|
|
# Gateway management
|
|
openclaw gateway # Start gateway
|
|
openclaw gateway --verbose # Start with logs
|
|
openclaw gateway status # Check status
|
|
openclaw gateway restart # Restart gateway
|
|
openclaw gateway stop # Stop gateway
|
|
|
|
# Model management
|
|
openclaw models list # List available models
|
|
openclaw models set <model> # Set default model
|
|
openclaw models status # Check model status
|
|
|
|
# Diagnostics
|
|
openclaw doctor # System health check
|
|
openclaw doctor --repair # Auto-fix issues
|
|
openclaw security audit # Security check
|
|
|
|
# Dashboard
|
|
openclaw dashboard # Open web UI
|
|
```
|
|
|
|
---
|
|
|
|
*End of Research Report*
|