From d0bc359cb4e8eb49a6205347a45e84a60cbfbb2e Mon Sep 17 00:00:00 2001 From: "Brian C. Gorzelic" Date: Wed, 15 Jul 2026 05:15:01 -0500 Subject: [PATCH] docs: document Android phantom process killer fix for Termux nodes Android 12+ caps apps at 32 phantom (forked child) processes and kills the excess, causing silent gateway/sshd deaths on Termux even with a wake lock. Add a Performance Optimizations section with the adb fix (disable settings_enable_monitor_phantom_procs, pin device_config so Play Services can't reset it) plus a Troubleshooting table row. Applied and verified on the Pixel 10a (Android 16) on 2026-07-15. --- OPTIMIZATION-GUIDE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/OPTIMIZATION-GUIDE.md b/OPTIMIZATION-GUIDE.md index 531e0f9..006bff6 100644 --- a/OPTIMIZATION-GUIDE.md +++ b/OPTIMIZATION-GUIDE.md @@ -210,6 +210,31 @@ if ! pgrep -f sshd > /dev/null 2>&1; then fi ``` +### 8. Disable the Android Phantom Process Killer + +Android 12+ limits apps to 32 "phantom" (forked child) processes and kills the excess. Termux running openclaw-gateway, sshd, crond, and watchdog scripts can trip this limit, causing silent gateway deaths — the process just disappears with no error, even with a wake lock held and battery optimization disabled. + +Disable it via adb: + +```bash +adb shell settings put global settings_enable_monitor_phantom_procs false +``` + +Then prevent Play Services from resetting the flag: + +```bash +adb shell device_config set_sync_disabled_for_tests persistent +adb shell device_config put activity_manager max_phantom_processes 2147483647 +``` + +Verify: + +```bash +adb shell dumpsys activity settings | grep phantom +``` + +Applied and verified on the Pixel 10a (Android 16) on 2026-07-15. + --- ## Native Termux vs proot-distro @@ -315,6 +340,7 @@ ssh termux 'kill -9 $(pgrep -f openclaw-gateway); sleep 2; nohup openclaw gatewa | "uv_interface_addresses error 13" | Running inside proot-distro | Run gateway in native Termux instead | | SSH "too many auth failures" | Multiple SSH keys offered | Add `IdentitiesOnly yes` to SSH config | | Termux killed in background | Android battery optimization | Exempt Termux from battery optimization | +| Gateway/sshd dies randomly despite wakelock | Phantom process killer (32-process cap) | Disable via `settings_enable_monitor_phantom_procs=false` | | Gateway slow after hours | Node.js memory growth | Set `NODE_OPTIONS="--max-old-space-size=384"` | | Canvas loads but chat fails | WebSocket not connected | Check gateway logs: `tail ~/openclaw-gateway.log` |