OpenClaw 에이전트 워크스페이스 설정 및 최적화 가이드

에이전트를 운영하다 보면 파일 관리가 꼬이거나 컨텍스트를 잃어버리는 일이 종종 생기죠. 어떤 파일을 백업해야 할지, 에이전트의 기억을 어떻게 안전하게 보관할지 고민하셨다면 이 가이드가 도움이 될 거예요.

워크스페이스는 에이전트의 집과 같습니다. 파일 도구와 워크스페이스 컨텍스트를 위해 사용되는 유일한 작업 디렉터리예요. 이 공간은 비공개로 유지하고, 에이전트의 메모리(기억)처럼 다뤄주세요.

이곳은 설정, 인증 정보, 세션이 저장되는 ~/.openclaw/와는 별개의 공간입니다.

중요: 워크스페이스는 **기본 cwd(현재 작업 디렉터리)**이며, 강력한 샌드박스는 아닙니다. 도구들은 워크스페이스를 기준으로 상대 경로를 해석하지만, 샌드박싱이 활성화되지 않았다면 절대 경로를 통해 호스트의 다른 곳에 접근할 수 있습니다. 격리가 필요하다면 agents.defaults.sandbox 또는 에이전트별 샌드박스 설정을 사용하세요. 샌드박싱이 활성화되고 workspaceAccess가 "rw"가 아닐 경우, 도구는 호스트 워크스페이스가 아닌 ~/.openclaw/sandboxes 아래의 샌드박스 워크스페이스 내에서 작동합니다.

기본 위치

• 기본값: ~/.openclaw/workspace
• OPENCLAW_PROFILE이 설정되어 있고 "default"가 아니라면, 기본값은 ~/.openclaw/workspace-<profile>이 됩니다.
• ~/.openclaw/openclaw.json에서 경로를 변경할 수 있습니다:

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

openclaw onboard, openclaw configure, 또는 openclaw setup 명령어를 실행하면 워크스페이스를 생성하고 필요한 부트스트랩 파일이 없을 경우 이를 채워 넣습니다. 샌드박스 시드 복사본은 워크스페이스 내부의 일반 파일만 허용하며, 소스 워크스페이스 외부를 가리키는 symlink나 hardlink 에일리어스는 무시됩니다.

직접 워크스페이스 파일을 관리하고 있다면 부트스트랩 파일 생성을 비활성화할 수 있습니다:

{ agent: { skipBootstrap: true } }

추가 워크스페이스 폴더

이전 버전 설치 시 ~/openclaw 폴더가 생성되었을 수 있습니다. 여러 워크스페이스 디렉터리를 유지하면 인증 문제나 상태 불일치가 발생해 혼란을 줄 수 있어요. 한 번에 하나의 워크스페이스만 활성화되기 때문입니다.

권장 사항: 하나의 활성 워크스페이스만 유지하세요. 더 이상 사용하지 않는 추가 폴더는 보관하거나 휴지통으로 이동시키세요 (예: trash ~/openclaw). 의도적으로 여러 워크스페이스를 유지한다면 agents.defaults.workspace가 현재 사용 중인 곳을 가리키고 있는지 확인해야 합니다.

openclaw doctor를 실행하면 추가 워크스페이스 디렉터리가 감지될 때 경고를 표시합니다.

워크스페이스 파일 맵 (각 파일의 의미)

OpenClaw가 워크스페이스 내부에서 사용하는 표준 파일들은 다음과 같습니다:

• AGENTS.md

  • 에이전트 작동 지침 및 메모리 사용 방법.
  • 모든 세션이 시작될 때 로드됩니다.
  • 규칙, 우선순위, 행동 방식 등을 적기에 좋습니다.

• SOUL.md

  • 페르소나, 말투, 가이드라인.
  • 매 세션마다 로드됩니다.

• USER.md

  • 사용자가 누구인지, 어떻게 호칭해야 하는지 정의.
  • 매 세션마다 로드됩니다.

• IDENTITY.md

  • 에이전트의 이름, 분위기(vibe), 이모지.
  • 부트스트랩 과정에서 생성되거나 업데이트됩니다.

• TOOLS.md

  • 로컬 도구 및 컨벤션에 대한 메모.
  • 도구 사용 가능 여부를 제어하지는 않으며, 안내 역할만 합니다.

• HEARTBEAT.md

  • 하트비트 실행을 위한 선택적 체크리스트.
  • 토큰 소모를 줄이기 위해 짧게 유지하세요.

• BOOT.md

  • 내부 훅이 활성화된 경우 Gateway 재시작 시 실행되는 선택적 시작 체크리스트.
  • 짧게 유지하고, 외부 전송에는 메시지 도구를 사용하세요.

• BOOTSTRAP.md

  • 최초 실행 시 한 번만 수행하는 절차.
  • 새 워크스페이스에서만 생성됩니다.
  • 절차가 완료되면 삭제하세요.

• memory/YYYY-MM-DD.md

  • 일일 메모리 로그 (하루에 파일 하나).
  • 세션 시작 시 오늘과 어제의 로그를 읽는 것을 권장합니다.

• MEMORY.md (선택 사항)

  • 선별된 장기 기억.
  • 공유/그룹 컨텍스트가 아닌 개인용 메인 세션에서만 로드하세요.

워크플로우와 자동 메모리 플러시에 대해서는 Memory 문서를 참고하세요.

• skills/ (선택 사항)

  • 워크스페이스 전용 스킬.
  • 이름이 충돌할 경우 관리형/번들 스킬보다 우선순위를 가집니다.

• canvas/ (선택 사항)

  • 노드 표시를 위한 Canvas UI 파일 (예: canvas/index.html).

부트스트랩 파일이 하나라도 누락되면 OpenClaw는 세션에 “파일 누락” 마커를 삽입하고 계속 진행합니다. 큰 부트스트랩 파일은 삽입 시 잘릴 수 있으니, agents.defaults.bootstrapMaxChars (기본값: 20000)와 agents.defaults.bootstrapTotalMaxChars (기본값: 150000) 설정을 통해 제한을 조정하세요. openclaw setup을 사용하면 기존 파일을 덮어쓰지 않고 누락된 기본 파일들만 다시 생성할 수 있습니다.

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

다음 항목들은 ~/.openclaw/ 아래에 위치하며, 워크스페이스 저장소에 커밋해서는 안 됩니다:

• ~/.openclaw/openclaw.json (설정)
• ~/.openclaw/credentials/ (OAuth 토큰, API 키)
• ~/.openclaw/agents/<agentId>/sessions/ (세션 기록 및 메타데이터)
• ~/.openclaw/skills/ (관리형 스킬)

세션이나 설정을 옮겨야 한다면 별도로 복사하고 버전 관리 시스템에 포함되지 않도록 주의하세요.

Git 백업 (권장, 프라이빗)

워크스페이스를 비공개 메모리로 취급하세요. 백업과 복구가 가능하도록 프라이빗(private) git 저장소에 보관하는 것이 좋습니다.

Gateway가 실행 중인 머신(워크스페이스가 있는 곳)에서 다음 단계를 실행하세요.

1) 저장소 초기화

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"

2) 프라이빗 원격 저장소 추가 (초보자용 옵션)

옵션 A: GitHub 웹 UI

1. GitHub에서 새로운 private 저장소를 만듭니다.
2. README 파일은 생성하지 마세요 (머지 충돌 방지).
3. HTTPS 원격 URL을 복사합니다.
4. 원격을 추가하고 푸시합니다:

git branch -M main
git remote add origin <https-url>
git push -u origin main

옵션 B: GitHub CLI (gh)

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

옵션 C: GitLab 웹 UI

1. GitLab에서 새로운 private 저장소를 만듭니다.
2. README 파일은 생성하지 마세요.
3. HTTPS 원격 URL을 복사합니다.
4. 원격을 추가하고 푸시합니다:

git branch -M main
git remote add origin <https-url>
git push -u origin main

3) 지속적인 업데이트

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

비밀 정보를 커밋하지 마세요

프라이빗 저장소라 하더라도 워크스페이스에 비밀 정보를 저장하는 것은 피해야 합니다:

• API 키, OAuth 토큰, 비밀번호 또는 개인 인증 정보.
• ~/.openclaw/ 아래의 모든 것.
• 채팅 내용의 원본 덤프나 민감한 첨부 파일.

민감한 정보를 참조해야 한다면 플레이스홀더(placeholder)를 사용하고, 실제 비밀 정보는 다른 곳(비밀번호 관리자, 환경 변수 또는 ~/.openclaw/)에 보관하세요.

권장하는 .gitignore 시작 설정:

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

워크스페이스를 새 기기로 이동하기

1. 원하는 경로(기본값 ~/.openclaw/workspace)에 저장소를 클론합니다.
2. ~/.openclaw/openclaw.json에서 agents.defaults.workspace를 해당 경로로 설정합니다.
3. openclaw setup --workspace <path>를 실행하여 누락된 파일을 채웁니다.
4. 세션이 필요하다면 이전 머신의 ~/.openclaw/agents/<agentId>/sessions/를 별도로 복사합니다.

고급 참고 사항

• 멀티 에이전트 라우팅을 사용하면 에이전트마다 다른 워크스페이스를 사용할 수 있습니다. 라우팅 설정은 Channel routing을 참고하세요.
• agents.defaults.sandbox가 활성화된 경우, 메인이 아닌 세션은 agents.defaults.sandbox.workspaceRoot 아래의 세션별 샌드박스 워크스페이스를 사용할 수 있습니다.

관련 문서

• Standing Orders — 워크스페이스 파일의 영구 지침
• Heartbeat — HEARTBEAT.md 워크스페이스 파일
• Session — 세션 저장 경로
• Sandboxing — 샌드박스 환경에서의 워크스페이스 접근

AI Setup Assistant