워크스페이스 모범 사례
기준일: 2026-07-13 난이도: 중급 공식 기준: Agent workspace, Agent runtime, Memory overview, Memory CLI
워크스페이스는 에이전트의 집입니다. 파일 도구가 상대 경로를 해석하는 기본 위치이고, 부트스트랩 파일과 메모리 파일이 에이전트 맥락을 구성합니다. 다만 워크스페이스는 기본 cwd이지 하드 샌드박스가 아니므로 보안과 백업 기준을 따로 세워야 합니다.
핵심 개념
활성 워크스페이스는 하나만 명확히 둡니다
기본 위치는 ~/.openclaw/workspace입니다. 프로필, 환경 변수, 에이전트별 설정으로 위치가 달라질 수 있으므로 실제 활성 경로를 먼저 확인합니다. 오래된 ~/openclaw 같은 별도 폴더가 남아 있으면 인증, 상태, 메모리 혼선이 생길 수 있습니다.
워크스페이스 파일 지도
| 파일 또는 폴더 | 운영 기준 |
|---|---|
AGENTS.md |
지침, 우선순위, 메모리 사용 방식 |
SOUL.md |
톤, 성격, 경계 |
USER.md |
사용자 정보와 호칭 |
IDENTITY.md |
에이전트 이름과 정체성 |
TOOLS.md |
도구 사용 관례, 도구 권한 자체를 제어하지 않음 |
HEARTBEAT.md |
짧은 heartbeat 체크리스트 |
BOOT.md |
선택적 시작 체크리스트 |
BOOTSTRAP.md |
최초 실행 의식, 완료 뒤 삭제 |
MEMORY.md |
선택적 장기 메모리 |
memory/YYYY-MM-DD.md |
daily memory log |
skills/ |
워크스페이스 스킬 |
canvas/ |
선택적 Canvas UI 파일 |
워크스페이스에 두지 말아야 할 것
다음 항목은 ~/.openclaw/ 아래 런타임 상태이며 워크스페이스 repo에 커밋하지 않습니다.
~/.openclaw/openclaw.json~/.openclaw/agents/<agentId>/agent/auth-profiles.json~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite~/.openclaw/agents/<agentId>/agent/codex-home/~/.openclaw/credentials/~/.openclaw/agents/<agentId>/sessions/~/.openclaw/skills/
API key, OAuth token, 비밀번호, 개인 자격 증명, 민감한 원문 채팅도 워크스페이스에 저장하지 않습니다.
선택 기준
| 상황 | 권장 선택 |
|---|---|
| 처음 설치했다 | openclaw setup으로 워크스페이스와 기본 파일을 생성 |
| 이미 직접 관리하는 워크스페이스가 있다 | 공식 문서의 skipBootstrap 안내를 검토 |
| 여러 워크스페이스가 남아 있다 | 하나만 활성으로 정하고 나머지는 보관 또는 제거 |
| 백업이 필요하다 | 워크스페이스만 private git repo로 백업 |
| 다른 머신으로 이동한다 | 워크스페이스 repo를 복제하고 config는 별도로 갱신 |
| 세션까지 옮겨야 한다 | 에이전트 SQLite 세션 저장소를 별도로 복사 |
| 격리가 필요하다 | 워크스페이스가 sandbox가 아니므로 sandbox 설정을 검토 |
실습
1. 워크스페이스 생성 또는 보정
openclaw setup
특정 워크스페이스를 새 머신에서 보정할 때는 공식 명령을 사용합니다.
openclaw setup --workspace <path>
2. 활성 워크스페이스 파일 확인
cd ~/.openclaw/workspace
ls
AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, memory/가 있는지 확인합니다.
3. private git 백업 초기화
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
원격 저장소는 private repository로 만들고 push합니다.
git branch -M main
git remote add origin <https-url>
git push -u origin main
GitHub CLI를 쓰는 경우 공식 문서 흐름은 다음과 같습니다.
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
4. 메모리 검색 상태 점검
openclaw memory status
openclaw memory search "워크스페이스 백업"
검색 인덱스가 오래되었으면 재색인합니다.
openclaw memory index --force
도구에 입력할 프롬프트
내 OpenClaw 워크스페이스를 공식 문서 기준으로 점검해줘.
1. 워크스페이스 repo에 남겨도 되는 파일과 ~/.openclaw/ 아래에만 둬야 하는 파일을 구분해줘.
2. AGENTS.md, MEMORY.md, memory/YYYY-MM-DD.md가 과도하게 길거나 민감 정보를 담고 있는지 확인해줘.
3. 공식 문서에 없는 워크스페이스 정리 명령이나 메모리 관리 명령을 가정하지 말고 openclaw setup과 openclaw memory status/index/search만 사용해줘.
체크리스트
- 활성 워크스페이스 경로를 하나로 정했다.
- 워크스페이스가 하드 샌드박스가 아니라는 점을 운영 지침에 반영했다.
~/.openclaw/openclaw.json, credentials, SQLite 세션 저장소를 repo에 넣지 않았다.- API key, OAuth token, 비밀번호, 민감한 원문 채팅을 워크스페이스에 저장하지 않았다.
MEMORY.md는 장기 요약만 남기고, 자세한 기록은memory/YYYY-MM-DD.md로 분리했다.- 백업 repo는 private으로 만들었다.
- 이동 시 config와 세션 저장소는 워크스페이스와 별도로 다룬다.
- 점검 명령은 공식 CLI만 사용했다.