Audience: platform engineers who run an OpenClaw gateway on a hosted Mac for callers beyond 127.0.0.1 such as CI agents VPN peers or a local reverse proxy fronting TLS. You get a copy-paste order of operations Node twenty-two plus install paths SecretRef-style env wiring validation commands and a compact refusal matrix aligned with official troubleshooting language. Canonical: macpull.com blog article slug. Related: gateway security config validate gate non-interactive onboard.

Why loopback-only defaults break remote Mac automation

Loopback-only development feels safe because curl is local production on a remote Mac is not local your peers hit a real interface share the same APFS volume as registry caches and the same outbound path as proxy pulls.

  1. PATH split. Shells see nvm or brew shims launchd does not so the daemon misses the token you exported interactively.
  2. Wide bind. Non-loopback without the upstream security checklist raises exposure empty tokens still fail startup.
  3. Proxy coupling. npm or PyPI mirrors share egress a dead gateway blocks webhooks and pre-pull hooks on the same runner.

Decision matrix: listen scope versus auth depth

Listen pattern Typical use Token and network note
127.0.0.1 only Local doctor loops and sidecar reverse proxy on the same Mac Still set OPENCLAW_GATEWAY_TOKEN if docs require inbound auth for tools that speak HTTP to the gateway.
Site-local or VPN interface CI agents on the same tailnet call the gateway without public internet Pair with firewall rules and rotate the token when the tailnet membership changes.
Non-loopback LAN IP Webhook ingress from adjacent build subnets Mandatory bearer checks plus rate limits documented in your internal runbook mirror upstream guidance.

Minimal reproducible steps

Step one. Install Node 22.14 LTS or Node 24. Log node -v first line of every job so drift between images is obvious when semver gates fail.

Step two. Use the official OpenClaw Installer curl flow from upstream documentation or a pinned npm install -g openclaw@^… range approved by security. Run which openclaw and openclaw --version immediately after install. If Homebrew bootstrap appears on clean runners capture verbose output once then bake brew into the golden AMI per non-interactive onboard.

node -v
npm install -g "openclaw@^2026.3.0"
command -v openclaw
openclaw --version

Step three. Unique OPENCLAW_HOME and OPENCLAW_CONFIG_HOME per job or daemon mkdir mode 700.

Step four. Map vault material the same way you would a Kubernetes SecretRef into plain process environment without echo GitHub Actions uses env: mappings Azure DevOps uses secret variables macOS daemons use plist EnvironmentVariables. Standardise on OPENCLAW_GATEWAY_TOKEN for inbound HTTP auth to the gateway API. Never paste the raw token into pull request comments or build summaries.

Step five. Change listen bind only while reading the official gateway listen TLS and exposure sections if you terminate TLS in nginx or Caddy keep the OpenClaw process on loopback and forward authenticated traffic when you must bind a LAN IP confirm the doc requirement for a non-empty gateway token unload and load launchd after atomic edits.

Step six. openclaw doctor then openclaw config validate merge streams to one CI log per config validate gate.

export OPENCLAW_GATEWAY_TOKEN="$(cat "$RUNNER_TEMP/gw.token")"
openclaw doctor
openclaw config validate --config "$OPENCLAW_CONFIG_HOME/openclaw.json"

curl -fsS -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  "http://127.0.0.1:18789/v1/health"

Refusal to start without authentication common messages

Upstream intentionally refuses unsafe combinations treat stderr lines about missing credentials or forbidden bind profiles as guardrails not regressions open the documentation version that matches your installed semver because exact wording shifts between minors.

Symptom or log cue Likely cause Official-doc aligned fix
Process exits immediately after widening bind away from loopback Gateway token env empty while non-loopback exposure is enabled Set OPENCLAW_GATEWAY_TOKEN from your secret store reload plist or job restart reread security section.
HTTP 401 on health or tool routes from CI Header missing or wrong bearer spelling Align curl or SDK clients with documented Authorization scheme rotate token if copied with trailing newline.
Doctor passes in shell but daemon still refuses launchd plist lacks the new variable Diff EnvironmentVariables blocks unload load cycle once per change.
Validate prints invalid-key JSON paths Hand edited config drift Run validate before merge keep tarball checkpoints from the validate gate article.

Hardening patterns gateway security. Diff messages against release notes for your semver.

Pre-flight checklist

  • Node 22.14+ or 24 logged.
  • openclaw path matches launchd when daemonized.
  • OPENCLAW_GATEWAY_TOKEN in listen context never printed.
  • Firewall allows only documented subnets.
  • Merged doctor plus validate log green.
  • curl health returns 200 with bearer 401 without.

CI proxy pull and webhook value on the same remote Mac

Colocating the gateway on the same remote Mac that already performs npm or PyPI mirror pulls keeps TLS session reuse and warm DNS for both tool traffic and webhook callbacks cross-region hops shrink compared with bouncing through a separate VM bearer health checks on the gateway surface misconfiguration before a whole pool of install jobs burns minutes on timeouts.

Summary and next steps

Path recap Node 22+ installer or global npm SecretRef-style token doctor validate refusal table from upstream security docs. For long-lived Apple Silicon as gateway plus CI pull host open pricing then purchase. Help Console blog index stay public.

Remote Mac for token-gated OpenClaw and CI pulls

Dedicated Apple Silicon with predictable networking for gateways registry mirrors and webhook automation. Public pages only below.

Console View Pricing Buy Now Blog