2026년 macOS에서 OpenClaw 게이트웨이 첫 실행: PATH, Node 관리자, LaunchAgent 환경 블록, 클라우드 Mac mini 스모크

가장 짜증 나는 OpenClaw 장애는 튜토리얼이 내 터미널에서 성공한 이후에 옵니다. LaunchAgent가 깨어 나면 뼈만 남은 PATH만 들고 node를 찾지 못하고 게이트웨이는 조용히 재시작을 반복하다가 API 소비자에게는 502 연쇄로 보입니다. 2026년에는 macOS launchd를 zsh와 다른 OS로 보세요. 예쁜 .zprofile export도 nvm 셸 함수도 읽지 않습니다. 이 글은 툴체인 고정, plist에 환경 변수 박기, 재현 가능한 스모크, 그리고 본전 전에 Mac mini를 클라우드로 빌려 두드리는 이유를 한국어로 정리합니다.

심화는 openclaw doctor 게이트웨이 진단, JSON 환경 프로파일, 한 호스트를 여러 엔지니어가 쓸 때는 공유 클라우드 Mac mini 격리 체크리스트를 참고하세요.

launchd가 대화 가정을 깨는 이유

대화형 셸은 rc, direnv, 에디터 연동을 읽습니다. launchd 작업은 plist에 적힌 환경만 계약입니다. tmux 안의 which node가 /opt/homebrew/bin/node여도 동일 사용자 LaunchAgent 로그가 command not found인 것은 우연이 아니라 시작 그래프가 다르기 때문입니다.

HOME도 함정입니다. 클라우드 이미지 복제면 예상과 다른 홈이 붙어 OpenClaw 상태 디렉터리를 놓칩니다. plist에 명시하고 런북에 이미지 출처를 기록하세요. LANG과 LC_ALL도 로그 파싱에 영향을 주므로 대화 세션과 맞추거나 의도적으로 고정하세요.

Homebrew Node, nvm, 고정 tarball

Homebrew는 Apple Silicon에서 /opt/homebrew에 안정 경로를 제공해 ProgramArguments가 직접 가리키기 좋습니다. nvm은 사람에게 편하지만 데몬에겐 취약합니다. 꼭 nvm이면 고정 버전을 export하는 래퍼를 두고 plist는 래퍼를 호출하세요. 로그인 셸 없이 source nvm.sh && nvm use를 직접 쓰지 마세요.

규제 산업에서는 Node 배포 tarball을 체크섬과 함께 /usr/local/node-20.11.1처럼 풀고 plist가 그 바이너리를 가리키게 합니다. 분기마다 30분 재고정과 스모크를 일정에 넣지 않으면 보안 패치가 조용히 드리프트를 만듭니다. Intel Mac에서 복사한 plist를 Apple Silicon에 가져오면 전역 npm 경로가 달라 즉시 실패합니다. README에 아키텍처별 절대 경로 표를 두세요.

LaunchEnvironmentVariables와 WorkingDirectory

WorkingDirectory는 openclaw.json이 있는 루트로 잡습니다. LaunchEnvironmentVariables에 PATH, 허용된 NODE_OPTIONS, 클라우드 SDK 경로를 열거하세요. 키는 12개 미만을 목표로 감사 가능한 밀도를 유지합니다. 표준 출력·표준 오류는 로테이션 파일로. Console.app만 믿으면 야간 grep이 느려집니다. 50MB·5세대는 출발점으로 무난합니다.

툴체인 선택 비교

방식	데몬 친화성	업그레이드 마찰	적합 상황
Homebrew Node	높음	중간	소규모 단일 게이트웨이
nvm 기본	낮음	사람에겐 낮음	노트북만
고정 tarball	매우 높음	높음	컴플라이언스 중시

5분 스모크 절차

1. launchctl print gui/$UID/com.yourorg.openclaw.gateway로 종료 사유 0 확인.
2. curl -fsS로 헬스를 10초 간격 두 번 호출해 TLS 지연 로드 확인.
3. 무해한 도구 호출로 자식 프로세스 PATH를 /usr/bin/true로 검증.
4. 로그를 한번 잘라 붙여 쓰기 권한 확인.
5. bootout 후 재기동해 30초 안에 같은 포트에 바인딩되는지 확인.

절차는 스크립트로 저장소에 올리세요. 사람은 네 번을 잊습니다.

PATH 드리프트를 잡는 doctor

openclaw doctor는 버전 어긋남과 빠진 바이너리를 드러냅니다. LaunchAgent 소유 계정으로 실행하고 필요하면 sudo -u로 비교하세요. TLS 경고가 나오면 먼저 키체인과 중간 인증서를 의심해 upstream 403으로 오인하지 마세요. 한국어 로그를 다룰 때 로케일 차이로 stderr가 깨져 PATH 문제로 오진하기 쉽습니다.

권한, umask, 격리 확장 속성

LaunchAgent의 umask는 대화형 셸에서 chmod할 때 가정한 값과 다를 수 있습니다. 소켓이나 pid를 공유 디렉터리에 두면 POSIX 그룹을 맞추고 ACL은 신중히. 격리 확장 속성이 남으면 실행 거절이 PATH 오류처럼 보입니다. 체크섬 확인 후 의도적으로 제거하세요.

업그레이드와 고아 plist

Node와 OpenClaw 릴리스를 동기화하고 스테이징에서 먼저 런타임을 올린 뒤 스모크한 다음 유지보수 창에 본전을 밀어 넣으세요. Git에 최소 두 세대 plist를 날짜와 함께 남기고 롤백 절차에 이전 ProgramArguments를 포함합니다. npm -g 경로는 아키텍처마다 달라 복붙 금지를 문화로 만드세요.

FAQ

터미널에서는 되는데 LaunchAgent에서 실패하는 이유는?

셸 시작 파일을 읽는 것은 터미널뿐입니다. PATH는 plist나 래퍼로 명시하세요.

plist에서 nvm use를 호출해도 되나요?

피합니다. 고정 바이너리나 고정 NODE_HOME 래퍼를 씁니다.

첫 스모크는?

5분 안정 트래픽과 재시작을 포함합니다.

TCC는?

카메라 등은 GUI 승인이 필요할 수 있습니다. VNC 있는 실기로 리허설하세요.

첫 실행 안정성은 하드웨어 모양 문제이기도 합니다. 본전 게이트웨이와 같은 Apple Silicon 동작, 같은 키체인, 같은 팬 곡선을 얻으려면 MacHTML 클라우드 Mac mini를 하루 약 16.9달러에 빌리는 것이 현실적입니다. SSH로 plist를 고치고 TCC 클릭이 필요하면 VNC로 개입한 뒤 검증이 끝나면 종료합니다. 잘못 설정된 LaunchAgent를 밤에 잠드는 개발 노트북에 두는 것보다 가용성이 훨씬 낫습니다.

오래 doctor와 합성 트래픽을 돌려도 Apple Silicon은 조용하고 Linux 컨테이너가 거짓말하는 파일 잠금과 TCC 의미를 밟을 수 있습니다. 실제 macOS에서 봤다는 증적이 필요하면 클라우드 실기가 가장 짧은 루트입니다.