Nothing erodes trust in an automation platform faster than 401/unauthorized from the gateway when channels look “green” in chat. On Mac mini M4 hosts, the usual culprit is not cryptography—it is two configs: the file openclaw reads under your interactive shell versus the one the LaunchAgent sees after reboot. This 2026 triage matrix aligns gateway.auth fields, documents token rotation, and gives eight reproducible steps that pair with health probes and doctor output you may already collect.
Diagnostics: openclaw doctor and health diagnostics. Readiness: health and readiness probes. launchd alignment: launchd and gateway readiness. Pricing: pricing; help: help.
Failure mode matrix
| Symptom | Likely drift | First fix |
|---|---|---|
| Gateway token missing | CLI wrote token to user profile env only | Persist under gateway.auth in JSON; rerun doctor |
| RPC probe fails loopback | Port clash or stale lock file | lsof -i :<port>; kill stray PID; restart |
| Works until reboot | LaunchAgent not loaded for daemon user | Verify plist path, launchctl bootstrap as logged-in user |
| Channel connected, UI 401 | Reverse proxy stripped Authorization |
Align proxy pass-through with egress TLS guide |
Config source of truth
| Layer | Owns | Audit command |
|---|---|---|
~/.openclaw/openclaw.json |
Gateway auth, bind mode, channels | openclaw config get gateway.auth.token (name may vary by version) |
| LaunchAgent plist | HOME, TMPDIR, explicit env overrides |
Diff against interactive printenv |
| Secrets store | Long-lived tokens outside Git | Rotation runbook + checksum in CMDB |
Headless Mac tip: if your gateway must survive reboot without GUI login, validate whether your install targets LaunchAgents vs LaunchDaemons—behavior differs; document the trade-off in your runbook.
Eight-step triage checklist
- Reproduce context: note whether failure is interactive-only or daemon-only.
- Run doctor: capture stdout/stderr to CI artifact or ticket.
- Compare configs: hash
openclaw.jsonfrom service account vs your shell user. - Validate token path: ensure auth fields match documented keys for your CLI major version.
- Restart cleanly: stop gateway, clear stale locks if documented safe, start again.
- Probe loopback: match readiness guide thresholds (<200 ms p95 target).
- Log slice: attach last 200 lines redacted to the incident.
- Post-incident: add alert when
gateway statusflaps > 3/day.
FAQ
Why does my OpenClaw gateway work in Terminal but fail under launchd?
Interactive shells load profiles and environment variables that LaunchAgents do not inherit. Tokens and proxy settings must live in ~/.openclaw/openclaw.json or the plist EnvironmentVariables, not only in shell exports.
Where should the gateway auth token live on macOS in 2026?
Prefer gateway.auth.token (or the version your CLI documents) inside the JSON config file used by the daemon. Regenerate with openclaw doctor if missing, then restart the gateway service and verify with openclaw gateway status.
Rehearse token rotation and plist edits on disposable Mac mini M4 rentals before touching production gateways. NodeMac provides dedicated Apple Silicon with SSH/VNC in Hong Kong, Japan, Korea, Singapore, and the United States so SREs can snapshot a failing gateway layout without buying spare hardware.