mirror of https://github.com/openclaw/openclaw.git synced 2026-07-07 09:17:12 +08:00

Files

Peter Steinberger f7d7148cf0 docs: rewrite published docs grounded in current source (#100142 )

Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green.

Closes #100141

2026-07-05 00:32:47 -04:00

2.8 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

Setup guide for developers working on the OpenClaw macOS app

Setting up the macOS development environment

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

pnpm install

2. Build and package the app

./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).

Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see [Troubleshooting](#troubleshooting).

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:

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+).

xcodebuild -version
xcrun 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.

Reset TCC permissions for the debug bundle id:
```
tccutil reset All ai.openclaw.mac.debug
```
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:

openclaw gateway status
openclaw 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.

2.8 KiB Raw Blame History