메인 콘텐츠로 건너뛰기

​
원격 액세스 (SSH, 터널 및 tailnets)

이 저장소는 전용 호스트(데스크톱/서버)에서 단일 게이트웨이(주 호스트)를 실행하고 클라이언트를 연결하여 “SSH를 통한 원격”을 지원합니다.
  • 운영자 (당신 / macOS 앱): SSH 터널링은 보편적인 대안입니다.
  • 노드 (iOS/Android 및 향후 디바이스): 필요 시 LAN/tailnet 또는 SSH 터널을 통해 게이트웨이 웹소켓에 연결합니다.

​
핵심 아이디어

  • 게이트웨이 웹소켓은 설정된 포트(기본값 18789)의 루프백에 바인딩됩니다.
  • 원격 사용을 위해 SSH를 통해 해당 루프백 포트를 전달하거나 tailnet/VPN을 사용하여 터널을 줄입니다.

​
일반적인 VPN/tailnet 설정 (에이전트가 위치하는 곳)

게이트웨이 호스트를 “에이전트가 위치하는 곳”으로 생각하세요. 이 호스트는 세션, 인증 프로파일, 채널 및 상태를 소유합니다. 노트북/데스크톱(및 노드)이 해당 호스트에 연결됩니다.

​
1) tailnet의 항상 켜져 있는 게이트웨이 (VPS 또는 집 서버)

지속적인 호스트에서 게이트웨이를 실행하고 Tailscale 또는 SSH를 통해 연결합니다.
  • 최고의 UX: gateway.bind: "loopback"을 유지하고 Tailscale Serve를 사용하여 제어 UI를 제공합니다.
  • 대체 옵션: 액세스가 필요한 모든 머신에서 루프백 + SSH 터널을 유지합니다.
  • 예시: exe.dev (쉬운 VM) 또는 Hetzner (생산용 VPS).
자주 잠에 드는 노트북에도 에이전트를 항상 켜 두고 싶을 때 이상적입니다.

​
2) 홈 데스크톱이 게이트웨이를 실행하고, 노트북은 원격 제어

노트북은 에이전트를 실행하지 않습니다. 원격으로 연결합니다:
  • macOS 앱의 원격 SSH 모드(Settings → General → “OpenClaw 실행”)를 사용하세요.
  • 앱이 터널을 열고 관리하므로, WebChat + 상태 검사가 “그냥 작동합니다.”
절차서: macOS 원격 액세스.

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

게이트웨이를 로컬로 유지하되 안전하게 노출합니다:
  • 다른 머신에서 노트북으로 SSH 터널을 생성하거나,
  • 제어 UI를 Tailscale Serve로 제공하고 게이트웨이를 루프백 전용으로 유지합니다.
가이드: Tailscale 및 웹 개요.

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

하나의 게이트웨이 서비스가 상태와 채널을 소유합니다. 노드는 주변기기입니다. 흐름 예시 (Telegram → 노드):
  • Telegram 메시지가 게이트웨이에 도착합니다.
  • 게이트웨이가 에이전트를 실행하고 노드 도구 호출 여부를 결정합니다.
  • 게이트웨이가 게이트웨이 웹소켓을 통해 노드를 호출합니다 (node.* RPC).
  • 노드가 결과를 반환하고, 게이트웨이는 Telegram으로 응답을 보냅니다.
주의사항:
  • 노드는 게이트웨이 서비스를 실행하지 않습니다. 의도적으로 격리된 프로파일을 실행하지 않는 한, 각 호스트 당 하나의 게이트웨이만 실행해야 합니다 (여러 게이트웨이 참조).
  • macOS 앱의 “노드 모드”는 단지 게이트웨이 웹소켓을 통한 노드 클라이언트입니다.

​
SSH 터널 (CLI + 도구)

원격 게이트웨이 WS에 로컬 터널을 생성합니다: 
ssh -N -L 18789:127.0.0.1:18789 user@host
터널이 열리면:
  • openclaw health와 openclaw status --deep이 이제 ws://127.0.0.1:18789를 통해 원격 게이트웨이에 도달합니다.
  • openclaw gateway {status,health,send,agent,call}도 필요 시 --url을 통해 전달된 URL로 타깃할 수 있습니다.
참고: 18789를 설정된 gateway.port(또는 --port/OPENCLAW_GATEWAY_PORT)로 대체하십시오. 참고: --url을 전달할 때, CLI는 구성이나 환경 자격 증명으로 되돌아가지 않습니다. --token 또는 --password를 명시적으로 포함하십시오. 명시적인 자격 증명 누락은 오류입니다.

​
CLI 원격 기본값

CLI 명령어가 기본적으로 사용할 수 있도록 원격 대상을 지속적으로 설정할 수 있습니다: 
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}
게이트웨이가 루프백 전용일 때, URL을 ws://127.0.0.1:18789로 유지하고 SSH 터널을 먼저 여십시오.

​
SSH를 통한 채팅 UI

WebChat은 더 이상 별도의 HTTP 포트를 사용하지 않습니다. SwiftUI 채팅 UI가 게이트웨이 웹소켓에 직접 연결합니다.
  • SSH를 통해 18789를 전달한 후(위 참조), 클라이언트를 ws://127.0.0.1:18789에 연결하십시오.
  • macOS에서는 터널을 자동으로 관리하는 앱의 “원격 SSH” 모드를 선호하십시오.

​
macOS 앱 “원격 SSH”

macOS 메뉴 바 앱은 동일한 설정을 처음부터 끝까지 수행할 수 있습니다 (원격 상태 검사, WebChat 및 Voice Wake 전달). 절차서: macOS 원격 액세스.

​
보안 규칙 (원격/VPN)

요약: 게이트웨이를 루프백 전용으로 유지하십시오. 바인드가 필요하다고 확신하지 않는 한.
  • 루프백 + SSH/Tailscale Serve는 가장 안전한 기본값입니다 (공개 노출 없음).
  • 비루프백 바인드(lan/tailnet/custom, 또는 루프백이 사용 불가능할 때 auto)는 인증 토큰/비밀번호를 반드시 사용해야 합니다.
  • gateway.remote.token은 원격 CLI 호출에만 사용됩니다. 로컬 인증을 활성화하지 않습니다.
  • gateway.remote.tlsFingerprint는 wss://를 사용할 때 원격 TLS 인증서를 고정합니다.
  • Tailscale Serve는 gateway.auth.allowTailscale: true일 때 신원 헤더를 통해 Control UI/WebSocket 트래픽을 인증할 수 있습니다; HTTP API 엔드포인트는 여전히 토큰/비밀번호 인증이 필요합니다. 이 토큰 없는 흐름은 게이트웨이 호스트가 신뢰할 수 있다고 가정합니다. 어디서나 토큰/비밀번호를 원하면 이를 false로 설정하세요.
  • 브라우저 제어는 운영자 접근처럼 다루십시오: tailnet 전용 + 의도적인 노드 페어링.
자세히 알아보기: 보안.