openclaw/docs/platforms/linux.md at 75cd0efb0454c5d7704887b87995eda18ca61652

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-22 20:01:09 +00:00

Files

Peter Steinberger ad8107e136 feat(linux): ship deb/AppImage bundles on stable main-based releases (#106891 )

* feat(linux): attach deb/AppImage bundles to main-based releases

* fix(linux): stamp release version into bundles and verify deb metadata

* fix(linux): stable-only release tags and ubuntu-22.04 glibc build floor

* docs(linux): document AppImage FUSE prerequisite

* fix(linux): allow numeric stable revision tags in release workflow

2026-07-13 16:31:09 -07:00

5.5 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

Linux support + companion app status

Looking for Linux companion app status

Planning platform coverage or contributions

Debugging Linux OOM kills or exit 137 on a VPS or container

Linux app

The Gateway is fully supported on Linux and requires Node. Bun can still be used as a dependency installer or package-script runner, but it cannot run OpenClaw because it does not provide node:sqlite.

Desktop companion

The OpenClaw Linux companion is a Tauri desktop app for a local Gateway. It:

installs the OpenClaw CLI and managed Node runtime when they are missing
attaches to a healthy Gateway before attempting service changes
delegates install, start, stop, and restart operations to the CLI-managed systemd user service
opens the Gateway-served Control UI with its resolved authentication URL
remains available from the system tray when its window is closed

Stable releases built from main ship .deb and AppImage bundles as assets on the GitHub release for the tag, named OpenClaw-<version>-amd64.deb and OpenClaw-<version>-amd64.AppImage, with a SHA256SUMS.linux-app.txt checksum file next to them. Download the .deb and install it with sudo apt install ./OpenClaw-<version>-amd64.deb, or mark the AppImage executable and run it directly. The AppImage runtime needs FUSE 2 (sudo apt install libfuse2, or libfuse2t64 on Ubuntu 24.04+); without it, run the AppImage with APPIMAGE_EXTRACT_AND_RUN=1.

You can also build the same bundles from a source checkout:

cd apps/linux/src-tauri
pnpm dlx @tauri-apps/cli@2.11.4 build --bundles deb,appimage

The Linux App CI workflow uploads the same bundles as the openclaw-linux-companion artifact for pull requests touching the app and for manual runs. See apps/linux/README.md in the repository for Linux build dependencies and development commands.

CLI and SSH alternative

The CLI remains the simplest option for a headless server, a VPS, or a remote Gateway:

Install Node 24.15+ (recommended), Node 22.22.3+ (LTS), or Node 25.9+.
npm i -g openclaw@latest
openclaw onboard --install-daemon
From your laptop: ssh -N -L 18789:127.0.0.1:18789 <user>@<host>
Open http://127.0.0.1:18789/ and authenticate with the configured shared secret (token by default; password if gateway.auth.mode is "password").

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

Install

Getting Started
Install & updates
Optional: Bun package workflow, Nix, Docker

Gateway service (systemd)

Install with one of:

openclaw onboard --install-daemon
openclaw gateway install
openclaw configure   # select "Gateway service" when prompted

Repair or migrate an existing install:

openclaw doctor

openclaw gateway install renders a systemd user unit by default. Full service guidance, including the system-level unit variant for shared or always-on hosts, lives in the Gateway runbook.

Write a unit by hand only for a custom setup. Minimal user-unit example (~/.config/systemd/user/openclaw-gateway[-<profile>].service):

[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target
StartLimitBurst=5
StartLimitIntervalSec=60

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

[Install]
WantedBy=default.target

Enable it:

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

Memory pressure and OOM kills

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

For eligible Linux child spawns, OpenClaw wraps the command in a short /bin/sh shim that raises the child's own oom_score_adj to 1000, then execs the real command. This is unprivileged: a process may always raise its own OOM score.

Covered child process surfaces:

Supervisor-managed command children
PTY shell children
MCP stdio server children
OpenClaw-launched browser/Chrome processes (via the plugin SDK process runtime)

The wrapper is Linux-only and skipped when /bin/sh is unavailable, or when the child env sets OPENCLAW_CHILD_OOM_SCORE_ADJ to 0, false, no, or off.

Verify a child process:

cat /proc/<child-pid>/oom_score_adj

Expected value for covered children is 1000; the Gateway process itself keeps its normal score (usually 0).

The systemd unit's OOMPolicy=continue keeps the Gateway service alive when a transient child is selected by the OOM killer instead of marking the whole unit failed and restarting all channels; the failed child/session reports its own error.

This does not replace normal memory tuning. If a VPS or container repeatedly kills children, raise the memory limit, reduce concurrency, or add stronger resource controls (systemd MemoryMax=, container memory limits).

5.5 KiB Raw Blame History