루프백 또는 인증 프록시만

2026 OpenClaw 업그레이드 실무: 3.22 → v2026.3.24 (Mac 클라우드)

2026년 초 OpenClaw 3.22와 v2026.3.24는 OPENCLAW_* 환경 변수 정리, SecretRef fail-fast, 네이티브 PDF, 스트리밍 중심 채널, OpenAI 호환 /v1/models 등이 한꺼번에 따라옵니다. Mac 클라우드에서 launchd로 게이트웨이를 돌리는 팀을 위해 스냅샷 없는 업그레이드·접두사 방치·doctor 생략의 위험을 구조화하고, 표·단계·기술 메모·전환 단락을 제공합니다. 첫 배포 5단계, 하드닝, 트러블슈팅을 함께 보세요.

1. 세 가지 실패 패턴

튜토리얼 가정의 일회성 머신과 달리 본번은 Slack/Discord 브리지와 Docker/npm 배포와 엮입니다.

스냅샷 없음: 설정·plist·환경 파일을 묶지 않으면 이전 버전 부팅을 증명할 수 없고 롤백이 추측에 의존합니다. 공유 Mac 클라우드 계정에서는 더욱 그렇습니다.
접두사 드리프트: 3.22는 OPENCLAW_*를 전제로 하며 구형 ClawdBot/MoltBot 스타일 변수는 무시될 수 있습니다. launchd는 EnvironmentVariables에 적힌 것만 주입하며, 인증/타임아웃처럼 보이는 반쯤 깨진 상태가 됩니다.
SecretRef fail-fast: 비밀이 없으면 의도적으로 기동을 멈춥니다. PDF·채널은 프로바이더 설정이 필요하고 doctor를 건너뛰면 트래픽이 올 때까지 문제가 드러나지 않습니다.

공유 계정에서는 셸에서 각자 다른 export를 시도하는 동안 launchd는 오래된 키를 주입하는 이중 상태가 생깁니다. 업그레이드 전 launchctl print, plist 경로, 효과적 환경(값은 티켓에 비밀 대신 키 이름만)을 기록하세요. IM 브리지를 돌리면 같은 변경 창에서 로그 경로와 토큰 파일을 새 CLI 레이아웃에 맞춥니다.

2. 릴리스 차이 표

실제 키는 설치된 CLI와 업스트림 릴리스 노트로 확인하세요.

영역	3.22	v2026.3.24	운영
환경 변수	`OPENCLAW_*` 우선	알 수 없는 키 검증 강화	plist·CI 비밀 grep 후 reload 전 이전
Secret	SecretRef + fail-fast	호환 게이트웨이 경로와 정합	스테이징에서 의도적 실패로 차단 검증
PDF	바이트/페이지 상한	모델 라우팅	작은 PDF로 회귀
채널	Telegram 등 스트리밍 기본값	—	429/백오프, 로그 경로 정렬
OpenAI 호환	—	`/v1/models` 등	루프백 curl, 공개 인터넷 노출 금지

크로스 플랫폼은 멀티 OS 글을 참고하세요.

3. 절차

동일 서비스 사용자로 포그라운드에서 doctor·스모크가 통과할 때까지 launchd를 다시 로드하지 마세요.

스냅샷: 설정·plist·환경 tarball, openclaw --version, lockfile. Git이 없으면 plist·바이너리 SHA256.
중지: openclaw gateway stop, 18789 lsof, IM 사이드카 중지.
업그레이드: pnpm/npm 등 공식 경로. root/사용자 혼합 설치 금지.
마이그레이션: plist EnvironmentVariables와 프로파일을 OPENCLAW_*로.
doctor: ERROR 제거, WARN은 정책으로 판단.
스모크: 소형 PDF, SecretRef 부정 테스트 후 복구, 필요 시 /v1/models curl.
launchd: launchctl unload/load, 15분 로그. 이전 tarball로 즉시 롤백.

PDF는 설정 상한 내 2페이지 정도로 경과 시간·RSS를 업그레이드 전후 비교하세요. SecretRef는 스테이징에서 깨진 경로를 가리켜 비정상 종료를 확인한 뒤 올바른 참조로 되돌립니다.

curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  "http://127.0.0.1:18789/v1/models" | head -c 400

launchctl unload ~/Library/LaunchAgents/com.example.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/com.example.openclaw.gateway.plist
launchctl print gui/$(id -u)/com.example.openclaw.gateway | head -n 40

주의: 게이트웨이는 루프백 또는 인증 리버스 프록시만—하드닝 준수.

4. 기술 메모

Node 22+ 필수. OS·툴체인 업데이트로 nvm 기본 alias가 바뀔 수 있습니다. SecretRef fail-fast는 빈 자격으로 조용히 도는 것을 막기 위한 설계입니다. PDF 상한만 올리고 동시 세션 상한을 안 올리면 Mac 클라우드가 스왑으로 떨어질 수 있습니다. 클라이언트는 /v1/models를 캐시할 수 있어 업그레이드 후 모델 ID가 바뀌면 캐시를 비워야 합니다. launchd ThrottleInterval은 크래시 루프를 가릴 수 있으니 설정이 먹히지 않으면 launchctl print와 시스템 로그를 확인하세요.

5. 감사 가능한 운영으로

개발자 노트만 쓰거나 프로덕션과 볼륨 경로가 다른 일반 Linux Docker만으로는 재현 가능한 업그레이드를 만들기 어렵습니다. 노트는 절전되고 Docker Desktop은 네트워크가 다르며 bind mount는 드리프트합니다. 전용 Mac 클라우드 계정에서 plist를 버전 관리하고 doctor·스모크를 스크립트로 묶고 불변 스냅샷을 남기면 변경 티켓이 됩니다.

노트·범용 Linux만으로는 launchd 계약과 SecretRef 경로를 맞추기 어렵고 IM/PDF 회귀도 데스크톱 전원 프로파일에 휘둘립니다. VPSMAC M4 Mac 클라우드를 임대해 게이트웨이 전용 호스트로 두면 Apple 네이티브 경로·안정적 출구·개발 랩톱과의 분리를 동시에 얻고, 보안 검토에 어떤 바이너리·plist·환경이 언제 활성였는지 제시하기 쉽습니다.

6. FAQ

업그레이드 후 게이트웨이가 조용히 종료되나요?

launchd 상태·ThrottleInterval·doctor·18789 포트 충돌을 확인하세요.

구형 환경 변수를 유지할 수 있나요?

3.22 이후 비권장입니다. OPENCLAW_*로 이전하세요.

OpenAI 호환을 공개해야 하나요?

아니요. 루프백·SSH 터널·인증 프록시만 사용하세요.