diff --git a/README.md b/README.md index d6a67e66..237fcbdf 100644 --- a/README.md +++ b/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) > diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 05f75904..13bf99bb 100644 --- a/docs/architecture/README.md +++ b/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 diff --git a/docs/openclaw_gateway_base_config.md b/docs/openclaw_gateway_base_config.md new file mode 100644 index 00000000..dfd20af0 --- /dev/null +++ b/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.