OpenClaw 구축·운영 (10/26) — 해부: 단일 사용자 에이전트 구성 요소

-

부제: 마이그레이션 전 인벤토리 작성법 — 에이전트·cron·LaunchAgent·스크립트·스킬·메모리 계층

핵심 요약

  • OpenClaw는 다수의 에이전트, 스케줄러/데몬, 운영 스크립트, 스킬로 구성된 단일 사용자 에이전트 시스템이다.
  • 메모리는 4-tier(Identity / Curated / Project / Episode) 구조이며 oMLX bge-m3-mlx-fp16 임베딩에 hybrid 0.7/0.3 + MMR + 30일 temporal decay로 검색한다.
  • 이 글은 마이그레이션/재설계 전에 필요한 인벤토리 작성 프레임을 여러 레이어(에이전트 / 스케줄러 / OS 데몬 / 스크립트 군 / 스킬 / 메모리 계층 / 라우팅)로 정리하는 기술 문서다.

인벤토리가 먼저인 이유

에이전트 시스템을 다른 프레임워크로 옮기거나 재설계할 때 첫 작업은 코드 이식이 아니라 구성 요소 인벤토리다. 이유는 세 가지다.

  1. 리듬은 코드가 아니라 스케줄러에 박혀 있다. cron/LaunchAgent 목록을 누락하면 "왜 이 스크립트가 존재하는지"가 사라진다.
  2. 페르소나 수 ≠ 에이전트 수. 에이전트 개수는 모델 라우팅과 도구 권한의 분할일 뿐, 대화 창구의 수와 다르다. 이 구분이 없으면 타겟 시스템에서 profile 수를 과대 설계한다.
  3. 메모리 계층은 이식 단위가 다르다. Identity/Curated/Project/Episode는 각각 다른 저장소·주기·합의 규칙을 가진다. 계층별로 매핑해야 손실이 없다.

아래는 OpenClaw를 예시로 한 인벤토리 구조다. 동일 프레임을 임의의 멀티 에이전트 시스템에 적용할 수 있다.

1. 에이전트 레이어 — 대화 창구 1개 + 백엔드 작업자 N개

대화 인터페이스는 mir 하나이며 나머지는 전부 백엔드 작업자다. 에이전트 분할 축은 두 가지: 모델 등급과 도구 권한.

대표적인 분할 예시:

역할군 모델 등급 예시 담당
대화 창구 고판단 LLM (high) 유일한 대화 창구, 라우팅
시스템 모니터 로컬 oMLX 시스템 상태
리서치 경량 LLM 웹 리서치, AutoSearch Deep
글쓰기 중급 LLM 콘텐츠 작성
코딩/오케스트레이션 코드 특화 LLM CLI, subagent/skill 팩토리
메모리 의미 판단 중급 LLM Reflect 판단
메모리 I/O 로컬 oMLX bank/ 파일 I/O
외부 통합 경량 LLM Google Workspace, 메신저 송신 등

(외 다수의 백엔드 작업자)

작동 원리: 사용자에게 노출되는 페르소나는 단일(mir)이고, 뒤쪽에서 모델 등급·비용·지연 특성에 따라 작업이 분배된다. 로컬 임베딩·파일 I/O에는 oMLX/Gemma를, 의미 판단에는 gemini-2.5-flash를, 고판단 작업에는 gpt-5.4 high를 할당하는 구조다.

2. 스케줄러 레이어 — cron이 만드는 시스템 리듬

대표적인 시간 해상도별 작업 예시:

주기 작업 유형
일간 (새벽) Reflect — 의미 통합
시간당 memory micro-cycle — 단기 메모리 정리
일간 (밤) self-review — 행동 점검, daily-summary
분 단위 폴링 외부 소스 스캔 (리서치, 커뮤니티)
월간 장기 메모리 리뷰

(외 다수의 스케줄 작업)

작동 원리: cron은 단순 스케줄러가 아니라 에이전트의 사고 리듬을 결정한다. 새벽 Reflect(의미 통합), 시간당 micro-cycle(단기 메모리 정리), 밤 self-review(행동 점검), 월간 review(장기 패턴 압축)가 각기 다른 시간 해상도로 돌면서 메모리 휘발을 막는다. 이식 시에는 "어느 시스템이 이 4단계 주기를 보존할 수 있는가"가 판단 기준이 된다.

3. OS 데몬 레이어 — macOS LaunchAgent

OS 레벨에서 상주해야 하는 프로세스:

  • ai.openclaw.gateway — Gateway 데몬 (포트 18789)
  • ai.openclaw.update-check — 자동 업데이트
  • com.openclaw.omlx / omlx-proxy — 로컬 임베딩 모델 서버
  • com.openclaw.daily-audit — 05:00 일일 감사 Phase A~E
  • com.claude-agent.watchdog / autostart — 세션 워치독

한계: LaunchAgent는 macOS 전용이므로 Linux/컨테이너 타겟으로 옮길 경우 systemd 유닛 또는 supervisord로 1:1 치환이 필요하다. 포트 바인딩(18789)과 오디트 Phase A~E는 OS 비의존 레이어로 분리 가능.

4. 스크립트 레이어 — 다수의 운영 스크립트, 기능별 군 분류

스크립트는 기능별로 다음 군에 속한다.

  • 메모리 파이프라인: retain-extract/merge, recall-tree/match, confidence-decay, topics-validate/expand, user-pattern-stage.
  • Heartbeat: heartbeat-router/update/tick/health, proactive-exception-alerts.
  • Self-Review: self-review-prescan/apply/fix, skill-candidate-stage.
  • Daily Audit: docs-snapshot, release-check, agent-linter, config-drift, cron-analytics, session-audit.
  • 외부 통합: scrape.py (Scrapling + playwright), gws-wrapper, omlx-serve.

적용 가능 패턴: 메모리 파이프라인의 confidence-decay와 topics-validate/expand는 장기 메모리 시스템 일반에 이식 가능한 독립 유닛이다. Heartbeat 군은 분산 에이전트 헬스 모니터링의 표준형에 가깝다.

5. 스킬 레이어 — 범용 + 전용

  • 범용 워크플로우: brainstorming, writing-plans, verification, deep-interview, code-review, testing, git-commit, project-doctor, self-audit.
  • OpenClaw 전용: oc-config, oc-agent, oc-channel, oc-skill, oc-memory, oc-doctor, oc-deploy, oc-backup.

분리 기준: 범용 스킬은 프레임워크 독립적이라 이식 시 원문 유지 가능. 전용 스킬은 해당 시스템의 설정 스키마·배포 경로에 묶여 있어 타겟 시스템의 동등 개념으로 재작성이 필요하다.

6. 메모리 v0.6 — 4-tier 계층

  • Identity: MEMORY.md (~600 토큰). 정체성·고정 선호. 변경 빈도 최저.
  • Curated: bank/ (world / experience / opinions / patterns / topics / index). 합성된 지식. Reflect가 갱신.
  • Project: bank/entities/. 엔티티별 축적.
  • Episode: memory/ (일일 로그). 원천 이벤트.

검색 메커니즘: oMLX bge-m3-mlx-fp16 임베딩 + hybrid 0.7/0.3 (vector / keyword) + MMR + 30일 temporal decay. Reflect는 6 Phase 파이프라인이고, U-tag(사용자 관련 판단)는 관찰 → 가설 → 검증의 3-phase dialectic으로 처리된다.

이식 관점: 4-tier는 저장 주기와 변경 권한이 계층마다 다르다. Identity는 수동, Curated는 Reflect(의미 판단 에이전트), Project는 혼합, Episode는 자동 append. 타겟 시스템이 이 권한 분할을 지원하지 않으면 일관성이 깨진다.

7. 채널 라우팅 레이어

  • Discord 주채널 1개에 Reflect 결과와 self-review 결과가 모두 흐른다.
  • Telegram Forum 다중 토픽: General / Server / Bot / Research / Memory / Heartbeat.

설계 원리: Discord는 단일 스트림(고밀도 판단 결과), Telegram은 다중 토픽(분류된 실시간 이벤트)으로 역할을 분리한다. 이벤트 빈도와 독해 비용의 trade-off가 기준.

인벤토리에서 드러나는 두 가지 구조적 사실

평면도를 완성하면 두 가지가 구조적으로 드러난다.

첫째, 메모리·heartbeat·self-review는 코드가 아니라 리듬이다. cron/LaunchAgent가 곧 시스템의 사고 주기이며, 옮길 그릇이 이 주기를 보존할 수 있는지가 이식 가능성의 핵심 판단 기준이다.

둘째, 에이전트 수는 페르소나 수가 아니다. 다수의 에이전트 중 대화 창구는 1개이며 나머지는 모델 등급·도구 권한의 축으로 분할된 작업자다. 따라서 타겟 시스템에서는 더 적은 profile로도 동등한 기능을 구성할 수 있다.

적용 가능 범위와 열린 질문

적용 가능 범위: - 멀티 에이전트 시스템을 타 프레임워크로 이식/재설계하는 경우. - 메모리 계층이 2-tier 이상으로 분리된 시스템의 감사/이식 체크리스트. - cron/LaunchAgent 기반 장기 실행 에이전트의 리듬 보존 설계.

열린 질문: - 4-tier 메모리에서 Curated와 Project 경계는 어디가 최적인가. 엔티티 중심 시스템에서는 두 계층이 병합 가능성이 있다. - 단일 페르소나 + N 작업자 모델이 지속 가능한 상한은 어디인가. 에이전트 수가 늘수록 라우팅 판단 비용이 O(N) 이상으로 증가할 가능성. - cron 기반 리듬을 이벤트 기반으로 치환할 때 의미 통합(Reflect) 품질이 유지되는가.

다음 글에서는 위 레이어들을 Hermes 내장 기능과 1:1로 매핑한 표를 제시한다. 분류는 4 카테고리: 대체 / 부분 대체 / 보존 이식 / 폐기.

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »