Linux app

The Gateway is fully supported on Linux. Node is the recommended runtime. Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).

Native Linux companion apps are planned. Contributions are welcome if you want to help build one.

Beginner quick path (VPS)

1. Install Node 24 (recommended; Node 22 LTS, currently
   text

   Copy

   22.14+
   , still works for compatibility)
2. text

   Copy

   npm i -g openclaw@latest
3. text

   Copy

   openclaw onboard --install-daemon
4. From your laptop:
   text

   Copy

   ssh -N -L 18789:127.0.0.1:18789 <user>@<host>
5. Open
   text

   Copy

   http://127.0.0.1:18789/
   and authenticate with the configured shared secret (token by default; password if you set
   text

   Copy

   gateway.auth.mode: "password"
   )

Full Linux server guide: Linux Server. Step-by-step VPS example: exe.dev

Install

• Getting Started
• Install & updates
• Optional flows: Bun (experimental), Nix, Docker

Gateway

• Gateway runbook
• Configuration

Gateway service install (CLI)

Use one of these:

text
Copy
openclaw onboard --install-daemon

Or:

text
Copy
openclaw gateway install

Or:

text
Copy
openclaw configure

Select Gateway service when prompted.

Repair/migrate:

text
Copy
openclaw doctor

System control (systemd user unit)

OpenClaw installs a systemd user service by default. Use a system service for shared or always-on servers.

and already render the current canonical unit for you; write one by hand only when you need a custom system/service-manager setup. The full service guidance lives in the Gateway runbook.

Minimal setup:

Create

:

text
Copy
[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

Enable it:

text
Copy
systemctl --user enable --now openclaw-gateway[-<profile>].service

Memory pressure and OOM kills

On Linux, the kernel chooses an OOM victim when a host, VM, or container cgroup runs out of memory. The Gateway can be a poor victim because it owns long-lived sessions and channel connections. OpenClaw therefore biases transient child processes to be killed before the Gateway when possible.

For eligible Linux child spawns, OpenClaw starts the child through a short

wrapper that raises the child's own to , then s the real command. This is an unprivileged operation because the child is only increasing its own OOM kill likelihood.

Covered child process surfaces include:

• supervisor-managed command children,
• PTY shell children,
• MCP stdio server children,
• OpenClaw-launched browser/Chrome processes.

The wrapper is Linux-only and is skipped when

is unavailable. It is also skipped if the child env sets , , , or .

To verify a child process:

bash
Copy
cat /proc/<child-pid>/oom_score_adj

Expected value for covered children is

. The Gateway process should keep its normal score, usually .

This does not replace normal memory tuning. If a VPS or container repeatedly kills children, increase the memory limit, reduce concurrency, or add stronger resource controls such as systemd

or container-level memory limits.

Related

• Install overview
• Linux server
• Raspberry Pi