agent-claw/offload-requirements.md

What Must Be Offloaded to External Services

Must-Offload Components

1. Messaging Channel Connections → External Service / Sidecar

Current: WhatsApp (Baileys WS), Discord (discord.js WS), Telegram (grammY), Slack (Bolt), etc. all run as persistent connections inside the gateway. Required: A separate always-on service that:

• Maintains persistent connections to each messaging platform
• Receives inbound messages
• Translates them into InvokeAgentRuntime calls to AgentCore
• Receives agent responses and routes them back to the correct channel

Options:

• ECS/Fargate task running a stripped-down "channel relay" service (the OpenClaw gateway minus the agent runtime)
• Lambda + API Gateway for webhook-based channels (Telegram webhook mode, Slack Events API)
• EC2 or ECS for WebSocket-based channels (WhatsApp Baileys, Discord)
• A lightweight "gateway lite" that keeps channel connections and forwards to AgentCore

Complexity: HIGH. This is the single biggest piece of work. The channel connection logic is deeply intertwined with the gateway.

2. Persistent State → S3 + DynamoDB / AgentCore Memory

Current: All state lives on the filesystem. Required:

State	Proposed External Store
Session transcripts (JSONL)	S3 (keyed by agent+session ID) or DynamoDB
Agent workspace (MEMORY.md, SOUL.md, etc.)	S3 bucket or EFS
WhatsApp auth state	DynamoDB or Secrets Manager
Config (openclaw.json)	S3 or Parameter Store
Pairing store (device trust)	DynamoDB
Secrets	Secrets Manager
Cron state	DynamoDB
Agent conversation history	AgentCore Memory (short-term + long-term)

Complexity: HIGH. Every file read/write in OpenClaw assumes a local filesystem. Would need a storage abstraction layer.

3. Heartbeat → EventBridge Scheduler

Current: Gateway-internal timer fires every 30m. Required: EventBridge Scheduler rule that periodically calls InvokeAgentRuntime with the heartbeat prompt.

Complexity: LOW. Straightforward EventBridge → Lambda → InvokeAgentRuntime.

4. Cron Jobs → EventBridge Scheduler

Current: croner library inside the gateway process. Required: Each cron job becomes an EventBridge Scheduler rule.

Complexity: MEDIUM. Need a way to manage/create/delete rules dynamically (since OpenClaw supports runtime cron management via the agent).

5. Webhook Ingress → API Gateway / ALB

Current: Gateway's HTTP server handles webhook endpoints for channels like Telegram (webhook mode), Slack Events API. Required: API Gateway or ALB fronting the channel relay service or Lambda functions.

Complexity: MEDIUM.

6. Browser Control → AgentCore Browser Tool or Sidecar

Current: Playwright controlling a local Chromium process. Required: Either:

• Use AgentCore's built-in Browser Tool
• Run headless Chrome inside the container (heavy, ephemeral)
• Separate browser service (like Browserless.io or an ECS sidecar)

Complexity: MEDIUM. AgentCore has its own browser tool which could replace OpenClaw's.

Can Stay Inside the Container

These components work within an AgentCore container:

• Agent reasoning loop (pi-mono core logic)
• LLM API calls (Bedrock, Anthropic, OpenAI — outbound HTTP)
• Web search / web fetch (outbound HTTP to Brave API, arbitrary URLs)
• TTS calls (outbound HTTP to ElevenLabs/Edge TTS)
• System prompt construction (pure logic)
• Context windowing / compaction (algorithmic)
• Model selection / failover (pure logic)
• Basic shell exec (within container, ephemeral)
• File read/write (within session, ephemeral — but see state offloading above)

Summary: Effort Estimate

Component	Effort	Notes
Channel relay service	XL	Core gateway refactor; messaging is deeply coupled
Storage abstraction layer	L	Every fs operation needs a backend swap
Heartbeat/Cron offload	S	EventBridge rules
Agent HTTP wrapper	M	Wrap pi-mono behind /invocations + /ping
Session model redesign	L	JSONL → AgentCore Memory or DynamoDB
Webhook ingress	M	API Gateway + routing
Browser adaptation	S-M	Use AgentCore Browser Tool or containerized Chrome