OpenClaw Gateway 게이트웨이 설정 완벽 가이드

서문

OpenClaw을 처음 접하신 분이라면, 다양한 채팅 애플리케이션과 AI 모델을 어떻게 연결하는지 궁금하실 수 있습니다. 그 답은 바로 핵심 컴포넌트인 Gateway(게이트웨이)에 있습니다. 공식 문서에서는 OpenClaw을 "채팅 앱과 프로그래밍 에이전트를 연결하는 Gateway 네트워크"로 정의하고 있으며, Gateway가 바로 이 네트워크의 허브입니다.

이 글에서는 Gateway의 핵심 개념부터 시작하여 설정 방법, 시작 매개변수, 실제 사용 시 중요한 설정을 상세히 설명합니다.

Gateway란?

Gateway는 OpenClaw의 핵심 아키텍처 레이어로, 모든 메시지의 수신, 라우팅, 전달이 이를 통해 이루어집니다. 일종의 "메시지 중계소"로 이해하시면 됩니다:

채팅 앱(WhatsApp / Telegram / Discord / ...)
        ↕
   OpenClaw Gateway(단일 프로세스, 멀티 채널)
        ↕
   AI 모델(Claude / GPT / Ollama / ...)

Gateway의 설계 철학은 단일 프로세스, 멀티 채널입니다. 하나의 Gateway 프로세스만 시작하면 모든 채팅 채널의 연결을 동시에 관리할 수 있습니다. 이는 배포가 간단하고, 리소스 사용량이 적으면서도 유연한 확장이 가능하다는 것을 의미합니다.

설정 파일 위치

Gateway 설정은 OpenClaw의 메인 설정 파일에 작성합니다. 기본 경로는 다음과 같습니다:

플랫폼	경로
Linux / macOS	`~/.config/openclaw/openclaw.json5`
Windows	`%USERPROFILE%\.config\openclaw\openclaw.json5`
Docker	`/app/config/openclaw.json5`

환경 변수를 통해 경로를 커스터마이징할 수도 있습니다:

export OPENCLAW_CONFIG=/path/to/your/openclaw.json5

Gateway 핵심 설정

설정 파일의 gateway 섹션을 편집합니다. 다음은 전체 설정 예시입니다:

{
  gateway: {
    // 수신 포트, 기본값 18789
    port: 18789,

    // 수신 주소
    // "127.0.0.1" — 로컬에서만 접근 가능(개발 환경 권장)
    // "0.0.0.0" — 모든 네트워크 접근 허용(프로덕션 환경에서는 방화벽 필수)
    host: "0.0.0.0",

    // Dashboard 접근 비밀번호
    dashboardPassword: "your-strong-password",

    // API 키(외부 시스템에서 OpenClaw API 호출 시 사용)
    apiKey: "your-api-key",

    // 요청 타임아웃(밀리초), 기본 120초
    timeout: 120000,

    // 최대 요청 본문 크기, 미디어 파일 업로드 상한 제어
    maxBodySize: "10mb",

    // CORS 크로스 오리진 설정
    cors: {
      enabled: true,
      origins: ["*"],
    },
  },
}

매개변수 빠른 참조표

매개변수	타입	기본값	설명
`port`	number	18789	Gateway 수신 포트
`host`	string	"127.0.0.1"	수신 주소
`dashboardPassword`	string	없음	Dashboard 로그인 비밀번호
`apiKey`	string	없음	API 인증 키
`timeout`	number	120000	요청 타임아웃(ms)
`maxBodySize`	string	"10mb"	최대 요청 본문 크기

Gateway 시작

설정 완료 후 다음 명령어로 Gateway를 시작합니다:

openclaw gateway --port 18789

설정 파일에 이미 포트가 지정되어 있다면, 간단한 명령어로도 시작할 수 있습니다:

openclaw up

백그라운드 실행:

openclaw up -d

시작 후 Gateway는 지정된 포트에서 수신을 시작하고, 활성화된 모든 채널에 자동으로 연결됩니다.

접근 제어

프로덕션 환경에서 접근 제어는 매우 중요합니다. OpenClaw은 다층 보안 메커니즘을 제공합니다.

IP 화이트리스트와 블랙리스트

security 설정 섹션으로 접근 가능한 IP 주소를 제한합니다:

{
  security: {
    // 다음 IP만 접근 허용(비어 있으면 제한 없음)
    ipWhitelist: [
      "192.168.1.0/24",
      "10.0.0.5",
    ],

    // 특정 IP 차단
    ipBlacklist: [
      "203.0.113.50",
    ],

    // 요청 속도 제한
    rateLimit: {
      enabled: true,
      maxRequests: 60,
      windowMs: 60000,
    },
  },
}

채널 수준의 사용자 제한

각 채널별로 허용할 사용자나 그룹을 개별 설정할 수 있습니다. Telegram을 예로 들면:

{
  channels: {
    telegram: {
      enabled: true,
      token: "your-bot-token",
      // 이 사용자 ID만 허용
      allowedUsers: [12345678, 87654321],
      // 이 그룹만 허용
      allowedGroups: [-100123456789],
    },
  },
}

이러한 이중 제어(Gateway 수준 + 채널 수준)를 통해 AI 서비스에 대한 접근을 세밀하게 관리할 수 있습니다.

멀티 채널 라우팅

Gateway의 대표적인 특징은 플러그인 방식의 채널 확장입니다. 각 채팅 플랫폼과의 연동은 독립적인 채널 플러그인이며, Gateway가 이를 통합 관리하고 메시지를 라우팅합니다.

{
  channels: {
    whatsapp: {
      enabled: true,
      phoneNumber: "+86138xxxx",
      responseMode: "all",
    },

    telegram: {
      enabled: true,
      token: "your-bot-token",
      responseMode: "mention",
    },

    discord: {
      enabled: true,
      token: "your-discord-token",
      responseMode: "mention",
      allowedChannels: ["general", "ai-chat"],
    },
  },
}

각 채널마다 다른 응답 모드를 설정할 수 있습니다:

"all": 모든 메시지에 응답
"mention": @멘션된 경우에만 응답

멀티 Agent 라우팅과 세션 격리

여러 AI 모델을 설정한 경우, Gateway는 규칙 기반의 멀티 Agent 라우팅을 지원합니다. 서로 다른 채널을 서로 다른 모델로 라우팅할 수 있으며, 각 채널의 대화 컨텍스트는 기본적으로 서로 격리됩니다.

{
  context: {
    // 격리 정책
    // "channel" — 채널별 격리(기본값, 권장)
    // "user" — 사용자별 격리(같은 사용자가 채널 간 컨텍스트 공유)
    // "global" — 전역 공유
    isolation: "channel",

    // 컨텍스트 윈도우 크기
    maxMessages: 50,

    // 컨텍스트 만료 시간(초)
    ttl: 3600,
  },
}

세션 격리 메커니즘을 통해 서로 다른 채널 간의 대화가 상호 간섭하지 않습니다. 예를 들어, Telegram의 대화가 Discord로 유출되지 않으며 그 반대도 마찬가지입니다.

미디어 지원

Gateway는 이미지, 오디오, 문서 등 다양한 미디어 타입을 기본 지원합니다. 사용자가 채팅에서 이미지를 보내면, Gateway가 이를 비전 기능을 지원하는 모델로 전달하여 처리합니다.

maxBodySize 매개변수를 조정하여 업로드 파일 크기 상한을 제어할 수 있습니다:

{
  gateway: {
    // 대용량 파일 처리가 필요한 경우 적절히 높일 수 있습니다
    maxBodySize: "25mb",
  },
}

웹 대시보드

Gateway에는 웹 Dashboard가 내장되어 있어 브라우저에서 서비스를 모니터링하고 관리할 수 있습니다:

openclaw dashboard

Dashboard는 다음 기능을 제공합니다:

각 채널의 실시간 연결 상태 확인
메시지 송수신 통계 모니터링
모델 호출 횟수 및 Token 소비량 확인
실시간 로그 스트림 조회

Dashboard에 접근할 때 dashboardPassword에 설정한 비밀번호를 입력해야 합니다. 비밀번호를 설정하지 않았다면 프로덕션 환경에서는 반드시 추가하는 것을 권장합니다.

설정 검증 및 문제 해결

Gateway 설정을 수정한 후에는 먼저 설정 파일이 올바른지 검증하는 것이 좋습니다:

# 진단 실행, 설정 및 각 컴포넌트 상태 검사
openclaw doctor

# 설정 파일 문법만 검증
openclaw doctor --config-only

Gateway 시작 후 문제가 발생하면 로그를 확인하여 문제를 해결할 수 있습니다:

# 실시간 로그 조회
openclaw logs

# 특정 채널 로그 조회
openclaw logs --channel telegram

요약

Gateway는 OpenClaw의 핵심 허브로, 그 작동 방식을 이해하면 AI 채팅 서비스를 더 효과적으로 배포하고 관리할 수 있습니다. 핵심 포인트를 정리하면:

단일 프로세스 멀티 채널: 하나의 Gateway 프로세스로 모든 채팅 플랫폼 연결을 관리
설정 집중화: 모든 설정을 openclaw.json5에서 통합 관리
계층적 보안: Gateway 수준 + 채널 수준의 이중 접근 제어
세션 격리: 멀티 채널 간 대화 컨텍스트가 기본적으로 독립적
플러그인 확장: 플러그인 메커니즘으로 새로운 채팅 플랫폼을 유연하게 연동

최소한의 설정부터 시작하여 먼저 하나의 채널을 연결한 후, 점진적으로 더 많은 채널과 고급 설정을 추가하는 것을 권장합니다.