Summary

Split the monolithic openclaw gateway into two components:

1. Control Plane (openclaw-gateway) — lightweight process handling channels, routing, cron scheduling, hooks, dashboard, and agent registry
2. Agent Runtime (openclaw-runtime) — per-agent process running the model loop, context engine, tool execution, MCP servers, and memory

This enables running each agent in its own compute environment (container, microVM, VM, or process) while preserving OpenClaw's unified channel management and agent orchestration.

Motivation

Today, openclaw gateway runs everything in a single Node.js process. All agents share one event loop, one filesystem, one set of MCP server processes, and one failure domain. This works well for 2-3 agents on a single VM, but creates real problems as deployments grow:

Reliability: Restarting the gateway (for config changes, upgrades, or crashes) drops all agents simultaneously — every Telegram connection, every in-flight session, every MCP server. A bug in one agent's MCP server can crash the entire gateway.

Security: Agent isolation is config-level (tool deny lists), not infrastructure-level. Jerry's tools can theoretically access Grif's workspace files. Secrets are shared in the process environment.

Scaling: A compute-heavy agent (Opus with 1M context) competes for CPU with lightweight agents (Haiku heartbeats). There's no way to give one agent more resources without over-provisioning for all.

Operability: You can't upgrade, restart, or debug one agent without affecting the others. You can't run agents in different regions, on different instance types, or with different security profiles.

Proposed Architecture

┌─────────────────────────────────────────────────────┐
│              openclaw-gateway (control plane)        │
│                                                     │
│  ┌──────────┐ ┌──────┐ ┌────────┐ ┌─────────────┐ │
│  │ Channels │ │ Cron │ │ Hooks  │ │  Dashboard  │ │
│  │ Telegram │ │ HB   │ │ HTTP   │ │  Control UI │ │
│  └────┬─────┘ └──┬───┘ └───┬────┘ └─────────────┘ │
│       └───────┬──┴─────────┘                        │
│               ▼                                     │
│  ┌──────────────────────────────────────┐           │
│  │     Agent Router + Session Store     │           │
│  │  (routes messages to agent runtimes) │           │
│  └──────────────┬───────────────────────┘           │
└─────────────────┼───────────────────────────────────┘
                  │ gRPC / WebSocket / Unix socket
      ┌───────────┼───────────┬───────────┐
      ▼           ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│  jerry   │ │  fran    │ │  grif    │ │  ray     │
│  runtime │ │  runtime │ │  runtime │ │  runtime │
│          │ │          │ │          │ │          │
│ Model    │ │ Model    │ │ Model    │ │ Model    │
│ Context  │ │ Context  │ │ Context  │ │ Context  │
│ Engine   │ │ Engine   │ │ Engine   │ │ Engine   │
│ MCP Svrs │ │ MCP Svrs │ │ MCP Svrs │ │ MCP Svrs │
│ Tools    │ │ Tools    │ │ Tools    │ │ Tools    │
│ Memory   │ │ Memory   │ │ Memory   │ │ Memory   │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
  Container    Container    Container    Container
  / VM         / VM         / VM         / VM

Key Design Decisions

Control Plane Responsibilities

• Channel connections (Telegram polling, webhook endpoints)
• Message routing (inbound → agent, outbound → channel)
• Cron job scheduling and dispatch
• Hook ingress (/hooks/agent)
• Agent-to-agent message relay (sessions_send)
• Session metadata store (which agent owns which session)
• Dashboard / Control UI
• Health monitoring of agent runtimes

Agent Runtime Responsibilities

• Model conversation loop (the core agent turn)
• Context engine plugins (assembling context per turn)
• Compaction and memory flush
• Tool execution (including sandbox)
• MCP server lifecycle management
• Agent workspace filesystem
• Session conversation state (the actual messages)

Runtime ↔ Control Plane Protocol

• Bidirectional streaming (gRPC or WebSocket)
• Control plane sends: inbound messages, cron triggers, system events, agent-to-agent messages
• Runtime sends: outbound messages (for channel delivery), session status updates, health pings
• Runtimes register on startup with their agent ID and capabilities

Deployment Modes

The embedded mode preserves full backward compatibility — existing single-process deployments continue to work unchanged.

Concrete Benefits

Independent lifecycle

# Restart just Jerry's runtime — Fran/Grif/Ray unaffected
openclaw runtime restart --agent jerry

# Upgrade Jerry to a new plugin version without touching others  
openclaw runtime upgrade --agent jerry

# Scale Grif's compute for a heavy workload
# (resize container, add CPU/memory — no gateway restart)

Per-agent compute profiles

{
  "agents": {
    "list": [
      {
        "id": "jerry",
        "runtime": { "cpus": 2, "memoryMb": 4096, "image": "openclaw-runtime:latest" }
      },
      {
        "id": "ray", 
        "runtime": { "cpus": 0.5, "memoryMb": 512, "image": "openclaw-runtime:latest" }
      }
    ]
  }
}

True secret isolation

Each runtime only receives its own agent's secrets. Jerry's Bedrock credentials, Grif's Graph tokens, and Fran's gog keys never coexist in the same process.

Fault isolation

A segfault in Grif's msgraph MCP server crashes only Grif's runtime. The gateway reconnects Grif on a fresh runtime while Jerry, Fran, and Ray continue uninterrupted.

Relation to Existing Work

• feat: Agents Plane — multi-tenant agent provisioning and isolation #17299 (Agents Plane) — Agents Plane is about multi-tenant provisioning (one agent per person across an org). This RFC is about the lower-level runtime architecture that makes Agents Plane possible. The distributed runtime is the compute layer that Agents Plane would orchestrate.
• feat: Add WhatsApp poll support #248 (Sandboxed Agent Execution) — Overlaps on isolation goals. The runtime boundary is a natural place to apply sandbox policies.
• "gifPlayback" (inline GIF) support missing for web outbound messages #98 (Agent session isolation) — Session isolation becomes trivial when agents run in separate runtimes.
• [Feature]: Add a secure way to pair dynamically autoscaled worked nodes in K8s #12429 (K8s worker nodes) — K8s is one deployment backend for distributed runtimes.

Implementation Phases

Phase 1: Define the runtime protocol

• Formalize the message contract between gateway and runtime
• Extract the agent turn loop into a separable module
• Implement local-split mode (same host, separate processes, Unix sockets)

Phase 2: Containerized runtimes

• Publish openclaw-runtime container image
• Docker Compose reference deployment (gateway + N runtimes)
• Health checks, graceful shutdown, reconnection

Phase 3: Orchestration backends

• ECS/Fargate task definitions
• K8s Deployment manifests + Helm chart
• AgentCore microVM backend (for AWS-native deployments)

Phase 4: Dynamic scaling

• Spin up/down runtimes based on agent activity
• Hibernate idle agents (save state, release compute)
• Burst scaling for cron job storms

Real-World Context

We run a 4-agent deployment (Jerry/Opus, Fran/Sonnet, Grif/Sonnet, Ray/Sonnet) on a single t3.large EC2 instance with systemd. Each agent has its own workspace, MCP servers, brain databases, and tool configurations. The single-process gateway works today, but we regularly hit:

• Gateway restarts (for config changes or upgrades) dropping all Telegram connections
• MCP server crashes in one agent's stack affecting gateway stability
• Inability to give Jerry (Opus, 1M context, heavy tool use) more compute without over-provisioning for Ray (Haiku heartbeats)
• Agent-to-agent debugging difficulty when everything shares one log stream

The distributed runtime would solve all of these while preserving the single openclaw.json config and unified dashboard that make OpenClaw productive for small teams.