Build Your Own OpenClaw: OpenClaw를 처음부터 단계별로 공부해보자

이 저장소는 완성형 프레임워크를 바로 쓰게 하는 대신, 가장 단순한 채팅 루프에서 출발해 도구 호출, 스킬, 세션 저장, 컨텍스트 압축, 이벤트 버스, 멀티 에이전트, 장기 메모리까지 직접 조립해 보게 만드는 튜토리얼형 프로젝트입니다. (GitHub)

요즘 AI 에이전트를 다룰 때 가장 답답한 지점은 “잘 돌아가는 데 왜 그렇게 설계됐는지”가 보이지 않는다는 점입니다. 프레임워크는 빠르게 결과를 내주지만, 구조를 이해하지 못하면 비용이 왜 늘었는지, 컨텍스트가 왜 깨졌는지, 왜 특정 상황에서만 불안정한지 판단하기 어렵습니다. 이 저장소는 그 불투명한 중간층을 단계별 코드로 드러냅니다. (GitHub)

이 글을 끝까지 읽으면 세 가지가 명확해집니다.
첫째, 에이전트가 단순한 LLM 호출이 아니라 세션, 이벤트, 라우팅, 메모리, 동시성 제어가 얽힌 시스템이라는 점입니다. 둘째, OpenClaw 계열 접근이 기존 “단일 프롬프트 챗봇”과 어떻게 다른지입니다. 셋째, 이 구조를 언제 도입해야 하고 언제는 과한 선택인지 판단할 수 있게 됩니다. (GitHub)

GitHub - czl9707/build-your-own-openclaw: A step-by-step guide to build your own AI agent.

 

왜 이 문제가 중요한가

처음에는 채팅 루프 하나면 충분해 보입니다. 실제로 이 튜토리얼도 Step 00에서 사용자 입력을 받고, 메시지 히스토리를 그대로 모델에 보내고, 응답을 다시 세션에 추가하는 아주 단순한 구조로 시작합니다. 문제는 이 방식이 조금만 길어져도 금방 한계를 드러낸다는 점입니다. (GitHub)

가장 먼저 드러나는 건 비용 문제입니다. 대화가 길어질수록 매 호출마다 전체 히스토리를 다시 보내야 하므로, 불필요한 토큰 사용이 늘어납니다. 저장소가 별도 단계로 compaction을 도입한 이유도 바로 이 때문인데, 오래된 대화를 요약하고 새 세션으로 넘기지 않으면 컨텍스트 한계와 비용 증가가 동시에 발생하기 때문입니다. (GitHub)

성능 문제도 바로 따라옵니다. 단일 루프 구조에서는 외부 채널 연동, 프로그램적 접근, 백그라운드 작업 같은 요구가 생길 때 병목이 쉽게 생깁니다. 이 저장소가 중간 단계에서 이벤트 버스와 WebSocket 계층을 따로 분리하는 이유는, 입력 소스와 에이전트 실행을 느슨하게 결합해 확장성을 확보하려는 설계 때문입니다. (GitHub)

유지보수 문제는 규모가 커질수록 더 커집니다. 도구, 프롬프트, 라우팅 규칙, 메모리 전략이 한 파일에 뒤섞이면 기능 추가보다 디버깅이 더 어려워집니다. 그래서 이 프로젝트는 스킬 정의, 에이전트 정의, 라우팅 테이블, 메모리 전용 에이전트처럼 책임을 나눠 보여 줍니다. (GitHub)

개발 경험 측면에서도 차이가 큽니다. 단순 챗봇은 빠르게 만들 수 있지만, 실제 제품화 단계에 가면 “왜 이 응답이 나왔는지”, “어느 에이전트가 처리했는지”, “동시에 여러 요청이 오면 어떻게 되는지”를 설명하기 어려워집니다. 이 저장소는 그 과정을 튜토리얼 단계로 분해해, 비결정적 동작을 줄이고 구조를 눈으로 따라가게 만듭니다. (GitHub)

Build Your Own OpenClaw란 무엇인가

한 문장으로 정의하면, Build Your Own OpenClaw는 “개인용 AI 에이전트 시스템을 작은 부품부터 직접 조립하며 이해하게 만드는 단계형 학습 저장소”입니다. (GitHub)

비유하면 이 프로젝트는 완성차를 주는 것이 아니라, 엔진과 조향 장치와 브레이크를 순서대로 조립해 보게 하는 정비 교육 키트에 가깝습니다. 처음에는 단순히 앞으로 가기만 하던 것이, 점점 외부 장치와 연결되고, 여러 작업을 분담하고, 오래 기억하고, 과부하를 막는 방향으로 발전합니다. (GitHub)

기술적으로 보면 이 저장소는 18개의 단계로 구성되어 있고, 각 단계마다 설명용 README와 실행 가능한 코드가 함께 제공됩니다. 구조는 1) 단일 에이전트, 2) 이벤트 기반 아키텍처, 3) 자율 동작과 멀티 에이전트, 4) 운영과 스케일 단계로 나뉘어 있습니다. (GitHub)

기존 방식과의 가장 큰 차이는 “프레임워크 사용법”이 아니라 “에이전트 시스템의 내부 모델”을 가르친다는 점입니다. 단순한 챗 인터페이스를 만드는 데서 멈추지 않고, 왜 세션이 필요하고, 왜 이벤트 버스가 필요한지, 왜 메모리를 별도 에이전트로 분리할 수 있는지까지 보여 줍니다. 이것이 이 프로젝트의 철학입니다. (GitHub)

핵심 특징

• 18단계 점진식 구성
  한 번에 거대한 구조를 던지지 않고, 채팅 루프에서 메모리와 동시성 제어까지 점진적으로 확장합니다. 초보자에게는 학습 곡선을 낮추고, 실무자에게는 아키텍처 변화 지점을 분명히 보여 줍니다. (GitHub)
• README와 실행 코드가 함께 존재
  각 단계가 설명 문서와 runnable codebase를 함께 제공하므로, 개념만 이해하고 끝나는 것이 아니라 바로 실행해 보며 검증할 수 있습니다. (GitHub)
• 스킬을 런타임에 지연 로드
  Step 02는 SKILL.md 기반 스킬을 필요할 때만 불러오는 구조를 소개합니다. 이는 모든 기능을 프롬프트에 미리 넣지 않고, 필요한 능력만 로드해 컨텍스트 낭비를 줄이려는 방향과 연결됩니다. (GitHub)
• 컨텍스트 압축 전략을 별도 단계로 다룸
  Step 05는 큰 툴 결과를 먼저 줄이고, 그래도 크면 오래된 대화를 요약해 새 세션으로 넘기는 방식을 설명합니다. 긴 대화에서 비용과 컨텍스트 한계를 동시에 다루는 점이 중요합니다. (GitHub)
• 이벤트 기반 구조로 전환
  Step 07 이후에는 입력과 실행을 직접 묶지 않고, InboundEvent와 OutboundEvent를 이벤트 버스로 흘려보냅니다. 이 방식은 CLI를 넘어 채널 연동, 서버화, 백그라운드 작업으로 확장하기 쉽게 만듭니다. (GitHub)
• 멀티 에이전트와 운영 제어까지 포함
  Step 11은 메시지 출처에 따라 다른 에이전트로 라우팅하고, Step 16은 세마포어 기반 동시성 제어를 둡니다. 즉, 이 프로젝트는 “잘 대답하는 봇”이 아니라 “운영 가능한 에이전트 시스템”으로 가는 과정을 다룹니다. (GitHub)

실제로 어떤 효과가 있는가

이 프로젝트의 가장 큰 효과는 성능 수치보다 이해 비용을 줄여 준다는 데 있습니다. 공개된 자료 기준으로 이 저장소는 “작동하는 결과물”보다 “왜 이런 구성요소가 필요한지”를 단계별로 체감하게 만드는 데 초점을 둡니다. 그래서 프레임워크를 외워 쓰는 것이 아니라, 설계 판단의 근거를 쌓는 데 유리합니다. (GitHub)

전과 후를 비교하면 차이가 분명합니다. 시작점은 전체 히스토리를 그대로 보내는 단일 채팅 루프입니다. 이후에는 툴 호출, 스킬 로딩, 세션 저장, 컨텍스트 압축, 이벤트 버스, WebSocket, 라우팅, 메모리, 동시성 제한이 더해지면서 “한 번 대답하는 봇”이 “여러 입력 경로를 처리하고 상태를 유지하는 시스템”으로 바뀝니다. (GitHub)

효과가 가장 크게 드러나는 상황은 두 가지입니다. 하나는 AI 에이전트를 처음 설계하는 팀이 구조를 통째로 이해해야 할 때입니다. 다른 하나는 이미 챗봇은 만들었지만, 긴 대화, 외부 채널 연결, 멀티 에이전트, 메모리, 운영 안정성 문제로 다음 단계가 막힌 팀입니다. (GitHub)

특히 스타트업이나 소규모 팀에는 장점이 큽니다. 처음부터 대형 프레임워크 전체를 받아들이지 않고, 필요한 복잡도를 필요한 시점에만 도입하는 사고방식을 익힐 수 있기 때문입니다. 반대로 이미 조직 표준 프레임워크와 운영 체계가 굳어 있는 팀이라면, 이 프로젝트는 생산성 도구보다 학습 재료로서 가치가 더 큽니다. 이 평가는 저장소의 단계형 구조와 설명 중심 구성에서 자연스럽게 도출되는 판단입니다. (GitHub)

동작 원리 / 구조

1. 입력을 받는다
   시작점은 CLI 채팅 루프입니다. 사용자가 메시지를 입력하면 세션이 이를 사용자 메시지로 저장하고, 현재까지의 히스토리를 모델 호출용 메시지 배열로 구성합니다. 가장 단순한 형태지만, 모든 에이전트 시스템의 최소 단위가 여기서 드러납니다. (GitHub)
2. 필요한 능력을 붙인다
   다음 단계에서 도구와 스킬이 들어옵니다. 특히 스킬은 SKILL.md 정의를 기반으로 런타임에 로드되며, 전용 스킬 툴을 통해 필요한 순간에만 내용을 꺼내 옵니다. 이 설계는 능력을 정적으로 다 박아 넣는 대신, 필요 시점에 확장하는 쪽에 가깝습니다. (GitHub)
3. 대화 상태를 보존한다
   세션과 저장 계층이 추가되면 에이전트는 단발성 호출이 아니라 상태 있는 상호작용으로 바뀝니다. 이후 compaction 단계에서는 오래된 히스토리를 그대로 유지하지 않고 요약해 새 세션으로 넘기는데, 이는 긴 대화에서도 컨텍스트를 관리하기 위한 설계입니다. (GitHub)
4. 입력과 실행을 분리한다
   이벤트 기반 단계에서는 InboundEvent와 OutboundEvent가 도입되고, EventBus가 이 이벤트를 pub/sub 방식으로 배포합니다. 이렇게 하면 입력 채널이 늘어나도 에이전트 실행 로직을 직접 뜯지 않아도 됩니다. 설계 목적은 확장성과 결합도 감소입니다. (GitHub)
5. 채널과 프로그램적 접근을 연다
   이후 채널 단계와 WebSocket 단계에서 에이전트는 CLI 밖으로 나갑니다. WebSocket 워커는 연결된 클라이언트를 관리하고 이벤트를 브로드캐스트하므로, 외부 애플리케이션이나 다른 인터페이스가 같은 에이전트 시스템과 연결될 수 있습니다. (GitHub)
6. 여러 에이전트로 역할을 나눈다
   멀티 에이전트 라우팅 단계에서는 에이전트 정의를 스캔하고, 소스 패턴과 매핑 규칙에 따라 어느 에이전트가 처리할지 결정합니다. 즉, 하나의 거대한 프롬프트에 모든 역할을 욱여넣는 대신, 역할별 에이전트를 분리하는 방향입니다. (GitHub)
7. 장기 메모리를 별도 책임으로 둔다
   메모리 단계에서는 기억을 전담하는 specialized agent가 등장합니다. 현재 구현은 메모리 전용 에이전트를 dispatch해 정보를 저장하고 조회하는 방식이며, 직접 툴로 붙이는 방식이나 벡터 데이터베이스 방식과 구분됩니다. 이 선택은 “기억”을 별도 책임으로 분리한다는 설계 의도를 보여 줍니다. (GitHub)
8. 운영 안정성을 보강한다
   마지막으로 동시성 제어 단계에서는 에이전트별 최대 동시 실행 수를 두고, 세마포어로 과도한 병렬 실행을 막습니다. 이것이 필요한 이유는 에이전트가 길게 실행되거나 백그라운드 작업을 동반할 때, 자원 고갈이 곧 장애로 이어질 수 있기 때문입니다. (GitHub)

설치 / 사용 방법

이 저장소는 각 단계가 독립 실행 가능한 형태로 구성되어 있습니다. 공통적으로 먼저 설정 파일을 복사해 API 키를 넣고, 그다음 원하는 단계 디렉터리로 들어가 실행하는 흐름입니다. 루트 README는 모든 단계 실행 전에 config.example.yaml을 config.user.yaml로 복사해 API 키를 넣으라고 안내합니다. (GitHub)

설치 흐름은 대략 아래처럼 이해하면 됩니다. 저장소는 Python 3.11 이상을 요구하고, Step 00의 pyproject.toml에는 litellm, typer, rich, pydantic, pyyaml 같은 의존성이 정의되어 있습니다. 실행 예시는 uv run my-bot chat 형태로 제공됩니다. (GitHub)

git clone <저장소>
cd build-your-own-openclaw

cp default_workspace/config.example.yaml default_workspace/config.user.yaml
# config.user.yaml에 API 키 입력

cd 00-chat-loop
uv run my-bot chat

최소 실행 예제는 Step 00입니다. 이 단계에서는 단순히 대화를 주고받는 기본 에이전트를 확인할 수 있습니다. 이후 Step 02로 가면 스킬 개념을, Step 05로 가면 컨텍스트 압축을, Step 07 이후로 가면 이벤트 기반 구조를 같은 방식으로 이어서 실험할 수 있습니다. (GitHub)

메모리까지 보고 싶다면 다음 흐름이 이해하기 좋습니다.
Step 00으로 기본 루프를 익히고, Step 02에서 능력 확장 방식을 보고, Step 05에서 컨텍스트 관리 이유를 체감한 다음, Step 07과 Step 11을 거쳐 Step 17에서 장기 기억이 어떻게 붙는지 확인하면 전체 구조가 자연스럽게 이어집니다. 이 순서는 저장소의 단계 설계와 잘 맞습니다. (GitHub)

자주 쓰는 예시 / 활용 시나리오

1. AI 에이전트 입문 학습

에이전트를 처음 만드는 개발자에게 가장 적합한 용도입니다. 단순 챗봇에서 끝나지 않고, 왜 도구와 세션, 이벤트, 메모리, 동시성 제어가 필요한지 흐름으로 익힐 수 있습니다. (GitHub)

2. 기존 챗봇을 시스템으로 확장하기

이미 “질문하면 대답하는 봇”은 있지만, 채널 연동이나 서버화가 필요한 팀에 맞습니다. 이벤트 버스와 WebSocket 단계는 입력 경로를 늘리면서도 실행 로직의 결합을 낮추는 방향을 보여 줍니다. (GitHub)

3. 컨텍스트 최적화 실험

대화가 길어져 비용이 늘고 응답 품질이 흔들리는 상황에서 compaction 단계가 유용합니다. 오래된 메시지를 요약해 넘기는 방식은 벡터 검색 없이도 긴 세션을 관리하는 현실적인 첫 단계가 됩니다. (GitHub)

4. 역할 분리형 에이전트 설계

하나의 에이전트에 모든 역할을 몰아넣는 대신, 소스별로 다른 에이전트가 처리하게 만들고 싶을 때 적합합니다. 멀티 에이전트 라우팅 단계는 어떤 메시지를 어느 에이전트가 맡을지 규칙 기반으로 분리하는 사고를 익히게 합니다. (GitHub)

5. 장기 기억 구조 실험

사용자 정보나 프로젝트 맥락을 장기적으로 유지해야 할 때, Step 17의 specialized memory agent 접근이 좋은 실험 재료가 됩니다. 특히 메모리를 주 에이전트의 프롬프트에 섞는 대신, 별도 책임으로 나누는 방식이 어떤 장단점을 가지는지 확인할 수 있습니다. (GitHub)

한계 / 주의할 점

첫째, 이 저장소는 어디까지나 튜토리얼 성격이 강합니다. 문서상 확인되는 범위에서 각 단계는 개념을 설명하고 runnable code를 제공하는 데 초점이 있으며, 대규모 운영 환경에서 필요한 모든 관찰성, 보안, 장애 복구, 배포 자동화를 포괄한다고 보기는 어렵습니다. (GitHub)

둘째, OpenClaw와 완전히 동일한 구현은 아닙니다. 예를 들어 스킬 시스템은 이 튜토리얼에서는 전용 skill 툴 방식으로 설명하지만, 설명상 OpenClaw는 시스템 프롬프트 주입과 파일 읽기 방식에 더 가깝다고 명시합니다. 따라서 “OpenClaw 복제본”이라기보다 “핵심 설계를 학습하기 위한 경량 구현”으로 보는 편이 정확합니다. (GitHub)

셋째, 적용이 어려운 경우도 있습니다. 단순한 사내 FAQ 봇이나 일회성 챗 인터페이스라면, 이벤트 버스·멀티 에이전트·동시성 제어까지 도입하는 것은 과할 수 있습니다. 이 구조는 채널이 늘고, 역할이 분리되고, 세션 지속성과 운영 안정성이 중요해질 때 가치가 커집니다. 이 부분은 저장소의 단계 구성을 바탕으로 한 실무적 해석입니다. (GitHub)

넷째, 현재 기준으로는 성능 벤치마크나 운영 지표를 체계적으로 제시하는 프로젝트는 아닙니다. 공개된 자료 기준으로 강점은 수치 최적화보다 구조 학습과 설계 이해에 있습니다. 따라서 “바로 프로덕션에 넣을 도구”를 찾는 기대와는 약간 다를 수 있습니다. (GitHub)

마무리

Build Your Own OpenClaw의 가치는 기능 수가 아니라 설명 방식에 있습니다.
이 프로젝트는 에이전트를 프롬프트 몇 줄의 문제가 아니라, 상태 관리와 이벤트 흐름, 역할 분리와 운영 제어가 필요한 시스템으로 보게 만듭니다. (GitHub)

특히 AI 에이전트 개발을 처음 구조적으로 배우고 싶은 개발자, 단일 챗봇에서 한 단계 넘어가려는 스타트업, 여러 역할과 채널을 다루는 개인용 혹은 소규모 팀용 에이전트를 설계하는 사람에게 잘 맞습니다. 반면, 당장 완성형 프레임워크만 필요한 팀에게는 학습용 비중이 더 크게 느껴질 수 있습니다. (GitHub)

핵심 요약

• 핵심 개념
  Build Your Own OpenClaw는 채팅 루프에서 시작해 도구, 스킬, 세션, 컨텍스트 압축, 이벤트 버스, 멀티 에이전트, 장기 메모리, 동시성 제어까지 직접 조립하며 배우는 단계형 에이전트 튜토리얼입니다. (GitHub)
• 차별점
  사용법을 가르치는 프레임워크 문서가 아니라, 왜 그런 구조가 필요한지까지 보여 주는 설계 학습형 저장소라는 점이 다릅니다. (GitHub)
• 언제 쓰면 좋은지
  AI 에이전트 아키텍처를 처음부터 이해하고 싶을 때, 기존 챗봇을 채널 연동·멀티 에이전트·메모리 구조로 확장하고 싶을 때 좋습니다. (GitHub)
• 언제 쓰면 안 되는지
  단순 질의응답 봇처럼 구조 복잡도가 낮은 문제를 빠르게 끝내야 한다면, 이 저장소의 단계적 아키텍처는 과한 선택일 수 있습니다. (GitHub)
• 한 줄 요약
  “에이전트를 만드는 법”보다 “에이전트 시스템이 왜 그렇게 생겨야 하는지”를 배우게 해 주는 저장소입니다. (GitHub)