이미 OpenClaw 구버전을 쓰고 있는데 2026.3.x로 업그레이드하려다 설정 호환이 걱정되시나요? 2026.3.x는 기본 설정 로직(tools.profile, ACP dispatch 등)이 바뀌어 예전 튜토리얼이 통하지 않을 수 있습니다. 이 글에서는 왜 이전이 필요한지, 업그레이드 전 필수 백업·확인, 5단계 이전(설치/업그레이드 → onboard 마법사 → API·권한 → 데몬 → 검증), 그리고 권한 롤백·포트 충돌·환경변수 등 VNC 원격 Mac에서 자주 걸리는 함정과 FAQ를 정리해 한 번에 통과할 수 있게 했습니다.
① 2026.3.x에서 왜 이전이 필요한가? 예전 튜토리얼과 주요 변경 사항
2026.3.x는 보안과 기본 동작을 더 엄격하게 했습니다. 새로 설치하면 tools.profile이 기본값 messaging(메시지/세션 도구만)이 되어, 파일 읽기·쓰기나 터미널 실행에 의존하면 업그레이드 후 “권한 없음”이 뜹니다. ACP dispatch는 기본 켜져 있어 멀티 에이전트 라우팅이 바뀔 수 있고, 플러그인 HTTP 등록 방식도 바뀌었습니다. 그래서 예전 설정을 그대로 쓰거나 예전 튜토리얼을 복사하면 업그레이드 후 동작하지 않기 쉽습니다.
| 변경 항목 | 구버전에서 흔한 상태 | 2026.3.x 기본/권장 |
|---|---|---|
| tools.profile | 미설정 또는 coding/full | 신규 설치 시 messaging; 읽기·쓰기·실행이 필요하면 coding 또는 full로 변경 |
| acp.dispatch | 대부분 미설정 | 기본 enabled; /acp만 쓰고 자동 라우팅이 필요 없으면 비활성화 가능 |
| 플러그인 HTTP 등록 | registerHttpHandler 등 | 등록 동작 변경; 플러그인 코드와 문서 확인 필요 |
② 업그레이드 전 필수: 백업·버전 확인·의존성 확인
업그레이드 전에 아래 세 가지를 해두면 실패나 설정 손실 후 복구가 수월합니다.
설정·워크스페이스 백업
~/.openclaw/openclaw.json과 ~/.openclaw/workspace/를 안전한 곳에 복사. 새 머신으로 옮길 때는 둘 다 복사한 뒤 openclaw doctor와 openclaw gateway restart 실행.
버전·의존성
Node 버전(20 이상 권장) 확인; openclaw doctor로 이전·수정 적용; openclaw config validate로 설정 문법 확인.
현재 tools·ACP 확인
openclaw config get tools로 현재 profile 확인; ACP를 쓰면 acp.dispatch.enabled가 원하는 값인지 확인.
③ 5단계 이전: 설치/업그레이드 → onboard 마법사 → API·권한 → 데몬 → 검증
단계 1: npm install -g openclaw@latest 또는 공식 설치 스크립트로 2026.3.x로 업그레이드.
단계 2: openclaw onboard로 설정 마법사에 들어가 사용 형태(개인/팀), 설치 유형(QuickStart 등), AI 모델·API(OpenAI/Claude/서드파티)를 선택.
단계 3: ~/.openclaw/openclaw.json에서 tools.profile을 coding(일반 파일·실행) 또는 full로 설정·확인; ACP 자동 라우팅을 끄려면 acp.dispatch.enabled: false 설정.
단계 4: daemon/LaunchAgent를 쓰면 openclaw onboard --install-daemon 실행 또는 문서대로 데몬 설정하고, plist/환경변수에 PATH와 API 관련 변수가 올바르게 들어가게 하기.
단계 5: openclaw gateway restart 후 openclaw health로 서비스 정상 확인; 원격 Mac에서는 VNC로 데스크톱에 접속해 한 번 돌려보고 미처리 권한 창이 없는지 확인하는 것을 권장.
④ 자주 걸리는 함정: 권한 롤백·포트 충돌·환경변수·VNC 원격 Mac
권한 롤백: 업그레이드 후 “읽기/쓰기/실행 권한 없음”이면 tools.profile이 messaging인 경우가 많음. coding 또는 full로 바꾸고 gateway 재시작.
포트 충돌: 포트 사용 중이면 lsof -i :포트번호로 프로세스 확인 후 종료하거나 설정에서 다른 포트로 변경.
환경변수: launchd·PM2로 기동할 때는 plist나 ecosystem에 PATH·API 관련 변수를 명시해야 함. 그렇지 않으면 대화형 터미널에서는 되고 백그라운드 서비스에서는 에러가 날 수 있음.
VNC 원격 Mac: 업그레이드와 최초 인증 시에는 반드시 VNC로 데스크톱에 접속해 시스템 권한·Keychain 창을 처리할 수 있게 하세요. 업그레이드 후에는 SSH로 자동화해도 됩니다. SSH만 있는 환경에서 업그레이드하면 창을 클릭할 수 없어 중간에 멈출 수 있습니다.
openclaw doctor 실행으로 이전·수정 적용을 권장; 새 머신으로 옮길 때 ~/.openclaw/와 ~/.openclaw/workspace/를 함께 복사하면 설정·채널 상태·자격증명을 유지할 수 있습니다.⑤ FAQ: 롤백·다중 인스턴스·사이트 내 배포/트러블슈팅 글 링크
롤백은 어떻게 하나요? openclaw.json·워크스페이스 백업이 있으면 복원한 뒤 구버전 npm 패키지를 설치하고 서비스를 재시작. 백업이 없으면 새 동작에 맞게 다시 설정해야 합니다.
다중 인스턴스 이전은? 인스턴스마다 설정 디렉터리가 따로 있음. 각각 백업하고 각각 업그레이드·검증하며, 포트와 profile을 구분해 설정.
사이트 내 관련 글: 설치 실패·실행 오류는 《OpenClaw 자주 나는 오류와 점검 가이드》 참고; 원격 Mac에서 인증 창 처리는 《OpenClaw VNC 승인·보안 격리》; 환경 선택은 《OpenClaw v2026.3.7 환경 선택》 참고.
마치며: 원격 Mac에서 OpenClaw 업그레이드할 때 VNC 환경을 추천하는 이유
2026.3.x 설정 이전에는 “최초 실행”과 시스템 권한·Keychain 창이 여러 번 나올 수 있는데, SSH만으로는 이 창들을 클릭할 수 없어 중간에 멈출 수 있습니다. VNC 원격 Mac이면 onboard 완료, 창 처리, openclaw health·로그 확인을 로컬처럼 할 수 있어 이전 경로가 명확하고 장애 대응도 빠릅니다. “업그레이드 후 안 뜨고, 권한이 안 맞는” 반복을 줄이려면 VNCMac 원격 Mac 노드에서 업그레이드·검증을 하고, 필요하면 SSH로 일상 자동화를 하는 구성이 더 안정적이고 시간도 절약됩니다.