2026 OpenClaw Gateway First-Aid Playbook: openclaw doctor Deep Scan, Port 18789 Conflicts, and Step-by-Step Dashboard/Token Auth Acceptance

Scope and assumptions

This playbook targets a dedicated remote Mac where OpenClaw owns the gateway process (CLI install or package manager layout). You have SSH or an equivalent shell; VNC is optional but useful when macOS prompts block headless workflows. Commands below are written for zsh on macOS; adjust paths if your install prefix differs.

For launchd ownership, onboarding flows, and gateway.mode acceptance, pair this article with the dedicated daemon runbook. Learn more: OpenClaw gateway daemon runbook (launchctl + startup FAQ)

Phase 1 — Baseline identity and doctor output

Before touching ports, prove which binary and config the shell resolves. Remote sessions often inherit a different PATH than the launchd job, which makes “it works in SSH” and “it fails at boot” diverge.

1.1 Resolve the CLI and version

which openclaw
openclaw --version
openclaw doctor --help

If which returns nothing, fall back to your installer’s documented shim (for example npx openclaw or a project-local binary). The goal is not “npm vs brew theology”—it is one canonical path documented in your runbook.

1.2 Deep doctor pass (capture logs)

openclaw doctor -v 2>&1 | tee ~/openclaw-doctor-"$(date +%Y%m%d-%H%M)".log

Store the log beside your ticket. Teams debugging asynchronously need the first failing check, not a screenshot of the last green line. When doctor reports provider or workspace issues, fix those before chasing HTTP errors—otherwise you will “fix” port 18789 while the gateway still refuses to bind for policy reasons.

Phase 2 — Port 18789: prove the listener, kill collisions, or relocate

In many OpenClaw layouts, 18789 is the default gateway HTTP port used by the local Dashboard and internal health probes. Symptom families include: browser spins on the Dashboard URL, APIs time out, or doctor reports bind errors that mention EADDRINUSE.

2.1 Who listens on 18789?

lsof -nP -iTCP:18789 -sTCP:LISTEN
sudo lsof -nP -iTCP:18789 -sTCP:LISTEN

Expected: a process you recognize (OpenClaw gateway) owned by the service user. Unexpected: another tool, an old gateway instance, or a stray integration test server. If two PIDs appear over time, you likely have duplicate launchd jobs or a manual foreground process fighting the daemon.

2.2 Quick collision triage matrix

2.3 Optional: loopback probe

curl -sv --max-time 3 http://127.0.0.1:18789/  -o /dev/null

Use this on the Mac itself. If loopback works but LAN clients fail, pivot to firewall, bind address, and reverse-proxy rules—not another doctor run.

Phase 3 — Dashboard acceptance (human path)

The Dashboard validates browser-trust assets: TLS termination at the edge, correct hostnames, WebSocket upgrades, and cookies or session storage. It is a poor substitute for token acceptance unless you explicitly test both.

3.1 Local vs proxied URL checklist

• • Loopback first: open the Dashboard via http://127.0.0.1:18789 (or your configured port) from the Mac to remove DNS and proxy variables.
• • Then edge URL: repeat through the same hostname your team uses in production, including HTTPS and HSTS expectations.
• • Hard refresh after TLS or port changes; stale service workers cause false negatives.

When exposing the gateway beyond localhost, walk the hardening checklist for HTTPS, token headers, and discovery surfaces. Learn more: OpenClaw gateway hardening (HTTPS, token auth, mDNS)

Phase 4 — Token auth acceptance (automation path)

Automation and CI callers must not rely on browser cookies. Standard pattern: mint or configure a gateway token, then send Authorization: Bearer … (or the header your deployment documents—match reality, not blog shorthand).

4.1 Minimal authenticated probe

export OPENCLAW_GATEWAY_TOKEN="replace-me"
curl -sv --max-time 5 \
  -H "Authorization: Bearer ${OPENCLAW_GATEWAY_TOKEN}" \
  "http://127.0.0.1:18789/health" -o /dev/null

Swap the path for the health or meta endpoint your build actually uses. Expect HTTP 200 with a stable body. If you receive 401/403 while the Dashboard works, you almost always have token scope mismatch or a different auth realm on the edge proxy.

4.2 Store secrets like an adult

On shared remote Macs, prefer a secrets manager or per-user keychain workflows over world-readable dotfiles. If you must export in shell for a drill, unset OPENCLAW_GATEWAY_TOKEN before you leave the session.

One-page acceptance checklist

FAQ

Doctor is clean but the Dashboard still spins—why?

Check reverse-proxy WebSocket settings, HTTP/2 quirks, and browser extensions. Confirm the process listening on 18789 is the gateway you think it is—doctor can be green while an old binary still serves traffic.

Can I change the default port away from 18789?

Yes, when your deployment supports it. Update OpenClaw config, restart the supervised process, update firewall and proxy upstreams, then re-run the checklist. Document the new port beside your runbook version.

Token works on loopback but fails through the public hostname—why?

Your edge layer may strip auth headers, enforce a different token, or terminate TLS with a different virtual host. Compare response bodies and status lines between direct loopback and proxied paths.

Is VNC required?

No for most CLI steps, but yes when macOS privacy prompts, keychain unlocks, or GUI-only installers block headless SSH. Dedicated remote Mac tenants often keep VNC as break-glass access.