설치 경로, 포트 충돌, 동일 사용자 런북
OpenClaw를 임대 Mac에 올릴 때 가장 흔한 착각은 “터미널만 열면 전부 끝”이라는 가정입니다. 실제 운영에서는 openclaw CLI가 스크립트와 헬스 체크의 첫 관문이고, Gateway가 로컬 웹소켓·도구 패널·브라우저 쪽 연동을 받으며, macOS 보조 앱은 메뉴 막대에서 재연결·클립보드·짧은 상태 표시를 맡는 삼각 구조가 됩니다. 본 글은 Windows 노트북만 있는 팀이 SSH 전용 클라우드 Mac과 VNC 임대 원격 Mac 중 어디에 무엇을 설치할지, 홈 경로와 LaunchAgent 위치가 어긋날 때 생기는유령 설정을 어떻게 없앨지, 그리고 포트 충돌을 줄이는 런북을 한 장으로 묶습니다. 배경으로 LaunchAgent·Gateway·플러그인 베타와 OAuth·fetch·타임아웃 글을 같이 열어두면 버전 경계가 덜 흐려집니다.
CLI는 배포 파이프라인과 서버 측 자동화가 읽을 수 있는 종료 코드와 표준 출력을 남깁니다. 장애 대응에서 가장 값진 것은 “사람이 주관적으로 본 화면”이 아니라 반복 가능한 명령 시퀀스입니다. 다만 키체인 동의나 시스템 설정 창은 CLI만으로 재현이 어렵고, 이때 Gateway가 제공하는 로컬 UI와 헬스 채널이 감사 추적에 실립니다. macOS 보조 앱은 편의를 넘어서지 말고 단말 표시·빠른 doctor 호출·연결 상태 같은 얇은 막으로 두세요. 세 층을 한 사용자 홈에 고정하지 않으면 SSH로 고친 설정 파일이 실제 데몬이 읽는 경로와 달라져 밤새 원인을 찾게 됩니다.
Windows를 일상 제어 노드로 쓰는 팀은 원격 Mac에만 바이너리를 두고 로컬는 뷰어만 두는 패턴이 흔합니다. 이 패턴은 비용은 낮지만 증거가 분산됩니다. 티켓에는 “누가 어떤 호스트에서 어떤 사용자로 Gateway를 띄웠는지”를 남기고, VNC 세션 ID와 SSH 세션의 whoami 출력을 짝으로 붙이세요. Windows에서 VNC로 Xcode·키체인 가이드는 입력기·해상도·클립보드 차이를 먼저 정리하는 데 도움이 됩니다.
CLI 책임: 버전 고정, doctor, 플러그인 목록, 구조화 로그 tail.
Gateway 책임: 로컬 포트 바인딩, 웹소켓 헬스, 도구 패널에서의 거부 UX.
보조 앱 책임: 재연결, 메뉴 막대 상태, 사용자에게 보이는 짧은 경고.
공통 불변식: LaunchAgent가 로드한 plist의 UserName과 Finder 창의 사용자가 같아야 합니다.
Windows 가정: 로컬 방화벽이 SSH 포워딩을 막지 않는지, 사내 SSL 검사가 localhost 예외를 허용하는지 별도 행으로 적습니다.
문서 링크: 아웃바운드 프록시가 섞이면 프록시·Gateway 체크리스트와 증거를 분리하세요.
벤더가 “SSH만으로 충분”이라고 마케팅하는 경우가 많지만 OpenClaw 운영자에게는 브라우저 로컬 스토리지, 게이트웨이 패널의 캐시, 드래그 앤 드롭 대상이 같은 사용자인지가 자주 쟁점이 됩니다. SSH 전용 호스트는 밤중 자동 빌드와 로그 수집에 이상적이고, VNC 임대는 키체인·화면 녹화·사람이 직접 눌러야 하는 동의 흐름에 이상적입니다. 비용이 아니라 증거 클래스를 기준으로 고르세요.
| 시나리오 | SSH 전용 | VNC 임대 | 메모 |
|---|---|---|---|
| 패키지 업그레이드·크론 | 권장 | 불필요 | 표준 출력만으로도 충분한 경우 많음 |
| Gateway UI 거부 메시지 캡처 | 누락 위험 | 권장 | 동일 사용자 데스크톱 |
| 키체인·서명 대화상자 | 불안정 | 권장 | 원격에서 실제 클릭 증적 |
| 대역폭 압축·터널 | 스크립트화 | 뷰어 품질 조정 | SSH 터널·압축 참고 |
| Fastlane·Match·SSH+VNC 병행 | CI 핵심 | GUI 검증 | SSH·VNC 매트릭스 런북 |
포트 표만 맞추고 사용자를 맞추지 않으면, 열린 포트는 있어도 증거는 닫혀 있습니다.
임대 Mac에서는 관리 계정과 임대 고객 계정이 분리되어 있거나, 같은 이름이라도 UID가 다른 이미지가 섞입니다. CLI 바이너리를 /opt/homebrew/bin에 두고 설정은 ~/.config/openclaw에 둘지, 공급자가 준 전용 프리픽스를 쓸지 먼저 문서화하세요. LaunchAgent plist는 ~/Library/LaunchAgents 아래에 두되, 로드 주체가 로그인한 GUI 세션인지, 공유 데몬인지에 따라 launchctl bootstrap 범위가 달라집니다. “한 번은 됐는데 재부팅 후 안 된다”는 대부분이 이 경계에서 옵니다.
Gateway는 문서에 적힌 기본 루프백 주소와 포트에 묶입니다. 로컬 개발자가 다른 도구를 같은 포트에 올려 두었거나, 이전 실험 프로세스가 좀비로 남아 있으면 바인드 실패가 CLI doctor에는 짧게 보이다가 UI에서는 “영원한 로딩”으로 보일 수 있습니다. 설치 런북에는 포트를 비우는 명령과 기대 프로세스 트리를 함께 적으세요. 플러그인을 쓰면 ClawHub·크론·채널 업그레이드 글의 semver 표와 맞춰 혼합 버전을 피합니다.
동결: openclaw --version, 임대 계약 ID, 현재 plist와 환경 변수 스냅샷을 티켓에 붙입니다.
사용자 단일화: VNC로 로그인한 사용자와 launchctl print gui/$(id -u) 범위를 맞춥니다.
경로 계약: 워크스페이스 루트와 SecretRef 스냅샷 cwd를 SecretRef 감사 기준으로 한 줄에 적습니다.
포트 스캔: 22 SSH, 5900대 VNC, Gateway 기본 포트가 문서와 일치하는지 확인하고 충돌 시 변경 이유를 남깁니다.
보조 앱: 메뉴 막대에서 보이는 “연결됨”이 실제 헬스 엔드포인트와 같은지 짧은 HTTP 확인으로 교차 검증합니다.
다중 프로젝트: API 키와 HOME 분리는 다중 프로젝트 격리 글과 함께 검토합니다.
openclaw --version openclaw doctor id -u printenv OPENCLAW_HOME || true lsof -nP -iTCP -sTCP:LISTEN | rg -n ':(22|5900|18789)\b' || true
명령 이름과 플래그는 설치된 버전의 도움말을 우선합니다. 소셜에 떠도는 오래된 한 줄 스니펫은 반드시 릴리스 노트와 대조하세요.
| 검증 | SSH 증거 | VNC 증거 | 합격 기준 |
|---|---|---|---|
| 동일 사용자 | whoami·uid | 시스템 설정 상단 사용자명 | 문자열 일치 |
| Gateway 헬스 | curl 로컬 루프백 | 패널 푸터 버전 | CLI semver와 동일 |
| 보조 앱 상태 | 해당 없음 | 메뉴 막대 스크린샷 | 헬스 JSON과 타임스탬프 근접 |
| 포트 충돌 | lsof 출력 | 동시에 뷰어 연결 유지 | 재현 2회 |
| OAuth·fetch | doctor 로그 | 브라우저 동의 창 | 타임아웃 글과 분리된 로그 |
그리드는 이미 VNC 뷰어와 터미널을 나란히 띄울 줄 아는 운영자를 전제로 합니다. 처음 임대 Mac을 쓰는 사람은 연결 가이드를 먼저 끝낸 뒤 이 표를 돌리면 창 관리와 보안 검증을 동시에 하느라 시간이 배로 듭니다.
조직이 Windows를 표준 데스크톱으로 두면 키보드 배열·클립보드 형식·이중 방화벽이 먼저 튀어나옵니다. 그럼에도 빌드와 서명의 “진실”은 macOS 쪽 동일 사용자 세션에 있어야 합니다. OpenClaw 입장에서 CLI는 자동화의 교차점이고 Gateway는 사람이 개입하는 교차점이며 보조 앱은 그 둘을 잇는 얇은 띠입니다. 이 삼분할을 문서 한 장에 그려 두지 않으면 온콜이 매번 다른 그림을 그립니다.
SSH 전용 클라우드 Mac은 밤새 도는 파이프라인에 강합니다. 파일 시스템 도구를 deny-by-default로 쓰는 팀이라면 허용 목록 JSON을 Git에 두고 SSH로만 배포하는 흐름이 자연스럽습니다. 그러나 “왜 Gateway 패널에서만 오류 문구가 다르게 보였는가” 같은 UI 캐시 이슈는 SSH 로그만으로는 설득력이 떨어집니다. 그때는 VNC 임대 Mac을 짧게 열어 같은 사용자로 화면을 녹화하고 티켓에 붙이세요. 비용은 시간제로 통제할 수 있고, 감사 대응 비용은 그보다 큽니다.
VNC 임대 경로를 택하면 설치 런북에 뷰어 해상도·색 깊이·지터 목표를 명시하세요. 저해상도로만 연결하다가 서명 대화상자 글자가 잘려 “클릭 불가”로 보고되는 사고가 있습니다. Windows VNC·키체인 글의 권장 클라이언트 설정을 그대로 복사해 팀 표준으로 만들면 재현성이 올라갑니다.
포트 충돌은 대개 “이전 실험”의 잔재입니다. 학습용으로 띄운 다른 웹 서버, 옛 Gateway 프로세스, 사내 보안 에이전트의 로컬 프록시가 같은 바인드를 탐낼 수 있습니다. 런북에는 충돌이 났을 때 어떤 프로세스 이름을 종료해도 안전한지, 반대로 절대 건드리면 안 되는 시스템 데몬은 무엇인지 구분해 적습니다. 임대 공급자가 이미 특정 포트를 예약했다면 그 표를 첫 페이지에 붙여 넣으세요.
LaunchAgent와 Gateway를 같이 다루는 변경은 베타 체크리스트의 순서를 존중하는 것이 안전합니다. 먼저 부팅 경로를 안정화하고 나서 플러그인을 얹으면, 실패 원인이 “플러그인 호환”인지 “데몬 자체”인지 나뉩니다. 반대 순서로 가면 로그가 섞여 롤백이 두 배로 걸립니다.
아웃바운드 프록시가 있는 사무실에서는 네트워크 실패와 로컬 거부를 혼동하기 쉽습니다. 아웃바운드 프록시·Gateway 글의 증거 패킷을 별도 첨부로 두고, 파일 도구의 PATH_DENIED와 분리하세요. 한 스프레드시트에 몰아넣으면 근본 원인 분석이 늦어집니다.
SecretRef와 워크스페이스 루트가 어긋나면 “파일은 읽혔는데 런타임 자격 증명은 실패” 같은 가짜 음성이 납니다. SecretRef 감사와 cwd를 한 티켓에 엮어 검토자가 한 번에 서명할 수 있게 하세요.
여러 모노레포를 한 Mac에서 돌리면 API 키와 HOME 분리가 흐트러집니다. 다중 프로젝트 격리를 배포 전 체크리스트에 넣고, 페어링 토큰이 프로젝트 간에 공유되지 않았는지 주기적으로 diff를 봅니다.
Fastlane·Match처럼 SSH는 필수이지만 키체인 UI가 개입하는 작업은 VNC가 사실상 표준입니다. SSH·VNC 매트릭스 런북의 행을 그대로 복사해 이번 변경이 어떤 행에 해당하는지 표시하면 리뷰가 빨라집니다.
OAuth 동의와 fetch 메타데이터 문제는 5.6 타임아웃 글과 타임라인을 맞춰 읽으세요. 네트워크 지연과 로컬 바인드 실패는 증상이 비슷하지만 수집해야 할 로그가 다릅니다.
클라우드 공급자가 “SSH만 제공”하는 플랜이라면 Gateway 로컬 UI 검증은 불가능할 수 있습니다. 그 경우 회사 정책으로 별도 VNC 임대 노드를 열거나, CI는 SSH로 두고 사람의 승인 단계만 VNC로 분리하는 하이브리드를 문서화하세요. 하이브리드를 선택했다면 데이터가 두 호스트 사이를 어떻게 이동하는지 DLP 관점에서 한 단락을 더 씁니다.
보조 앱은 편의를 넘어 기능을 늘리면 오히려 혼란이 커집니다. 재연결, 버전 표시, 짧은 경고 정도로 제한하고 나머지는 CLI와 Gateway에 남기세요. 사용자가 “보조 앱에서만 보이는 설정”을 만들기 시작하면 동기화 지옥에 가깝습니다.
런북 마지막에는 롤백입니다. plist를 이전 바이트 동일 복사, 포트 표를 이전 값으로, 환경 변수 스냅샷을 되돌리는 세 줄과 검증 한 줄을 반드시 붙입니다. 롤백이 성공했다는 증거 없이 새 버전만 올리면 감사가 받아들이지 않습니다.
임대 Apple Silicon Mac은 사무실 책상에 없는 하드웨어를 가동률 위주로 쓰면서도 Gateway·터미널·감사를 한 그래픽 세션에 모을 수 있게 해 줍니다. 온프레미스 고립 노드보다 증거 일관성을 맞추기 쉬운 경우가 많습니다. 다만 “임대”라는 사실 자체가 변경 관리에 들어가야 하며, 계약 종료 시 키와 토큰 회수를 런북에 포함하세요.
Windows 노트북은 제어의 허브로 두되, 최종 서명과 키체인 증명은 Mac 화면에 남깁니다. 이 원칙만 지켜도 야간 장애 통화 시간이 눈에 띄게 줄어듭니다. 팀이 커질수록 표준 뷰어 설정과 표준 터널 스크립트를 저장소에 넣고 버전을 태그하세요.
마지막으로 이 글은 파일 도구 deny-by-default나 페어링 세부를 대체하지 않습니다. 파일 경계가 필요하면 같은 날짜대의 영문·다국어 파일 도구 체크리스트와 짝을 이루게 두고, 여기서는 전송층과 데스크톱 세션 쪽만 다룹니다. 검색 의도를 섞지 않는 것이 장기적으로 독자에게 이롭습니다.
자동화와 스크립트는 CLI로 충분한 경우가 많지만, 도구 패널·브라우저 연동·헬스 UI는 Gateway가 담당합니다. 증거를 티켓에 남길 때는 둘의 역할을 분리해 기록하세요.
키체인·시스템 설정·게이트웨이 창 검증이 필요하면 VNC 같은 그래픽 세션이 필요합니다. SSH만으로는 Finder나 동의 창 재현이 어렵습니다.
로컬 다른 서비스와 충돌하면 바인드 주소를 바꾸거나 충돌 프로세스를 정리하고, 방화벽 규칙과 문서의 기대 포트를 함께 업데이트하세요.
원격 화면 옆에서 클립보드·파일 드롭·단축 재연결을 돕는 역할로 두고, 실제 빌드와 서명은 항상 Mac 쪽 동일 사용자 세션에서 검증하세요.
CLI·Gateway·macOS 보조의 경계를 문서화하고, Windows는 제어 허브로 두며, SSH 전용과 VNC 임대 중 증거가 요구하는 쪽을 선택하세요. 포트와 사용자를 표에 고정하면 반복 장애가 줄어듭니다.
자체 Mac도 감가·수면·대역을 짊어집니다. Apple Silicon 임대 원격 Mac은 가동과 이미지를 공급자에 맡기면서 Gateway·터미널·감사를 한 세션에 맞출 수 있습니다.
같은 검수를 원격 Mac에서 하려면 VNCMac: 메인 버튼은 Mac 클라우드 구매 페이지, 연결 안내는 헬프 센터입니다.