OpenClaw 릴리스 가이드: 버전 관리 및 배포 절차

새로운 버전을 배포할 때마다 “혹시 버그가 섞여 들어가진 않았을까?” 걱정하며 배포 버튼 앞에서 망설여본 적 있으시죠? 복잡한 프로젝트일수록 릴리스 과정에서 발생하는 작은 실수가 큰 문제로 이어지곤 합니다.

OpenClaw는 개발자들이 안심하고 배포할 수 있도록 체계적인 릴리스 정책을 운영하고 있어요. 안정적인 배포를 위해 우리가 어떤 규칙을 따르고 있는지, 그리고 배포 과정에서 어떤 체크리스트를 확인하는지 자세히 소개해 드릴게요.

OpenClaw는 세 가지 공개 릴리스 레인을 운영합니다:

• stable: npm beta에 기본으로 게시되거나, 명시적으로 요청 시 npm latest에 게시되는 태그된 릴리스입니다.
• beta: npm beta에 게시되는 프리릴리스 태그입니다.
• dev: main 브랜치의 최신 상태입니다.

버전 네이밍 규칙

• Stable 릴리스 버전: YYYY.M.D
  • Git tag: vYYYY.M.D
• Stable 수정(Correction) 릴리스 버전: YYYY.M.D-N
  • Git tag: vYYYY.M.D-N
• Beta 프리릴리스 버전: YYYY.M.D-beta.N
  • Git tag: vYYYY.M.D-beta.N
• 월 또는 일에 0을 채워 넣지 마세요 (Zero-pad 금지).
• latest는 현재 승인된 stable npm 릴리스를 의미합니다.
• beta는 현재 beta 설치 대상을 의미합니다.
• Stable 및 stable 수정 릴리스는 기본적으로 npm beta에 게시됩니다. 릴리스 담당자는 명시적으로 latest를 타겟팅하거나, 나중에 검증된 beta 빌드를 승격(promote)시킬 수 있습니다.
• 모든 OpenClaw 릴리스는 npm 패키지와 macOS 앱을 함께 출시합니다.

릴리스 주기

• 릴리스는 beta 우선으로 진행됩니다.
• Stable 버전은 최신 beta 버전이 검증된 후에만 출시됩니다.
• 상세한 릴리스 절차, 승인, 자격 증명 및 복구 관련 노트는 메인테이너 전용 문서에서 관리합니다.

릴리스 프리플라이트(Preflight) 체크

• pnpm release:check를 실행하기 전에 pnpm build && pnpm ui:build를 먼저 실행하세요. 그래야 패키지 검증 단계에서 필요한 dist/* 빌드 결과물과 Control UI 번들이 존재합니다.
• 모든 태그된 릴리스 전에 pnpm release:check를 실행하세요.
• Main 브랜치의 npm 프리플라이트는 tarball 패키징 전에 OPENAI_API_KEY와 ANTHROPIC_API_KEY 워크플로우 비밀값을 사용하여 OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache를 실행합니다.
• 승인 전에 RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts (또는 해당되는 beta/수정 태그)를 실행하세요.
• npm 게시 후에는 node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D (또는 해당되는 beta/수정 버전)를 실행하여 새로운 임시 프리픽스에서 게시된 레지스트리 설치 경로를 확인하세요.
• 메인테이너 릴리스 자동화는 이제 ‘프리플라이트 후 승격(preflight-then-promote)’ 방식을 사용합니다:
  • 실제 npm 게시를 위해서는 성공한 npm preflight_run_id가 반드시 필요합니다.
  • Stable npm 릴리스는 기본적으로 beta로 설정됩니다.
  • Stable npm 게시 시 워크플로우 입력을 통해 명시적으로 latest를 타겟팅할 수 있습니다.
  • beta에서 latest로의 stable npm 승격은 신뢰할 수 있는 OpenClaw NPM Release 워크플로우에서 수동 모드로 여전히 가능합니다.
  • npm dist-tag 관리는 신뢰할 수 있는 게시(trusted publishing)와 별개이므로, 승격 모드에서도 npm-release 환경에 유효한 NPM_TOKEN이 필요합니다.
  • 공개 macOS Release는 검증 전용입니다.
  • 실제 프라이빗 mac 게시는 성공적인 프라이빗 mac preflight_run_id 및 validate_run_id를 통과해야 합니다.
  • 실제 게시 경로는 결과물을 다시 빌드하는 대신 준비된 아티팩트를 승격시킵니다.
• YYYY.M.D-N과 같은 stable 수정 릴리스의 경우, 게시 후 검증 도구가 YYYY.M.D에서 YYYY.M.D-N으로의 임시 경로 업그레이드도 함께 체크합니다. 이는 릴리스 수정 시 기존의 글로벌 설치본이 이전 stable 페이로드에 머물러 있지 않도록 하기 위함입니다.
• npm 릴리스 프리플라이트는 tarball에 dist/control-ui/index.html과 비어 있지 않은 dist/control-ui/assets/ 페이로드가 모두 포함되지 않으면 실패 처리됩니다. 이는 빈 브라우저 대시보드가 배포되는 것을 방지하기 위함입니다.
• 릴리스 작업이 CI 계획, 익스텐션 타이밍 매니페스트 또는 익스텐션 테스트 매트릭스를 수정한 경우, 승인 전에 .github/workflows/ci.yml에서 플래너 소유의 checks-node-extensions 워크플로우 매트릭스 출력을 다시 생성하고 검토하세요. 릴리스 노트에 오래된 CI 레이아웃이 설명되지 않도록 주의해야 합니다.
• Stable macOS 릴리스 준비 상태에는 업데이트 관련 요소도 포함됩니다:
  • GitHub 릴리스에는 패키징된 .zip, .dmg, .dSYM.zip 파일이 포함되어야 합니다.
  • 게시 후 main 브랜치의 appcast.xml은 새로운 stable zip을 가리켜야 합니다.
  • 패키징된 앱은 디버그용이 아닌 번들 ID, 비어 있지 않은 Sparkle 피드 URL, 그리고 해당 릴리스 버전의 표준 Sparkle 빌드 플로어 이상의 CFBundleVersion을 유지해야 합니다.

NPM 워크플로우 입력값

OpenClaw NPM Release는 운영자가 제어하는 다음 입력값들을 받습니다:

• tag: v2026.4.2, v2026.4.2-1, 또는 v2026.4.2-beta.1과 같은 필수 릴리스 태그입니다.
• preflight_only: 검증/빌드/패키징만 수행하려면 true, 실제 게시를 진행하려면 false로 설정합니다.
• preflight_run_id: 실제 게시 경로에서 필수입니다. 워크플로우가 성공적인 프리플라이트 실행에서 준비된 tarball을 재사용하도록 합니다.
• npm_dist_tag: 게시 경로를 위한 npm 타겟 태그이며, 기본값은 beta입니다.
• promote_beta_to_latest: 이미 게시된 stable beta 빌드를 latest로 옮기고 게시 과정을 건너뛰려면 true로 설정합니다.

규칙:

• Stable 및 수정 태그는 beta 또는 latest로 게시할 수 있습니다.
• Beta 프리릴리스 태그는 beta로만 게시할 수 있습니다.
• 실제 게시 경로는 프리플라이트 중에 사용된 것과 동일한 npm_dist_tag를 사용해야 합니다. 워크플로우는 게시를 계속하기 전에 이 메타데이터를 확인합니다.
• 승격(Promotion) 모드는 stable 또는 수정 태그를 사용해야 하며, preflight_only=false, 빈 preflight_run_id, 그리고 npm_dist_tag=beta 설정을 사용해야 합니다.
• 승격 모드에서도 npm dist-tag add 명령에는 일반적인 npm 인증이 필요하므로 npm-release 환경에 유효한 NPM_TOKEN이 필요합니다.

Stable NPM 릴리스 절차

Stable npm 릴리스를 진행할 때의 순서입니다:

1. preflight_only=true 옵션으로 OpenClaw NPM Release를 실행합니다.
2. 일반적인 beta 우선 흐름을 원하면 npm_dist_tag=beta를 선택하고, 의도적으로 직접 stable 게시를 원할 때만 latest를 선택합니다.
3. 성공한 preflight_run_id를 저장합니다.
4. 동일한 tag, 동일한 npm_dist_tag, 그리고 저장해둔 preflight_run_id를 사용하여 OpenClaw NPM Release를 다시 실행합니다 (preflight_only=false).
5. 만약 릴리스가 beta에 게시되었다면, 나중에 해당 빌드를 latest로 옮기고 싶을 때 동일한 stable tag, promote_beta_to_latest=true, preflight_only=false, 빈 preflight_run_id, 그리고 npm_dist_tag=beta 옵션으로 실행합니다.

승격 모드는 여전히 npm-release 환경 승인과 해당 환경의 유효한 NPM_TOKEN이 필요합니다.

이러한 방식을 통해 직접 게시 경로와 beta 우선 승격 경로를 모두 문서화하고 운영자가 가시적으로 확인할 수 있게 유지합니다.

공개 참조 링크

• .github/workflows/openclaw-npm-release.yml
• scripts/openclaw-npm-release-check.ts
• scripts/package-mac-dist.sh
• scripts/make_appcast.sh

메인테이너는 실제 실행 지침을 위해 openclaw/maintainers/release/README.md에 있는 프라이빗 릴리스 문서를 사용합니다.

다음 단계

• 설치 가이드 보러 가기
• 기여 방법 알아보기

AI Setup Assistant