From 7eef176afc0a64e88b5fdc4a034d45a213319b61 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 22 Jan 2026 00:21:04 +0000
Subject: [PATCH] fix: warn on unset gateway.mode

---
 CHANGELOG.md                    |  8 ++++++++
 docs/gateway/troubleshooting.md | 28 ++++++++++++++++++++++++++++
 src/commands/doctor.ts          | 13 +++++++++++++
 3 files changed, 49 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ecf10530a..40e4b141a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,14 @@ Docs: https://docs.clawd.bot
 - BlueBubbles: resolve short message IDs safely and expose full IDs in templates. (#1387) Thanks @tyler6204.
 - Infra: preserve fetch helper methods when wrapping abort signals. (#1387)
 
+## 2026.1.22
+
+### Changes
+- Docs: add troubleshooting entry for gateway.mode blocking gateway start. https://docs.clawd.bot/gateway/troubleshooting
+
+### Fixes
+- Doctor: warn when gateway.mode is unset with configure/config guidance.
+
 ## 2026.1.20
 
 ### Changes
diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index 803360439..1e9f595a7 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -82,6 +82,34 @@ Doctor/service will show runtime state (PID/last exit) and log hints.
 
 See [/logging](/logging) for a full overview of formats, config, and access.
 
+### "Gateway start blocked: set gateway.mode=local"
+
+This means the config exists but `gateway.mode` is unset (or not `local`), so the
+Gateway refuses to start.
+
+**Fix (recommended):**
+- Run the wizard and set the Gateway run mode to **Local**:
+  ```bash
+  clawdbot configure
+  ```
+- Or set it directly:
+  ```bash
+  clawdbot config set gateway.mode local
+  ```
+
+**If you meant to run a remote Gateway instead:**
+- Set a remote URL and keep `gateway.mode=remote`:
+  ```bash
+  clawdbot config set gateway.mode remote
+  clawdbot config set gateway.remote.url "wss://gateway.example.com"
+  ```
+
+**Ad-hoc/dev only:** pass `--allow-unconfigured` to start the gateway without
+`gateway.mode=local`.
+
+**No config file yet?** Run `clawdbot setup` to create a starter config, then rerun
+the gateway.
+
 ### Service Environment (PATH + runtime)
 
 The gateway service runs with a **minimal PATH** to avoid shell/manager cruft:
diff --git a/src/commands/doctor.ts b/src/commands/doctor.ts
index 2bc17db11..0ec3bd296 100644
--- a/src/commands/doctor.ts
+++ b/src/commands/doctor.ts
@@ -87,6 +87,19 @@ export async function doctorCommand(
   });
   let cfg: ClawdbotConfig = configResult.cfg;
 
+  const configPath = configResult.path ?? CONFIG_PATH_CLAWDBOT;
+  if (!cfg.gateway?.mode) {
+    const lines = [
+      "gateway.mode is unset; gateway start will be blocked.",
+      `Fix: run ${formatCliCommand("clawdbot configure")} and set Gateway mode (local/remote).`,
+      `Or set directly: ${formatCliCommand("clawdbot config set gateway.mode local")}`,
+    ];
+    if (!fs.existsSync(configPath)) {
+      lines.push(`Missing config: run ${formatCliCommand("clawdbot setup")} first.`);
+    }
+    note(lines.join("\n"), "Gateway");
+  }
+
   cfg = await maybeRepairAnthropicOAuthProfileId(cfg, prompter);
   await noteAuthProfileHealth({
     cfg,