원격 OpenClaw (macOS ⇄ 원격 호스트)

이 흐름을 통해 macOS 앱이 다른 호스트(데스크톱/서버)에서 실행되는 OpenClaw 게이트웨이의 완전한 원격 제어 역할을 합니다. 앱의 Remote over SSH (원격 실행) 기능입니다. 상태 확인, Voice Wake 전달, Web Chat을 포함한 모든 기능이 _Settings → General_의 동일한 원격 SSH 설정을 재사용합니다.

모드

Local (this Mac): 모든 것이 노트북에서 실행됩니다. SSH 불필요.
Remote over SSH (기본): OpenClaw 명령이 원격 호스트에서 실행됩니다. Mac 앱이 -o BatchMode와 선택한 아이덴티티/키 및 로컬 포트 포워딩으로 SSH 연결을 엽니다.
Remote direct (ws/wss): SSH 터널 없음. Mac 앱이 게이트웨이 URL에 직접 연결합니다 (예: Tailscale Serve 또는 퍼블릭 HTTPS 리버스 프록시를 통해).

원격 전송 방식

원격 모드는 두 가지 전송 방식을 지원합니다:

SSH 터널 (기본): ssh -N -L ...을 사용하여 게이트웨이 포트를 로컬호스트로 포워딩합니다. 터널이 루프백이므로 게이트웨이는 노드의 IP를 127.0.0.1로 인식합니다.
Direct (ws/wss): 게이트웨이 URL에 직접 연결합니다. 게이트웨이가 실제 클라이언트 IP를 인식합니다.

원격 호스트 사전 요구 사항

Node + pnpm을 설치하고 OpenClaw CLI를 빌드/설치합니다 (pnpm install && pnpm build && pnpm link --global).
비대화형 셸에서 openclaw가 PATH에 있는지 확인합니다 (필요 시 /usr/local/bin 또는 /opt/homebrew/bin에 심볼릭 링크).
키 인증으로 SSH를 엽니다. LAN 외부에서 안정적인 접근을 위해 Tailscale IP를 권장합니다.

macOS 앱 설정

_Settings → General_을 엽니다.
OpenClaw runs에서 Remote over SSH를 선택하고 설정합니다:
- Transport: SSH tunnel 또는 Direct (ws/wss).
- SSH target: user@host (선택적 :port).
  - 게이트웨이가 동일 LAN에 있고 Bonjour를 광고하면, 발견된 목록에서 선택하여 이 필드를 자동 채울 수 있습니다.
- Gateway URL (Direct만): wss://gateway.example.ts.net (또는 로컬/LAN용 ws://...).
- Identity file (고급): 키 경로.
- Project root (고급): 명령에 사용되는 원격 체크아웃 경로.
- CLI path (고급): 실행 가능한 openclaw 진입점/바이너리 경로 (선택, 광고 시 자동 채움).
Test remote를 누릅니다. 성공은 원격 openclaw status --json이 올바르게 실행됨을 나타냅니다. 실패는 보통 PATH/CLI 문제; exit 127은 CLI가 원격에서 발견되지 않음을 의미합니다.
이후 상태 확인과 Web Chat이 이 SSH 터널을 통해 자동으로 실행됩니다.

Web Chat

SSH 터널: Web Chat이 포워딩된 WebSocket 제어 포트(기본 18789)를 통해 게이트웨이에 연결합니다.
Direct (ws/wss): Web Chat이 설정된 게이트웨이 URL에 직접 연결합니다.
별도의 WebChat HTTP 서버는 더 이상 없습니다.

권한

원격 호스트도 로컬과 동일한 TCC 승인이 필요합니다 (자동화, 접근성, 화면 기록, 마이크, 음성 인식, 알림). 해당 머신에서 온보딩을 실행하여 한 번 부여하세요.
노드는 node.list / node.describe를 통해 권한 상태를 광고하여 에이전트가 가용한 기능을 파악합니다.

보안 참고 사항

원격 호스트에서 루프백 바인딩을 선호하고, SSH 또는 Tailscale을 통해 연결하세요.
SSH 터널링은 엄격한 호스트 키 확인을 사용합니다. ~/.ssh/known_hosts에 호스트 키가 있도록 먼저 신뢰하세요.
게이트웨이를 비루프백 인터페이스에 바인딩하면, 토큰/비밀번호 인증을 요구하세요.
보안 및 Tailscale을 참조하세요.

WhatsApp 로그인 흐름 (원격)

원격 호스트에서 openclaw channels login --verbose를 실행합니다. 스마트폰의 WhatsApp으로 QR 코드를 스캔합니다.
인증이 만료되면 해당 호스트에서 로그인을 다시 실행합니다. 상태 확인이 연결 문제를 알려줍니다.

문제 해결

exit 127 / not found: 비로그인 셸에서 openclaw가 PATH에 없습니다. /etc/paths, 셸 rc에 추가하거나 /usr/local/bin//opt/homebrew/bin에 심볼릭 링크하세요.
상태 확인 프로브 실패: SSH 접근성, PATH, Baileys 로그인 여부(openclaw status --json)를 확인하세요.
Web Chat 멈춤: 원격 호스트에서 게이트웨이가 실행 중이고 포워딩된 포트가 게이트웨이 WS 포트와 일치하는지 확인하세요. UI는 정상적인 WS 연결이 필요합니다.
노드 IP가 127.0.0.1로 표시: SSH 터널에서는 예상된 동작입니다. 게이트웨이가 실제 클라이언트 IP를 인식하길 원하면 Transport를 **Direct (ws/wss)**로 전환하세요.
Voice Wake: 원격 모드에서 트리거 문구가 자동으로 전달됩니다. 별도의 전달기가 필요 없습니다.

알림 소리

스크립트에서 openclaw 및 node.invoke로 알림별 소리를 선택할 수 있습니다:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

앱에 전역 “기본 소리” 토글은 더 이상 없습니다. 호출자가 요청마다 소리를 선택합니다(또는 없음).