​

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

리포지토리 루트에서 pnpm (Node 22+)를 사용합니다. 태깅/게시 전에 작업 트리를 깨끗하게 유지합니다.

​

운영자 트리거

운영자가 “release”라고 말하면, 차단되는 경우가 아니라면 추가 질문 없이 즉시 다음 사전 점검을 수행합니다.

• 이 문서와 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 및 src/provider-web.ts의 Baileys 사용자 에이전트.
• 패키지 메타데이터(이름, 설명, 저장소, 키워드, 라이선스)를 확인하고, bin 맵이 openclaw에 대해 openclaw.mjs를 가리키는지 확인합니다.
• 의존성이 변경되었다면 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 pack 내용 검증)
• 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 (두 키 모두 필요; 두 프로바이더 실행)
• (선택 사항) 변경 사항이 송수신 경로에 영향을 주는 경우 웹 Gateway(게이트웨이)를 스폿 체크합니다.

5. macOS 앱 (Sparkle)

• macOS 앱을 빌드 및 서명한 후 배포용으로 zip 합니다.
• Sparkle appcast 를 생성하고(HTML 노트는 scripts/make_appcast.sh 사용) appcast.xml를 업데이트합니다.
• 앱 zip (및 선택 사항인 dSYM zip)을 GitHub 릴리스에 첨부할 수 있도록 준비합니다.
• 정확한 명령과 필요한 환경 변수는 macOS release를 따릅니다.
  • APP_BUILD는 숫자형이며 단조 증가해야 합니다 (-beta 금지). 그래야 Sparkle 이 버전을 올바르게 비교합니다.
  • 공증을 수행하는 경우 App Store Connect API 환경 변수로 생성한 openclaw-notary 키체인 프로파일을 사용합니다 (macOS release 참조).

6. 게시 (npm)

• git 상태가 깨끗한지 확인하고, 필요 시 커밋 및 푸시합니다.
• 필요 시 npm login (2FA 확인).
• npm publish --access public (프리릴리스에는 --tag beta 사용).
• 레지스트리를 확인합니다: npm view openclaw version, npm view openclaw dist-tags, 및 npx -y [email protected] --version (또는 --help).

​

문제 해결 (2.0.0-beta2 릴리스의 메모)

• npm pack/publish 가 멈추거나 매우 큰 tarball 을 생성함: dist/OpenClaw.app의 macOS 앱 번들(및 릴리스 zip)이 패키지에 포함됩니다. package.json files로 게시 콘텐츠를 화이트리스트하여 수정합니다 (dist 하위 디렉토리, docs, skills 포함; 앱 번들 제외). npm pack --dry-run로 dist/OpenClaw.app가 목록에 없는지 확인합니다.
• dist-tags 에서 npm 인증 웹 루프: OTP 프롬프트를 받기 위해 레거시 인증을 사용합니다:
  • NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add [email protected] latest
• npx 검증이 ECOMPROMISED: Lock compromised로 실패함: 새 캐시로 재시도합니다:
  • NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y [email protected] --version
• 늦은 수정 후 태그 재지정이 필요함: 태그를 강제로 업데이트하고 푸시한 다음, GitHub 릴리스 자산이 여전히 일치하는지 확인합니다:
  • git tag -f vX.Y.Z && git push -f origin vX.Y.Z

7. GitHub 릴리스 + appcast

• 태그 지정 및 푸시: git tag vX.Y.Z && git push origin vX.Y.Z (또는 git push --tags).
• vX.Y.Z에 대한 GitHub 릴리스를 생성/갱신하고 **제목은 openclaw X.Y.Z**로 설정합니다(태그만 사용하지 마십시오). 본문에는 해당 버전의 전체 변경 로그 섹션(Highlights + Changes + Fixes)을 인라인으로 포함해야 하며(단순 링크 금지), 본문에 제목을 반복해서는 안 됩니다.
• 산출물을 첨부합니다: npm pack tarball (선택 사항), OpenClaw-X.Y.Z.zip, 및 OpenClaw-X.Y.Z.dSYM.zip (생성된 경우).
• 업데이트된 appcast.xml를 커밋하고 푸시합니다 (Sparkle 은 main 에서 피드를 가져옵니다).
• 깨끗한 임시 디렉토리(package.json 없음)에서 npx -y [email protected] send --help를 실행하여 설치/CLI 진입점이 정상 동작하는지 확인합니다.
• 릴리스 노트를 공지/공유합니다.

​

플러그인 게시 범위 (npm)

우리는 @openclaw/* 스코프 아래의 기존 npm 플러그인만 게시합니다. npm 에 없는 번들 플러그인은 디스크 트리 전용으로 유지됩니다(여전히 extensions/**에 포함되어 배포됨). 목록을 도출하는 과정:

1. npm search @openclaw --json를 실행하고 패키지 이름을 수집합니다.
2. extensions/*/package.json 이름과 비교합니다.
3. 교집합(이미 npm 에 존재하는 것)만 게시합니다.

현재 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

릴리스 노트에는 기본값으로 켜져 있지 않은 새로운 선택적 번들 플러그인도 반드시 명시해야 합니다(예: tlon).