OpenClaw 2026 원격 Gateway 페어링과 SSH 터널: macOS 클라이언트 Health Check 문제 해결 및 LaunchAgent 상주 체크리스트
JEXCLOUD 클라우드 Mac에서 OpenClaw Gateway를 이미 띄웠는데, 로컬 macOS 앱에서는 「Health check pending」 또는 gateway.remote 페어링 실패에 막히고 있지 않나요? 2026년에 가장 흔한 원인은 「Gateway가 죽었다」가 아니라 로컬 App ↔ SSH 터널 ↔ 원격 127.0.0.1:18789 경로 어딘가 한 고리가 끊긴 것입니다. 본문은 로컬 OpenClaw 클라이언트로 원격 Gateway를 제어하는 개발자와 SRE를 위해 SSH 터널과 Direct WSS 선택 매트릭스, LaunchAgent 상주 체크리스트, Health Check 순찰 스크립트와 대조 문제 해결 표를 제공합니다(설정 세부는 OpenClaw 공식 onboarding 문서 참고).
읽은 뒤 다음 세 가지에 답할 수 있어야 합니다: ① 네트워크 환경에서 SSH LocalForward와 Direct wss:// 중 무엇을 택할지; ② OPENCLAW_GATEWAY_TOKEN과 ai.openclaw.ssh-tunnel / ai.openclaw.gateway 두 LaunchAgent의 역할 분담; ③ CLI openclaw health는 통과하는데 UI가 pending일 때 포트, Token, 터널 프로세스 중 무엇을 볼지.
01 OpenClaw 원격 Gateway 아키텍처: 로컬 macOS 클라이언트로 클라우드 Mac 원격 제어
2026년 OpenClaw는 macOS에서 Gateway 연결에 Local(Gateway와 App 동일 머신)과 Remote(Gateway는 다른 Mac, 로컬 App은 SSH 터널 또는 Direct WebSocket) 두 모드를 제공합니다. 프로덕션에서는 Gateway를 JEXCLOUD 베어메탈 Mac의 127.0.0.1:18789에서 돌리고 개발자 노트북의 OpenClaw.app은 「리모컨」만 담당하는 구성이 흔합니다. 이는 노드 선택과 launchd Token 문제 해결 글과 보완 관계입니다. 그 글은 「원격 머신 설치·선택」, 본문은 「로컬 연결·상주·검증」을 다룹니다.
리뷰 회의에서 과소평가되기 쉬운 pain point 다섯 가지입니다.
- 터널 미상주: SSH 세션이 끊겨도 로컬 App은 이전 상태를 보여 주다 Health Check 타임아웃 후에야 Gateway 불가를 알게 됩니다.
- Token 이중 체계 불일치: 원격
launchctl환경 변수,~/.openclaw설정, 로컬 App 입력 Token이 어긋나면 pairing / device token류 오류가 납니다. - 포트와 포워딩 불일치: 기본 Gateway 포트 18789 점유 또는 LocalForward 대상 오류 시 CLI는 원격 직결 성공, 로컬 localhost 실패가 됩니다.
- Health Check UI 지연: CLI 헬스는 통과했는데 macOS 앱 UI는 pending(커뮤니티 Issue: openclaw#66306).
- 보안 노출: Gateway를
0.0.0.0에 바인딩하고 mTLS 없이 공인 IP에 두면 사실상 노출 상태입니다. 127.0.0.1 + SSH/Tailscale을 권장합니다.
기억 구절: 「Gateway는 루프백만, 터널이 외부로, Token은 단일 진실원」. 어느 하나라도 우회하면 문제 해결은 시간 단위가 됩니다.
02 SSH 터널인가 Direct WSS인가: OpenClaw 원격 접속 선택 매트릭스
OpenClaw 설정의 OpenClaw runs에서 Transport는 보통 SSH tunnel과 Direct (ws/wss) 중 하나입니다. 영원히 맞는 선택은 없고 방화벽, Tailscale 커버리지, 운영 습관에 맞는 것을 고릅니다.
| 차원 | SSH 터널 + LocalForward | Direct WSS |
|---|---|---|
| 보안 경계 | Gateway는 127.0.0.1만 수신; 외부는 SSH 암호화 | TLS 종료와 Token 필요; Tailscale / 사내망 DNS와 병용이 많음 |
| 방화벽 친화도 | SSH 22(또는 사용자 포트)만 통과하면 됨 | wss 포트와 인증서 체인 개방 필요; 기업 프록시에서 실패하기 쉬움 |
| 지연과 안정성 | SSH 1홉 추가, RTT 15–40 ms는 허용; KeepAlive plist로 자가 복구 | 홉이 적음; 안정된 WSS 리버스 프록시 환경에 적합 |
| 운영 복잡도 | ~/.ssh/config와 터널 LaunchAgent 유지 |
인증서, 리버스 프록시, Token 로테이션 절차 유지 |
| 권장 시나리오 | 개발자 노트북에서 JEXCLOUD 단일 노드 원격 제어; 전담 SRE 없는 소규모 팀 | Tailscale Serve / 통합 API 게이트웨이가 있는 다인 팀 |
도움말 센터에서 SSH 키 로그인을 켰고 원격 Gateway가 루프백만 바인딩되어 있다면 우선 SSH 터널을 택하세요. 회사에서 안정된 wss://gateway.example.ts.net을 제공하고 macOS 클라이언트 「Test remote」가 지속 통과할 때만 Direct로 전환합니다.
03 클라우드 Mac 사전 준비: PATH, Token 권한, SSH 설정 조각
원격 호스트는 비대화형 Shell에서 OpenClaw CLI를 호출할 수 있어야 합니다(pnpm link --global 후 /opt/homebrew/bin 또는 /usr/local/bin symlink 권장). Token 파일 권한은 600, 소유자는 Gateway 실행 사용자와 일치해야 합니다.
Host jex-openclaw-sg
HostName your-instance.jexcloud.com
User macuser
IdentityFile ~/.ssh/jexcloud_ed25519
LocalForward 18789 127.0.0.1:18789
ServerAliveInterval 30
ServerAliveCountMax 3<key>Label</key>
<string>ai.openclaw.ssh-tunnel</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/ssh</string>
<string>-N</string>
<string>jex-openclaw-sg</string>
</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>Gateway 본체는 macOS 앱 또는 CLI로 LaunchAgent ai.openclaw.gateway를 설치합니다. 환경 변수 OPENCLAW_GATEWAY_TOKEN은 launchctl setenv 또는 plist EnvironmentVariables로 주입하고 shell profile과 plist 이중 기록으로 드리프트를 피하세요.
04 OpenClaw 원격 Gateway 페어링 6단계: Test remote부터 LaunchAgent 검증까지
- 원격 CLI 설치 및 Gateway 기동: JEXCLOUD 인스턴스에서
openclaw gateway install(또는 앱 가이드로 LaunchAgent 설치) 실행 후lsof -i :18789가127.0.0.1만 수신하는지 확인합니다. - Token 기록 및 검증: Gateway Token 생성,
chmod 600저장;launchctl setenv OPENCLAW_GATEWAY_TOKEN '…'후 Gateway Agent 재시작. - 로컬 SSH 설정: 앞 절
LocalForward 18789를~/.ssh/config에 기록,ssh -N jex-openclaw-sg수동 실행. 다른 터미널에서curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health가 200이어야 합니다. - 터널 LaunchAgent 설치:
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist실행, 로그인 후 터널 자동 기동 확인. - macOS 클라이언트 페어링: 설정 → OpenClaw runs → Remote + SSH tunnel 선택,
user@host입력(config 별칭이면 Host만 가능), Test remote 통과까지 실행. - 순찰과 알림 등록: Health 스크립트를
StartInterval(권장 300s) 또는 CI SSH job에 넣고, 실패 시launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel과 종료 코드를 on-call용으로 기록합니다.
페어링 후 앱 내 onboarding 세션으로 Agent 채널을 검증할 수 있습니다. CLI만 되고 UI가 pending이면 다음 절 대조표로 조사하고 Gateway 재설치는 반복하지 마세요.
05 Health Check 순찰 스크립트와 인용 가능한 기술 데이터
프로덕션에서는 UI 상태등보다 스크립트로 HTTP 200을 단언하는 것을 권장합니다. 아래는 리뷰 문서에 인용 가능한 항목입니다(2026 커뮤니티 실천과 JEXCLOUD 노드 관측 구간, SLA 아님).
- 기본 Gateway 포트:
18789(LocalForward와 일치; 다중 인스턴스는 문서대로 추가 포트 계획). - Health 엔드포인트: 흔히
/health, Bearer Token 필요; 200이 아니면 모니터링 종료 코드 비영. - SSH 터널 자가 복구: LaunchAgent
KeepAlive+ServerAliveInterval 30으로 끊김 복구를 30–90초 수준으로 압축하는 경우가 많음(네트워크 지터에 따름). - 아시아 태평양 RTT: 동아시아 개발자가 SSH로 SG/JP/HK 노드 접근 시 CLI 왕복 15–35 ms가 흔함; 터널 추가 부하는 보통 < 5 ms로 무시 가능.
- Token 파일 권한: 600 필수; 소유자와 Gateway 프로세스 사용자 불일치 시 launchd가 조용히 거부할 수 있음.
#!/bin/bash
TOKEN="${OPENCLAW_GATEWAY_TOKEN:?}"
CODE=$(curl -sf -o /dev/null -w '%{http_code}' \
-H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health)
[[ "$CODE" == "200" ]] || exit 106 자주 묻는 FAQ, Health pending 대조, JEXCLOUD 선택 정리
| 현상 | 우선 확인 | 조치 |
|---|---|---|
| CLI 200, UI pending | App 캐시, Transport 모드, 로컬 localhost 포워딩 | App 재시작; Remote+SSH 확인; Test remote 재실행 |
| pairing / token mismatch | 이중 Token, device token 파일 | plist와 App 내 Token 통일; 공식 remote gateway 문서로 페어링 재설정 |
| Connection refused | 터널 프로세스, 포트 점유 | launchctl list | grep openclaw; 18789 확인 |
| 터널 자주 끊김 | 노트북 절전, NAT 타임아웃 | ServerAlive; 터널 KeepAlive plist; 수동 ssh -N만 의존하지 않기 |
가정용 회선이나 불안정한 Wi‑Fi를 7×24 터널 입구로 쓰면 NAT 타임아웃과 절전 정책으로 「아침엔 되고 오후엔 전부 빨강」이 잦습니다. Gateway를 시간제 VPS나 오버셀 가상화에 두면 이웃 경합으로 Health가 간헐 실패할 수 있습니다. 순수 로컬 Mac은 자동 업데이트 재부팅, Keychain 팝업 무인 대응도 영향을 줍니다. 로컬 App 안정 원격 제어, Token 감사 가능, 터널 자가 복구가 필요한 팀에는 Gateway를 JEXCLOUD 다중 리전 베어메탈 Mac에 두고 SSH 루프백 + LaunchAgent 상주가 가장 수고가 적은 조합인 경우가 많습니다: Apple Silicon 전용, 약 120초 배포, 프로젝트별 병렬 또는 M4 Pro 업그레이드 가능. 플랜과 노드는 JEXCLOUD 요금 페이지; GUI 문제 해결은 VNC 페이지 원격 데스크톱 개통 안내와 병용하세요.