v0.3.1 — Session Continuity

Highlights

Unified session storage ensures conversation context is preserved when smart routing switches between Lambda and Fargate. Previously each runtime used different S3 paths, causing the bot to "forget" previous conversations after a routing transition.

Fixes

• Unified S3 session path: Both Lambda and Fargate now read/write sessions to sessions/{userId}/agents/default/sessions/{sessionId}.jsonl
• Fargate session sync: LifecycleManager backs up and restores OpenClaw sessions to/from the shared S3 path
• Shared constants: SESSION_S3_PREFIX, SESSION_DEFAULT_AGENT in @serverless-openclaw/shared

Integration Tests (11 new, 7 patterns)

Pattern	Verified
Lambda → Lambda (2 consecutive)	Context preserved across cold starts
Lambda → Lambda (3 consecutive)	Full conversation accumulation
Fargate → Lambda	Lambda picks up Fargate history
Lambda → Fargate	Fargate restores Lambda history
Lambda → Fargate → Lambda	Full round-trip context
Fargate → Lambda → Fargate	Reverse round-trip context
User isolation	Separate users don't share sessions

Test Coverage

259 unit tests + 35 E2E tests = 294 total, all passing

🤖 Generated with Claude Code

v0.3.0 — Smart Routing

Highlights

When AGENT_RUNTIME=both, the system now intelligently routes messages to Lambda or Fargate based on task characteristics.

Routing Rules

Priority	Condition	Route	Reason
1	Fargate container Running	Fargate	Reuse (already paid for)
2	Message starts with /heavy or /fargate	Fargate	User explicit request
3	Default	Lambda	Fast (1.35s), cheap ($0)
4	Lambda fails	Fargate (fallback)	Auto-retry with full runtime

New Features

• Smart routing (route-classifier.ts): Dynamic Lambda/Fargate selection based on task state and message hints
• Fargate reuse: Running containers are reused instead of wasting them by routing to Lambda
• User hints: /heavy and /fargate message prefixes explicitly request Fargate runtime
• Lambda fallback: Automatic Fargate retry when Lambda invocation fails

Test Coverage

248 unit tests + 35 E2E tests = 283 total, all passing

🤖 Generated with Claude Code

v0.2.1 — Security Hardening & Skill Restructuring

Security Fixes

• Timing-safe token comparison: Bearer token (Bridge) and Telegram webhook secret now use timingSafeEqual to prevent timing side-channel attacks
• S3 path traversal prevention: sessionId and userId validated against ^[a-zA-Z0-9_:-]{1,128}$ before S3 key construction
• Gateway Lambda log retention: All 7 Lambda functions now have ONE_WEEK log retention (previously unbounded)
• ECR lifecycle policy: Lambda agent ECR repository limited to 5 images (prevents unbounded storage cost)

Skills (13 total)

5 new skills + 1 release skill + 5 updated:

• /dev — Build, test, lint, coding conventions
• /troubleshoot — Common CDK/Docker/Lambda/OpenClaw issues
• /openclaw — OpenClaw internals reference
• /cold-start — Cold start optimization history
• /status — Project progress and deployment info
• /release — 6 parallel review lanes before release

Documentation

• 22 issues fixed from comprehensive review (CRITICAL to LOW)
• All Korean text translated to English
• Architecture diagrams updated for 9 CDK stacks
• Migration journey documented from Claude Code work logs

Release Review

6 parallel review lanes executed: Code (APPROVE), Docs (fixed), Tests (APPROVE), Security (HIGH issues fixed), Cost (HIGH issues fixed), Operations (HIGH issue fixed).

268 tests (233 UT + 35 E2E) all passing.

🤖 Generated with Claude Code

v0.2.0 — Lambda Container Migration

Highlights

OpenClaw now runs directly in AWS Lambda, eliminating all fixed compute costs. The Fargate runtime remains available as a fallback.

• Zero idle cost: Lambda charges only per invocation (~$0.00005/request)
• 1.35s cold start: Down from 55.9s (97.6% reduction)
• 0.12s warm start: Down from 34.6s (99.7% reduction)
• Zero OpenClaw modifications: Wrapper-only approach, fully upstream-compatible

New Features

• Lambda Agent Runtime (packages/lambda-agent/): Runs OpenClaw's runEmbeddedPiAgent() in a Lambda Container Image (ARM64, 2048MB, 15min timeout)
• S3 Session Persistence: Session files (JSONL) synced between S3 and Lambda /tmp for cross-invocation continuity
• DynamoDB Session Lock: Conditional writes prevent concurrent session corruption
• AGENT_RUNTIME Feature Flag: fargate (default) | lambda | both — controls which compute path is deployed
• CDK LambdaAgentStack: ECR repository, DockerImageFunction, IAM (S3 + SSM + DynamoDB + CloudWatch)
• /lambda-migration Claude Code skill: Guided implementation for each migration step

Performance

Metric	Before (Fargate)	After (Lambda)	Change
Cold start	55.9s	1.35s	-97.6%
Warm start	34.6s	0.12s	-99.7%
Idle cost	~$15/month	$0	-100%
Memory (warm)	1,270 MB	119 MB	-90.6%

Breaking Changes

None. Default AGENT_RUNTIME=fargate preserves existing behavior.

Deployment Notes

• Docker build requires --provenance=false (Lambda doesn't support OCI manifests)
• ECR repository must be pre-created before first deploy
• CDK Bootstrap v30+ required (cdk bootstrap to update)
• Current operational mode: both (Lambda primary, Fargate fallback)

Test Coverage

233 unit tests + 35 E2E tests = 268 total, all passing

Key Technical Decisions

• file:// URL import bypasses Node.js exports map for OpenClaw's extensionAPI.js
• Bedrock discovery disabled via config (bedrockDiscovery.enabled: false) — saves ~54s per invocation
• OpenClaw module cached across warm invocations for 0.12s response time
• Session files synced via S3 with DynamoDB conditional-write locking

---

Full migration journey: docs/lambda-migration-journey.md

🤖 Generated with Claude Code

v0.1.0 — Phase 1 MVP + Cold Start Optimization

Overview

First release of Serverless OpenClaw — an open-source project that runs OpenClaw on-demand on AWS serverless infrastructure, providing a web UI and Telegram bot as interfaces. Inspired by Cloudflare MoltWorker, built as an independent AWS-native solution.

Alpha Release — Development in progress. Use for development and testing purposes only.

Highlights

• On-demand Fargate Spot containers — ~$1/month for personal use
• Web Chat UI — React SPA on S3 + CloudFront with Cognito authentication
• Telegram Bot — Webhook-based integration with Web-Telegram identity linking
• Predictive Pre-Warming — Optional EventBridge cron eliminates ~68s cold start (0s first response)
• One-command deployment — `cdk deploy --all` deploys 8 CDK stacks

Features

Core Platform

• ECS Fargate Spot containers with automatic startup/shutdown (watchdog)
• API Gateway (WebSocket + REST) with 7 Lambda handlers
• DynamoDB (5 tables, PAY_PER_REQUEST) for conversations, settings, task state, connections, pending messages
• S3 for file storage and backups
• Cognito JWT authentication for all API requests

Web UI

• React + Vite SPA hosted on S3 + CloudFront (OAC)
• Real-time chat via WebSocket with streaming responses
• Cognito SRP authentication (sign-up, sign-in)
• Telegram account linking via 6-digit OTP

Telegram Bot

• Webhook-only integration with secret token verification
• Progress messages during container cold start
• AI response streaming with 4096-char message splitting
• OTP-based identity linking for container sharing with Web UI

Cold Start Optimization

• Docker image reduced from 2.22GB to 1.27GB (43% reduction)
• Container startup parallelization (~3-5s saved)
• zstd image compression (-16%)
• SOCI lazy loading support (~50% additional reduction)
• Stale IP detection with 3s Bridge timeout + fallback
• Dynamic watchdog timeout (active/inactive hours)
• OpenClaw v2026.2.13 pinned (fastest compatible version)
• Predictive Pre-Warming (P9): EventBridge cron proactively starts containers before scheduled usage, claimed by first real user message

Security

• 6-layer Bridge defense (Security Group → Bearer token → TLS → localhost binding → non-root → SSM Parameter Store)
• SSM Parameter Store SecureString for all secrets (no secrets on disk)
• Server-side userId only (IDOR prevention)
• Telegram webhook secret token verification

Monitoring

• CloudWatch custom metrics (10 metrics, namespace: ServerlessOpenClaw)
• Dashboard with 6 sections: cold start, messages, Lambda, API Gateway, ECS/DynamoDB, pre-warming
• 7-day Lambda log retention, 14-day Fargate log retention

Infrastructure

Stack	Resources
SecretsStack	5 SSM SecureString parameters
NetworkStack	VPC, public subnets, VPC Gateway Endpoints
StorageStack	5 DynamoDB tables, 2 S3 buckets, ECR
AuthStack	Cognito User Pool + App Client
ComputeStack	ECS Cluster, Fargate task definition
ApiStack	API Gateway (WS+REST), 7 Lambda functions, EventBridge
WebStack	S3 + CloudFront
MonitoringStack	CloudWatch dashboard

Test Coverage

• 198 unit tests (vitest)
• 28 E2E tests (CDK synth verification for all 8 stacks)

Getting Started

See the Deployment Guide for full instructions.

npm install
npm run build
cd packages/web && npx vite build && cd ../..
cd packages/cdk && npx cdk deploy --all