2026-05-13 OpenClaw on a headless rented Mac mini: SSH first-boot checklist before launchd, MCP, and overnight agents

Operators who rent Apple Silicon Mac mini capacity in Hong Kong, Japan, Korea, Singapore, or the United States through ProxyMac often land via SSH first—no Finder session, no Screen Sharing yet—then try to wire OpenClaw straight into launchd. Before you bootstrap the gateway, confirm plist argv uses an absolute node path and consider ProcessType Interactive if cold-boot listen takes minutes—see launchd gateway startup fix (2026-05-21). The expensive mistake is skipping a first-boot pre-flight: you burn hours chasing MCP timeouts that were really disk pressure, or “missing API key” ghosts that were really non-login shells. This checklist gives you (1) a crisp audience definition, (2) three measurable signals to capture before install, (3) a five-column preflight matrix, (4) a seven-step SSH runbook you can paste into runbooks, (5) a symptom→remediation table, and (6) explicit bridges into install & deploy, MCP environment vs launchd, gateway token JSON, and launchctl recovery. When you need human eyes on macOS prompts, fall back to VNC; for capacity math, use pricing; for access recipes, help.

Who this checklist serves—and what “done” means

This page is for platform engineers and automation leads who treat the mini as an always-on gateway host for OpenClaw agents, MCP tool servers, and JSONL observability. “Done” means you can reboot cold, SSH back in within 90 seconds, watch the LaunchAgent come up without manual ssh attachment, and see structured logs prove the gateway negotiated model and tool health checks. If your definition of done still requires a human to type export in a shell after every reboot, you are not finished—you have deferred environment debt that will explode under parallel agent load.

• Quantified target: keep at least 25% APFS free space on the volume that holds JSONL logs and model caches; drop below 15% only during planned maintenance windows.
• Latency sanity: record RTT from your operator laptop to the mini’s region; if control-plane APIs live in another continent, budget 120–220 ms per hop when setting MCP timeouts.
• Concurrency budget: assume 4 concurrent MCP handshakes during peak; multiply file descriptors accordingly before declaring networking “fine.”

Three signals you must capture before running any installer

First, snapshot df -h and diskutil apfs listSnapshots /—OpenClaw’s append-heavy logging collides badly with APFS snapshots taken by migration tools. Second, print sysctl hw.optional.arm64 and uname -m to confirm you are on arm64 Apple Silicon, not Rosetta confusion around Node binaries. Third, compare ssh host 'command -v openclaw' against ssh -t host zsh -lic 'command -v openclaw'; a mismatch here predicts the exact class of launchd failures documented in MCP environment article. Capture those three outputs in your ticket so the next on-call engineer inherits facts instead of folklore.

Preflight matrix: artifact, owner, verification command, rollback, and blast radius

Artifact	Owner account	Verify	Rollback	Blast radius if skipped
Workspace directory	Same UID as LaunchAgent	ls -le ACL audit	Archive to tarball, recreate with install -d -o	Silent partial writes during tool installs
JSONL log path	Dedicated _openclaw or role user	Disk quota + rotation policy	Truncate with backup; tighten rotation	Full-volume lockup at 3 a.m. ingest peaks
Plist ProgramArguments	Root-less LaunchAgent domain	plutil -lint + diff in git	launchctl bootout + restore plist	Boot loops consuming CPU credits
Model provider secrets	Keychain or plist-referenced file mode 600	Non-interactive probe with timeout	Rotate key + invalidate caches	Cross-tenant leakage in shared labs
MCP server manifests	Repo pinned SHA	Checksum + openclaw doctor subset	Checkout previous SHA	Tool schema drift breaking agents

Seven-step SSH runbook you can paste into Confluence

1. Baseline storage: refuse to install if free space is under 25%; schedule cleanup or larger SKU via pricing before continuing.
2. Normalize time: set NTP healthy; log date -u and region intent (HK / JP / KR / SG / US) beside OpenClaw config so log correlation across regions stays honest.
3. Install or upgrade OpenClaw following install guide, but only after PATH snapshots above succeed.
4. Author plist with explicit PATH that includes Homebrew’s /opt/homebrew/bin and any language managers you truly need—never rely on implicit inheritance.
5. Smoke test twice: run the gateway foreground from SSH, then identical arguments under launchctl kickstart; diff JSONL lines for startup tokens.
6. Wire diagnostics: enable JSONL sinks per logging guide and verify rotation so files cannot grow unbounded for 48 hours.
7. Handoff: document restart owner, pager tier, and link to recovery article; attach plist hash to the ticket.

Symptom → likely cause → first remediation (still over SSH)

Symptom	Likely cause	First remediation
MCP tool exits 127	Trimmed PATH under launchd	Absolute binary paths in plist or wrapper script
Gateway idle CPU 95% after deploy	Tight poll loop or log write blocking	Check JSONL volume latency; apply rotation from logging guide
Auth errors only after reboot	Token only in shell profile	Move to plist EnvironmentVariables or Keychain per token article
Handshake hangs ~40s	DNS or provider rate limit masquerading as loss	Lower parallelism; add explicit resolver test from mini

When to escalate from SSH to VNC (and how to keep it rare)

Stay on SSH for TCC prompts that can be pre-provisioned with mobileconfig profiles, file permission fixes, and plist edits. Open VNC when you must click through Screen Recording approvals, watch GPU-accelerated UI automation, or pair-debug with a designer who cannot read JSONL. Keep VNC sessions short: enable reduced color depth, pause bulk scp jobs, and coordinate with cross-region latency guidance so mouse events stay usable. Most OpenClaw fleets we see in HK / JP / KR / SG / US only need VNC once per machine generation—not weekly.

FAQ

Is Homebrew mandatory? No, but if your docs assume it, encode that assumption in the checklist row for PATH or you will rebuild the same incident.

Can I run everything as my personal admin account? Works in demos; production should use a role account with constrained sudo and explicit log ownership.

What about corporate HTTP proxies? If SSH exits through ProxyCommand, MCP traffic may need the same—mirror the corporate networking articles family before blaming OpenClaw. Encode HTTP_PROXY/HTTPS_PROXY/NO_PROXY for launchd in HTTP/HTTPS outbound proxy under launchd (2026-05-14).

Why ProxyMac Mac mini is the right substrate for headless OpenClaw

A rented Mac mini M4 pairs native macOS with predictable single-tenant CPU—ideal when OpenClaw agents orchestrate Apple-only toolchains while your operators stay on Linux laptops. Keeping gateways in HK / JP / KR / SG / US lets you colocate inference control-planes next to API regions without buying five datacenter cages. After this checklist passes, you inherit the same metal economics you already use for CI: compare SKUs on pricing, rehearse break-glass SSH from help, and keep VNC in your pocket—not on your critical path.