​

릴리스 체크리스트 (npm + macOS)

​

운영자 트리거

• 이 문서와 docs/platforms/mac/release.md를 읽으세요.
• ~/.profile에서 환경을 로드하고 SPARKLE_PRIVATE_KEY_FILE + App Store Connect 변수들이 설정되어 있는지 확인하세요 (SPARKLE_PRIVATE_KEY_FILE은 ~/.profile에 있어야 합니다).
• 필요하다면 ~/Library/CloudStorage/Dropbox/Backup/Sparkle에서 Sparkle 키를 사용하세요.

1. 버전 및 메타데이터

• package.json 버전 올리기 (예: 2026.1.29).
• pnpm plugins:sync를 실행하여 확장 패키지 버전 및 변경 로그를 정렬합니다.
• CLI / 버전 문자열 업데이트: src/cli/program.ts 및 Baileys 사용자 에이전트를 src/provider-web.ts에서 업데이트합니다.
• 패키지 메타데이터(이름, 설명, 리포지토리, 키워드, 라이선스) 및 bin 맵이 openclaw.mjs를 openclaw로 가리키는지 확인합니다.
• 종속성이 변경되었다면, pnpm install을 실행하여 pnpm-lock.yaml을 최신 상태로 만듭니다.

2. 빌드 및 아티팩트

• A2UI 입력이 변경되었다면, pnpm canvas:a2ui:bundle을 실행하고 업데이트된 src/canvas-host/a2ui/a2ui.bundle.js를 커밋합니다.
• pnpm run build (재생성 dist/).
• npm 패키지 files에 모든 필수 dist/* 폴더가 포함되어 있는지 확인합니다 (특히 무인 노드 및 ACP CLI를 위한 dist/node-host/** 및 dist/acp/**).
• dist/build-info.json이 존재하며 예상 commit 해시가 포함되어 있는지 확인합니다 (CLI 배너는 npm 설치에 이 정보를 사용합니다).
• 선택 사항: 빌드 후 npm pack --pack-destination /tmp을 실행하세요; tarball 내용을 검사하고 GitHub 릴리스에 대비해 준비해 두세요 (커밋하지는 마세요).

3. 변경 로그 및 문서

• 사용자 대상의 하이라이트로 CHANGELOG.md를 업데이트하세요 (파일이 없다면 만드세요); 항목을 버전 순으로 내림차순으로 유지하세요.
• README 예제/플래그가 현재 CLI 동작에 맞도록 업데이트하세요 (특히 새로운 명령어나 옵션).

4. 검증

• pnpm build
• pnpm check
• pnpm test (또는 커버리지 출력이 필요하다면 pnpm test:coverage)
• pnpm release:check (npm 패키지 내용을 검증합니다)
• OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke (Docker 설치 간이 테스트, 빠른 경로; 릴리스 전에 필수)
  • 만약 직전의 npm 릴리스가 문제가 있는 것으로 알려져 있다면, 사전 설치 단계에서 OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version> 또는 OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1을 설정하세요.
• (선택 사항) 전체 설치 간이 테스트 (비 루트 및 CLI 커버리지 추가): pnpm test:install:smoke
• (선택 사항) 설치자 E2E (Docker, curl -fsSL https://openclaw.ai/install.sh | bash를 실행하고, 온보딩 후 실제 도구 호출 실행):
  • pnpm test:install:e2e:openai (OPENAI_API_KEY 필요)
  • pnpm test:install:e2e:anthropic (ANTHROPIC_API_KEY 필요)
  • pnpm test:install:e2e (두 키 모두 필요; 두 프로바이더 실행)
• (선택 사항) 변경 사항이 송수신 경로에 영향을 미치는 경우 웹 게이트웨이를 점검하세요.

5. macOS 앱 (Sparkle)

• macOS 앱을 빌드하고 서명한 후 배포를 위해 압축하세요.
• Sparkle 앱캐스트 생성 (HTML 노트는 scripts/make_appcast.sh를 통해) 및 appcast.xml을 업데이트하세요.
• 앱 압축 파일 및 선택적 dSYM 압축 파일을 GitHub 릴리스에 첨부할 준비를 하세요.
• 정확한 명령어 및 필요한 환경 변수를 위해 macOS 릴리스를 따르세요.
  • APP_BUILD는 버전 비교가 제대로 이루어지도록 숫자 및 단조 증가해야 합니다 (no -beta).
  • 공증을 하는 경우, App Store Connect API 환경 변수에서 생성된 openclaw-notary 키체인 프로파일을 사용하세요 (macOS 릴리스 참조).

6. 게시 (npm)

• git 상태가 깨끗한지 확인하고 필요한 경우 커밋 및 푸시하세요.
• 필요한 경우 npm login (2FA 확인).
• npm publish --access public (사전 릴리스에는 --tag beta를 사용).
• 레지스트리 확인: npm view openclaw version, npm view openclaw dist-tags, 그리고 npx -y openclaw@X.Y.Z --version (또는 --help).

​

문제 해결 (2.0.0-beta2 릴리스의 노트에서)

• npm pack/publish가 멈추거나 큰 tarball을 생성함: dist/OpenClaw.app 내의 macOS 앱 번들 (및 릴리스 zip 파일)이 패키지에 포함됩니다. 게시 내용을 package.json files를 통해 화이트리스트로 관리해 해결하세요 (dist 하위 디렉토리, 문서, 스킬 포함; 앱 번들 제외). npm pack --dry-run으로 dist/OpenClaw.app가 목록에 나오지 않는지 확인하세요.
• dist-tags에 대한 npm 인증 웹 루프: OTP 프롬프트를 얻기 위해 레거시 인증을 사용하세요:
  • NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add openclaw@X.Y.Z latest
• npx 인증 실패 및 ECOMPROMISED: Lock compromised 에러: 새로운 캐시로 다시 시도:
  • NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y openclaw@X.Y.Z --version
• 늦은 수정 후 태그가 재지정 필요: 태그를 강제 업데이트 및 푸시하고, GitHub 릴리스 에셋이 여전히 맞는지 확인하세요:
  • git tag -f vX.Y.Z && git push -f origin vX.Y.Z

7. GitHub 릴리스 + 앱캐스트

• 태그 및 푸시: git tag vX.Y.Z && git push origin vX.Y.Z (또는 git push --tags).
• vX.Y.Z에 대한 GitHub 릴리스를 생성/새로 고침하며 **제목 openclaw X.Y.Z**을 사용하세요 (단순 태그명이 아닌); 본문은 해당 버전에 대한 전체 변경 로그 섹션을 포함해야 하며 (하이라이트 + 변경사항 + 수정사항) 인라인으로 제공되며, 본문에 제목을 반복해서는 안 됩니다.
• 아티팩트 첨부: npm pack tarball (선택적), OpenClaw-X.Y.Z.zip, 및 OpenClaw-X.Y.Z.dSYM.zip (생성된 경우).
• 업데이트된 appcast.xml을 커밋하고 푸시하세요 (Sparkle은 메인에서 공급됩니다).
• 깨끗한 임시 디렉토리에서 (no package.json), npx -y openclaw@X.Y.Z send --help를 실행하여 설치/CLI 진입점이 동작하는지 확인합니다.
• 릴리스 노트를 발표/공유하세요.

​

플러그인 출판 범위 (npm)

1. npm search @openclaw --json을 사용하여 패키지 이름을 캡처합니다.
2. extensions/*/package.json 이름과 비교합니다.
3. 교집합만 게시 (이미 npm에 있는 것들).

• @openclaw/bluebubbles
• @openclaw/diagnostics-otel
• @openclaw/discord
• @openclaw/feishu
• @openclaw/lobster
• @openclaw/matrix
• @openclaw/msteams
• @openclaw/nextcloud-talk
• @openclaw/nostr
• @openclaw/voice-call
• @openclaw/zalo
• @openclaw/zalouser