---
read_when:
    - Вам потрібно пояснити робочий простір агента або його файлову структуру
    - Ви хочете створити резервну копію або перенести робочий простір агента
sidebarTitle: Agent workspace
summary: 'Робочий простір агента: розташування, структура та стратегія резервного копіювання'
title: Робочий простір агента
x-i18n:
    generated_at: "2026-06-27T17:24:34Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6020aa96b2aa829a9684164994d1fb1fb1b31157c47b60e947ad82f9f5508e1c
    source_path: concepts/agent-workspace.md
    workflow: 16
---

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

Це окремо від `~/.openclaw/`, де зберігаються конфігурація, облікові дані та сеанси.

<Warning>
Робочий простір є **типовим cwd**, а не жорсткою пісочницею. Інструменти розв’язують відносні шляхи відносно робочого простору, але абсолютні шляхи все ще можуть діставатися інших місць на хості, якщо пісочницю не ввімкнено. Якщо вам потрібна ізоляція, використовуйте [`agents.defaults.sandbox`](/uk/gateway/sandboxing) (та/або конфігурацію пісочниці для окремого агента).

Коли пісочницю ввімкнено і `workspaceAccess` не є `"rw"`, інструменти працюють усередині робочого простору пісочниці в `~/.openclaw/sandboxes`, а не у вашому робочому просторі хоста.
</Warning>

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

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

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

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

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

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

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

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

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

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

`openclaw doctor` попереджає, коли виявляє додаткові каталоги робочого простору.
</Note>

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

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

<AccordionGroup>
  <Accordion title="AGENTS.md - робочі інструкції">
    Робочі інструкції для агента й того, як він має використовувати пам’ять. Завантажуються на початку кожного сеансу. Добре місце для правил, пріоритетів і деталей про те, «як поводитися».
  </Accordion>
  <Accordion title="SOUL.md - персона й тон">
    Персона, тон і межі. Завантажується кожного сеансу. Посібник: [посібник із персональності SOUL.md](/uk/concepts/soul).
  </Accordion>
  <Accordion title="USER.md - хто є користувачем">
    Хто є користувачем і як до нього звертатися. Завантажується кожного сеансу.
  </Accordion>
  <Accordion title="IDENTITY.md - ім’я, вайб, емодзі">
    Ім’я агента, вайб і емодзі. Створюється/оновлюється під час ритуалу початкового налаштування.
  </Accordion>
  <Accordion title="TOOLS.md - локальні домовленості щодо інструментів">
    Нотатки про ваші локальні інструменти та домовленості. Не керує доступністю інструментів; це лише настанови.
  </Accordion>
  <Accordion title="HEARTBEAT.md - контрольний список Heartbeat">
    Необов’язковий короткий контрольний список для запусків Heartbeat. Тримайте його стислим, щоб уникнути витрат токенів.
  </Accordion>
  <Accordion title="BOOT.md - контрольний список запуску">
    Необов’язковий контрольний список запуску, який виконується автоматично під час перезапуску Gateway (коли ввімкнено [внутрішні hooks](/uk/automation/hooks)). Тримайте його стислим; використовуйте інструмент повідомлень для вихідних надсилань.
  </Accordion>
  <Accordion title="BOOTSTRAP.md - ритуал першого запуску">
    Одноразовий ритуал першого запуску. Створюється лише для цілком нового робочого простору. Видаліть його після завершення ритуалу.
  </Accordion>
  <Accordion title="memory/YYYY-MM-DD.md - щоденний журнал пам’яті">
    Щоденний журнал пам’яті (один файл на день). Рекомендовано читати сьогоднішній і вчорашній файли на початку сеансу.
  </Accordion>
  <Accordion title="MEMORY.md - упорядкована довготривала пам’ять (необов’язково)">
    Упорядкована довготривала пам’ять: сталі факти, уподобання, рішення та короткі підсумки. Тримайте докладні журнали в `memory/YYYY-MM-DD.md`, щоб інструменти пам’яті могли отримувати їх на вимогу без додавання до кожного prompt. Завантажуйте `MEMORY.md` лише в основному приватному сеансі (не у спільних/групових контекстах). Див. [Пам’ять](/uk/concepts/memory) для workflow та автоматичного скидання пам’яті.
  </Accordion>
  <Accordion title="skills/ - Skills робочого простору (необов’язково)">
    Skills, специфічні для робочого простору. Розташування Skills із найвищим пріоритетом для цього робочого простору. Перевизначає Skills агента проєкту, особисті Skills агента, керовані Skills, вбудовані Skills і `skills.load.extraDirs`, коли імена збігаються.
  </Accordion>
  <Accordion title="canvas/ - файли Canvas UI (необов’язково)">
    Файли Canvas UI для відображень вузлів (наприклад, `canvas/index.html`).
  </Accordion>
</AccordionGroup>

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

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

Це міститься в `~/.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 (саме там розміщений робочий простір).

<Steps>
  <Step title="Ініціалізуйте репозиторій">
    Якщо git встановлено, цілком нові робочі простори ініціалізуються автоматично. Якщо цей робочий простір ще не є репозиторієм, виконайте:

    ```bash
    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"
    ```

  </Step>
  <Step title="Додайте приватний remote">
    <Tabs>
      <Tab title="Вебінтерфейс GitHub">
        1. Створіть новий **приватний** репозиторій на GitHub.
        2. Не ініціалізуйте з README (це уникає конфліктів злиття).
        3. Скопіюйте HTTPS URL remote.
        4. Додайте remote і виконайте push:

        ```bash
        git branch -M main
        git remote add origin <https-url>
        git push -u origin main
        ```
      </Tab>
      <Tab title="GitHub CLI (gh)">
        ```bash
        gh auth login
        gh repo create openclaw-workspace --private --source . --remote origin --push
        ```
      </Tab>
      <Tab title="Вебінтерфейс GitLab">
        1. Створіть новий **приватний** репозиторій на GitLab.
        2. Не ініціалізуйте з README (це уникає конфліктів злиття).
        3. Скопіюйте HTTPS URL remote.
        4. Додайте remote і виконайте push:

        ```bash
        git branch -M main
        git remote add origin <https-url>
        git push -u origin main
        ```
      </Tab>
    </Tabs>

  </Step>
  <Step title="Поточні оновлення">
    ```bash
    git status
    git add .
    git commit -m "Update memory"
    git push
    ```
  </Step>
</Steps>

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

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

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

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

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

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

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

<Steps>
  <Step title="Клонуйте репозиторій">
    Клонуйте репозиторій у потрібний шлях (типово `~/.openclaw/workspace`).
  </Step>
  <Step title="Оновіть конфігурацію">
    Установіть `agents.defaults.workspace` на цей шлях у `~/.openclaw/openclaw.json`.
  </Step>
  <Step title="Додайте відсутні файли">
    Виконайте `openclaw setup --workspace <path>`, щоб додати будь-які відсутні файли.
  </Step>
  <Step title="Скопіюйте сеанси (необов’язково)">
    Якщо вам потрібні сеанси, окремо скопіюйте `~/.openclaw/agents/<agentId>/sessions/` зі старої машини.
  </Step>
</Steps>

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

- Маршрутизація кількох агентів може використовувати різні робочі простори для кожного агента. Див. [Маршрутизація каналів](/uk/channels/channel-routing) для конфігурації маршрутизації.
- Якщо `agents.defaults.sandbox` увімкнено, неосновні сеанси можуть використовувати робочі простори пісочниці для окремих сеансів у `agents.defaults.sandbox.workspaceRoot`.

## Пов’язане

- [Heartbeat](/uk/gateway/heartbeat) - файл робочого простору HEARTBEAT.md
- [Пісочниця](/uk/gateway/sandboxing) - доступ до робочого простору в ізольованих середовищах
- [Сеанс](/uk/concepts/session) - шляхи зберігання сеансів
- [Постійні інструкції](/uk/automation/standing-orders) - сталі інструкції у файлах робочого простору