🦞 03. 핵심개념

Agent/🚀 OpenClaw/images/openclaw-03-핵심개념-diagram.svg

설치를 마치고 첫 대화까지 해봤다면, 다음 질문이 바로 들어올 것이다. “이게 어떻게 돌아가는 거지?” 이 페이지에서는 OpenClaw를 제대로 쓰기 위해 꼭 알아야 할 핵심 구조를 정리한다. 설치 가이드, 시작하기를 먼저 끝낸 뒤 읽기를 권장한다.

---

💡 한 줄 치트시트: OpenClaw는 “파일이 곧 기억”인 에이전트다. 마크다운 파일로 정체성·기억·작업을 관리하고, Heartbeat·Cron·Webhook 세 가지 방식으로 스스로 돌아간다.

---

🧠 30초 핵심 아키텍처

OpenClaw는 하나의 Gateway 프로세스가 모든 채팅 채널(텔레그램·디스코드·WhatsApp·iMessage 등)과 AI 에이전트 사이에서 다리 역할을 한다. 사용자가 메시지를 보내면 Gateway가 에이전트에게 전달하고, 에이전트가 답을 생성해 다시 채널로 돌려준다. 이 과정이 24시간 돌아간다.

flowchart LR
    A["💬 채팅 앱"] --> B["🔄 Gateway"]
    B --> C["🤖 AI 에이전트"]
    B --> D["🖥️ 웹 대시보드"]
    B --> E["📱 모바일 노드"]
    C -->|"답변"| B
    B -->|"전달"| A

핵심 특징 5가지:

• 셀프 호스팅: 내 기기에서 돌아간다. 데이터가 외부 서버를 거치지 않는다.
• 멀티 채널: 하나의 Gateway가 여러 채팅 앱을 동시에 서비스한다.
• 에이전트 네이티브: 도구 사용, 세션, 메모리, 멀티 에이전트 라우팅을 기본 지원한다.
• 프로액티브: Heartbeat와 Cron으로 에이전트가 스스로 작업을 수행한다.
• 오픈소스: MIT 라이선스, 커뮤니티 주도.

공식 문서: OpenClaw Architecture, Features

---

📁 Workspace: 파일이 곧 기억

OpenClaw에서 가장 중요한 개념은 파일 기반 메모리다. 에이전트는 세션이 끝날 때마다 기억이 초기화되지만, ~/.openclaw/workspace/ 폴더 안의 마크다운 파일이 연속성을 만들어낸다.

핵심 파일 한눈에 보기

~/.openclaw/workspace/
├── SOUL.md        # 에이전트 성격·말투·경계
├── USER.md        # 사용자 정보 (이름, 타임존, 선호)
├── IDENTITY.md    # 이름, 아바타, 바이브
├── MEMORY.md      # 장기 기억 (중요 결정, 레슨런)
├── TOOLS.md       # 로컬 환경 메모 (SSH, 카메라 등)
├── AGENTS.md      # 워크스페이스 운영 규칙·안전 지침
├── HEARTBEAT.md   # 주기적 작업 체크리스트
├── BOOT.md        # (선택) Gateway 재시작 시 실행할 작업
├── BOOTSTRAP.md   # (최초 1회) 온보딩 의식 → 완료 후 삭제
├── memory/        # 일일 메모리 로그
│   └── 2026-03-28.md
└── skills/        # 커스텀 스킬

파일별 역할

파일	언제 읽히나	무엇을 적나
SOUL.md	매 세션	”효율적으로, 캐주얼하게, 필러 금지”
USER.md	매 세션	”또우, 서울 거주, AI/기술 관심”
IDENTITY.md	매 세션	”Flux, 해적 랍스터 🦞“
MEMORY.md	메인 세션만	장기 프로젝트 히스토리, 중요 선호
AGENTS.md	매 세션	파일 정리 규칙, 그룹 채팅 행동 수칙
HEARTBEAT.md	Heartbeat 시	정기 체크 작업 목록
memory/YYYY-MM-DD.md	매 세션 시작	당일 이벤트 로그

💡 실전 팁: MEMORY.md는 메인 1:1 세션에서만 불러온다. 그룹 채팅이나 다른 사람과의 세션에서는 개인 정보 보호를 위해 로드하지 않는다. 이건 공식 문서 Agent Workspace에 명시된 동작이다.

Workspace ≠ ~/.openclaw/

헷갈리기 쉬운 부분이 하나 있다. Workspace(~/.openclaw/workspace/)는 에이전트의 작업 공간이고, ~/.openclaw/는 설정·인증·세션 데이터가 사는 곳이다. Workspace 파일은 Git 백업을 권장하지만, ~/.openclaw/ 아래 내용(특히 credentials/)은 절대 Git에 올리지 않는다.

---

⏰ 자동 실행 3가지 방식

OpenClaw 에이전트는 사용자가 메시지를 보내지 않아도 스스로 작동할 수 있다. 세 가지 트리거가 있다.

1) Heartbeat — 주기적 폴링

openclaw.json의 heartbeat.interval 설정에 따라 매 N분마다 에이전트가 깨어난다. HEARTBEAT.md를 읽고 할 일이 있으면 실행하고, 없으면 HEARTBEAT_OK로 조용히 돌아간다.

{
  "heartbeat": {
    "interval": 300
  }
}

언제 쓰나: 여러 체크를 한 번에 묶을 때, 대화 컨텍스트가 필요할 때.

2) Cron — 정확한 시간 예약

“매일 아침 7시에 뉴스 요약”, “금요일 오후 7시에 주간 리뷰”처럼 정확한 시간이 필요할 때.

openclaw cron add --name "morning-news" --schedule "0 7 * * *" --message "오늘 기술 뉴스 요약해줘"
openclaw cron list

언제 쓰나: 정확한 시간이 중요할 때, 메인 세션과 분리된 독립 실행이 필요할 때.

3) Webhook — 외부 이벤트 트리거

GitHub push, 캘린더 이벤트, Gmail 수신 같은 외부 시스템 이벤트로 에이전트를 호출한다.

📖 자세한 비교: 공식 문서 Cron vs Heartbeat에서 어떤 상황에 어떤 방식을 쓸지 기준을 확인할 수 있다.

한눈에 비교

기준	Heartbeat	Cron	Webhook
트리거	시간 간격	정확한 스케줄	외부 이벤트
컨텍스트	메인 세션 공유	독립 세션	독립 세션
적합한 용도	여러 체크 묶기	정기 리포트	외부 연동
지연	±interval	±1분	실시간

---

🛡️ 보안: 강력한 도구, 강력한 책임

OpenClaw는 셸 실행, 파일 접근, 브라우저 제어까지 가능한 강력한 도구다. 보안 설정 없이 인터넷에 노출하면 심각한 위험이 따른다.

최소한 해야 할 4가지

1. 인증 활성화: auth: "none"은 절대 그대로 두지 않는다. 토큰이나 비밀번호를 설정한다.
2. 포트 보호: Gateway 포트(기본 18789)를 공용 인터넷에 직접 노출하지 않는다.
3. Tailscale 사용 권장: VPN으로 감싸면 포트 노출 없이 안전하게 원격 접속이 가능하다.
4. 비밀 분리: API 키, OAuth 토큰은 Workspace가 아닌 ~/.openclaw/credentials/에 보관한다.

# 보안 진단 실행
openclaw security audit --deep
 
# 자동 수정 (신중하게)
openclaw security audit --deep --fix

📖 공식 문서: Security, Tailscale

현장 사례: Shodan 노출

한 사용자가 auth: "none" 설정으로 테스트 후 포트를 닫지 않았다. 며칠 뒤 Shodan(인터넷 연결 장비 검색 엔진)이 해당 포트를 스캔했고, 누구나 에이전트에 명령을 내릴 수 있는 상태가 되었다. 해결: 토큰 인증을 켜고 Tailscale 뒤로 Gateway를 이동했다. openclaw security audit --deep을 습관적으로 실행하면 이런 상황을 예방할 수 있다.

---

🧩 스킬 시스템

스킬은 OpenClaw의 확장 플러그인이다. 날씨 조회, PDF 편집, 브라우저 자동화, 유튜브 분석 등 필요한 기능을 스킬로 추가할 수 있다.

스킬 찾고 설치하기

# 스킬 마켓 검색: https://clawhub.com
# 설치
openclaw skills install weather
 
# 설치된 스킬 확인
openclaw skills list

스킬 로딩 우선순위

같은 이름의 스킬이 여러 곳에 있으면 아래 순서로 불러온다:

1. workspace/skills/ (사용자 커스텀, 최우선)
2. ~/.openclaw/skills/ (글로벌 설치)
3. 번들 스킬 (기본 포함)

스킬 하나의 구조

스킬 폴더 안에는 SKILL.md가 있고, 여기에 “언제 이 스킬을 쓸지”와 “어떻게 실행할지”가 적혀 있다. 에이전트는 매 메시지마다 사용 가능한 스킬 목록을 스캔하고, 현재 작업에 맞는 스킬을 자동으로 선택한다.

📖 공식 문서: Skills, ClawHub

---

💰 비용 구조

OpenClaw 자체는 무료(MIT 오픈소스)다. 비용은 연결하는 AI 모델의 API 사용량에서 발생한다.

방식	월 비용 추정	특징
Ollama 로컬	$0	무료, 로컬 GPU 필요
Claude Pro/Max	구독료 포함	setup-token 사용
ChatGPT Plus/Pro	구독료 포함	Codex OAuth
API 키 (가벼운 사용)	$10~30	일반 사용
API 키 (헤비 사용)	$70~150	상시 운영 시

비용 절약 팁

• Heartbeat 간격 조정: 5분에서 15분으로 늘리면 API 호출이 약 1/3로 줄어든다.
• Heartbeat이 필요 없는 시간대에는 Gateway를 멈춰둔다.
• 로컬 모델 활용: 간단한 분류·요약은 Ollama로 처리하고 복잡한 작업만 상용 API로.

📖 공식 문서: Models, Quota

---

🔄 CLI vs OpenClaw

둘 다 AI 도구지만 용도가 다르다. 대체가 아니라 보완 관계다.

기준	CLI (Claude Code, Codex 등)	OpenClaw
인터페이스	터미널	메시징 앱 + 웹
작동	명시적 호출	24/7 상시 대기
주 용도	코딩, 파일 편집	생활·업무 자동화 전반
메모리	세션 휘발	영속적 (파일 기반)
프로액티브	❌	✅ Heartbeat/Cron/Webhook
멀티 채널	❌	✅ 6개 이상 동시

실전에서는 OpenClaw가 코딩 에이전트를 서브 에이전트로 호출하는 방식으로 함께 쓰는 경우가 많다. 예를 들어 텔레그램에서 “이 코드 버그 잡아줘”라고 보내면, OpenClaw가 Codex나 Claude Code를 백그라운드에서 실행하고 결과를 텔레그램으로 돌려준다.

---

📊 전체 디렉토리 구조

~/.openclaw/
├── workspace/          # 마크다운 메모리 (이것이 핵심!)
│   ├── SOUL.md
│   ├── USER.md
│   ├── MEMORY.md
│   ├── IDENTITY.md
│   ├── TOOLS.md
│   ├── AGENTS.md
│   ├── HEARTBEAT.md
│   └── memory/
│       └── 2026-03-28.md
├── openclaw.json       # 메인 설정 파일
├── credentials/        # OAuth 토큰, API 키 (Git 금지)
├── agents/             # 에이전트 프로필
├── cron/               # 스케줄 작업 정의
├── skills/             # 글로벌 스킬
├── sandboxes/          # 샌드박스 격리 공간
└── logs/               # 실행 로그

Workspace 안의 파일은 개인용 Git 프라이빗 리포로 백업을 권장한다. 단 .env, credentials/ 등 비밀은 절대 포함하지 않는다. 공식 문서 Agent Workspace > Git backup에서 절차를 확인할 수 있다.

---

📚 다음 읽기

• 🦞 04. 활용사례 — 실제로 어떤 일을 할 수 있는지
• 🦞 06. CronJob — 정기 작업 설정 방법
• 🦞 10. OpenCode — CLI 에이전트 연동
• 🦞 14. SkillOps 운영전환 — 스킬 운영 실전

---

참고 자료

• 공식 문서: docs.openclaw.ai
• GitHub: github.com/openclaw/openclaw
• 스킬 마켓: clawhub.com
• 커뮤니티: Discord