이 글의 목표는 한 가지입니다.
OpenClaw 위에서 일어나는 모든 일을 같은 평면 위에 얹어 볼 수 있는 좌표계
를 머리에 만드는 것. 좌표계가 잡혀 있으면 다음 글들은 그 위에 점을 찍는 작업이 되고, 좌표가 없으면 글마다 각기 다른 평면 위에서 헤매게 됩니다.
OpenClaw는 진규 머신에서 도는 에이전트 OS입니다. 여러 LLM
에이전트가 같은 도구·스킬·메모리·외부 채널을 공유하면서 일할 수 있게 묶어 주는
로컬 런타임입니다. 운영은 openclaw CLI로 하고, 코어 역할을 하는
프로세스 한 개(gateway)가 거의 모든 것을 잡고 있습니다.
"에이전트 OS"라는 단어가 광고처럼 들릴 수 있지만, 실제로 OS의 시점에서 보면 편합니다. OS가 프로세스·파일·디바이스를 추상화해서 앱에 빌려주듯, OpenClaw는 채널·세션·도구·스킬·메모리를 추상화해서 LLM 에이전트들에게 빌려줍니다. 그러면 에이전트는 자기 인격(시스템 프롬프트와 페르소나)에만 집중하면 됩니다.
처음 한 번만 머리에 박아두시면 다른 모든 글이 이 좌표 위에 얹혀서 읽힙니다. 세 줄로 요약하면 이렇습니다.
외부에서 들어온 메시지가 어떤 에이전트의 어떤 세션으로 가서, 그 세션이 어떤 도구·스킬을 쓰고, 결과를 어떤 메모리에 남기느냐.
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) (자아 · 작업 · 메모리)
| 층 | 한 줄 정의 |
|---|---|
| Channel | 외부 세계와의 입출력. "텔레그램의 진규" → 적절한 에이전트 세션으로 라우팅합니다. |
| Agent | 페르소나·시스템 프롬프트·기본 모델을 묶은 단위. 진규 환경엔 main과 spot-bot 둘. |
| Session | 대화 컨텍스트 한 개. (channel, target) 쌍이 키. fork·isolated·sub도 같은 추상화. |
| Tools | 에이전트가 일을 하는 손. 코어 도구는 항상 있고 정책으로 켜고 끕니다. |
| Skills | 도구 위에 얹힌 패턴화된 작업 가이드. SKILL.md 한 개로 정의되고 trigger로 로드됩니다. |
표가 다소 빽빽해 보일 수 있지만, 정말 외워야 하는 것은 위쪽의 5개 (Channel · Agent · Session · Tools · Skills · Memory) 흐름입니다. Gateway와 Workspace는 그것들이 사는 "장소"라고 보시면 됩니다.
추상화는 잡혔으니, 같은 추상화가 진규 머신에서는 어떤 모습으로 살아 있는지 스냅샷으로 봅니다. 시점은 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)
활성 세션을 들여다보면 추상화가 어떻게 한 줄씩 인스턴스화되는지 보입니다.
| 세션 키 | 종류 | 모델 | 비고 |
|---|---|---|---|
agent:main:telegram:direct:5626… | direct | claude-opus-4-7 | 지금 진규와 나누는 대화 |
agent:main:main | direct | gpt-5.5 | TUI 메인 세션 |
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/
npm으로 설치된 OpenClaw의 본체입니다. 진규 환경에서는
~/.local/share/fnm/.../node_modules/openclaw/에 있습니다. 이
안에서 자주 들여다보게 되는 폴더는 셋입니다. docs/(공식
문서), skills/(시스템 스킬),
dist/(컴파일된 런타임). 시스템 스킬은 모든 에이전트가 공유
하고, 워크스페이스 스킬은 진규 한정, 플러그인 스킬은 그 사이에 위치합니다.
OpenClaw는 모델을 "에이전트 단위 디폴트 + 세션·요청 단위 override" 방식으로 잡습니다. 같은 main 에이전트라도 어디서 부르느냐에 따라 다른 모델이 뜨는 이유입니다. 위 세션 표에서 텔레그램 direct가 Claude Opus 4.7, TUI가 gpt-5.5인 것이 그 결과입니다.
들어오는 방향과 나가는 방향이 거울 구조입니다. 들어오는 쪽은 "외부 메시지 →
채널 어댑터 → 세션 리졸버 → 에이전트 세션 → 모델 호출 → 응답 → 채널 출력"의
흐름입니다. 나가는 쪽은 에이전트가 openclaw message send를
호출하면 채널 어댑터가 외부 surface로 돌려줍니다.
나가는 쪽에서 한 가지 정해야 하는 것이 있습니다. "누가 push 버튼을 누르는가"입니다. 코딩 위임을 Hermes에 넘긴 케이스를 예로 들면, Hermes가 직접 push 버튼을 누르게 둘 수도 있고, 오케이징이 결과를 받아서 검토 후 push할 수도 있습니다. 진규 환경은 최근에 후자로 바꿨습니다 — 검토 단계가 빠지면 컨텍스트가 즉시 증발하기 때문입니다. 이 결정은 Layer 4(위임)에서 진하게 다룹니다.
openclaw status의 보안 audit이 지금 4개의 warn을 띄웁니다. 모두
의도된 상태이지만, 외부 노출을 시작할 때 다시 들여다봐야 할 자리들이라
적어둡니다.
| 항목 | 의미 | 외부 노출 시 액션 |
|---|---|---|
gateway.bind=loopback + trustedProxies | 로컬 루프백만 열림. 리버스 프록시 신뢰 IP 미설정. | 프록시를 띄우면 화이트리스트 |
controlUi.allowInsecureAuth=true | 컨트롤 UI 인증 완화 모드. 디바이스 인증 우회는 아닙니다. | 외부 노출 전에 끔 |
| 위험 플래그 1개 활성 | 위와 동일 항목 (별도 카운트) |
지금은 머신이 닫혀 있고 Tailscale도 꺼져 있어서 위험은 0에 가깝습니다. 모바일 노드를 본격적으로 페어링하기 시작하면 이 표가 다시 살아납니다. Layer 6에서 이어서 다룹니다.
여기까지가 좌표계입니다. 머리에 남기면 좋은 것을 한 번 더 짚어봅니다.
~/.openclaw/), 자아와 작업(~/.openclaw/workspace/), 코어 npm 모듈.다음 글을 시작하기 전에 직접 해보면 좋은 정찰이 셋 있습니다.
| 할 일 | 한 줄 이유 |
|---|---|
openclaw status --deep 한 번 돌리기 | probe까지 켠 상태가 어떤지 감을 잡습니다 |
Dashboard http://127.0.0.1:18789/ 들어가 보기 | UI에서 본 모양도 머리에 같이 박아두면 좋습니다 |
~/.openclaw/openclaw.json 첫 50줄만 훑기 | config의 톤(섹션 구분, 키 명명 규칙)을 잡습니다 |
Layer 1에서는 이 좌표 위의 가장 무거운 한 점인 gateway를 직접 분해합니다. config schema, hot-reload 가능한 부분과 restart가 필요한 부분, 세션 모델, 도구 정책 — 다음 글에서 함께 보겠습니다.
| Memory | 세션 너머의 영속 저장소. 종류가 여러 개입니다 — Layer 2에서 자세히 다룹니다. |
| Gateway | 위 전부를 묶는 로컬 서버. config 단일 진실. 보통 systemd로 띄워둡니다. |
| Workspace | 진규의 자아·프로젝트·메모리 파일이 사는 디렉토리. |
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 캡스톤 디스코드 봇 |
| 운영 시 끔 |
nodes.denyCommands 일부 무효 | 정확한 명령 ID 매칭만 동작. 텍스트 패턴은 매칭하지 않음. | denyCommands 표현식 정정 |