OpenClaw v2026.4.5(약 2026-04-06 공개)는 운영자에게 중요한 마일스톤입니다. 다수의 레거시 공개 설정 별칭을 제거하거나 정식 경로와 명시적인 enabled 의미로 이전하고, 플러그인 전용 도구 허용 목록, /allowlist 변경의 소유자 전용 제한, before_tool_call 훅 충돌 시 fail-closed, 특정 브라우저 SSRF 리다이렉트 클래스의 조기 차단 등 보안 강화를 여럿 포함하며, doctor는 정규화된 talk 설정을 깨지기 쉬운 직렬화가 아닌 구조로 비교해 불필요한 “수정” 소음을 줄입니다. 임대·코로케이션 Mac에서 Gateway를 돌릴 때 실패는 “npm 다운로드 실패”보다 “설정에 몇 마이너 전부터 조용히 먹통인 키가 남아 있다”인 경우가 많습니다. 이 글은 숙련 사용자와 온콜 엔지니어에게 반복 가능한 순서를 제시합니다: 백업 → 패키지 또는 이미지 버전 올리기 → openclaw doctor → openclaw doctor --fix → Gateway 기동 → VNC 데스크톱에서 제어 UI 검증. 이전 마이그레이션 글을 보완하며 v2026.4.5 Breaking·보안 노트에 초점을 두고, 같은 사이트의 Docker, launchd, SecretRef, 브라우저 MCP, 무응답 진단 글로 연결합니다.
1) 고통 포인트: 원격 업그레이드와 조용한 설정 드리프트
- 튜토리얼 반감기: 이슈·Discord·블로그에서 온 스니펫은 특정 마이너에 묶입니다. 파싱은 되어도 스키마 강화 이후 런타임에는 영향이 없을 수 있습니다.
- 늦은 검증: Gateway는 기동 검증에서만 터질 수 있고, launchd에서는 로그를 안 보면 재시작 폭풍처럼 보입니다.
- 툴체인 분열: Homebrew Node, nvm 심볼릭 링크, 전역 npm prefix가 어떤
openclaw바이너리가 도는지 엇갈립니다. v2026.4.5는 “prefix를 소유한 npm”을 명시적으로 중시합니다. - SSH만으로는 GUI 공백: OAuth, 동의 화면, 로컬 브라우저 핸드오프는 데스크톱이 필요합니다. VNC가 터미널과 브라우저를 한 화면으로 묶습니다.
- 컨테이너 괴리: 이미지 태그만 올리고 설정 볼륨이 Breaking 이전 형태면 호스트와 컨테이너의 doctor 결과가 서로 모순될 수 있습니다.
- 더 엄격한 보안 기본값: “느슨해서 돌아가던” 흐름이 이제 fail-closed 될 수 있습니다. 기대되는 동작이며, 맹목적으로 안전장치를 끄기보다 정책을 맞춰 고치는 편이 맞습니다.
2) 결정표: npm vs Docker vs launchd vs 다중 워크스페이스
| 토폴로지 | 업그레이드 위치 | 주요 리스크 | 2026 관행 |
|---|---|---|---|
| 전역 npm / 인스톨러 | 호스트 셸 | prefix 불일치 | which openclaw + openclaw --version으로 확인 후 doctor |
| Docker Compose | 이미지 다이제스트 + 볼륨 | 분열된 CLI | 문서화된 컨텍스트에서 doctor 실행; 스택 재기동 |
| launchd | Plist 환경 + WorkingDirectory | nvm 없는 PATH | 절대 바이너리 경로 또는 단일 툴체인; 수정 후 bootout/bootstrap |
| 다중 워크스페이스 | 여러 JSON 루트 | 한 트리만 고침 | 경로 스프레드시트 유지; 다중 프로젝트 격리 글과 짝지음 |
3) v2026.4.5의 Breaking·보안 표면
Breaking: 정식화
이 릴리스는 talk.voiceId/talk.apiKey, agents.*.sandbox.perSession, browser.ssrfPolicy.allowPrivateNetwork, hooks.internal.handlers 같은 레거시 별칭을 제거하거나 이전하고, 채널·그룹·룸 allow 토글을 enabled가 있는 정식 위치로 옮기며, 로드 시 호환과 openclaw doctor --fix 마이그레이션을 유지합니다. 중첩 JSON을 손으로 고치기보다 자동 마이그레이션을 우선하세요.
보안과 플러그인
플러그인 도구 허용 목록, 권한 있는 allowlist 명령, 훅 실패, 브라우저 SSRF 방어 주변의 집행이 더 엄격해집니다. 업그레이드 후 최소 플러그인 매트릭스를 돌리세요: 안전한 도구 호출 하나, 채널 메시지 하나, 거부 경로 하나로 정책이 의도대로인지 확인합니다.
Doctor와 프로바이더
노트에는 오래된 anthropic:claude-cli 프로필 정리와 talk 정규화 비교 개선도 포함됩니다. 예전에 실제 diff 없이 끝없이 “talk.provider 수정”만 보이던 경우에 유용합니다.
백업 스니펫
cp ~/.openclaw/openclaw.json ~/backups/openclaw-$(date +%Y%m%d).json tar czf ~/backups/openclaw-workspace-$(date +%Y%m%d).tar.gz ~/.openclaw/workspace 2>/dev/null || true
4) 백업부터 검증까지 7단계 실행
범위 고정과 백업
설정, 시크릿 전략, 워크스페이스; Node와 OpenClaw 버전을 기록합니다.
한 채널로 v2026.4.5로 업그레이드
전역 npm, 인스톨러 스크립트, 또는 Docker 태그—섞지 마세요.
openclaw doctor 실행(아직 fix 없음)
전체 출력을 티켓 시스템에 남깁니다.
openclaw doctor --fix 적용
Breaking 항목이 비울 때까지 doctor를 다시 실행; SecretRef를 쓰면 흐름을 맞춥니다.
Gateway 기동과 로그 확인
리스너, 프로바이더, 플러그인 확인; 컨테이너면 18789 포트 매핑을 맞춥니다.
VNC에서 제어 UI 검증
브라우저 동의나 OAuth 루프를 마칩니다; 증상이 남으면 브라우저 MCP·무응답 가이드와 대조합니다.
스모크 테스트와 롤백 계획
최소 채팅 + 도구 호출을 실행; 깨지면 백업 tarball을 복원하고 diff를 기록합니다.
5) 참고 사실과 명령
doctor를 신뢰하세요.- doctor 전·후 출력 저장
- 모든 워크스페이스 디렉터리 마이그레이션 완료
- 도구 스모크 테스트 통과
- 롤백 tarball 복원 테스트 완료
6) FAQ, 관련 글, 마무리
Q: doctor를 건너뛰고 JSON만 손으로? 가능하지만 중첩 스키마에서는 오류가 잦습니다.
Q: 업그레이드 후 채널이 조용해졌나요? launchd의 환경 상속을 확인한 뒤 무응답·네트워크 글을 보세요.
관련: 자주 나는 오류 10가지 해결, launchd 체크리스트, 공식 Docker Compose 가이드, SecretRef 감사, 브라우저 MCP, 무응답 진단.
마무리: 업그레이드는 설정 증거 사슬을 다시 짓는 일
공유 원격 Mac에서는 부분 마이그레이션이 그 Gateway에 의존하는 모든 사람을 막습니다. VNC로 CLI 출력, 브라우저 검증, 파일 편집을 한 세션에 맞추세요. 짧은 주기에 하드웨어를 사지 않고 macOS 용량이 필요하면 VNCMac과 이 체크리스트 라이브러리가 임시 머신 빌리기보다 보통 빠릅니다.