OpenClaw Gateway Install Fix

A working install for OpenClaw on headless Linux boxes, where the official openclaw gateway install fails with:

Gateway service install failed: systemctl enable failed:
Failed to enable unit: Unit file openclaw-gateway.service does not exist.

This repo contains a single script that gets you to a running, persistent OpenClaw gateway in about two minutes — and a writeup of why the bug happens and how the fix works.

Tracking issue upstream: openclaw/openclaw#33633. The first patch shipped in v2026.3.7 did not fully resolve the issue for headless root installs; it's still reproducible on 2026.5.7.

---

TL;DR

curl -fsSL https://raw.githubusercontent.com/anhourtec/Openclaw/main/openclaw-install.sh -o openclaw-install.sh
chmod +x openclaw-install.sh
sudo ./openclaw-install.sh

You'll get one Type YES to proceed prompt, then the script runs end-to-end. Tested on Ubuntu 24.04 with OpenClaw 2026.5.7.

Always read installer scripts before piping them to bash, including this one. That goes for https://openclaw.ai/install.sh (which this script also runs internally), and for the script in this repo. Both run as root.

---

What's in this repo

File	What it is
openclaw-install.sh	The fix script. Runs the official OpenClaw installer, works around the broken systemd registration, applies homelab-friendly Control UI config, locks down config permissions, verifies the service is healthy.
install-issue.md	Full writeup: what's broken, why it's broken, what the script does, how to verify, and the proper long-term fix (Nginx Proxy Manager + Let's Encrypt).

---

What the script does

1. Preflight checks. Refuses to run as non-root, requires systemd, requires curl. Bails early with a clear message if anything's missing.
2. Safety prompt. Single Type YES to proceed confirmation before doing anything irreversible.
3. Runs the official OpenClaw installer. curl -fsSL https://openclaw.ai/install.sh | bash. Skips this if OpenClaw is already installed (and asks before re-running).
4. Detects the right gateway start command by probing --help, so it works across CLI versions that use either gateway --port N or gateway start --port N.
5. Smoke-tests the gateway in foreground for 5 seconds. If the gateway crashes immediately (wrong command, port conflict, bad config), the script aborts before writing a systemd unit that would crash-loop silently.
6. Cleans up the failed user-level service that the broken installer leaves behind.
7. Writes a system-level systemd unit at /etc/systemd/system/openclaw.service with Restart=always, network-online ordering, and basic hardening (NoNewPrivileges, PrivateTmp).
8. Applies the homelab Control UI config — allowedOrigins=["*"], allowInsecureAuth=true, dangerouslyDisableDeviceAuth=true — via openclaw config set, with a timestamped backup of openclaw.json first. See the security note below.
9. Locks down ~/.openclaw — chmod 700 on the dir, chmod 600 on openclaw.json and any backups.
10. Enables, starts, and verifies with patient polling — up to 60 seconds for the port to bind and openclaw health to return cleanly. (OpenClaw startup includes model warmup and sidecars and routinely takes ~25–30 seconds.)

---

Security note — read this before running

Step 8 disables three real security controls:

• gateway.controlUi.allowedOrigins=["*"] — accepts dashboard connections from any web origin
• gateway.controlUi.allowInsecureAuth=true — allows credentials over plain ws://
• gateway.controlUi.dangerouslyDisableDeviceAuth=true — skips device authentication

This is a homelab convenience. It is appropriate for a closed LAN with only your trusted devices on it. It is not appropriate for shared networks, untrusted IoT, or anything reachable from the internet.

The proper long-term fix is loopback bind + Nginx Proxy Manager (or Caddy/Traefik) + Let's Encrypt, which gives you wss:// with a real cert and lets you keep all three controls on. The writeup walks through this. Treat the script's relaxed defaults as a "get unblocked tonight, fix properly next weekend" measure.

---

After running

Verify:

systemctl status openclaw            # should be: active (running)
systemctl is-enabled openclaw        # should be: enabled
openclaw health                      # should be: OK

Reboot once to confirm auto-start works, then open the dashboard from any device on your LAN at http://YOUR-HOST-IP:18789/.

A few loose ends the script intentionally doesn't handle:

• Set a strong gateway password if you didn't already, via openclaw configure.
• Configure your channel allowlists (Telegram, Discord, etc.) before exposing the bot. Without an allowlist, anyone who finds your bot's username can pair with it and inherit any tools you've enabled. The OpenClaw pairing docs cover this.
• Run the OpenClaw security audit once you've got channels wired up:

  openclaw security audit --deep

---

Was this helpful?

If this saved you an evening of debugging, a ⭐ on the repo helps it surface for the next person who hits the same error.

I write about homelab debugging, IoT, and self-hosted infrastructure — connect with me on LinkedIn.

Got a different environment where the script needs adjustment? Open an issue — happy to fold in fixes.

---

Related

• Upstream issue: openclaw/openclaw#33633
• OpenClaw docs: docs.openclaw.ai
• Security model & pairing: docs.openclaw.ai/gateway/security

---

License

MIT — use it, fork it, ship it. No warranty; you're running shell scripts as root, you know the deal.