@quantumclaw/quantumclaw 2026.3.22

package/docs/gateway/local-models.md

@@ -0,0 +1,152 @@
+---
+summary: "Run QuantumClaw on local LLMs (LM Studio, vLLM, LiteLLM, custom OpenAI endpoints)"
+read_when:
+  - You want to serve models from your own GPU box
+  - You are wiring LM Studio or an OpenAI-compatible proxy
+  - You need the safest local model guidance
+title: "Local Models"
+---
+
+# Local models
+
+Local is doable, but QuantumClaw expects large context + strong defenses against prompt injection. Small cards truncate context and leak safety. Aim high: **≥2 maxed-out Mac Studios or equivalent GPU rig (~$30k+)**. A single **24 GB** GPU works only for lighter prompts with higher latency. Use the **largest / full-size model variant you can run**; aggressively quantized or “small” checkpoints raise prompt-injection risk (see [Security](/gateway/security)).
+
+If you want the lowest-friction local setup, start with [Ollama](/providers/ollama) and `quantumclaw onboard`. This page is the opinionated guide for higher-end local stacks and custom OpenAI-compatible local servers.
+
+## Recommended: LM Studio + MiniMax M2.5 (Responses API, full-size)
+
+Best current local stack. Load MiniMax M2.5 in LM Studio, enable the local server (default `http://127.0.0.1:1234`), and use Responses API to keep reasoning separate from final text.
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "lmstudio/minimax-m2.5-gs32" },
+      models: {
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+        "lmstudio/minimax-m2.5-gs32": { alias: "Minimax" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      lmstudio: {
+        baseUrl: "http://127.0.0.1:1234/v1",
+        apiKey: "lmstudio",
+        api: "openai-responses",
+        models: [
+          {
+            id: "minimax-m2.5-gs32",
+            name: "MiniMax M2.5 GS32",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 196608,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+**Setup checklist**
+
+- Install LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
+- In LM Studio, download the **largest MiniMax M2.5 build available** (avoid “small”/heavily quantized variants), start the server, confirm `http://127.0.0.1:1234/v1/models` lists it.
+- Keep the model loaded; cold-load adds startup latency.
+- Adjust `contextWindow`/`maxTokens` if your LM Studio build differs.
+- For WhatsApp, stick to Responses API so only final text is sent.
+
+Keep hosted models configured even when running local; use `models.mode: "merge"` so fallbacks stay available.
+
+### Hybrid config: hosted primary, local fallback
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-sonnet-4-6",
+        fallbacks: ["lmstudio/minimax-m2.5-gs32", "anthropic/claude-opus-4-6"],
+      },
+      models: {
+        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
+        "lmstudio/minimax-m2.5-gs32": { alias: "MiniMax Local" },
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      lmstudio: {
+        baseUrl: "http://127.0.0.1:1234/v1",
+        apiKey: "lmstudio",
+        api: "openai-responses",
+        models: [
+          {
+            id: "minimax-m2.5-gs32",
+            name: "MiniMax M2.5 GS32",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 196608,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### Local-first with hosted safety net
+
+Swap the primary and fallback order; keep the same providers block and `models.mode: "merge"` so you can fall back to Sonnet or Opus when the local box is down.
+
+### Regional hosting / data routing
+
+- Hosted MiniMax/Kimi/GLM variants also exist on OpenRouter with region-pinned endpoints (e.g., US-hosted). Pick the regional variant there to keep traffic in your chosen jurisdiction while still using `models.mode: "merge"` for Anthropic/OpenAI fallbacks.
+- Local-only remains the strongest privacy path; hosted regional routing is the middle ground when you need provider features but want control over data flow.
+
+## Other OpenAI-compatible local proxies
+
+vLLM, LiteLLM, OAI-proxy, or custom gateways work if they expose an OpenAI-style `/v1` endpoint. Replace the provider block above with your endpoint and model ID:
+
+```json5
+{
+  models: {
+    mode: "merge",
+    providers: {
+      local: {
+        baseUrl: "http://127.0.0.1:8000/v1",
+        apiKey: "sk-local",
+        api: "openai-responses",
+        models: [
+          {
+            id: "my-local-model",
+            name: "Local Model",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 120000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+Keep `models.mode: "merge"` so hosted models stay available as fallbacks.
+
+## Troubleshooting
+
+- Gateway can reach the proxy? `curl http://127.0.0.1:1234/v1/models`.
+- LM Studio model unloaded? Reload; cold start is a common “hanging” cause.
+- Context errors? Lower `contextWindow` or raise your server limit.
+- Safety: local models skip provider-side filters; keep agents narrow and compaction on to limit prompt injection blast radius.

package/docs/gateway/logging.md

@@ -0,0 +1,113 @@
+---
+summary: "Logging surfaces, file logs, WS log styles, and console formatting"
+read_when:
+  - Changing logging output or formats
+  - Debugging CLI or gateway output
+title: "Logging"
+---
+
+# Logging
+
+For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
+
+QuantumClaw has two log “surfaces”:
+
+- **Console output** (what you see in the terminal / Debug UI).
+- **File logs** (JSON lines) written by the gateway logger.
+
+## File-based logger
+
+- Default rolling log file is under `/tmp/quantumclaw/` (one file per day): `quantumclaw-YYYY-MM-DD.log`
+  - Date uses the gateway host's local timezone.
+- The log file path and level can be configured via `~/.quantumclaw/quantumclaw.json`:
+  - `logging.file`
+  - `logging.level`
+
+The file format is one JSON object per line.
+
+The Control UI Logs tab tails this file via the gateway (`logs.tail`).
+CLI can do the same:
+
+```bash
+quantumclaw logs --follow
+```
+
+**Verbose vs. log levels**
+
+- **File logs** are controlled exclusively by `logging.level`.
+- `--verbose` only affects **console verbosity** (and WS log style); it does **not**
+  raise the file log level.
+- To capture verbose-only details in file logs, set `logging.level` to `debug` or
+  `trace`.
+
+## Console capture
+
+The CLI captures `console.log/info/warn/error/debug/trace` and writes them to file logs,
+while still printing to stdout/stderr.
+
+You can tune console verbosity independently via:
+
+- `logging.consoleLevel` (default `info`)
+- `logging.consoleStyle` (`pretty` | `compact` | `json`)
+
+## Tool summary redaction
+
+Verbose tool summaries (e.g. `🛠️ Exec: ...`) can mask sensitive tokens before they hit the
+console stream. This is **tools-only** and does not alter file logs.
+
+- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
+- `logging.redactPatterns`: array of regex strings (overrides defaults)
+  - Use raw regex strings (auto `gi`), or `/pattern/flags` if you need custom flags.
+  - Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise `***`.
+  - Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, and popular token prefixes.
+
+## Gateway WebSocket logs
+
+The gateway prints WebSocket protocol logs in two modes:
+
+- **Normal mode (no `--verbose`)**: only “interesting” RPC results are printed:
+  - errors (`ok=false`)
+  - slow calls (default threshold: `>= 50ms`)
+  - parse errors
+- **Verbose mode (`--verbose`)**: prints all WS request/response traffic.
+
+### WS log style
+
+`quantumclaw gateway` supports a per-gateway style switch:
+
+- `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
+- `--ws-log compact`: compact output (paired request/response) when verbose
+- `--ws-log full`: full per-frame output when verbose
+- `--compact`: alias for `--ws-log compact`
+
+Examples:
+
+```bash
+# optimized (only errors/slow)
+quantumclaw gateway
+
+# show all WS traffic (paired)
+quantumclaw gateway --verbose --ws-log compact
+
+# show all WS traffic (full meta)
+quantumclaw gateway --verbose --ws-log full
+```
+
+## Console formatting (subsystem logging)
+
+The console formatter is **TTY-aware** and prints consistent, prefixed lines.
+Subsystem loggers keep output grouped and scannable.
+
+Behavior:
+
+- **Subsystem prefixes** on every line (e.g. `[gateway]`, `[canvas]`, `[tailscale]`)
+- **Subsystem colors** (stable per subsystem) plus level coloring
+- **Color when output is a TTY or the environment looks like a rich terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respects `NO_COLOR`
+- **Shortened subsystem prefixes**: drops leading `gateway/` + `channels/`, keeps last 2 segments (e.g. `whatsapp/outbound`)
+- **Sub-loggers by subsystem** (auto prefix + structured field `{ subsystem }`)
+- **`logRaw()`** for QR/UX output (no prefix, no formatting)
+- **Console styles** (e.g. `pretty | compact | json`)
+- **Console log level** separate from file log level (file keeps full detail when `logging.level` is set to `debug`/`trace`)
+- **WhatsApp message bodies** are logged at `debug` (use `--verbose` to see them)
+
+This keeps existing file logs stable while making interactive output scannable.

package/docs/gateway/multiple-gateways.md

@@ -0,0 +1,112 @@
+---
+summary: "Run multiple QuantumClaw Gateways on one host (isolation, ports, and profiles)"
+read_when:
+  - Running more than one Gateway on the same machine
+  - You need isolated config/state/ports per Gateway
+title: "Multiple Gateways"
+---
+
+# Multiple Gateways (same host)
+
+Most setups should use one Gateway because a single Gateway can handle multiple messaging connections and agents. If you need stronger isolation or redundancy (e.g., a rescue bot), run separate Gateways with isolated profiles/ports.
+
+## Isolation checklist (required)
+
+- `QUANTUMCLAW_CONFIG_PATH` — per-instance config file
+- `QUANTUMCLAW_STATE_DIR` — per-instance sessions, creds, caches
+- `agents.defaults.workspace` — per-instance workspace root
+- `gateway.port` (or `--port`) — unique per instance
+- Derived ports (browser/canvas) must not overlap
+
+If these are shared, you will hit config races and port conflicts.
+
+## Recommended: profiles (`--profile`)
+
+Profiles auto-scope `QUANTUMCLAW_STATE_DIR` + `QUANTUMCLAW_CONFIG_PATH` and suffix service names.
+
+```bash
+# main
+quantumclaw --profile main setup
+quantumclaw --profile main gateway --port 18789
+
+# rescue
+quantumclaw --profile rescue setup
+quantumclaw --profile rescue gateway --port 19001
+```
+
+Per-profile services:
+
+```bash
+quantumclaw --profile main gateway install
+quantumclaw --profile rescue gateway install
+```
+
+## Rescue-bot guide
+
+Run a second Gateway on the same host with its own:
+
+- profile/config
+- state dir
+- workspace
+- base port (plus derived ports)
+
+This keeps the rescue bot isolated from the main bot so it can debug or apply config changes if the primary bot is down.
+
+Port spacing: leave at least 20 ports between base ports so the derived browser/canvas/CDP ports never collide.
+
+### How to install (rescue bot)
+
+```bash
+# Main bot (existing or fresh, without --profile param)
+# Runs on port 18789 + Chrome CDC/Canvas/... Ports
+quantumclaw onboard
+quantumclaw gateway install
+
+# Rescue bot (isolated profile + ports)
+quantumclaw --profile rescue onboard
+# Notes:
+# - workspace name will be postfixed with -rescue per default
+# - Port should be at least 18789 + 20 Ports,
+#   better choose completely different base port, like 19789,
+# - rest of the onboarding is the same as normal
+
+# To install the service (if not happened automatically during setup)
+quantumclaw --profile rescue gateway install
+```
+
+## Port mapping (derived)
+
+Base port = `gateway.port` (or `QUANTUMCLAW_GATEWAY_PORT` / `--port`).
+
+- browser control service port = base + 2 (loopback only)
+- canvas host is served on the Gateway HTTP server (same port as `gateway.port`)
+- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108`
+
+If you override any of these in config or env, you must keep them unique per instance.
+
+## Browser/CDP notes (common footgun)
+
+- Do **not** pin `browser.cdpUrl` to the same values on multiple instances.
+- Each instance needs its own browser control port and CDP range (derived from its gateway port).
+- If you need explicit CDP ports, set `browser.profiles.<name>.cdpPort` per instance.
+- Remote Chrome: use `browser.profiles.<name>.cdpUrl` (per profile, per instance).
+
+## Manual env example
+
+```bash
+QUANTUMCLAW_CONFIG_PATH=~/.quantumclaw/main.json \
+QUANTUMCLAW_STATE_DIR=~/.quantumclaw-main \
+quantumclaw gateway --port 18789
+
+QUANTUMCLAW_CONFIG_PATH=~/.quantumclaw/rescue.json \
+QUANTUMCLAW_STATE_DIR=~/.quantumclaw-rescue \
+quantumclaw gateway --port 19001
+```
+
+## Quick checks
+
+```bash
+quantumclaw --profile main status
+quantumclaw --profile rescue status
+quantumclaw --profile rescue browser status
+```

package/docs/gateway/network-model.md

@@ -0,0 +1,22 @@
+---
+summary: "How the Gateway, nodes, and canvas host connect."
+read_when:
+  - You want a concise view of the Gateway networking model
+title: "Network model"
+---
+
+# Network Model
+
+Most operations flow through the Gateway (`quantumclaw gateway`), a single long-running
+process that owns channel connections and the WebSocket control plane.
+
+## Core rules
+
+- One Gateway per host is recommended. It is the only process allowed to own the WhatsApp Web session. For rescue bots or strict isolation, run multiple gateways with isolated profiles and ports. See [Multiple gateways](/gateway/multiple-gateways).
+- Loopback first: the Gateway WS defaults to `ws://127.0.0.1:18789`. The wizard generates a gateway token by default, even for loopback. For tailnet access, run `quantumclaw gateway --bind tailnet --token ...` because tokens are required for non-loopback binds.
+- Nodes connect to the Gateway WS over LAN, tailnet, or SSH as needed. The legacy TCP bridge is deprecated.
+- Canvas host is served by the Gateway HTTP server on the **same port** as the Gateway (default `18789`):
+  - `/__quantumclaw__/canvas/`
+  - `/__quantumclaw__/a2ui/`
+    When `gateway.auth` is configured and the Gateway binds beyond loopback, these routes are protected by Gateway auth. Node clients use node-scoped capability URLs tied to their active WS session. See [Gateway configuration](/gateway/configuration) (`canvasHost`, `gateway`).
+- Remote use is typically SSH tunnel or tailnet VPN. See [Remote access](/gateway/remote) and [Discovery](/gateway/discovery).

package/docs/gateway/openai-http-api.md

@@ -0,0 +1,132 @@
+---
+summary: "Expose an OpenAI-compatible /v1/chat/completions HTTP endpoint from the Gateway"
+read_when:
+  - Integrating tools that expect OpenAI Chat Completions
+title: "OpenAI Chat Completions"
+---
+
+# OpenAI Chat Completions (HTTP)
+
+QuantumClaw’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.
+
+This endpoint is **disabled by default**. Enable it in config first.
+
+- `POST /v1/chat/completions`
+- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/chat/completions`
+
+Under the hood, requests are executed as a normal Gateway agent run (same codepath as `quantumclaw agent`), so routing/permissions/config match your Gateway.
+
+## Authentication
+
+Uses the Gateway auth configuration. Send a bearer token:
+
+- `Authorization: Bearer <token>`
+
+Notes:
+
+- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `QUANTUMCLAW_GATEWAY_TOKEN`).
+- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `QUANTUMCLAW_GATEWAY_PASSWORD`).
+- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
+
+## Security boundary (important)
+
+Treat this endpoint as a **full operator-access** surface for the gateway instance.
+
+- HTTP bearer auth here is not a narrow per-user scope model.
+- A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
+- Requests run through the same control-plane agent path as trusted operator actions.
+- There is no separate non-owner/per-user tool boundary on this endpoint; once a caller passes Gateway auth here, QuantumClaw treats that caller as a trusted operator for this gateway.
+- If the target agent policy allows sensitive tools, this endpoint can use them.
+- Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.
+
+See [Security](/gateway/security) and [Remote access](/gateway/remote).
+
+## Choosing an agent
+
+No custom headers required: encode the agent id in the OpenAI `model` field:
+
+- `model: "quantumclaw:<agentId>"` (example: `"quantumclaw:main"`, `"quantumclaw:beta"`)
+- `model: "agent:<agentId>"` (alias)
+
+Or target a specific QuantumClaw agent by header:
+
+- `x-quantumclaw-agent-id: <agentId>` (default: `main`)
+
+Advanced:
+
+- `x-quantumclaw-session-key: <sessionKey>` to fully control session routing.
+
+## Enabling the endpoint
+
+Set `gateway.http.endpoints.chatCompletions.enabled` to `true`:
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        chatCompletions: { enabled: true },
+      },
+    },
+  },
+}
+```
+
+## Disabling the endpoint
+
+Set `gateway.http.endpoints.chatCompletions.enabled` to `false`:
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        chatCompletions: { enabled: false },
+      },
+    },
+  },
+}
+```
+
+## Session behavior
+
+By default the endpoint is **stateless per request** (a new session key is generated each call).
+
+If the request includes an OpenAI `user` string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.
+
+## Streaming (SSE)
+
+Set `stream: true` to receive Server-Sent Events (SSE):
+
+- `Content-Type: text/event-stream`
+- Each event line is `data: <json>`
+- Stream ends with `data: [DONE]`
+
+## Examples
+
+Non-streaming:
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/chat/completions \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-quantumclaw-agent-id: main' \
+  -d '{
+    "model": "quantumclaw",
+    "messages": [{"role":"user","content":"hi"}]
+  }'
+```
+
+Streaming:
+
+```bash
+curl -N http://127.0.0.1:18789/v1/chat/completions \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-quantumclaw-agent-id: main' \
+  -d '{
+    "model": "quantumclaw",
+    "stream": true,
+    "messages": [{"role":"user","content":"hi"}]
+  }'
+```