openclaw-generator

What this skill does

# OpenClaw Generator -- Deploy OpenClaw Anywhere via Ralph Loop

Creates a fully resumable Ralph loop that deploys an OpenClaw instance step-by-step
on the user's chosen provider. Each loop iteration is one micro-step (prereq check,
config, deploy, verify, or fix). Lessons learned during deployment are automatically
ported back to the skill's reference docs.

---

## What Gets Created

```
{project-dir}/
  .ralph/
    PLAN.md                    # Provider-specific deployment plan (micro-steps)
    PROMPT.md                  # Ralph loop discipline + instructions
    PROGRESS.md                # Timestamped progress log (Ralph appends)
    LESSONS.md                 # Deployment gotchas discovered (Ralph appends)
  .ralphrc                     # Ralph configuration (model, tools, timeouts)
  .env                         # Secrets (API keys, tokens) -- gitignored
  references/                  # Symlinked from skill -- provider docs + overview
    OPENCLAW_OVERVIEW.md
    PROVIDER_{NAME}.md
    RALPH_LOOP_TEMPLATE.md
  Dockerfile                   # (cloud providers only) OpenClaw container image
  fly.toml                     # (Fly.io only)
  render.yaml                  # (Render only)
  docker-compose.yml           # (Docker local only)
  .gitignore
  README.md                    # Quick-reference for the deployment
```

---

## Supported Providers

| Provider | Difficulty | Cost | Best For |
|----------|-----------|------|----------|
| **Docker Local** | Easiest | Free (API costs only) | Trying OpenClaw on your machine |
| **Railway** | Easy | $5-20/month | Quick cloud deploy with web wizard |
| **Fly.io** | Easy | $5-15/month | Global edge deployment |
| **DigitalOcean** | Easy | $12-24/month | 1-Click marketplace or manual VPS |
| **Coolify** | Moderate | Free + VPS costs | Self-hosted PaaS on your own server |
| **Render** | Easy | $7-25/month | Zero-config cloud with render.yaml |

---

## Prerequisites

- **Claude Code CLI** with Ralph loop support
- **Git** installed
- **Node.js 22+** (for local testing; cloud providers handle this)
- **At least one AI model API key** (Anthropic recommended: `ANTHROPIC_API_KEY`)
- **Provider-specific tooling** (installed during the loop):
  - Fly.io: `flyctl`
  - Railway: `@railway/cli`
  - DigitalOcean: `doctl` or browser
  - Docker: Docker Desktop or Docker Engine
  - Coolify: Browser access to Coolify dashboard
  - Render: Browser access to Render dashboard

---

## Phase 0: Provider Selection

Ask the user which provider they want to deploy to. Use `AskUserQuestion` with these options:

```
AskUserQuestion:
  question: "Which provider do you want to deploy OpenClaw to?"
  header: "Provider"
  options:
    - label: "Docker Local (Recommended for beginners)"
      description: "Run OpenClaw in Docker on your machine. Free, instant, great for trying it out."
    - label: "Railway"
      description: "One-click cloud deploy with web setup wizard. $5-20/month usage-based."
    - label: "Fly.io"
      description: "Global edge deployment with persistent volumes. $5-15/month."
    - label: "DigitalOcean"
      description: "1-Click Droplet or manual VPS. $12-24/month. Most documented."
  multiSelect: false
```

If the user picks "Other", follow up with a second question offering Coolify and Render.

Store the selected provider as `{PROVIDER}` for the rest of the skill.

---

## Phase 1: Pre-Flight -- Interactive Setup (Before Ralph)

**This phase runs interactively before the Ralph loop is created.** It collects
all secrets, authenticates with the provider, and validates everything works.
Once pre-flight passes, the Ralph loop is 100% autonomous with zero user interaction.

### Step 1.1: Collect AI model API key

```
AskUserQuestion:
  question: "What is your Anthropic API key? (starts with sk-ant-)"
  header: "API Key"
  options:
    - label: "I have it in my environment"
      description: "ANTHROPIC_API_KEY is already exported in my shell"
    - label: "I'll paste it now"
      description: "I have the key ready to paste"
    - label: "I use a different provider"
      description: "I use OpenAI, OpenRouter, or another provider instead"
  multiSelect: false
```

If "already in environment", verify: `echo $ANTHROPIC_API_KEY | head -c 10` shows `sk-ant-...`.
If "paste it now", store it securely for the `.env` file.
If "different provider", ask which provider and which env var to use.

### Step 1.2: Install and authenticate provider CLI

Run the provider-specific CLI setup **interactively** so the user can complete
any browser-based auth flows:

**Fly.io:**

```bash
# Install flyctl if missing
command -v flyctl >/dev/null || curl -L https://fly.io/install.sh | sh
# Login (opens browser for OAuth)
fly auth login
# Verify
fly auth whoami
```

**Railway:**

```bash
# Install CLI if missing
command -v railway >/dev/null || npm install -g @railway/cli
# Login (opens browser for OAuth)
railway login
# Verify
railway whoami
```

**Docker Local:**

```bash
# Verify Docker is running
docker info >/dev/null 2>&1 || echo "ERROR: Docker is not running. Start Docker Desktop first."
```

**DigitalOcean:**

```bash
# If using doctl:
command -v doctl >/dev/null || brew install doctl  # or snap install doctl
doctl auth init  # prompts for API token
doctl account get
# If browser-only: skip CLI, confirm user has dashboard access
```

**Coolify:**

```
AskUserQuestion:
  question: "What is the URL of your Coolify dashboard?"
  header: "Coolify URL"
  options:
    - label: "I use Coolify Cloud"
      description: "My dashboard is at app.coolify.io"
    - label: "Self-hosted"
      description: "I'll provide my Coolify URL"
  multiSelect: false
```

**Render:**
No CLI needed -- confirm user has Render dashboard access and a GitHub repo ready.

### Step 1.3: Generate security tokens

Generate tokens that will be baked into the `.env` file:

```bash
# Generate a secure gateway auth token
OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# For Railway: generate a setup password
SETUP_PASSWORD=$(openssl rand -hex 16)
```

### Step 1.4: Validate all prerequisites

Run a final validation checklist and display results:

```
Pre-Flight Checklist:
  [x] AI model API key verified
  [x] Provider CLI installed and authenticated
  [x] Gateway token generated
  [x] Docker running (if Docker Local)
  [ ] Provider-specific requirements met

All checks passed. The Ralph loop will run fully autonomously from here.
```

If any check fails, tell the user exactly what to fix and re-run the check.
Do NOT proceed to Phase 2 until all checks pass.

### Step 1.5: Write .env file

Write all collected secrets to `{PROJECT_NAME}/.env`:

```bash
# .env -- OpenClaw deployment secrets (DO NOT COMMIT)
# Generated by openclaw-generator pre-flight

# AI Model Provider
ANTHROPIC_API_KEY={collected_key}

# OpenClaw Gateway Auth
OPENCLAW_GATEWAY_TOKEN={generated_token}

# Provider-specific (Railway only)
SETUP_PASSWORD={generated_password}
```

This file is gitignored. Ralph reads it via `source .env` at the start of deploy steps.

---

## Phase 2: Create Project Directory

### Step 2.1: Ask for project name

```
AskUserQuestion:
  question: "What should we name this OpenClaw deployment?"
  header: "Name"
  options:
    - label: "openclaw-local"
      description: "Default name for a local/personal instance"
    - label: "openclaw-prod"
      description: "For a production deployment"
    - label: "openclaw-dev"
      description: "For a development/testing instance"
  multiSelect: false
```

Store the name as `{PROJECT_NAME}`.

### Step 2.2: Create directory structure

```bash
mkdir -p {PROJECT_NAME}/.ralph
mkdir -p {PROJECT_NAME}/references
cd {PROJECT_NAME}
git init
```

### Step 2.3: Create .gitignore

```gitignore
# OpenClaw state
.openclaw/

# Ralph logs (keep structure, ignore content)
.ralph/logs/

# Environment secrets
.env
.env.*

# Node
node_modules/

# OS
.DS_Store
```

---

## Phase 3: Generate Ralph Loop Files

### Step 3.1: Read the provider reference