> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openclaw.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 원격 액세스

# 원격 액세스 (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](/ko-KR/install/exe-dev) (쉬운 VM) 또는 [Hetzner](/ko-KR/install/hetzner) (생산용 VPS).

자주 잠에 드는 노트북에도 에이전트를 항상 켜 두고 싶을 때 이상적입니다.

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

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

* macOS 앱의 **원격 SSH** 모드(Settings → General → “OpenClaw 실행”)를 사용하세요.
* 앱이 터널을 열고 관리하므로, WebChat + 상태 검사가 "그냥 작동합니다."

절차서: [macOS 원격 액세스](/ko-KR/platforms/mac/remote).

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

게이트웨이를 로컬로 유지하되 안전하게 노출합니다:

* 다른 머신에서 노트북으로 SSH 터널을 생성하거나,
* 제어 UI를 Tailscale Serve로 제공하고 게이트웨이를 루프백 전용으로 유지합니다.

가이드: [Tailscale](/ko-KR/gateway/tailscale) 및 [웹 개요](/ko-KR/web).

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

하나의 게이트웨이 서비스가 상태와 채널을 소유합니다. 노드는 주변기기입니다.

흐름 예시 (Telegram → 노드):

* Telegram 메시지가 **게이트웨이**에 도착합니다.
* 게이트웨이가 **에이전트**를 실행하고 노드 도구 호출 여부를 결정합니다.
* 게이트웨이가 게이트웨이 웹소켓을 통해 **노드**를 호출합니다 (`node.*` RPC).
* 노드가 결과를 반환하고, 게이트웨이는 Telegram으로 응답을 보냅니다.

주의사항:

* **노드는 게이트웨이 서비스를 실행하지 않습니다.** 의도적으로 격리된 프로파일을 실행하지 않는 한, 각 호스트 당 하나의 게이트웨이만 실행해야 합니다 ([여러 게이트웨이](/ko-KR/gateway/multiple-gateways) 참조).
* macOS 앱의 "노드 모드"는 단지 게이트웨이 웹소켓을 통한 노드 클라이언트입니다.

## SSH 터널 (CLI + 도구)

원격 게이트웨이 WS에 로컬 터널을 생성합니다:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 명령어가 기본적으로 사용할 수 있도록 원격 대상을 지속적으로 설정할 수 있습니다:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 원격 액세스](/ko-KR/platforms/mac/remote).

## 보안 규칙 (원격/VPN)

요약: **게이트웨이를 루프백 전용으로 유지**하십시오. 바인드가 필요하다고 확신하지 않는 한.

* **루프백 + SSH/Tailscale Serve**는 가장 안전한 기본값입니다 (공개 노출 없음).
* 평문 `ws://`는 기본적으로 루프백 전용입니다. 신뢰된 사설 네트워크에서만 예외적으로 사용할 때는 클라이언트 프로세스에 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`을 설정하십시오.
* **비루프백 바인드**(`lan`/`tailnet`/`custom`, 또는 루프백이 사용 불가능할 때 `auto`)는 인증 토큰/비밀번호를 반드시 사용해야 합니다.
* `gateway.remote.token` / `gateway.remote.password`는 클라이언트 자격 증명 소스입니다. 이것만으로 서버 인증이 구성되지는 않습니다.
* 로컬 호출 경로에서는 `gateway.auth.*`가 비어 있을 때만 `gateway.remote.*`를 폴백으로 사용할 수 있습니다.
* `gateway.auth.token` / `gateway.auth.password`가 SecretRef로 명시적으로 구성되어 있는데 해석되지 않으면, 해석은 fail-closed 됩니다 (remote fallback으로 가리지 않음).
* `gateway.remote.tlsFingerprint`는 `wss://`를 사용할 때 원격 TLS 인증서를 고정합니다.
* **Tailscale Serve**는 `gateway.auth.allowTailscale: true`일 때 신원 헤더를 통해 Control UI/WebSocket 트래픽을 인증할 수 있습니다; HTTP API 엔드포인트는 여전히 토큰/비밀번호 인증이 필요합니다. 이 토큰 없는 흐름은 게이트웨이 호스트가 신뢰할 수 있다고 가정합니다. 어디서나 토큰/비밀번호를 원하면 이를 `false`로 설정하세요.
* 브라우저 제어는 운영자 접근처럼 다루십시오: tailnet 전용 + 의도적인 노드 페어링.

자세히 알아보기: [보안](/ko-KR/gateway/security).