@captain-app/openclaw 2026.2.4

package/docs/gateway/discovery.md

@@ -0,0 +1,116 @@
+---
+summary: "Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway"
+read_when:
+  - Implementing or changing Bonjour discovery/advertising
+  - Adjusting remote connection modes (direct vs SSH)
+  - Designing node discovery + pairing for remote nodes
+title: "Discovery and Transports"
+---
+
+# Discovery & transports
+
+OpenClaw has two distinct problems that look similar on the surface:
+
+1. **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.
+2. **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.
+
+The design goal is to keep all network discovery/advertising in the **Node Gateway** (`openclaw gateway`) and keep clients (mac app, iOS) as consumers.
+
+## Terms
+
+- **Gateway**: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.
+- **Gateway WS (control plane)**: the WebSocket endpoint on `127.0.0.1:18789` by default; can be bound to LAN/tailnet via `gateway.bind`.
+- **Direct WS transport**: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
+- **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.
+- **Legacy TCP bridge (deprecated/removed)**: older node transport (see [Bridge protocol](/gateway/bridge-protocol)); no longer advertised for discovery.
+
+Protocol details:
+
+- [Gateway protocol](/gateway/protocol)
+- [Bridge protocol (legacy)](/gateway/bridge-protocol)
+
+## Why we keep both “direct” and SSH
+
+- **Direct WS** is the best UX on the same network and within a tailnet:
+  - auto-discovery on LAN via Bonjour
+  - pairing tokens + ACLs owned by the gateway
+  - no shell access required; protocol surface can stay tight and auditable
+- **SSH** remains the universal fallback:
+  - works anywhere you have SSH access (even across unrelated networks)
+  - survives multicast/mDNS issues
+  - requires no new inbound ports besides SSH
+
+## Discovery inputs (how clients learn where the gateway is)
+
+### 1) Bonjour / mDNS (LAN only)
+
+Bonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience.
+
+Target direction:
+
+- The **gateway** advertises its WS endpoint via Bonjour.
+- Clients browse and show a “pick a gateway” list, then store the chosen endpoint.
+
+Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
+
+#### Service beacon details
+
+- Service types:
+  - `_openclaw-gw._tcp` (gateway transport beacon)
+- TXT keys (non-secret):
+  - `role=gateway`
+  - `lanHost=<hostname>.local`
+  - `sshPort=22` (or whatever is advertised)
+  - `gatewayPort=18789` (Gateway WS + HTTP)
+  - `gatewayTls=1` (only when TLS is enabled)
+  - `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
+  - `canvasPort=18793` (default canvas host port; serves `/__openclaw__/canvas/`)
+  - `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint or binary)
+  - `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
+
+Disable/override:
+
+- `OPENCLAW_DISABLE_BONJOUR=1` disables advertising.
+- `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
+- `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).
+- `OPENCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).
+- `OPENCLAW_CLI_PATH` overrides the advertised CLI path.
+
+### 2) Tailnet (cross-network)
+
+For London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is:
+
+- Tailscale MagicDNS name (preferred) or a stable tailnet IP.
+
+If the gateway can detect it is running under Tailscale, it publishes `tailnetDns` as an optional hint for clients (including wide-area beacons).
+
+### 3) Manual / SSH target
+
+When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.
+
+See [Remote access](/gateway/remote).
+
+## Transport selection (client policy)
+
+Recommended client behavior:
+
+1. If a paired direct endpoint is configured and reachable, use it.
+2. Else, if Bonjour finds a gateway on LAN, offer a one-tap “Use this gateway” choice and save it as the direct endpoint.
+3. Else, if a tailnet DNS/IP is configured, try direct.
+4. Else, fall back to SSH.
+
+## Pairing + auth (direct transport)
+
+The gateway is the source of truth for node/client admission.
+
+- Pairing requests are created/approved/rejected in the gateway (see [Gateway pairing](/gateway/pairing)).
+- The gateway enforces:
+  - auth (token / keypair)
+  - scopes/ACLs (the gateway is not a raw proxy to every method)
+  - rate limits
+
+## Responsibilities by component
+
+- **Gateway**: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.
+- **macOS app**: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback.
+- **iOS/Android nodes**: browse Bonjour as a convenience and connect to the paired Gateway WS.

package/docs/gateway/doctor.md

@@ -0,0 +1,282 @@
+---
+summary: "Doctor command: health checks, config migrations, and repair steps"
+read_when:
+  - Adding or modifying doctor migrations
+  - Introducing breaking config changes
+title: "Doctor"
+---
+
+# Doctor
+
+`openclaw doctor` is the repair + migration tool for OpenClaw. It fixes stale
+config/state, checks health, and provides actionable repair steps.
+
+## Quick start
+
+```bash
+openclaw doctor
+```
+
+### Headless / automation
+
+```bash
+openclaw doctor --yes
+```
+
+Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
+
+```bash
+openclaw doctor --repair
+```
+
+Apply recommended repairs without prompting (repairs + restarts where safe).
+
+```bash
+openclaw doctor --repair --force
+```
+
+Apply aggressive repairs too (overwrites custom supervisor configs).
+
+```bash
+openclaw doctor --non-interactive
+```
+
+Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.
+Legacy state migrations run automatically when detected.
+
+```bash
+openclaw doctor --deep
+```
+
+Scan system services for extra gateway installs (launchd/systemd/schtasks).
+
+If you want to review changes before writing, open the config file first:
+
+```bash
+cat ~/.openclaw/openclaw.json
+```
+
+## What it does (summary)
+
+- Optional pre-flight update for git installs (interactive only).
+- UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
+- Health check + restart prompt.
+- Skills status summary (eligible/missing/blocked).
+- Config normalization for legacy values.
+- OpenCode Zen provider override warnings (`models.providers.opencode`).
+- Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
+- State integrity and permissions checks (sessions, transcripts, state dir).
+- Config file permission checks (chmod 600) when running locally.
+- Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
+- Extra workspace dir detection (`~/openclaw`).
+- Sandbox image repair when sandboxing is enabled.
+- Legacy service migration and extra gateway detection.
+- Gateway runtime checks (service installed but not running; cached launchd label).
+- Channel status warnings (probed from the running gateway).
+- Supervisor config audit (launchd/systemd/schtasks) with optional repair.
+- Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
+- Gateway port collision diagnostics (default `18789`).
+- Security warnings for open DM policies.
+- Gateway auth warnings when no `gateway.auth.token` is set (local mode; offers token generation).
+- systemd linger check on Linux.
+- Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
+- Writes updated config + wizard metadata.
+
+## Detailed behavior and rationale
+
+### 0) Optional update (git installs)
+
+If this is a git checkout and doctor is running interactively, it offers to
+update (fetch/rebase/build) before running doctor.
+
+### 1) Config normalization
+
+If the config contains legacy value shapes (for example `messages.ackReaction`
+without a channel-specific override), doctor normalizes them into the current
+schema.
+
+### 2) Legacy config key migrations
+
+When the config contains deprecated keys, other commands refuse to run and ask
+you to run `openclaw doctor`.
+
+Doctor will:
+
+- Explain which legacy keys were found.
+- Show the migration it applied.
+- Rewrite `~/.openclaw/openclaw.json` with the updated schema.
+
+The Gateway also auto-runs doctor migrations on startup when it detects a
+legacy config format, so stale configs are repaired without manual intervention.
+
+Current migrations:
+
+- `routing.allowFrom` → `channels.whatsapp.allowFrom`
+- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
+- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
+- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
+- `routing.queue` → `messages.queue`
+- `routing.bindings` → top-level `bindings`
+- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
+- `routing.agentToAgent` → `tools.agentToAgent`
+- `routing.transcribeAudio` → `tools.media.audio.models`
+- `bindings[].match.accountID` → `bindings[].match.accountId`
+- `identity` → `agents.list[].identity`
+- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
+- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
+  → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
+
+### 2b) OpenCode Zen provider overrides
+
+If you’ve added `models.providers.opencode` (or `opencode-zen`) manually, it
+overrides the built-in OpenCode Zen catalog from `@mariozechner/pi-ai`. That can
+force every model onto a single API or zero out costs. Doctor warns so you can
+remove the override and restore per-model API routing + costs.
+
+### 3) Legacy state migrations (disk layout)
+
+Doctor can migrate older on-disk layouts into the current structure:
+
+- Sessions store + transcripts:
+  - from `~/.openclaw/sessions/` to `~/.openclaw/agents/<agentId>/sessions/`
+- Agent dir:
+  - from `~/.openclaw/agent/` to `~/.openclaw/agents/<agentId>/agent/`
+- WhatsApp auth state (Baileys):
+  - from legacy `~/.openclaw/credentials/*.json` (except `oauth.json`)
+  - to `~/.openclaw/credentials/whatsapp/<accountId>/...` (default account id: `default`)
+
+These migrations are best-effort and idempotent; doctor will emit warnings when
+it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates
+the legacy sessions + agent dir on startup so history/auth/models land in the
+per-agent path without a manual doctor run. WhatsApp auth is intentionally only
+migrated via `openclaw doctor`.
+
+### 4) State integrity checks (session persistence, routing, and safety)
+
+The state directory is the operational brainstem. If it vanishes, you lose
+sessions, credentials, logs, and config (unless you have backups elsewhere).
+
+Doctor checks:
+
+- **State dir missing**: warns about catastrophic state loss, prompts to recreate
+  the directory, and reminds you that it cannot recover missing data.
+- **State dir permissions**: verifies writability; offers to repair permissions
+  (and emits a `chown` hint when owner/group mismatch is detected).
+- **Session dirs missing**: `sessions/` and the session store directory are
+  required to persist history and avoid `ENOENT` crashes.
+- **Transcript mismatch**: warns when recent session entries have missing
+  transcript files.
+- **Main session “1-line JSONL”**: flags when the main transcript has only one
+  line (history is not accumulating).
+- **Multiple state dirs**: warns when multiple `~/.openclaw` folders exist across
+  home directories or when `OPENCLAW_STATE_DIR` points elsewhere (history can
+  split between installs).
+- **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run
+  it on the remote host (the state lives there).
+- **Config file permissions**: warns if `~/.openclaw/openclaw.json` is
+  group/world readable and offers to tighten to `600`.
+
+### 5) Model auth health (OAuth expiry)
+
+Doctor inspects OAuth profiles in the auth store, warns when tokens are
+expiring/expired, and can refresh them when safe. If the Anthropic Claude Code
+profile is stale, it suggests running `claude setup-token` (or pasting a setup-token).
+Refresh prompts only appear when running interactively (TTY); `--non-interactive`
+skips refresh attempts.
+
+Doctor also reports auth profiles that are temporarily unusable due to:
+
+- short cooldowns (rate limits/timeouts/auth failures)
+- longer disables (billing/credit failures)
+
+### 6) Hooks model validation
+
+If `hooks.gmail.model` is set, doctor validates the model reference against the
+catalog and allowlist and warns when it won’t resolve or is disallowed.
+
+### 7) Sandbox image repair
+
+When sandboxing is enabled, doctor checks Docker images and offers to build or
+switch to legacy names if the current image is missing.
+
+### 8) Gateway service migrations and cleanup hints
+
+Doctor detects legacy gateway services (launchd/systemd/schtasks) and
+offers to remove them and install the OpenClaw service using the current gateway
+port. It can also scan for extra gateway-like services and print cleanup hints.
+Profile-named OpenClaw gateway services are considered first-class and are not
+flagged as "extra."
+
+### 9) Security warnings
+
+Doctor emits warnings when a provider is open to DMs without an allowlist, or
+when a policy is configured in a dangerous way.
+
+### 10) systemd linger (Linux)
+
+If running as a systemd user service, doctor ensures lingering is enabled so the
+gateway stays alive after logout.
+
+### 11) Skills status
+
+Doctor prints a quick summary of eligible/missing/blocked skills for the current
+workspace.
+
+### 12) Gateway auth checks (local token)
+
+Doctor warns when `gateway.auth` is missing on a local gateway and offers to
+generate a token. Use `openclaw doctor --generate-gateway-token` to force token
+creation in automation.
+
+### 13) Gateway health check + restart
+
+Doctor runs a health check and offers to restart the gateway when it looks
+unhealthy.
+
+### 14) Channel status warnings
+
+If the gateway is healthy, doctor runs a channel status probe and reports
+warnings with suggested fixes.
+
+### 15) Supervisor config audit + repair
+
+Doctor checks the installed supervisor config (launchd/systemd/schtasks) for
+missing or outdated defaults (e.g., systemd network-online dependencies and
+restart delay). When it finds a mismatch, it recommends an update and can
+rewrite the service file/task to the current defaults.
+
+Notes:
+
+- `openclaw doctor` prompts before rewriting supervisor config.
+- `openclaw doctor --yes` accepts the default repair prompts.
+- `openclaw doctor --repair` applies recommended fixes without prompts.
+- `openclaw doctor --repair --force` overwrites custom supervisor configs.
+- You can always force a full rewrite via `openclaw gateway install --force`.
+
+### 16) Gateway runtime + port diagnostics
+
+Doctor inspects the service runtime (PID, last exit status) and warns when the
+service is installed but not actually running. It also checks for port collisions
+on the gateway port (default `18789`) and reports likely causes (gateway already
+running, SSH tunnel).
+
+### 17) Gateway runtime best practices
+
+Doctor warns when the gateway service runs on Bun or a version-managed Node path
+(`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node,
+and version-manager paths can break after upgrades because the service does not
+load your shell init. Doctor offers to migrate to a system Node install when
+available (Homebrew/apt/choco).
+
+### 18) Config write + wizard metadata
+
+Doctor persists any config changes and stamps wizard metadata to record the
+doctor run.
+
+### 19) Workspace tips (backup + memory system)
+
+Doctor suggests a workspace memory system when missing and prints a backup tip
+if the workspace is not already under git.
+
+See [/concepts/agent-workspace](/concepts/agent-workspace) for a full guide to
+workspace structure and git backup (recommended private GitHub or GitLab).

package/docs/gateway/gateway-lock.md

@@ -0,0 +1,34 @@
+---
+summary: "Gateway singleton guard using the WebSocket listener bind"
+read_when:
+  - Running or debugging the gateway process
+  - Investigating single-instance enforcement
+title: "Gateway Lock"
+---
+
+# Gateway lock
+
+Last updated: 2025-12-11
+
+## Why
+
+- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
+- Survive crashes/SIGKILL without leaving stale lock files.
+- Fail fast with a clear error when the control port is already occupied.
+
+## Mechanism
+
+- The gateway binds the WebSocket listener (default `ws://127.0.0.1:18789`) immediately on startup using an exclusive TCP listener.
+- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
+- On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.
+
+## Error surface
+
+- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
+
+## Operational notes
+
+- If the port is occupied by _another_ process, the error is the same; free the port or choose another with `openclaw gateway --port <port>`.
+- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.

package/docs/gateway/health.md

@@ -0,0 +1,35 @@
+---
+summary: "Health check steps for channel connectivity"
+read_when:
+  - Diagnosing WhatsApp channel health
+title: "Health Checks"
+---
+
+# Health Checks (CLI)
+
+Short guide to verify channel connectivity without guessing.
+
+## Quick checks
+
+- `openclaw status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
+- `openclaw status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
+- `openclaw status --deep` — also probes the running Gateway (per-channel probes when supported).
+- `openclaw health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
+- Send `/status` as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent.
+- Logs: tail `/tmp/openclaw/openclaw-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
+
+## Deep diagnostics
+
+- Creds on disk: `ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
+- Session store: `ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
+- Relink flow: `openclaw channels logout && openclaw channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
+
+## When something fails
+
+- `logged out` or status 409–515 → relink with `openclaw channels logout` then `openclaw channels login`.
+- Gateway unreachable → start it: `openclaw gateway --port 18789` (use `--force` if the port is busy).
+- No inbound messages → confirm linked phone is online and the sender is allowed (`channels.whatsapp.allowFrom`); for group chats, ensure allowlist + mention rules match (`channels.whatsapp.groups`, `agents.list[].groupChat.mentionPatterns`).
+
+## Dedicated "health" command
+
+`openclaw health --json` asks the running Gateway for its health snapshot (no direct channel sockets from the CLI). It reports linked creds/auth age when available, per-channel probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.