Робочий простір агента

Робочий простір є домом агента. Це єдиний робочий каталог, який використовується для файлових інструментів і контексту робочого простору. Зберігайте його приватним і ставтеся до нього як до пам’яті. Це окремо від ~/.openclaw/, де зберігаються конфігурація, облікові дані та сеанси.

Робочий простір є типовим cwd, а не жорсткою пісочницею. Інструменти розв’язують відносні шляхи відносно робочого простору, але абсолютні шляхи все ще можуть діставатися інших місць на хості, якщо пісочницю не ввімкнено. Якщо вам потрібна ізоляція, використовуйте agents.defaults.sandbox (та/або конфігурацію пісочниці для окремого агента).Коли пісочницю ввімкнено і workspaceAccess не є "rw", інструменти працюють усередині робочого простору пісочниці в ~/.openclaw/sandboxes, а не у вашому робочому просторі хоста.

Типове розташування

Типово: ~/.openclaw/workspace
Якщо OPENCLAW_PROFILE задано і це не "default", типовим стає ~/.openclaw/workspace-<profile>.
Перевизначення в ~/.openclaw/openclaw.json:

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

openclaw onboard, openclaw configure або openclaw setup створить робочий простір і додасть початкові файли, якщо їх бракує.

Початкові копії для пісочниці приймають лише звичайні файли всередині робочого простору; псевдоніми symlink/hardlink, які розв’язуються за межі вихідного робочого простору, ігноруються.

Якщо ви вже самостійно керуєте файлами робочого простору, можна вимкнути створення початкових файлів:

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

Додаткові папки робочого простору

Старіші встановлення могли створити ~/openclaw. Наявність кількох каталогів робочого простору може спричинити плутанину з автентифікацією або розбіжність стану, бо активним одночасно є лише один робочий простір.

Рекомендація: тримайте один активний робочий простір. Якщо ви більше не використовуєте додаткові папки, заархівуйте їх або перемістіть у Trash (наприклад, trash ~/openclaw). Якщо ви навмисно тримаєте кілька робочих просторів, переконайтеся, що agents.defaults.workspace вказує на активний.openclaw doctor попереджає, коли виявляє додаткові каталоги робочого простору.

Мапа файлів робочого простору

Це стандартні файли, які OpenClaw очікує всередині робочого простору:

AGENTS.md - робочі інструкції

Робочі інструкції для агента й того, як він має використовувати пам’ять. Завантажуються на початку кожного сеансу. Добре місце для правил, пріоритетів і деталей про те, «як поводитися».

SOUL.md - персона й тон

Персона, тон і межі. Завантажується кожного сеансу. Посібник: посібник із персональності SOUL.md.

USER.md - хто є користувачем

Хто є користувачем і як до нього звертатися. Завантажується кожного сеансу.

IDENTITY.md - ім’я, вайб, емодзі

Ім’я агента, вайб і емодзі. Створюється/оновлюється під час ритуалу початкового налаштування.

TOOLS.md - локальні домовленості щодо інструментів

Нотатки про ваші локальні інструменти та домовленості. Не керує доступністю інструментів; це лише настанови.

HEARTBEAT.md - контрольний список Heartbeat

Необов’язковий короткий контрольний список для запусків Heartbeat. Тримайте його стислим, щоб уникнути витрат токенів.

BOOT.md - контрольний список запуску

Необов’язковий контрольний список запуску, який виконується автоматично під час перезапуску Gateway (коли ввімкнено внутрішні hooks). Тримайте його стислим; використовуйте інструмент повідомлень для вихідних надсилань.

BOOTSTRAP.md - ритуал першого запуску

Одноразовий ритуал першого запуску. Створюється лише для цілком нового робочого простору. Видаліть його після завершення ритуалу.

memory/YYYY-MM-DD.md - щоденний журнал пам’яті

Щоденний журнал пам’яті (один файл на день). Рекомендовано читати сьогоднішній і вчорашній файли на початку сеансу.

MEMORY.md - упорядкована довготривала пам’ять (необов’язково)

Упорядкована довготривала пам’ять: сталі факти, уподобання, рішення та короткі підсумки. Тримайте докладні журнали в memory/YYYY-MM-DD.md, щоб інструменти пам’яті могли отримувати їх на вимогу без додавання до кожного prompt. Завантажуйте MEMORY.md лише в основному приватному сеансі (не у спільних/групових контекстах). Див. Пам’ять для workflow та автоматичного скидання пам’яті.

skills/ - Skills робочого простору (необов’язково)

Skills, специфічні для робочого простору. Розташування Skills із найвищим пріоритетом для цього робочого простору. Перевизначає Skills агента проєкту, особисті Skills агента, керовані Skills, вбудовані Skills і skills.load.extraDirs, коли імена збігаються.

canvas/ - файли Canvas UI (необов’язково)

Файли Canvas UI для відображень вузлів (наприклад, canvas/index.html).

Якщо бракує будь-якого початкового файлу, OpenClaw вставляє маркер «missing file» у сеанс і продовжує. Великі початкові файли обрізаються під час вставлення; налаштуйте ліміти через agents.defaults.bootstrapMaxChars (типово: 20000) і agents.defaults.bootstrapTotalMaxChars (типово: 60000). openclaw setup може повторно створити відсутні типові файли, не перезаписуючи наявні.

Що НЕ входить до робочого простору

Це міститься в ~/.openclaw/ і НЕ має комітитися в репозиторій робочого простору:

~/.openclaw/openclaw.json (конфігурація)
~/.openclaw/agents/<agentId>/agent/auth-profiles.json (профілі автентифікації моделі: OAuth + API keys)
~/.openclaw/agents/<agentId>/agent/codex-home/ (обліковий запис середовища виконання Codex для окремого агента, конфігурація, Skills, plugins і нативний стан потоків)
~/.openclaw/credentials/ (стан channel/provider плюс дані імпорту застарілого OAuth)
~/.openclaw/agents/<agentId>/sessions/ (транскрипти сеансів + метадані)
~/.openclaw/skills/ (керовані Skills)

Якщо потрібно перенести сеанси або конфігурацію, скопіюйте їх окремо й тримайте поза системою контролю версій.

Git-резервна копія (рекомендовано, приватно)

Ставтеся до робочого простору як до приватної пам’яті. Помістіть його в приватний git-репозиторій, щоб мати резервну копію та можливість відновлення. Виконайте ці кроки на машині, де працює Gateway (саме там розміщений робочий простір).

Ініціалізуйте репозиторій

Якщо 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"

Додайте приватний remote

Вебінтерфейс GitHub
GitHub CLI (gh)
Вебінтерфейс GitLab

Створіть новий приватний репозиторій на GitHub.
Не ініціалізуйте з README (це уникає конфліктів злиття).
Скопіюйте HTTPS URL remote.
Додайте remote і виконайте push:

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

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

Створіть новий приватний репозиторій на GitLab.
Не ініціалізуйте з README (це уникає конфліктів злиття).
Скопіюйте HTTPS URL remote.
Додайте remote і виконайте push:

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

Поточні оновлення

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

Не комітьте секрети

Навіть у приватному репозиторії уникайте зберігання секретів у робочому просторі:

API keys, OAuth tokens, паролі або приватні облікові дані.
Будь-що в ~/.openclaw/.
Необроблені дампи чатів або чутливі вкладення.

Якщо вам потрібно зберігати чутливі посилання, використовуйте placeholders і тримайте справжній секрет в іншому місці (менеджер паролів, змінні середовища або ~/.openclaw/).

Рекомендований початковий .gitignore:

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

Перенесення робочого простору на нову машину

Клонуйте репозиторій

Клонуйте репозиторій у потрібний шлях (типово ~/.openclaw/workspace).

Оновіть конфігурацію

Установіть agents.defaults.workspace на цей шлях у ~/.openclaw/openclaw.json.

Додайте відсутні файли

Виконайте openclaw setup --workspace <path>, щоб додати будь-які відсутні файли.

Скопіюйте сеанси (необов’язково)

Якщо вам потрібні сеанси, окремо скопіюйте ~/.openclaw/agents/<agentId>/sessions/ зі старої машини.

Розширені нотатки

Маршрутизація кількох агентів може використовувати різні робочі простори для кожного агента. Див. Маршрутизація каналів для конфігурації маршрутизації.
Якщо agents.defaults.sandbox увімкнено, неосновні сеанси можуть використовувати робочі простори пісочниці для окремих сеансів у agents.defaults.sandbox.workspaceRoot.

Пов’язане

Heartbeat - файл робочого простору HEARTBEAT.md
Пісочниця - доступ до робочого простору в ізольованих середовищах
Сеанс - шляхи зберігання сеансів
Постійні інструкції - сталі інструкції у файлах робочого простору

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Робочий простір агента

Типове розташування

Додаткові папки робочого простору

Мапа файлів робочого простору

Що НЕ входить до робочого простору

Git-резервна копія (рекомендовано, приватно)

Не комітьте секрети

Перенесення робочого простору на нову машину

Розширені нотатки

Пов’язане

​Типове розташування

​Додаткові папки робочого простору

​Мапа файлів робочого простору

​Що НЕ входить до робочого простору

​Git-резервна копія (рекомендовано, приватно)

​Не комітьте секрети

​Перенесення робочого простору на нову машину

​Розширені нотатки

​Пов’язане

Типове розташування

Додаткові папки робочого простору

Мапа файлів робочого простору

Що НЕ входить до робочого простору

Git-резервна копія (рекомендовано, приватно)

Не комітьте секрети

Перенесення робочого простору на нову машину

Розширені нотатки

Пов’язане