1부·3장 아키텍처 한눈에 보기
OpenClaw를 처음 보면 살짝 헷갈립니다. 메신저도 있고, 웹 UI도 있고, 스킬도 있고, 파일도 많습니다. 얼핏 보면 부품이 너무 많은 것처럼 느껴지죠. 그런데 구조를 한 번만 제대로 잡아두면, 그다음부터는 설치도 훨씬 쉬워지고 커스터마이징도 외우는 일이 아니라 이해하는 일이 됩니다.
이 장의 목표는 단순합니다. OpenClaw를 "명령어 모음"이 아니라 "하나의 운영 구조"로 보게 만드는 것입니다. 오늘 머릿속에 넣어둘 핵심 그림은 이것입니다.
OpenClaw는 하나의 중심 허브가 메시지를 받고, 에이전트 런타임이 생각하고, 도구가 손발이 되어 움직이고, 스킬이 그 손발을 잘 쓰는 요령을 가르치며, 워크스페이스 파일이 성격과 기억을 붙들어 줍니다.12
OpenClaw를 한 문장으로 그리면
가장 쉬운 비유는 이렇습니다. OpenClaw는 "메신저 속 AI"가 아니라 "메신저를 입구로 쓰는 개인용 AI 운영체제"입니다. 텔레그램, 왓츠앱, 슬랙 같은 채널은 현관문이고, Gateway는 건물 로비 데스크이며, Agent Runtime은 실제로 일을 처리하는 사무실입니다. Tools는 책상 위 장비이고, Skills는 직원 교육 매뉴얼입니다. 그리고 워크스페이스 파일은 이 사무실의 문화, 규칙, 메모장, 일정표에 해당합니다.
이 비유만 기억해도 구조가 훨씬 편해집니다. 사용자는 메신저에서 말을 걸지만, 실제로는 뒤에서 여러 층의 시스템이 협업하고 있는 셈입니다.
전체 구조: Hub-and-Spoke로 이해하기
OpenClaw의 기본 철학은 중앙 허브 하나가 여러 연결점을 관리하는 방식입니다. 흔히 Hub-and-Spoke 구조라고 부릅니다. 바퀴를 떠올리면 쉽습니다. 가운데 허브가 있고, 바깥으로 여러 개의 살이 뻗어 있죠.
여기서 허브는 Gateway입니다. 그리고 살처럼 바깥으로 연결되는 것이 Telegram, WhatsApp, Slack, Discord 같은 Channels입니다. 사용자는 어느 채널에서 말을 걸든 결국 중앙의 Gateway로 메시지가 모입니다. Gateway는 그 메시지를 적절한 세션으로 연결하고, Agent Runtime에게 "이제 생각할 차례야"라고 넘깁니다.13
이 구조의 장점은 아주 현실적입니다. 채널이 달라도 두뇌는 하나라는 점입니다. 텔레그램에서는 일정 정리를 하고, 디스코드에서는 서버 알림을 받고, 웹 UI에서는 설정을 바꾸더라도, 뒤에서 움직이는 에이전트의 성격과 기억은 같은 워크스페이스를 공유할 수 있습니다.
즉, 인터페이스는 여러 개지만 정체성은 하나입니다. 그래서 OpenClaw를 "챗봇 여러 개"가 아니라 "하나의 디지털 분신이 여러 창구로 말하는 구조"라고 이해하는 편이 정확합니다.
Gateway: 모든 길이 모이는 중앙 허브
Gateway는 OpenClaw 아키텍처의 심장에 가장 가까운 부품입니다. 항상 켜져 있으면서 채널 연결, 제어 요청, 상태 확인, 이벤트 전달을 맡습니다. 공식 문서도 Gateway를 장수명 단일 프로세스로 설명합니다. 쉽게 말해, 계속 살아 있으면서 모든 대화를 접수하는 접수실입니다.23
Gateway가 하는 일은 크게 세 가지입니다.
여러 메시지 채널과 연결을 유지합니다.
CLI, 웹 UI, 앱 같은 제어면 클라이언트의 요청을 받습니다.
에이전트 실행 요청을 Agent Runtime으로 넘기고 결과를 다시 라우팅합니다.
여기서 중요한 설계 포인트는 "보통 한 호스트에 Gateway 하나"라는 원칙입니다. 특히 WhatsApp처럼 세션을 하나가 대표로 잡아야 하는 채널은 이 구조가 단순함과 안정성을 줍니다.23
왜 이게 중요할까요? 설치 초반에 많은 사람이 "왜 여러 프로세스로 쪼개지 않았지?"라고 묻습니다. 하지만 개인용, 소규모 팀용 AI 운영에서는 복잡한 분산 구조보다 단일 Gateway가 훨씬 다루기 쉽습니다. 장애 지점도 적고, 디버깅도 쉽고, 무엇보다 내 머리도 덜 아픕니다.
Agent Runtime: 실제로 생각하고 행동하는 두뇌
Gateway가 접수실이라면, Agent Runtime은 실제 실무자입니다. 사용자의 메시지를 읽고, 어떤 맥락이 필요한지 모으고, 어떤 모델을 부를지 결정하고, 도구를 실행하고, 최종 답을 만듭니다.14
이 런타임은 단순히 "모델 API 한 번 호출하는 래퍼"가 아닙니다. OpenClaw가 에이전트처럼 느껴지는 이유는 바로 여기서 만들어집니다. Agent Runtime은 매 라운드마다 대략 이런 순서로 움직입니다.
사용자 메시지를 받습니다. 그다음 워크스페이스 파일과 메모리, 세션 기록, 사용 가능한 도구 설명을 한데 모아 지금 필요한 문맥을 조립합니다. 그 문맥을 모델에게 넘기고, 모델이 도구 호출을 요청하면 실제 도구를 실행합니다. 결과를 다시 모델에 넣고, 필요한 경우 이 과정을 몇 번 더 반복한 뒤 최종 응답을 채널로 되돌려 보냅니다.14
이 흐름을 알고 나면 OpenClaw의 많은 현상이 설명됩니다. 왜 SOUL.md를 고치면 말투가 바뀌는지, 왜 MEMORY.md를 정리하면 답변이 달라지는지, 왜 스킬을 추가하면 갑자기 특정 업무를 더 잘하는지 모두 이 컨텍스트 조립 단계 때문입니다. 설치만 해서는 빈 사무실이지만, 워크스페이스와 스킬을 채우면 점점 유능한 운영체제가 됩니다.
Channels: 메신저는 얼굴이고, Gateway는 목소리다
Channels는 OpenClaw가 세상과 만나는 창구입니다. Telegram, WhatsApp, Slack, Discord, Signal, WebChat 같은 표면이 여기에 들어갑니다.3
중요한 점은 채널이 곧 두뇌가 아니라는 것입니다. 텔레그램 봇을 하나 만들었다고 해서 그 텔레그램 안에 지능이 들어 있는 게 아닙니다. 지능은 Agent Runtime에 있고, 채널은 그 지능을 불러내는 전화기 같은 존재입니다.
이 구분을 이해하면 운영 감각이 좋아집니다. 예를 들어 텔레그램에서 응답이 이상하다고 해서 문제의 원인이 늘 텔레그램에 있는 것은 아닙니다. Gateway 연결 문제일 수도 있고, 모델 설정 문제일 수도 있고, 워크스페이스 문맥 문제일 수도 있습니다. 반대로 채널을 바꿔도 같은 워크스페이스를 쓰면 에이전트의 성격과 기억은 대체로 유지됩니다.
한마디로 말해, 채널은 입이고 런타임은 뇌입니다. 입을 바꿔도 사람 자체가 바뀌는 건 아닙니다.
Tools와 Skills: 손발과 매뉴얼의 차이
초보자가 가장 많이 헷갈리는 부분이 바로 Tools와 Skills입니다. 둘 다 뭔가 "기능 추가"처럼 보이기 때문입니다. 하지만 역할은 꽤 다릅니다.
Tools는 에이전트가 실제로 할 수 있는 기본 능력입니다. 파일 읽기, 파일 쓰기, 셸 명령 실행, 웹 검색, 웹 페이지 가져오기, 메시지 전송, 세션 생성 같은 것이 여기에 들어갑니다.56
반면 Skills는 그 도구를 어떤 순서와 맥락으로 써야 하는지 알려주는 작업 지침입니다. 요리로 치면 Tools는 칼, 냄비, 가스레인지이고, Skills는 "김치볶음밥 만드는 법"입니다. 칼만 있다고 요리가 저절로 되지 않듯, 도구만 있다고 좋은 업무 자동화가 되진 않습니다. 반대로 레시피만 있고 칼이 없으면 할 줄 알아도 실행을 못 합니다.
이 구분은 나중에 커스텀 스킬을 만들 때 엄청 중요해집니다. 스킬은 새로운 초능력을 발명하는 것이 아니라, 이미 가진 능력을 더 똑똑하게 조합하는 일인 경우가 많습니다. 그래서 좋은 스킬은 장황하지 않고, 어떤 상황에서 어떤 도구를 왜 쓰는지를 명확하게 알려줍니다.5
워크스페이스: 에이전트가 사는 집
OpenClaw 공식 문서는 워크스페이스를 에이전트의 집이라고 설명합니다. 이 표현이 아주 정확합니다. 워크스페이스는 파일 도구의 기본 작업 디렉터리이자, 에이전트가 자기 정체성과 기억을 읽어오는 장소입니다.6
중요한 점은 워크스페이스와 ~/.openclaw/가 다르다는 것입니다. 워크스페이스는 성격, 규칙, 사용자 정보, 메모리처럼 "에이전트의 뇌와 습관"이 들어 있는 곳입니다. 반면 ~/.openclaw/ 아래에는 설정, 인증 정보, 세션 데이터, 관리형 스킬처럼 엔진룸에 가까운 정보가 들어갑니다.6
이 차이를 모르면 나중에 백업과 보안에서 사고가 납니다. 워크스페이스는 개인 비서의 노트와 매뉴얼이니 비공개 Git 저장소로 백업할 만합니다. 하지만 자격 증명과 토큰이 들어 있는 엔진룸은 절대 같은 방식으로 퉁쳐서 공개 저장소에 올리면 안 됩니다.
워크스페이스 파일 5종: 성격, 규칙, 사용자, 기억, 심장박동
이 장의 핵심은 파일 하나하나를 외우는 것이 아니라, "누가 어떤 역할을 맡는가"를 잡는 데 있습니다. 우선 가장 자주 만나게 될 다섯 파일부터 보겠습니다.
SOUL.md: 이 에이전트는 어떤 존재인가
SOUL.md는 에이전트의 말투, 가치관, 태도, 경계선을 정하는 파일입니다. 쉽게 말해 성격 파일입니다. 정중한지, 직설적인지, 과장된 립서비스를 싫어하는지, 의견을 말해도 되는지 같은 것이 여기에 들어갑니다.67
같은 모델을 써도 SOUL.md가 다르면 완전히 다른 동료처럼 느껴집니다. 이 파일이 없으면 OpenClaw는 대체로 무난하지만 밋밋한 조수에 머물고, 잘 쓰면 "아, 얘는 내 방식으로 일하는구나"라는 감각이 생깁니다.
AGENTS.md: 어떻게 일해야 하는가
AGENTS.md는 운영 규칙 파일입니다. 어떤 상황에서 바로 행동하고, 어떤 상황에서 사람 승인을 받아야 하며, 무엇을 우선순위로 두고, 어떤 내용을 메모리에 남길지를 적는 곳입니다.67
SOUL.md가 성격이라면 AGENTS.md는 업무 매뉴얼입니다. "친절하라"는 SOUL의 영역이고, "파괴적 명령은 항상 승인받아라"는 AGENTS의 영역입니다.
USER.md: 누구를 위해 일하는가
USER.md는 사용자의 기본 맥락입니다. 이름, 호칭, 시간대, 기술 수준, 선호하는 설명 방식, 일정 감각 같은 것이 여기에 들어갑니다.67
이 파일이 있으면 에이전트는 매번 사용자를 처음 보는 사람처럼 굴지 않습니다. 예를 들어 당신이 한국 시간 기준으로 움직이고, 터미널은 익숙하지만 리눅스 내부 구조는 약하다는 사실을 알고 있으면 설명 수준이 훨씬 맞아집니다.
MEMORY.md: 오래 기억할 것들
MEMORY.md는 장기 기억에 가깝습니다. 자주 바뀌지 않는 사실, 중요한 선호, 반복되는 의사결정 기준 같은 것을 담아두는 곳입니다. 공식 문서 계열 자료에서는 이 파일을 메인 프라이빗 세션에서만 로드하는 장기 기억으로 설명합니다.16
즉, 하루짜리 잡생각이 아니라 "이 사람은 메시지를 짧게 받는 걸 좋아함", "주요 프로젝트 우선순위는 A > B > C", "회의 요약은 항상 액션 아이템부터" 같은 내용을 두는 편이 좋습니다.
HEARTBEAT.md: 먼저 움직이는 습관
HEARTBEAT.md는 능동적 행동의 체크리스트입니다. 매일 아침 브리핑, 주기적 상태 확인, 일정한 시간의 알림 같은 작업을 짧게 적어 둡니다.6
중요한 포인트는 길게 쓰지 않는 것입니다. Heartbeat는 자주 읽히기 때문에 장황하면 토큰을 태우고, 에이전트도 괜히 분주해집니다. 심장박동은 규칙적이어야지, 북소리처럼 요란하면 안 됩니다.
daily memory와 MEMORY.md는 왜 분리될까
OpenClaw는 기억도 층을 나눠서 다룹니다. memory/YYYY-MM-DD.md 같은 일일 로그는 최근 작업 기억에 가깝고, MEMORY.md는 오래 남길 큐레이션된 장기 기억에 가깝습니다.16
이 분리는 아주 실용적입니다. 오늘 회의에서 나온 임시 아이디어, 버그 조사 메모, 잠깐의 할 일은 일일 로그로 흘려보내고, 몇 주 뒤에도 계속 중요할 정보만 MEMORY.md로 끌어올리면 됩니다. 사람도 메모장을 다 외우지 않듯, 에이전트도 모든 기록을 같은 무게로 들고 다니면 둔해집니다.
여기서 감각적인 기준은 이렇습니다. "내일이면 잊어도 되는가?" 그렇다면 일일 로그입니다. "다음 달에도 이 사실을 알아야 하나?" 그렇다면 MEMORY.md 후보입니다.
메시지 하나가 흘러가는 실제 경로
이제 구조를 한 번 연결해 봅시다. 사용자가 텔레그램에서 "오늘 해야 할 일 정리해줘"라고 보냈다고 가정해보겠습니다.
먼저 Telegram 채널 어댑터가 메시지를 받습니다. 그 메시지는 Gateway로 들어갑니다. Gateway는 이 메시지가 어느 세션에 속하는지 확인하고, Agent Runtime에게 처리를 넘깁니다. Runtime은 SOUL.md, AGENTS.md, USER.md, MEMORY.md, 최근 메모리, 대화 기록, 사용 가능한 스킬과 도구 설명을 모아 현재 라운드의 문맥을 구성합니다. 그다음 모델을 호출합니다. 모델이 캘린더 조회나 메모 검색 같은 도구 사용이 필요하다고 판단하면 Runtime이 도구를 실행합니다. 결과가 돌아오면 모델이 최종 답을 만듭니다. 마지막으로 Gateway가 그 답을 다시 텔레그램으로 전달합니다.134
겉으로는 내가 메신저에 한 줄 보냈을 뿐이지만, 실제로는 꽤 많은 계층이 협업합니다. 이걸 이해하면 문제를 볼 때도 덜 막막합니다. 답변이 이상하면 "모델이 멍청한가?"만 볼 게 아니라, 문맥 파일이 잘못됐는지, 스킬이 과한지, 도구 권한이 비어 있는지, 채널 연결이 꼬였는지를 차례대로 볼 수 있습니다.
18789 포트와 18793 포트는 무엇을 뜻할까
설치 자료를 보다 보면 18789와 18793이 자주 보입니다. 처음엔 암호 같지만, 역할만 알면 별것 아닙니다.
기준이 되는 포트는 18789입니다. 최신 공식 runbook 기준으로 이 포트는 Gateway의 메인 멀티플렉스 포트입니다. WebSocket 제어 연결, HTTP API, OpenAI 호환 엔드포인트, 제어 UI와 훅이 모두 여기로 모입니다.2
쉽게 말해 18789는 "정문"입니다. CLI도, 웹 대시보드도, 일부 연동도 대개 이 포트와 이야기합니다.
그런데 자료를 찾다 보면 18793을 Canvas 호스트 포트로 설명하는 문서나 커뮤니티 글도 만납니다.89 이것은 시점과 배포 설명 차이에서 오는 혼란으로 보는 편이 좋습니다. 어떤 설명에서는 Canvas를 별도 호스트처럼 그렸고, 최신 공식 문서에서는 Gateway의 HTTP 서버 아래 경로로 제공한다고 정리합니다.23
실전 감각으로 정리하면 이렇습니다. 일단 설치와 점검은 18789를 중심으로 생각하면 됩니다. 그리고 18793이 보이더라도 "아, Canvas 관련 표면을 별도 포트로 설명한 자료구나" 정도로 이해하면 됩니다. 중요한 것은 숫자 암기가 아니라, Gateway가 WebSocket과 HTTP 표면을 함께 품고 있다는 구조입니다.
Canvas와 Nodes: 텍스트 밖으로 손을 뻗는 구조
OpenClaw는 텍스트만 주고받는 존재로 끝나지 않으려는 설계를 가지고 있습니다. 공식 아키텍처 문서에는 Gateway HTTP 서버 아래의 Canvas 경로와, 별도 역할로 연결되는 Nodes 개념이 등장합니다.3
Canvas는 에이전트가 보여줄 수 있는 웹 UI 표면입니다. 단순한 채팅 답변 대신 표, 카드, 간단한 대시보드, 미니 UI를 띄우는 방향으로 확장할 수 있습니다. Nodes는 카메라, 화면, 위치 같은 디바이스 능력을 가진 연결 대상입니다.3
이 장에서는 깊게 파고들지 않겠지만, 큰 그림 차원에서 꼭 알아둘 점이 하나 있습니다. OpenClaw는 "채팅 답변기"가 아니라 "메시지 기반 제어 OS"에 더 가깝다는 사실입니다. 그래서 아키텍처도 처음부터 채널, UI, 디바이스 확장을 품고 있습니다.
왜 이 구조가 설치와 커스터마이징을 쉽게 만드는가
이제 처음 문장으로 돌아가 봅시다. 구조를 알면 설치가 암기가 아니라 이해가 된다고 했습니다. 그 이유는 명확합니다.
설치할 때는 "Gateway를 살아 있게 만든다"는 관점으로 보게 됩니다. 채널 연결은 "입구를 만든다"는 의미가 됩니다. API 키 설정은 "Runtime이 쓸 두뇌 연료를 넣는다"는 작업이 됩니다. SOUL.md와 AGENTS.md를 쓰는 일은 "성격과 업무 규칙을 심는다"는 일로 보입니다. 스킬을 넣는 것은 "새 능력을 추가한다"가 아니라 "도구 사용법을 훈련시킨다"로 이해됩니다.
이렇게 보면 앞으로 배울 모든 실습이 서로 연결됩니다. 2부의 설치는 Gateway와 채널을 붙이는 과정이고, 3부의 워크스페이스 커스터마이징은 Runtime에 성격과 규칙을 먹이는 과정이며, 4부의 스킬 실전은 Tools를 더 영리하게 쓰게 만드는 과정입니다. 그리고 6부의 보안은 이 구조 전체의 위험 지점을 줄이는 일입니다.
초보자가 꼭 기억해야 할 아키텍처 규칙 5가지
처음 OpenClaw를 다룰 때는 다음 다섯 문장만 몸에 붙여도 충분합니다.
첫째, Gateway는 중앙 허브다. 대부분의 길은 여기로 들어오고 여기서 나간다.
둘째, Agent Runtime은 두뇌다. 실제로 생각하고 도구를 돌리고 응답을 만든다.
셋째, Channels는 입구다. 텔레그램이 곧 에이전트는 아니다.
넷째, Tools는 능력이고 Skills는 사용법이다. 둘을 섞어 생각하면 설계가 흐려진다.
다섯째, 워크스페이스 파일은 에이전트의 성격과 습관이다. 여기를 잘 만져야 "내 AI"가 된다.
마무리: OpenClaw를 기계가 아니라 구조로 보자
OpenClaw를 처음 설치하면 대개 봇 하나가 생긴 것처럼 느껴집니다. 하지만 조금만 들여다보면, 그 안에는 꽤 정교한 운영 구조가 있습니다. 중앙 허브인 Gateway, 생각과 실행을 맡는 Agent Runtime, 여러 채널, 손발이 되는 도구, 행동 패턴을 가르치는 스킬, 그리고 그 모든 것을 한 사람처럼 묶어 주는 워크스페이스 파일들.
이 구조를 이해한 순간부터 OpenClaw는 덜 신비롭고 더 다룰 만한 시스템이 됩니다. 막연히 "잘 되면 좋고 안 되면 어렵다"는 대상이 아니라, 어디를 만지면 어떤 변화가 나는지 읽히는 기계가 됩니다.
다음 장에서는 이 구조를 바탕으로, 과연 누가 OpenClaw와 잘 맞고 누가 그렇지 않은지 더 현실적으로 살펴보겠습니다. 멋져 보여도 아무에게나 맞는 도구는 아니니까요.
참고
1OpenClaw 아키텍처 완전 분석: Gateway에서 Agent Runtime까지 전체 구조 파헤치기
3Gateway Architecture - OpenClaw
4OpenClaw Gateway & Agent Runtime - DeepWiki
7OpenClaw Workspace Files: SOUL.md, AGENTS.md & USER.md (2026)
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.