macOS에서 OpenClaw를 처음 깔 때 막히는 지점은 네 가지입니다: 로컬과 원격 게이트웨이 선택, launchd 데몬 여부, TCC(Transparency, Consent, Control) 승인, 그리고 데스크톱 앱과 전역 CLI의 semver 일치입니다. 이 글은 2026년 기준으로 openclaw onboard, --install-daemon, ai.openclaw.gateway plist 동작을 정리하고, SSH/VNC로 접속하는 렌탈 Mac mini에서도 그래픽으로 TCC를 끝내는 방법을 다룹니다. 설정 파일은 openclaw.json과 .env 글을 이어서 읽으세요.
전제: Node 22/24와 CLI
문서는 Node.js 22 LTS(22.16+) 또는 Node 24를 전제로 합니다. Homebrew나 nvm으로 설치한 뒤 팀이 같은 릴리스 라인을 씁니다.
npm install -g openclaw@latest프리뷰 앱과 오래된 전역 패키지 조합은 핸드셰이크에서 바로 실패합니다. 공유 머신에서는 which openclaw로 경로를 확인하세요.
로컬·원격 결정표
| 모드 | 적합 | 트레이드오프 |
|---|---|---|
| 로컬 | 개인 개발, 브라우저 자동화, 낮은 지연 | 해당 Mac에 데몬+TCC |
| 원격 | 중앙 운영, 공유 시크릿 금고 | 네트워크·인증 증가 |
| 나중에 | 하드웨어 평가 중 | 게이트웨이 없으면 에이전트 불안정 |
프런트엔드 팀은 WebKit 자동화와 파일 도구를 한 OS에 두려고 클라우드 Mac mini에서 로컬을 고릅니다. 플랫폼 팀은 노트북을 원격으로 돌리고 외주에 SSH 포워딩을 줍니다——URL·allowedOrigins·TLS 종료를 런북에 적으세요.
마법사와 공급자 인증
openclaw onboard로 게이트웨이 위치를 고르고 모델 API 키나 OAuth를 넣으며 기본 tools.profile(예: coding)으로 파일·셸 도구를 켭니다. 가이드 채팅은 문서 대용이지만 Slack·메일에 키를 붙이지 마세요——컴플라이언스에서 반드시 묻습니다. 끝난 뒤 업그레이드 체크리스트와 환경 변수를 대조해 업그레이드 시 고아 토큰이 없게 하세요.
머지 전 15분 스모크를 권장: 안전한 도구 호출, 프로젝트 디렉터리 읽기, 의도적 잘못된 경로로 오류 포맷 확인. allowedPaths 오설정은 주말 장애로 드러나기 쉽습니다. doctor 텍스트 출력을 위키에 남기고, 이전 npm list -g openclaw 버전과 ~/.openclaw tarball을 롤백 메모에 두면 빠른 회선에서 약 3분 안에 되돌릴 수 있습니다.
LaunchAgent와 포트
openclaw onboard --install-daemon은 ~/Library/LaunchAgents/ai.openclaw.gateway.plist를 쓰고 StandardOut/Err를 지정합니다. 바쁜 호스트는 로그를 월 단위로 로테이션하세요. 포트가 이미 잡혀 있으면 UI는 성공처럼 보여도 헬스가 빨강——로그의 EADDRINUSE를 doctor와 함께 확인합니다.
앱만 종료해서는 데몬이 멈추지 않습니다. 콜드 스타트는 문서의 unload나 launchctl bootout gui/$UID/ai.openclaw.gateway가 필요합니다. OS 메이저 업데이트 후 TCC가 옛 바이너리 경로를 잃으면 재승인이 필요할 수 있습니다.
자동화를 막는 TCC
손쉬운 사용성, 자동화(AppleEvents), 알림, 경우에 따라 화면 녹화까지 요구됩니다. 신뢰하는 머신에서만 허용하고, 공유 클라우드 Mac은 사용자별 계정으로 권한 철회를 단순화하세요. SSH만으로는 모달이 안 뜰 수 있으니 첫 승인은 VNC로 그래픽 클릭을 하세요. 엔터프라이즈는 구성 프로파일로 선승인할 수 있으나 렌탈은 수동이 많습니다——변경 티켓에 승인자·날짜를 남기세요.
버전과 doctor
openclaw --version이 앱 호환 표시와 같은 마이너 계열인지.openclaw doctor가 채널·경로·선택 브라우저 드라이버에서 초록인지.~/.openclaw/openclaw.json리스닝 포트가 리버스 프록시와 맞는지——외부 공개 전 프록시·터널 하드닝을 읽으세요.
모델 API 401이면 JSON이 아니라 .env에서 키를 교체하고 화면 공유에 비밀이 비치지 않게 하세요. 복잡한 연결은 doctor와 게이트웨이 진단과 병행하세요.
전용 클라우드 Mac 이유
노트북 한 대로 시작하면 누군가 집에 가져가는 순간 게이트웨이가 사라집니다. 데이터센터 Mac mini는 전원이 안정되고 고정 egress 옵션이 있으며 Apple Silicon은 저소음 상시 구동에 적합합니다. MacHTML 물리 렌탈은 SSH/VNC 포함——TCC·데몬을 마친 뒤에도 에디터는 로컬에 두면 됩니다. 프로젝트 끝나면 인스턴스를 줄이고 중고 하드 팔 필요가 없습니다.
가상화 macOS보다 syscall·타이머 엣지가 적어 launchd 운용과 잘 맞습니다. 짧은 빌드 버스트에도 전력 대 성능이 좋습니다.
엔터프라이즈에서는 변경 관리에 doctor 출력과 plist 경로, 사용 중인 Node 메이저 버전을 함께 첨부하면 감사 대응이 빨라집니다. 분기마다 게이트웨이 포트와 방화벽 규칙을 한 번씩 교차 검증해 두면 장애 시 추측 대신 로그로 바로 들어갈 수 있습니다.
FAQ
앱이 게이트웨이 버전 불일치를 표시하는 이유는?
앱이 실행 중 게이트웨이와 기대 버전을 대조합니다. 전역 CLI를 맞추고 launchd를 재시작한 뒤 doctor를 다시 실행하세요.
앱을 종료하면 게이트웨이도 멈추나요?
데몬 모드에서는 launchd가 유지합니다. 의도적 콜드 스타트는 launchctl bootout 등이 필요합니다.
API 키는 어디에?
~/.openclaw/.env에 엄격한 chmod, 저장소에 커밋 금지. 프로필 분리는 별도 글 참고.
정리하면 신뢰할 수 있는 온보딩은 올바른 Node, 명시적 데몬 설치, 그래픽 TCC, 버전 고정 CLI입니다. Apple Silicon Mac mini에서 한 번 통과하면 macOS를 인프라처럼 다루고 SSH로 doctor 중심 진단을 반복할 수 있습니다. MacHTML은 베어메탈 클라우드 Mac에 집중해 수요에 맞춰 프로비저닝과 해제를 반복할 수 있게 합니다.