Fundamentals
에이전트 작업 공간
작업공간은 에이전트의 집입니다. 파일 도구와 작업공간 컨텍스트에 사용되는 유일한 작업 디렉터리입니다. 비공개로 유지하고 메모리처럼 다루세요.
이는 설정, 자격 증명, 세션을 저장하는 ~/.openclaw/와는 별개입니다.
기본 위치
- 기본값:
~/.openclaw/workspace OPENCLAW_PROFILE이 설정되어 있고"default"가 아니면, 기본값은~/.openclaw/workspace-<profile>이 됩니다.~/.openclaw/openclaw.json에서 재정의합니다.
{
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
},
},
}
openclaw onboard, openclaw configure, 또는 openclaw setup은 작업공간을 만들고 부트스트랩 파일이 없으면 시드합니다.
작업공간 파일을 이미 직접 관리하고 있다면, 부트스트랩 파일 생성을 비활성화할 수 있습니다.
{ agents: { defaults: { skipBootstrap: true } } }
추가 작업공간 폴더
오래된 설치에서는 ~/openclaw를 만들었을 수 있습니다. 한 번에 하나의 작업공간만 활성화되므로 여러 작업공간 디렉터리를 유지하면 인증 또는 상태 드리프트가 혼란스러워질 수 있습니다.
작업공간 파일 맵
다음은 OpenClaw가 작업공간 안에 있을 것으로 기대하는 표준 파일입니다.
AGENTS.md - 운영 지침
에이전트를 위한 운영 지침과 메모리 사용 방법입니다. 모든 세션 시작 시 로드됩니다. 규칙, 우선순위, "행동 방식" 세부사항을 두기에 좋은 위치입니다.
SOUL.md - 페르소나와 톤
페르소나, 톤, 경계입니다. 모든 세션에서 로드됩니다. 가이드: SOUL.md 성격 가이드.
USER.md - 사용자가 누구인지
사용자가 누구이며 어떻게 호칭할지입니다. 모든 세션에서 로드됩니다.
IDENTITY.md - 이름, 분위기, 이모지
에이전트의 이름, 분위기, 이모지입니다. 부트스트랩 의식 중 생성/업데이트됩니다.
TOOLS.md - 로컬 도구 관례
로컬 도구와 관례에 대한 메모입니다. 도구 사용 가능 여부를 제어하지 않으며, 안내일 뿐입니다.
HEARTBEAT.md - heartbeat 체크리스트
Heartbeat 실행을 위한 선택적 작은 체크리스트입니다. 토큰 소모를 피하려면 짧게 유지하세요.
BOOT.md - 시작 체크리스트
Gateway 재시작 시(내부 훅이 활성화된 경우) 자동으로 실행되는 선택적 시작 체크리스트입니다. 짧게 유지하고, 외부 전송에는 메시지 도구를 사용하세요.
BOOTSTRAP.md - 첫 실행 의식
일회성 첫 실행 의식입니다. 완전히 새로운 작업공간에만 생성됩니다. 의식이 완료되면 삭제하세요.
memory/YYYY-MM-DD.md - 일일 메모리 로그
일일 메모리 로그입니다(하루에 파일 하나). 세션 시작 시 오늘 + 어제를 읽는 것이 권장됩니다.
MEMORY.md - 선별된 장기 메모리(선택 사항)
선별된 장기 메모리입니다. 기본 비공개 세션에서만 로드하세요(공유/그룹 컨텍스트에서는 로드하지 않음). 워크플로와 자동 메모리 플러시는 메모리를 참고하세요.
skills/ - 작업공간 Skills(선택 사항)
작업공간별 Skills입니다. 해당 작업공간에서 가장 높은 우선순위의 skill 위치입니다. 이름이 충돌하면 프로젝트 에이전트 skills, 개인 에이전트 skills, 관리형 skills, 번들 skills, skills.load.extraDirs를 재정의합니다.
canvas/ - Canvas UI 파일(선택 사항)
노드 표시를 위한 Canvas UI 파일입니다(예: canvas/index.html).
작업공간에 포함되지 않는 항목
다음은 ~/.openclaw/ 아래에 있으며 작업공간 저장소에 커밋하면 안 됩니다.
~/.openclaw/openclaw.json(설정)~/.openclaw/agents/<agentId>/agent/auth-profiles.json(모델 인증 프로필: OAuth + API 키)~/.openclaw/agents/<agentId>/agent/codex-home/(에이전트별 Codex 런타임 계정, 설정, skills, plugins, 네이티브 스레드 상태)~/.openclaw/credentials/(채널/제공자 상태와 레거시 OAuth 가져오기 데이터)~/.openclaw/agents/<agentId>/sessions/(세션 트랜스크립트 + 메타데이터)~/.openclaw/skills/(관리형 skills)
세션이나 설정을 마이그레이션해야 한다면 별도로 복사하고 버전 관리에서는 제외하세요.
Git 백업(권장, 비공개)
작업공간을 비공개 메모리로 다루세요. 백업과 복구가 가능하도록 비공개 git 저장소에 넣으세요.
다음 단계는 Gateway가 실행되는 머신에서 실행하세요(작업공간이 있는 곳입니다).
저장소 초기화
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"
비공개 원격 추가
GitHub 웹 UI
- GitHub에서 새 비공개 저장소를 만듭니다.
- README로 초기화하지 마세요(병합 충돌 방지).
- HTTPS 원격 URL을 복사합니다.
- 원격을 추가하고 푸시합니다.
git branch -M main
git remote add origin <https-url>
git push -u origin main
GitHub CLI (gh)
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
GitLab 웹 UI
- GitLab에서 새 비공개 저장소를 만듭니다.
- README로 초기화하지 마세요(병합 충돌 방지).
- HTTPS 원격 URL을 복사합니다.
- 원격을 추가하고 푸시합니다.
git branch -M main
git remote add origin <https-url>
git push -u origin main
지속적인 업데이트
git status
git add .
git commit -m "Update memory"
git push
비밀 정보를 커밋하지 마세요
권장 .gitignore 시작점:
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
작업공간을 새 머신으로 이동하기
저장소 클론
원하는 경로(기본값 ~/.openclaw/workspace)에 저장소를 클론합니다.
설정 업데이트
~/.openclaw/openclaw.json에서 agents.defaults.workspace를 해당 경로로 설정합니다.
누락 파일 시드
openclaw setup --workspace <path>를 실행하여 누락된 파일을 시드합니다.
세션 복사(선택 사항)
세션이 필요하다면 이전 머신에서 ~/.openclaw/agents/<agentId>/sessions/를 별도로 복사하세요.
고급 참고 사항
- 다중 에이전트 라우팅은 에이전트마다 다른 작업공간을 사용할 수 있습니다. 라우팅 설정은 채널 라우팅을 참고하세요.
agents.defaults.sandbox가 활성화되어 있으면 기본 세션이 아닌 세션은agents.defaults.sandbox.workspaceRoot아래의 세션별 샌드박스 작업공간을 사용할 수 있습니다.
관련 항목
- Heartbeat - HEARTBEAT.md 작업공간 파일
- 샌드박싱 - 샌드박스 환경에서의 작업공간 접근
- 세션 - 세션 저장 경로
- 상시 지시 - 작업공간 파일의 지속적 지시