원격 액세스 (SSH, 터널, tailnet)

이 저장소는 전용 호스트(데스크탑/서버)에서 단일 Gateway(마스터)를 실행하고 클라이언트를 여기에 연결하여 "SSH를 통한 원격" 작동을 지원합니다.

  • Operator(본인 / macOS 앱)의 경우: SSH 터널링이 범용 폴백입니다.
  • Node(iOS/Android 및 향후 장치)의 경우: Gateway WebSocket에 연결 (LAN/tailnet 또는 필요에 따라 SSH 터널).

핵심 아이디어

  • Gateway WebSocket은 구성된 포트에서 루프백에 바인딩됩니다 (기본값 18789).
  • 원격 사용을 위해, 해당 루프백 포트를 SSH를 통해 전달합니다 (또는 tailnet/VPN을 사용하여 터널링을 줄임).

일반적인 VPN/tailnet 설정 (agent가 있는 위치)

Gateway 호스트를 "agent가 사는 곳"으로 생각하세요. 세션, 인증 프로파일, 채널 및 상태를 소유합니다. 노트북/데스크탑(및 node)이 해당 호스트에 연결됩니다.

1) tailnet의 상시 Gateway (VPS 또는 홈 서버)

영구 호스트에서 Gateway를 실행하고 Tailscale 또는 SSH를 통해 연결합니다.

  • 최고의 UX: gateway.bind: "loopback"을 유지하고 Control UI에 Tailscale Serve를 사용합니다.
  • 폴백: 루프백을 유지 + 액세스가 필요한 모든 머신에서 SSH 터널.
  • 예제: exe.dev (간편한 VM) 또는 Hetzner (프로덕션 VPS).

노트북이 자주 슬립 모드로 들어가지만 agent를 항상 켜두고 싶을 때 이상적입니다.

2) 홈 데스크탑이 Gateway를 실행하고, 노트북은 원격 제어

노트북은 agent를 실행하지 않습니다. 원격으로 연결합니다:

  • macOS 앱의 SSH를 통한 원격 모드 사용 (설정 → 일반 → "OpenClaw 실행 위치").
  • 앱이 터널을 열고 관리하므로 WebChat + 상태 확인이 "그냥 작동"합니다.

런북: macOS 원격 액세스.

3) 노트북이 Gateway를 실행하고, 다른 머신에서 원격 액세스

Gateway를 로컬로 유지하되 안전하게 노출:

  • 다른 머신에서 노트북으로 SSH 터널을 연결하거나,
  • Control UI를 Tailscale Serve하고 Gateway를 루프백 전용으로 유지합니다.

가이드: Tailscale 및 Web 개요.

명령 흐름 (무엇이 어디서 실행되는지)

하나의 gateway 서비스가 상태 + 채널을 소유합니다. Node는 주변 장치입니다.

흐름 예제 (Telegram → node):

  • Telegram 메시지가 Gateway에 도착합니다.
  • Gateway가 agent를 실행하고 node tool을 호출할지 결정합니다.
  • Gateway는 Gateway WebSocket (node.* RPC)을 통해 node를 호출합니다.
  • Node가 결과를 반환하면 Gateway는 Telegram으로 다시 응답합니다.

참고:

  • Node는 gateway 서비스를 실행하지 않습니다. 의도적으로 격리된 프로파일을 실행하지 않는 한 호스트당 하나의 gateway만 실행해야 합니다 (Multiple gateways 참조).
  • macOS 앱 "node 모드"는 Gateway WebSocket을 통한 node 클라이언트일 뿐입니다.

SSH 터널 (CLI + tools)

원격 Gateway WS로 로컬 터널 생성:

ssh -N -L 18789:127.0.0.1:18789 user@host

터널이 열리면:

  • openclaw health 및 openclaw status --deep이 이제 ws://127.0.0.1:18789를 통해 원격 gateway에 연결됩니다.
  • openclaw gateway {status,health,send,agent,call}도 필요할 때 --url을 통해 전달된 URL을 대상으로 할 수 있습니다.

참고: 18789를 구성된 gateway.port (또는 --port/OPENCLAW_GATEWAY_PORT)로 교체하세요.

CLI 원격 기본값

원격 대상을 영구 저장하여 CLI 명령이 기본적으로 이를 사용하도록 할 수 있습니다:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token"
    }
  }
}

gateway가 루프백 전용인 경우, URL을 ws://127.0.0.1:18789로 유지하고 먼저 SSH 터널을 여세요.

SSH를 통한 채팅 UI

WebChat은 더 이상 별도의 HTTP 포트를 사용하지 않습니다. SwiftUI 채팅 UI는 Gateway WebSocket에 직접 연결합니다.

  • SSH를 통해 18789를 전달한 다음 (위 참조), 클라이언트를 ws://127.0.0.1:18789에 연결합니다.
  • macOS에서는 터널을 자동으로 관리하는 앱의 "SSH를 통한 원격" 모드를 선호합니다.

macOS 앱 "SSH를 통한 원격"

macOS 메뉴 바 앱은 동일한 설정을 완전히 구동할 수 있습니다 (원격 상태 확인, WebChat 및 Voice Wake 전달).

런북: macOS 원격 액세스.

보안 규칙 (원격/VPN)

간단히 말해: gateway를 루프백 전용으로 유지하세요. 바인딩이 필요하다고 확신하지 않는 한 말입니다.

  • 루프백 + SSH/Tailscale Serve가 가장 안전한 기본값입니다 (공개 노출 없음).
  • 비루프백 바인딩 (lan/tailnet/custom, 또는 루프백을 사용할 수 없을 때 auto)은 인증 token/password를 사용해야 합니다.
  • gateway.remote.token은 원격 CLI 호출 전용입니다 — 로컬 인증을 활성화하지 않습니다.
  • gateway.remote.tlsFingerprint는 wss:// 사용 시 원격 TLS 인증서를 고정합니다.
  • Tailscale Serve는 gateway.auth.allowTailscale: true일 때 identity 헤더를 통해 인증할 수 있습니다. 대신 token/password를 원하면 false로 설정하세요.
  • 브라우저 제어를 operator 액세스처럼 취급: tailnet 전용 + 의도적인 node 페어링.

심층 분석: 보안.

← 문서로 돌아가기