OpenClaw 특집: 아키텍처 분석 🦞

지난 글에서 생태계를 다뤘으니, 이번에는 아키텍처를 해부해 보겠습니다.

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

0. 먼저 몇 가지 용어부터

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

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

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

먼저 전체 그림을 봅시다:

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

전체 시스템의 핵심은 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의 모든 설정이 직접 열어서 편집할 수 있는 일반 텍스트 파일입니다:

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

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

대화 한 턴의 실행 과정

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

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

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

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

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

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

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

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

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

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

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

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

끝입니다. 진짜로요.

창립자의 논리: 커맨드 라인(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를 동시에 실행할 수 있으며, 각각 독립적으로 작동합니다. 라우팅 규칙은 이렇게 생겼습니다:

1
{
2
  "bindings": [
3
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
4
    { "agentId": "work", "match": { "channel": "slack" } },
5
    { "agentId": "bot", "match": { "channel": "discord", "guildId": "123456" } }
6
  ]
7
}

쉽게 말하면: 개인 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의 안정성, 샌드박스가 실제로 공격을 견디는지, 크로스 채널 아이덴티티 연결의 엣지 케이스 — 은 더 많은 프로덕션 데이터로 검증이 필요합니다.

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