Agent workspace

Workspace는 agent의 집입니다. 파일 tool 및 workspace 컨텍스트에 사용되는 유일한 작업 디렉토리입니다. 비공개로 유지하고 메모리로 취급하세요.

이는 config, credential 및 session을 저장하는 ~/.openclaw/와는 별개입니다.

중요: workspace는 기본 cwd이지, 엄격한 샌드박스가 아닙니다. Tool은 workspace에 대한 상대 경로를 해결하지만, 샌드박싱이 활성화되지 않은 경우 절대 경로는 여전히 host의 다른 곳에 도달할 수 있습니다. 격리가 필요한 경우 agents.defaults.sandbox를 사용하세요 (및/또는 agent별 sandbox config). 샌드박싱이 활성화되고 workspaceAccess가 "rw"가 아닌 경우, tool은 host workspace가 아닌 ~/.openclaw/sandboxes 아래의 sandbox workspace 내에서 작동합니다.

기본 위치

  • 기본값: ~/.openclaw/workspace
  • OPENCLAW_PROFILE이 설정되고 "default"가 아닌 경우, 기본값은 ~/.openclaw/workspace-<profile>이 됩니다.
  • ~/.openclaw/openclaw.json에서 재정의:
{
  agent: {
    workspace: "~/.openclaw/workspace"
  }
}

openclaw onboard, openclaw configure 또는 openclaw setup은 workspace를 생성하고 누락된 경우 bootstrap 파일을 시드합니다.

이미 workspace 파일을 직접 관리하는 경우, bootstrap 파일 생성을 비활성화할 수 있습니다:

{ agent: { skipBootstrap: true } }

추가 workspace 폴더

이전 설치는 ~/openclaw를 생성했을 수 있습니다. 여러 workspace 디렉토리를 유지하면 한 번에 하나의 workspace만 활성화되므로 혼란스러운 auth 또는 state drift가 발생할 수 있습니다.

권장 사항: 단일 활성 workspace를 유지하세요. 추가 폴더를 더 이상 사용하지 않는 경우, 보관하거나 휴지통으로 이동하세요 (예: trash ~/openclaw). 의도적으로 여러 workspace를 유지하는 경우, agents.defaults.workspace가 활성 workspace를 가리키는지 확인하세요.

openclaw doctor는 추가 workspace 디렉토리를 감지하면 경고합니다.

Workspace 파일 맵 (각 파일의 의미)

OpenClaw가 workspace 내부에서 예상하는 표준 파일입니다:

  • AGENTS.md

    • agent를 위한 작동 지침 및 메모리 사용 방법.
    • 모든 session 시작 시 로드됩니다.
    • 규칙, 우선순위 및 "행동 방법" 세부 정보를 위한 좋은 장소입니다.

  • SOUL.md

    • 페르소나, 톤 및 경계.
    • 모든 session에서 로드됩니다.

  • USER.md

    • 사용자가 누구이며 어떻게 호칭해야 하는지.
    • 모든 session에서 로드됩니다.

  • IDENTITY.md

    • agent의 이름, 분위기 및 이모지.
    • bootstrap 의식 중에 생성/업데이트됩니다.

  • TOOLS.md

    • 로컬 tool 및 규칙에 대한 참고 사항.
    • tool 가용성을 제어하지 않습니다; 단지 지침일 뿐입니다.

  • HEARTBEAT.md

    • heartbeat 실행을 위한 선택적 소형 체크리스트.
    • token 소모를 피하기 위해 짧게 유지하세요.

  • BOOT.md

    • 내부 hook이 활성화된 경우 gateway 재시작 시 실행되는 선택적 시작 체크리스트.
    • 짧게 유지하세요; 아웃바운드 전송에는 message tool을 사용하세요.

  • BOOTSTRAP.md

    • 일회성 첫 실행 의식.
    • 완전히 새로운 workspace에만 생성됩니다.
    • 의식이 완료되면 삭제하세요.

  • memory/YYYY-MM-DD.md

    • 일일 메모리 로그 (하루에 하나의 파일).
    • session 시작 시 오늘 + 어제를 읽는 것이 권장됩니다.

  • MEMORY.md (선택)

    • 큐레이션된 장기 메모리.
    • main, 비공개 session에서만 로드합니다 (공유/그룹 컨텍스트 아님).

워크플로우 및 자동 메모리 플러시는 Memory 참조.

  • skills/ (선택)

    • Workspace별 skill.
    • 이름이 충돌하면 관리형/번들 skill을 재정의합니다.

  • canvas/ (선택)

    • node 디스플레이를 위한 Canvas UI 파일 (예: canvas/index.html).

bootstrap 파일이 누락된 경우, OpenClaw는 "누락된 파일" 마커를 session에 주입하고 계속합니다. 큰 bootstrap 파일은 주입 시 잘립니다; 제한은 agents.defaults.bootstrapMaxChars로 조정하세요 (기본값: 20000). openclaw setup은 기존 파일을 덮어쓰지 않고 누락된 기본값을 다시 생성할 수 있습니다.

Workspace에 없는 것

이것들은 ~/.openclaw/ 아래에 있으며 workspace 저장소에 커밋하지 말아야 합니다:

  • ~/.openclaw/openclaw.json (config)
  • ~/.openclaw/credentials/ (OAuth token, API key)
  • ~/.openclaw/agents/<agentId>/sessions/ (session transcript + 메타데이터)
  • ~/.openclaw/skills/ (관리형 skill)

session 또는 config를 마이그레이션해야 하는 경우, 별도로 복사하고 버전 제어에서 제외하세요.

Git 백업 (권장, 비공개)

Workspace를 비공개 메모리로 취급하세요. 비공개 git 저장소에 넣어 백업되고 복구 가능하도록 하세요.

Gateway가 실행되는 머신에서 이 단계를 실행하세요 (workspace가 있는 곳).

1) 저장소 초기화

git이 설치된 경우, 완전히 새로운 workspace는 자동으로 초기화됩니다. 이 workspace가 아직 저장소가 아닌 경우 실행하세요:

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에서 새로운 비공개 저장소를 생성합니다.
  2. README로 초기화하지 마세요 (병합 충돌 방지).
  3. HTTPS 원격 URL을 복사합니다.
  4. 원격을 추가하고 push하세요:
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에서 새로운 비공개 저장소를 생성합니다.
  2. README로 초기화하지 마세요 (병합 충돌 방지).
  3. HTTPS 원격 URL을 복사합니다.
  4. 원격을 추가하고 push하세요:
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

비밀을 커밋하지 마세요

비공개 저장소에서도 workspace에 비밀을 저장하지 마세요:

  • API key, OAuth token, 비밀번호 또는 비공개 credential.
  • ~/.openclaw/ 아래의 모든 것.
  • 채팅 또는 민감한 첨부 파일의 원시 덤프.

민감한 참조를 저장해야 하는 경우, placeholder를 사용하고 실제 비밀을 다른 곳에 보관하세요 (비밀번호 관리자, 환경 변수 또는 ~/.openclaw/).

제안된 .gitignore 스타터:

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

Workspace를 새 머신으로 이동

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

고급 참고 사항

  • 다중 agent 라우팅은 agent당 다른 workspace를 사용할 수 있습니다. 라우팅 구성은 Channel routing 참조.
  • agents.defaults.sandbox가 활성화된 경우, 비 main session은 agents.defaults.sandbox.workspaceRoot 아래의 session별 sandbox workspace를 사용할 수 있습니다.
← 문서로 돌아가기