2026 클라우드 Mac에서 OpenClaw 환경 변수와 launchd: 우선순위, 비밀, 안전한 롤아웃
임대한 Apple Silicon 호스트에서 macOS launchd 아래 OpenClaw 게이트웨이를 돌리면 오래된 불일치가 남습니다. SSH 세션에서는 .zshrc에서보낸 변수가 풍부해 보이지만, 재부팅 뒤 실제로 게이트웨이를 띄우는 LaunchAgent는 거의 빈 환경에서 시작합니다. 2026년에도 우선순위를 문서화하지 않은 팀은「SSH에선 되는데 부팅 직후 실패」에 시간을 허비합니다. 분기마다 API 키를 바꿀 때 .env만 고치고 plist를 잊는 경우도 흔합니다. 이 글에서는 계층이 왜 필요한지, 5행 우선순위 표, 체크포인트가 있는 9단계 롤아웃, OPENCLAW_STATE_DIR 이동과 위험한 셸 일괄 임포트 비교, 불필요한 게이트웨이 재시작 없이 키를 바꾸는 방법, FAQ, 홍콩·일본·한국·싱가포르·미국 등 MacLogin 리전과의 정렬을 정리합니다.
운영 맥락은 OpenClaw 내장 cron과 launchd, CLI 훅과 컴플라이언스 감사, SSH keepalive·세션 끊김과 함께 읽으면 네트워크 끊김을 환경 문제로 오인하기 어렵습니다. 클라우드 Mac에서는 게이트웨이와 cron형 워커가 같은 plist 템플릿을 쓰는 경우가 많고, cron 글의 시간대·로그 전략은「WorkingDirectory에서 .env가 보이는가」판단에 직결됩니다. 훅 글은 키 교체 후 실패율을 감사 로그와 연결합니다. SSH가 안정돼야 printenv 비교와 수동 복구가 신뢰됩니다. 변경 창에는 plist 체크섬, doctor 출력, 성공한 cron 한 번의 스크린샷을 남겨 교대 시 인수인계를 쉽게 하세요.
OpenClaw 게이트웨이에 환경 계층이 필요한 이유
OpenClaw는 Node 프로세스 환경을 물려받은 뒤 빌드에 따라 워크스페이스 파일과 dotenv류 로더를 합칩니다. 클라우드 Mac에는 세 주체가 공존합니다. 대화형 셸의 운영자, launchd가 관리하는 상주 데몬, SSH로 배포하는 CI입니다. ANTHROPIC_API_KEY를 읽는 경로가 하나뿐이면 유지보수 후 재부팅 때 자동화가 들쭉날쭉해집니다. 부울 플래그, 모델 엔드포인트, 파일 시스템 루트, 베어러 토큰을 표 없이 한 파일에 우겨 넣지 마세요.
- 재현성: 감사에서「프로덕션 정의 파일은 무엇인가」를 묻습니다. 버전 관리된 JSON과 plist가 임시 export보다 낫습니다. 티켓에는 데몬만 영향인지 SSH 세션도 영향인지 적으세요.
- 최소 권한: 읽기 전용 설정과 비밀을 분리하고
.env는 chmod600입니다. - 멀티테넌트: 무관한 고객이 같은
~/.openclaw트리를 쓰면 안 됩니다. 사용자 분리나 상태 디렉터리 재배치가 필요합니다.
우선순위 표: 변수를 어디에 둘까
| 계층 | 적합한 용도 | launchd에서 주의 | 예시 키 |
|---|---|---|---|
LaunchAgent plist EnvironmentVariables |
부팅 필수 경로, PATH 수정 |
수정 후 launchctl unload/load 필요 |
NODE_OPTIONS, 사용자 정의 루트 |
openclaw.json(워크스페이스·사용자) |
비밀이 아닌 기본값, 기능 토글 | 프로세스 시작 뒤 해석—권한 확인 | 모델 라우팅, 도구 허용 목록 |
저장소 .env |
git에 없는 비밀 | WorkingDirectory 정확히 |
클라우드 공급자 API 키 |
| 셸 래퍼 스크립트 | 복잡한 source(드묾) | 감사 어려움; argv 로깅 주의 | 레거시 기업 CA 번들 |
| 대화형 전용 export | 개발자 노트북 | 게이트웨이는 이 경로에절대 의존하지 말 것 | 별칭 |
launchctl print gui/$(id -u)/com.example.openclaw(레이블 치환)로 환경이 반영됐는지 확인한 다음 게이트웨이 동작을 신뢰하세요.
9단계 launchd 환경 롤아웃
- 기준선: 동작하는 SSH에서
env | sort를 티켓에 붙이고 필수 항목에 표시합니다. - 분류: 각 키를 비밀·경로·플래그로 나누고 plist와 JSON에서중복 없음을 목표로 합니다.
- PATH 고정: Homebrew나 nvm 경로가 콘솔과 데몬에서 다르면 plist에 최소 PATH를 명시합니다.
- WorkingDirectory:
.env가 있는 저장소 루트를 가리킵니다. 어긋나면 비밀이 조용히 빠집니다. - ProgramArguments: 해당 호스트의
which node절대 경로로node를 호출합니다. - unload/load 테스트: 두 번 사이클합니다. 두 번째에서 오래된 소켓이 남을 수 있습니다.
- 헬스 체크:
openclaw doctor등을 실행하고 stdout을 변경 기록에 첨부합니다. - 재부팅 훈련: 월간으로 프로덕션에 가까운 호스트에서 계획 재부팅을 하고 게이트웨이가90초 안에 돌아오는지 봅니다.
- 문서: plist 경로와 체크섬을 내부 위키에. 외주를 위해 MacLogin 도움말 SSH 기초로 링크해 별도 시작 스크립트 난립을 막습니다.
OPENCLAW_STATE_DIR와 셸 임포트 트레이드오프
OPENCLAW_STATE_DIR로 상태를 옮기면 빠른 NVMe는 빌드에 두고 에이전트 저널은 다른 볼륨에 두며 백업 보존만 바꾸는 MacLogin 플랜에 잘 맞습니다. 변수는 plist에 두어 launchd와 CLI를 맞춥니다. 반면 ProgramArguments를 /bin/zsh -lc 'source ~/.profile && exec node ...'로 감싸면 대화형 dotfile이 섞입니다. 데모엔 편하지만 개발자 로컬 수정이 프로덕션을 깨는 컴플라이언스 리스크가 있습니다. 셸 source는 샌드박스로만 제한하세요.
비밀 로테이션과 뜻밖의 게이트웨이 재시작
키를 바꿀 때마다 게이트웨이 전체를 내리는 팀이 많지만, 요청마다 파일 워처나 외부 저장소에서 읽으면 중단을 줄일 수 있습니다. 최소한 새 .env를 임시 파일에서 mv로 원자적으로 쓰고, 문서화된 SIGUSR나 리로드 훅이 있으면 쓰며, 이전 키를 폐기하기 전 15분 오류율을 봅니다. 훅 글의 로그와 결합하면 보안이 키 나이와 실패 스파이크를 상관할 수 있습니다.
2026 환경 FAQ
Docker Desktop은 무엇이 달라지나요? 게이트웨이를 컨테이너화하면 docker run 시 환경을 주입하고 launchd는 감독 프로세스만 관리합니다. 다이어그램을 갱신하세요.
여러 Node 버전은? 절대 경로나 커밋된 버전 관리자 설정을 씁니다. 지난주 brew link에 의존하지 마세요.
1Password CLI는? 가능하지만 LaunchAgent는 네트워크 준비와 기기 승인을 기다려야 합니다. 도쿄 헤드리스 Mac mini는 노트북과 생체 인식 동작이 다릅니다.
Mac mini M4가 엄격한 환경 규율을 단순화하는 이유
M4 통합 메모리는 Node, 워처, 선택적 로컬 모델을 cron 글의 게이트웨이·워커용 여러 LaunchAgent를 병렬로 돌려도 쾌적하게 유지합니다. MacLogin 5리전은 plist 템플릿을 복제하고 지연에 민감한 엔드포인트만 바꾸기 좋습니다. 가격 페이지에서 용량을 빌리고 위 표를 적용하며 환경 드리프트를 개인 미스터리가 아니라 사고 유형으로 다루세요.
