OpenClaw AWS Deploy Skill

Quick Start (Minimal Deployment ~$30/mo)

Prerequisites

• AWS credentials — any of these methods:
  • --profile <name> flag (named AWS CLI profile)
  • .env.aws file in workspace root or skill directory (optional):

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

  • Existing environment variables, AWS SSO session, or IAM role
• .env.starfish in workspace root (recommended) or skill directory:

  TELEGRAM_BOT_TOKEN=...     # from @BotFather (required)
  TELEGRAM_USER_ID=...       # your Telegram user ID (optional, enables auto-approve pairing)
  GEMINI_API_KEY=...         # from aistudio.google.com (optional, for Gemini models)

• aws CLI installed OR Docker for sandboxed access
• jq, openssl available

One-Shot Deploy

# From the skill directory:
./scripts/deploy_minimal.sh --name starfish --region us-east-1 \
  --env-dir /path/to/workspace

# Or with cleanup of previous deployment first:
./scripts/deploy_minimal.sh --name starfish --region us-east-1 \
  --env-dir /path/to/workspace --cleanup-first

This single command:

1. Creates VPC + subnet + IGW + route table
2. Creates security group (NO inbound ports — SSM only)
3. Creates IAM role with minimal permissions (SSM + Parameter Store + Bedrock)
4. Stores secrets in SSM Parameter Store (fetched at each service start — rewritten on each start, never stored in repo or static images)
5. Launches t4g.medium ARM64 instance with user-data bootstrap
6. User-data installs Node.js 22 + OpenClaw + configures everything
7. Runs smoke test via SSM
8. Saves all resource IDs to deploy-output.json

After Deploy

1. Message the Telegram bot — you'll get a pairing code
2. Approve pairing via SSM:

   aws ssm start-session --target <INSTANCE_ID> --region us-east-1
   sudo -u openclaw bash
   export HOME=/home/openclaw
   openclaw pairing approve telegram <CODE>

3. Bot is live! ✅

Teardown

# Using saved output:
./scripts/teardown.sh --from-output ./deploy-output.json --env-dir /path/to/workspace --yes

# Or by name (discovers via tags):
./scripts/teardown.sh --name starfish --region us-east-1 --env-dir /path/to/workspace --yes

Model Support

--model flag

Pass any model string — it goes directly into openclaw.json as model.primary:

# Default (MiniMax M2.1 on Bedrock — no API key needed, uses IAM role)
./scripts/deploy_minimal.sh --name starfish --region us-east-1

# Gemini Flash (needs GEMINI_API_KEY in .env.starfish)
./scripts/deploy_minimal.sh --name starfish --region us-east-1 \
  --model google/gemini-2.0-flash

AWS Bedrock

Bedrock IAM permissions (bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream) are always added to the instance role — regardless of which model you choose. This means any deployed instance can use Bedrock models out of the box via IAM role credentials (no API key needed).

Note: Bedrock models must be enabled in your AWS account via the Bedrock console before use.

Gemini

If GEMINI_API_KEY is present in .env.starfish, it's stored in SSM and written to auth-profiles.json. If absent, it's simply skipped — no error.

.env.starfish

TELEGRAM_BOT_TOKEN=...     # Required — from @BotFather
GEMINI_API_KEY=...         # Optional — from aistudio.google.com (needed for Gemini models)

Architecture (Minimal)

┌─────────────────────────────────────────────────────┐
│                      VPC (10.50.0.0/16)             │
│  ┌───────────────────────────────────────────────┐  │
│  │           Public Subnet (10.50.0.0/24)        │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │      EC2 t4g.medium (ARM64, 4GB)        │  │  │
│  │  │  ┌───────────────────────────────────┐  │  │  │
│  │  │  │       OpenClaw Gateway             │  │  │  │
│  │  │  │  • Node.js 22.14.0                 │  │  │  │
│  │  │  │  • Any model (Bedrock/Gemini/etc)   │  │  │  │
│  │  │  │  • Telegram channel                │  │  │  │
│  │  │  │  • Encrypted EBS (gp3, 20GB)       │  │  │  │
│  │  │  └───────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
         ↑                              ↓
    SSM (no SSH/inbound)      Outbound HTTPS only

Critical Lessons Learned (22 Issues)

These are baked into the deploy script. See references/TROUBLESHOOTING.md for full details.

Instance Sizing

• t4g.medium (4GB) required — t4g.small (2GB) OOMs during npm install + gateway startup
• ARM64 — better price/performance than x86

Node.js

• Node 22+ required — OpenClaw 2026.x requires Node ≥22.12.0
• Official tarball install — NodeSource setup_22.x unreliable on AL2023 ARM64
• git required — OpenClaw npm install has git-based dependencies

npm

• Use openclaw@latest — bare openclaw may resolve to placeholder package (0.0.1)

Gateway Startup

• Use openclaw gateway run --allow-unconfigured — NOT gateway start (which tries systemctl --user and fails)

  7w4.net收錄了海量優質技能外掛。

• Config file must be openclaw.json — not config.yaml
• gateway.mode: "local" — required or you get "Missing config" error
• gateway.auth.mode: "token" — "none" is invalid

Telegram

• plugins.entries.telegram.enabled: true — must be explicit
• dmPolicy: "pairing" — not "allowlist" (blocks everyone without user list)
• streamMode: "partial" — some models don't support streaming tools, use "off" as fallback

Model

• Gemini 2.0 Flash — recommended (free tier: 15 RPM, 1M tokens/day, supports tools)
• Auth profiles required — create auth-profiles.json in agent dir
• Bedrock format — amazon-bedrock/MODEL_ID (not bedrock/)
• Bedrock models need console enablement — Anthropic requires use case form

Systemd Service

• Simplified service file — removed ProtectHome, ReadWritePaths=/tmp/openclaw, PrivateTmp due to namespace issues
• Use NODE_OPTIONS="--max-old-space-size=1024" — helps prevent OOM

Security

• No inbound ports — SSM Session Manager only
• Secrets fetched from SSM at runtime — startup script fetches secrets each time the service starts; config files are ephemeral (rewritten on each start, never stored in repo or static images)
• Encrypted EBS — enabled by default in deploy script
• IMDSv2 required — HttpTokens=required

File Layout

scripts/
  deploy_minimal.sh        # One-shot deploy (VPC + EC2 + OpenClaw)
  teardown.sh              # Clean teardown of all resources
  setup_deployer_role.sh   # Create IAM role/user with minimum permissions
  preflight.sh             # Pre-deploy validation checks
  smoke_test.sh            # Post-deploy health verification

references/
  TROUBLESHOOTING.md   # All 22 issues + solutions
  config-templates/    # Ready-to-use config files
    gemini-flash.json  # OpenClaw config for Gemini Flash
    auth-profiles-gemini.json  # Auth profile template
    openclaw.service.txt  # Systemd unit file template
    startup.sh         # Startup script template

Config Templates

OpenClaw Config (gemini-flash.json)

See references/config-templates/gemini-flash.json — includes all required fields.

Auth Profiles (auth-profiles-gemini.json)

Create at ~/.openclaw/agents/main/agent/auth-profiles.json

Systemd Service (openclaw.service)

Simplified for reliability — security hardening removed due to namespace issues.

Cost Breakdown (~$30/mo)

Troubleshooting

"No API key found for amazon-bedrock"

Cause: OpenClaw needs models.providers config in openclaw.json with "auth": "aws-sdk". An auth-profiles.json entry alone is NOT sufficient.

Fix: Add to openclaw.json on the instance:

sudo -u openclaw bash
cd /home/openclaw/.openclaw
jq '.models = {
  "providers": {"amazon-bedrock": {"baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com", "api": "bedrock-converse-stream", "auth": "aws-sdk", "models": [{"id": "minimax.minimax-m2.1", "name": "MiniMax M2.1", "input": ["text"], "contextWindow": 128000, "maxTokens": 4096}]}},
  "bedrockDiscovery": {"enabled": true, "region": "us-east-1"}
}' openclaw.json > /tmp/oc.json && mv /tmp/oc.json openclaw.json
chown openclaw:openclaw openclaw.json
systemctl restart openclaw

"API rate limit reached" (Gemini)

Fix: Switch to Bedrock (default in current version) or redeploy with --model amazon-bedrock/minimax.minimax-m2.1.

Bedrock model returns errors

Cause: Model must be enabled in AWS Console → Bedrock → Model access. MiniMax models are auto-authorized; Anthropic/Meta models require use-case approval.

Bot doesn't respond after deploy

Fix: Add TELEGRAM_USER_ID to .env.starfish for auto-pairing, or use --pair-user <id>. Manual: openclaw pairing approve telegram <CODE> via SSM.

Safety Rules

• Never print secrets in logs
• Never open SSH/inbound ports; use SSM Session Manager only
• Use least-privilege IAM policies
• All resources tagged with Project=<name> and DeployId=<unique-id> for deterministic cleanup
• Encrypted EBS volumes always

質量很好，文件詳細、使用說明清晰。優勢是安全性高（無 SSH、直接通過訊息控制）、支援多種 AI 模型、人格可定製。部署成功後基本無需額外維護。不足是需要一定的技術基礎，依賴 AWS 環境。總體推薦，適合需要自動化部署 AI agent 的使用者。