From 1d12a844c27817fa2954c3bf0027c6c0cb1db22c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 2 Jan 2026 16:34:27 +0000
Subject: [PATCH] docs: add WhatsApp disconnect workaround to FAQ

When using macOS app with WhatsApp issues:
1. Run pnpm gateway:watch (Node instead of bun)
2. Enable 'External gateway' in app debug settings

Verified gateway:watch command exists in package.json
---
 docs/faq.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index 50134fbee..aafcd012f 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -181,6 +181,19 @@ If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemente
 
 **For debugging:** Use `pnpm gateway:watch` for live reload during development.
 
+### WhatsApp keeps disconnecting / crashing (macOS app)
+
+This is often the bun WebSocket issue. Workaround:
+
+1. Run gateway with Node instead:
+   ```bash
+   pnpm gateway:watch
+   ```
+2. In **Clawdis.app → Settings → Debug**, check **"External gateway"**
+3. The app now connects to your Node gateway instead of spawning bun
+
+This is the most stable setup until bun's WebSocket handling improves.
+
 ---
 
 ## Multi-Instance & Contexts