---
title: "OpenClaw 특집: 아키텍처 분석 🦞"
date: "2026-02-24T16:37:11+08:00"
category: "OpenClaw"
description: v2026.3.8 소스코드 기반, 셀프호스팅 AI 어시스턴트의 엔지니어링 골격 해부
tags: [AI, open-source, openclaw]
pinned: false
---

![OpenClaw](/images/openclaw-logo-text-dark.webp)

[지난 글](/ko/posts/openclaw-ecosystem/)에서 생태계를 다뤘으니, 이번에는 아키텍처를 해부해 보겠습니다.

OpenClaw의 코드베이스는 작지 않습니다 -- TypeScript 43만 줄입니다. 하지만 흥미로운 건 코드 줄 수가 아니라 아키텍처 설계입니다. 20개 이상의 채팅 플랫폼을 동시에 다루고, 여러 Agent를 관리하면서, 도구까지 실시간으로 호출해야 하는 AI 어시스턴트를 어떻게 하나의 시스템에 우겨넣되 무너지지 않게 만들 수 있을까요?

## 0. 먼저 몇 가지 용어부터

시스템 아키텍처에 익숙하지 않아도 괜찮다. 아래 6개 용어만 먼저 잡으면 뒤가 훨씬 수월해진다:

- `아키텍처`: 시스템이 어떻게 계층을 나누고 책임을 배치하는지
- `Channel / 채널 계층`: 외부 채팅 플랫폼마다 다른 프로토콜을 맞춰 주는 적응 계층
- `Gateway`: 메시지 라우팅, 세션, Agent를 관리하는 중앙 조정자
- `Node`: 실제로 명령을 실행하고 디바이스를 움직이는 실행 끝단
- `workspace / 워크스페이스`: Agent의 설정, 메모리, 스킬, 세션 파일이 모여 있는 로컬 폴더
- `sandbox / 샌드박스`: 위험한 작업을 격리해서 실행하는 제한된 환경

## 1. 3계층 아키텍처: Channel -> Gateway -> Node

먼저 전체 그림을 봅시다:

![OpenClaw 아키텍처](/images/openclaw-architecture-ko.svg)

OpenClaw을 3개 부서를 가진 회사라고 생각해 보세요:

| 구성 요소 | 역할 | 비유 |
|-----------|------|------|
| **Channel (어댑터 계층)** | WhatsApp, Telegram, Discord, Feishu 등 20개 이상의 채팅 플랫폼에 연결 | 프론트 데스크 -- 전화 받고, 우편 수령하고, 방문객 맞이 |
| **Gateway** | 중앙 디스패치; 모든 세션과 Agent를 관리 | 두뇌 -- 누구의 메시지를 어디로 보내고 어떻게 답할지 결정 |
| **Node (실행 노드)** | 디바이스에서 실제 작업 수행 -- 사진 촬영, 화면 캡처, 명령 실행 | 손과 발 -- 두뇌가 "사진 찍어"라고 하면 Node가 가서 실행 |

전체 시스템의 핵심은 Gateway입니다 -- 기본적으로 localhost(`127.0.0.1:18789`)에서만 수신 대기하는 장기 실행 프로세스로, 절대 공개 인터넷에 노출되지 않습니다. 원격 접속이 필요하면 Tailscale 터널을 사용하세요. 포트를 직접 열지 마세요. 이런 설계를 "Loopback-First"라고 하는데, 기발한 보안 전략입니다: 열린 포트가 0개면 공격 면적도 0입니다.

왜 분산 구조 대신 단일 프로세스일까요? 이유는 현실적입니다: WhatsApp 프로토콜은 한 번에 하나의 디바이스만 온라인일 수 있습니다. 두 개의 프로세스를 띄우면 서로 싸웁니다. "아키텍처적 정석"을 위해 조정 로직을 잔뜩 쌓느니, 단일 프로세스로 처음부터 끝까지 처리하는 게 낫습니다. 대부분의 개인 사용자에게는 이것만으로도 충분합니다.

## 2. 메시지 하나의 여정

Telegram에서 OpenClaw에게 "내일 베이징 날씨 어때?"라고 보내봅시다. 이런 일이 벌어집니다:

**1단계: 접수.** Telegram 어댑터가 메시지를 수신하고, Telegram 형식의 데이터를 OpenClaw 내부의 통합 형식으로 변환합니다. 어느 플랫폼에서 온 메시지든, 변환 결과는 동일한 형태입니다.

**2단계: 신원 확인 및 라우팅.** 당신은 누구인가요? 이 Agent와 대화할 권한이 있나요? 모르는 사람이라면 먼저 페어링 코드가 전송되고, 소유자가 승인해야 합니다. 확인이 끝나면 라우팅 엔진이 어떤 Agent에게 메시지를 보낼지 결정합니다.

**3단계: 컨텍스트 조립.** 이전 대화 기록이 디스크에서 로드되고, Agent의 성격 정의(SOUL.md), 행동 규칙(AGENTS.md), 메모리 저장소에서 의미적으로 관련된 항목들이 함께 불러와집니다. 이 모든 것이 완전한 "두뇌 브리핑"으로 조립됩니다.

**4단계: LLM 질의.** 그 브리핑이 설정된 LLM 제공자에게 전송됩니다 -- Anthropic, OpenAI, DeepSeek, MiniMax, GLM, Qwen, Gemini 등. 모델이 토큰 단위로 스트리밍 응답을 보내옵니다.

**5단계: 도구 실행.** 모델이 "날씨를 확인하려면 명령어를 실행해야 해"라고 하면, 런타임이 요청을 가로채서 보안 정책에 따라 어디서 실행할지 결정합니다(관리자 명령은 직접 실행; 낯선 사람의 명령은 Docker 샌드박스에서 실행). 결과는 모델에 다시 전달되어 생성을 이어갑니다.

**6단계: 응답.** 최종 답변이 Telegram의 요구사항(글자 수 제한, Markdown 규칙 등)에 맞게 포맷되고, 필요하면 분할된 후 당신에게 전송됩니다. 대화 내용은 디스크에 기록됩니다.

이 전체 과정에서 유일하게 느린 부분은 4단계 -- 모델이 첫 토큰을 생성할 때까지 기다리는 것입니다. 나머지는 전부 밀리초 수준입니다.

## 3. Channel 어댑터 계층: 한 번 만들고 어디서든 대화

OpenClaw은 20개 이상의 채팅 플랫폼과 연동되지만, 각 플랫폼마다 처음부터 끝까지 새로 구현하지 않습니다. "어댑터" 계층을 추상화했고, 각 플랫폼의 어댑터는 딱 네 가지만 책임집니다:

- **로그인**: WhatsApp은 QR 코드 스캔, Telegram은 Bot Token, iMessage는 macOS 네이티브 기능 사용 -- 플랫폼마다 각자의 방식
- **수신 메시지 변환**: 텍스트, 이미지, 답장, 리액션 -- 전부 내부 통합 형식으로 변환
- **접근 제어**: 누가 DM할 수 있는지, 그룹에서 @멘션할 때만 답하는지, 어떤 그룹이 허용되는지
- **발신 응답 변환**: Agent의 응답을 각 플랫폼이 표시할 수 있는 형식으로 변환

6개 주요 플랫폼은 기본 내장(WhatsApp, Telegram, Discord, Slack, Signal, iMessage)이고, 30개 이상(Feishu, LINE, Matrix, Mattermost 등)은 플러그인으로 연결됩니다.

이 추상화의 최대 이점: Agent는 메시지가 어느 플랫폼에서 왔는지 알 필요가 없습니다. WhatsApp에서 대화하는 Agent와 Telegram에서 대화하는 Agent는 같은 Agent입니다 -- 동일한 로직, 완전한 재사용. Channel은 그저 확성기일 뿐, 확성기를 바꿔도 말하는 사람은 같습니다.

## 4. Agent 런타임과 워크스페이스

Agent 런타임의 핵심은 Pi-mono(오픈소스 코딩 Agent)에서 왔으며, Gateway 프로세스에 직접 내장되어 있습니다.

### "모든 것이 텍스트 파일" 워크스페이스

OpenClaw에서 가장 매력적인 설계 중 하나입니다 -- Agent의 모든 설정이 직접 열어서 편집할 수 있는 일반 텍스트 파일입니다:

```
workspace/
├── AGENTS.md          # Agent가 누구이고 어떻게 동작하는지 정의 (이력서 + 사원 핸드북)
├── SOUL.md            # 영혼 정의 -- 성격, 가치관 (설정하고 내버려두세요)
├── USER.md            # 사용자 프로필 -- 이름, 선호도
├── MEMORY.md          # 장기 기억 -- Agent가 능동적으로 메모한 중요한 것들
├── HEARTBEAT.md       # 예약 작업 -- 예: 매일 아침 날씨 알림
├── memory/            # 일기장
│   └── YYYY-MM-DD.md  # 하루에 한 페이지, 추가만 가능
├── skills/            # 스킬 팩
└── sessions.json      # 세션 기록
```

데이터베이스도 없고, 전용 관리 패널도 없습니다 -- 그냥 일반 텍스트 파일입니다. Agent의 성격을 바꾸고 싶으면? SOUL.md를 열고 몇 줄 수정하세요. 뭘 기억하는지 보고 싶으면? MEMORY.md를 열어서 읽으세요. 이런 "Agent의 뇌를 통째로 들여다볼 수 있는" 투명성은 대부분의 폐쇄형 AI 제품이 제공하지 못하는 것입니다.

### 대화 한 턴의 실행 과정

1. **발신자 식별**: 관리자와의 DM인지, 친구의 DM인지, 그룹에서 @멘션한 것인지? 출처에 따라 보안 수준이 다름
2. **메모리 조립**: 대화 기록 로드, 성격과 규칙 로드, 관련 장기 기억 검색, 전부 하나의 완전한 컨텍스트로 조합
3. **LLM 질의**: 설정된 모델에 전송, 폴백 지원 -- 주 모델이 다운되면 자동으로 백업 모델로 전환
4. **실행 및 기억**: 도구 호출 실행, 대화 로그 업데이트

컨텍스트 조립은 모든 것을 무차별적으로 쏟아붓는 게 아닙니다. 관련 없는 스킬은 로드하지 않고, 불필요한 도구는 주입하지 않습니다 -- 토큰을 아끼는 것이 곧 비용을 아끼는 것입니다.

## 5. 4단계 메모리: AI가 정말로 당신을 기억하게 만들기

대부분의 챗봇은 창을 닫으면 당신을 잊어버립니다. OpenClaw은 그렇지 않습니다. 가장 깊은 "나는 누구인가"부터 가장 얕은 "방금 뭘 이야기했지?"까지, 4단계 메모리가 있습니다:

| 계층 | 내용 | 비유 |
|------|------|------|
| **SOUL** | 성격 정의, 절대 변하지 않음 | 당신의 성격 -- 태어날 때부터 결정된 것 |
| **TOOLS** | 현재 설치된 스킬 | 오늘 가져온 도구들 |
| **USER** | 당신에 대한 장기 기억 | 좋아하는 음식을 기억하는 오랜 친구 |
| **Session** | 현재 대화 | 지금 이야기하고 있는 주제 |

몇 가지 기발한 메커니즘이 있습니다:

**데일리 일기.** 매일의 대화가 자동으로 `memory/2026-03-12.md`에 기록됩니다(추가만 가능, 덮어쓰기 불가). 다음 대화가 시작되면, Agent가 자동으로 오늘과 어제의 일기를 훑어보며 연속성을 유지합니다 -- "어제 말한 그 책, 결국 샀어?"

**자동 메모리 구출.** 대화가 길어져서 컨텍스트 윈도우가 거의 찰 때는 어떻게 할까요? OpenClaw이 백그라운드에서 눈에 보이지 않는 턴을 실행해 핵심 정보를 MEMORY.md에 저장한 뒤, 오래된 내용을 압축합니다. 당신은 이 과정을 눈치채지 못하지만, 핵심 사실은 보존됩니다. 이 메커니즘을 Pre-Compaction이라고 부릅니다.

**시맨틱 검색.** "전에 이야기한 배포 문제 있잖아"라고 말하면, 실제로 기억에서 찾아낼 수 있습니다 -- 정확한 키워드 매칭이 아니라 의미를 이해해서 찾습니다. 내부적으로는 벡터 검색(SQLite-vec)과 전통적인 키워드 검색(BM25)의 이중 접근 방식을 사용합니다.

**크로스 플랫폼 아이덴티티.** Telegram에서 30분 대화한 다음 WhatsApp으로 옮겨서 계속해도 -- 당신을 알아봅니다. 같은 사람의 여러 플랫폼 ID가 하나의 아이덴티티로 연결되어 같은 메모리를 공유합니다. 다만 그룹 채팅 메모리는 격리됩니다 -- 그룹에서 한 말이 개인 대화로 흘러가지 않습니다.

## 6. 도구 시스템: 칼 딱 4자루

OpenClaw에서 가장 "반항적인" 설계 선택입니다.

다른 AI Agent 프레임워크들은 수백 개의 내장 도구를 넣으려 합니다. OpenClaw은 딱 네 개만 제공합니다:

| 도구 | 한 줄 설명 |
|------|-----------|
| **Read** | 파일 읽기 |
| **Write** | 파일 쓰기 |
| **Edit** | 파일 수정 |
| **Bash** | 명령어 실행 |

끝입니다. 진짜로요.

창립자의 논리: 커맨드 라인(Bash)이 있으면 뭐든 할 수 있습니다. 날씨 확인? `curl`로 가져오면 됩니다. 이메일 보내기? CLI 도구를 호출하면 됩니다. 데이터베이스 쿼리? `psql`이면 충분합니다. 모든 시나리오마다 전용 도구를 미리 만들어 둘 필요가 없습니다.

이것이 Unix 철학입니다 -- 작은 도구, 조합 가능, 텍스트 스트림. 트레이드오프는? 어떤 명령을 실행할지 스스로 파악할 수 있을 만큼 똑똑한 모델이 필요합니다. 그래서 OpenClaw은 Claude Opus급 모델을 권장합니다. 약한 모델로는 어려울 수 있습니다.

이 네 가지 핵심 도구 위에 55개의 내장 Skills과 ClawHub 스킬 마켓플레이스가 있습니다. Skills은 설치하고 제거할 수 있습니다 -- Agent용 앱이라고 생각하면 됩니다.

**여기서 자극적인 부분: OpenClaw은 의도적으로 MCP를 지원하지 않습니다.** MCP는 Anthropic의 도구 프로토콜 표준으로, 전 세계의 AI 프레임워크가 앞다투어 도입하고 있습니다. OpenClaw은 거부합니다. Peter의 정확한 발언: "MCP는 쓰레기야, 확장이 안 돼. 뭐가 확장되는지 알아? CLI. Unix." 대안은 내장된 `mcporter` 브리지입니다.

**더 재미있는 건 자기 확장입니다.** OpenClaw Agent가 못 하는 일을 만나면, 스킬을 직접 작성한 다음 자동으로 설치합니다. 스킬에서 버그를 발견하면? 고치고 다시 로드합니다. 이는 Agent가 사용할수록 점점 강해진다는 뜻입니다 -- 본질적으로 스스로를 키우고 있는 셈입니다.

## 7. Multi-Agent 라우팅: 하나의 두뇌, 여러 인격

하나의 Gateway에서 여러 Agent를 동시에 실행할 수 있으며, 각각 독립적으로 작동합니다. 라우팅 규칙은 이렇게 생겼습니다:

```json
{
  "bindings": [
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "slack" } },
    { "agentId": "bot", "match": { "channel": "discord", "guildId": "123456" } }
  ]
}
```

쉽게 말하면: 개인 WhatsApp에서 온 메시지는 "홈 어시스턴트"로, Slack 메시지는 "업무 어시스턴트"로, 특정 Discord 서버는 "커뮤니티 봇"으로 갑니다. 세 Agent는 완전히 격리되어 있습니다 -- 각각 고유한 성격, 기억, 스킬, 보안 정책을 가집니다.

## 8. 보안: 3개의 문

당신의 Agent는 당신의 서버에서 돌아갑니다. 명령어를 실행하고 파일을 읽고 쓸 수 있으니 -- 보안이 당연히 중요합니다. OpenClaw의 보안 모델에는 세 개의 문이 있습니다:

**첫 번째 문: 당신은 누구? (DM 페어링)** 모르는 사람이 당신의 Agent에게 메시지를 보내면, Agent가 그냥 답하지 않습니다. 6자리 페어링 코드를 보내고, 당신이 이미 인증된 채널을 통해 확인한 후에야 그 사람이 상호작용할 수 있습니다. 이것이 기본 동작입니다 -- 끄면 당신의 번호를 아는 아무나 API 크레딧을 공짜로 태울 수 있습니다.

**두 번째 문: VIP 통로 (허용 목록).** 신뢰할 수 있는 사람은 허용 목록(`allowFrom`)에 직접 추가하여 페어링 없이 바로 대화할 수 있습니다.

**세 번째 문: 끼어들지 마 (그룹 규칙).** 그룹 채팅에서 Agent는 기본적으로 @멘션이 있을 때만 답합니다 -- 모든 메시지에 불쑥 나타나지 않습니다. 토큰을 아끼고 모두를 귀찮게 하지 않기 위해서입니다.

이 아래에는 심층 방어 계층이 있습니다: 5단계 도구 권한 필터링, Docker 샌드박스 격리(모르는 사람의 명령은 샌드박스에서 실행), 보안 감사 명령(`openclaw security audit`). 이 계층들은 독립적입니다 -- 페어링 코드가 뚫렸다고요? 샌드박스가 여전히 있습니다. 샌드박스가 우회됐다고요? 도구 정책이 호출 가능한 것을 여전히 제한합니다.

## 9. 정리

**단일 프로세스는 게으름이 아니라 실용주의입니다.** 개인 사용자에게는 하나의 프로세스가 모든 것을 처리하는 게 분산 구조보다 훨씬 안정적입니다. 한계점은? 아마 동시 메시지 처리량이 단일 머신의 능력을 초과할 때일 텐데 -- 대다수의 사람에게 그 날은 절대 오지 않을 겁니다.

**Channel 추상화 계층이 가장 가치 있는 계층입니다.** 20개 이상 플랫폼의 특이사항이 어댑터에 완전히 캡슐화되어 있어, Agent는 메시지가 어디서 왔는지 신경 쓰지 않습니다. 새 플랫폼을 추가하고 싶으면? 어댑터를 작성하면 됩니다 -- Agent 로직 변경은 제로입니다. 디커플링이 매우 깔끔합니다.

**보안 설계는 진지하지만, 구현에는 아직 빈틈이 있습니다.** 아키텍처적으로 신원 확인, 샌드박싱, 도구 정책이 심층 방어를 구성합니다. 하지만 Kaspersky 감사에서 512개의 취약점(치명적 8개)이 발견되었으며, 이는 훌륭한 청사진과 실제 보안 사이의 거리가 지속적인 엔지니어링 노력으로 측정된다는 것을 보여줍니다.

**4개 핵심 도구 미니멀리즘은 하나의 베팅입니다.** 모델 능력이 계속 올라갈 것이라는 베팅입니다 -- 충분히 강력해서 미리 만든 도구가 필요 없고 "모든 것은 Bash로 가능"하다는 것입니다. LLM 능력이 정체되면 이 경로는 힘들어집니다. 하지만 모델 지능이 계속 상승하면, 이것이 가장 우아한 접근법일 수도 있습니다.

**궁극적인 시험은 아키텍처가 얼마나 예쁜지가 아니라, 얼마나 안정적으로 돌아가느냐입니다.** 이 분석은 정적 소스코드 리딩에 기반합니다. 실제 성능 -- 고동시성에서 Gateway의 안정성, 샌드박스가 실제로 공격을 견디는지, 크로스 채널 아이덴티티 연결의 엣지 케이스 -- 은 더 많은 프로덕션 데이터로 검증이 필요합니다.

아키텍처는 골격일 뿐입니다. 프로덕션이 진짜 시험입니다.