내 PC/서버에 직접 설치해 텔레그램·디스코드로 제어하는 셀프호스팅 AI 에이전트 플랫폼입니다.
외부 서버 없이 로컬 환경에서 Claude, GPT 등 LLM을 연결해 나만의 AI 직원을 구성할 수 있습니다.
봇이 갑자기 응답을 멈췄을 때, 과연 어느 지점에서 문제가 생긴 것인지 막막했던 경험이 있으신가요? 이 막막함의 근본 원인은 대부분 시스템 내부 구조를 모른 채 사용하기 때문입니다. 구조를 알면 문제의 원인이 보이고, 해결책도 훨씬 빠르게 찾을 수 있습니다.
이번 13편에서는 openclaw 아키텍처를 구성하는 Gateway·Node·Client 세 계층의 역할과 통신 원리를 처음부터 끝까지 해설합니다. 이 구조를 이해하면 알 수 없는 에러에 당황하지 않고 스스로 원인을 좁혀가는 진정한 AI 에이전트 운영자로 거듭날 수 있습니다.
지난 편(이전: 채널별 권한·allowlist 설정 — 누가 AI를 쓸 수 있게 할까)에서는 내가 허락한 사람만 AI를 쓸 수 있도록 통제하는 채널 보안과 allowlist 설정법을 완성했습니다. 이제 그 보안이 적용된 시스템이 내부에서 어떻게 작동하는지 살펴볼 차례입니다.
OpenClaw 3대 핵심 요소 — Gateway, Node, Client의 역할
OpenClaw는 하나의 거대한 통짜 프로그램이 아닙니다. 크게 세 가지 독립적인 구성 요소가 유기적으로 통신하며 작동하는 현대적인 분산 구조를 가지고 있습니다. 이 세 계층의 역할을 명확히 구분하는 것이 openclaw 아키텍처 이해의 첫걸음입니다.
세 계층의 역할 한눈에 보기
- Gateway (게이트웨이): 시스템의 관문이자 모든 통신을 지휘하는 통제소 역할을 합니다. 외부에서 들어오는 모든 메시지를 받아 적절한 에이전트 노드로 라우팅하고, 권한을 검증하며, 각 채널(텔레그램, 디스코드 등)과의 연결을 유지합니다.
- Node (노드/Agent): 실제 AI 모델과 결합하여 생각하고 작업을 수행하는 실무자입니다. 게이트웨이로부터 메시지를 전달받아 LLM(대규모 언어 모델)을 호출하고, 스킬(Skills)을 활용해 실질적인 자동화 작업을 처리한 뒤 결과를 반환합니다.
- Client (클라이언트): 우리가 직접 눈으로 보고 명령을 입력하는 인터페이스입니다. 웹 UI, 텔레그램·디스코드 등 메신저 앱, 또는 CLI가 모두 클라이언트에 해당합니다. 클라이언트는 Gateway와 통신하며 사용자의 입력을 전달하고 AI의 응답을 수신합니다.
📎 OpenClaw 공식 문서 원문 보기 →
Gateway 완전 해설 — 모든 트래픽의 중앙 통제 타워
게이트웨이는 OpenClaw 시스템의 심장입니다. 기본적으로 18789번 포트를 통해 외부 및 내부의 요청을 수신하며, 시스템 전체의 트래픽을 지휘합니다. 게이트웨이가 멈추면 연결된 모든 채널과 클라이언트도 함께 작동을 멈추기 때문에, 안정적인 게이트웨이 운영이 전체 시스템 가용성의 핵심입니다.
Gateway의 핵심 기능 3가지
- 인증 및 권한 검증:
openclaw.json의auth.token을 통해 접속자의 권한을 엄격하게 검증합니다. 유효하지 않은 토큰으로의 접근은 즉시 차단됩니다. - 채널 라우팅: 텔레그램·디스코드·왓츠앱 등 여러 채널에서 동시에 들어오는 메시지를 수신하고, 설정에 따라 적절한 에이전트 노드에게 전달합니다.
- 바인딩 보안 설정: 클라우드 서버(VPS)에 구축한 셀프호스팅 AI의 경우, 게이트웨이의 바인딩을
"bind": "loopback"으로 설정하면 외부 인터넷에서 직접 게이트웨이 포트에 접근하는 것을 차단할 수 있습니다. 이것이 아키텍처 보안의 핵심 설정입니다.
Node와 Agent — 실제 '일'을 처리하는 손발
게이트웨이가 메시지를 배달해 주면, 실제 작업은 Node(노드)에서 구동되는 에이전트가 처리합니다. 노드는 OpenClaw 아키텍처에서 "두뇌"에 해당하는 요소로, AI 모델과의 실제 연산이 이곳에서 이루어집니다.
Node의 두 가지 핵심 구성 요소
- Provider (프로바이더): 에이전트가 사용할 AI 모델을 지정하는 설정입니다. Anthropic(Claude), OpenAI(GPT), Google(Gemini) 등 다양한 LLM 제공사와 연결하여 각 노드마다 다른 모델을 사용하도록 구성할 수 있습니다.
- Skills (스킬): 에이전트가 실제로 수행할 수 있는 능력의 목록입니다. 웹 브라우저 제어, 로컬 파일 읽기/쓰기, 코드 실행, 외부 API 호출 등 에이전트가 사용할 수 있는 도구(Tool)들이 여기에 등록됩니다.
시스템 구조상 하나의 게이트웨이 아래에 각기 다른 역할을 하는 여러 개의 에이전트 노드를 병렬로 운영할 수 있습니다. 예를 들어 복잡한 업무를 처리하는 메인 에이전트(고성능 모델)와 단순 상태 체크만 하는 경량 에이전트(저비용 모델)를 분리해 게이트웨이 하나에서 통합 관리하는 구성이 가능합니다.
auth.token)과 분리된 remote.token을 사용합니다. 만약 원격 토큰이 유출되더라도 해당 토큰만 독립적으로 폐기할 수 있어 시스템 전체 보안을 유지할 수 있습니다.아키텍처 상태 확인 및 진단 명령어
훌륭한 openclaw 사용법의 기본은 내 서버 아키텍처의 상태를 정확히 모니터링하는 것입니다. 아래 명령어 두 가지를 터미널에서 실행하면 Gateway와 Node의 연결 상태를 종합적으로 확인하고 진단할 수 있습니다.
# 현재 게이트웨이, 채널, 스킬 등 전체 아키텍처의 실행 상태 확인
openclaw status
# 아키텍처 내 설정 파일 오류, 종속성 누락, 포트 충돌 여부 종합 진단
openclaw doctor
두 명령어의 역할 차이
openclaw status: 현재 실행 중인 게이트웨이, 연결된 채널, 활성화된 노드와 스킬의 상태를 실시간으로 출력합니다. "지금 이 순간" 무엇이 살아있고 무엇이 죽어있는지 파악하는 데 사용합니다.openclaw doctor: 설정 파일의 문법 오류, 필수 종속성 누락, 포트 충돌, API 키 누락 여부 등을 종합적으로 스캔하여 잠재적인 문제를 미리 진단합니다. 시스템이 이상하게 느껴질 때 가장 먼저 실행해야 할 명령어입니다.
openclaw status로 현재 실행 상태를, openclaw doctor로 잠재적 설정 오류를 진단합니다. 문제가 생기면 항상 이 두 명령어를 먼저 실행해 Gateway·Node·Client 중 어느 계층이 원인인지 확인하세요.
실전 팁과 주의사항
- 문제 발생 시 계층별로 원인을 좁혀라: "봇이 응답 안 해요" 같은 증상이 생기면, Client(메신저 API 상태) → Gateway(포트·토큰 오류) → Node(LLM API 키·모델 오류) 순으로 계층을 차례로 점검하면 대부분의 문제를 빠르게 해결할 수 있습니다.
- VPS 배포 시 bind를 반드시 loopback으로 설정: 클라우드 서버에 게이트웨이를 운영할 때
"bind": "loopback"을 설정하지 않으면 게이트웨이 포트(기본 18789)가 인터넷에 노출되어 무단 접근 위험이 생깁니다. - remote.token은 auth.token과 반드시 분리 발급: 스마트폰 앱 등 원격 클라이언트용 토큰은 마스터 토큰(
auth.token)과 별도로 관리해야 합니다. 원격 토큰이 유출돼도 마스터 권한은 안전하게 유지됩니다. - 여러 노드는 역할별로 분리 운영이 유리: 하나의 게이트웨이 아래 고성능·고비용 모델 노드와 가벼운 경량 노드를 분리 운영하면 비용 효율을 극대화하면서도 다양한 자동화 시나리오를 처리할 수 있습니다.
자주 묻는 질문 (FAQ)
- 코딩을 잘 모르는 입문자인데 아키텍처 구조까지 굳이 알아야 하나요?
- 꼭 알아두시기를 권장합니다. 예를 들어 "디스코드 봇이 응답하지 않아요"라는 문제가 생겼을 때, Client(디스코드 API) 문제인지, Gateway(포트·토큰 오류) 문제인지, Node(LLM API 키 오류) 문제인지 스스로 원인을 좁힐 수 있다면 해결 시간이 몇 배 빨라집니다. 구조를 아는 것만으로도 이 시리즈의 내용을 200% 활용할 수 있게 됩니다.
- Gateway 서버가 꺼지면 텔레그램이나 왓츠앱 봇도 같이 죽나요?
- 그렇습니다. Gateway가 모든 메신저(Client) 채널과의 네트워크 통신을 담당하기 때문에, Gateway 프로세스가 재시작되거나 중단되면 외부 메신저에서도 봇이 즉시 응답을 멈춥니다. 클라우드 배포 시에는 반드시 데몬 또는 서비스 매니저를 통해 자동 재시작을 설정하세요.
- 하나의 Gateway에 여러 개의 Node(에이전트)를 연결해서 사용할 수 있나요?
- 물론입니다. OpenClaw 아키텍처의 가장 강력한 장점 중 하나가 바로 이 유연성입니다. 메인 업무를 처리하는 고성능 에이전트 노드와, 단순 백그라운드 체크를 수행하는 경량 노드를 분리하여 하나의 게이트웨이에서 통합 관리하는 구성이 가능합니다.
- 스마트폰 앱이나 외부 클라이언트에서 접속할 때 보안은 어떻게 유지되나요?
- 외부 원격 클라이언트는
remote.token이라는 별도의 전용 인증 키를 통해 게이트웨이와 안전하게 통신합니다. 마스터 권한(auth.token)과 원격 클라이언트 권한을 분리 발급하므로, 토큰이 유출되더라도 원격 기기의 접근 권한만 단독으로 회수할 수 있어 아키텍처 전반의 보안이 유지됩니다.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
openclaw 아키텍처 구조에서 궁금한 점은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
'OpenClaw' 카테고리의 다른 글
| [openclaw 완전 가이드] 12편 openclaw 채널 보안 — 권한 통제 및 allowlist 설정으로 안전한 AI 에이전트 만들기 (0) | 2026.03.31 |
|---|---|
| [openclaw 완전 가이드] 11편 openclaw 멀티채널 — 하나의 게이트웨이로 여러 메신저 동시 운영하기 (0) | 2026.03.31 |
| [openclaw 완전 가이드] 10편 Mattermost·Teams 채널 연결 — 기업 메신저 연동 가이드 (1) | 2026.03.31 |
| [openclaw 완전 가이드] 9편 Signal·Slack 연결 — 보안·업무 채널을 위한 AI 에이전트 설정법 (0) | 2026.03.30 |
| [openclaw 완전 가이드] 8편 WhatsApp + OpenClaw QR 페어링 (0) | 2026.03.30 |
댓글