시리즈: OpenClaw AI 에이전트 완전 가이드 (총 9편) | 2편
OpenClaw 아키텍처 완전 해부 — Gateway, Nodes, Skills, Tools 구조
OpenClaw 내부에 Gateway, Nodes, Skills, Tools 네 계층이 있다는데 뭘 하는 건지 궁금하지? 이번 편에서는 공식 소스코드 기반으로 각 구성요소의 역할과 데이터 흐름을 해부하고, 로봇 시스템에서 이 아키텍처가 갖는 의미까지 정리해 봤어.
Summary
- OpenClaw는 Gateway(제어면), Nodes(실행 노드), Skills(작업 템플릿), Tools(실행 능력) 4계층 구조야
- Gateway가 WebSocket 기반으로 세션/채널/도구/이벤트를 통합 관리해
- 로봇 관점에서 이 구조는 "하드웨어 드라이버"가 아니라 "운영 자동화 오케스트레이터"에 최적화돼 있어
이 글의 대상
- OpenClaw의 기술 구조를 이해하고 싶은 개발자
- 에이전트 아키텍처에 관심 있는 SW 엔지니어
- OpenClaw를 자기 프로젝트에 붙여볼까 고민 중인 팀
목차
- 전체 아키텍처 개요
- Gateway — 모든 것의 중심
- Nodes/Agents — 기기에서 실행되는 일꾼들
- Skills — "뭘 할 수 있는지" 결정하는 플러그인
- Tools — 실행 능력 그 자체
- Raspberry Pi 사례로 보는 하드웨어 접근
1. 전체 아키텍처 개요
OpenClaw의 구조를 한 장짜리 다이어그램으로 그리면 이런 계층이 나와:
[사용자/채널] → [Gateway(제어면)] → [Nodes/Agents] → [Skills] → [Tools(실행)]여기서 핵심을 기억해야 해: 이 구조는 "이미 존재하는 도구/시스템을 안전하게 호출"하는 데 최적화돼 있다는 거야. OpenClaw가 직접 모터를 돌리거나 센서를 읽는 게 아니라, 그런 걸 할 수 있는 외부 도구를 연결하고 오케스트레이션하는 거지.
2. Gateway — 모든 것의 중심
Gateway는 OpenClaw의 심장이야. 공식 문서에서는 이걸 "세션과 이벤트, 도구 호출을 통합 관리하는 중심 허브"라고 설명해.
기술적으로 보면:
| 항목 | 상세 |
|---|---|
| 프로토콜 | WebSocket 기반 |
| 기본 주소 | ws://127.0.0.1:18789 |
| 역할 | 세션 관리, 명령 라우팅, 권한 통제, 이벤트 허브 |
| 특징 | 로컬-퍼스트 (클라우드 의존 X) |
Gateway가 하는 일을 쉽게 풀면, "누가 뭘 요청했고, 그걸 어디로 보내고, 결과를 어디로 돌려줄지"를 관리하는 교통 정리반 같은 거야. 메신저에서 들어온 메시지든, CLI에서 날린 명령이든, 전부 Gateway를 거쳐.
3. Nodes/Agents — 기기에서 실행되는 일꾼들
Nodes(또는 Agents)는 실제로 네 기기에서 뭔가를 실행하는 구성요소야. macOS 앱, Raspberry Pi 에이전트 같은 게 여기에 해당해.
각 Node는 권한 기반으로 동작하거든. 어떤 Node는 파일 시스템 접근이 가능하고, 어떤 Node는 네트워크 요청만 할 수 있고 — 이런 식으로 권한을 나눠서 관리해. Gateway가 Node에게 "이거 해"라고 시키면, Node가 자기 권한 범위 안에서 실행하는 구조지.
핵심은, Node가 "독립적인 실행 환경"이라는 거야. 한 대의 맥에서 돌릴 수도 있고, 여러 디바이스에 Node를 깔아서 분산 실행도 가능해. 이게 나중에 로봇 연동할 때 중요해지거든 — Raspberry Pi에 Node를 깔고, 센서/카메라를 붙이는 패턴이 여기서 나오는 거야.
4. Skills — "뭘 할 수 있는지" 결정하는 플러그인
Skills는 OpenClaw의 확장성을 책임지는 핵심 단위야. 외부 API 호출, 로컬 명령 실행, 도구 조합 — 이런 걸 묶어서 하나의 "능력"으로 패키징한 거지.
예를 들면:
- 브라우저 자동화 스킬: 특정 웹사이트에서 정보를 긁어와
- 파일 관리 스킬: 로컬 파일을 읽고 정리해
- 알림 스킬: 센서 값이 임계치를 넘으면 메신저로 알려줘
- ROS 호출 스킬:
ros2 service call /gripper/open을 실행해
스킬은 커뮤니티 레지스트리(ClawHub)를 통해 설치할 수도 있고, 직접 만들 수도 있어. openclaw CLI로 설치/실행/관리가 가능하지. 이 확장 구조 덕분에 OpenClaw가 "범용 자동화 허브"로 기능할 수 있는 거야.
5. Tools — 실행 능력 그 자체
Tools는 Skills보다 한 단계 아래에 있는 "실행 프리미티브"야. Skills가 "무엇을 할지"를 정의한다면, Tools는 "어떻게 실행할지"를 담당하는 거지.
공식 문서에서 확인되는 주요 Tools:
| Tool 종류 | 하는 일 |
|---|---|
exec |
쉘 명령 실행 |
browser |
브라우저 자동화 |
node.invoke |
기기 노드 호출 |
보면 알겠지만, "로컬에서 명령을 실행"하는 능력이 중심이야. 이게 왜 중요하냐면, 이 Tool들이 시스템 권한을 가지고 동작하기 때문이야. exec로 쉘 명령을 실행할 수 있다는 건, 그만큼 강력하면서도 위험하다는 뜻이거든. 6편(보안)에서 이 부분을 깊게 다뤄.
6. Raspberry Pi 사례로 보는 하드웨어 접근
"이론은 알겠는데, 실제로 하드웨어랑 어떻게 연결되는데?"라는 질문에 가장 좋은 답변이 Adafruit의 Raspberry Pi 가이드야.
이 가이드는 Pi 5에서 OpenClaw를 실행하고, TFT 디스플레이, 온도/압력 센서, USB 카메라, NeoPixel LED에 접근시키는 구성을 보여줘. GPIO, I2C, SPI, USB 같은 인터페이스를 통해 주변기기와 연결되는 거지.
하지만 여기서 아주 중요한 포인트가 있어: 이건 로봇 제어에서 가장 어려운 부분(안전한 폐루프 제어, 타이밍 보장, 오류 시 안전 상태 전환)을 해결했다는 뜻이 아니야. Adafruit도 "쉘 접근 가능한 에이전트의 위험"을 강하게 경고하고 있거든.
즉, Pi + OpenClaw로 센서 읽기나 LED 제어는 가능하지만, 모터를 안전하게 구동하려면 별도의 하위 제어기가 필요하다는 거지.
핵심 정리
1. Gateway = WebSocket 기반 제어면, 모든 요청의 허브
2. Nodes = 기기별 실행 환경, 권한 기반 동작
3. Skills = 외부 서비스/명령을 묶은 확장 플러그인
4. Tools = exec/browser/node.invoke 같은 실행 프리미티브
5. 전체 구조는 "제어"보다 "운영 자동화/오케스트레이션"에 최적화FAQ
Q: Gateway가 WebSocket 말고 다른 프로토콜도 지원해?
A. 공식 문서 기준으로는 WebSocket이 주요 제어면 프로토콜로 안내돼 있어. 추가 프로토콜 지원은 릴리즈 노트를 확인해 봐야 하는데, 현재까지는 WS 중심이야.
Q: Skills를 직접 만들 수 있어?
A. 그럼. 공식 스킬 레포(openclaw/skills)에서 구조를 참고해서 커스텀 스킬을 만들 수 있어. CLI로 설치/관리도 되고, 커뮤니티 레지스트리에 공유할 수도 있지.
Q: Node를 여러 기기에 분산 배치할 수 있어?
A. 가능해. 맥에 하나, Pi에 하나 — 이런 식으로 여러 기기에 Node를 깔고, Gateway가 중앙에서 관리하는 구조야. 분산 환경에서 각 기기의 리소스를 활용할 수 있다는 게 장점이지.
Q: exec Tool로 아무 쉘 명령이나 실행할 수 있는 거야?
A. 기술적으로는 그래. 그래서 위험한 거야. 권한 설정을 제대로 안 하면 시스템 전체에 접근할 수 있거든. 6편 보안 편에서 왜 이게 물리 시스템과 만나면 더 위험해지는지 다뤄.
Q: OpenClaw가 지원하는 LLM 모델은 뭐가 있어?
A. Anthropic(Claude), OpenAI(GPT), HuggingFace, Ollama(로컬 LLM), GLM 등 멀티 모델/프로바이더를 지원해. 채널도 WhatsApp, Telegram, Discord, Slack 등 다양하게 연결할 수 있지.
Q: ClawHub가 뭐야?
A. OpenClaw 스킬의 커뮤니티 레지스트리야. 다른 사람들이 만든 스킬을 검색하고 설치할 수 있는 일종의 앱스토어 같은 거지. 직접 만든 스킬을 공유할 수도 있어.
Q: 이 구조가 로봇 제어에 적합한 거야?
A. "직접 제어"에는 적합하지 않아. 하지만 "상위 오케스트레이션" — 예를 들어 "작업 시퀀스 관리, 상태 모니터링, 알람 라우팅" 같은 역할에는 꽤 잘 맞아. 3편에서 ROS와의 통합 패턴을 자세히 다뤄.
참고 자료 (References)
데이터 출처
| 출처 | 설명 | 링크 |
|---|---|---|
| GitHub OpenClaw | 공식 저장소 | GitHub |
| OpenClaw Docs | 공식 문서 | Docs |
| Yale OpenHand | 오픈 그리퍼 레퍼런스 | OpenHand |
| Bitsight | 보안 리스크 분석 | Bitsight |
핵심 인용
"Local-first Gateway — single control plane for sessions, channels, tools, and events."
— OpenClaw GitHub README
다음 편 예고
[3편] OpenClaw와 ROS — 로봇 연동의 현실적인 통합 패턴
- OpenClaw가 ROS를 대체할 수 있는지 직접 따져봐
- 권장 아키텍처 vs 비권장 아키텍처
- 실제 커뮤니티 데모 사례 분석