docs: add base gateway configuration for local development

README.md

@@ -15,6 +15,7 @@ OpenClaw Mission Control is under active development. Expect breaking changes an
 - **Backend:** FastAPI service (default http://localhost:8000)
 - **Data:** Postgres
 - **Gateway integration:** see [`docs/openclaw_gateway_ws.md`](./docs/openclaw_gateway_ws.md)
+- **Gateway base config (local):** see [`docs/openclaw_gateway_base_config.md`](./docs/openclaw_gateway_base_config.md)
 
 > Note on auth (Clerk)
 >

docs/architecture/README.md

@@ -54,6 +54,7 @@ Mission Control can call into an OpenClaw Gateway over WebSockets.
 - Client: `backend/app/integrations/openclaw_gateway.py`
 - Known methods/events: `backend/app/integrations/openclaw_gateway_protocol.py`
 - Protocol doc: `docs/openclaw_gateway_ws.md`
+- Base gateway config (getting started): `docs/openclaw_gateway_base_config.md`
 
 ## Request flows
 

docs/openclaw_gateway_base_config.md

@@ -0,0 +1,167 @@
+# OpenClaw Gateway Base Config (Local)
+
+This document explains a "base" OpenClaw Gateway config intended for local development and LAN use, and how to connect it to Mission Control.
+
+Related:
+- Gateway WebSocket protocol: `docs/openclaw_gateway_ws.md` (default URL `ws://127.0.0.1:18789`)
+- Mission Control architecture (gateway integration): `docs/architecture/README.md`
+
+## Who This Is For
+
+Use this config if you want:
+- A gateway listening locally (and optionally on your LAN)
+- A predictable workspace location for agents/sessions
+- A small, readable starting point you can extend
+
+## Base Config (Template)
+
+Start from this template and change the values in **Required edits**.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "openai-codex/gpt-5.2"
+      },
+      "models": {
+        "openai-codex/gpt-5.2": {}
+      },
+      "workspace": "~/.openclaw/workspace",
+      "compaction": {
+        "mode": "safeguard"
+      },
+      "thinkingDefault": "minimal",
+      "maxConcurrent": 4,
+      "subagents": {
+        "maxConcurrent": 8
+      }
+    }
+  },
+  "gateway": {
+    "port": 18789,
+    "mode": "local",
+    "bind": "lan",
+    "controlUi": {
+      "allowInsecureAuth": true
+    },
+    "tailscale": {
+      "mode": "off",
+      "resetOnExit": false
+    },
+    "reload": {
+      "mode": "hot",
+      "debounceMs": 750
+    }
+  },
+  "memory": {
+    "backend": "qmd",
+    "citations": "auto",
+    "qmd": {
+      "includeDefaultMemory": true,
+      "update": {
+        "interval": "15m",
+        "debounceMs": 15000,
+        "onBoot": true
+      },
+      "limits": {
+        "maxResults": 6,
+        "maxSnippetChars": 900,
+        "maxInjectedChars": 4500,
+        "timeoutMs": 4000
+      }
+    }
+  },
+  "skills": {
+    "install": {
+      "nodeManager": "npm"
+    }
+  }
+}
+```
+
+### Required Edits
+
+1. `agents.defaults.workspace`
+   - Set a directory the gateway can read/write.
+   - Recommended default is `~/.openclaw/workspace` (Mission Control defaults the "workspace root" UI to `~/.openclaw`).
+
+### Optional Edits (Common)
+
+- `gateway.bind`
+  - `"lan"` is convenient for reaching the gateway from another machine on your network.
+  - If you want local-only access, configure your gateway to bind only to localhost/loopback (exact values depend on the gateway build) and/or firewall the port.
+- `gateway.port`
+  - Change if `18789` is already in use.
+  - Mission Control requires the URL to include an explicit port (example: `ws://127.0.0.1:18789`).
+- `agents.defaults.model.primary`
+  - Set your preferred default model identifier.
+- `memory.qmd.limits`
+  - Tune memory query/injection sizes if you see timeouts or overly-large prompts.
+
+## What Each Top-Level Section Does
+
+### `agents.defaults`
+
+Default runtime behavior for agents created/managed by the gateway:
+- `model.primary`: default model identifier
+- `models`: per-model overrides (empty means "use provider defaults")
+- `workspace`: where agent state/files live on disk
+- `compaction.mode: "safeguard"`: enables conservative compaction behavior
+- `thinkingDefault: "minimal"`: default "thinking" level
+- `maxConcurrent`: max concurrent top-level runs
+- `subagents.maxConcurrent`: max concurrent subagent runs
+
+### `gateway`
+
+Network/runtime settings for the gateway service itself:
+- `port`: TCP port for the WebSocket server (protocol doc defaults to `18789`)
+- `mode: "local"`: local mode (vs remote-managed)
+- `bind: "lan"`: binds in a way that's reachable from your LAN (treat as "network exposed")
+- `controlUi.allowInsecureAuth: true`: convenience for local dev; do not use as-is for production
+- `tailscale.mode: "off"`: disables Tailscale integration by default
+- `reload.mode: "hot"` + `reload.debounceMs`: enables hot reload of config with a debounce window
+
+### `memory`
+
+Configures the gateway's memory subsystem.
+- `backend: "qmd"`: use the QMD backend
+- `citations: "auto"`: automatically include citations when supported
+- `qmd.includeDefaultMemory`: includes default memory sources
+- `qmd.update`: periodic update settings
+- `qmd.limits`: bounds for query size/latency and injected context
+
+### `skills.install.nodeManager`
+
+Controls which Node package manager is used for skill installation.
+- `"npm"` is the most compatible baseline.
+
+## Connecting Mission Control To The Gateway
+
+Mission Control connects over WebSockets and supports passing a token.
+
+What Mission Control expects:
+- Gateway URL must be `ws://...` or `wss://...` and must include an explicit port.
+- Token is optional. Empty/whitespace tokens are treated as "no token" by the Mission Control API.
+
+In the Mission Control UI:
+1. Go to "Gateways" and add a new gateway.
+2. Set URL to something like `ws://127.0.0.1:18789` (or your LAN host/IP + port).
+3. If your gateway is configured to require a token, paste it here. Otherwise leave blank.
+4. Use the "Check connection" action to confirm reachability.
+
+Implementation note (how Mission Control sends tokens):
+- If you provide a token, Mission Control's backend will include it when connecting to the gateway (it attaches it to the URL query string and also sends it in the `connect` params). See `backend/app/integrations/openclaw_gateway.py`.
+
+### Workspace Root (Mission Control) vs Workspace (Gateway)
+
+Mission Control stores a `workspace_root` value per gateway (configured in the UI). This is used when generating agent context/templates (for example, to compute a per-agent `workspace_path`). See `backend/app/services/openclaw/provisioning.py`.
+
+The gateway config's `agents.defaults.workspace` is a separate setting that controls where the gateway runtime actually reads/writes agent state on disk.
+
+For the smoothest onboarding, set these so the paths you show agents match what exists on the gateway host.
+
+## Security Notes (Read This If You Expose The Gateway)
+
+- Treat `gateway.bind: "lan"` as "this is reachable by other devices on your network".
+- `controlUi.allowInsecureAuth: true` is for convenience in local dev. If you run this beyond your laptop, tighten this setting and prefer TLS (`wss://`) and network-level protections.