OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Fundamentals

에이전트 작업 공간

워크스페이스는 에이전트의 홈입니다. 즉, 파일 도구와 워크스페이스 컨텍스트에 사용되는 작업 디렉터리입니다. 워크스페이스를 비공개로 유지하고 메모리처럼 취급하십시오.

이는 구성, 자격 증명, 세션을 저장하는 ~/.openclaw/와는 별개입니다.

기본 위치

  • 기본값: ~/.openclaw/workspace
  • OPENCLAW_PROFILE이 설정되어 있고 "default"가 아니면 기본값은 ~/.openclaw/workspace-<profile>이 됩니다.
  • OPENCLAW_WORKSPACE_DIR이 설정되어 있으면 위 두 기본값을 모두 재정의합니다.
  • 명시적인 워크스페이스가 없는 기본값 외 에이전트(agents.list[])는 공유 기본 워크스페이스가 아니라 <state-dir>/workspace-<agentId>로 해석됩니다.

~/.openclaw/openclaw.json에서 재정의하십시오.

json5
{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",    },  },}

에이전트별 재정의: agents.list[].workspace.

openclaw onboard, openclaw configure 또는 openclaw setup은 워크스페이스를 생성하고 부트스트랩 파일이 없으면 초기 파일을 배치합니다.

워크스페이스 파일을 이미 직접 관리하고 있다면 부트스트랩 파일 생성을 비활성화하십시오.

json5
{ 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 - 선별된 장기 메모리(선택 사항)

선별된 장기 메모리로, 지속적인 사실, 선호 사항, 결정 및 짧은 요약을 저장합니다. 메모리 도구가 모든 프롬프트에 삽입하지 않고도 필요할 때 검색할 수 있도록 상세 로그는 memory/YYYY-MM-DD.md에 보관하십시오. MEMORY.md는 기본 비공개 세션에서만 로드하고 공유/그룹 컨텍스트에서는 로드하지 마십시오. 워크플로와 자동 메모리 플러시는 메모리를 참조하십시오.

skills/ - 워크스페이스 Skills(선택 사항)

워크스페이스별 Skills입니다. 이름이 충돌할 경우 프로젝트 에이전트 Skills, 개인 에이전트 Skills, 관리형 Skills, 번들 Skills 및 skills.load.extraDirs보다 우선하는 해당 워크스페이스의 최우선 Skills 위치입니다.

canvas/ - Canvas UI 파일(선택 사항)

Node 디스플레이용 Canvas UI 파일입니다(예: canvas/index.html).

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

다음 항목은 ~/.openclaw/ 아래에 있으며 워크스페이스 저장소에 커밋해서는 안 됩니다.

  • ~/.openclaw/openclaw.json(구성)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json(모델 인증 프로필: OAuth + API 키)
  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite(세션 행, 대화 기록 및 에이전트별 런타임 상태)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/(에이전트별 Codex 런타임 계정, 구성, Skills, Plugin 및 네이티브 스레드 상태)
  • ~/.openclaw/credentials/(채널/공급자 상태 및 레거시 OAuth 가져오기 데이터)
  • ~/.openclaw/agents/<agentId>/sessions/(레거시 마이그레이션 소스 및 보관/지원 아티팩트)
  • ~/.openclaw/skills/(관리형 Skills)

세션 또는 구성을 마이그레이션해야 한다면 별도로 복사하고 버전 관리에는 포함하지 마십시오.

Git 백업(권장, 비공개)

워크스페이스를 비공개 메모리처럼 취급하십시오. 백업하고 복구할 수 있도록 비공개 git 저장소에 넣으십시오.

Gateway가 실행되는 머신에서 다음 단계를 수행하십시오(워크스페이스가 있는 위치입니다).

  • 저장소 초기화

    git이 설치되어 있으면 완전히 새로운 워크스페이스는 자동으로 초기화됩니다. 이 워크스페이스가 아직 저장소가 아니라면 다음을 실행하십시오.

    bash
    cd ~/.openclaw/workspacegit initgit add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/git commit -m "Add agent workspace"

  • 비공개 원격 저장소 추가

    GitHub 웹 UI

    1. GitHub에서 새 private 저장소를 생성합니다.
    2. README로 초기화하지 마십시오(병합 충돌 방지).
    3. HTTPS 원격 URL을 복사합니다.
    4. 원격 저장소를 추가하고 푸시합니다.
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

    GitHub CLI (gh)

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

    GitLab 웹 UI

    1. GitLab에서 새 private 저장소를 생성합니다.
    2. README로 초기화하지 마십시오(병합 충돌 방지).
    3. HTTPS 원격 URL을 복사합니다.
    4. 원격 저장소를 추가하고 푸시합니다.
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

  • 지속적인 업데이트

    bash
    git statusgit add .git commit -m "Update memory"git push

    • 비밀 정보를 커밋하지 마십시오

    권장 .gitignore 시작 예시는 다음과 같습니다.

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

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

  • 저장소 복제

    원하는 경로(기본값 ~/.openclaw/workspace)에 저장소를 복제합니다.

  • 구성 업데이트

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

  • 누락된 파일 초기 배치

    openclaw setup --workspace <path>를 실행하여 누락된 파일을 초기 배치합니다.

  • 세션 복사(선택 사항)

    세션이 필요하면 이전 머신의 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite를 별도로 복사하십시오. 레거시 마이그레이션 입력 또는 보관/지원 아티팩트도 필요한 경우에만 ~/.openclaw/agents/<agentId>/sessions/를 복사하십시오.

    • 고급 참고 사항

    • 다중 에이전트 라우팅에서는 agents.list[].workspace를 통해 에이전트마다 서로 다른 워크스페이스를 사용할 수 있습니다. 라우팅 구성은 채널 라우팅을 참조하십시오.
    • agents.defaults.sandbox가 활성화되어 있으면 기본 세션이 아닌 세션에서 agents.defaults.sandbox.workspaceRoot 아래의 세션별 샌드박스 워크스페이스를 사용할 수 있습니다.

    관련 항목

    • Heartbeat - HEARTBEAT.md 워크스페이스 파일
    • 샌드박싱 - 샌드박스 환경에서의 워크스페이스 접근
    • 세션 - 세션 저장소 경로
    • 상시 지침 - 워크스페이스 파일의 영구 지침
    Was this useful?
    On this page

    On this page