# Architecture Comparison: OpenClaw vs AgentCore Runtime

## OpenClaw Architecture

OpenClaw is a **long-lived, stateful daemon** designed to run on personal hardware (Mac, Linux, Pi, VPS).

### Core Components

**Gateway (the heart)**
- Single long-lived Node.js process (Node ≥22)
- Binds to a local port (default `127.0.0.1:18789`)
- Multiplexed WebSocket server: control plane, RPC, events
- Also serves HTTP (OpenAI-compatible API, hooks, Control UI, Canvas)
- Maintains **persistent outbound connections** to messaging providers
- Hot-reloads config changes; supervised via launchd/systemd

**Channel Plugins (always-on connections)**
- WhatsApp (Baileys — maintains a persistent WebSocket to WhatsApp servers)
- Telegram (grammY — long-polling or webhook)
- Discord (discord.js — persistent WebSocket gateway connection)
- Slack (Bolt — Socket Mode or webhook)
- Signal (signal-cli subprocess)
- iMessage/BlueBubbles (local macOS integration)
- IRC, Matrix, MS Teams, Google Chat, LINE, Feishu, Nostr, Twitch, Zalo, etc.
- Each channel maintains its own long-lived connection or polling loop

**Agent Runtime (Pi agent)**
- Embedded "pi-mono" agent runtime, invoked via internal RPC
- Tool execution: `exec` (shell commands), `read/write/edit` (filesystem), `browser` (Playwright/CDP)
- Session transcripts stored as JSONL files: `~/.openclaw/agents/<agentId>/sessions/*.jsonl`
- Workspace files: AGENTS.md, SOUL.md, MEMORY.md, etc. — filesystem-based memory

**Persistent State (filesystem)**
- Config: `~/.openclaw/openclaw.json`
- Session transcripts: `~/.openclaw/agents/*/sessions/*.jsonl`
- Pairing store (device trust)
- Secrets store
- WhatsApp auth state (Baileys session)
- Cron state
- Agent workspace (MEMORY.md, daily notes, etc.)

**Scheduled Tasks**
- Heartbeat: periodic agent turns in main session (default every 30m)
- Cron jobs: scheduled commands/agent invocations
- Both rely on the gateway being continuously running

**Connected Clients (inbound WS)**
- macOS menu bar app
- iOS/Android nodes (camera, screen, location, voice)
- CLI tools
- WebChat UI
- Browser control (Playwright/CDP to managed Chrome)

### Key Characteristics
- **Always-on process** — not request/response
- **Persistent outbound connections** — channels maintain socket connections
- **Local filesystem** — session transcripts, config, workspace, WhatsApp state
- **PTY/process spawning** — exec tool runs shell commands, coding agents
- **Native integrations** — macOS APIs (iMessage, voice), Bonjour discovery
- **Single-user, single-host** — designed for one person's machine

---

## AgentCore Runtime Architecture

AgentCore is a **serverless, request-driven container hosting environment** for AI agents.

### Core Components

**Runtime Container**
- ARM64 Docker container on a dedicated microVM
- Must listen on `0.0.0.0:8080` (HTTP) / `0.0.0.0:8000` (MCP) / `0.0.0.0:9000` (A2A)
- Invoked via `InvokeAgentRuntime` API with a session ID

**Session Model**
- Each session gets its own **isolated microVM**
- Session identified by `runtimeSessionId` (≥33 chars)
- Session states: Active → Idle → Terminated
- **Max lifetime: 8 hours**
- **Idle timeout: 15 minutes** — session terminated after 15min of no requests
- After termination: microVM destroyed, memory sanitized
- Filesystem is **ephemeral** — nothing persists beyond session lifetime

**Health Contract**
- Must implement `/ping` endpoint
- Returns `Healthy` (idle, can accept work) or `HealthyBusy` (processing async tasks)
- Used for session lifecycle management

**Networking**
- Optional VPC connectivity (ENIs in your VPC)
- Outbound internet: requires NAT gateway in VPC config
- Without VPC: default internet access for API calls
- No persistent inbound listener — invoked via AWS API

**Persistent Storage**
- None built-in — filesystem is ephemeral
- **AgentCore Memory**: managed service for short-term (per-session) and long-term (cross-session) memory
- External services: DynamoDB, S3, RDS for durable state

**Scaling**
- Consumption-based pricing (pay for active CPU; I/O wait is typically free)
- Auto-scales sessions
- No pre-provisioning needed

### Key Characteristics
- **Request-driven** — not always-on
- **Ephemeral filesystem** — nothing persists after session ends
- **Session-scoped** — 15min idle timeout, 8hr max
- **Container-based** — ARM64 Docker image
- **No persistent outbound connections** — designed for request/response + async tasks
- **Multi-tenant** — designed for scaling across users