OpenClaw 내부 분석 — ReAct 루프, 컨텍스트 조립, Lobster DAG로 보는 로컬 에이전트 파이프라인 설계
처음 OpenClaw를 접했을 때 솔직히 "또 다른 AI 에이전트 프레임워크겠지"라고 생각했습니다. LangChain, AutoGPT, CrewAI... 비슷한 것들이 워낙 많이 나와서요. 그런데 실제로 파고들어 보니 좀 달랐습니다. 특히 툴 호출 체인이 내부에서 어떻게 연결되는지, 그리고 컨텍스트가 매 요청마다 어떤 요소로 조립되는지를 이해하고 나면, 왜 이 프레임워크가 프로덕션 자동화 파이프라인 설계에 쓰일 만한지가 보입니다.
배경만 짧게 짚자면, 로컬 LLM 생태계가 성숙하면서 — Ollama가 공식 프로바이더로 편입되고, Qwen3나 Llama 3.x 같은 모델이 랩탑 수준에서도 실용적인 성능을 내면서 — 데이터를 외부로 내보내지 않고도 에이전트 파이프라인을 돌릴 수 있게 됐습니다. OpenClaw는 그 시점에 필요한 레이어를 채워주는 프레임워크로 자리 잡았습니다. GitHub 스타 수 같은 구체적 지표는 시점에 따라 편차가 크고 저도 1차 출처를 확인하지 못했기 때문에, 이 글에서는 인용을 생략하겠습니다.
이 글에서는 ReAct 루프가 실제로 어떻게 동작하는지, 컨텍스트 패키지가 어떤 요소로 조립되는지, 그리고 Lobster 워크플로 엔진을 통해 결정론적 멀티 에이전트 파이프라인을 어떻게 구성하는지를 집중적으로 살펴보겠습니다. 설치와 Hello World가 아니라, 파이프라인 설계 관점에서 내부 구조를 이해하는 데 초점을 맞춥니다.
세 계층이 분리되어 있다는 게 왜 중요한가
OpenClaw의 아키텍처는 세 계층으로 분리되어 있습니다. 처음 보면 과하게 느껴질 수 있는데, 실제 자동화 파이프라인을 운영해보면 이 분리가 얼마나 실용적인지 알게 됩니다.
Cognitive Layer는 LLM이 실제로 추론하는 영역입니다. 컨텍스트 윈도우를 얼마나 효율적으로 구성하느냐가 여기서 결정됩니다. Execution Layer는 모델이 선택한 툴을 Docker 컨테이너 안에서 격리 실행합니다. 이 격리가 중요한 이유는 에이전트가 선택한 스킬이 호스트 시스템에 직접 접근하지 못하게 막기 위해서입니다. Persistence Layer는 SQLite 또는 PostgreSQL 기반으로 대화 히스토리와 메모리를 저장하고, 세션 간 컨텍스트 연속성을 제공합니다. 위 다이어그램에서 텍스트 응답 역시 종료 전에 Persistence Layer를 거치도록 표현한 이유가 이것입니다 — 다음 세션에서 이어 쓰려면 최종 응답도 저장되어야 하니까요.
이 세 계층이 분리되어 있기 때문에, LLM 프로바이더만 Ollama에서 다른 모델로 교체하거나, 메모리 백엔드만 SQLite에서 PostgreSQL로 바꾸는 게 비교적 독립적으로 이루어집니다.
참고로 뒤에서 등장하는 MCClaw는 Cognitive Layer 안에서 로컬 LLM 추론을 실제로 담당하는 서브 컴포넌트입니다. OpenClaw가 별도 계층으로 격리해두지는 않았지만, Ollama·llama.cpp 같은 로컬 런타임에 직접 붙는 어댑터 역할을 맡습니다.
ReAct 루프 — 실제로 어떻게 돌아가는가
ReAct는 원 논문(Yao et al., 2022)에서 정의한 대로 Reasoning + Acting의 합성어입니다. 원리 자체는 단순한데, OpenClaw가 이걸 어떻게 구현했는지를 보면 설계 판단이 명확하게 보입니다.
핵심은 루프 종료 조건입니다. 모델이 tool call이 아닌 텍스트 전용 응답을 반환할 때 루프가 종료됩니다. 이걸 이해하면 왜 툴 정의를 명확하게 해야 하는지가 납득됩니다. 모델이 툴을 써야 할 상황인지 텍스트로 답해야 할 상황인지를 구분하지 못하면, 루프가 의도치 않게 일찍 끊기거나 반대로 너무 오래 돌 수 있습니다.
툴 호출 체인의 흐름을 의사코드 수준으로 표현하면 이렇습니다 (개념적 예시입니다).
def react_loop(message, context_package):
while True:
response = llm.invoke(context_package + [message])
if response.type == "text":
return response.content
elif response.type == "tool_call":
tool_result = gateway.invoke({
"node": response.tool_name,
"args": response.tool_args,
})
context_package = update_context(context_package, tool_result)실제 OpenClaw 코드는 이것보다 훨씬 복잡하지만, 설계의 핵심 흐름은 이렇습니다. 특히 툴 결과가 컨텍스트에 추가된 채로 재제출되기 때문에, 툴 체인이 길어질수록 컨텍스트가 선형적으로 늘어납니다. 이 점은 뒤에서 다시 이야기하겠습니다.
컨텍스트 패키지 — 매 세션마다 무엇이 주입되는가
OpenClaw는 세션 시작 시 여러 조각을 하나의 컨텍스트 패키지로 조립합니다.
SOUL.md는 에이전트의 정체성을 정의합니다. 매 세션마다 주입되는 파일이라, 여기 쓰는 내용이 토큰 비용에 직결됩니다.
# 에이전트 페르소나
당신은 백엔드 인프라 모니터링 에이전트입니다.
주요 역할: CI/CD 파이프라인 모니터링, 빌드 실패 분석, PR 자동 생성
## 경계값
- 프로덕션 데이터베이스에 직접 쓰기 작업 금지
- 외부 API 호출 전 승인 게이트 필요
- 민감 환경변수는 절대 로그에 출력하지 않음AGENTS.md는 프로젝트 수준의 행동 지침, TOOLS.md는 사용 가능한 스킬 목록입니다.
시맨틱 메모리 검색
여기서 흥미로운 부분이 시맨틱 검색으로 관련 과거 세션을 조회해서 주입한다는 겁니다. Markdown 파일을 수백 토큰 단위로 청킹하고, 일정 크기의 오버랩을 두어 임베딩 후 SQLite에 저장하는 구조로 알려져 있습니다. 파일 워처가 변경사항을 점진적으로 업데이트합니다. 정확한 청크 크기와 오버랩 값은 시점과 설정에 따라 다를 수 있으니, 실제 프로덕션에 넣기 전에 OpenClaw 세션·컨텍스트 관리 문서나 실제 소스 코드에서 확인하는 편이 안전합니다.
단순 전체 히스토리 주입이 아니라 현재 요청과 의미적으로 관련 있는 과거 세션만 선별해서 주입하기 때문에 컨텍스트 토큰을 효율적으로 씁니다. 이 방식이 외부 프로젝트에 영감을 줬다는 이야기도 있지만, 저는 1차 출처를 확인하지 못했기에 이 글에서는 인용하지 않겠습니다.
로컬 LLM 연동 — Ollama 설정에서 흔히 빠지는 함정
MCClaw는 앞서 짧게 소개한 대로 Cognitive Layer 안에서 로컬 LLM 추론을 담당하는 서브 컴포넌트입니다. Ollama의 /api/chat 엔드포인트에 직접 연결하는데, 여기서 많은 분들이 빠지는 함정이 있습니다.
# 잘못된 설정 — tool call이 무음으로 누락됨
mcclaw:
base_url: "http://localhost:11434/v1" # /v1 접미사 사용 시 tool call 누락
# 올바른 설정
mcclaw:
base_url: "http://localhost:11434" # /api/chat 엔드포인트 직접 연결
model: "qwen3:27b"키 표기는 OpenClaw 설정 파일에서 실제로 쓰이는 이름과 다를 수 있어, 도입 시 공식 스키마를 한 번 확인하는 편이 좋습니다. 본문에서는 컴포넌트 이름을 지칭할 때 MCClaw, 설정 키에서는 스네이크 케이스로 통일했습니다.
/v1 접미사를 붙이면 Ollama가 OpenAI 호환 엔드포인트로 라우팅되는데, 이 경우 스트리밍 중 tool_calls 델타 청크가 제대로 방출되지 않는 알려진 이슈가 있습니다. 에러 메시지도 없이 툴 호출이 그냥 사라집니다. 로컬 LLM 설정에서 툴 호출이 예상대로 동작하지 않는다면 이 부분부터 확인해보세요.
2026년 기준 OpenClaw 커뮤니티에서 자주 언급되는 로컬 모델은 Qwen3 계열과 Llama 3.x 계열입니다. 벤치마크 순위는 리포트마다 편차가 크고 프레임워크 자체 블로그의 성능 주장은 검증하기 어렵기 때문에, 실제 도입 전에는 자신의 태스크로 직접 A/B 테스트를 돌려보는 편이 훨씬 신뢰할 만합니다. Apple Silicon 통합 메모리 환경이나 최근 세대 GPU에서는 70B급 모델도 로컬 구동 사례가 늘고 있습니다. 자세한 설정 예시는 OpenClaw + Ollama 셋업 가이드를 참고하세요.
Lobster로 결정론적 멀티 에이전트 파이프라인 짜기
왜 결정론적 워크플로 엔진이 필요한가
단일 에이전트 ReAct 루프는 범용적이지만, 복잡한 자동화 파이프라인에서는 예측 가능성이 중요합니다. "에이전트가 알아서 판단하겠지"라는 구조는 디버깅이 어렵고, 프로덕션에서 신뢰하기가 쉽지 않습니다.
이를 위해 OpenClaw 생태계에는 Lobster 워크플로 엔진(openclaw/lobster)이 있습니다. TypeScript로 작성된 결정론적 DAG 워크플로 엔진으로, 단계 간 JSON 데이터 흐름, 승인 게이트, 재개 토큰을 지원합니다. npm 패키지명·조직명은 릴리스에 따라 변할 수 있으니, 실제 설치 시 GitHub 리포지토리의 package.json이나 npm 레지스트리를 확인해 실제 이름으로 import하세요. 아래 예시에서는 조직 스코프를 @openclaw/lobster로 표기합니다.
CI/CD 빌드 실패 자동 복구 파이프라인
실제 사례로 빌드 실패 감지 → 오류 분석 → PR 자동 생성 파이프라인을 Lobster로 구성하면 이런 구조입니다 (개념적 예시입니다).
import { Workflow, Step, ApprovalGate } from '@openclaw/lobster';
const buildRecoveryPipeline = new Workflow({
name: 'build-failure-recovery',
steps: [
new Step({
id: 'detect-failure',
agent: 'ci-monitor-agent',
input: (ctx) => ({ buildId: ctx.trigger.buildId }),
}),
new Step({
id: 'analyze-error',
agent: 'log-analyzer-agent',
input: (ctx) => ({ logs: ctx.steps['detect-failure'].output.errorLogs }),
}),
new ApprovalGate({
id: 'pr-approval',
message: (ctx) =>
`Root cause: ${ctx.steps['analyze-error'].output.summary}. PR 생성을 승인하시겠습니까?`,
}),
new Step({
id: 'create-fix-pr',
agent: 'code-fix-agent',
input: (ctx) => ({ rootCause: ctx.steps['analyze-error'].output.rootCause }),
}),
],
});앞선 초안 예시에는 스텝 출력을 별도 별칭(output: 'failureReport')으로 등록하면서 접근은 스텝 id로 하는 불일치가 있었는데, 여기서는 스텝 id로 접근하고 반환값은 .output을 통해 참조하는 방식으로 통일했습니다. 실제 API에 어떤 방식이 존재하는지는 반드시 Lobster 리포지토리 문서를 참조해서 맞춰야 합니다.
이 구조의 핵심은 각 단계가 독립적인 에이전트를 호출하지만, 전체 흐름은 DAG에 의해 결정론적으로 제어된다는 점입니다. 재개 토큰(resume token)도 실무에서 유용합니다. 승인 게이트에서 파이프라인이 멈춰 있을 때, 외부 시스템(Slack 봇, 웹훅 등)에서 토큰을 전달해 파이프라인을 이어서 실행할 수 있습니다.
이런 파이프라인으로 빌드 장애 복구 시간을 크게 줄였다는 팀 사례가 Context Studios의 프로덕션 도입기에 소개되어 있습니다. 자사 사례라는 성격을 감안해서 참고하시면 됩니다.
트레이드오프 — 솔직하게 말하면
OpenClaw가 모든 자동화 시나리오에 맞는 건 아닙니다. 아래 비교표는 OpenClaw를 Lobster까지 포함해서 봤을 때의 인상 평가입니다. ReAct 단독만 놓고 보면 "오픈엔디드 태스크"와 "예측 가능성" 축이 달라지므로, 아래 각주로 구분해두었습니다.
| 기준 | OpenClaw (+ Lobster) | n8n | AutoGPT | LangGraph |
|---|---|---|---|---|
| 실행 방식 | LLM 추론 기반 | 고정 흐름 | 자율 에이전트 | 그래프 기반 |
| 데이터 로컬화 | 완전 지원 | 설정 의존 | 설정 의존 | 설정 의존 |
| 예측 가능성 | Lobster 사용 시 높음¹ | 높음 | 낮음 | 중간 |
| 운영 복잡도 | 높음 | 낮음 | 중간 | 중간 |
| 오픈엔디드 태스크 | 명시적 DAG 설계 필요² | 불가 | 강함 | 중간 |
| 토큰 비용 | 높음 | 없음 | 높음 | 중간 |
| 감사 가능성 | 높음 (로컬 Markdown + JSONL) | 중간 | 낮음 | 중간 |
¹ ReAct 단독으로만 쓰면 다른 LLM 에이전트 프레임워크와 비슷한 수준의 비결정성을 갖습니다. ² AutoGPT 같은 완전 자율 방식과 달리, 자유도가 높은 목표는 DAG로 단계를 잘게 쪼개 정의해야 안정적으로 돕니다.
실무에서 자주 만나는 문제들
컨텍스트 폭발. SOUL.md, AGENTS.md, 과거 대화 요약, 스킬 목록이 모두 매 요청 컨텍스트에 주입됩니다. 설정 파일이 방만해지면 토큰 비용이 급격히 증가합니다. SOUL.md를 최대한 간결하게 유지하고, TOOLS.md에도 실제로 필요한 스킬만 포함하는 게 좋습니다.
오픈엔디드 태스크. "이 코드베이스에서 성능 문제를 찾아 수정해"처럼 자유도가 높은 목표는 OpenClaw가 AutoGPT류 자율 에이전트보다 제약적입니다. 이런 경우엔 Lobster DAG로 단계를 명시적으로 나눠 정의하는 편이 낫습니다.
Ollama 스트리밍 이슈. 앞서 언급한 /v1 스트리밍 버그가 여기에도 해당합니다. 툴 호출이 예상대로 안 오면 이 부분부터 확인하세요.
대용량 이벤트 기반 자동화. 각 상호작용마다 LLM이 추론하므로, 이벤트 수가 많은 시스템에서는 비용이 빠르게 올라갑니다. 단순 분기 로직이 대부분인 자동화라면 n8n 같은 고정 흐름 도구가 더 경제적입니다.
ReAct 단독과 Lobster DAG, 어떻게 나눠 쓸까
결국 이 글의 실용적인 결론은 하나입니다. 워크로드의 성격에 따라 ReAct 단독과 Lobster DAG를 나눠 쓴다.
- 탐색·조사형 태스크 — 코드베이스 분석, 로그에서 원인 추적, 리서치성 요약처럼 다음 스텝이 이전 결과에 따라 달라지는 작업은 ReAct 루프가 잘 맞습니다. 대신 TOOLS.md를 얇게 유지하고, 종료 조건이 되는 텍스트 응답 패턴을 자주 리뷰해야 합니다.
- 운영·복구형 태스크 — CI/CD 복구, 배포 자동화, 온콜 응대처럼 감사와 재현이 중요한 흐름은 Lobster DAG로 뼈대를 만들고, 각 스텝 안에서만 ReAct를 제한적으로 씁니다. 승인 게이트를 넣기 좋은 지점이 어디인지가 설계의 절반입니다.
- 경계에 있는 태스크 — 코드 리뷰 자동화 같은 케이스는 상위 흐름은 DAG(diff 수신 → 분석 → 코멘트 게시)로 잡고, 분석 스텝 내부만 ReAct에 맡기는 하이브리드가 잘 맞습니다.
반대로 단순 알림 파이프라인이나 데이터 변환처럼 "if A then B" 구조가 명확한 작업이라면, 굳이 OpenClaw를 들일 이유가 없습니다. n8n이나 자체 워커로 충분합니다.
내부 구조를 이해하고 나면 SOUL.md를 어디까지 줄여야 하는지, 어느 스텝에 승인 게이트를 넣어야 하는지, 어디서 컨텍스트가 폭발할 수 있는지가 훨씬 명확하게 보입니다. 파이프라인을 설계하는 사람 입장에서 프레임워크의 내부 흐름을 아는 것과 모르는 것은 실제 운영에서 꽤 큰 차이로 돌아옵니다.
참고 자료
- What is OpenClaw: Self-Hosted AI Agent Guide — Contabo Blog
- OpenClaw: The AI Agent Framework Explained (2026 Update) — clawbot.blog (프레임워크 자체 블로그, 성능 주장은 별도 검증 권장)
- Sessions & Context Management — OpenClaw Docs (DeepWiki)
- OpenClaw Memory System, Fully Explained — ai-coding.wiselychen.com
- GitHub - openclaw/lobster
- OpenClaw + Ollama Setup Guide — codersera.com
- OpenClaw vs. n8n — decodo.com
- OpenClaw vs AutoGPT vs CrewAI vs LangGraph
- How I Built a Deterministic Multi-Agent Dev Pipeline Inside OpenClaw — DEV Community
- The Complete OpenClaw Guide: How We Run an AI Agent in Production (2026) — Context Studios (자사 사례)
- Reference Architecture: OpenClaw (Early Feb 2026 Edition) — robotpaper.ai
- ReAct: Synergizing Reasoning and Acting in Language Models — Yao et al., 2022