OpenClaw를 최신 상태로 유지하세요.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
권장: openclaw update
가장 빠른 업데이트 방법입니다. 설치 유형(npm 또는 git)을 감지하고, 최신 버전을 가져오고, openclaw doctor를 실행한 다음 Gateway를 다시 시작합니다.
openclaw update는 --verbose를 허용하지 않습니다. 업데이트 진단에는
--dry-run을 사용해 계획된 작업을 미리 보거나, --json으로 구조화된 결과를 보거나,
openclaw update status --json으로 채널 및 사용 가능 상태를 확인하세요.
설치 프로그램에는 자체 --verbose 플래그가 있지만, 그 플래그는
openclaw update의 일부가 아닙니다.
--channel beta는 beta를 선호하지만, beta 태그가 없거나 최신 stable 릴리스보다 오래된 경우
런타임은 stable/latest로 폴백합니다. 일회성 패키지 업데이트에 원시 npm beta dist-tag를
원한다면 --tag beta를 사용하세요.
관리되는 Plugin의 경우 beta 채널 폴백은 경고입니다. Plugin beta가 없기 때문에 Plugin이
기록된 default/latest 릴리스를 사용하더라도 코어 업데이트는
여전히 성공할 수 있습니다.
채널 의미는 개발 채널을 참조하세요.
npm 설치와 git 설치 간 전환
설치 유형을 변경하려면 채널을 사용하세요. 업데이터는~/.openclaw의 상태, 구성, 자격 증명, 작업공간을 유지합니다. CLI와 Gateway가 사용하는
OpenClaw 코드 설치만 변경합니다.
--dry-run으로 실행하세요.
dev 채널은 git 체크아웃을 보장하고, 이를 빌드한 뒤 해당 체크아웃에서 전역 CLI를
설치합니다. stable 및 beta 채널은 패키지 설치를 사용합니다. Gateway가 이미 설치되어 있으면
openclaw update는 서비스 메타데이터를 새로 고치고, --no-restart를 전달하지 않는 한
다시 시작합니다.
대안: 설치 프로그램 다시 실행
--no-onboard를 추가하세요. 설치 프로그램을 통해 특정 설치 유형을 강제하려면
--install-method git --no-onboard 또는
--install-method npm --no-onboard를 전달하세요.
npm 패키지 설치 단계 이후 openclaw update가 실패하면
설치 프로그램을 다시 실행하세요. 설치 프로그램은 이전 업데이터를 호출하지 않고, 전역
패키지 설치를 직접 실행하므로 부분적으로 업데이트된 npm 설치를 복구할 수 있습니다.
--version을 추가하세요.
대안: 수동 npm, pnpm 또는 bun
openclaw update를 선호하세요. 실행 중인 Gateway 서비스와
패키지 교체를 조율할 수 있기 때문입니다. 관리형 Gateway가 실행 중일 때
수동으로 업데이트하는 경우, 패키지 관리자가 완료된 직후 Gateway를 다시 시작하여
이전 프로세스가 교체된 패키지 파일에서 계속 서비스하지 않도록 하세요.
openclaw update가 전역 npm 설치를 관리할 때는 먼저 대상을
임시 npm 접두사에 설치하고, 패키징된 dist 인벤토리를 검증한 다음,
깨끗한 패키지 트리를 실제 전역 접두사로 교체합니다. 이렇게 하면 npm이
이전 패키지의 오래된 파일 위에 새 패키지를 덮어쓰는 것을 피할 수 있습니다. 설치 명령이 실패하면
OpenClaw는 --omit=optional로 한 번 재시도합니다. 이 재시도는 네이티브
선택적 의존성을 컴파일할 수 없는 호스트에 도움이 되며, 폴백도 실패할 경우 원래 실패가 계속
보이도록 유지합니다.
고급 npm 설치 주제
읽기 전용 패키지 트리
읽기 전용 패키지 트리
OpenClaw는 전역 패키지 디렉터리가 현재 사용자가 쓸 수 있는 경우에도, 런타임에서 패키징된 전역 설치를 읽기 전용으로 취급합니다. Plugin 패키지 설치는 사용자 구성 디렉터리 아래의 OpenClaw 소유 npm/git 루트에 위치하며, Gateway 시작은 OpenClaw 패키지 트리를 변경하지 않습니다.일부 Linux npm 설정은
/usr/lib/node_modules/openclaw 같은 root 소유 디렉터리 아래에 전역 패키지를 설치합니다. OpenClaw는 Plugin 설치/업데이트 명령이 해당 전역 패키지 디렉터리 바깥에 쓰기 때문에 이 레이아웃을 지원합니다.강화된 systemd 유닛
강화된 systemd 유닛
명시적 Plugin 설치, Plugin 업데이트, doctor 정리가 변경 사항을 유지할 수 있도록 OpenClaw에 구성/상태 루트에 대한 쓰기 권한을 부여하세요.
디스크 공간 사전 점검
디스크 공간 사전 점검
패키지 업데이트와 명시적 Plugin 설치 전에 OpenClaw는 대상 볼륨에 대해 최선형 디스크 공간 검사를 시도합니다. 공간이 부족하면 확인한 경로와 함께 경고가 표시되지만, 파일시스템 할당량, 스냅샷, 네트워크 볼륨은 확인 후에도 변경될 수 있으므로 업데이트를 차단하지는 않습니다. 실제 패키지 관리자 설치와 설치 후 검증이 계속 권위 있는 기준입니다.
자동 업데이터
자동 업데이터는 기본적으로 꺼져 있습니다.~/.openclaw/openclaw.json에서 활성화하세요.
| 채널 | 동작 |
|---|---|
stable | stableDelayHours 동안 기다린 다음, stableJitterHours 전반에 결정적 지터를 적용해 실행합니다(분산 롤아웃). |
beta | betaCheckIntervalHours마다 확인하고(기본값: 매시간) 즉시 적용합니다. |
dev | 자동 적용 없음. openclaw update를 수동으로 사용하세요. |
update.checkOnStart: false로 비활성화).
다운그레이드 또는 사고 복구의 경우, update.auto.enabled가 구성되어 있더라도 자동 적용을 차단하려면 Gateway 환경에 OPENCLAW_NO_AUTO_UPDATE=1을 설정하세요. update.checkOnStart도 비활성화하지 않으면 시작 업데이트 힌트는 계속 실행될 수 있습니다.
실시간 Gateway 제어 플레인 핸들러를 통해 요청된 패키지 관리자 업데이트는
패키지 교체 후 지연 없는, 쿨다운 없는 업데이트 재시작을 강제합니다. 이렇게 하면
이미 교체된 패키지 트리에서 청크를 지연 로드할 만큼 오래 이전 인메모리 프로세스가 남는 것을
피할 수 있습니다. 셸 openclaw update는 업데이트 전후로 서비스를 중지하고
다시 시작할 수 있으므로 관리형 설치에 여전히 권장되는 경로입니다.
업데이트 후
구성을 마이그레이션하고, DM 정책을 감사하며, Gateway 상태를 확인합니다. 자세한 내용: Doctor
롤백
버전 고정(npm)
커밋 고정(소스)
git checkout main && git pull.
막힌 경우
openclaw doctor를 다시 실행하고 출력을 주의 깊게 읽으세요.- 소스 체크아웃에서
openclaw update --channel dev를 실행할 때, 업데이터는 필요하면pnpm을 자동으로 부트스트랩합니다. pnpm/corepack 부트스트랩 오류가 보이면pnpm을 수동으로 설치하거나(corepack을 다시 활성화) 업데이트를 다시 실행하세요. - 확인: 문제 해결
- Discord에서 질문: https://discord.gg/clawd