diff --git a/docs/research/openclaw-architecture-deployment-guide.md b/docs/research/openclaw-architecture-deployment-guide.md new file mode 100644 index 00000000..bbdc544f --- /dev/null +++ b/docs/research/openclaw-architecture-deployment-guide.md @@ -0,0 +1,912 @@ +# 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//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 < ~/.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 < ~/.openclaw/openclaw.json < # 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 # 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*