Thanks to visit codestin.com
Credit goes to docs.openclaw.ai

OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

macOS companion app

macOS dev setup

macOS developer setup

Build and run the OpenClaw macOS application from source.

Prerequisites

  • Xcode 26.2+ (Swift 6.2 toolchain), on the latest macOS available in Software Update.
  • Node.js 24 & pnpm for the gateway, CLI, and packaging scripts. Node 22.19+ also works.

1. Install dependencies

bash
pnpm install

2. Build and package the app

bash
./scripts/package-mac-app.sh

Outputs dist/OpenClaw.app. Without an Apple Developer ID certificate, the script falls back to ad-hoc signing.

For dev run modes, signing flags, and Team ID troubleshooting, see apps/macos/README.md. Fast dev loop from repo root: scripts/restart-mac.sh (add --no-sign for ad-hoc signing; TCC permissions do not stick with --no-sign).

3. Install the CLI and Gateway

The packaged app embeds the canonical scripts/install-cli.sh installer. On a fresh profile, choose This Mac during onboarding; the app installs the matching user-space CLI and runtime before starting the Gateway wizard.

For manual development recovery, install the matching CLI yourself:

bash
npm install -g openclaw@<version>

pnpm add -g openclaw@<version> and bun add -g openclaw@<version> also work. Node remains the recommended runtime for the Gateway itself.

Troubleshooting

Build fails: toolchain or SDK mismatch

The macOS app build expects the latest macOS SDK and the Swift 6.2 toolchain (Xcode 26.2+).

bash
xcodebuild -versionxcrun swift --version

If versions don't match, update macOS/Xcode and re-run the build.

App crashes on permission grant

If the app crashes when you try to allow Speech Recognition or Microphone access, it may be a corrupted TCC cache or signature mismatch.

  1. Reset TCC permissions for the debug bundle id:

    bash
    tccutil reset All ai.openclaw.mac.debug

  2. If that fails, temporarily change BUNDLE_ID in scripts/package-mac-app.sh to force a clean slate from macOS.

Gateway "Starting..." indefinitely

Check whether a zombie process holds the port:

bash
openclaw gateway statusopenclaw gateway stop # If you're not using a LaunchAgent (dev mode / manual runs), find the listener:lsof -nP -iTCP:18789 -sTCP:LISTEN

If a manual run holds the port, stop it (Ctrl+C), or kill the PID found above as a last resort.

Was this useful?
On this page

On this page