Skip to content

Architecture

This document describes the technical architecture of the OpenClaw deployment.

High-Level Overview

User → Gateway → Agent Core → Tools/Skills → Response
            ↓
    Session + Memory
            ↓
    External APIs (OpenRouter, GitHub, etc.)

OpenClaw runs as a Kubernetes-native agent with containerized components.

Components

Gateway

Handles incoming messages from multiple channels:

  • Discord — Bot integration via Discord.js
  • WhatsApp — Baileys library for personal account linking
  • Web UI — HTTP interface for browser access

Routes messages to the appropriate session and handles responses back to users.

Agent Core

The central brain of OpenClaw:

  • Session Management — Tracks conversation context per user/channel
  • Tool Selection — Chooses which skills/tools to invoke based on requests
  • LLM Integration — Calls OpenRouter API (Kimi K2.5 default)
  • Response Generation — Formats and sends replies

Chromium Sidecar

A separate container for browser automation:

  • Screenshots of web pages
  • PDF generation
  • Canvas rendering for visual outputs

Runs alongside the main container with dedicated resources (100m-1000m CPU, 256Mi-1Gi RAM).

Persistence

  • PVC — 5Gi volume mounted at ~/.openclaw/workspace/
  • Storage Class — local-path (k3s default)
  • Backup — Workspace synced to git repo periodically

Data Flow

  1. Incoming Message
  2. Gateway receives from Discord/WhatsApp/Web

  3. Identifies session (user + channel)

  4. Context Loading

  5. Session history loaded
  6. Memory files searched for relevant context

  7. SOUL.md and USER.md loaded for persona

  8. Agent Processing

  9. LLM evaluates request
  10. Decides which tools/skills to use

  11. Executes tool calls

  12. Response

  13. Results formatted
  14. Sent back through Gateway
  15. Session state updated

External Integrations

Service Purpose Connection
OpenRouter LLM API HTTPS
Discord API Bot messaging WebSocket/REST
WhatsApp Personal messaging Baileys library
Cloudflare Tunnel Web access Outbound tunnel
n8n Workflow triggers Webhook callbacks

Security Model

  • No direct public exposure — Web UI only via Cloudflare tunnel
  • Private networking — Tailscale mesh for cluster access
  • Credential management — Sealed Secrets for all sensitive data
  • RBAC — Service account with limited k3s permissions
  • Session isolation — Sub-agents run in isolated contexts

File Structure

~/.openclaw/workspace/
├── SOUL.md              # Agent behavior/personality
├── USER.md              # User preferences
├── MEMORY.md            # Long-term curated memory
├── memory/
│   └── YYYY-MM-DD.md    # Daily raw logs
├── personas/
│   └── *.md             # Custom personas
├── skills/              # Custom skills
└── TOOLS.md             # Local infrastructure notes

Deployment Specs

Resource Request Limit
CPU 200m 2000m
RAM 1Gi 4Gi
PVC 5Gi —

Node Selector: Pinned to k3s-master for persistent storage locality.