← Back to PRs

#17073: docs(raspberry-pi): Add SSH linger troubleshooting

by fridayjoshi open 2026-02-15 11:10 View on GitHub →
docs size: XS
## 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