From 0182dd16949bb61835a27341bfc753156ecc047f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 10:27:09 +0100
Subject: [PATCH] docs: refresh linux service docs

---
 docs/install/raspberry-pi.md   |  6 +++---
 docs/platforms/digitalocean.md |  2 +-
 docs/platforms/raspberry-pi.md | 33 ++++++++++++++++++++-------------
 docs/vps.md                    |  7 +++++--
 4 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/docs/install/raspberry-pi.md b/docs/install/raspberry-pi.md
index 49e3d63b8dc..045dc65ab34 100644
--- a/docs/install/raspberry-pi.md
+++ b/docs/install/raspberry-pi.md
@@ -95,8 +95,8 @@ Run a persistent, always-on OpenClaw Gateway on a Raspberry Pi. Since the Pi is
   <Step title="Verify">
     ```bash
     openclaw status
-    sudo systemctl status openclaw
-    journalctl -u openclaw -f
+    systemctl --user status openclaw-gateway.service
+    journalctl --user -u openclaw-gateway.service -f
     ```
   </Step>
 
@@ -146,7 +146,7 @@ sudo systemctl disable bluetooth
 
 **Slow performance** -- Use a USB SSD instead of an SD card. Check for CPU throttling with `vcgencmd get_throttled` (should return `0x0`).
 
-**Service will not start** -- Check logs with `journalctl -u openclaw --no-pager -n 100` and run `openclaw doctor --non-interactive`.
+**Service will not start** -- Check logs with `journalctl --user -u openclaw-gateway.service --no-pager -n 100` and run `openclaw doctor --non-interactive`. If this is a headless Pi, also verify lingering is enabled: `sudo loginctl enable-linger "$(whoami)"`.
 
 **ARM binary issues** -- If a skill fails with "exec format error", check whether the binary has an ARM64 build. Verify architecture with `uname -m` (should show `aarch64`).
 
diff --git a/docs/platforms/digitalocean.md b/docs/platforms/digitalocean.md
index ff0921fd062..9514e366b45 100644
--- a/docs/platforms/digitalocean.md
+++ b/docs/platforms/digitalocean.md
@@ -236,7 +236,7 @@ For the full setup guide, see [Oracle Cloud](/platforms/oracle). For signup tips
 ```bash
 openclaw gateway status
 openclaw doctor --non-interactive
-journalctl -u openclaw --no-pager -n 50
+journalctl --user -u openclaw-gateway.service --no-pager -n 50
 ```
 
 ### Port already in use
diff --git a/docs/platforms/raspberry-pi.md b/docs/platforms/raspberry-pi.md
index 7b82cb119ae..abf41402d65 100644
--- a/docs/platforms/raspberry-pi.md
+++ b/docs/platforms/raspberry-pi.md
@@ -146,11 +146,11 @@ Follow the wizard:
 # Check status
 openclaw status
 
-# Check service
-sudo systemctl status openclaw
+# Check service (standard install = systemd user unit)
+systemctl --user status openclaw-gateway.service
 
 # View logs
-journalctl -u openclaw -f
+journalctl --user -u openclaw-gateway.service -f
 ```
 
 ## 9) Access the OpenClaw Dashboard
@@ -221,7 +221,7 @@ If this Pi is mostly running OpenClaw, add a service drop-in to reduce restart
 jitter and keep startup env stable:
 
 ```bash
-sudo systemctl edit openclaw
+systemctl --user edit openclaw-gateway.service
 ```
 
 ```ini
@@ -236,13 +236,20 @@ TimeoutStartSec=90
 Then apply:
 
 ```bash
-sudo systemctl daemon-reload
-sudo systemctl restart openclaw
+systemctl --user daemon-reload
+systemctl --user restart openclaw-gateway.service
 ```
 
 If possible, keep OpenClaw state/cache on SSD-backed storage to avoid SD-card
 random-I/O bottlenecks during cold starts.
 
+If this is a headless Pi, enable lingering once so the user service survives
+logout:
+
+```bash
+sudo loginctl enable-linger "$(whoami)"
+```
+
 How `Restart=` policies help automated recovery:
 [systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery).
 
@@ -307,8 +314,8 @@ Since the Pi is just the Gateway (models run in the cloud), use API-based models
   "agents": {
     "defaults": {
       "model": {
-        "primary": "anthropic/claude-sonnet-4-20250514",
-        "fallbacks": ["openai/gpt-4o-mini"]
+        "primary": "anthropic/claude-sonnet-4-6",
+        "fallbacks": ["openai/gpt-5.4-mini"]
       }
     }
   }
@@ -325,13 +332,13 @@ Onboarding sets this up, but to verify:
 
 ```bash
 # Check service is enabled
-sudo systemctl is-enabled openclaw
+systemctl --user is-enabled openclaw-gateway.service
 
 # Enable if not
-sudo systemctl enable openclaw
+systemctl --user enable openclaw-gateway.service
 
 # Start on boot
-sudo systemctl start openclaw
+systemctl --user start openclaw-gateway.service
 ```
 
 ---
@@ -358,12 +365,12 @@ free -h
 
 ```bash
 # Check logs
-journalctl -u openclaw --no-pager -n 100
+journalctl --user -u openclaw-gateway.service --no-pager -n 100
 
 # Common fix: rebuild
 cd ~/openclaw  # if using hackable install
 npm run build
-sudo systemctl restart openclaw
+systemctl --user restart openclaw-gateway.service
 ```
 
 ### ARM Binary Issues
diff --git a/docs/vps.md b/docs/vps.md
index 4a1eb692c85..8682327c7f4 100644
--- a/docs/vps.md
+++ b/docs/vps.md
@@ -93,10 +93,10 @@ For VM hosts using `systemd`, consider:
   - `TimeoutStartSec=90`
 - Prefer SSD-backed disks for state/cache paths to reduce random-I/O cold-start penalties.
 
-Example:
+For the standard `openclaw onboard --install-daemon` path, edit the user unit:
 
 ```bash
-sudo systemctl edit openclaw
+systemctl --user edit openclaw-gateway.service
 ```
 
 ```ini
@@ -108,5 +108,8 @@ RestartSec=2
 TimeoutStartSec=90
 ```
 
+If you deliberately installed a system unit instead, edit
+`openclaw-gateway.service` 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).