Skip to main content
OpenClaw.app bundles a private Node runtime and matching OpenClaw package for its app-owned node worker helper. Rebuilding or replacing the app replaces that helper too, including rebuilds with the same public version. The helper runs from the signed bundle, so moving the app or removing its build checkout does not change which worker it uses. The Gateway remains external. The app uses an external openclaw CLI to manage a per-user launchd service, or attaches to an already-running Gateway. It does not start the Gateway inside its private worker runtime. Packaging the worker never installs, updates, or restarts a Gateway service. The private worker validates core and node configuration through a read-only bootstrap, without Gateway-wide Doctor preflight or channel-schema validation. Node plugins still validate their own settings before publishing commands, and the node runtime owns its MCP clients. Node startup retains the Doctor-owned device-auth, device-identity, and exec-approval migrations; this is not a promise that all worker startup is read-only. Public node run, Gateway, and Doctor retain their existing startup policies. When the native app creates identity, device-auth, or approval tables before the worker starts, node startup completes that recognized version-zero database through the canonical initializer before plugins read their state. Existing native rows are preserved. This does not migrate an already-versioned shared Gateway database or adopt unknown or occupied bootstrap state.

​
Automatic setup

On a fresh Mac, choose This Mac during onboarding. The app runs its signed, bundled installer script before the Gateway wizard: it installs a user-space Node runtime and the matching openclaw CLI under ~/.openclaw, then installs and starts the per-user launchd service. This path needs no Terminal, Homebrew, or administrator access. Gateway setup still needs an internet connection to download its separate runtime and matching OpenClaw package. The bundled installer owns that setup; the private worker is not a replacement for a CLI or Gateway installation. Remote connections and attachment to an independently managed local Gateway skip this installation. Attach-only mode never prompts for a CLI to run the app’s node. Pausing preserves who manages the Gateway, even when stopping an app-managed service removes its LaunchAgent record. If an independent endpoint is no longer available on reattachment, local setup becomes available again. An unreadable service ownership record blocks automatic installation instead of being treated as a missing service; check the LaunchAgent and retry.

​
Manual recovery

For a manual install, use Node 26 (recommended) or another supported release: Node 22.22.3+, Node 24.15+, or Node 25.9+. Install openclaw globally: The command below is for npm 12 or npm 11.16+. On npm 11.15 and earlier, omit --allow-scripts=openclaw.
Use Retry setup after a failed automatic setup. If that still fails, install the CLI manually with the command above, then choose Check again in onboarding.

​
Launchd (Gateway as LaunchAgent)

Label: ai.openclaw.gateway (default profile), or ai.openclaw.<profile> for a named profile. Plist location (per-user): ~/Library/LaunchAgents/ai.openclaw.gateway.plist (or ai.openclaw.<profile>.plist). The macOS app owns LaunchAgent install/update for the default profile in Local mode. The CLI can also install it directly: openclaw gateway install (named profiles are selected via the OPENCLAW_PROFILE env var). Behavior:
  • “OpenClaw Active” enables/disables the LaunchAgent.
  • Quitting the app does not stop the Gateway (launchd keeps it alive).
  • If a Gateway is already running on the configured port, the app attaches to it instead of starting a new one.
Use the CLI for lifecycle checks and recovery:
Launchd provides auto-start at login, crash restarts, and one predictable log location without tying the Gateway lifetime to the app process.

​
Attach-only development

When another process already owns the local Gateway, run the development app without installing or changing its LaunchAgent:
Launching the app directly with --attach-only or --no-launchd has the same effect. The override persists in ~/.openclaw/disable-launchagent; remove that file to restore app-managed launchd behavior. Logging:
  • launchd stdout: ~/Library/Logs/openclaw/gateway.log (profiles use gateway-<profile>.log)
  • launchd stderr: suppressed
  • If the host loops with repeated EADDRINUSE or fast restarts, check for duplicate ai.openclaw.gateway / ai.openclaw.node LaunchAgents and the launchd-marker workaround in Gateway troubleshooting.

​
Version compatibility

The private worker must match the app’s build provenance, not merely its version number. A missing or incompatible worker payload produces a visible worker error; rebuild or reinstall the app. Changing CLI channels or updating a global CLI does not repair this private payload. Unbundled Swift development builds can use the checkout’s freshness-aware source runner instead. For an app-owned local Gateway, the macOS app checks the external CLI against its install policy. Onboarding runs managed setup when that CLI is missing or incompatible. An attached Gateway uses connection and health checks instead of local CLI installation diagnostics. Use Retry setup after a failed managed installation, or Recheck in Connection settings after repairing it.

​
State directory on macOS

Keep OpenClaw state on a local, non-synced disk. Avoid iCloud Drive and other cloud-synced folders; sync latency and file locks can affect sessions, credentials, and Gateway state. Set OPENCLAW_STATE_DIR to a local path only when you need an override. openclaw doctor warns about common cloud-synced state paths and recommends moving back to local storage. See environment variables and Doctor.

​
Debug app connectivity

Use the macOS debug CLI from a source checkout to exercise the same Gateway WebSocket handshake and discovery logic the app uses:
connect accepts --url, --token, --timeout, --probe, and --json (plus client-identity overrides; run with --help for the full list). discover accepts --timeout, --json, and --include-local. Compare discovery output with openclaw gateway discover --json when you need to separate CLI discovery from app-side connection issues.

​
Smoke check

Then: