Skip to content

docs(okayJing): 오케이징 시리즈 초기 포스트 4편 #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
seoJing merged 2 commits into from
May 11, 2026
Merged

docs(okayJing): 오케이징 시리즈 초기 포스트 4편 #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
383ad2e
docs(okayJing): 오케이징 시리즈 초기 포스트 4편 추가
seoJing May 11, 2026
3dfbf61
style(okayJing): prettier 포맷 수정
seoJing May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
321 changes: 321 additions & 0 deletions apps/web/content/okayJing/big-picture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,321 @@
---
title: "Layer 0 — OpenClaw 큰 그림"
date: 2026-05-08
tags:
- okayJing
- OpenClaw
- 인프라
- 아키텍처
description: OpenClaw를 처음 한 바퀴 돌릴 때 머리에 박아두면 좋은 6개 추상화와, 진규 머신 위에서 실제로 그것이 어떻게 배치되어 있는지의 좌표계를 잡는 글.
---

<Subtitle level={2}>0. 오늘의 목적</Subtitle>

<Paragraph>
이 글의 목표는 한 가지입니다.{" "}
<strong>
OpenClaw 위에서 일어나는 모든 일을 같은 평면 위에 얹어 볼 수 있는 좌표계
</strong>
를 머리에 만드는 것. 좌표계가 잡혀 있으면 다음 글들은 그 위에 점을 찍는 작업이
되고, 좌표가 없으면 글마다 각기 다른 평면 위에서 헤매게 됩니다.
</Paragraph>

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

- <strong>OpenClaw가 무엇인가</strong>를 한 문장으로 박아두기
- 그 한 문장이 풀어지는 <strong>6개의 추상화</strong>를 한 다이어그램으로 보기
- 그 추상화가 진규 머신에서 실제로 어떻게 살아 있는지 <strong>스냅샷</strong>으로 확인하기
- 어디에 무엇이 사는지 <strong>3개의 디렉토리</strong>로 위치 잡기
- 마지막으로 모델·채널·보안의 작은 디테일들 짚기

---

<Subtitle level={2}>1. OpenClaw를 한 문장으로 박아두자</Subtitle>

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

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

---

<Subtitle level={2}>2. 6개의 추상화 (좌표계의 본체)</Subtitle>

<Paragraph>
처음 한 번만 머리에 박아두시면 다른 모든 글이 이 좌표 위에 얹혀서 읽힙니다. 세
줄로 요약하면 이렇습니다.{" "}
<strong>
외부에서 들어온 메시지가 어떤 에이전트의 어떤 세션으로 가서, 그 세션이 어떤
도구·스킬을 쓰고, 결과를 어떤 메모리에 남기느냐.
</strong>
</Paragraph>

```
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) (자아 · 작업 · 메모리)
```

<Paragraph>각 층을 한 줄씩 풀면 다음과 같습니다.</Paragraph>

| 층 | 한 줄 정의 |
| :------------ | :----------------------------------------------------------------------------------- |
| **Channel** | 외부 세계와의 입출력. "텔레그램의 진규" → 적절한 에이전트 세션으로 라우팅합니다. |
| **Agent** | 페르소나·시스템 프롬프트·기본 모델을 묶은 단위. 진규 환경엔 main과 spot-bot 둘. |
| **Session** | 대화 컨텍스트 한 개. (channel, target) 쌍이 키. fork·isolated·sub도 같은 추상화. |
| **Tools** | 에이전트가 일을 하는 손. 코어 도구는 항상 있고 정책으로 켜고 끕니다. |
| **Skills** | 도구 위에 얹힌 패턴화된 작업 가이드. SKILL.md 한 개로 정의되고 trigger로 로드됩니다. |
| **Memory** | 세션 너머의 영속 저장소. 종류가 여러 개입니다 — Layer 2에서 자세히 다룹니다. |
| **Gateway** | 위 전부를 묶는 로컬 서버. config 단일 진실. 보통 systemd로 띄워둡니다. |
| **Workspace** | 진규의 자아·프로젝트·메모리 파일이 사는 디렉토리. |

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

---

<Subtitle level={2}>3. 진규 머신에서 실제로 도는 모습</Subtitle>

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

```
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)
```

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

| 세션 키 | 종류 | 모델 | 비고 |
| :--------------------------------- | :----- | :-------------- | :---------------------- |
| `agent:main:telegram:direct:5626…` | direct | claude-opus-4-7 | 지금 진규와 나누는 대화 |
| `agent:main:main` | direct | gpt-5.5 | TUI 메인 세션 |
| `agent:main:subagent:1d1d…` | direct | gpt-5.5 | 백그라운드 sub-agent |
| `agent:main:cron:59ef…` | direct | gpt-5.5 | cron 잡이 띄운 워커 |
| `agent:spot-bot:discord:channel:…` | group | gpt-5.5 | spot 캡스톤 디스코드 봇 |

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

- 같은 <strong>main</strong> 에이전트라도 채널마다 세션이 따로 떠 있고 모델도
다릅니다. 텔레그램 직대화는 Claude Opus 4.7, TUI는 gpt-5.5입니다. 즉 "에이전
트의 모델"은 고정값이 아니라 채널·맥락에 따라 라우팅됩니다.
- cron이나 sub-agent도 일반 세션과 같은 키 규칙을 사용합니다.{" "}
<strong>cron 잡 = 잠깐 떴다 죽는 세션</strong>이라는 추상화가 일관되게 적용
되어 있어서, 다른 도구로도 같은 세션을 들여다볼 수 있습니다.

---

<Subtitle level={2}>4. 3대 디렉토리 — 어디서 무엇이 사는가</Subtitle>

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

<Subtitle level={3}>
4-1. <code>~/.openclaw/</code> — 게이트웨이 운영 데이터
</Subtitle>

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

```
~/.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/ → 진규 워크스페이스 마운트
```

<Subtitle level={3}>
4-2. <code>~/.openclaw/workspace/</code> — 자아·작업 공간
</Subtitle>

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

```
~/.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/
```

<Subtitle level={3}>4-3. OpenClaw 코어 자체</Subtitle>

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

---

<Subtitle level={2}>5. 모델 라우팅의 작은 디테일</Subtitle>

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

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

- "이 세션은 어떤 모델로 도는가"를 세션 status에서 직접 확인하는 습관이
필요합니다.
- 모델 마이그레이션(예: Claude Max 만료 → Codex/gpt-5.5 통일)을 할 때 에이전트
정의만 바꿔도 안 되고, 채널·세션별 override를 모두 훑어야 합니다.

<Paragraph>이 부분은 Layer 1에서 더 깊이 다룹니다.</Paragraph>

---

<Subtitle level={2}>6. 채널 / 알림 라우팅 한눈에</Subtitle>

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

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

---

<Subtitle level={2}>7. 보안 — 지금 켜진 4개의 노란불</Subtitle>

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

| 항목 | 의미 | 외부 노출 시 액션 |
| :----------------------------------------- | :------------------------------------------------------- | :--------------------------- |
| `gateway.bind=loopback` + `trustedProxies` | 로컬 루프백만 열림. 리버스 프록시 신뢰 IP 미설정. | 프록시를 띄우면 화이트리스트 |
| `controlUi.allowInsecureAuth=true` | 컨트롤 UI 인증 완화 모드. 디바이스 인증 우회는 아닙니다. | 외부 노출 전에 끔 |
| 위험 플래그 1개 활성 | 위와 동일 항목 (별도 카운트) | 운영 시 끔 |
| `nodes.denyCommands` 일부 무효 | 정확한 명령 ID 매칭만 동작. 텍스트 패턴은 매칭하지 않음. | denyCommands 표현식 정정 |

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

---

<Subtitle level={2}>8. 정리 — 다음 글로 가기 전에</Subtitle>

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

- OpenClaw는 <strong>에이전트 OS</strong>이고, <strong>gateway 프로세스 한 개</strong>가
거의 모든 것을 잡고 있습니다.
- 좌표는 <strong>6개 추상화</strong>(Channel · Agent · Session · Tools · Skills
· Memory) + 두 장소(Gateway · Workspace)로 잡습니다.
- 디렉토리는 셋입니다. 운영 데이터(<code>{"~/.openclaw/"}</code>), 자아와 작업(<code>{"~/.openclaw/workspace/"}</code>), 코어 npm 모듈.
- 모델은 에이전트 단위 디폴트 + 세션·요청 단위 override로 굴러갑니다.

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

| 할 일 | 한 줄 이유 |
| :---------------------------------------------- | :---------------------------------------------- |
| `openclaw status --deep` 한 번 돌리기 | probe까지 켠 상태가 어떤지 감을 잡습니다 |
| Dashboard `http://127.0.0.1:18789/` 들어가 보기 | UI에서 본 모양도 머리에 같이 박아두면 좋습니다 |
| `~/.openclaw/openclaw.json` 첫 50줄만 훑기 | config의 톤(섹션 구분, 키 명명 규칙)을 잡습니다 |

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