Provisioning OpenClaw by hand once is fine. Doing it five times — once for a staging box, once for a production box, once after a panel mistake, twice for new team members — is how you end up with five subtly different installs. The fix is the same as for every other server-class workload: a cloud-init manifest the VPS panel applies at first boot, so the box comes up already correct. Ubuntu’s NoCloud and OVA datasource flow has been standard for years (cloudinit.readthedocs.io), every reputable IaaS panel — Hetzner, Vultr, DigitalOcean, Linode, Scaleway, OVH, Virtuozzo Automator — accepts user-data, and OpenClaw is just an npm-installed Node daemon, exactly the kind of workload cloud-init handles well.
This article gives you a complete cloud-init.yaml that installs OpenClaw on a fresh Ubuntu 22.04 or 24.04 LTS VPS in one boot. The output is a running gateway on 127.0.0.1:18789 (github.com/openclaw/openclaw) with the workspace on a dedicated mount, owned by a dedicated system user, with provider keys in a sealed env file, behind a systemd unit. The only step left is onboarding (which is interactive by design) and the remote-access edge.
What’s happening
Cloud-init runs in three phases — init, config, final — and the manifest below uses four top-level keys that map onto the phases: users, packages, write_files, and runcmd (cloudinit.readthedocs.io — Modules). At the end of runcmd, OpenClaw is installed and the daemon is enabled but not yet onboarded — the manifest deliberately stops before the interactive onboarding step because the pairing token must be entered with a human in front of a terminal.
The manifest does six things in order:
- Create the
openclawsystem user with/var/lib/openclawas its home and/usr/sbin/nologinas its shell. - Format and mount the secondary disk (if your provider gives you one) at
/var/lib/openclaw/. - Install base packages, harden SSH (no passwords), enable unattended security upgrades, set up UFW.
- Add the NodeSource APT repo for Node 24, install Node, pin it with
apt-mark hold(deb.nodesource.com). - Write the systemd unit and a stub env file at
/etc/openclaw/openclaw.envwith0640 root:openclaw. - Install OpenClaw globally via npm and enable the gateway unit so the daemon comes up at every boot.
Onboarding (openclaw onboard) happens after the cloud-init run is done — you SSH in once, run it, and the daemon is ready. After that the VPS comes back from any reboot already running, no human in the loop.
Prerequisites
- A VPS panel that accepts a user-data field at provision time. Almost every modern panel does — look for “Cloud-init”, “User Data”, “Startup Script”, or similar.
- An Ubuntu 22.04 or 24.04 LTS image. The manifest is tested on both.
- Your SSH public key. The manifest pre-authorizes it for the
rootuser; password auth is disabled. - Optionally, a secondary disk attached at provision time (preferred — see Sizing storage for OpenClaw memory and skills). If your provider only gives you a single disk, the manifest still works; the workspace just lives on the OS volume.
How to verify
When cloud-init has finished — usually 90 seconds to 3 minutes after first boot, depending on the image — SSH in and check:
cloud-init status --wait
# status: done
The daemon should be enabled and active:
systemctl is-enabled openclaw-gateway.service # enabled
systemctl is-active openclaw-gateway.service # active (after onboarding)
Listening sockets should be exactly these (port 18789 is the OpenClaw default — github.com/openclaw/openclaw):
ss -lntp | grep -E ':(22|18789)\b'
# 0.0.0.0:22 sshd
# 127.0.0.1:18789 node (openclaw gateway) — only after onboarding completes
If 18789 is not listening yet, that is expected — the unit started but the daemon has no config until you run openclaw onboard.
The fix
The manifest
Save the following as cloud-init.yaml and paste it into your panel’s user-data field at provision time. Substitute the SSH key on line 9, the API key placeholder, and the data-disk device if your provider gives you one with a different name (Hetzner: /dev/sdb, DigitalOcean: /dev/sda with the OS on /dev/vda, Vultr: /dev/vdb).
#cloud-config
# OpenClaw IaaS — first-boot manifest for Ubuntu 22.04 / 24.04 LTS
# After cloud-init runs, SSH in and: sudo -u openclaw HOME=/var/lib/openclaw /usr/bin/openclaw onboard
hostname: openclaw-prod
manage_etc_hosts: true
preserve_hostname: false
users:
- name: root
ssh_authorized_keys:
- ssh-ed25519 AAAAC3Nz...REPLACE_ME you@example.com
- name: openclaw
system: true
shell: /usr/sbin/nologin
home: /var/lib/openclaw
create_home: false
package_update: true
package_upgrade: true
packages:
- curl
- ca-certificates
- gnupg
- build-essential
- ufw
- fail2ban
- unattended-upgrades
- chrony
- jq
- iproute2
- lsof
- parted
# Workspace disk — only if your provider gives you a second disk.
# If not, comment this whole section out; the workspace will live on /.
disk_setup:
/dev/vdb:
table_type: gpt
layout: true
overwrite: false
fs_setup:
- label: openclaw-data
filesystem: ext4
device: /dev/vdb
partition: auto
mounts:
- [ "LABEL=openclaw-data", "/var/lib/openclaw", "ext4", "defaults,noatime", "0", "2" ]
write_files:
- path: /etc/ssh/sshd_config.d/99-openclaw.conf
permissions: '0644'
content: |
PasswordAuthentication no
PermitRootLogin prohibit-password
KbdInteractiveAuthentication no
- path: /etc/apt/apt.conf.d/20auto-upgrades
permissions: '0644'
content: |
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
APT::Periodic::AutocleanInterval "7";
- path: /etc/fail2ban/jail.d/sshd.local
permissions: '0644'
content: |
[sshd]
enabled = true
port = ssh
backend = systemd
maxretry = 4
findtime = 10m
bantime = 1h
- path: /etc/openclaw/openclaw.env
permissions: '0640'
owner: 'root:openclaw'
defer: true
content: |
# Replace ANTHROPIC_API_KEY with your provider key before starting the unit
ANTHROPIC_API_KEY=sk-ant-REPLACE_ME
OPENCLAW_HOME=/var/lib/openclaw
OPENCLAW_GATEWAY_BIND=127.0.0.1
OPENCLAW_GATEWAY_PORT=18789
- path: /etc/systemd/system/openclaw-gateway.service
permissions: '0644'
content: |
[Unit]
Description=OpenClaw gateway daemon
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/var/lib/openclaw
EnvironmentFile=/etc/openclaw/openclaw.env
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/lib/openclaw
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
RestrictNamespaces=true
LockPersonality=true
SystemCallArchitectures=native
LimitNOFILE=65536
MemoryMax=3G
[Install]
WantedBy=multi-user.target
runcmd:
# Mountpoint exists before mount unit fires
- [ install, -d, -m, '0750', -o, openclaw, -g, openclaw, /var/lib/openclaw ]
# NTP
- [ systemctl, enable, --now, chrony ]
# UFW: SSH only — remote access goes through Tailscale / Cloudflare Tunnel
- [ ufw, --force, reset ]
- [ ufw, default, deny, incoming ]
- [ ufw, default, allow, outgoing ]
- [ ufw, allow, '22/tcp' ]
- [ ufw, --force, enable ]
# fail2ban
- [ systemctl, enable, --now, fail2ban ]
# NodeSource Node 24
- bash -c "curl -fsSL https://deb.nodesource.com/setup_24.x | bash -"
- [ apt-get, install, -y, nodejs ]
- [ apt-mark, hold, nodejs ]
# OpenClaw global install — npm puts the binary at /usr/bin/openclaw
- [ npm, install, -g, openclaw@latest ]
# Re-apply ownership in case the mount wiped it
- [ chown, -R, 'openclaw:openclaw', /var/lib/openclaw ]
- [ chmod, '0750', /var/lib/openclaw ]
# SSH hardening file is in place; restart sshd
- [ systemctl, restart, ssh ]
# Enable the gateway unit. It will fail until onboarding writes openclaw.json;
# systemd will keep retrying every 5 s. That is fine for now.
- [ systemctl, daemon-reload ]
- [ systemctl, enable, --now, openclaw-gateway.service ]
# Touch a flag file so you can tell at a glance that cloud-init finished
- [ touch, /var/lib/openclaw/.cloud-init-done ]
final_message: "OpenClaw provisioned. SSH in, edit /etc/openclaw/openclaw.env, then: sudo -u openclaw HOME=/var/lib/openclaw /usr/bin/openclaw onboard"
Single-disk variant
If your VPS only has one disk (most cheap-tier panels), comment out the disk_setup, fs_setup, and mounts blocks. The workspace will live at /var/lib/openclaw/ on the OS volume. Everything else works unchanged — just remember the entire box is now a single failure domain. See Sizing storage for OpenClaw memory and skills for why a separate workspace volume earns its keep.
Sealed env file from a secret store
The manifest above ships a stub env file with a placeholder key — that is deliberate, because a real key has no business sitting in a panel’s user-data field where the panel logs it. The patterns that work:
- Manual edit on first SSH. Pragmatic for one-off boxes. SSH in once, edit
/etc/openclaw/openclaw.env,systemctl restart openclaw-gateway.service. - Pull from a secret store at boot. Add a
runcmdline that pulls from HashiCorp Vault, AWS Secrets Manager, Doppler, or 1Password — the canonical pattern is documented in the secrets-engine docs of each tool (developer.hashicorp.com — Vault Agent). - Vendor the env file at provision time via SSM or User Data extras. Works on AWS and some panels; check what your provider supports.
For most personal/team OpenClaw deployments option (1) is fine — the env file is touched once and rotated only when the LLM provider key rotates.
After cloud-init finishes
# Verify cloud-init exit
cloud-init status --wait
# Replace the placeholder API key
sudo $EDITOR /etc/openclaw/openclaw.env
# Onboard — this is interactive, hence not in cloud-init
sudo -u openclaw HOME=/var/lib/openclaw /usr/bin/openclaw onboard
# Restart the daemon so it picks up the new config
sudo systemctl restart openclaw-gateway.service
sudo systemctl status openclaw-gateway.service --no-pager
Then bolt on the remote-access edge — Tailscale, Cloudflare Tunnel, or Caddy. See DNS, TLS, and secure remote access to OpenClaw.
What this manifest deliberately does not do
It does not install the channel SDKs — Telegram, Slack, Discord, etc. The OpenClaw npm package bundles them, and the agent loads them when you configure channels in openclaw.json. There is nothing to install ahead of time.
It does not install a reverse proxy. The right edge is workload-dependent — Tailscale for personal-use, Cloudflare Tunnel when you want a public hostname, Caddy when you control the public IP. Pick one and follow DNS, TLS, and secure remote access to OpenClaw.
It does not configure backup. The workspace is at /var/lib/openclaw/ and /etc/openclaw/openclaw.env holds the keys, but the backup target — restic to S3, ZFS snapshots, the panel’s own snapshot feature — is a choice that depends on what storage you have. See Snapshot and backup strategy for cloud-hosted OpenClaw.
It does not run openclaw onboard. Onboarding asks interactive questions and writes the auth token to the workspace — putting it inside cloud-init either fails (no TTY) or leaks the token into cloud-init logs. The friction of one manual command is the right cost.
Troubleshooting
cloud-init status says error. Read /var/log/cloud-init.log and /var/log/cloud-init-output.log. Most failures are either a bad SSH key in users, a wrong device name in disk_setup, or a transient APT mirror error during package install.
The gateway unit is activating (auto-restart) forever. That is the daemon failing because openclaw.json does not exist yet. Run openclaw onboard once and it will start cleanly.
disk_setup did not partition the second disk. Two common causes: wrong device name (verify with lsblk) or a leftover partition table from a previous boot. wipefs -a /dev/vdb then re-run cloud-init via cloud-init clean && reboot for a hard reset (cloudinit.readthedocs.io — Manual clean).
Node hold did not take. Confirm with apt-mark showhold | grep nodejs. If it is missing, run apt-mark hold nodejs manually. Without the hold an unattended-upgrade major-version bump can take the daemon down.
Related
- Deploying OpenClaw on a Virtuozzo Hybrid Server VM
- Deploying OpenClaw on a small IaaS VPS for 24/7 access
- Firewall rules for an OpenClaw IaaS deployment
Sources
- openclaw.ai
- github.com/openclaw/openclaw
- cloudinit.readthedocs.io
- cloudinit.readthedocs.io — Modules
- deb.nodesource.com
- developer.hashicorp.com — Vault Agent
Last verified on OpenClaw current.