Skip to content

docs: document Android phantom process killer fix for Termux nodes #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bgorzelic wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document Android phantom process killer fix for Termux nodes #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions OPTIMIZATION-GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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` |

Expand Down