2026 OpenClaw headless Linux Docker: stuck onboard, pending.json & dashboard --no-open verification runbook

About 16 min read · MACCOME

If you run OpenClaw with Docker only on a headless Linux VPS—no desktop, no browser—and hit wizard or onboard stuck in pending, logs asking you to open a local browser, or dashboard failing without DISPLAY, this article gives a change-ticket-ready headless acceptance ladder: freeze one compose track and one TOKEN source of truth, then replace “I saw Control UI” with dashboard --no-open, gateway status/probe, and structured logs. It complements the three-OS install guide, Windows Docker triage, Linux systemd+Tunnel without Docker, and Compose pairing 1006/1008; production anchors pair with SSH-forwarded dedicated Gateway.

Six false failures on headless Linux Docker for OpenClaw

  1. Defining “must open a browser” as acceptance: on headless hosts the failure is the test script, not Gateway—use CLI contracts instead.
  2. Dual-track onboard plus compose: two entry points half-write pending.json / env vars, yielding random pending or TOKEN drift (same root cause as the Compose pairing article).
  3. Missing silent/headless switches: the wizard waits for interaction while health checks still look “green”.
  4. cgroup, graph driver, and default ulimits: small VPS plans hit OOM or fd exhaustion, misread as WebSocket 1006.
  5. Corporate MITM or transparent proxies: image pulls succeed while WebSocket handshakes break—verify TLS expectations and trust stores.
  6. Copying Windows homework onto Linux: WSL2 and Docker Desktop preconditions differ from the Linux engine—follow post-install doctor triage “engine before business” order.

Headless value is smaller attack surface and stronger automation; if acceptance still depends on clicking a browser, you only moved desktop chaos into SSH sessions. When reading Docker production runbook, keep image tag, compose hash, and TOKEN injection on the same ticket.

If the team maintains both systemd bare metal and Docker, document the default source of truth: which path is CI image integration and which is production—mixed hosts are the hardest class to debug.

Dimension Headless Docker (this article) Linux systemd + Tunnel (no containers)
Repro & upgrades Image tags + compose files version quickly, rollback is fast Depends on distro packages and unit files; deeper customization, weaker image story
Headless acceptance Natural fit for --no-open and container log drivers journald + curl probes; different paths than Docker
Network namespaces 1006/1008 often tied to bridge / publish combinations Host stack; issues often land on Tunnel and bind
With dedicated remote Mac Gateway can move to a dedicated host; laptop keeps CLI only Same conclusion; ops habits differ
Common misuse CI and prod compose forks without labels Running Tunnel gateway and Docker gateway dual-boot mentally on one box
info

Note: Community guidance to set silent true in pending.json to skip blocking wizards must be cross-checked against current OpenClaw docs before you bake it into pipelines; re-run a regression after upgrades so silent does not become silent hang.

Six-step headless runbook: from “can pull images” to “gateway probe green”

  1. Freeze a single entry track: choose compose-only or official docker-setup only; treat the other path as read-only reference.
  2. Validate engine and disk: docker info, free space on the Docker data root, ulimit -n; tiny VPS plans should add swap or cap concurrency before features.
  3. Handle onboard / pending: apply documented headless switches; after changes, print a hash of pending files into CI logs for audit.
  4. Start Gateway and verify via CLI only: openclaw gateway status → openclaw gateway probe (if available) → openclaw dashboard --no-open; forbid “I saw it in a browser” as the only pass signal.
  5. Run doctor and register waivers: align fields with post-install doctor triage; every waiver needs an owner and expiry.
  6. Add regression: after container rebuild, the same script must pass within 10 minutes; failures open an incident with compose hash and image digest.
bash
# Example: CLI-only checks (adjust compose service names)
docker compose ps
docker compose logs -f --tail=200 openclaw-gateway

openclaw gateway status || true
openclaw dashboard --no-open || true
openclaw doctor --yes || true

Three metrics for SLOs or on-call notes (tune to your SKUs)

  • Cold start to first successful probe (G2P): median minutes from compose up -d to first successful gateway probe; if week-over-week rises >40% with unchanged image tags, check disk and fds before blaming models.
  • Browser-dependent steps on headless hosts: target zero; any new step requiring DISPLAY should return to productization or a dev-only compose profile.
  • Dual-Gateway events: count double binds on 18789 or TOKEN dual-source alerts; >0 for two weeks should trigger architecture review per TOKEN dual-source article.

Why “install a lightweight desktop + VNC” or “retry onboard until lucky” is a bad 2026 trade

Light desktops widen patch surface and session auditing cost; public VNC is a classic high-risk pattern. Infinite onboard retries hide field drift inside manual muscle memory, not automation.

When you need 7×24, auditable Gateway aligned with CI while headless Linux stays best for edge tryouts or short PoCs, placing the authoritative Gateway on a dedicated Apple Silicon remote Mac with documented SSH forward or tailnet policy usually beats fighting cgroup limits on small VPS plans—MACCOME offers Mac mini (M4 / M4 Pro) across six regions with flexible leases; size the topology with the public node and lease guide before you commit.

Close: headless acceptance belongs in DOCKER_GATEWAY.md, not chat lore

Ship: compose file version, image digest, silent/pending policy, sample CLI outputs, explicit “no browser required” statement. Any step that cannot be replayed on a second headless box is unfinished documentation.

When comparing with Windows Docker triage, remember: same ladder, different host and engine; do not mix Docker Desktop log paths with Linux engine paths.

FAQ

Onboard stays pending on a headless server—do I need a desktop?

Usually no: use headless switches and CLI acceptance; verify pending.json fields against docs. For production Gateway on dedicated nodes, read rental rates and support center.

Can Linux Docker and systemd+Tunnel share one machine?

Technically yes but dual Gateway / dual TOKEN truth is common unless environments are split with a documented default. See Tunnel runbook and the Compose pairing article.