뒤로가기
Openclaw-Series

04. OpenClaw Gateway 핵심 개념 해설

OpenClaw Gateway의 핵심 아키텍처를 깊이 이해합니다. 본 문서는 Session 세션 모델, Message Router 메시지 라우팅, Tool Registry 도구 등록, Skills 스킬 시스템, WebSocket 프로토콜 등 핵심 개념을 상세히 해설하여, 개발자가 고급 설정과 문제 해결 능력을 갖추도록 돕습니다.

OpenClaw v2026.2 적용 | 본 문서는 기본 설정을 마쳤고, 아키텍처를 깊이 이해하고 싶은 사용자에게 적합합니다. 먼저 앞선 3편 튜토리얼을 완료할 것을 권장합니다.

TL;DR: Gateway는 OpenClaw의 핵심 제어 평면입니다. Session은 대화 컨텍스트 컨테이너(main/channel/group)이고, Message Router는 메시지 라우팅을 결정하며, Tool Registry는 도구 권한을 관리하고, Skills는 사전 패키지된 기능 확장입니다. WebSocket 엔드포인트 ws://127.0.0.1:18789/ws, 자주 쓰는 명령어 openclaw gateway/doctor/config. 이 개념들을 이해하는 것이 고급 설정의 기초입니다.

아키텍처 개요

전체 아키텍처

flowchart TB
    subgraph Clients["클라이언트 계층"]
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WC[WebChat]
        CLI[CLI]
        MAC[macOS App]
        IOS[iOS Node]
        AND[Android Node]
    end
    
    subgraph Gateway["Gateway 계층"]
        WS[WebSocket 서버]
        HTTP[HTTP 서버]
        MR[메시지 라우터]
        SM[세션 매니저]
        TR[도구 레지스트리]
        EM[이벤트 매니저]
        CFG[설정 저장소]
    end
    
    subgraph Agent["Agent 계층"]
        PI[Pi Agent]
        PROMPT[프롬프트 엔진]
        TOOLS[도구 실행기]
        SKILLS[스킬 매니저]
    end
    
    subgraph External["외부 서비스"]
        FS[파일 시스템]
        BR[브라우저]
        API[API 서비스]
        DB[데이터베이스]
        CAL[Cron 스케줄러]
    end
    
    Clients --> WS
    Clients --> HTTP
    WS --> MR
    HTTP --> MR
    MR --> SM
    SM --> PI
    PI --> PROMPT
    PI --> TOOLS
    PI --> SKILLS
    TOOLS --> TR
    TR --> External
    EM --> MR
    CFG --> SM
    CFG --> TR

컴포넌트 역할

컴포넌트 역할 핵심 기능
WebSocket 서버 클라이언트 연결 관리 연결 유지, 헬스체크, 메시지 송수신
HTTP 서버 REST API 및 정적 리소스 Web UI, 헬스체크, 설정 인터페이스
메시지 라우터 메시지 라우팅·분배 채널 식별, 세션 매핑, 메시지 전달
세션 매니저 세션 생명주기 관리 생성, 복구, 압축, 정리
도구 레지스트리 도구 등록 및 호출 도구 발견, 권한 제어, 실행 샌드박스
이벤트 매니저 이벤트 분배·구독 Webhook, Cron, 내부 이벤트
설정 저장소 설정 영속화 핫 업데이트, 버전 관리, 백업·복구

데이터 흐름

sequenceDiagram
    participant U as 사용자
    participant C as Channel
    participant WS as WebSocket
    participant MR as Router
    participant SM as Session
    participant A as Agent
    participant T as Tools
    
    U->>C: 메시지 전송
    C->>WS: 메시지 푸시
    WS->>MR: 라우팅 요청
    MR->>SM: 세션 조회/생성
    SM-->>MR: 세션 반환
    MR->>A: 메시지 전달
    A->>A: 메시지 처리
    A->>T: 도구 호출(선택)
    T-->>A: 결과 반환
    A-->>MR: 응답 생성
    MR->>WS: 응답 전송
    WS->>C: 응답 푸시
    C-->>U: 메시지 표시

Session 세션 모델

Session이란?

Session은 OpenClaw의 핵심 개념 중 하나입니다. 각 Session은 독립적인 대화 컨텍스트를 나타내며, 다음을 포함합니다:

구성 요소 설명
메시지 기록 전체 대화 기록
컨텍스트 상태 현재 작업, 임시 변수
설정 모델, 사고 수준, 샌드박스 설정
메타데이터 생성 시간, Token 통계, 연결 채널

Session 유형

{
  "sessions": {
    "main": {
      "type": "main",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "high",
      "channel": null,
      "created": "2026-02-26T10:00:00Z"
    },
    "telegram:user:123456789": {
      "type": "channel",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "normal",
      "channel": "telegram",
      "sender": "123456789",
      "created": "2026-02-26T10:05:00Z"
    },
    "telegram:group:-100123456789": {
      "type": "group",
      "model": "anthropic/claude-sonnet-4",
      "thinkingLevel": "minimal",
      "channel": "telegram",
      "groupId": "-100123456789",
      "created": "2026-02-26T10:10:00Z"
    }
  }
}
유형 Session ID 형식 설명
main main 기본 메인 세션, CLI 및 WebChat 사용
channel {channel}:user:{senderId} 1:1 대화 세션, 채널·사용자별 격리
group {channel}:group:{groupId} 그룹 세션, 그룹별 격리

Session 생명주기

stateDiagram-v2
    [*] --> Created: 메시지 도착
    Created --> Active: 첫 응답
    Active --> Active: 메시지 교환
    Active --> Idle: 활동 없음
    Idle --> Active: 새 메시지
    Idle --> Compacted: 자동 압축
    Compacted --> Active: 대화 계속
    Active --> Reset: /reset 명령
    Reset --> Created: 새로 시작
    Active --> Pruned: 세션 정리
    Idle --> Pruned: 타임아웃 정리
    Pruned --> [*]

Session 명령어

채팅에서 다음 명령어로 세션을 관리합니다:

명령어 기능 예시
/status 세션 상태 확인 모델, Token, 비용 표시
/new 또는 /reset 세션 초기화 기록 삭제, 새 대화 시작
/compact 컨텍스트 압축 기록 요약, Token 해제
/think <level> 사고 수준 설정 /think high
/verbose on/off 상세 모드 토글 도구 호출 표시/숨김
/usage off/tokens/full 사용량 표시 /usage full

Session 설정

{
  "sessionPruning": {
    "enabled": true,
    "maxAge": 86400000,
    "maxSize": 100,
    "pruneOnStartup": true
  },
  "sessionCompression": {
    "enabled": true,
    "threshold": 50000,
    "targetRatio": 0.3
  }
}
설정 항목 설명 기본값
maxAge 세션 최대 유지 시간(밀리초) 24시간
maxSize 최대 메시지 수 100개
threshold 압축 임계값(Token) 50000
targetRatio 압축 목표 비율 30%

Message Router 메시지 라우팅

라우팅 규칙

Message Router는 수신 메시지를 올바른 Session으로 라우팅합니다:

flowchart TB
    MSG[메시지 도착] --> CH{채널 유형?}
    CH -->|1:1 대화| DM[발신자 ID 추출]
    CH -->|그룹 대화| GRP[그룹 ID 추출]
    CH -->|WebChat/CLI| MAIN[main 세션 사용]
    
    DM --> SID[Session: channel:user:id]
    GRP --> GID[Session: channel:group:id]
    
    SID --> EXISTS{세션 존재?}
    GID --> EXISTS
    
    EXISTS -->|예| LOAD[세션 로드]
    EXISTS -->|아니오| CREATE[새 세션 생성]
    
    CREATE --> LOAD
    LOAD --> AGENT[Agent에 전달]

라우팅 설정

{
  "messageRouting": {
    "defaultSession": "main",
    "channelMapping": {
      "telegram": {
        "userPrefix": "telegram:user",
        "groupPrefix": "telegram:group"
      },
      "whatsapp": {
        "userPrefix": "whatsapp:user",
        "groupPrefix": "whatsapp:group"
      }
    },
    "groupActivation": {
      "mode": "mention",
      "mentionPatterns": ["@bot", "/bot"]
    }
  }
}

그룹 활성화 전략

모드 설명 적용 시나리오
mention @멘션 시에만 응답 활성 그룹, 간섭 감소
always 모든 메시지에 응답 전용 업무 그룹
keyword 키워드 포함 시 응답 특정 주제 그룹 
{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-100WORKGROUP": {
          "requireMention": false,
          "activationMode": "always"
        }
      }
    }
  }
}

Tool Registry 도구 등록

내장 도구

OpenClaw는 다양한 도구를 내장합니다:

도구 분류 도구 이름 기능
파일 작업 read 파일 읽기
write 파일 쓰기
edit 파일 편집
명령 실행 bash Shell 명령 실행
process 프로세스 관리
브라우저 browser 브라우저 제어
검색 web_search 웹 검색
노드 camera 카메라 작업
screen_record 화면 녹화
notify 알림 발송
세션 sessions_list 세션 목록
sessions_history 세션 기록
sessions_send 세션 간 메시지
캔버스 canvas 캔버스 작업

도구 권한 제어

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off",
        "allowlist": ["read", "write", "bash", "web_search"],
        "denylist": []
      }
    }
  }
}
샌드박스 모드 설명
off 모든 도구 사용 가능(main 세션만)
non-main main이 아닌 세션에서 샌드박스 활성화
always 모든 세션에서 샌드박스 활성화

샌드박스 설정 상세

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": [
          "read",
          "write",
          "edit",
          "bash",
          "web_search",
          "sessions_list",
          "sessions_history"
        ],
        "denylist": [
          "browser",
          "canvas",
          "camera",
          "screen_record"
        ]
      }
    }
  }
}

Skills 스킬 시스템

Skills 아키텍처

flowchart LR
    subgraph Skills["Skills 디렉터리"]
        S1[gmail/SKILL.md]
        S2[calendar/SKILL.md]
        S3[home-assistant/SKILL.md]
    end
    
    subgraph Manager["스킬 매니저"]
        DISC[발견]
        LOAD[로드]
        EXEC[실행]
    end
    
    subgraph Agent["Agent"]
        PROMPT[프롬프트 주입]
        TOOLS[도구 등록]
        RES[결과 반환]
    end
    
    Skills --> DISC
    DISC --> LOAD
    LOAD --> PROMPT
    LOAD --> TOOLS
    PROMPT --> Agent
    TOOLS --> Agent
    Agent --> EXEC
    EXEC --> RES

Skills 디렉터리 구조

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md          # 스킬 정의
│   ├── package.json      # 의존성(선택)
│   └── src/
│       └── index.js      # 구현(선택)
├── calendar/
│   └── SKILL.md
└── my-custom-skill/
    └── SKILL.md

SKILL.md 구조

# Gmail Skill

## Description
Send and read Gmail messages through OpenClaw.

## Triggers
- email
- gmail
- mail
- send email
- read email

## Instructions
When the user wants to send an email:
1. Ask for recipient, subject, and body
2. Use the gmail_send tool
3. Confirm the email was sent

When the user wants to check emails:
1. Use the gmail_list tool
2. Summarize the results

## Tools
- gmail_list: List recent emails
- gmail_send: Send an email
- gmail_read: Read a specific email

## Examples
User: "Check my email"
Action: Use gmail_list tool

User: "Send an email to [email protected]"
Action: Ask for subject and body, then use gmail_send

Skills 설치 방식

# ClawHub에서 설치
openclaw skill install gmail

# GitHub에서 설치
openclaw skill install github:user/repo/skill-name

# 수동 설치
git clone https://github.com/user/skill-repo.git ~/.openclaw/workspace/skills/skill-name

Skills 설정

{
  "skills": {
    "bundled": true,
    "managed": true,
    "workspace": true,
    "installGating": true
  }
}
설정 항목 설명
bundled 내장 스킬 활성화
managed ClawHub 관리 스킬 활성화
workspace 로컬 작업 공간 스킬 활성화
installGating 설치 전 확인 필요

WebSocket 프로토콜

연결 엔드포인트

ws://127.0.0.1:18789/ws

메시지 형식

{
  "type": "message_type",
  "id": "unique_message_id",
  "data": {
    // 메시지 내용
  }
}

클라이언트 메시지 유형

유형 설명 예시
agent.send 메시지 전송 Agent와 대화
session.list 세션 목록 세션 관리
session.get 세션 상세 조회 세션 확인
session.patch 세션 설정 수정 모델 변경
config.get 설정 조회 설정 읽기
config.set 설정 변경 설정 업데이트

서버 메시지 유형

유형 설명
agent.response Agent 응답
agent.thinking 사고 과정(스트리밍)
tool.invoked 도구 호출
tool.result 도구 결과
session.created 세션 생성
session.reset 세션 초기화
error 오류 정보

예시: 메시지 전송

// WebSocket 연결
const ws = new WebSocket('ws://127.0.0.1:18789/ws');

// 메시지 전송
ws.send(JSON.stringify({
  type: 'agent.send',
  id: 'msg-001',
  data: {
    session: 'main',
    message: '안녕, 자기소개 해줘'
  }
}));

// 응답 수신
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
  
  // 출력 예:
  // {
  //   type: 'agent.response',
  //   id: 'msg-001',
  //   data: {
  //     content: '안녕하세요! 저는 OpenClaw 어시스턴트입니다...',
  //     session: 'main'
  //   }
  // }
};

Event System 이벤트 시스템

내장 이벤트

이벤트 발생 시점
message.received 사용자 메시지 수신
message.sent 응답 메시지 전송
session.created 새 세션 생성
session.reset 세션 초기화
tool.invoked 도구 호출
tool.completed 도구 실행 완료
agent.thinking Agent 사고 중
error.occurred 오류 발생

Webhook 설정

{
  "webhooks": [
    {
      "url": "https://your-server.com/webhook/openclaw",
      "events": ["message.received", "tool.invoked"],
      "secret": "your_webhook_secret",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  ]
}

Webhook 페이로드

{
  "event": "message.received",
  "timestamp": "2026-02-26T10:30:00Z",
  "data": {
    "channel": "telegram",
    "sender": "123456789",
    "session": "telegram:user:123456789",
    "message": "안녕",
    "metadata": {
      "messageId": "msg_abc123",
      "timestamp": "2026-02-26T10:30:00Z"
    }
  },
  "signature": "sha256=..."
}

Cron 예약 작업

설정 예시

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "오늘 일정 알려줘",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "이번 주 업무 요약 생성해줘",
      "enabled": true
    }
  ]
}

Cron 표현식

┌───────────── 분 (0 - 59)
│ ┌───────────── 시 (0 - 23)
│ │ ┌───────────── 일 (1 - 31)
│ │ │ ┌───────────── 월 (1 - 12)
│ │ │ │ ┌───────────── 요일 (0 - 6, 0 = 일요일)
│ │ │ │ │
* * * * *

자주 쓰는 예시

표현식 설명
0 9 * * * 매일 9:00
0 18 * * 1-5 평일 18:00
*/30 * * * * 30분마다
0 0 1 * * 매월 1일 0:00

설정 계층과 우선순위

우선순위 순서

CLI 인자 > 환경 변수 > 설정 파일 > 기본값

설정 출처

출처 위치 우선순위
CLI 인자 명령줄 인자 최상
환경 변수 OPENCLAW_* 높음
설정 파일 ~/.openclaw/openclaw.json 중간
기본값 코드 내장 최하

설정 병합 예시

// ~/.openclaw/openclaw.json
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

# 환경 변수로 덮어쓰기
export OPENCLAW_AGENT_MODEL="anthropic/claude-sonnet-4"

# CLI 인자로 덮어쓰기(최우선)
openclaw gateway --model "anthropic/claude-opus-4"

설정 핫 업데이트

# 설정 업데이트(재시작 없음)
openclaw config set agent.model "anthropic/claude-sonnet-4"

# 설정 파일 재로드
openclaw config reload

# 설정 검증
openclaw config get agent.model

자주 쓰는 명령어 요약

Gateway 관리

# Gateway 시작
openclaw gateway

# 포트 지정
openclaw gateway --port 18790

# 백그라운드 실행
openclaw gateway --daemon

# 상세 로그
openclaw gateway --verbose

# 헬스체크
openclaw health

세션 관리

# 모든 세션 목록
openclaw session list

# 세션 상세 조회
openclaw session show main
openclaw session show telegram:user:123456789

# 세션 초기화
openclaw session reset main

# 세션 삭제
openclaw session delete telegram:user:123456789

설정 관리

# 설정 조회
openclaw config get agent.model
openclaw config get channels.telegram.botToken

# 설정 변경
openclaw config set agent.thinkingLevel high

# 모든 설정 목록
openclaw config list

# 설정 검증
openclaw config validate

진단 도구

# 전체 진단
openclaw doctor

# 특정 항목 확인
openclaw doctor --check gateway
openclaw doctor --check config
openclaw doctor --check channels

# 로그 확인
openclaw logs
openclaw logs --follow
openclaw logs --level error

문제 해결

Gateway 시작 실패

# 포트 사용 확인
lsof -i :18789
netstat -tlnp | grep 18789

# 설정 문법 확인
openclaw config validate

# 상세 오류 확인
openclaw gateway --verbose 2>&1 | tee gateway.log

세션 손실

# 세션 디렉터리 확인
ls -la ~/.openclaw/sessions/

# 정리 설정 확인
openclaw config get sessionPruning

# 자동 정리 비활성화
openclaw config set sessionPruning.enabled false

도구 호출 실패

# 샌드박스 설정 확인
openclaw config get agents.defaults.sandbox

# 임시 샌드박스 비활성화
openclaw config set agents.defaults.sandbox.mode off

# 도구 로그 확인
openclaw logs --filter tool

WebSocket 연결 실패

# Gateway 상태 확인
curl http://127.0.0.1:18789/health

# WebSocket 엔드포인트 확인
wscat -c ws://127.0.0.1:18789/ws

# 방화벽 확인
sudo ufw status
sudo iptables -L -n | grep 18789

요약

Gateway 핵심 개념을 이해하는 것이 OpenClaw를 잘 다루는 핵심입니다:

  • Session: 대화 컨텍스트 컨테이너, 유형별 격리 지원
  • Message Router: 메시지 라우팅의 핵심, 메시지 경로 결정
  • Tool Registry: 도구 등록 센터, Agent 능력 제어
  • Skills: 스킬 확장 시스템, 기능 빠르게 확장
  • WebSocket: 실시간 통신 프로토콜, 사용자 정의 클라이언트 지원
  • Event System: 이벤트 분배 메커니즘, Webhook 및 Cron 지원

이 개념들은 이후 글에서도 계속 등장하므로, 이해를 깊게 하면 OpenClaw 설정과 사용에 도움이 됩니다.

본 편 요약:

  • Gateway 전체 아키텍처와 컴포넌트 역할 파악
  • Session 세션 모델과 생명주기 이해
  • 메시지 라우팅과 그룹 활성화 전략 학습
  • 도구 권한과 샌드박스 설정 이해
  • WebSocket 프로토콜과 이벤트 시스템 파악

업데이트 기록:

  • 2026-02-26: 초판 발행, OpenClaw v2026.2 기준

시리즈 네비게이션: