개요

OpenClaw의 핵심은 **단일 장기 실행 게이트웨이(Single Long-lived Gateway)**이다. 이 게이트웨이 하나가 모든 메시징 채널을 관리한다.

주요 구성 요소

1. Gateway (데몬)

게이트웨이는 백그라운드 데몬으로 실행되며 다음을 담당한다:

  • 프로바이더 연결 유지: AI 모델 프로바이더와의 연결을 지속적으로 관리
  • 타입드 WebSocket API 제공: 모든 통신이 WebSocket을 통해 이루어짐
  • JSON Schema 프레임 검증: 송수신되는 모든 프레임을 JSON Schema로 검증
  • 세션 관리: 에이전트별 세션 생성, 유지, 정리
  • 인증 처리: 토큰 기반 접근 제어

기본 리스닝 주소:

127.0.0.1:18789

2. Clients (클라이언트)

클라이언트는 게이트웨이에 연결하는 제어 평면(Control-plane) 인터페이스이다.

클라이언트설명
macOS 앱메뉴바 앱으로 빠른 접근
CLI터미널 명령어 인터페이스
Web UI브라우저 기반 Control UI

모든 클라이언트는 WebSocket으로 127.0.0.1:18789에 연결한다.

3. Nodes (노드)

노드는 role:node로 연결하는 디바이스이다.

  • iOS/Android 모바일 디바이스
  • 원격 서버
  • IoT 디바이스

노드는 에이전트의 확장 인터페이스로 동작하며 메시지를 수발신한다.

와이어 프로토콜

게이트웨이와 클라이언트 간 통신은 WebSocket/JSON 프로토콜을 사용한다.

연결 흐름

  1. 클라이언트가 WebSocket 연결을 설정
  2. 첫 번째 프레임은 반드시 connect 메시지여야 함
  3. 게이트웨이가 연결을 검증하고 세션을 할당
  4. 이후 양방향 메시지 교환

connect 프레임 예시

{
  "type": "connect",
  "role": "client",
  "token": "<OPENCLAW_GATEWAY_TOKEN>"
}

프레임 검증

모든 프레임은 JSON Schema로 검증된다. 잘못된 형식의 프레임은 거부되며 오류 메시지가 반환된다.

인증

게이트웨이 토큰

게이트웨이 접근은 OPENCLAW_GATEWAY_TOKEN 환경 변수로 제어한다.

export OPENCLAW_GATEWAY_TOKEN="your-secret-token"

토큰이 설정되면 모든 클라이언트와 노드는 연결 시 이 토큰을 제공해야 한다.

로컬 접근

기본적으로 게이트웨이는 127.0.0.1에서만 수신하므로 로컬 머신에서만 접근 가능하다.

원격 접근

외부에서 게이트웨이에 접근해야 하는 경우, 직접 포트를 열지 말고 다음 방법을 사용할 것을 권장한다.

Tailscale (권장)

# Tailscale을 통해 안전하게 원격 접근
tailscale up
# 이후 Tailscale IP로 게이트웨이 접근

SSH 터널링

# 원격 서버의 게이트웨이를 로컬로 포워딩
ssh -L 18789:127.0.0.1:18789 user@remote-server

주의: 게이트웨이 포트를 공용 인터넷에 직접 노출하지 않도록 한다. 반드시 Tailscale이나 SSH 터널링을 사용하여 보안을 유지한다.

아키텍처 다이어그램

┌──────────────────────────────────────────────┐
│                  Gateway                      │
│               127.0.0.1:18789                 │
│                                               │
│  ┌─────────┐  ┌─────────┐  ┌──────────────┐ │
│  │ Provider │  │ Session │  │ Frame        │ │
│  │ Manager  │  │ Manager │  │ Validator    │ │
│  └─────────┘  └─────────┘  └──────────────┘ │
│                                               │
│  ┌─────────────────────────────────────────┐ │
│  │         WebSocket API (JSON)            │ │
│  └─────────────────────────────────────────┘ │
└──────────┬──────────┬──────────┬─────────────┘
           │          │          │
    ┌──────┴──┐ ┌─────┴───┐ ┌───┴──────┐
    │ macOS   │ │  CLI    │ │  Web UI  │
    │  App    │ │         │ │          │
    └─────────┘ └─────────┘ └──────────┘
     (client)    (client)    (client)

           │
    ┌──────┴──────┐
    │  Mobile     │
    │  Node       │
    │ (role:node) │
    └─────────────┘