From 7dc8ea815e4cee670c8fb085284d23f77e81600b Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Sun, 4 Jan 2026 20:10:20 +0300
Subject: [PATCH] docs: add macOS launchd instructions for stopping gateway

Unify the "Processes keep restarting" FAQ section to cover both macOS
(launchd) and Linux (systemd). Previously only covered Linux.

Also update the "Clean uninstall" section with macOS commands.
---
 docs/faq.md | 51 +++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 37 insertions(+), 14 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index 126f1d423..2f2266ba2 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -446,31 +446,54 @@ cd ~/path/to/clawdbot
 codex --full-auto "debug why clawdbot gateway won't start"
 ```
 
-### Processes keep restarting after I kill them (Linux)
+### Processes keep restarting after I kill them
 
-Something is supervising them. Check:
+The gateway runs under a supervisor that auto-restarts it. You need to stop the supervisor, not just kill the process.
+
+**macOS (launchd)**
 
 ```bash
-# systemd?
-systemctl list-units | grep -i clawdbot
-sudo systemctl stop clawdbot
+# Check if running
+launchctl list | grep clawdbot
 
-# pm2?
-pm2 list
-pm2 delete all
+# Stop and disable
+launchctl disable gui/$UID/com.clawdbot.gateway
+launchctl bootout gui/$UID/com.clawdbot.gateway
+
+# Re-enable later
+launchctl enable gui/$UID/com.clawdbot.gateway
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.gateway.plist
 ```
 
-Stop the supervisor first, then the processes.
+**Linux (systemd)**
+
+```bash
+# Check if running
+systemctl list-units | grep -i clawdbot
+
+# Stop and disable
+sudo systemctl disable --now clawdbot
+```
+
+**pm2 (if used)**
+
+```bash
+pm2 list
+pm2 delete clawdbot
+```
 
 ### Clean uninstall (start fresh)
 
 ```bash
-# Stop processes
-pkill -f "clawdbot"
+# macOS: stop launchd service
+launchctl disable gui/$UID/com.clawdbot.gateway
+launchctl bootout gui/$UID/com.clawdbot.gateway 2>/dev/null
 
-# If using systemd
-sudo systemctl stop clawdbot
-sudo systemctl disable clawdbot
+# Linux: stop systemd service
+sudo systemctl disable --now clawdbot
+
+# Kill any remaining processes
+pkill -f "clawdbot"
 
 # Remove data
 rm -rf ~/.clawdbot