Snippet-ready: This runbook focuses on OpenClaw’s native macOS footprint—the official packaged app optional path plus the openclaw CLI—and the platform facts that refuse to live inside Docker: OPENCLAW_STATE_DIR, keeping state off iCloud-synced locations, macOS Transparency Consent & Privacy (TCC) for Accessibility, Automation, Screen Recording, and microphone where needed, and preventing LaunchAgent-managed gateways from colliding with ad-hoc openclaw gateway start. It complements the three-OS install overview and troubleshooting doctor flow, contrasts with Compose-heavy guides, and gives verifiable checks using openclaw doctor and openclaw gateway status before wiring local vs remote Gateway semantics for teams leasing metal in Singapore, Tokyo, Seoul, Hong Kong, or North America.
openclaw differs from a GUI app runner; upgrades that replace the executable path revoke prior grants unless migrated carefully.launchd and an interactive Terminal session spawn separate parents; triage resembles port conflicts plus divergent configs.Canonical cross-platform scaffolding remains in the 2026 install & deploy guide and post-install doctor & WSL-adjacent triage. When you operationalize gateways with containers under orchestration budgets, defer to the Docker production gateway runbook. Geography, lease maths, and colocation thinking still belong with the multi-region mini rental guide.
Set OPENCLAW_STATE_DIR to a path under a local APFS volume you control, for example /usr/local/var/openclaw or /opt/openclaw/state, and document that choice in your internal inventory system. Avoid paths inside ~/Library/Mobile Documents, Desktop/Documents when synchronized, or any folder managed by third-party sync clients that rewrite files opportunistically.
When multiple user accounts share a host, scope state per account or per service identity; never point two distinct gateway instances at the same directory unless you intend to cluster with shared storage semantics you have tested.
Use the table as a radio script: each row should produce one owner and one rollback step.
| Symptom | Likely root cause | Stabilizing move |
|---|---|---|
| Token or pairing flaps only on one reboot | State path on a synced or roaming volume; two processes writing competing stores | Pin OPENCLAW_STATE_DIR to local disk; ensure only one gateway parent (LaunchAgent or manual) |
| AppleScript / UI automation stalls | Automation or Accessibility not granted to the exact binary | Trigger a controlled failure in System Settings > Privacy & Security; re-approve after upgrades |
| Pixel or window capture APIs hang | Screen Recording permission missing for the calling binary | Grant Screen Recording; restart the gateway process so TCC attaches to the right parent |
| Address already in use on gateway port | Double listener from LaunchAgent plus manual gateway start |
launchctl bootout the test plist or stop the interactive process; standardize on one scheduler |
| Works on AC power, dies overnight | Laptop sleep or network power management, not OpenClaw logic | Move authoritative Gateway to an always-on remote Mac; keep local as client only |
Do not stack schedulers: If production uses launchd, treat manual openclaw gateway start as a debug-only exception. Document the bootout path beside the plist name so on-call engineers do not “helpfully” start a second copy during incidents.
Accessibility covers assistive control of other applications. Automation (AppleEvents) governs AppleScript and many bridge patterns. Screen Recording is separate; absence shows up as tools that never return frames. If you enable dictation or audio-driven skills, add Microphone deliberately rather than assuming container-era defaults.
After every major macOS upgrade or OpenClaw package upgrade, schedule a 10-minute re-walk through Privacy settings with a checklist screenshot stored beside your runbook version.
openclaw gateway startLaunchAgents are ideal for unattended remote Macs in colocation or lease environments: they restart after reboot, respect the logged-in console context you configure, and integrate with your existing MDM or shell bootstrap. Manual starts belong in developer sandboxes where an engineer is literally watching stdout.
When debugging, prefer launchctl print gui/$uid/com.example.openclaw.gateway (replace label) over guesswork. If you must run manually, stop the LaunchAgent first to prove you are not observing ghost traffic from an older instance.
Local Gateway means the control plane sits on the same ergonomic machine as the human: fast iteration, immediate GUI prompts, but vulnerable to sleep, VPN flaps, and conference-room Wi-Fi. Remote Gateway pins pairing, queue depth, and long-lived automation to a host with data-center or premium-residential power and fixed egress—exactly the pattern teams adopt when they lease dedicated Mac minis per region.
CLI ergonomics stay the same; what changes is which host answers for health checks and which disk owns OPENCLAW_STATE_DIR. Document the mapping in your internal service catalog so security reviews do not conflate the two.
OPENCLAW_STATE_DIR, log directories, and optional cache roots on local APFS; set ownership for the runtime user.Keep remediation cross-links handy: Compose-specific networking belongs in Docker articles, while doctor-driven checks stay aligned with the doctor troubleshooting companion.
#!/usr/bin/env bash
set -euo pipefail
# Safe, read-mostly probes — adapt paths to your policy
export OPENCLAW_STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/Library/Application Support/OpenClawState-local}"
umask 077
mkdir -p "$OPENCLAW_STATE_DIR"
echo "OPENCLAW_STATE_DIR=$OPENCLAW_STATE_DIR"
command -v openclaw >/dev/null && openclaw doctor || echo "doctor: CLI not on PATH"
openclaw gateway status 2>/dev/null || echo "gateway: not responding (expected if down)"
launchctl print "gui/$(id -u)" 2>/dev/null | grep -i openclaw || echo "launchd: no plist label matched string openclaw (OK if manual mode)"
gateway status: capture wall-clock seconds after reboot; regressions often track plist errors or delayed TCC prompts, not Rust compile times.OPENCLAW_STATE_DIR via df; if it shows a cloud-backed FUSE or sync shim, relocate before opening the incident bridge.Attach raw command transcripts to tickets; narration without numbers expires within one staffing rotation.
Laptops prioritize human comfort: they sleep when lids close, downgrade Wi-Fi aggressively, and mix corporate VPN overlays with captive portals. Those behaviors are virtues for mobility and liabilities for authoritative automation planes.
An always-on MACCOME cloud Mac mini in the correct region gives you fixed power, predictable disks, and room to run LaunchAgent-backed gateways beside other macOS-native workloads while your developers keep local CLIs as clients only. Pair that hardware choice with regional lease math so latency to your model hosts and registry mirrors stays honest.
File TCC and path locality bugs against the macOS runbook; file cgroups, bridge networks, and image digests against container guides. When both appear in one incident, split the timeline so executives see two parallel RCAs instead of one confused thread.
Before closing any change window, rerun openclaw doctor, archive the output beside your semver, and note whether authoritative Gateway stayed remote for the duration of the test.
FAQ
We already standardized on Docker for production gateways—why read about LaunchAgents?
Because some workflows still originate on bare macOS GUIs—design reviews, Xcode-adjacent automations, or operator laptops that initiate pairing before containers exist. Knowing how launchd differs from Compose prevents double gateways when someone “just starts” the daemon during an incident.
Where should I rent an always-on Mac mini for Gateway hosting?
Compare flexible leases across regions on our rental rates page first. Billing or placement edge cases belong in the help center so diagrams and compliance answers stay current.