2026 OpenClaw Docker on a VPS
Exit 137 and Control UI errors at a glance

Prerequisites: free -h, mem_limit, and telling first-run WASM compile from a “hard hang”

When the OpenClaw Gateway starts in a container for the first time, CPU pegged while the port stays closed is often the WASM sandbox compile phase, not a deadlock. Align with the resource guidance in the v2026.4 install guide: when both host free memory and mem_limit are too tight, Linux OOM yields Exit 137 and logs may not print a friendly error in time.

1. 01

   Host: run free -h on the host and confirm headroom is not chronically below about 1.5–2 GiB; Exit 137 is more common when swap is 0.

2. 02

   Compose: set mem_limit: 2g or higher and avoid competing with other heavy services on the same machine.

3. 03

   First-run window: allow 3–7 minutes on a cold start before calling it failed; use docker logs -f to see whether the compile chain is still running.

4. 04

   Health checks: set healthcheck.start_period to at least 360s so compose does not kill the process before WASM finishes.

5. 05

   Avoid false positives: do not repeatedly docker compose restart inside the first-run window or each restart retriggers the cold compile spike.

Put these five lines on page one of your “OpenClaw on a VPS” runbook to cut tickets that say “I followed the tutorial but it still won’t start.” For fuller Gateway layering, see the three-part runtime guide.

Control UI, 127.0.0.1 binding, and reverse proxies: choosing allowedOrigins and Host options

Publishing 18789 to the public internet on a VPS is a common misconfiguration. The install guide recommends binding the container to loopback only and terminating TLS with Caddy or Nginx on 443. When Control UI reports non-loopback errors, the root cause is usually a mismatch between browser origin and what the Gateway allows, not “Docker is broken.”

{
  "gateway": {
    "mode": "local",
    "controlUi": {
      "allowedOrigins": ["https://openclaw.example.com"]
    }
  }
}

Copy-paste compose skeleton, ten launch checks, and the “laptop always on” alternative

The three bullets below are common review bands from community and production; replace them with real monitoring from your hosts and add them to README so new hires do not repeat the same pits.

• First-start budget: allow at least 3–7 minutes on a cold start before opening a ticket; restarting before 3 minutes often amplifies 137.
• Memory headroom: for a single instance, keep host free memory chronically above about 2 GiB of margin; below that band, prefer a resize before stacking features.
• Log rotation: cap Docker json-file at ≤10 MiB per file, ≤3 files so a full disk does not cause secondary failures.

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    restart: unless-stopped
    mem_limit: 2g
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - ${HOME}/.openclaw:/home/node/.openclaw
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "curl", "-f", "http://127.0.0.1:18789/health"]
      interval: 60s
      timeout: 15s
      retries: 5
      start_period: 360s

Running the Gateway on a laptop long term is often dragged down by sleep, lid close, and flaky uplink; home broadband alone rarely yields an enforceable SLA. By contrast, a cloud Mac Mini billed by period fits hybrid flows that pair OpenClaw on a VPS with macOS or Xcode-side work.

If you want a stable Docker gateway online while moving heavy compiles or device work into a contract-grade macOS environment, self-owned capex is often weaker on procurement and multi-site sync. For 7×24 nodes with enforceable specs, VpsMesh cloud Mac Mini rental is usually the better fit: draw the split between VPS OpenClaw and dedicated remote Mac in your architecture, then use the pricing page and order page for capacity review instead of relying on verbal promises alone.