개요

OpenClaw는 단일 임베디드 에이전트 런타임을 제공한다. 에이전트는 게이트웨이 내부에서 직접 실행되며, 워크스페이스 디렉토리의 마크다운 파일을 통해 설정된다.

워크스페이스 구조

각 에이전트는 워크스페이스 디렉토리를 가지며, 다음 부트스트랩 파일들로 구성된다:

workspace/
├── AGENTS.md       # 에이전트 지시사항 + 메모리
├── SOUL.md         # 에이전트 페르소나 (성격, 말투)
├── TOOLS.md        # 사용 가능한 도구 문서
├── BOOTSTRAP.md    # 초기 설정 지시사항
├── IDENTITY.md     # 에이전트 이름 및 정체성
├── USER.md         # 사용자 프로필 정보
└── memory/         # 일별 메모리 파일
    ├── MEMORY.md
    └── YYYY-MM-DD.md

각 파일의 역할

AGENTS.md

에이전트의 핵심 지시사항과 장기 메모리를 담는 파일이다.

# My Agent

## 지시사항
- 항상 한국어로 응답
- 비즈니스 톤 유지
- 코드 관련 질문에 상세히 답변

## 메모리
- 사용자는 Next.js 프로젝트를 진행 중
- 선호 모델: Claude Sonnet

SOUL.md

에이전트의 페르소나를 정의한다. 성격, 말투, 행동 원칙 등을 기술한다.

# 페르소나

당신은 친절하고 전문적인 개발 도우미입니다.
기술 용어는 정확히 사용하되, 설명은 쉽게 합니다.

TOOLS.md

에이전트가 사용할 수 있는 도구의 문서를 기술한다.

BOOTSTRAP.md

에이전트가 최초 세션에서 실행해야 할 초기 설정 지시사항이다.

IDENTITY.md

에이전트의 이름과 정체성 정보를 정의한다.

USER.md

대화 상대인 사용자의 프로필 정보를 담는다.

부트스트랩 인젝션

세션의 첫 번째 턴에서 부트스트랩 파일들이 에이전트 컨텍스트에 주입된다.

인젝션 순서:

  1. IDENTITY.md - 에이전트 정체성
  2. SOUL.md - 페르소나
  3. AGENTS.md - 지시사항과 메모리
  4. TOOLS.md - 도구 문서
  5. USER.md - 사용자 프로필
  6. BOOTSTRAP.md - 초기 설정

이 파일들은 시스템 프롬프트의 일부로 삽입되어 에이전트의 동작을 정의한다.

세션 관리

세션 저장 형식

세션은 JSONL (JSON Lines) 형식으로 저장된다.

~/.openclaw/agents/<agentId>/sessions/
├── <sessionId>.jsonl
├── <sessionId>.jsonl
└── ...

각 줄은 하나의 메시지 또는 이벤트를 나타내는 JSON 객체이다.

세션 격리

각 에이전트는 독립된 세션 공간을 가진다. 서로 다른 에이전트의 세션은 격리되어 있어 데이터가 섞이지 않는다.

스킬 로딩

에이전트가 사용하는 스킬은 다음 우선순위로 로드된다:

  1. 워크스페이스 스킬 (최고 우선순위) - 에이전트 워크스페이스 내 스킬
  2. 관리형 스킬 (managed) - openclaw skills install로 설치한 스킬
  3. 번들 스킬 (bundled) - OpenClaw에 기본 내장된 스킬

워크스페이스 스킬이 가장 높은 우선순위를 가지므로, 기본 스킬을 오버라이드할 수 있다.

에이전트 디렉토리 구조

~/.openclaw/
├── openclaw.json          # 글로벌 설정
├── agents/
│   ├── default/
│   │   ├── workspace/     # 워크스페이스 파일들
│   │   │   ├── AGENTS.md
│   │   │   ├── SOUL.md
│   │   │   └── ...
│   │   └── sessions/      # 세션 JSONL 파일들
│   │       └── *.jsonl
│   └── custom-agent/
│       ├── workspace/
│       └── sessions/
└── skills/                # 설치된 스킬