​

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

• **운영자(사용자 / macOS 앱)**의 경우: SSH 터널링이 범용 fallback입니다.
• **node(iOS/Android 및 향후 디바이스)**의 경우: 필요에 따라 WebSocket Gateway(LAN/tailnet 또는 SSH 터널)를 통해 연결합니다.

​

핵심 개념

• Gateway WebSocket은 구성된 포트(기본값 18789)에서 loopback에 바인딩됩니다.
• 원격 사용 시에는 이 loopback 포트를 SSH로 포워딩합니다(또는 tailnet/VPN을 사용해 터널 의존도를 줄일 수 있습니다).

​

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

​

1) tailnet 내 항상 켜져 있는 Gateway(VPS 또는 홈 서버)

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

​

2) 집의 데스크톱에서 Gateway를 실행하고, 노트북은 원격 제어만 수행

• macOS 앱의 Remote over SSH 모드를 사용하세요(Settings → General → “OpenClaw runs”).
• 앱이 터널을 열고 관리하므로 WebChat + 상태 점검이 “그냥 작동”합니다.

​

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

• 다른 머신에서 노트북으로 SSH 터널을 열거나
• Tailscale Serve로 Control UI를 노출하고 Gateway는 loopback 전용으로 유지합니다.

​

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

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

• Node는 gateway 서비스를 실행하지 않습니다. 의도적으로 격리된 profile을 실행하는 경우가 아니라면 호스트당 gateway는 하나만 실행해야 합니다(Multiple gateways 참조).
• macOS 앱의 “node mode”는 Gateway WebSocket을 통한 node 클라이언트일 뿐입니다.

​

SSH 터널(CLI + 도구)

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, openclaw gateway health, openclaw gateway probe, openclaw gateway call도 필요할 때 --url로 포워딩된 URL을 대상으로 사용할 수 있습니다.

​

CLI 원격 기본값

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

​

자격 증명 우선순위

• 명시적 자격 증명(--token, --password, 또는 도구 gatewayToken)은 명시적 auth를 허용하는 call 경로에서 항상 우선합니다.
• URL 재정의 안전 규칙:
  • CLI URL 재정의(--url)는 암묵적인 config/env 자격 증명을 절대 재사용하지 않습니다.
  • Env URL 재정의(OPENCLAW_GATEWAY_URL)는 env 자격 증명만 사용할 수 있습니다(OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• 로컬 모드 기본값:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (원격 fallback은 로컬 auth token 입력이 설정되지 않은 경우에만 적용)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (원격 fallback은 로컬 auth password 입력이 설정되지 않은 경우에만 적용)
• 원격 모드 기본값:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Node-host 로컬 모드 예외: gateway.remote.token / gateway.remote.password는 무시됩니다.
• 원격 probe/status 토큰 검사는 기본적으로 엄격합니다. 원격 모드를 대상으로 할 때는 gateway.remote.token만 사용합니다(로컬 토큰 fallback 없음).
• Gateway env 재정의는 OPENCLAW_GATEWAY_*만 사용합니다.

​

SSH를 통한 채팅 UI

• SSH로 18789를 포워딩한 다음(위 참조), 클라이언트를 ws://127.0.0.1:18789에 연결하세요.
• macOS에서는 앱의 “Remote over SSH” 모드를 사용하는 것이 좋습니다. 이 모드는 터널을 자동으로 관리합니다.

​

macOS 앱 “Remote over SSH”

​

보안 규칙(원격/VPN)

• Loopback + SSH/Tailscale Serve가 가장 안전한 기본값입니다(공개 노출 없음).
• 평문 ws://는 기본적으로 loopback 전용입니다. 신뢰할 수 있는 사설 네트워크에서는 비상 우회용으로 클라이언트 프로세스에 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1을 설정하세요.
• 비-loopback 바인딩(lan/tailnet/custom, 또는 loopback을 사용할 수 없을 때의 auto)은 gateway auth를 사용해야 합니다: token, password 또는 gateway.auth.mode: "trusted-proxy"를 사용하는 identity-aware 리버스 프록시.
• gateway.remote.token / .password는 클라이언트 자격 증명 소스입니다. 이것만으로 서버 auth를 구성하지는 않습니다.
• 로컬 call 경로는 gateway.auth.*가 설정되지 않은 경우에만 gateway.remote.*를 fallback으로 사용할 수 있습니다.
• gateway.auth.token / gateway.auth.password가 SecretRef로 명시적으로 구성되어 있는데 확인되지 않으면, 해상은 안전하게 실패합니다(원격 fallback이 이를 가리지 않음).
• gateway.remote.tlsFingerprint는 wss:// 사용 시 원격 TLS 인증서를 pinning합니다.
• Tailscale Serve는 gateway.auth.allowTailscale: true일 때 identity 헤더를 통해 Control UI/WebSocket 트래픽을 인증할 수 있습니다. HTTP API 엔드포인트는 이 Tailscale 헤더 auth를 사용하지 않으며 대신 gateway의 일반 HTTP auth 모드를 따릅니다. 이 토큰 없는 흐름은 gateway 호스트가 신뢰된다는 것을 전제로 합니다. 어디서나 공유 시크릿 auth를 원한다면 이를 false로 설정하세요.
• Trusted-proxy auth는 비-loopback identity-aware 프록시 설정 전용입니다. 동일 호스트의 loopback 리버스 프록시는 gateway.auth.mode: "trusted-proxy" 조건을 충족하지 않습니다.
• browser 제어는 운영자 액세스처럼 취급하세요: tailnet 전용 + 의도적인 node 페어링.

​

macOS: LaunchAgent를 통한 영구 SSH 터널

​

1단계: SSH config 추가

Host remote-gateway
    HostName <REMOTE_IP>
    User <REMOTE_USER>
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

​

2단계: SSH 키 복사(1회)

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

​

3단계: gateway 토큰 구성

openclaw config set gateway.remote.token "<your-token>"

​

4단계: LaunchAgent 생성

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

​

5단계: LaunchAgent 로드

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

​

문제 해결

ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel