Konfiguracja środowiska deweloperskiego macOS

Zbuduj i uruchom aplikację OpenClaw dla macOS ze źródeł.

Wymagania wstępne

Przed zbudowaniem aplikacji upewnij się, że masz zainstalowane:

1. Xcode 26.2+: Wymagany do programowania w Swift.
2. Node.js 24 i pnpm: Zalecane dla Gateway, CLI i skryptów pakietowania. Node 22 LTS, obecnie 22.19+, pozostaje obsługiwany ze względów zgodności.

1. Zainstaluj zależności

Zainstaluj zależności dla całego projektu:

pnpm install

2. Zbuduj i spakietuj aplikację

Aby zbudować aplikację macOS i spakietować ją do dist/OpenClaw.app, uruchom:

./scripts/package-mac-app.sh

Jeśli nie masz certyfikatu Apple Developer ID, skrypt automatycznie użyje podpisywania ad-hoc (-).

Tryby uruchamiania deweloperskiego, flagi podpisywania i rozwiązywanie problemów z Team ID opisuje README aplikacji macOS: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

Uwaga: Aplikacje podpisane ad-hoc mogą wywoływać monity bezpieczeństwa. Jeśli aplikacja natychmiast ulega awarii z komunikatem „Abort trap 6”, zobacz sekcję Rozwiązywanie problemów.

3. Zainstaluj CLI i Gateway

Spakietowana aplikacja zawiera kanoniczny instalator scripts/install-cli.sh. W nowym profilu wybierz This Mac podczas wdrażania; aplikacja instaluje pasujące CLI i środowisko uruchomieniowe w przestrzeni użytkownika przed uruchomieniem kreatora Gateway.

Do ręcznego odzyskiwania środowiska deweloperskiego zainstaluj pasujące CLI samodzielnie:

npm install -g openclaw@<version>

pnpm add -g openclaw@<version> i bun add -g openclaw@<version> również działają. Dla środowiska uruchomieniowego Gateway zalecaną ścieżką pozostaje Node.

Rozwiązywanie problemów

Kompilacja nie powiodła się: niezgodność toolchaina lub SDK

Kompilacja aplikacji macOS oczekuje najnowszego macOS SDK i toolchaina Swift 6.2.

Zależności systemowe (wymagane):

• Najnowsza wersja macOS dostępna w Software Update (wymagana przez SDK Xcode 26.2)
• Xcode 26.2 (toolchain Swift 6.2)

Kontrole:

xcodebuild -versionxcrun swift --version

Jeśli wersje się nie zgadzają, zaktualizuj macOS/Xcode i ponownie uruchom kompilację.

Aplikacja ulega awarii podczas nadawania uprawnień

Jeśli aplikacja ulega awarii podczas próby zezwolenia na dostęp do Rozpoznawania mowy lub Mikrofonu, przyczyną może być uszkodzona pamięć podręczna TCC albo niezgodność podpisu.

Poprawka:

1. Zresetuj uprawnienia TCC:

   tccutil reset All ai.openclaw.mac.debug

2. Jeśli to się nie powiedzie, tymczasowo zmień BUNDLE_ID w scripts/package-mac-app.sh, aby wymusić „czysty stan” z perspektywy macOS.

Gateway „Starting...” bez końca

Jeśli status Gateway pozostaje na „Starting...”, sprawdź, czy proces zombie nie zajmuje portu:

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

Jeśli ręczne uruchomienie zajmuje port, zatrzymaj ten proces (Ctrl+C). W ostateczności zabij znaleziony powyżej PID.

Powiązane

• Aplikacja macOS
• Omówienie instalacji