#17073: docs(raspberry-pi): Add SSH linger troubleshooting
docs
size: XS
Cluster:
Windows Path and Exec Fixes
## Problem
Addresses #17069 - OpenClaw Gateway service dies when SSH session closes on Raspberry Pi setups.
## Solution
Added troubleshooting section to explaining:
- **Root cause**: systemd's kills user services on logout
- **Fix**: to persist user session
- **Verification**: How to check if linger is needed
- **Context**: Critical for headless Pi deployments accessed via SSH
## Impact
This is a common pain point for SSH-based Pi deployments. Without linger enabled, the Gateway service stops unexpectedly every time the user disconnects from SSH, breaking the "always-on" nature of the deployment.
## Testing
Tested on Raspberry Pi 5 (ARM64) running Debian Linux, accessed via SSH. Verified that:
1. Service stops on logout without linger
2. Service persists after enabling linger
3. Instructions are clear and work as documented
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds a troubleshooting section to the Raspberry Pi docs explaining why the OpenClaw Gateway service dies when SSH sessions close and how to fix it with `loginctl enable-linger`. The new section correctly uses `systemctl --user restart openclaw-gateway`, consistent with how the codebase installs the service (as a systemd user unit via `src/daemon/systemd.ts`).
- The root cause explanation (`KillUserProcesses=yes`) is accurate and well-articulated
- The diagnostic command (`loginctl show-user $USER | grep Linger`) and fix (`sudo loginctl enable-linger $USER`) are correct
- The restart command in the new section correctly targets `openclaw-gateway` via `systemctl --user`, matching the actual service name in `src/daemon/constants.ts`
- No issues found in the new content
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge — it adds a well-written, technically accurate documentation section with no code changes.
- This is a docs-only change adding a single troubleshooting section. The commands are correct and match the codebase's actual systemd user service implementation. The linger mechanism is accurately described, and the section fills a genuine gap in the documentation for headless Pi deployments.
- No files require special attention.
<sub>Last reviewed commit: b1ff6b5</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#17099: docs(pi): add loginctl enable-linger instruction for SSH persistence
by Limitless2023 · 2026-02-15
85.8%
#18792: docs: add macOS source-run troubleshooting for setup/auth issues
by yash27-lab · 2026-02-17
70.7%
#20698: docs: add production VPS deployment guide
by aiagentswiz · 2026-02-19
69.7%
#21212: fix: detect and manage systemd system services (rebased)
by growthringsadvisory · 2026-02-19
69.6%
#16016: fix: update systemd unit version on gateway restart
by jbold · 2026-02-14
69.0%
#16251: docs: remove note about personal single-user access from trusted pr...
by nickytonline · 2026-02-14
69.0%
#21934: fix #21914 - Add the most obvious option to the error message
by vivganes · 2026-02-20
69.0%
#5036: docs: improve Slack setup and troubleshooting guide
by DanBatten · 2026-01-31
68.9%
#23666: fix(doctor): openclaw-browser.service falsely flagged as duplicate ...
by yinghaosang · 2026-02-22
68.9%
#14259: fix(discord): add timeout to restart to prevent duplicate responses
by George5562 · 2026-02-11
68.6%