From fc85d5fbfe8d5b4597a57d2a2a94e5ed9f515de1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 24 Aug 2026 08:38:27 -0700
Subject: [PATCH] docs: align systemd host tuning with managed policy (#128752)

---
 docs/install/raspberry-pi.md |  4 +---
 docs/vps.md                  | 10 ++++------
 2 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/docs/install/raspberry-pi.md b/docs/install/raspberry-pi.md
index 8052fa79e0bd..d4072e02d9de 100644
--- a/docs/install/raspberry-pi.md
+++ b/docs/install/raspberry-pi.md
@@ -154,7 +154,7 @@ echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
 sudo systemctl disable bluetooth
 ```
 
-**systemd drop-in for stable restarts** -- If this Pi is mostly running OpenClaw, add a service drop-in:
+**systemd drop-in for host-specific startup tuning** -- The managed unit owns the generic restart policy (`Restart=always`, `RestartSec=5`). If this Pi is mostly running OpenClaw, add a service drop-in for host-specific startup settings only:
 
 ```bash
 systemctl --user edit openclaw-gateway.service
@@ -164,8 +164,6 @@ systemctl --user edit openclaw-gateway.service
 [Service]
 Environment=OPENCLAW_NO_RESPAWN=1
 Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
-Restart=always
-RestartSec=2
 TimeoutStartSec=90
 ```
 
diff --git a/docs/vps.md b/docs/vps.md
index 7ff15f102ffd..2f1aa59fee51 100644
--- a/docs/vps.md
+++ b/docs/vps.md
@@ -104,11 +104,12 @@ For VM hosts using `systemd`, consider:
 
 - Service env for a stable startup path: `OPENCLAW_NO_RESPAWN=1` and
   `NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache`
-- Explicit restart behavior: `Restart=always`, `RestartSec=2`, `TimeoutStartSec=90`
+- A longer startup timeout for slow hosts: `TimeoutStartSec=90`.
+- The managed unit owns the generic restart policy: `Restart=always`, `RestartSec=5`.
 - SSD-backed disks for state/cache paths to reduce random-I/O cold-start penalties.
 
 The standard `openclaw onboard --install-daemon` path installs a systemd user
-unit; edit it with:
+unit; customize only host-specific startup settings with:
 
 ```bash
 systemctl --user edit openclaw-gateway.service
@@ -118,16 +119,13 @@ systemctl --user edit openclaw-gateway.service
 [Service]
 Environment=OPENCLAW_NO_RESPAWN=1
 Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
-Restart=always
-RestartSec=2
 TimeoutStartSec=90
 ```
 
 If you deliberately installed a system unit instead, edit it via
 `sudo systemctl edit openclaw-gateway.service`.
 
-How `Restart=` policies help automated recovery:
-[systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery).
+For the canonical managed unit body and its restart policy, see the [Gateway runbook](/gateway).
 
 For Linux OOM behavior, child process victim selection, and `exit 137`
 diagnostics, see [Linux memory pressure and OOM kills](/platforms/linux#memory-pressure-and-oom-kills).