업데이트

OpenClaw는 빠르게 발전하고 있습니다(pre "1.0"). 업데이트를 인프라 배포처럼 취급하세요: 업데이트 → 확인 실행 → 재시작(또는 openclaw update 사용, 재시작함) → 확인.

권장: 웹사이트 설치 프로그램 다시 실행 (제자리 업그레이드)

선호하는 업데이트 경로는 웹사이트에서 설치 프로그램을 다시 실행하는 것입니다. 기존 설치를 감지하고 제자리에서 업그레이드하며 필요할 때 openclaw doctor를 실행합니다.

curl -fsSL https://openclaw.bot/install.sh | bash

참고:

  • 온보딩 마법사를 다시 실행하고 싶지 않으면 --no-onboard를 추가하세요.
  • 소스 설치의 경우 다음을 사용하세요: 
    curl -fsSL https://openclaw.bot/install.sh | bash -s -- --install-method git --no-onboard
    설치 프로그램은 저장소가 깨끗한 경우에만 git pull --rebase를 실행합니다.
  • 전역 설치의 경우 스크립트는 내부적으로 npm install -g openclaw@latest를 사용합니다.
  • 레거시 참고사항: openclaw는 호환성 심으로 계속 사용할 수 있습니다.

업데이트하기 전에

  • 설치 방법을 알아두세요: 전역 (npm/pnpm) vs 소스에서 (git clone).
  • Gateway가 어떻게 실행되는지 알아두세요: 포그라운드 터미널 vs 감독 서비스 (launchd/systemd).
  • 맞춤 설정을 스냅샷하세요:
    • Config: ~/.openclaw/openclaw.json
    • Credentials: ~/.openclaw/credentials/
    • Workspace: ~/.openclaw/workspace

업데이트 (전역 설치)

전역 설치 (하나 선택):

npm i -g openclaw@latest

pnpm add -g openclaw@latest

Gateway 런타임에 Bun은 권장하지 않습니다 (WhatsApp/Telegram 버그).

업데이트 채널 전환 (git + npm 설치):

openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable

일회성 설치 태그/버전은 --tag <dist-tag|version>를 사용하세요.

채널 의미 및 릴리스 노트는 Development channels를 참조하세요.

참고: npm 설치의 경우 Gateway는 시작 시 업데이트 힌트를 로그에 기록합니다(현재 채널 태그 확인). update.checkOnStart: false로 비활성화합니다.

그런 다음:

openclaw doctor
openclaw gateway restart
openclaw health

참고:

  • Gateway가 서비스로 실행되는 경우 PID를 죽이는 것보다 openclaw gateway restart가 선호됩니다.
  • 특정 버전에 고정된 경우 아래의 "롤백 / 고정"을 참조하세요.

업데이트 (openclaw update)

소스 설치 (git 체크아웃)의 경우 다음을 선호합니다:

openclaw update

안전한 업데이트 플로우를 실행합니다:

  • 깨끗한 worktree가 필요합니다.
  • 선택한 채널(태그 또는 브랜치)로 전환합니다.
  • 구성된 업스트림에 대해 가져오기 + 리베이스 (dev 채널).
  • 의존성 설치, 빌드, Control UI 빌드 및 openclaw doctor 실행.
  • 기본적으로 Gateway를 재시작합니다(--no-restart로 건너뛰기).

npm/pnpm을 통해 설치한 경우(git 메타데이터 없음), openclaw update는 패키지 관리자를 통해 업데이트를 시도합니다. 설치를 감지할 수 없으면 대신 "업데이트 (전역 설치)"를 사용하세요.

업데이트 (Control UI / RPC)

Control UI에는 Update & Restart (RPC: update.run)가 있습니다. 다음을 수행합니다:

  1. openclaw update와 동일한 소스 업데이트 플로우 실행 (git 체크아웃만).
  2. 구조화된 보고서(stdout/stderr tail)로 재시작 센티널을 작성합니다.
  3. Gateway를 재시작하고 보고서로 마지막 활성 세션에 ping합니다.

리베이스가 실패하면 Gateway는 업데이트를 적용하지 않고 중단하고 재시작합니다.

업데이트 (소스에서)

저장소 체크아웃에서:

권장:

openclaw update

수동 (동등함):

git pull
pnpm install
pnpm build
pnpm ui:build # 첫 실행 시 UI 의존성 자동 설치
openclaw doctor
openclaw health

참고:

  • 패키지된 openclaw 바이너리(openclaw.mjs)를 실행하거나 Node를 사용하여 dist/를 실행할 때 pnpm build가 중요합니다.
  • 전역 설치 없이 저장소 체크아웃에서 실행하는 경우 CLI 명령에 pnpm openclaw ...를 사용하세요.
  • TypeScript에서 직접 실행하는 경우(pnpm openclaw ...), 재빌드는 일반적으로 불필요하지만 구성 마이그레이션은 여전히 적용됨 → doctor를 실행하세요.
  • 전역 및 git 설치 간 전환은 쉽습니다: 다른 flavor를 설치한 다음 openclaw doctor를 실행하여 Gateway 서비스 entrypoint가 현재 설치로 다시 작성되도록 하세요.

항상 실행: openclaw doctor

Doctor는 "안전한 업데이트" 명령입니다. 의도적으로 지루합니다: 복구 + 마이그레이션 + 경고.

참고: 소스 설치 (git 체크아웃)인 경우 openclaw doctor는 먼저 openclaw update를 실행하도록 제안합니다.

일반적으로 수행하는 작업:

  • 더 이상 사용되지 않는 구성 키 / 레거시 구성 파일 위치 마이그레이션.
  • DM 정책 감사 및 위험한 "open" 설정에 대한 경고.
  • Gateway 상태 확인 및 재시작 제안 가능.
  • 이전 Gateway 서비스(launchd/systemd; 레거시 schtasks) 감지 및 현재 OpenClaw 서비스로 마이그레이션.
  • Linux에서 systemd 사용자 lingering 확인(Gateway가 로그아웃 후에도 유지되도록).

세부사항: Doctor

Gateway 시작 / 중지 / 재시작

CLI (OS에 관계없이 작동):

openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow

감독되는 경우:

  • macOS launchd (앱 번들 LaunchAgent): launchctl kickstart -k gui/$UID/bot.molt.gateway (bot.molt.<profile> 사용; 레거시 com.openclaw.*도 작동)
  • Linux systemd user service: systemctl --user restart openclaw-gateway[-<profile>].service
  • Windows (WSL2): systemctl --user restart openclaw-gateway[-<profile>].service
    • launchctl/systemctl은 서비스가 설치된 경우에만 작동합니다; 그렇지 않으면 openclaw gateway install을 실행하세요.

Runbook + 정확한 서비스 레이블: Gateway runbook

롤백 / 고정 (문제 발생 시)

고정 (전역 설치)

알려진 양호한 버전 설치 (<version>을 마지막 작동 버전으로 교체):

npm i -g openclaw@<version>

pnpm add -g openclaw@<version>

팁: 현재 게시된 버전을 보려면 npm view openclaw version을 실행하세요.

그런 다음 재시작 + doctor 다시 실행:

openclaw doctor
openclaw gateway restart

날짜별 고정 (소스)

날짜에서 커밋 선택 (예: "2026-01-01 기준 main 상태"):

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"

그런 다음 의존성 재설치 + 재시작:

pnpm install
pnpm build
openclaw gateway restart

나중에 최신으로 돌아가려면:

git checkout main
git pull

막힌 경우

← 문서로 돌아가기