OpenClaw macOS 배포 가이드: Sparkle로 자동 업데이트 구현하기

macOS 앱을 배포할 때 가장 번거로운 작업 중 하나가 바로 업데이트 관리예요. 새로운 버전을 출시할 때마다 사용자가 직접 웹사이트에 방문해 파일을 다운로드하게 만드는 건 사용자 경험 측면에서 아쉬운 부분이죠.

안전하고 신뢰할 수 있는 자동 업데이트 환경을 구축하는 것은 개발자에게 꼭 필요한 작업이에요. OpenClaw는 Sparkle 프레임워크를 사용해 이 과정을 자동화하고 있어요.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• Developer ID Application 인증서: 시스템에 설치되어 있어야 해요. (예: Developer ID Application: <Developer Name> (<TEAMID>))
• Sparkle 개인키: SPARKLE_PRIVATE_KEY_FILE 환경 변수에 ed25519 개인키 경로를 설정해야 해요. (공공키는 Info.plist에 포함됨)
• Notary 자격 증명: Gatekeeper를 통과하기 위한 xcrun notarytool용 openclaw-notary 프로필이 필요해요.
• pnpm: 의존성이 설치되어 있어야 해요. (pnpm install --config.node-linker=hoisted)

빠른 시작

OpenClaw macOS 앱을 빌드하고 패키징하는 5분 완성 가이드예요.

1. 앱 빌드하기

먼저 리포지토리 루트에서 다음 명령어를 실행해 앱을 빌드해요. APP_BUILD를 생략하면 APP_VERSION을 기반으로 자동 생성돼요.

BUNDLE_ID=ai.openclaw.mac \
APP_VERSION=2026.3.7 \
BUILD_CONFIG=release \
SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
scripts/package-mac-app.sh

2. 배포용 파일 패키징 및 Notarization

사용자에게 배포할 Zip 파일과 DMG 파일을 만들고 애플의 공증(Notarization)을 받는 과정이에요.

# Zip 파일 생성
ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.3.7.zip

# Notarize 및 Staple 실행
NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
BUNDLE_ID=ai.openclaw.mac \
APP_VERSION=2026.3.7 \
BUILD_CONFIG=release \
SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
scripts/package-mac-dist.sh

3. Appcast 생성

Sparkle이 업데이트를 감지할 수 있도록 appcast.xml 파일을 업데이트해요. 이 스크립트는 CHANGELOG.md를 HTML로 변환해 릴리스 노트에 포함해 줘요.

SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.3.7.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml

4. 배포 및 확인

• 빌드된 Zip 파일을 GitHub 릴리스에 업로드하세요.
• appcast.xml 파일의 URL이 유효한지 curl -I 명령어로 확인하세요.
• 이전 버전 앱에서 “Check for Updates…”를 실행해 정상적으로 설치되는지 테스트하세요.

문제 해결

배포 과정에서 발생할 수 있는 일반적인 문제와 해결 방법이에요.

• Sparkle 업데이트 감지 실패: APP_BUILD 값은 반드시 숫자여야 하며 이전 버전보다 커야 해요. -beta 같은 문자가 포함되면 Sparkle이 버전을 제대로 비교하지 못할 수 있어요.
• 개인키 유실: SPARKLE_PRIVATE_KEY_FILE이 설정되지 않으면 앱캐스트 서명이 불가능해요. 환경 변수가 비어 있다면 ~/.profile 설정을 확인해 보세요.

##结尾

설정 과정에서 궁금한 점이 생기면 AI Setup Assistant에게 물어보세요!

다음 단계

• GitHub Actions를 이용한 CI 설정
• Sparkle 델타 업데이트 가이드