⚠️ This project is still under development, use at your own risk ⚠️

AlphaClaw Render Template

Deploy OpenClaw to Render in one click. Get a 24/7 AI agent connected to Telegram or Discord, with your entire config and workspace backed up to GitHub. No CLI required.

The AlphaClaw Advantage

• OpenClaw Gateway running 24/7
• Everything version controlled — config, cron jobs, workspace, and memory backed up to GitHub automatically
• Telegram or Discord configured out of the box (add/remove channels anytime via the UI)
• Google Workspace integration — connect Gmail, Calendar, Drive, Contacts, and Sheets with a few clicks via built-in OAuth flow
• Secrets never committed — raw API keys are replaced with ${ENV_VAR} references before pushing to GitHub
• Prompt hardening — improve change visibility and reduce silent/partial edits so your OpenClaw project stays stable over time
• Setup UI — web-based onboarding, env var management, channel pairing, and gateway control
• Webhook proxy — single exposed port handles both the setup UI and gateway webhooks

Convenient Setup UI

Pricing note

Render uses fixed-price instance tiers, so you pay for reserved capacity regardless of utilization. An instance with enough RAM for OpenClaw (8 GB) runs ~$85/mo on Render's Standard plan.

Deploy

Only one variable is needed at deploy time:

Click the button to deploy:

Everything else — AI keys, GitHub credentials, channel tokens — is configured through the setup UI after your first login.

First-time setup

After deploying, visit your Render app URL (e.g. https://your-app.onrender.com).

1. Log in with your setup password

2. Complete the welcome screen

The welcome screen walks you through selecting your default model and entering the minimum required variables:

• Model (required): Pulled dynamically from your installed OpenClaw model catalog
• AI Provider auth (required for selected model): Anthropic API Key/Setup Token, OpenAI API Key, Gemini API Key, or OpenAI Codex OAuth
• GitHub: Personal access token + a repo (owner/repo) for backing up your agent's state
• Channel (at least one): Telegram Bot Token or Discord Bot Token

Each field includes instructions and links for how to get the value. Optional fields (like Brave Search API Key) can be filled in later from the Envars tab.

Model catalog note: Models are discovered at runtime via openclaw models list --all --json. This keeps the setup UI aligned with the OpenClaw version installed in your deployment.

Versioning note: OpenClaw's version is pinned transitively by the alphaclaw commit SHA in package.json (see CHANGELOG.md for what each pin bump ships). New OpenClaw releases land by bumping that pin and redeploying, or from the setup UI's Upgrade tab on a running deploy — not automatically at build time.

Codex OAuth note: OpenClaw onboarding runs in non-interactive mode here. For OAuth-only Codex setups, the wrapper uses --auth-choice skip and then applies your selected openai-codex/* model after onboarding.

Click Complete Setup — the server runs onboarding, configures channels, and pushes an initial commit to your GitHub repo. This takes 10–15 seconds.

3. Approve channel pairing

DM your bot on Telegram (or Discord). The setup UI shows "Send a message to your bot on Telegram or Discord" with pending pairings polling every second. Click Approve to connect.

4. Connect Google Workspace (optional)

Once at least one channel is paired, the Google Workspace section appears:

1. Click Set up Google and enter your OAuth client credentials (from Google Cloud Console)
2. Select which permissions to grant
3. Click Sign in with Google to complete the OAuth flow
4. The UI shows API status for each service — click Enable API links for any that need enabling

5. Start chatting

DM your bot again — you're live!

Check your GitHub repo — you should see the initial commit with your agent's full config and workspace.

Memory search: For your agent to semantically search its own memory, you need either OPENAI_API_KEY or GEMINI_API_KEY set. OpenClaw uses these to generate embeddings. Without one, memory recall won't work.

Managing environment variables

The Envars tab lets you:

• View and edit all configured environment variables
• See which vars are set (values masked by default, click Show to reveal)
• Add custom variables — supports pasting multiple KEY=VALUE lines at once
• Delete custom variables with the ✕ button
• Save changes to the persistent /data/.env file
• Apply saved changes to bot runtime by clicking Restart Gateway after saving changes

The Models tab lets you:

• Set your primary model after onboarding
• Manage AI provider keys and Codex OAuth connection

Adding or removing a channel token (e.g. DISCORD_BOT_TOKEN) automatically enables/disables that channel in the OpenClaw config using openclaw channels add/remove.

The server watches /data/.env for changes — including ones written by the OpenClaw agent itself. When the agent needs an API key for a tool, it adds a placeholder to /data/.env and tells you to visit the Envars tab to fill it in.

All configurable variables

Architecture

Internet → Render :3000 (Express)
├── /                          → Setup UI (auth required)
├── /setup                     → Setup UI (auth required)
├── /api/status, /api/env ...  → Express handles (setup endpoints)
├── /api/* (everything else)   → proxy → gateway :18789
├── /webhook/*                 → proxy → gateway :18789 (token → Bearer header)
├── /openclaw                  → proxy → gateway :18789 (gateway control UI)
├── /assets/*                  → proxy → gateway :18789 (gateway UI assets)
└── WebSocket upgrade          → proxy → gateway :18789

File layout

/data/.openclaw/           ← Render persistent disk + git repo
├── openclaw.json          ← Config (secrets → ${ENV_VAR} references)
├── skills/                ← Agent skills (control-ui installed on onboard)
├── cron/jobs.json         ← Scheduled tasks
├── .gitignore             ← Excludes keys, logs, caches
├── agents/                ← Session state
└── workspace/             ← Agent workspace
    ├── hooks/bootstrap/   ← Deploy-synced prompt templates
    │   ├── AGENTS.md      ← Injected by bootstrap-extra-files
    │   └── TOOLS.md       ← Injected by bootstrap-extra-files
    ├── HEARTBEAT.md       ← Periodic check instructions
    └── memory/            ← Agent memory

/data/.env                 ← Persistent env vars (managed via Setup UI)
/data/tmp/                  ← Temp dir (TMPDIR) — kept off ephemeral /tmp, on the disk

First boot

1. Container starts, installs dependencies
2. Server starts and serves the setup UI at /
3. User completes the welcome screen with required variables
4. Server runs openclaw onboard, configures channels, sanitizes secrets, and enables bootstrap-extra-files with hooks/bootstrap/*
5. Everything committed and pushed to your GitHub repo
6. Gateway starts

Subsequent boots

1. /data/.env is loaded, bootstrap prompt templates are synced into workspace/hooks/bootstrap, and channel config is synced to match available tokens
2. Gateway starts
3. Setup UI available at / for managing env vars, channels, and pairings

Gateway management

• Status: The setup UI checks if the gateway is listening on its port in real-time
• Restart: Click "Restart" in the General tab — runs openclaw gateway install --force then openclaw gateway restart
• Channel sync: Adding/removing channel tokens in the Envars tab automatically runs openclaw channels add/remove

Baked-in tools

The image ships a fixed set of operator/agent tools so they survive redeploys instead of being hand-installed into the ephemeral container layer. Every pin lives in baked-tools.env at the repo root and is verified at build time.

Nothing is auto-started. Installing a tool does not enable it: the image launches no tailscaled, no caddy, opens no extra port and adds no cron job. A fresh deploy reaches the setup UI with no Tailscale or Caddy configuration. Gateway lifecycle stays with AlphaClaw.

Optional, manual use

These are things an operator may run by hand from the Render Shell tab. None of them is wired into boot; keep any state on the persistent disk (/data) or it is gone after the next redeploy.

• Tailscale — Render containers have no TUN device or CAP_NET_ADMIN, so userspace networking mode is required, and the state file must live under /data or you re-authenticate after every redeploy:

  mkdir -p /data/tailscale
  tailscaled --tun=userspace-networking \
    --state=/data/tailscale/tailscaled.state \
    --socket=/data/tailscale/tailscaled.sock

• Caddy — keep configs under /data, e.g. caddy validate --config /data/Caddyfile.

• Bun — bun install -g lands in the ephemeral /root/.bun unless BUN_INSTALL points under /data (e.g. BUN_INSTALL=/data/.bun).

• PostgreSQL client — psql, pg_dump, pg_restore for an external database; there is no server in the image.

git-lfs note

The LFS filter is installed system-wide at build time (git lfs install --system). It activates for any repo whose .gitattributes uses filter=lfs — including repos you clone by hand — and smudging then needs network access and credentials for that repo's LFS endpoint. If you do not want a checkout to download large objects, opt out per repo by running git lfs install --local --skip-smudge inside that repo (this writes the repo's own .git/config, so it persists with the repo under /data; without --local the override lands in ~/.gitconfig, which lives in the ephemeral /root and vanishes on redeploy). For a one-off clone use GIT_LFS_SKIP_SMUDGE=1 git clone …, then git lfs pull when you actually want the objects.

Exact pins (SBOM-lite)

cat /etc/baked-tools.env

lists every pinned version, checksum, MONOLITH_REV and PG_MAJOR the running image was built from. /etc/baked-tools.env is part of the image, not /data, which is why it does not appear in the file layout above.

Maintenance policy

• Tool CVEs are handled by bumping the pin; nothing auto-updates inside the image.
• Review the pins at each alphaclaw minor bump, or quarterly, whichever comes first.
• Soft budgets: image size at most +300 MB over the 2.0.0.2 image; cold build at most +8 minutes.

Bumping a pin

1. Edit baked-tools.env (the version and its matching checksums; for monolith, MONOLITH_VERSION + MONOLITH_REV).
2. Run npm test and npm run test:e2e.
3. Record the bump in CHANGELOG.md + VERSION.

Rollback

• Render dashboard → Deploys → Rollback to the previous deploy. Render redeploys the retained prior image; nothing is rebuilt.
• Or git revert the merge commit and redeploy. This rebuilds from the same pinned inputs, but the floating bases (the Node/Debian image and the PostgreSQL minor inside the signed repo) may differ from the original build.
• Either way the image never touches /data; there is no data migration to undo.

Troubleshooting

Pairing

First time you DM the bot, it sends a pairing request. Approve it in the setup UI. Pairings poll every second when pending — if nothing appears, check that the channel token is correct in the Envars tab.

Bot doesn't respond

• Check deploy logs for errors
• Verify your channel token is correct (Envars tab)
• Try clicking Restart in the General tab
• Check gateway status — should show green "running"

Gateway won't start

• Ensure the Render persistent disk is mounted at /data
• Check that AI provider credentials are valid
• Check deploy logs for the specific error — common cause is a missing env var referenced in openclaw.json

Channel shows "Add token"

The channel's env var is empty or missing. Go to the Envars tab, add the token, and save. The channel will be automatically enabled in the config.

If alphaclaw keeps crashing at boot

start.sh supervises alphaclaw start: intentional restarts (exit 75, or any exit after a run longer than 60s) relaunch immediately, and rapid crash-loops back off briefly. After 5 rapid failures in a row you get a failure-status page at the service URL with a Restart AlphaClaw button; the deploy stays Live so the Render Shell tab remains reachable. The supervisor writes every exit code, run duration, and decision to /data/start.log — read that first:

cat /data/start.log

If nobody intervenes, /health flips to 503 after ~5 minutes so Render restarts the container automatically. Before running anything by hand, check for a pending rollback marker — ls /data/.openclaw/.alphaclaw/openclaw-rollback-pending.json — a manual alphaclaw start replays a pending rollback and can wedge the install; prefer the Restart button.

Container crash-looping (debug mode)

If the container won't stay up long enough to use the Render Shell tab, swap the Dockerfile CMD to use the bundled debug-start.sh script:

COPY debug-start.sh /debug-start.sh
RUN chmod +x /debug-start.sh
# ... (other directives) ...
CMD ["/debug-start.sh"]

debug-start.sh does the bare minimum to keep the container alive for diagnosis:

• Binds port 3000 with a tiny Node HTTP server so Render marks the deploy Live and unlocks the Shell tab
• tail -f /dev/null keeps PID 1 alive so the container doesn't restart-loop
• Tees all boot output (PATH, env dump, whoami) to /data/debug.log on the persistent disk so the record survives even if Render's log stream drops anything

Once the deploy is Live, open the Shell tab and:

cat /data/debug.log               # boot environment dump
echo $PATH                        # what PATH alphaclaw will inherit
ls /app/node_modules/.bin | grep -i claw
alphaclaw start                   # reproduce the failure with full stdout

When you've identified and shipped the fix, restore CMD ["/start.sh"] in the Dockerfile.

Links

• OpenClaw docs
• OpenClaw GitHub
• Community Discord