OpenClaw AWS Deploy

intent

Deploy a production-ready OpenClaw gateway on AWS in one command. use this skill when spinning up a new OpenClaw agent instance on EC2, switching AI models (Bedrock, Gemini, etc.), or tearing down an existing deployment. the skill creates a minimal, secure infrastructure stack (VPC, subnet, security group, t4g.medium ARM64 instance) with no inbound ports, encrypts secrets in AWS Systems Manager Parameter Store, bootstraps Node.js 22+, installs OpenClaw, and hands off a live Telegram bot connected to your chosen LLM. total cost runs ~$30/month for the compute + storage layer.

inputs

AWS credentials (one of):

• Named AWS CLI profile via --profile <name> flag
• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION
• Active AWS SSO session or IAM role (if running from EC2)
• .env.aws file (workspace root or skill directory):

  AWS_ACCESS_KEY_ID=...
  AWS_SECRET_ACCESS_KEY=...
  AWS_DEFAULT_REGION=us-east-1
  

Telegram bot token and (optional) user ID in .env.starfish (workspace root or skill directory):

TELEGRAM_BOT_TOKEN=<token_from_@BotFather>
TELEGRAM_USER_ID=<your_user_id>
GEMINI_API_KEY=<optional_api_key_from_aistudio.google.com>

Local binaries required:

• aws CLI (v2.x+)
• jq (command-line JSON processor)
• openssl (for secure random generation)
• git (required by OpenClaw npm dependencies)

Alternatively, Docker provides sandboxed access if these are unavailable.

External connections:

• AWS IAM: requires permissions to create VPC, EC2, security groups, IAM roles, EBS volumes, Systems Manager Parameter Store, and (optionally) Bedrock invoke model
• Telegram Bot API: outbound HTTPS to api.telegram.org (gateway will message TELEGRAM_BOT_TOKEN)
• Bedrock (optional): requires model access enabled in AWS Bedrock console for your region (MiniMax auto-approved, Anthropic/Meta require use-case form)
• Gemini (optional): requires API key from aistudio.google.com (free tier: 15 RPM, 1M tokens/day)

Parameters:

• --name <string>: deployment name (tagged on all resources, used for teardown discovery)
• --region <string>: AWS region, e.g. us-east-1 (default: us-east-1)
• --model <string>: AI model identifier, e.g. google/gemini-2.0-flash or amazon-bedrock/minimax.minimax-m2.1 (default: Bedrock MiniMax M2.1)
• --env-dir <path>: workspace directory containing .env.starfish and .env.aws (default: current directory)
• --cleanup-first: destroy any existing deployment with the same --name before deploying (optional)
• --pair-user <telegram_user_id>: auto-approve Telegram pairing for this user ID (optional)

procedure

1. preflight checks , run ./scripts/preflight.sh. verify aws, jq, openssl, git are installed and in PATH. verify AWS credentials are valid. verify .env.starfish exists and TELEGRAM_BOT_TOKEN is set. fail fast if any dependency is missing.

   • input: AWS credentials, local binaries
   • output: pass/fail status; if pass, AWS account ID and region confirmed

2. cleanup existing deployment (if requested) , if --cleanup-first flag is set, run ./scripts/teardown.sh --name <name> --region <region> --yes. wait for all resources to be destroyed. skip this step if flag is absent.

   • input: deployment name, region, IAM permissions
   • output: empty AWS state for the given name (or no-op if nothing exists)

3. create VPC, subnet, internet gateway, and route table , call AWS API to create a VPC (CIDR 10.50.0.0/16), public subnet (10.50.0.0/24), internet gateway, and route table with 0.0.0.0/0 to IGW. tag all resources with Project=<name> and DeployId=<unique-id>.

   • input: region, deployment name
   • output: VPC ID, subnet ID, IGW ID, route table ID

4. create security group , create a security group in the VPC with no inbound rules (SSM Session Manager only; no SSH, no HTTP/HTTPS from internet). allow all outbound traffic (required for package installs, API calls, Telegram). tag it.

   • input: VPC ID, deployment name
   • output: security group ID

5. create IAM role and instance profile , create an IAM role with inline policy granting: ssm:StartSession, ssm:TerminateSession, ssm:GetParameter, ssm:PutParameter, ssm:DescribeParameters, bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, ec2:DescribeInstances. attach instance profile to the role. tag it.

   • input: deployment name
   • output: IAM role ARN, instance profile ARN

6. store secrets in Systems Manager Parameter Store , for each secret in .env.starfish (e.g., TELEGRAM_BOT_TOKEN, GEMINI_API_KEY), create or overwrite an SSM Parameter (String type, not SecureString for speed) at path /openclaw/<name>/<KEY>. these are fetched by the startup script on each service start and written to ephemeral config files (never persisted in AMI or repo).

   • input: .env.starfish contents, SSM API
   • output: parameter paths (e.g., /openclaw/starfish/TELEGRAM_BOT_TOKEN)

7. generate user-data bootstrap script , compose a bash script that runs on first boot. the script will: install Node.js 22 from official tarball, install OpenClaw from npm, fetch secrets from SSM Parameter Store, write openclaw.json config and auth-profiles.json, create systemd service file, start the service. see step 13 for config generation.

   • input: instance ID (will be available after launch), SSM parameter paths, model choice, region
   • output: base64-encoded user-data script (max 16KB)

8. launch EC2 instance , create an EC2 t4g.medium ARM64 instance (4GB RAM, 20GB gp3 EBS, encrypted) in the public subnet. assign the IAM instance profile. set metadata options to IMDSv2 required. supply the user-data script from step 7. tag it with Project=<name>, DeployId=<unique-id>, Name=openclaw-<name>.

   • input: subnet ID, security group ID, instance profile ARN, user-data script, region
   • output: instance ID, public IP address

9. wait for instance state , poll aws ec2 describe-instances every 5 seconds until the instance state is running and status checks reach ok or 2/2. timeout after 5 minutes and fail if not ready.

   • input: instance ID, region
   • output: confirmed running state

10. wait for SSM agent readiness , poll aws ssm describe-instance-information --filters "Key=InstanceIds,Values=<instance-id>" every 5 seconds until the instance appears with PingStatus=Online. timeout after 3 minutes and fail if SSM agent is not reachable.

    • input: instance ID, region
    • output: confirmed SSM agent online

11. run smoke test via SSM , call aws ssm start-session --target <instance-id> and execute: sudo -u openclaw openclaw gateway status and sudo -u openclaw cat /home/openclaw/.openclaw/openclaw.json | jq .gateway. verify the gateway is running and config is correct. timeout after 60 seconds per command.

    • input: instance ID, region
    • output: gateway status (running or failed); if failed, exit with error and log session output

12. save deployment output , write a JSON file deploy-output.json (in current directory) containing: instance ID, public IP, security group ID, VPC ID, subnet ID, IAM role ARN, region, deployment name, model, Telegram token (masked), DeployId, and timestamp. this file is used by teardown.sh to clean up resources deterministically.

    • input: all resource IDs from previous steps
    • output: deploy-output.json in current working directory

Config generation (step 7, detail):

Generate openclaw.json with these required fields:

{
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true,
        "botToken": "${TELEGRAM_BOT_TOKEN}"
      }
    }
  },
  "model": {
    "primary": "<model_from_--model_flag>"
  }
}

If --model is not provided, default to amazon-bedrock/minimax.minimax-m2.1.

If the model starts with amazon-bedrock/, add Bedrock-specific config:

{
  "models": {
    "providers": {
      "amazon-bedrock": {
        "baseUrl": "https://bedrock-runtime.<region>.amazonaws.com",
        "api": "bedrock-converse-stream",
        "auth": "aws-sdk",
        "models": [...]
      }
    }
  }
}

If GEMINI_API_KEY is present in .env.starfish and the model is google/*, create auth-profiles.json:

{
  "gemini": {
    "apiKey": "${GEMINI_API_KEY}"
  }
}

If neither condition is met, skip auth-profiles.json (no error).

decision points

if --cleanup-first flag is set:

• run teardown before deploying. fail the entire deploy if teardown fails (e.g., resource in use).

else:

• proceed directly to step 3 (VPC creation).

if preflight checks fail (missing binary, invalid credentials, no .env.starfish):

• exit with error code 1 and print the missing requirement. do not attempt to create any AWS resources.

if the --model parameter starts with amazon-bedrock/:

• assume Bedrock auth via IAM role (from instance profile in step 5). do NOT require an API key.
• add Bedrock provider config to openclaw.json (see config generation detail above).

else if the --model parameter starts with google/:

• check for GEMINI_API_KEY in .env.starfish. if present, create auth-profiles.json with the API key.
• if absent, proceed without auth-profiles.json (Gemini call will fail at runtime, but startup will succeed).

else:

• treat the model string as-is. assume the user has set up auth separately or the model uses a default (e.g., local provider).

if user-data script exceeds 16 KB:

• split it: store the majority (config generation, service startup) in SSM Parameter Store /openclaw/<name>/startup-script and fetch it during bootstrap. adjust base64 encoding accordingly.

if EC2 instance fails to reach running state within 5 minutes:

• exit with error code 1, log the instance state and reason (e.g., "InsufficientInstanceCapacity"). suggest retrying or choosing a different region.

if SSM agent is not online within 3 minutes:

• exit with error code 1. log that the instance is running but SSM agent is not reachable. suggest checking security group outbound rules and instance role policies.

if smoke test fails (gateway not running, config invalid):

• exit with error code 1, log the SSM session output (stdout/stderr). provide manual remediation steps: aws ssm start-session --target <instance-id> and inspect logs in /home/openclaw/.openclaw/logs/.

if --pair-user flag is provided:

• auto-approve the Telegram pairing for that user ID during startup. write this to the config before the service starts.

else:

• skip auto-pairing. user must approve manually via openclaw pairing approve telegram <CODE> after receiving the bot message.

if the model requires credentials (e.g., external API key) and they are not found:

• proceed with deploy (do not block). the service will start successfully. at runtime, the LLM call will fail with an auth error. this is intentional (fail-fast on config, not on secrets availability).

output contract

file: deploy-output.json (in current working directory)

{
  "deploymentName": "<name>",
  "deployId": "<unique-id>",
  "timestamp": "2025-01-14T12:34:56Z",
  "region": "us-east-1",
  "instanceId": "i-0123456789abcdef0",
  "publicIp": "203.0.113.42",
  "vpcId": "vpc-0123456789abcdef0",
  "subnetId": "subnet-0123456789abcdef0",
  "securityGroupId": "sg-0123456789abcdef0",
  "iamRoleArn": "arn:aws:iam::123456789012:role/openclaw-starfish-role",
  "model": "amazon-bedrock/minimax.minimax-m2.1",
  "telegramBotTokenMasked": "123456789:ABCDEfg***",
  "ssm_parameter_prefix": "/openclaw/starfish"
}

AWS resources (all tagged with Project=<name>, DeployId=<deploy-id>):

• 1 VPC (10.50.0.0/16)
• 1 public subnet (10.50.0.0/24)
• 1 internet gateway
• 1 route table
• 1 security group (no inbound)
• 1 IAM role + instance profile
• 1 EC2 t4g.medium instance (running, SSM agent online)
• 1 EBS gp3 volume (20GB, encrypted)
• N SSM Parameters (e.g., /openclaw/starfish/TELEGRAM_BOT_TOKEN)

service status:

• systemd service openclaw is active (running) on the instance
• gateway is listening on localhost:8765 (internal only)
• Telegram bot is connected and responding to messages

gateway log: viewable via aws ssm start-session --target <instance-id> then sudo journalctl -u openclaw -f

outcome signal

1. deploy-output.json exists in the current working directory with all resource IDs populated.

2. smoke test passes: the script logs "OpenClaw gateway is running" and prints valid JSON from openclaw.json config.

3. SSM session works: you can connect via aws ssm start-session --target <instance-id> and run commands as the openclaw user.

4. Telegram bot responds: send a message to the bot (token from TELEGRAM_BOT_TOKEN). within ~10 seconds, the gateway logs show an incoming message and the bot either replies (if configured) or posts a pairing code (if unconfigured).

5. no SSH access needed: verify that the security group has no inbound SSH rule. confirm that direct SSH to the public IP fails (e.g., ssh -i key.pem ec2-user@<public-ip> times out or is refused).

6. secrets are not in the AMI or repo: verify that deploy-output.json masks the Telegram token, and the actual token exists only in SSM Parameter Store (fetch it via aws ssm get-parameter --name /openclaw/<name>/TELEGRAM_BOT_TOKEN --region <region>).

7. cost is ~$30/month: instance billing has started; you can view estimated charges in AWS Billing console (usually appears within 1 hour).