System Overview

OpenClaw's architecture is designed for flexibility, security, and extensibility. This article provides an in-depth look at how the system processes requests from user input to action execution.

Core Components

┌─────────────────────────────────────────────────────────────────┐
│                        OpenClaw Runtime                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  Message    │  │   Context   │  │      Tool Executor      │ │
│  │  Router     │  │   Manager   │  │                         │ │
│  │             │  │             │  │  ┌─────┐ ┌─────┐ ┌────┐ │ │
│  │  WhatsApp ──┤  │  Memory ────┤  │  │Shell│ │Files│ │API │ │ │
│  │  Telegram ──┤  │  Bootstrap ─┤  │  └─────┘ └─────┘ └────┘ │ │
│  │  Discord ───┤  │  Session ───┤  │                         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
│         │                │                      ▲               │
│         ▼                ▼                      │               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    LLM Interface                         │   │
│  │   ┌─────────┐  ┌─────────────┐  ┌────────────────────┐  │   │
│  │   │ OpenAI  │  │  Anthropic  │  │  Local (Ollama)    │  │   │
│  │   └─────────┘  └─────────────┘  └────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Request Processing Flow

1. Message Ingestion

When a user sends a message:

// Message arrives via platform adapter
{
  platform: 'telegram',
  userId: '12345',
  messageId: 'msg_001',
  content: 'Send an email to john about the meeting',
  timestamp: 1706400000
}

2. Context Assembly

The Context Manager builds the complete context:

const context = {
  // Bootstrap files
  system: loadBootstrapFiles(),
  
  // Conversation history
  history: getConversationHistory(userId),
  
  // Available tools
  tools: mcp.listTools(),
  
  // Current request
  userMessage: message.content
};

3. LLM Processing

The assembled context is sent to the LLM:

const response = await llm.complete({
  messages: [
    { role: 'system', content: context.system },
    ...context.history,
    { role: 'user', content: context.userMessage }
  ],
  tools: context.tools,
  tool_choice: 'auto'
});

4. Tool Execution

If the LLM requests tool use:

// LLM response includes tool calls
{
  content: "I'll send that email for you.",
  tool_calls: [{
    id: 'call_001',
    name: 'gmail_send',
    arguments: {
      to: '[email protected]',
      subject: 'Meeting Update',
      body: '...'
    }
  }]
}

// Tool Executor processes each call
for (const call of response.tool_calls) {
  const result = await toolExecutor.run(call);
  context.history.push({
    role: 'tool',
    tool_call_id: call.id,
    content: JSON.stringify(result)
  });
}

5. Response Synthesis

After tool execution, the LLM synthesizes the final response:

// Final response to user
{
  content: "✅ Email sent to [email protected] with subject 'Meeting Update'"
}

Memory Architecture

Short-term Memory

Maintains current conversation context:

class ShortTermMemory {
  private messages: Message[] = [];
  private maxTokens: number = 8000;
  
  add(message: Message) {
    this.messages.push(message);
    this.prune(); // Keep within token limit
  }
}

Long-term Memory

Persistent storage for cross-session knowledge:

class LongTermMemory {
  // Vector store for semantic search
  private vectorStore: VectorDB;
  
  // Structured storage for facts
  private factStore: KeyValueStore;
  
  async remember(content: string, metadata: object) {
    const embedding = await embed(content);
    await this.vectorStore.upsert(embedding, content, metadata);
  }
  
  async recall(query: string, limit: number = 5) {
    const embedding = await embed(query);
    return this.vectorStore.search(embedding, limit);
  }
}

Tool Execution Engine

Sandboxing

Tools execute in isolated environments:

class ToolSandbox {
  // Resource limits
  maxMemory: '512MB',
  maxCPU: '50%',
  timeout: 30000,
  
  // Filesystem restrictions
  allowedPaths: ['/workspace', '/tmp'],
  deniedPaths: ['/etc', '/var', '/usr'],
  
  // Network restrictions
  allowedHosts: ['api.github.com', 'smtp.gmail.com'],
  deniedPorts: [22, 23, 3389]
}

Execution Flow

async executeTool(call: ToolCall): Promise {
  // 1. Validate permissions
  if (!this.checkPermissions(call)) {
    return { error: 'Permission denied' };
  }
  
  // 2. Apply rate limits
  await this.rateLimiter.acquire(call.name);
  
  // 3. Execute in sandbox
  const result = await this.sandbox.run(call);
  
  // 4. Log for audit
  await this.auditLog.record(call, result);
  
  return result;
}

Conclusion

OpenClaw's architecture balances power with safety, enabling sophisticated agent behaviors while maintaining control and auditability. Understanding these internals helps you build more effective and secure agent configurations.