Przejdź do głównej treści

​
Konfiguracja deweloperska macOS

Ten przewodnik obejmuje niezbędne kroki do zbudowania i uruchomienia aplikacji OpenClaw na 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 pakowania. Node 22 LTS, obecnie 22.14+, pozostaje obsługiwany dla zgodności.

​
1. Zainstaluj zależności

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

​
2. Zbuduj i spakuj aplikację

Aby zbudować aplikację macOS i spakować ją do dist/OpenClaw.app, uruchom: 
./scripts/package-mac-app.sh
Jeśli nie masz certyfikatu Apple Developer ID, skrypt automatycznie użyje podpisu ad-hoc (-). Tryby uruchamiania deweloperskiego, flagi podpisywania i rozwiązywanie problemów z Team ID opisano w README aplikacji macOS: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md
Uwaga: Aplikacje podpisane ad-hoc mogą wywoływać prompty bezpieczeństwa. Jeśli aplikacja natychmiast się wyłącza z komunikatem „Abort trap 6”, zobacz sekcję Rozwiązywanie problemów.

​
3. Zainstaluj CLI

Aplikacja macOS oczekuje globalnej instalacji CLI openclaw, aby zarządzać zadaniami w tle. Aby je zainstalować (zalecane):
  1. Otwórz aplikację OpenClaw.
  2. Przejdź do karty ustawień General.
  3. Kliknij “Install CLI”.
Alternatywnie zainstaluj je ręcznie: 
npm install -g openclaw@<version>
pnpm add -g openclaw@<version> i bun add -g openclaw@<version> również działają. Dla środowiska uruchomieniowego Gateway Node pozostaje zalecaną ścieżką.

​
Rozwiązywanie problemów

​
Kompilacja kończy się niepowodzeniem: niezgodność toolchain lub SDK

Kompilacja aplikacji macOS oczekuje najnowszego SDK macOS i toolchain 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 -version
xcrun swift --version
Jeśli wersje się nie zgadzają, zaktualizuj macOS/Xcode i ponownie uruchom kompilację.

​
Aplikacja ulega awarii przy przyznawaniu uprawnień

Jeśli aplikacja ulega awarii, gdy próbujesz zezwolić na dostęp do Speech Recognition lub Microphone, może to wynikać z uszkodzonej pamięci podręcznej TCC lub niezgodności podpisu. Naprawa:
  1. Zresetuj uprawnienia TCC: 
    tccutil reset All ai.openclaw.mac.debug
  2. Jeśli to nie pomoże, tymczasowo zmień BUNDLE_ID w scripts/package-mac-app.sh, aby wymusić „czysty stan” w macOS.

​
Gateway „Starting…” bez końca

Jeśli status gateway pozostaje na „Starting…”, sprawdź, czy procesu zombie nie trzyma portu: 
openclaw gateway status
openclaw gateway stop

# Jeśli nie używasz LaunchAgent (tryb deweloperski / uruchomienia ręczne), znajdź listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN
Jeśli port jest zajęty przez ręczne uruchomienie, zatrzymaj ten proces (Ctrl+C). W ostateczności zabij PID znaleziony powyżej.