macOS용 OpenClaw 빌드 및 설치 가이드

새로운 오픈소스 프로젝트를 내 로컬 환경에 빌드하려고 할 때, 예상치 못한 설정 오류나 버전 충돌로 고생한 적 있으신가요? 특히 macOS 환경에서 특정 toolchain이나 의존성 문제로 빌드가 막히면 참 답답하죠.

OpenClaw를 소스 코드에서 직접 빌드하고 실행하고 싶은 개발자분들을 위해, 환경 설정부터 문제 해결까지 꼭 필요한 단계들을 정리했습니다. 이 가이드를 따라 차근차근 진행하면 macOS에서 OpenClaw를 성공적으로 구동할 수 있어요.

macOS 개발 환경 설정

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

사전 준비 사항 (Prerequisites)

앱을 빌드하기 전에 다음 도구들이 설치되어 있는지 확인해 주세요.

1. Xcode 26.2+: Swift 개발을 위해 꼭 필요해요.
2. Node.js 24 & pnpm: Gateway, CLI, 패키징 스크립트 실행에 권장해요. 호환성을 위해 Node 22 LTS(현재 22.14+) 버전도 계속 지원하고 있어요.

1. 의존성 설치 (Install Dependencies)

먼저 프로젝트 전체에서 사용하는 의존성 패키지들을 설치합니다.

pnpm install

2. 앱 빌드 및 패키징 (Build and Package the App)

macOS 앱을 빌드하고 dist/OpenClaw.app 경로로 패키징하려면 다음 명령어를 실행하세요.

./scripts/package-mac-app.sh

Apple Developer ID 인증서가 없는 경우, 스크립트가 자동으로 ad-hoc signing(-)을 사용해서 서명해요.

개발 실행 모드, 서명 플래그, Team ID 관련 트러블슈팅에 대해서는 macOS 앱 README 파일을 참고해 주세요. https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

참고: Ad-hoc 서명된 앱은 보안 경고 팝업을 띄울 수 있어요. 만약 앱이 실행되자마자 “Abort trap 6” 오류와 함께 종료된다면 문제 해결 섹션을 확인해 보세요.

3. CLI 설치 (Install the CLI)

macOS 앱은 백그라운드 작업을 관리하기 위해 전역(global)으로 설치된 openclaw CLI를 사용해요.

설치 방법 (권장):

1. OpenClaw 앱을 실행합니다.
2. General 설정 탭으로 이동합니다.
3. “Install CLI” 버튼을 클릭합니다.

또는 다음과 같이 수동으로 설치할 수도 있어요.

npm install -g openclaw@<version>

문제 해결 (Troubleshooting)

빌드 실패: Toolchain 또는 SDK 불일치

macOS 앱 빌드에는 최신 macOS SDK와 Swift 6.2 toolchain이 필요해요.

필수 시스템 요구 사항:

• 소프트웨어 업데이트에서 사용 가능한 최신 macOS 버전 (Xcode 26.2 SDK 사용을 위해 필요)
• Xcode 26.2 (Swift 6.2 toolchain 포함)

버전 확인 방법:

xcodebuild -version
xcrun swift --version

버전이 일치하지 않는다면 macOS와 Xcode를 업데이트한 뒤 빌드를 다시 시도해 보세요.

권한 허용 시 앱 종료

Speech Recognition이나 Microphone 접근 권한을 허용할 때 앱이 갑자기 종료된다면, TCC 캐시가 손상되었거나 서명(signature)이 일치하지 않아서 발생한 문제일 수 있어요.

해결 방법:

1. TCC 권한 설정을 초기화합니다.

   tccutil reset All ai.openclaw.mac.debug

2. 위 방법으로 해결되지 않는다면, scripts/package-mac-app.sh 파일에서 BUNDLE_ID를 임시로 변경해 보세요. macOS가 앱을 완전히 새로운 상태로 인식하게 하여 문제를 해결할 수 있어요.

Gateway가 “Starting…” 상태에서 멈추는 경우

Gateway 상태가 계속 “Starting…”에 머물러 있다면, 종료되지 않은 좀비 프로세스가 포트를 점유하고 있는지 확인해야 해요.

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

수동으로 실행한 프로세스가 포트를 잡고 있다면 해당 프로세스를 종료(Ctrl+C)하세요. 마지막 수단으로 위 명령어로 찾은 PID를 직접 강제 종료할 수 있어요.

AI Setup Assistant

다음 단계

• macOS 앱 상세 README
• CLI 명령어 가이드