OpenClaw’s gateway authenticates RPC clients with a shared secret. In practice, that secret arrives through three different channels on macOS: the on-disk openclaw.json tree, the macOS app UI wizard that may rewrite config, and the LaunchAgent environment block that injects variables for headless sessions. When any layer disagrees, operators chase ghosts: openclaw status looks healthy while the app shows disconnected. This article gives two matrices, eight rollout steps, and a HowTo sequence so your Mac mini M4 gateway host stops oscillating between “fixed” and “401 Unauthorized.”
Start from token auth and launchd drift, then keep gateway restart outside agent sessions. Baseline installs: installation and deployment; health automation: doctor and diagnostics. Account questions: help; add hosts via pricing.
Symptoms that scream “split token,” not “bad model”
- Split personality: CLI succeeds while the menu-bar app loops on setup.
- 401 after reboot only: loginwindow session lacks env var but file token is correct.
- 401 after upgrade: app bumped a minor version and rewrote JSON while launchd still exports the old variable.
- Intermittent success: two gateway processes briefly race with different configs during reload.
Matrix A: where each client reads credentials from
| Client | Primary source | Common drift | Stabilizer |
|---|---|---|---|
| CLI over SSH | User home openclaw.json |
Different $HOME for service user vs admin |
Always sudo to the service account before editing |
| macOS app | Sandboxed preferences + JSON merge logic | Wizard overwrite after detecting “no gateway” | Pin app versions with change control; open app only after file is canonical |
| launchd gateway | Plist EnvironmentVariables + working directory file | Stale OPENCLAW_GATEWAY_TOKEN export |
Single writer script that updates both atomically |
| Automation agent | Inherited env from parent shell | Missing token when tool sandbox strips env | Explicit config path flags in tool manifest |
Matrix B: rollout risk vs mitigation
| Change | Blast radius | Mitigation |
|---|---|---|
| Rotate token monthly | All chat channels until clients reload | Dual-write old+new for 15 minutes with monitor on 401 rate |
| Move gateway user | Absolute paths and plist labels | Recreate symlinks; rerun install with --force patterns from recovery article |
| Add second region host | Operators paste token into wrong host | Per-host secret names in vault; never reuse clipboard macros |
| Enable non-loopback bind | Stricter auth requirements | Pair with allowlists from gateway rate limits |
Numeric guardrails
- Rotation overlap: keep old token valid for at least 900 s after publishing new to disk.
- Equality checks: automated diff of plist env vs file token every 6 h on production gateways.
- Incident budget: if 401 rate exceeds 1% of RPCs for five minutes, freeze app upgrades automatically.
GUI tip: when macOS privacy prompts block unattended token writes, use VNC once, approve, then return to SSH-only maintenance.
Eight rollout steps
- Declare ownership of the canonical token file path on each host.
- Remove duplicate exports from shells that fight launchd.
- Script atomic updates to JSON + plist in one transaction with backup paths.
- Add CI-style checks that fail deploy if hashes differ across layers.
- Document app version pins next to gateway semver in the CMDB row.
- Run doctor after every upgrade before announcing “healthy.”
- Train on-call to read 401 logs as config drift first, model outage second.
- Split production and lab onto different NodeMac Mac mini M4 hosts when teams cannot agree on a single writer.
FAQ
Is storing the token in Keychain better?
It can be, if all consumers support it consistently. Mixed stacks usually keep file+plist synchronized first, then migrate.
What about team members’ laptops?
Never reuse production tokens on laptops. Use short-lived dev tokens and separate gateway hosts to avoid accidental production RPC from a coffee shop.
Does launchd inherit my shell profile?
No. That is exactly why tokens “disappear” after reboot until you copy them into the plist or a file the gateway reads.
Token hygiene loves boring hardware: a dedicated Mac mini M4 on NodeMac gives Apple Silicon headroom for always-on gateways, native macOS behavior identical to your developers’ laptops, and SSH plus VNC when GUI consent blocks automation. With nodes in Hong Kong, Japan, Korea, Singapore, and the United States, you can place gateways next to users while keeping secrets off shared laptops. Renting instead of buying makes it cheap to isolate “prod gateway” from “lab gateway” so token rotations never become a political fight. Start from pricing by region when you split hosts.