업데이트

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

권장: 웹사이트 설치 스크립트 재실행 (제자리 업그레이드)

권장 업데이트 경로는 웹사이트의 설치 스크립트를 다시 실행하는 것입니다. 기존 설치를 감지하고, 제자리에서 업그레이드하며, 필요시 openclaw doctor를 실행합니다.

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

참고:

  • 온보딩 마법사를 다시 실행하고 싶지 않으면 --no-onboard를 추가하세요.

  • 소스 설치의 경우:

    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

    설치 프로그램은 저장소가 클린한 경우에만 git pull --rebase를 실행합니다.

  • 전역 설치의 경우, 스크립트는 내부적으로 npm install -g openclaw@latest를 사용합니다.

  • 레거시 참고: clawdbot는 호환성 심으로 계속 사용 가능합니다.

업데이트 전 확인사항

  • 설치 방법을 파악하세요: 전역 (npm/pnpm) vs 소스에서 (git clone).
  • 게이트웨이 실행 방식을 파악하세요: 포그라운드 터미널 vs 관리형 서비스 (launchd/systemd).
  • 맞춤 설정을 스냅샷하세요:
    • 설정: ~/.openclaw/openclaw.json
    • 인증 정보: ~/.openclaw/credentials/
    • 워크스페이스: ~/.openclaw/workspace

업데이트 (전역 설치)

전역 설치 (하나 선택):

npm i -g openclaw@latest
pnpm add -g openclaw@latest

게이트웨이 런타임에는 Bun을 권장하지 않습니다 (WhatsApp/Telegram 버그).

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

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

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

채널 의미와 릴리스 노트는 개발 채널을 참고하세요.

참고: npm 설치에서 게이트웨이는 시작 시 업데이트 힌트를 로그합니다(현재 채널 태그 확인). update.checkOnStart: false로 비활성화할 수 있습니다.

코어 자동 업데이터 (선택사항)

자동 업데이터는 기본적으로 꺼져 있으며 플러그인이 아닌 코어 게이트웨이 기능입니다.

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

동작:

  • stable: 새 버전이 감지되면 stableDelayHours 만큼 대기한 후 stableJitterHours 범위의 설치별 결정론적 지터를 적용합니다(분산 롤아웃).
  • beta: betaCheckIntervalHours 주기(기본: 매시간)로 확인하고 업데이트가 있으면 적용합니다.
  • dev: 자동 적용 없음. 수동으로 openclaw update를 사용하세요.

자동화를 활성화하기 전에 openclaw update --dry-run으로 업데이트 동작을 미리 확인하세요.

이후:

openclaw doctor
openclaw gateway restart
openclaw health

참고:

  • 게이트웨이가 서비스로 실행 중이면 PID를 직접 종료하는 것보다 openclaw gateway restart가 권장됩니다.
  • 특정 버전에 고정되어 있다면 아래 “롤백 / 버전 고정”을 참고하세요.

업데이트 (openclaw update)

소스 설치 (git 체크아웃)의 경우:

openclaw update

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

  • 클린 워크트리가 필요합니다.
  • 선택한 채널(태그 또는 브랜치)로 전환합니다.
  • 설정된 업스트림에서 페치 + 리베이스합니다(dev 채널).
  • 의존성 설치, 빌드, Control UI 빌드, openclaw doctor 실행.
  • 기본적으로 게이트웨이를 재시작합니다(--no-restart로 건너뛰기).

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

업데이트 (Control UI / RPC)

Control UI에는 업데이트 및 재시작 (RPC: update.run)이 있습니다. 동작:

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

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

업데이트 (소스에서)

저장소 체크아웃에서:

권장:

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 설치 간 전환은 쉽습니다: 다른 방식을 설치한 뒤 openclaw doctor를 실행하면 게이트웨이 서비스 엔트리포인트가 현재 설치로 다시 작성됩니다.

항상 실행: openclaw doctor

Doctor는 “안전한 업데이트” 명령어입니다. 의도적으로 지루합니다: 수리 + 마이그레이션 + 경고.

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

일반적으로 하는 일:

  • 더 이상 사용되지 않는 설정 키 / 레거시 설정 파일 위치를 마이그레이션합니다.
  • DM 정책을 감사하고 위험한 “open” 설정에 대해 경고합니다.
  • 게이트웨이 상태를 확인하고 재시작을 제안할 수 있습니다.
  • 이전 게이트웨이 서비스(launchd/systemd; 레거시 schtasks)를 현재 OpenClaw 서비스로 감지하고 마이그레이션합니다.
  • Linux에서 systemd 사용자 링거링을 보장합니다(게이트웨이가 로그아웃 후에도 생존).

상세: Doctor

게이트웨이 시작 / 중지 / 재시작

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/ai.openclaw.gateway (ai.openclaw.<profile> 사용; 레거시 com.openclaw.*도 작동)
  • Linux systemd 사용자 서비스: systemctl --user restart openclaw-gateway[-<profile>].service
  • Windows (WSL2): systemctl --user restart openclaw-gateway[-<profile>].service
    • launchctl/systemctl은 서비스가 설치된 경우에만 작동합니다. 그렇지 않으면 openclaw gateway install을 실행하세요.

런북 + 정확한 서비스 레이블: 게이트웨이 런북

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

버전 고정 (전역 설치)

정상 작동하던 버전을 설치합니다(<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

문제가 해결되지 않으면

  • openclaw doctor를 다시 실행하고 출력을 주의 깊게 읽으세요(수정 방법을 알려주는 경우가 많습니다).
  • 확인: 문제 해결
  • Discord에서 질문: https://discord.gg/clawd
arrow_back
이전
Bun
다음
Migrating
arrow_forward