2026년 OpenClaw 원격 Mac 네이티브 설치와 게이트웨이 SSH 터널 운영: Node 22, onboard 데몬, doctor 오류 FAQ

팀은 웹훅·MCP 자식 프로세스·장기 큐를 개발자 노트북이 아닌 전용 원격 Mac에 두는 경우가 늘고 있습니다. 실패의 대부분은 나쁜 YAML이 아니라 PATH 불일치, 이중 NAT, 그리고 VNC 로그인이 끊기면 Gateway도 같이 잠드는 운영입니다. 여기서는 네이티브 설치와 Node 22 고정, 디렉터리를 만들어 주는 onboard를 doctor보다 먼저 돌리는 순서, 공인 IP에 바인딩하지 않고 SSH 터널로 제어 UI·RPC에 닿는 패턴, 그리고 터널이 살아 있어도 남는 doctor 이슈를 FAQ로 묶습니다. 터널이 안정된 뒤 MCP 전송·타임아웃을 다루려면 OpenClaw MCP stdio와 Streamable HTTP, 타임아웃·ENOENT 재현을 함께 보고, 러너·디스크 운영은 자체 호스티드 Runner·Actions 캐시·영구 디스크 FAQ와 맞추면 좋습니다. Docker·경로·로컬 상주 비교는 원격 Mac 배포 실무에서 이어집니다.

1. 호스트 기준선: Apple Silicon, Xcode CLT, plist에 넣을 Node 22

git·security 등을 위해 Command Line Tools 또는 Xcode를 설치합니다. Node 22는 Homebrew 경로(/opt/homebrew/opt/node@22/bin/node)나 nvm 프리픽스처럼 절대 경로로 고정하고, 대화형 셸의 node -v와 doctor가 출력하는 런타임이 같은지 확인합니다. 실험 중 Node를 올렸다면 plist를 맞춘 뒤 에이전트를 다시 올리고 그다음 doctor를 실행하세요. 그렇지 않으면 권한 문제로 보이는 현상이 사실은 argv·PATH 드리프트인 경우가 많습니다. OpenClaw 상태 디렉터리는 로컬 APFS에 두고 Desktop/Documents·iCloud 동기화 아래는 피합니다. WAL·락 파일이 클라우드 동기화와 섞이면 간헐 손상이 납니다.

2. 설치 경로 한눈에: npm 전역 vs install.sh vs 소스(pnpm)

2026년 커뮤니티에서 흔한 분기는 (1) npm i -g openclaw@latest, (2) 공식 curl -fsSL https://openclaw.ai/install.sh | bash류, (3) 저장소 클론 후 pnpm 빌드입니다. 운영 편의는 전역 npm·스크립트 쪽이고, 패치·포크가 필요하면 소스입니다. Docker는 격리·업그레이드 롤백에 유리하지만 본문 주제는 네이티브·launchd입니다. 어떤 경로든 최종적으로 which openclaw와 비대화형 SSH 세션에서의 PATH가 같아야 합니다.

• 네이티브(본문): Metal·로컬 바이너리·TCC를 그대로 쓰고 SSH·plist로 감쌉니다.
• Docker: 호스트 볼륨·포트 매핑·데스크톱 키체인과의 간극을 감수하는 대신 이미지 핀으로 재현성이 좋습니다.
• 매니지드 SaaS: 운영을 아웃소싱하고 싶을 때; 커스텀 MCP·로컬 도구 체인은 제약을 먼저 확인합니다.

3. 올바른 순서: onboard를 doctor 앞에

onboard는 예상 폴더 생성, 예시 설정, 플러그인 엔트리와 파일 레이아웃을 맞춥니다. 먼저 doctor만 돌리면 소켓 없음·상태 루트 읽기 실패·아직 링크되지 않은 바이너리에 대한 ENOENT 등 가짜 양성이 쌓입니다. onboard를 프로비저닝, doctor를 검증으로 두고 출력을 한 티켓에 묶어 두면 지원·온콜이 diff하기 쉽습니다. 상시 데몬이 필요하면 openclaw onboard --install-daemon(버전에 따라 동등 플래그)으로 가이드를 따르고, 이후 openclaw gateway status와 doctor를 교차 확인합니다. ClawHub 스킬을 쓴다면 자동화 전에 plugins.entries를 최소화하세요.

4. Gateway 가시성과 SSH: 기본 포트 18789를 localhost에 두고

많은 배포에서 Gateway는 Mac 안의 127.0.0.1:18789(또는 문서 기준 포트)에만 바인딩하고, 노트북·배스천에서 LocalForward로 붙습니다. 데이터센터 쪽에서 역방향 다이얼이 필요하면 같은 SSH 세션으로 RemoteForward를 쓰고, 인바운드 방화벽을 열지 않습니다. 설정에서 루프백 전용 바인드(버전별 키 이름은 릴리스 노트 확인)를 켜 두어 MCP가 0.0.0.0에 실수로 노출되지 않게 합니다. CI가 터널을 물려 받는 경우 ServerAliveInterval·TCPKeepAlive를 조정해 반쯤 열린 연결을 줄입니다.

5. onboard 보조 작업과 Gateway를 launchd로

Gateway형 부하는 사용자 LaunchAgent가 일반적입니다. WorkingDirectory를 저장소 또는 상태 루트로 두고, 최소한의 PATH를 plist에 선언하며, 표준 출력·에러는 ~/Library/Logs 아래로 보냅니다. 수정 후에는 launchctl bootstrap gui/$UID …로 다시 올립니다. 일회성 onboard를 plist에 넣었다면 초기 부트 한 번 뒤 비활성화해 의도적인 설정 드리프트를 덮어쓰지 않게 합니다. 대부분 팀은 업그레이드 때만 onboard를 수동으로 돌리고 Gateway만 감시합니다. 여러 운영자가 한 대를 쓴다면 루트 데몬보다 사용자별 에이전트를 선호하세요. TCC 프롬프트가 상호작용 셸에서는 보이는데 root 작업에서는 숨는 경우가 있습니다.

6. doctor FAQ: 터널 다음에도 남는 것들

자식 MCP ENOENT: 터널이 아니라 plist의 cwd·argv[0]·PATH를 고칩니다. 포트 사용 중: Gateway는 한 포트에 하나; launchctl print로 중복 Label을 정리합니다. TLS·웹훅 불일치: GitHub이 보는 공개 URL과 전달된 Host 헤더가 맞는지, 터널을 통한 curl -v로 먼저 확인합니다. 도구 버스트 타임아웃: 전송이 검증된 뒤 MCP 타임아웃을 올리세요. Xcode가 CPU를 쓸 때는 OpenClaw 버그처럼 보이기 쉽습니다. 로컬은 정상인데 웹훅만 실패: 트래픽이 오래된 LAN IP가 아니라 포워딩된 포트로 들어오는지 확인합니다. arm64에서 sharp 등 네이티브 모듈 빌드 실패: Python·Xcode CLT 정합, pnpm approve-builds 필요 여부, 또는 문서에 나오는 SHARP_IGNORE_GLOBAL_LIBVIPS=1 같은 우회를 릴리스 노트와 함께 점검합니다. openclaw: command not found: 전역 bin이 비로그인 셸 PATH에 없습니다. plist에 전체 경로를 넣거나 심볼릭 링크를 표준 위치에 둡니다. JSON 구문 오류: openclaw.json을 jq 등으로 검증한 뒤 프로세스를 재시작합니다.

7. “원격 Mac이 프로덕션”일 때 프리플라이트

• plist의 Node 22 경로가 doctor와 일치하고, GUI 로그인 없이 재부팅 테스트를 통과합니다.
• 상태 디렉터리는 로컬 디스크에 있으며 백업 정책이 별도로 있습니다. 클라우드 동기화 폴더가 아닙니다.
• SSH 터널이 Gateway가 실제로 바인딩한 루프백 포트와 일치하고, 헬스 체크는 터널을 통해 실행합니다.
• Xcode·시뮬레이터 피크가 있으면 워커를 키우거나 스케줄을 분리해 Gateway 응답을 지킵니다.

왜 여전히 Mac mini급 하드웨어인가

SSH로 포워딩된 Gateway에는 안정적인 NIC·예측 가능한 발열·조용한 디스크가 피크 클럭보다 중요합니다. Apple Silicon Mac mini는 유휴 전력이 매우 낮으면서도 팀이 이미 신뢰하는 Unix 면을 제공합니다. Gatekeeper·SIP·FileVault와 SSH·코드 서명 도구가 같은 OS에 있어 일반 PC를 같은 역할로 굳이 단단하게 만드는 것보다 단순한 경우가 많습니다.

별도 책상 장비를 두기 어렵다면, 사용자 가까운 리전에 전용 Mac mini M4를 두고 루프백 전용 리스너와 탄력적인 터널, Xcode 피크용 여유를 한 번에 맞출 수 있습니다. 구성 비교는 Macstripe 홈에서 이어가면 됩니다.