WebSocket port (default comes from config/env; usually `18789`).
Listener bind mode.
Auth mode override.
Token override (also sets `OPENCLAW_GATEWAY_TOKEN` for the process).
Password override.
Read the gateway password from a file.
Expose the Gateway via Tailscale.
Reset Tailscale serve/funnel config on shutdown.
Allow gateway start without `gateway.mode=local` in config. Bypasses the startup guard for ad-hoc/dev bootstrap only; does not write or repair the config file.
Create a dev config + workspace if missing (skips BOOTSTRAP.md).
Reset dev config + credentials + sessions + workspace (requires `--dev`).
Kill any existing listener on the selected port before starting.
Verbose logs.
Only show CLI backend logs in the console (and enable stdout/stderr).
Websocket log style.
Alias for `--ws-log compact`.
Log raw model stream events to jsonl.
Raw stream jsonl path.
warning
Inline `--password` can be exposed in local process listings. Prefer `--password-file`, env, or a SecretRef-backed `gateway.auth.password`.
Startup profiling
Set
text
OPENCLAW_GATEWAY_STARTUP_TRACE=1
to log phase timings during Gateway startup, including per-phase
text
eventLoopMax
delay and plugin lookup-table timings for installed-index, manifest registry, startup planning, and owner-map work.
Set
text
OPENCLAW_DIAGNOSTICS=timeline
with
text
OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>
to write a best-effort JSONL startup diagnostics timeline for external QA harnesses. You can also enable the flag with
text
diagnostics.flags: ["timeline"]
in config; the path is still env-provided. Add
text
OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1
to include event-loop samples.
Run
text
pnpm test:startup:gateway -- --runs 5 --warmup 1
to benchmark Gateway startup. The benchmark records first process output,
* Default: human-readable (colored in TTY).
* `--json`: machine-readable JSON (no styling/spinner).
* `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout.
* `--url `: Gateway WebSocket URL.
* `--token `: Gateway token.
* `--password `: Gateway password.
* `--timeout `: timeout/budget (varies per command).
* `--expect-final`: wait for a "final" response (agent calls).
note
When you set `--url`, the CLI does not fall back to config or environment credentials. Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
text
gateway health
bash
openclaw gateway health --url ws://127.0.0.1:18789
The HTTP
text
/healthz
endpoint is a liveness probe: it returns once the server can answer HTTP. The HTTP
text
/readyz
endpoint is stricter and stays red while startup sidecars, channels, or configured hooks are still settling. Local or authenticated detailed readiness responses include an
text
eventLoop
diagnostic block with event-loop delay, event-loop utilization, CPU core ratio, and a
Maximum number of recent events to include (max `1000`).
Filter by diagnostic event type, such as `payload.large` or `diagnostic.memory.pressure`.
Include only events after a diagnostic sequence number.
Read a persisted stability bundle instead of calling the running Gateway. Use `--bundle latest` (or just `--bundle`) for the newest bundle under the state directory, or pass a bundle JSON path directly.
Write a shareable support diagnostics zip instead of printing stability details.
Output path for `--export`.
text
gateway diagnostics export
Write a local diagnostics zip that is designed to attach to bug reports. For the privacy model and bundle contents, see Diagnostics Export.
Output zip path. Defaults to a support export under the state directory.
Maximum sanitized log lines to include.
Maximum log bytes to inspect.
Gateway WebSocket URL for the health snapshot.
Gateway token for the health snapshot.
Gateway password for the health snapshot.
Status/health snapshot timeout.
Skip persisted stability bundle lookup.
Print the written path, size, and manifest as JSON.
The export contains a manifest, a Markdown summary, config shape, sanitized config details, sanitized log summaries, sanitized Gateway status/health snapshots, and the newest stability bundle when one exists.
It is meant to be shared. It keeps operational details that help debugging, such as safe OpenClaw log fields, subsystem names, status codes, durations, configured modes, ports, plugin ids, provider ids, non-secret feature settings, and redacted operational log messages. It omits or redacts chat text, webhook bodies, tool outputs, credentials, cookies, account/message identifiers, prompt/instruction text, hostnames, and secret values. When a LogTape-style message looks like user/chat/tool payload text, the export keeps only that a message was omitted plus its byte count.
text
gateway status
text
gateway status
shows the Gateway service (launchd/systemd/schtasks) plus an optional probe of connectivity/auth capability.
bash
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
Add an explicit probe target. Configured remote + localhost are still probed.
Token auth for the probe.
Password auth for the probe.
Probe timeout.
Skip the connectivity probe (service-only view).
Scan system-level services too.
Upgrade the default connectivity probe to a read probe and exit non-zero when that read probe fails. Cannot be combined with `--no-probe`.
text
gateway probe
text
gateway probe
is the "debug everything" command. It always probes:
your configured remote gateway (if set), and
localhost (loopback) even if remote is configured.
If you pass
text
--url
, that explicit target is added ahead of both. Human output labels the targets as:
text
URL (explicit)
text
Remote (configured)
or
text
Remote (configured, inactive)
text
Local loopback
note
If 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.
The 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
text
ws://127.0.0.1:<port>
.
CLI equivalent:
bash
openclaw gateway probe --ssh user@gateway-host
`user@host` or `user@host:port` (port defaults to `22`).
Identity file.
Pick the first discovered gateway host as SSH target from the resolved discovery endpoint (`local.` plus the configured wide-area domain, if any). TXT-only hints are ignored.
JSON object string for params.
Gateway WebSocket URL.
Gateway token.
Gateway password.
Timeout budget.
Mainly for agent-style RPCs that stream intermediate events before a final payload.
Machine-readable JSON output.
when the managed service must start through another executable, for example a
secrets manager shim or a run-as helper. The wrapper receives the normal Gateway args and is
responsible for eventually exec'ing
* The CLI scans `local.` plus the configured wide-area domain when one is enabled.
* `wsUrl` in JSON output is derived from the resolved service endpoint, not from TXT-only hints such as `lanHost` or `tailnetDns`.
* On `local.` mDNS, `sshPort` and `cliPath` are only broadcast when `discovery.mdns.mode` is `full`. Wide-area DNS-SD still writes `cliPath`; `sshPort` stays optional there too.