fix: warn on unset gateway.mode

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

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:

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,