원격 제어

​

모드

• 로컬(이 Mac): 모든 항목이 노트북에서 실행되며 SSH는 사용하지 않습니다.
• SSH를 통한 원격(기본값): OpenClaw 명령이 원격 호스트에서 실행됩니다. 앱은 -o BatchMode, 선택한 ID/키, 로컬 포트 전달을 사용하여 SSH 연결을 엽니다.
• 원격 직접 연결(ws/wss): SSH 터널을 사용하지 않으며 앱이 Gateway URL에 직접 연결합니다(LAN, Tailscale, Tailscale Serve 또는 공개 HTTPS 역방향 프록시).

​

원격 전송 방식

• SSH 터널(기본값): ssh -N -L ...을 사용하여 Gateway 포트를 localhost로 전달합니다. 터널이 루프백이므로 Gateway에는 Node의 IP가 127.0.0.1로 표시됩니다.
• 직접 연결(ws/wss): Gateway URL에 바로 연결합니다. Gateway에는 실제 클라이언트 IP가 표시됩니다.

​

원격 호스트의 사전 요구 사항

1. Node + pnpm을 설치하고 OpenClaw CLI를 빌드/설치합니다(pnpm install && pnpm build && pnpm link --global).
2. 비대화형 셸의 PATH에 openclaw가 포함되어 있는지 확인합니다(필요한 경우 /usr/local/bin 또는 /opt/homebrew/bin에 심볼릭 링크 생성).
3. SSH 전송 방식의 경우 키 기반 SSH 인증을 설정합니다. LAN 외부에서도 안정적으로 연결하려면 Tailscale IP를 사용하는 것이 좋습니다.

​

macOS 앱 설정

openclaw-mac configure-remote \
  --ssh-target user@gateway-host \
  --local-port 18789 \
  --remote-port 18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw-mac configure-remote \
  --direct-url ws://192.168.0.202:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

1. _Settings -> General_을 엽니다.
2. OpenClaw runs에서 Remote를 선택하고 다음을 설정합니다.
   • Transport: SSH tunnel 또는 Direct (ws/wss).
   • SSH target: user@host(선택적으로 :port). Gateway가 동일한 LAN에 있고 Bonjour를 통해 자신을 알리는 경우 검색된 목록에서 선택하면 이 필드가 자동으로 채워집니다.
   • Gateway URL(Direct 전용): wss://gateway.example.ts.net(로컬/LAN에서는 ws://...).
   • Identity file(고급): 키 파일의 경로.
   • Project root(고급): 명령에 사용되는 원격 체크아웃 경로.
   • CLI path(고급): 실행 가능한 openclaw 진입점/바이너리의 선택적 경로(알림 정보에 포함된 경우 자동으로 채워짐).
3. Test remote를 누릅니다. 성공은 원격 openclaw status --json이 올바르게 실행되었음을 의미합니다. 실패는 일반적으로 PATH/CLI 문제이며, 종료 코드 127은 원격에서 CLI를 찾지 못했음을 의미합니다.
4. 이제 상태 확인과 Web Chat이 선택한 전송 방식을 통해 자동으로 실행됩니다.

​

Web Chat

• SSH 터널: 전달된 WebSocket 제어 포트(기본값 18789)를 통해 Gateway에 연결합니다.
• 직접 연결(ws/wss): 구성된 Gateway URL에 바로 연결합니다.
• 별도의 Web Chat HTTP 서버는 없습니다.

​

권한

• 원격 호스트에는 로컬과 동일한 TCC 승인(자동화, 손쉬운 사용, 화면 기록, 마이크, 음성 인식, 알림)이 필요합니다. 해당 시스템에서 온보딩을 한 번 실행하여 권한을 부여하세요.
• Node는 node.list / node.describe를 통해 권한 상태를 알리므로 에이전트가 사용 가능한 기능을 파악할 수 있습니다.

​

보안 참고 사항

• 원격 호스트에서는 루프백 바인딩을 우선 사용하고 SSH, Tailscale Serve 또는 신뢰할 수 있는 Tailnet/LAN 직접 URL을 통해 연결하세요.
• SSH 터널링에는 기본적으로 이미 신뢰된 호스트 키가 필요합니다. 먼저 호스트 키를 신뢰하도록 설정하여 구성된 known-hosts 파일에 추가하거나, OpenSSH 신뢰 정책을 수락할 수 있는 관리형 별칭에 대해 gateway.remote.sshHostKeyPolicy: "openssh"를 명시적으로 설정하세요.
• Gateway를 비루프백 인터페이스에 바인딩하는 경우 유효한 Gateway 인증을 요구하도록 설정하세요. 토큰, 비밀번호 또는 gateway.auth.mode: "trusted-proxy"가 설정된 ID 인식 역방향 프록시를 사용할 수 있습니다.
• 보안 및 Tailscale을 참조하세요.

​

WhatsApp 로그인 흐름(원격)

• 원격 호스트에서 openclaw channels login --channel whatsapp --verbose를 실행합니다. 휴대전화의 WhatsApp으로 QR 코드를 스캔합니다.
• 인증이 만료되면 해당 호스트에서 로그인을 다시 실행합니다. 상태 확인에 연결 문제가 표시됩니다.

​

문제 해결

​

알림 소리

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

​

관련 문서

• macOS 앱
• 원격 액세스