기본 개념

기준일: 2026-07-13 난이도: 초급 공식 기준: Agent runtime, Agent workspace, Memory overview, Memory CLI

OpenClaw는 채널 메시지를 외부 실행기로 넘기는 단순 라우터가 아니라, 에이전트 루프, 도구 연결, 프롬프트 조립, 세션 저장, 채널 전달을 한 런타임 안에서 다루는 시스템입니다.

핵심 개념

에이전트 런타임

OpenClaw의 에이전트 런타임은 내장 에이전트 루프와 도구 배선, 프롬프트 조립을 포함합니다. 각 에이전트는 자기 워크스페이스, 부트스트랩 파일, 세션 저장소를 갖습니다.

워크스페이스

워크스페이스는 에이전트의 기본 작업 디렉터리입니다. 도구가 상대 경로를 해석하는 기준이며, 에이전트가 읽는 작업 맥락이 저장됩니다.

• 기본 워크스페이스는 ~/.openclaw/workspace입니다.
• 실제 경로는 openclaw config get agents.defaults.workspace로 확인합니다. 에이전트별 override가 있으면 agents.list[].workspace가 우선합니다.
• 워크스페이스는 기본 cwd일 뿐 하드 샌드박스가 아닙니다. 격리가 필요하면 샌드박스 설정을 따로 검토해야 합니다.
• ~/.openclaw/ 아래의 설정, 자격 증명, 세션 데이터는 워크스페이스 repo에 커밋하지 않습니다.

부트스트랩 파일

OpenClaw는 워크스페이스 안의 사용자 편집 파일을 새 세션의 Project Context로 주입합니다.

파일	역할
AGENTS.md	에이전트 운영 지침과 메모리 사용 방식
SOUL.md	성격, 톤, 경계
TOOLS.md	로컬 도구 사용 관례
IDENTITY.md	에이전트 이름과 정체성
USER.md	사용자 프로필과 선호 호칭
HEARTBEAT.md	heartbeat 실행 지침
BOOTSTRAP.md	최초 실행 의식, 완료 후 삭제
MEMORY.md	선택적 장기 메모리 파일

빈 파일은 건너뛰고, 큰 파일은 프롬프트 예산에 맞게 잘린 사본만 주입됩니다. MEMORY.md는 워크스페이스 루트에 있을 때만 주입됩니다.

세션

세션 행은 에이전트별 SQLite 데이터베이스에 저장됩니다. 과거 JSONL 세션 파일은 마이그레이션, 가져오기, 내보내기, 지원 자료로 남을 수 있지만 활성 히스토리는 SQLite 세션 행이 기준입니다.

메모리

OpenClaw 메모리는 숨은 내부 상태가 아니라 워크스페이스의 Markdown 파일에 저장됩니다.

파일	용도
MEMORY.md	장기 기억: durable facts, preferences, decisions
memory/YYYY-MM-DD.md	일별 작업 노트와 관찰 기록
DREAMS.md	선택적 dreaming 검토 기록

도구 수준에서는 memory_search와 memory_get이 관련 메모리를 찾고 읽습니다. CLI에서는 openclaw memory status, openclaw memory index, openclaw memory search가 기본 확인 흐름입니다.

선택 기준

상황	우선 확인할 개념
에이전트가 어떤 파일을 읽는지 알고 싶다	부트스트랩 파일과 워크스페이스
작업 파일이 어디에 생성되는지 알고 싶다	워크스페이스 경로와 샌드박스 여부
이전 대화를 기억하지 못한다	MEMORY.md, memory/YYYY-MM-DD.md, 메모리 인덱스
세션 기록을 백업하거나 이전하고 싶다	에이전트 SQLite 세션 저장소와 워크스페이스 repo
여러 에이전트를 나눠 쓰고 싶다	에이전트별 워크스페이스와 라우팅

실습

1. 워크스페이스를 초기화합니다

openclaw setup

이미 워크스페이스를 직접 관리한다면 공식 Agent workspace 문서의 skipBootstrap 안내를 확인한 뒤 적용합니다.

2. 워크스페이스 파일을 확인합니다

cd ~/.openclaw/workspace
ls

AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, memory/가 현재 워크스페이스에 어떻게 배치되어 있는지 확인합니다.

3. 메모리 상태를 확인합니다

openclaw memory status

인덱스가 오래되었거나 검색이 기대와 다르면 다음 명령으로 재색인합니다.

openclaw memory index --force

4. 메모리를 검색합니다

openclaw memory search "프로젝트 선호도"

도구에 입력할 프롬프트

내 OpenClaw 워크스페이스의 AGENTS.md, MEMORY.md, memory/YYYY-MM-DD.md 역할을 공식 문서 기준으로 구분해줘.
숨은 상태나 임의 설정을 가정하지 말고, 파일에 저장된 내용과 openclaw memory CLI로 확인 가능한 항목만 근거로 설명해줘.

체크리스트

• 워크스페이스와 ~/.openclaw/ 저장소의 역할을 구분했다.
• AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md의 주입 방식을 이해했다.
• 워크스페이스가 기본 cwd이지 하드 샌드박스가 아니라는 점을 확인했다.
• 장기 메모리와 일별 메모리의 저장 위치를 구분했다.
• 메모리 확인에는 공식 CLI인 openclaw memory status, index, search를 사용했다.
• 모델명, 가격, 기본 모델 값은 문서에 고정하지 않고 현재 설정 또는 공식 문서에서 확인하기로 했다.

다음 단계

• 첫 메시지에서 실제 세션과 응답 흐름을 확인합니다.
• 메모리 시스템에서 MEMORY.md, daily note, memory CLI를 학습합니다.
• 워크스페이스 모범 사례에서 백업과 보안 운영 기준을 정리합니다.