← Gritz World Engine
pillar

OpenClaw 게이트웨이 채널 연동 및 에이전트 상호운용성 가이드

핵심 요약

OpenClaw 게이트웨이는 다양한 외부 메시징 채널을 정규화된 형식으로 통합하고, 접근 제어 정책으로 필터링하며, ACP 런타임을 통해 Codex나 Claude Code와 같은 외부 에이전트와의 상호운용성을 제공한다. 이를 통해 통신 효율성과 보안이 동시에 향상된다.

이 글의 핵심 주장과 근거

핵심 주장
OpenClaw 는 sessions_spawn 을 통해 runtime='acp' 모드로 Codex, Claude Code 등 외부 ACP(Agent Communication Protocol) 에이전트와 상호운용성을 지원하며, thread-bound persistent 세션 생성과 서브에이전트 오케스트레이션 기능을 제공한다
출처: [1] OpenClaw Session Recovery Mechanisms
핵심 주장
OpenClaw Gateway 는 Telegram, Discord, Slack, Signal, WhatsApp, iMessage, Matrix, Feishu 등 다양한 외부 메시징 플랫폼으로부터 들어오는 메시지를 수신하여 정규화된 공통 형식으로 변환한 후 접근 제어 정책을 통해 필터링한다
출처: [1] OpenClaw Documentation
핵심 주장
OpenClaw 채널 연동은 openclaw onboard --install-daemon 으로 데몬 서비스를 설치한 후, openclaw channels login 명령어로 WhatsApp Web QR 코드를 스캔하는 방식으로 설정하며, Gateway 는 서비스로 실행된 후에도 수동 실행이 가능하다
출처: [1] OpenClaw Session Recovery Mechanisms
OpenClaw 는 sessions_send 를 통해 다른 세션이나 서브에이전트 간 크로스-메시징을 지원하며, sessionKey 또는 label 로 타겟을 식별하고 agentId 와 timeoutSeconds 파라미터로 에이전트 실행 제어가 가능하다
출처: [1] OpenClaw Documentation
OpenClaw Gateway 는 단일 장기 실행 Node.js 프로세스로 모든 통신과 오케스트레이션을 관리하며, 포그라운드 개발 모드(openclaw gateway) 와 대시몬 프로덕션 모드(openclaw gateway --daemon), 커스텀 포트 설정(--port 19000) 을 지원한다
출처: [1] Claude Code GAV Feedback Loop
OpenClaw Gateway(기본 포트 18789)는 OpenAI 호환 HTTP API 엔드포인트인 POST /v1/chat/completions를 외부에 노출하며, Authorization: Bearer 토큰 인증과 Content-Type: text/event-stream 기반 스트리밍 응답을 지원한다. 이 API 구조를 통해 LMStudio, Open WebUI 등 외부 클라이언트가 OpenClaw 에이전트에 직접 연결할 수 있다.
출처: [1] OpenClaw Gateway API 문서
Gateway 프로세스 트리 내부에서 exec 도구로 gateway restart를 실행하면 gateway가 조용히 종료되고 launchd 등록이 해제되는 문제가 있어, 바이브코딩 세션의 연속성이 단절될 수 있다
출처: [1] OpenClaw Gateway Restart Issue
OpenClaw Gateway는 사용자의 로컬 머신 또는 서버에서 단일 프로세스로 실행되며, WhatsApp, Telegram, Discord, iMessage 등 다수의 메시징 앱과 AI 코딩 에이전트(Pi 등)를 실시간으로 연결하는 self-hosted 브릿지 역할을 한다.
출처: [1] OpenClaw Documentation
OpenClaw CLI는 session-target(main/isolated/current) 옵션으로 실행 환경을 지정할 수 있어, 메인 세션에서 장기 프로젝트를 관리하거나 격리된 세션에서 단일 태스크를 수행하거나 현재 활성 세션을 전환하는 등 용도에 따른 유연한 세션 관리가 가능하다. Gateway가 모든 세션 상태를 소유·관리하므로 연결된 클라이언트는 지속적인 컨텍스트를 유지할 수 있다.
출처: [1] OpenClaw 세션 아키텍처 문서

채널 연동 아키텍처 개요

OpenClaw 게이트웨이는 Telegram, Discord, Slack, Signal, WhatsApp, iMessage, Matrix, Feishu 등 8개 이상의 외부 메시징 플랫폼으로부터 다양한 형태의 메시지를 수신한다. 이 메시지는 내부적으로 JSON 구조로 정규화되어 통일된 포맷으로 변환되고, 접근 제어 정책을 통해 허용된 채널·발신자·키워드만 처리하도록 필터링된다. 이를 통해 시스템은 모든 플랫폼에 일관된 응답 흐름을 제공하고, 보안과 프라이버시를 동시에 강화한다.

게이트웨이 코어 구조와 실행 모드

OpenClaw 게이트웨이는 단일 장기 실행 Node.js 프로세스로, 모든 통신·오케스트레이션을 담당한다. 개발 단계에서는 openclaw gateway 명령을 사용해 프론트엔드 모드로 실행하고, 생산 환경에서는 openclaw gateway --daemon 또는 --port 19000 옵션으로 백그라운드 서비스로 전환한다. 서비스 설정은 openclaw onboard --install-daemon 으로 시스템 초기화 스크립트를 생성하고, 필요 시 수동으로 재시작할 수 있다. 이러한 구조는 장애 격리 및 자동 복구 기능을 내재하고 있어 높은 가용성을 보장한다.

ACP 기반 에이전트 상호운용성

OpenClaw는 sessions_spawn을 runtime='acp'와 thread:true 옵션으로 실행해 Codex, Claude Code, Pi 등 외부 ACP(Agent Communication Protocol) 에이전트와 연동한다. 이 경우 세션은 스레드-바운드.persistent하게 유지되며, 다른 세션에 메시지를 전달할 때는 sessions_send(sessionKey, message)를 사용한다. 서브에이전트는 자동으로 오케스트레이션되어 특정 작업이나 검증 흐름을 수행하고, 결과는 다시 메인 세션으로 반환된다. 이를 통해 코드 작성·리뷰·배포 과정을 통합적으로 관리한다.

보안 및 접근 제어 정책

Gateway는 사전 정의된 규칙 집합을 기반으로 메시지 허용·차단 대상을 결정한다. rule은 플랫폼 아이디, 발신자 ID, 키워드 패턴, 시간대 등을 포함하며, 관리 인터페이스를 통해 동적으로 수정 가능하다. 인증은 OAuth2 또는 토큰 기반 시스템을 사용해 접근 권한을 검증하고, 모든 작업은 로그로 기록되어 감사 가능하도록 설계되었다. 이러한 정책은 데이터 유출 방지와 불법적 활용을 예방하는 데 핵심적인 역할을 한다.

자주 묻는 질문

OpenClaw 게이트웨이의 채널 연동 설정 단계는 무엇인가요?

먼저 openclaw onboard --install-daemon 명령으로 서비스를 설치하고, openclaw channels login 명령어로 WhatsApp Web QR 코드를 스캔하여 인증하면 됩니다. 이후 서비스가 자동 실행되며 백그라운드에서 메시지를 수신합니다.

ACP 런타임을 사용해 외부 코딩 에이전트를 어떻게 연결하나요?

sessions_spawn을 runtime='acp'와 thread:true 옵션으로 실행하면 됩니다. 이 경우 세션은 스레드-바운드.persistent하게 유지되며, 다른 세션에 메시지를 전달할 때는 sessions_send를 사용해 요청을 전송할 수 있습니다.

메시지 필터링 정책은 어떻게 정의하고 적용하나요?

Gateway는 사전 정의된 규칙 집합을 기반으로 메시지 허용·차단 대상을 결정한다. rule은 플랫폼 아이디, 발신자 ID, 키워드 패턴, 시간대 등을 포함하며, 관리 인터페이스를 통해 동적으로 수정 가능하다. 인증은 OAuth2 또는 토큰 기반 시스템을 사용해 접근 권한을 검증하고, 모든 작업은 로그로 기록되어 감사 가능하도록 설계되었다.