에이전트 워크스페이스

워크스페이스는 에이전트의 홈 디렉터리입니다. 파일 도구와 워크스페이스 컨텍스트에 사용되는 유일한 작업 디렉터리이며, 비공개로 유지하고 메모리처럼 다루어야 합니다.

설정, 자격 증명, 세션을 저장하는 ~/.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 명령어로 워크스페이스를 생성하고 부트스트랩 파일이 없으면 초기 파일을 생성합니다. 샌드박스 시드 복사는 워크스페이스 내부의 일반 파일만 허용하며, 소스 워크스페이스 외부로 연결되는 심볼릭/하드 링크는 무시됩니다.

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

{ agent: { skipBootstrap: true } }

추가 워크스페이스 폴더

이전 설치에서 ~/openclaw이 생성되었을 수 있습니다. 여러 워크스페이스 디렉터리를 보유하면 한 번에 하나의 워크스페이스만 활성화되기 때문에 인증이나 상태 불일치가 발생할 수 있습니다.

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

openclaw doctor는 추가 워크스페이스 디렉터리를 감지하면 경고합니다.

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

OpenClaw가 워크스페이스 내에서 기대하는 표준 파일 목록입니다:

  • AGENTS.md

    • 에이전트의 동작 지침과 메모리 사용 방법.
    • 모든 세션 시작 시 로드됩니다.
    • 규칙, 우선순위, “어떻게 행동할지”에 대한 세부사항을 기록하기 좋은 곳입니다.

  • SOUL.md

    • 페르소나, 톤, 경계.
    • 매 세션마다 로드됩니다.

  • USER.md

    • 사용자 정보와 호칭 방식.
    • 매 세션마다 로드됩니다.

  • IDENTITY.md

    • 에이전트의 이름, 분위기, 이모지.
    • 부트스트랩 의식 중에 생성/업데이트됩니다.

  • TOOLS.md

    • 로컬 도구와 관례에 대한 메모.
    • 도구 가용성을 제어하지 않으며 안내 역할만 합니다.

  • HEARTBEAT.md

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

  • BOOT.md

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

  • BOOTSTRAP.md

    • 최초 실행 의식용.
    • 새 워크스페이스에만 생성됩니다.
    • 의식 완료 후 삭제하세요.

  • memory/YYYY-MM-DD.md

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

  • MEMORY.md (선택)

    • 큐레이션된 장기 메모리.
    • 메인 비공개 세션에서만 로드하세요 (공유/그룹 컨텍스트에서는 제외).

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

  • skills/ (선택)

    • 워크스페이스별 스킬.
    • 이름이 충돌할 경우 관리형/번들 스킬을 오버라이드합니다.

  • canvas/ (선택)

    • 노드 디스플레이용 Canvas UI 파일 (예: canvas/index.html).

부트스트랩 파일이 누락된 경우 OpenClaw는 “missing file” 마커를 세션에 주입하고 계속 진행합니다. 큰 부트스트랩 파일은 주입 시 잘리며, 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 백업 (권장, 비공개)

워크스페이스를 비공개 메모리로 취급하세요. 비공개 Git 저장소에 넣어 백업하고 복구 가능하게 만드세요.

게이트웨이가 실행되는 머신에서 아래 단계를 수행하세요 (워크스페이스가 있는 곳입니다).

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에서 새 비공개 저장소를 생성합니다.
  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에서 새 비공개 저장소를 생성합니다.
  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/ 하위의 모든 것.
  • 채팅 원본 덤프나 민감한 첨부파일.

민감한 참조를 저장해야 하는 경우 플레이스홀더를 사용하고 실제 비밀은 별도 보관하세요 (비밀번호 관리자, 환경 변수, 또는 ~/.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/를 별도로 복사합니다.

고급 참고사항

  • 멀티 에이전트 라우팅은 에이전트별로 다른 워크스페이스를 사용할 수 있습니다. 라우팅 설정은 채널 라우팅을 참고하세요.
  • agents.defaults.sandbox가 활성화된 경우, 비메인 세션은 agents.defaults.sandbox.workspaceRoot 하위의 세션별 샌드박스 워크스페이스를 사용할 수 있습니다.
arrow_back
이전
Context
다음
OAuth
arrow_forward