English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Fundamentals

에이전트 작업 공간

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

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

기본 위치

  • 기본값: ~/.openclaw/workspace
  • OPENCLAW_PROFILE이 설정되어 있고 "default"가 아니면, 기본값은 ~/.openclaw/workspace-<profile>이 됩니다.
  • ~/.openclaw/openclaw.json에서 재정의:
json5
{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",    },  },}

openclaw onboard, openclaw configure 또는 openclaw setup은 워크스페이스를 만들고 bootstrap 파일이 없으면 초기 파일을 배치합니다.

워크스페이스 파일을 이미 직접 관리하고 있다면 bootstrap 파일 생성을 비활성화할 수 있습니다.

json5
{ agents: { defaults: { skipBootstrap: true } } }

추가 워크스페이스 폴더

이전 설치에서는 ~/openclaw가 만들어졌을 수 있습니다. 활성 워크스페이스는 한 번에 하나뿐이므로, 여러 워크스페이스 디렉터리를 남겨 두면 인증 또는 상태 드리프트가 혼란스러울 수 있습니다.

워크스페이스 파일 맵

다음은 OpenClaw가 워크스페이스 안에 있을 것으로 기대하는 표준 파일입니다.

AGENTS.md - operating instructions

에이전트를 위한 운영 지침과 메모리 사용 방식입니다. 모든 세션 시작 시 로드됩니다. 규칙, 우선순위, “행동 방식” 세부 사항을 두기에 좋은 위치입니다.

SOUL.md - persona and tone

페르소나, 톤, 경계입니다. 모든 세션에서 로드됩니다. 가이드: SOUL.md 성격 가이드.

USER.md - who the user is

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

IDENTITY.md - name, vibe, emoji

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

TOOLS.md - local tool conventions

로컬 도구와 규칙에 대한 메모입니다. 도구 사용 가능 여부를 제어하지 않으며, 안내용일 뿐입니다.

HEARTBEAT.md - heartbeat checklist

Heartbeat 실행을 위한 선택적 작은 체크리스트입니다. 토큰 소모를 피하려면 짧게 유지하세요.

BOOT.md - startup checklist

Gateway 재시작 시(internal hooks가 활성화된 경우) 자동으로 실행되는 선택적 시작 체크리스트입니다. 짧게 유지하고, outbound 전송에는 메시지 도구를 사용하세요.

BOOTSTRAP.md - first-run ritual

일회성 최초 실행 의식입니다. 완전히 새 워크스페이스에만 생성됩니다. 의식이 완료되면 삭제하세요.

memory/YYYY-MM-DD.md - daily memory log

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

MEMORY.md - curated long-term memory (optional)

선별된 장기 메모리: 지속적인 사실, 선호도, 결정, 짧은 요약입니다. 자세한 로그는 memory/YYYY-MM-DD.md에 보관해 메모리 도구가 필요할 때 검색할 수 있게 하고, 모든 프롬프트에 주입하지 않도록 하세요. MEMORY.md는 메인 비공개 세션에서만 로드하세요(공유/그룹 컨텍스트 제외). 워크플로와 자동 메모리 flush는 메모리를 참고하세요.

skills/ - workspace skills (optional)

워크스페이스별 Skills입니다. 해당 워크스페이스에서 가장 높은 우선순위를 갖는 Skills 위치입니다. 이름이 충돌하면 프로젝트 에이전트 Skills, 개인 에이전트 Skills, 관리형 Skills, bundled Skills, skills.load.extraDirs를 재정의합니다.

canvas/ - Canvas UI files (optional)

노드 표시용 Canvas UI 파일입니다(예: canvas/index.html).

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

다음은 ~/.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가 실행되는 머신에서 실행하세요(워크스페이스가 있는 곳입니다).

  • Initialize the repo

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

    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"

  • Add a private remote

    GitHub web UI

    1. GitHub에서 새 private 저장소를 만듭니다.
    2. README로 초기화하지 마세요(merge conflict 방지).
    3. HTTPS remote URL을 복사합니다.
    4. remote를 추가하고 push합니다.
    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 web UI

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

  • Ongoing updates

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

    • 비밀을 커밋하지 마세요

    제안하는 .gitignore 시작점:

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

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

  • Clone the repo

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

  • Update config

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

  • Seed missing files

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

  • 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 - 워크스페이스 파일의 지속적 지침
    Was this useful?
    On this page

    On this page