⚠️ Alpha — Development in ProgressThis project is in an early alpha stage and has not been fully tested in production environments. It involves LLM API calls, which can incur unexpected costs and may expose security risks if misconfigured. Use for development and testing purposes only. The authors are not responsible for any costs or damages arising from its use.
An open-source project that runs OpenClaw on-demand on AWS serverless infrastructure, providing a web UI and Telegram as interfaces.
Inspired by the architecture of Cloudflare MoltWorker, this project delivers an independent serverless solution optimized for the AWS ecosystem.
- Serverless On-demand Execution: Minimizes cost (~$1/month) by running containers only when requested, powered by ECS Fargate Spot
- Predictive Pre-Warming: Optional EventBridge-scheduled container pre-warming eliminates cold start during active hours (0s first response)
- Web Chat UI: Real-time chat interface built with React SPA (hosted on S3 + CloudFront)
- Telegram Bot Integration: Chat with the AI agent from anywhere via Telegram, with Web-Telegram identity linking for container sharing
- Multi-LLM Support: Choose your preferred LLM provider — Claude, GPT, DeepSeek, and more
- Task Automation: Automate various tasks through OpenClaw skills
- One-command Deployment: Deploy the entire infrastructure with a single
cdk deploy
- Operate at under $1-2/month for personal use (~$0.23 within Free Tier)
- 70% compute cost reduction with ECS Fargate Spot
- Eliminate $18-25/month fixed costs by using API Gateway instead of ALB
- Zero idle costs with automatic container termination during inactivity
- Deploy/update the entire infrastructure with a single
cdk deploycommand - No server management required — all components are serverless or managed services
- OpenClaw version updates handled by changing the Docker image tag
- No separate monitoring infrastructure needed thanks to CloudWatch-based logging
- Easily adjust Fargate task specifications (vCPU, memory) via CDK configuration
- Multi-channel extensible Gateway architecture (Telegram, Discord, Slack, etc.)
- Feature extensibility through custom Skills
- Automatic traffic scaling with DynamoDB on-demand mode
- AWS Cognito-based JWT authentication — token verification applied to all API requests
- HTTPS enforced (CloudFront + API Gateway)
- Secrets managed via SSM Parameter Store SecureString
- Least-privilege IAM roles applied to Fargate containers
- Telegram webhook protected with secret token verification to prevent spoofing
- Public subnet + multi-layer defense (Security Group + Bridge token authentication + TLS + localhost binding)
graph TB
User[User]
subgraph "Interface"
WebUI[React SPA\nS3 + CloudFront]
TGBot[Telegram Bot]
end
subgraph "API Layer"
APIGW[API Gateway\nWebSocket + REST]
Lambda_GW[Gateway Lambda\nRouting/Auth/Container Management]
end
subgraph "Authentication"
Cognito[AWS Cognito\nUser Pool]
end
subgraph "Compute"
Fargate[ECS Fargate Task\nOpenClaw Container]
end
subgraph "Storage"
DynamoDB[(DynamoDB\nConversation History/Settings)]
S3[(S3\nFiles/Backups)]
end
User --> WebUI
User --> TGBot
WebUI --> APIGW
TGBot --> Lambda_GW
APIGW --> Lambda_GW
Lambda_GW --> Cognito
Lambda_GW --> Fargate
Fargate --> DynamoDB
Fargate --> S3
| Layer | Technology |
|---|---|
| IaC | AWS CDK (TypeScript) |
| API | API Gateway (WebSocket + REST) |
| Gateway | Lambda (Node.js/TypeScript) |
| Runtime | ECS Fargate |
| Frontend | React + Vite + TypeScript |
| Auth | AWS Cognito |
| DB | DynamoDB |
| File Storage | S3 |
| Monitoring | CloudWatch |
| Messenger | Telegram Bot API |
- On-demand deployment of OpenClaw containers on AWS
- Web chat UI + Telegram bot integration
- AI conversation/chat + task automation
- Cognito authentication + data persistence
- Browser automation (headless Chromium)
- Custom Skills development support
- Settings management UI
- CloudWatch alerts + cost dashboard
- EventBridge-based scheduled task execution
- Additional messenger support (Discord, Slack)
Extreme cost optimization applied with the Fargate Spot + API Gateway combination. (Assuming 2 hours of daily usage)
| Category | Monthly Cost |
|---|---|
| Within Free Tier (12 months) | ~$0.27/month |
| After Free Tier expires | ~$1.11/month |
Key: Fargate Spot (~70% discount vs On-Demand) + API Gateway ($18-25/month savings vs ALB)
Predictive Pre-Warming (optional): Adds ~$0.003/hour on Spot when enabled. A weekday 1-hour schedule costs ~$0.07/month extra but eliminates the ~68s cold start entirely.
Detailed analysis: Cost Optimization Document
Pre-warming is disabled by default. To enable, add to .env:
# Comma-separated EventBridge cron expressions
PREWARM_SCHEDULE=0 9 ? * MON-FRI * # Weekdays at 9 AM UTC
# Duration in minutes to keep container alive (default: 60)
PREWARM_DURATION=60Then redeploy: cd packages/cdk && npx cdk deploy ApiStack
Skills are provided that automatically load project context in Claude Code during development.
| Skill | Invocation | Description |
|---|---|---|
| context | Auto-loaded | Project overview, tech stack, key decisions |
| implement | /implement 1-3 |
Guide for specific implementation steps (goals, deliverables, verification criteria) |
| architecture | /architecture |
Network, data model, CDK stack reference |
| security | /security |
Security checklist (Bridge defense, IDOR, secrets) |
| cost | /cost |
Cost target verification (prohibited resources, checklist) |
serverless-openclaw/
├── packages/
│ ├── shared/ # Shared types, constants
│ ├── cdk/ # AWS CDK infrastructure definitions
│ ├── gateway/ # Lambda functions (API Gateway handlers)
│ ├── container/ # Fargate container (Bridge server)
│ └── web/ # React SPA (Vite)
├── docs/ # Design documents
└── references/ # Reference projects (MoltWorker, etc.)
Organized as an npm workspaces monorepo with TypeScript project references.
npm install # Install dependencies
cp .env.example .env # Configure AWS profile (edit .env)
npm run build # TypeScript build
npm run lint # ESLint check
npm run format # Prettier formatting
npm run test # Unit tests (198 tests)
npm run test:e2e # E2E tests (CDK synth, 28 tests)AWS deployment: Deployment Guide | Local development details: Development Guide
- PRD (Product Requirements Document)
- Architecture Design
- Detailed Design & Implementation Plan
- Cost Optimization Analysis
- Deployment Guide
- Development Guide
- Project Progress Plan
- User Guide (Quick Start)
Contributions are welcome! Please read the guidelines below before submitting.
- Bug fixes and small improvements — Submit a Pull Request directly
- Major features or architecture changes — Open a GitHub Issue first to discuss the approach
- Questions — Open a GitHub Discussion
- Fork the repository and create a feature branch from
main - Run the full build and test suite locally:
npm run build && npm run lint && npm run test && npm run test:e2e
- Keep each PR focused on a single change
- Provide a clear description of what changed and why
- Ensure all CI checks pass
git clone https://github.com/<your-fork>/serverless-openclaw.git
cd serverless-openclaw
npm install
cp .env.example .env # Configure AWS profile
npm run build
npm run test # Unit tests (99 tests)
npm run test:e2e # E2E tests (24 tests)For detailed local development instructions, see the Development Guide.
- TypeScript strict mode with ES2022 target
.jsextension required in all import paths- ESLint + Prettier enforced via Git hooks (pre-commit)
- TDD required — write tests before implementation (except
packages/web)
AI-generated code is welcome. When submitting AI-assisted PRs:
- Indicate in the PR title or description that AI tools were used
- Document the testing level (untested / lightly tested / fully tested)
- Confirm that you understand what the code does
If you discover a security vulnerability, please do not open a public issue. Instead, report it via GitHub's private vulnerability reporting feature or contact the maintainers directly.
A complete report should include: severity level, affected components, reproduction steps, and suggested fixes.
MIT License