메인 콘텐츠로 건너뛰기
워크스페이스는 에이전트의 홈입니다. 파일 도구와 워크스페이스 컨텍스트에 사용되는 유일한 작업 디렉터리입니다. 비공개로 유지하고 메모리처럼 다루세요. 이는 config, 자격 증명, 세션을 저장하는 ~/.openclaw/와는 별개입니다.
워크스페이스는 기본 cwd이지, 강제 sandbox가 아닙니다. 도구는 상대 경로를 워크스페이스 기준으로 해석하지만, sandboxing이 활성화되어 있지 않으면 절대 경로로 호스트의 다른 위치에 여전히 접근할 수 있습니다. 격리가 필요하다면 agents.defaults.sandbox(및/또는 에이전트별 sandbox config)를 사용하세요.sandboxing이 활성화되어 있고 workspaceAccess가 "rw"가 아니면, 도구는 호스트 워크스페이스가 아니라 ~/.openclaw/sandboxes 아래의 sandbox 워크스페이스 안에서 작동합니다.

​
기본 위치

  • 기본값: ~/.openclaw/workspace
  • OPENCLAW_PROFILE이 설정되어 있고 "default"가 아니면, 기본값은 ~/.openclaw/workspace-<profile>이 됩니다.
  • ~/.openclaw/openclaw.json에서 재정의:
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}
openclaw onboard, openclaw configure 또는 openclaw setup은 워크스페이스를 만들고 bootstrap 파일이 없으면 초기 파일을 배치합니다.
Sandbox seed 복사는 일반적인 워크스페이스 내부 파일만 허용합니다. 소스 워크스페이스 밖으로 해석되는 symlink/hardlink 별칭은 무시됩니다.
워크스페이스 파일을 이미 직접 관리하고 있다면 bootstrap 파일 생성을 비활성화할 수 있습니다. 
{ agents: { defaults: { skipBootstrap: true } } }

​
추가 워크스페이스 폴더

이전 설치에서는 ~/openclaw가 만들어졌을 수 있습니다. 활성 워크스페이스는 한 번에 하나뿐이므로, 여러 워크스페이스 디렉터리를 남겨 두면 인증 또는 상태 드리프트가 혼란스러울 수 있습니다.
권장 사항: 활성 워크스페이스는 하나만 유지하세요. 추가 폴더를 더 이상 사용하지 않는다면 보관하거나 휴지통으로 이동하세요(예: trash ~/openclaw). 여러 워크스페이스를 의도적으로 유지한다면 agents.defaults.workspace가 활성 워크스페이스를 가리키는지 확인하세요.openclaw doctor는 추가 워크스페이스 디렉터리를 감지하면 경고합니다.

​
워크스페이스 파일 맵

다음은 OpenClaw가 워크스페이스 안에 있을 것으로 기대하는 표준 파일입니다.
에이전트를 위한 운영 지침과 메모리 사용 방식입니다. 모든 세션 시작 시 로드됩니다. 규칙, 우선순위, “행동 방식” 세부 사항을 두기에 좋은 위치입니다.
페르소나, 톤, 경계입니다. 모든 세션에서 로드됩니다. 가이드: SOUL.md 성격 가이드.
사용자가 누구이며 어떻게 호칭해야 하는지입니다. 모든 세션에서 로드됩니다.
에이전트의 이름, 분위기, 이모지입니다. bootstrap 의식 중에 생성/업데이트됩니다.
로컬 도구와 규칙에 대한 메모입니다. 도구 사용 가능 여부를 제어하지 않으며, 안내용일 뿐입니다.
Heartbeat 실행을 위한 선택적 작은 체크리스트입니다. 토큰 소모를 피하려면 짧게 유지하세요.
Gateway 재시작 시(internal hooks가 활성화된 경우) 자동으로 실행되는 선택적 시작 체크리스트입니다. 짧게 유지하고, outbound 전송에는 메시지 도구를 사용하세요.
일회성 최초 실행 의식입니다. 완전히 새 워크스페이스에만 생성됩니다. 의식이 완료되면 삭제하세요.
일일 메모리 로그(하루에 파일 하나)입니다. 세션 시작 시 오늘 + 어제를 읽는 것을 권장합니다.
선별된 장기 메모리: 지속적인 사실, 선호도, 결정, 짧은 요약입니다. 자세한 로그는 memory/YYYY-MM-DD.md에 보관해 메모리 도구가 필요할 때 검색할 수 있게 하고, 모든 프롬프트에 주입하지 않도록 하세요. MEMORY.md는 메인 비공개 세션에서만 로드하세요(공유/그룹 컨텍스트 제외). 워크플로와 자동 메모리 flush는 메모리를 참고하세요.
워크스페이스별 Skills입니다. 해당 워크스페이스에서 가장 높은 우선순위를 갖는 Skills 위치입니다. 이름이 충돌하면 프로젝트 에이전트 Skills, 개인 에이전트 Skills, 관리형 Skills, bundled Skills, skills.load.extraDirs를 재정의합니다.
노드 표시용 Canvas UI 파일입니다(예: canvas/index.html).
bootstrap 파일이 누락되면 OpenClaw는 세션에 “missing file” 마커를 주입하고 계속 진행합니다. 큰 bootstrap 파일은 주입 시 잘립니다. 제한은 agents.defaults.bootstrapMaxChars(기본값: 20000) 및 agents.defaults.bootstrapTotalMaxChars(기본값: 60000)로 조정하세요. openclaw setup은 기존 파일을 덮어쓰지 않고 누락된 기본값을 다시 만들 수 있습니다.

​
워크스페이스에 포함되지 않는 것

다음은 ~/.openclaw/ 아래에 있으며 워크스페이스 repo에 커밋하면 안 됩니다.
  • ~/.openclaw/openclaw.json (config)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (모델 인증 프로필: OAuth + API keys)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/ (에이전트별 Codex 런타임 계정, config, skills, plugins, 네이티브 thread 상태)
  • ~/.openclaw/credentials/ (채널/제공자 상태 및 legacy OAuth import 데이터)
  • ~/.openclaw/agents/<agentId>/sessions/ (세션 transcript + metadata)
  • ~/.openclaw/skills/ (관리형 skills)
세션이나 config를 마이그레이션해야 한다면 별도로 복사하고 버전 관리에는 포함하지 마세요.

​
Git 백업(권장, 비공개)

워크스페이스를 비공개 메모리로 다루세요. 백업 및 복구가 가능하도록 private git repo에 넣으세요. 다음 단계는 Gateway가 실행되는 머신에서 실행하세요(워크스페이스가 있는 곳입니다).
1

Initialize the repo

git이 설치되어 있으면 완전히 새 워크스페이스는 자동으로 초기화됩니다. 이 워크스페이스가 아직 repo가 아니라면 다음을 실행하세요.
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"
2

Add a private remote

  1. GitHub에서 새 private 저장소를 만듭니다.
  2. README로 초기화하지 마세요(merge conflict 방지).
  3. HTTPS remote URL을 복사합니다.
  4. remote를 추가하고 push합니다.
git branch -M main
git remote add origin <https-url>
git push -u origin main
3

Ongoing updates

git status
git add .
git commit -m "Update memory"
git push

​
비밀을 커밋하지 마세요

private repo에서도 워크스페이스에 비밀을 저장하지 마세요.
  • API keys, OAuth tokens, passwords 또는 private credentials.
  • ~/.openclaw/ 아래의 모든 항목.
  • 채팅 또는 민감한 첨부 파일의 원시 dump.
민감한 참조를 저장해야 한다면 placeholder를 사용하고 실제 비밀은 다른 곳(password manager, environment variables 또는 ~/.openclaw/)에 보관하세요.
제안하는 .gitignore 시작점: 
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

​
워크스페이스를 새 머신으로 이동하기

1

Clone the repo

원하는 경로(기본값 ~/.openclaw/workspace)로 repo를 clone합니다.
2

Update config

~/.openclaw/openclaw.json에서 agents.defaults.workspace를 해당 경로로 설정합니다.
3

Seed missing files

누락된 파일을 배치하려면 openclaw setup --workspace <path>를 실행합니다.
4

Copy sessions (optional)

세션이 필요하다면 이전 머신에서 ~/.openclaw/agents/<agentId>/sessions/를 별도로 복사합니다.

​
고급 참고 사항

  • 다중 에이전트 routing은 에이전트별로 다른 워크스페이스를 사용할 수 있습니다. routing config는 채널 routing을 참고하세요.
  • agents.defaults.sandbox가 활성화되어 있으면 메인이 아닌 세션은 agents.defaults.sandbox.workspaceRoot 아래의 세션별 sandbox 워크스페이스를 사용할 수 있습니다.

​
관련 문서

  • Heartbeat - HEARTBEAT.md 워크스페이스 파일
  • Sandboxing - sandboxed 환경의 워크스페이스 접근
  • 세션 - 세션 저장 경로
  • Standing orders - 워크스페이스 파일의 지속적 지침