{
  "title": "Gateway CLI",
  "content": "The Gateway is OpenClaw’s WebSocket server (channels, nodes, sessions, hooks).\n\nSubcommands in this page live under `openclaw gateway …`.\n\n* [/gateway/bonjour](/gateway/bonjour)\n* [/gateway/discovery](/gateway/discovery)\n* [/gateway/configuration](/gateway/configuration)\n\nRun a local Gateway process:\n\n* By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.openclaw/openclaw.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.\n* Binding beyond loopback without auth is blocked (safety guardrail).\n* `SIGUSR1` triggers an in-process restart when authorized (enable `commands.restart` or use the gateway tool/config apply/update).\n* `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.\n\n* `--port <port>`: WebSocket port (default comes from config/env; usually `18789`).\n* `--bind <loopback|lan|tailnet|auto|custom>`: listener bind mode.\n* `--auth <token|password>`: auth mode override.\n* `--token <token>`: token override (also sets `OPENCLAW_GATEWAY_TOKEN` for the process).\n* `--password <password>`: password override (also sets `OPENCLAW_GATEWAY_PASSWORD` for the process).\n* `--tailscale <off|serve|funnel>`: expose the Gateway via Tailscale.\n* `--tailscale-reset-on-exit`: reset Tailscale serve/funnel config on shutdown.\n* `--allow-unconfigured`: allow gateway start without `gateway.mode=local` in config.\n* `--dev`: create a dev config + workspace if missing (skips BOOTSTRAP.md).\n* `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`).\n* `--force`: kill any existing listener on the selected port before starting.\n* `--verbose`: verbose logs.\n* `--claude-cli-logs`: only show claude-cli logs in the console (and enable its stdout/stderr).\n* `--ws-log <auto|full|compact>`: websocket log style (default `auto`).\n* `--compact`: alias for `--ws-log compact`.\n* `--raw-stream`: log raw model stream events to jsonl.\n* `--raw-stream-path <path>`: raw stream jsonl path.\n\n## Query a running Gateway\n\nAll query commands use WebSocket RPC.\n\n* Default: human-readable (colored in TTY).\n* `--json`: machine-readable JSON (no styling/spinner).\n* `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout.\n\nShared options (where supported):\n\n* `--url <url>`: Gateway WebSocket URL.\n* `--token <token>`: Gateway token.\n* `--password <password>`: Gateway password.\n* `--timeout <ms>`: timeout/budget (varies per command).\n* `--expect-final`: wait for a “final” response (agent calls).\n\nNote: when you set `--url`, the CLI does not fall back to config or environment credentials.\nPass `--token` or `--password` explicitly. Missing explicit credentials is an error.\n\n`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.\n\n* `--url <url>`: override the probe URL.\n* `--token <token>`: token auth for the probe.\n* `--password <password>`: password auth for the probe.\n* `--timeout <ms>`: probe timeout (default `10000`).\n* `--no-probe`: skip the RPC probe (service-only view).\n* `--deep`: scan system-level services too.\n\n`gateway probe` is the “debug everything” command. It always probes:\n\n* your configured remote gateway (if set), and\n* localhost (loopback) **even if remote is configured**.\n\nIf multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.\n\n#### Remote over SSH (Mac app parity)\n\nThe macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.\n\n* `--ssh <target>`: `user@host` or `user@host:port` (port defaults to `22`).\n* `--ssh-identity <path>`: identity file.\n* `--ssh-auto`: pick the first discovered gateway host as SSH target (LAN/WAB only).\n\nConfig (optional, used as defaults):\n\n* `gateway.remote.sshTarget`\n* `gateway.remote.sshIdentity`\n\n### `gateway call <method>`\n\nLow-level RPC helper.\n\n## Manage the Gateway service\n\n* `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.\n* Lifecycle commands accept `--json` for scripting.\n\n## Discover gateways (Bonjour)\n\n`gateway discover` scans for Gateway beacons (`_openclaw-gw._tcp`).\n\n* Multicast DNS-SD: `local.`\n* Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: `openclaw.internal.`) and set up split DNS + a DNS server; see [/gateway/bonjour](/gateway/bonjour)\n\nOnly gateways with Bonjour discovery enabled (default) advertise the beacon.\n\nWide-Area discovery records include (TXT):\n\n* `role` (gateway role hint)\n* `transport` (transport hint, e.g. `gateway`)\n* `gatewayPort` (WebSocket port, usually `18789`)\n* `sshPort` (SSH port; defaults to `22` if not present)\n* `tailnetDns` (MagicDNS hostname, when available)\n* `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)\n* `cliPath` (optional hint for remote installs)\n\n### `gateway discover`\n\n* `--timeout <ms>`: per-command timeout (browse/resolve); default `2000`.\n* `--json`: machine-readable output (also disables styling/spinner).",
  "code_samples": [
    {
      "code": "Foreground alias:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.openclaw/openclaw.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.\n* Binding beyond loopback without auth is blocked (safety guardrail).\n* `SIGUSR1` triggers an in-process restart when authorized (enable `commands.restart` or use the gateway tool/config apply/update).\n* `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.\n\n### Options\n\n* `--port <port>`: WebSocket port (default comes from config/env; usually `18789`).\n* `--bind <loopback|lan|tailnet|auto|custom>`: listener bind mode.\n* `--auth <token|password>`: auth mode override.\n* `--token <token>`: token override (also sets `OPENCLAW_GATEWAY_TOKEN` for the process).\n* `--password <password>`: password override (also sets `OPENCLAW_GATEWAY_PASSWORD` for the process).\n* `--tailscale <off|serve|funnel>`: expose the Gateway via Tailscale.\n* `--tailscale-reset-on-exit`: reset Tailscale serve/funnel config on shutdown.\n* `--allow-unconfigured`: allow gateway start without `gateway.mode=local` in config.\n* `--dev`: create a dev config + workspace if missing (skips BOOTSTRAP.md).\n* `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`).\n* `--force`: kill any existing listener on the selected port before starting.\n* `--verbose`: verbose logs.\n* `--claude-cli-logs`: only show claude-cli logs in the console (and enable its stdout/stderr).\n* `--ws-log <auto|full|compact>`: websocket log style (default `auto`).\n* `--compact`: alias for `--ws-log compact`.\n* `--raw-stream`: log raw model stream events to jsonl.\n* `--raw-stream-path <path>`: raw stream jsonl path.\n\n## Query a running Gateway\n\nAll query commands use WebSocket RPC.\n\nOutput modes:\n\n* Default: human-readable (colored in TTY).\n* `--json`: machine-readable JSON (no styling/spinner).\n* `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout.\n\nShared options (where supported):\n\n* `--url <url>`: Gateway WebSocket URL.\n* `--token <token>`: Gateway token.\n* `--password <password>`: Gateway password.\n* `--timeout <ms>`: timeout/budget (varies per command).\n* `--expect-final`: wait for a “final” response (agent calls).\n\nNote: when you set `--url`, the CLI does not fall back to config or environment credentials.\nPass `--token` or `--password` explicitly. Missing explicit credentials is an error.\n\n### `gateway health`",
      "language": "unknown"
    },
    {
      "code": "### `gateway status`\n\n`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.",
      "language": "unknown"
    },
    {
      "code": "Options:\n\n* `--url <url>`: override the probe URL.\n* `--token <token>`: token auth for the probe.\n* `--password <password>`: password auth for the probe.\n* `--timeout <ms>`: probe timeout (default `10000`).\n* `--no-probe`: skip the RPC probe (service-only view).\n* `--deep`: scan system-level services too.\n\n### `gateway probe`\n\n`gateway probe` is the “debug everything” command. It always probes:\n\n* your configured remote gateway (if set), and\n* localhost (loopback) **even if remote is configured**.\n\nIf multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.",
      "language": "unknown"
    },
    {
      "code": "#### Remote over SSH (Mac app parity)\n\nThe macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.\n\nCLI equivalent:",
      "language": "unknown"
    },
    {
      "code": "Options:\n\n* `--ssh <target>`: `user@host` or `user@host:port` (port defaults to `22`).\n* `--ssh-identity <path>`: identity file.\n* `--ssh-auto`: pick the first discovered gateway host as SSH target (LAN/WAB only).\n\nConfig (optional, used as defaults):\n\n* `gateway.remote.sshTarget`\n* `gateway.remote.sshIdentity`\n\n### `gateway call <method>`\n\nLow-level RPC helper.",
      "language": "unknown"
    },
    {
      "code": "## Manage the Gateway service",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.\n* Lifecycle commands accept `--json` for scripting.\n\n## Discover gateways (Bonjour)\n\n`gateway discover` scans for Gateway beacons (`_openclaw-gw._tcp`).\n\n* Multicast DNS-SD: `local.`\n* Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: `openclaw.internal.`) and set up split DNS + a DNS server; see [/gateway/bonjour](/gateway/bonjour)\n\nOnly gateways with Bonjour discovery enabled (default) advertise the beacon.\n\nWide-Area discovery records include (TXT):\n\n* `role` (gateway role hint)\n* `transport` (transport hint, e.g. `gateway`)\n* `gatewayPort` (WebSocket port, usually `18789`)\n* `sshPort` (SSH port; defaults to `22` if not present)\n* `tailnetDns` (MagicDNS hostname, when available)\n* `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)\n* `cliPath` (optional hint for remote installs)\n\n### `gateway discover`",
      "language": "unknown"
    },
    {
      "code": "Options:\n\n* `--timeout <ms>`: per-command timeout (browse/resolve); default `2000`.\n* `--json`: machine-readable output (also disables styling/spinner).\n\nExamples:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Run the Gateway",
      "id": "run-the-gateway"
    },
    {
      "level": "h3",
      "text": "Options",
      "id": "options"
    },
    {
      "level": "h2",
      "text": "Query a running Gateway",
      "id": "query-a-running-gateway"
    },
    {
      "level": "h3",
      "text": "`gateway health`",
      "id": "`gateway-health`"
    },
    {
      "level": "h3",
      "text": "`gateway status`",
      "id": "`gateway-status`"
    },
    {
      "level": "h3",
      "text": "`gateway probe`",
      "id": "`gateway-probe`"
    },
    {
      "level": "h3",
      "text": "`gateway call <method>`",
      "id": "`gateway-call-<method>`"
    },
    {
      "level": "h2",
      "text": "Manage the Gateway service",
      "id": "manage-the-gateway-service"
    },
    {
      "level": "h2",
      "text": "Discover gateways (Bonjour)",
      "id": "discover-gateways-(bonjour)"
    },
    {
      "level": "h3",
      "text": "`gateway discover`",
      "id": "`gateway-discover`"
    }
  ],
  "url": "llms-txt#gateway-cli",
  "links": []
}