Layer 0 — OpenClaw 큰 그림

0. 오늘의 목적

이 글의 목표는 한 가지입니다.

OpenClaw 위에서 일어나는 모든 일을 같은 평면 위에 얹어 볼 수 있는 좌표계

를 머리에 만드는 것. 좌표계가 잡혀 있으면 다음 글들은 그 위에 점을 찍는 작업이 되고, 좌표가 없으면 글마다 각기 다른 평면 위에서 헤매게 됩니다.

오늘 잡을 것을 미리 말씀드리면 다음과 같습니다.

• OpenClaw가 무엇인가를 한 문장으로 박아두기

• 그 한 문장이 풀어지는 6개의 추상화를 한 다이어그램으로 보기

• 그 추상화가 진규 머신에서 실제로 어떻게 살아 있는지 스냅샷으로 확인하기

• 어디에 무엇이 사는지 3개의 디렉토리로 위치 잡기

• 마지막으로 모델·채널·보안의 작은 디테일들 짚기

1. OpenClaw를 한 문장으로 박아두자

OpenClaw는 진규 머신에서 도는 에이전트 OS입니다. 여러 LLM 에이전트가 같은 도구·스킬·메모리·외부 채널을 공유하면서 일할 수 있게 묶어 주는 로컬 런타임입니다. 운영은 openclaw CLI로 하고, 코어 역할을 하는 프로세스 한 개(gateway)가 거의 모든 것을 잡고 있습니다.

"에이전트 OS"라는 단어가 광고처럼 들릴 수 있지만, 실제로 OS의 시점에서 보면 편합니다. OS가 프로세스·파일·디바이스를 추상화해서 앱에 빌려주듯, OpenClaw는 채널·세션·도구·스킬·메모리를 추상화해서 LLM 에이전트들에게 빌려줍니다. 그러면 에이전트는 자기 인격(시스템 프롬프트와 페르소나)에만 집중하면 됩니다.

2. 6개의 추상화 (좌표계의 본체)

처음 한 번만 머리에 박아두시면 다른 모든 글이 이 좌표 위에 얹혀서 읽힙니다. 세 줄로 요약하면 이렇습니다.

외부에서 들어온 메시지가 어떤 에이전트의 어떤 세션으로 가서, 그 세션이 어떤 도구·스킬을 쓰고, 결과를 어떤 메모리에 남기느냐.

                          CHANNELS
        (telegram · discord · web · iPad · macOS · whatsapp …)
                              │ 메시지 in/out
                              ▼
                           AGENTS
              (main = 오케이징 · spot-bot · 사용자 정의)
                              │
                ┌─────────────┴─────────────┐
                ▼                           ▼
            SESSIONS                     SUBAGENTS
        (direct · group)              (spawned · forked)
                │                           │
                └──────────────┬────────────┘
                               ▼
                             TOOLS
   exec · process · browser · canvas · nodes · cron · gateway ·
   sessions_* · subagents · web_fetch · web_search · message …
                               │
                               ▼
                            SKILLS
        system (내장) + plugin (clawhub 등) + workspace (개인)
                               │
                               ▼
                            MEMORY
   workspace daily · curated MEMORY.md · active-memory ·
   honcho/qmd (옵션) · vector / fts 인덱스
                               │
                  ┌────────────┴────────────┐
                  ▼                         ▼
              GATEWAY                   WORKSPACE
       ws://127.0.0.1:18789       ~/.openclaw/workspace/
       (config · routing · log)   (자아 · 작업 · 메모리)

각 층을 한 줄씩 풀면 다음과 같습니다.

표가 다소 빽빽해 보일 수 있지만, 정말 외워야 하는 것은 위쪽의 5개 (Channel · Agent · Session · Tools · Skills · Memory) 흐름입니다. Gateway와 Workspace는 그것들이 사는 "장소"라고 보시면 됩니다.

3. 진규 머신에서 실제로 도는 모습

추상화는 잡혔으니, 같은 추상화가 진규 머신에서는 어떤 모습으로 살아 있는지 스냅샷으로 봅니다. 시점은 2026-05-08 오전 10시 무렵입니다.

OS               Linux 6.6.87.2 WSL2 / node v22.22.2
Dashboard        http://127.0.0.1:18789/
Gateway          systemd active (pid 313), local loopback only
Channel          stable (default), 업데이트 가능 (2026.5.7)
Agents           2 (main · spot-bot)
Sessions active  12
Memory           12 files / 137 chunks · plugin "memory-core"
Tasks            0 active / 16 tracked / 1 audit warn / 3 issues
Heartbeat        main = 1h, spot-bot = disabled
Default model    gpt-5.5 (200k ctx)

활성 세션을 들여다보면 추상화가 어떻게 한 줄씩 인스턴스화되는지 보입니다.

여기서 짚어두면 좋은 패턴이 두 가지입니다.

• 같은 main 에이전트라도 채널마다 세션이 따로 떠 있고 모델도 다릅니다. 텔레그램 직대화는 Claude Opus 4.7, TUI는 gpt-5.5입니다. 즉 "에이전 트의 모델"은 고정값이 아니라 채널·맥락에 따라 라우팅됩니다.

• cron이나 sub-agent도 일반 세션과 같은 키 규칙을 사용합니다. cron 잡 = 잠깐 떴다 죽는 세션이라는 추상화가 일관되게 적용 되어 있어서, 다른 도구로도 같은 세션을 들여다볼 수 있습니다.

4. 3대 디렉토리 — 어디서 무엇이 사는가

OpenClaw로 일하다 보면 결국 이 셋만 머리에 박아두시면 됩니다.

4-1. ~/.openclaw/ — 게이트웨이 운영 데이터

거의 손대지 않는 영역입니다. 게이트웨이가 자기 살림을 하는 곳입니다. 가장 중요한 파일은 openclaw.json(설정 단일 진실)이고, 이것은 직접 손대지 않고 gateway 도구로 patch/apply 합니다. 자동 백업이 .bak 시리즈로 같이 살아 있어서 문제가 생기면 롤백할 수 있습니다.

~/.openclaw/
├── openclaw.json            ← gateway config (단일 진실)
├── openclaw.json.bak{,.1,.2,.3,.4}  ← 자동 백업
├── openclaw.json.last-good  ← 마지막 성공 적용본
├── agents/                  ← 에이전트 정의 (main, spot-bot)
├── cron/, tasks/, flows/    ← 시간·자동화 레이어 상태
├── plugins/, plugin-runtime-deps/
├── credentials/, identity/  ← 인증 자료
├── logs/, gateway-startup.log  ← 디버깅의 첫 출발점
├── delivery-queue/, telegram/, discord/  ← 채널별 in-flight 큐
├── canvas/, devices/, media/
└── workspace/  → 진규 워크스페이스 마운트

4-2. ~/.openclaw/workspace/ — 자아·작업 공간

여기가 진규의 "OS 위에 깔린 홈디렉토리"에 해당합니다. 자아 파일들과 일별 메모리, 프로젝트 클론, 운영 노트, 워크스페이스 스킬이 모두 여기에 삽니다. 세션 시작 시 자동으로 읽히는 파일도 다 이쪽에 있습니다.

~/.openclaw/workspace/
├── AGENTS.md SOUL.md IDENTITY.md USER.md TOOLS.md HEARTBEAT.md
├── PROJECTS.md NOJINGU.md  ← 운영용 메타
├── memory/        일별 daily 노트 (raw 로그)
├── planning/      스프린트·로드맵 (이 시리즈의 준비 메모도 여기서 자랐습니다)
├── state/         운영 상태 (handoff-to-hermes.md, hermes-runs/ …)
├── projects/      프로젝트 클론 (SEOJing, frontend, backend, …)
├── skills/        워크스페이스 스킬 (ideation, ppt-editorial-js, lazyweb-* …)
├── integrations/  google_calendar, kyonggi-lms
├── archives/      이전 작업물
└── claude/, synthetic-content-pipeline/

4-3. OpenClaw 코어 자체

npm으로 설치된 OpenClaw의 본체입니다. 진규 환경에서는 ~/.local/share/fnm/.../node_modules/openclaw/에 있습니다. 이 안에서 자주 들여다보게 되는 폴더는 셋입니다. docs/(공식 문서), skills/(시스템 스킬), dist/(컴파일된 런타임). 시스템 스킬은 모든 에이전트가 공유 하고, 워크스페이스 스킬은 진규 한정, 플러그인 스킬은 그 사이에 위치합니다.

5. 모델 라우팅의 작은 디테일

OpenClaw는 모델을 "에이전트 단위 디폴트 + 세션·요청 단위 override" 방식으로 잡습니다. 같은 main 에이전트라도 어디서 부르느냐에 따라 다른 모델이 뜨는 이유입니다. 위 세션 표에서 텔레그램 direct가 Claude Opus 4.7, TUI가 gpt-5.5인 것이 그 결과입니다.

실용적으로는 두 가지 결과가 따라옵니다.

• "이 세션은 어떤 모델로 도는가"를 세션 status에서 직접 확인하는 습관이 필요합니다.

• 모델 마이그레이션(예: Claude Max 만료 → Codex/gpt-5.5 통일)을 할 때 에이전트 정의만 바꿔도 안 되고, 채널·세션별 override를 모두 훑어야 합니다.

이 부분은 Layer 1에서 더 깊이 다룹니다.

6. 채널 / 알림 라우팅 한눈에

들어오는 방향과 나가는 방향이 거울 구조입니다. 들어오는 쪽은 "외부 메시지 → 채널 어댑터 → 세션 리졸버 → 에이전트 세션 → 모델 호출 → 응답 → 채널 출력"의 흐름입니다. 나가는 쪽은 에이전트가 openclaw message send를 호출하면 채널 어댑터가 외부 surface로 돌려줍니다.

나가는 쪽에서 한 가지 정해야 하는 것이 있습니다. "누가 push 버튼을 누르는가"입니다. 코딩 위임을 Hermes에 넘긴 케이스를 예로 들면, Hermes가 직접 push 버튼을 누르게 둘 수도 있고, 오케이징이 결과를 받아서 검토 후 push할 수도 있습니다. 진규 환경은 최근에 후자로 바꿨습니다 — 검토 단계가 빠지면 컨텍스트가 즉시 증발하기 때문입니다. 이 결정은 Layer 4(위임)에서 진하게 다룹니다.

7. 보안 — 지금 켜진 4개의 노란불

openclaw status의 보안 audit이 지금 4개의 warn을 띄웁니다. 모두 의도된 상태이지만, 외부 노출을 시작할 때 다시 들여다봐야 할 자리들이라 적어둡니다.

지금은 머신이 닫혀 있고 Tailscale도 꺼져 있어서 위험은 0에 가깝습니다. 모바일 노드를 본격적으로 페어링하기 시작하면 이 표가 다시 살아납니다. Layer 6에서 이어서 다룹니다.

8. 정리 — 다음 글로 가기 전에

여기까지가 좌표계입니다. 머리에 남기면 좋은 것을 한 번 더 짚어봅니다.

• OpenClaw는 에이전트 OS이고, gateway 프로세스 한 개가 거의 모든 것을 잡고 있습니다.

• 좌표는 6개 추상화(Channel · Agent · Session · Tools · Skills · Memory) + 두 장소(Gateway · Workspace)로 잡습니다.

• 디렉토리는 셋입니다. 운영 데이터(~/.openclaw/), 자아와 작업(~/.openclaw/workspace/), 코어 npm 모듈.

• 모델은 에이전트 단위 디폴트 + 세션·요청 단위 override로 굴러갑니다.

다음 글을 시작하기 전에 직접 해보면 좋은 정찰이 셋 있습니다.

Layer 1에서는 이 좌표 위의 가장 무거운 한 점인 gateway를 직접 분해합니다. config schema, hot-reload 가능한 부분과 restart가 필요한 부분, 세션 모델, 도구 정책 — 다음 글에서 함께 보겠습니다.