macOS 개발자 설정

이 가이드는 OpenClaw macOS 애플리케이션을 소스에서 빌드하고 실행하는 데 필요한 단계를 다룹니다.

사전 요구 사항

앱을 빌드하기 전에 다음이 설치되어 있는지 확인하세요:

Xcode 26.2+: Swift 개발에 필요합니다.
Node.js 24 및 pnpm: 게이트웨이, CLI, 패키징 스크립트에 권장됩니다. Node 22 LTS(현재 22.16+)도 호환성을 위해 지원됩니다.

프로젝트 전체 의존성을 설치합니다:

pnpm install

macOS 앱을 빌드하고 dist/OpenClaw.app으로 패키징하려면:

./scripts/package-mac-app.sh

Apple Developer ID 인증서가 없으면, 스크립트가 자동으로 ad-hoc 서명(-)을 사용합니다.

개발 실행 모드, 서명 플래그, Team ID 문제 해결에 대해서는 macOS 앱 README를 참조하세요: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

참고: Ad-hoc 서명된 앱은 보안 프롬프트를 유발할 수 있습니다. 앱이 “Abort trap 6”으로 즉시 충돌하면 문제 해결 섹션을 참조하세요.

macOS 앱은 백그라운드 작업을 관리하기 위해 전역 openclaw CLI 설치를 필요로 합니다.

설치 방법 (권장):

또는 수동으로 설치:

npm install -g openclaw@<version>

macOS 앱 빌드는 최신 macOS SDK와 Swift 6.2 툴체인을 필요로 합니다.

시스템 의존성 (필수):

확인:

xcodebuild -version
xcrun swift --version

버전이 맞지 않으면 macOS/Xcode를 업데이트하고 빌드를 다시 실행하세요.

음성 인식 또는 마이크 접근을 허용할 때 앱이 충돌하면, 손상된 TCC 캐시나 서명 불일치 때문일 수 있습니다.

해결 방법:

TCC 권한을 초기화합니다:
```
tccutil reset All ai.openclaw.mac.debug
```
그래도 실패하면, scripts/package-mac-app.sh에서 BUNDLE_ID를 임시로 변경하여 macOS가 “새로운 상태”로 인식하게 합니다.

게이트웨이 상태가 “Starting…”에 머물러 있으면, 좀비 프로세스가 포트를 점유하고 있는지 확인하세요:

openclaw gateway status
openclaw gateway stop

# LaunchAgent를 사용하지 않는 경우 (개발 모드 / 수동 실행), 리스너 찾기:
lsof -nP -iTCP:18789 -sTCP:LISTEN

수동 실행이 포트를 점유 중이면 해당 프로세스를 중지하세요(Ctrl+C). 최후의 수단으로 위에서 찾은 PID를 종료하세요.