이 레포가 무엇을 하는 물건인가.
OpenClaw는 "AI 비서 앱"이 아니라 내 기기에서 24시간 돌아가는 비서 본체 + 그 비서를 어디서든 부를 수 있는 연결망이다. 비서는 WhatsApp·텔레그램·슬랙 같은 평소 쓰던 앱으로 답하고, macOS/iOS/안드로이드에서는 목소리로 듣고 말하기까지 한다.
좀 더 풀어보자. 대부분의 AI 비서는 회사 서버(클라우드)에 살고, 우리는 그 집에 손님으로 방문해 대화한다. OpenClaw는 반대다. 비서의 본체(게이트웨이)를 내 컴퓨터에 설치하고, 그 비서가 내가 평소 쓰는 메신저들로 나에게 말을 건다. 그래서 "로컬 우선"이고, 대화·도구 실행·메모리가 기본적으로 내 손 안에 있다.
이름과 분위기가 독특하다. OpenClaw는 Molty(몰티)라는 "우주 바닷가재 AI 비서" 캐릭터를 위해 만들어졌고(🦞 "EXFOLIATE!"는 그 마스코트 밈), iOS 개발자로 유명한 Peter Steinberger(steipete)와 커뮤니티가 함께 만든다. 밈처럼 보이지만 코드베이스는 진지하다 — 수백 개 패키지로 짜인 거대한 모노레포(monorepo)이고, 스폰서에 OpenAI·GitHub·NVIDIA·Vercel이 올라 있다.
트렌딩 이유 · 경쟁 대비 장점.
OpenClaw는 TrendShift 연간 트렌딩 1위(올해 +37만 스타)에 오른, 2026년 오픈소스 폭발의 대표 사례다. 사람들을 끌어들인 건 세 가지다: ① 20여 개 메신저를 하나의 비서로 묶는다, ② 클라우드가 아니라 내 기기에서 돈다, ③ 음성·화면(Canvas)·모바일 앱까지 한 묶음. 여기에 "우주 바닷가재 Molty"라는 강한 밈 정체성이 입소문을 키웠다.
| 비교 축 | 일반적인 AI 비서(클라우드 챗봇) | OpenClaw |
|---|---|---|
| 실행 위치 | 제공사 서버(클라우드) | 내 노트북·서버(로컬 우선) |
| 접점 | 전용 앱/웹 하나 | 이미 쓰는 메신저 20여 종 + 음성 + Canvas |
| 도구 실행 | 제한된 샌드박스 | 호스트에서 bash·브라우저·cron 등 직접(샌드박스 선택) |
| 확장 | 플러그인 마켓(닫힘) | 채널/도구를 plugin-SDK로 직접 작성, 스킬(ClawHub) |
클라우드 챗봇은 보통 전용 앱 안에 갇혀 있다. 친구에게 텔레그램으로 답을 대신 보내거나, 내 노트북의 파일을 직접 정리하거나, 새벽에 cron으로 작업을 돌리는 일은 어렵거나 불가능했다.
게이트웨이가 모든 채널·세션·도구의 교차로 역할을 한다. 한 비서를 텔레그램에서도, 슬랙에서도, 맥 메뉴바에서 음성으로도 부르고, 같은 비서가 내 컴퓨터에서 bash·브라우저·cron을 써서 실제로 일을 한다.
+37만 스타와 밈 화제성은 인기의 신호이지 품질 보증이 아니다. 더구나 OpenClaw는 실제 메신저 + 내 호스트 권한을 다루므로 보안 설정(아래 s4·s7)을 건너뛰면 위험하다. 공부용으로는 최고의 교재지만, 실사용 전엔 보안 문서를 반드시 읽자.
백엔드(게이트웨이)·프론트엔드(앱·UI)·인프라 한눈에.
OpenClaw는 한 언어 한 프레임워크가 아니라 여러 런타임이 한 저장소에 모인 모노레포다. 중심축은 TypeScript(게이트웨이), 양 날개는 Swift(Apple 앱)·Kotlin(안드로이드 앱)이다.
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| 핵심 런타임 | Node.js 24 (또는 22.19+) | 게이트웨이 데몬 실행 환경. ESM("type":"module") 기반. |
| 언어(서버) | TypeScript | 게이트웨이·에이전트·채널·도구의 본체. tsx로 직접 실행, tsdown으로 dist/ 빌드. |
| 채널 어댑터 | grammy(Telegram)·Slack·Discord·Matrix·Nostr 등 | 각 메신저 SDK를 extensions/* 플러그인으로 감쌈. |
| 메모리 | LanceDB (memory-lancedb) | 대화·지식을 벡터로 저장·검색하는 임베디드 DB. |
| 음성 | ElevenLabs + 시스템 TTS | Voice Wake(호출어)·Talk Mode(연속 음성). 외부 실패 시 OS 음성으로 폴백. |
| 데스크탑/모바일 앱 | Swift(macOS·iOS) · Kotlin/Gradle(Android) | 맥 메뉴바 앱, iOS/안드로이드 "노드"(음성·카메라·화면). |
| Control UI | 웹 UI (ui/, dist/control-ui) | 게이트웨이를 브라우저에서 보고 제어(WebChat·디버그). |
| 샌드박스 | Docker(기본, "crabbox") · SSH · OpenShell | 비신뢰 세션의 도구 실행을 격리. |
| 빌드/품질 툴체인 | oxc(oxlint·oxfmt) · tsgo · vitest · knip·madge | 초고속 린트/포맷, 타입체크, 테스트, 죽은 코드·import 순환 탐지. |
| 패키지/버전 | pnpm workspace · CalVer(vYYYY.M.D) | 모노레포 의존성 관리, 날짜 기반 버전(예: 2026.5.26). |
v2026.5.26 = 2026년 5월 26일 릴리스. 매일/매주 빠르게 쏟아내는 프로젝트가 즐겨 쓴다.메시지 한 통이 들어와서 답이 나가기까지.
먼저 독수리 시점으로 전체 그림부터 보자. 가운데 게이트웨이가 교차로다. 왼쪽에서 메신저(채널)들이 들어오고, 가운데에서 에이전트가 LLM·도구·메모리를 쓰며, 아래의 샌드박스가 위험한 실행을 가두고, 오른쪽 위의 노드(맥·폰)가 음성·화면을 담당한다.
이제 대표 흐름 한 줄기를 입력부터 출력까지 손으로 따라가 보자. "텔레그램으로 모르는 사람이 DM을 보냈다"를 예로 든다(핵심 줄만 형광):
여기서 두 가지 "이 레포의 정상(컨벤션)"을 짚어두면 코드가 덜 낯설다. 첫째, 모든 채널은 같은 모양의 "봉투(envelope)"로 정규화된다 — 그래서 게이트웨이 코드는 텔레그램인지 슬랙인지 몰라도 똑같이 다룬다(채널 무관 경계). 둘째, 채널·도구는 전부 plugin-sdk라는 정해진 출입구로만 코어에 접근한다 — package.json의 export 목록 대부분이 이 SDK 표면(approval/reply/channel runtime 등)인 이유다.
extensions/에 플러그인 하나만 추가하면 된다.main 세션을 Docker 샌드박스에 넣고 bash·read·write는 허용하되 browser·cron 등은 막는다. "낯선 손님은 응접실까지만, 안방·금고는 잠금"에 해당.어떤 폴더가 무슨 일을 하나. (모노레포라 폴더가 곧 아키텍처다)
| 경로 | 역할 |
|---|---|
src/ | 핵심. 게이트웨이 데몬, 에이전트 루프, 세션 모델, 도구 구현. |
extensions/ | 각 메신저·모델 제공자를 독립 플러그인으로. 새 채널은 여기에 추가. |
packages/plugin-sdk/ | 플러그인이 import해도 되는 "공식 출입구". 경계 검사 스크립트가 외부에서 코어 직접 접근을 막는다. |
apps/ | 네이티브 앱들. macOS/iOS는 Swift, Android는 Kotlin. shared/에 게이트웨이 프로토콜(Swift) 공유. |
skills/ · ~/.openclaw/workspace/skills/ | 비서가 쓰는 절차서(SKILL.md). 번들/관리형/워크스페이스 3종. |
scripts/ | 빌드·죽은코드·의존성·문서·릴리스를 검사하는 자동화. 이 프로젝트의 "엔지니어링 규율"이 여기 다 보인다. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
새 메신저를 코어 수정 없이 추가하려면 어떤 경계가 필요한가? plugin-sdk/의 export 표면과 extensions/telegram/을 나란히 보면, "코어가 모르는 채로 채널을 갈아끼우는" 인터페이스 설계의 모범 사례를 읽을 수 있다.
실제 메신저 DM은 누구나 보낼 수 있는 "비신뢰 입력"이다. DM 페어링·허용목록·세션별 도구 allow/deny·Docker 샌드박스가 어떻게 맞물리는지 보안 문서와 함께 읽으면, AI 에이전트의 현실적 위협 모델을 익힐 수 있다.
scripts/에는 import 순환 탐지(madge), 죽은 코드(knip·ts-prune), 의존성 취약점 게이트, plugin-sdk 경계 린트 같은 수백 개의 검사가 있다. "코드를 어떻게 짜는가"만큼 "대규모 코드를 어떻게 썩지 않게 지키는가"를 배우기 좋은 교본이다.
게이트웨이 프로토콜을 JSON 스키마로 정의하고 Swift 모델로 동기화하는 흐름(protocol:gen, GatewayModels.swift)을 보면, 서로 다른 언어의 클라이언트를 "한 진실원"으로 맞추는 실전 기법을 볼 수 있다.
예를 들어, 게이트웨이를 띄우고 한 줄로 비서에게 일을 시키는 모양은 이렇다:
# 데몬으로 게이트웨이 설치 + 온보딩
npm install -g openclaw@latest
openclaw onboard --install-daemon
# 비서에게 직접 말 걸기(생각 깊이 high)
openclaw agent --message "출시 체크리스트 정리해줘" --thinking high돌리려면 무엇이 필요한가. (순수 소프트웨어 — 특수 하드웨어는 없음)
| 항목 | 요구사항 |
|---|---|
| 런타임 | Node.js 24 권장(또는 22.19+). 패키지 매니저는 npm·pnpm·bun. |
| OS | macOS · Linux · Windows(네이티브 Hub 앱 포함) 모두 지원. |
| 상시 실행 | 게이트웨이 데몬(launchd/systemd 사용자 서비스)으로 항상 켜둠. |
| 샌드박스(선택) | 비-main 세션 격리에 Docker(기본) 또는 SSH·OpenShell. |
| 소스 빌드 | 반드시 pnpm(모노레포 워크스페이스). 루트 npm install은 비지원. |
| 앱 빌드(선택) | macOS/iOS는 Xcode·xcodegen(Swift), Android는 Gradle(Kotlin). |
| 모델/계정 | LLM 제공자 1곳(예: OpenAI). 음성은 ElevenLabs(없으면 시스템 TTS 폴백). |
혼자 쓸 땐 편하라고 main 세션 도구가 내 컴퓨터에서 그대로 돈다. 그룹/공개 채널을 붙이기 전에 agents.defaults.sandbox.mode: "non-main"로 격리하고, openclaw doctor로 위험한 DM 정책을 점검해야 한다.
난이도별로 손에 익히는 단계.
npm i -g openclaw@latest → openclaw onboard로 모델만 연결한 뒤, 메신저 없이 WebChat/CLI로 비서와 대화해 본다. "무엇이 게이트웨이이고 무엇이 에이전트인지" 체감하는 게 목표.
봇 토큰으로 텔레그램을 연결하고, 모르는 계정으로 DM을 보내 페어링 코드 → approve 흐름을 직접 겪어본다. s4의 ②단계가 코드가 아니라 손끝에서 일어난다.
sandbox.mode: "non-main"을 켜고 browser·cron을 deny로 바꾼 뒤, 비서에게 그 도구를 시켜본다. 거부되는 모습을 보며 능력 기반 보안을 이해한다.
~/.openclaw/workspace/skills/<이름>/SKILL.md를 만들어 비서에게 새 절차를 가르친다. AGENTS.md·SOUL.md·TOOLS.md가 프롬프트에 어떻게 주입되는지 함께 관찰.
pnpm install → pnpm gateway:watch로 개발 루프를 돌리고, extensions/의 기존 채널을 본떠 가장 단순한 채널 플러그인 골격을 plugin-sdk만으로 작성해 본다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 게이트웨이·에이전트·세션 개념 + 로컬 실행 | README · docs.openclaw.ai 시작하기 · 실습 1 |
| 2주차 | 채널/플러그인 구조와 plugin-sdk 경계 | extensions/telegram · plugin-sdk/ 정독 · 실습 2 |
| 3주차 | 보안 모델: 비신뢰 입력·페어링·샌드박스 | Security·Sandboxing 문서 · 실습 3 |
| 4주차 | 에이전트 워크스페이스와 스킬(SKILL.md) | Tools·Skills 문서 · 실습 4 · ClawHub 둘러보기 |
| 5주차 | 모노레포 엔지니어링(pnpm·oxc·죽은코드·CI) | scripts/·config/ · vitest 테스트 |
| 6주차 | 멀티런타임: 게이트웨이 프로토콜 ↔ Swift/Kotlin 노드 | apps/shared 프로토콜 · 노드 연결 문서 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| Gateway(게이트웨이) | 채널·세션·도구·이벤트를 묶는 로컬 제어 평면(중앙 교차로). OpenClaw의 본체. |
| Agent(에이전트) | LLM을 돌려 도구를 호출하며 일을 처리하는 비서 루프. 세션마다 독립적. |
| Channel(채널) | WhatsApp·텔레그램 등 메신저를 게이트웨이에 연결하는 플러그인. |
| Node(노드) | 맥·iOS·안드로이드 동반 앱. WebSocket으로 페어링해 음성·화면·카메라 제공. |
| inbound envelope | 채널이 다른 메시지를 같은 모양으로 정규화한 "표준 봉투". 코어가 채널 종류를 몰라도 되게 함. |
| DM pairing(페어링) | 모르는 발신자에게 코드만 주고, 운영자 승인 전엔 본문을 처리하지 않는 기본 보안. |
| Sandbox(샌드박스) | 비신뢰 세션의 도구 실행을 Docker 등에 격리. 허용/금지 도구를 세밀히 지정. |
| plugin-sdk | 플러그인이 코어에 접근하는 공식 출입구(공개 API 표면). |
| Skill(스킬) | 비서에게 절차를 가르치는 SKILL.md 문서. 레지스트리는 ClawHub. |
| LanceDB | 대화·지식을 벡터로 저장·검색하는 임베디드 DB. 메모리 확장에 사용. |
| Live Canvas / A2UI | 에이전트가 제어하는 시각 작업 공간. 비서가 화면을 직접 그려 보여줌. |
| Molty(몰티) 🦞 | OpenClaw가 만들어진 "우주 바닷가재" AI 비서 캐릭터(밈 정체성). |