Fresh Linux install created the workspace but no Gateway service

Troubleshooting
, , , ,
1

Adapted community discussion: Paraphrased and condensed from an anonymized public OpenClaw Discord support conversation from September 2026. Technical guidance was reviewed for OpenClaw 2026.9.3.

I am doing a fresh install on a Linux cloud VM. Model authentication, the workspace, and sessions were created, but setup failed when it tried to start openclaw-gateway.service. Systemd says the unit does not exist.

2

The saved model and workspace setup are still useful. Only the per-user Gateway service registration failed. Run the repair as the same non-root user who owns the OpenClaw state:

openclaw --version
export XDG_RUNTIME_DIR=/run/user/$(id -u)
sudo loginctl enable-linger "$USER"
openclaw gateway install
openclaw gateway status --deep

Use openclaw gateway install, which manages the user service. A root-level sudo systemctl start looks for the wrong unit.

3

I ran the original installer after switching to a root shell. Could that be why the service context is wrong?

4

Yes. That would place state under the root account and manage root’s service context. Exit the root shell, confirm whoami and $HOME identify the normal service account, and run onboarding or the installer there. Use elevated privileges only for the specific host command that needs them.

5

I reinstalled as the normal user and enabled Tailscale access. The service exists now, but the Gateway entered another restart failure.

6

The service-registration issue is fixed. The new log points to a plugin whose capability consent has not been accepted. Inspect the exact installed plugin before changing it:

openclaw plugins list --verbose
openclaw plugins inspect codex --json

If you intend to use and trust that plugin, review its capabilities and enable it with openclaw plugins enable codex --accept-capabilities. Otherwise disable it. Then run openclaw update repair, restart the Gateway, and inspect openclaw gateway status --deep.

7

The status now shows the user service enabled, runtime running, connectivity probe OK, matching CLI and Gateway versions, and a loopback listener.

8

That is a healthy Gateway. A loopback listener is expected when Tailscale Serve provides the HTTPS route. Confirm the configured mode and the route:

openclaw config get gateway.tailscale.mode
tailscale serve status

If the mode is serve, use the Tailscale HTTPS URL and keep the Gateway port closed to the public internet. Current references: Linux and Tailscale.