---
read_when: You want agent sessions to run on ephemeral cloud machines instead of the Gateway host, or you are configuring cloudWorkers profiles.
sidebarTitle: Cloud Workers
status: active
summary: 'Спрямування сеансів на одноразові хмарні машини: підготовка ресурсів, середовище виконання воркера, проксований інференс і потокове передавання результатів'
title: Хмарні воркери
x-i18n:
    generated_at: "2026-07-16T18:01:28Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: c20b3b4f1408ed3ef0beb155a207f99476323cf67eba7b44931eec32c79e52be
    source_path: gateway/cloud-workers.md
    workflow: 16
---

Хмарні робочі середовища дають змогу сеансу виконувати цикл агента на тимчасовій хмарній машині, тоді як усе, що стосується сеансу, залишається там, де й завжди: відображається на бічній панелі, транслюється наживо, а транскрипт належить Gateway. Gateway орендує машину, установлює на ній зафіксовану версію OpenClaw, синхронізує робочий простір сеансу й передає цикл обробки ходу обмеженому процесу `openclaw worker`. Виклики моделі проксіюються назад через Gateway, тому облікові дані провайдера ніколи не залишають вашу машину, а кешування запитів продовжує працювати, оскільки провайдер бачить один безперервний потік.

Коли роботу завершено (або машина припиняє роботу), її видаляють. Стійкий стан — транскрипт, коміти робочого простору, записи про розміщення — зберігається в Gateway.

<Note>
Хмарні робочі середовища вмикаються явно й залишаються невидимими, доки не буде налаштовано профіль. У неналаштованих установках не з’являються нові RPC, конфігурація чи інтерфейс.
</Note>

## Що де виконується

| Складова                                                 | Розташування                                                                         |
| ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Цикл агента й інструменти (`exec`, `read`, `write`, `edit`, …) | Хмарна робоча машина                                                                 |
| Виведення моделі й облікові дані провайдера                | Gateway (проксіюються за посиланням `{provider, model}`)                               |
| Транскрипт (стійке сховище сеансу)                     | Gateway                                                                          |
| Пряма трансляція на бічну панель                         | Розгалуження Gateway, яке отримує відтворюваний потік подій робочого середовища                      |
| Історія Git робочого простору                                   | Створюється на машині без облікових даних; Gateway приймає коміти й відповідає за push/PR |

Машині не потрібні вхідні порти, окрім `sshd`: Gateway установлює вихідне з’єднання через SSH із фіксацією ключа, а зворотний тунель передає WebSocket робочого середовища назад. Вбудований провайдер Crabbox примусово використовує загальнодоступний маршрут SSH і вимикає кероване підключення до Tailscale. Вихідний доступ до інтернету визначається політикою провайдера; стандартний профіль AWS має доступ до інтернету, якщо його мережу або групу безпеки не обмежено.

## Вимоги

- Plugin провайдера робочого середовища. Вбудований Plugin `crabbox` керує CLI [Crabbox](https://github.com/openclaw/crabbox), який розподіляє оренди між хмарними бекендами (AWS, Hetzner та іншими). Виконуваний файл `crabbox` має бути в `PATH` (або задайте `settings.binary`), а облікові дані провайдера мають бути вже налаштовані. Для допуску до AWS потрібен Crabbox 0.38.1 або новіший.
- Для робочих середовищ Crabbox AWS фактичне значення `aws.instanceProfile` має бути порожнім. Перед виділенням ресурсів провайдер перевіряє `crabbox config show --json`, а потім вимагає, щоб `crabbox inspect --json` повідомляв `providerMetadata.instanceProfileAttached: false` із EC2 `DescribeInstances`. Оренди з роллю екземпляра або без авторитетних метаданих зупиняються й відхиляються.
- Node.js на орендованій машині. У базових хмарних образах його зазвичай немає — установіть його командою `setup` профілю.
- Сеанс із керованим робочим деревом, що належить сеансу (створіть його за допомогою `worktree: true`). Під час надсилання переміщується вміст цього робочого дерева; звичайні каталоги синхронізуються як дзеркало маніфесту.

## Конфігурація

Додайте профіль у `cloudWorkers.profiles` у файлі `openclaw.json`:

```json
{
  "cloudWorkers": {
    "profiles": {
      "aws": {
        "provider": "crabbox",
        "install": "bundle",
        "settings": {
          "provider": "aws",
          "class": "standard",
          "ttl": "8h",
          "idleTimeout": "45m",
          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"
        }
      }
    }
  }
}
```

Поля профілю:

| Ключ        | Значення                                                                                                                                                                                                                                        |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | Ідентифікатор провайдера робочого середовища, зареєстрований Plugin (`crabbox` для вбудованого Plugin).                                                                                                                                                                  |
| `install`  | `bundle` (за замовчуванням) постачає збірку запущеного Gateway; `npm` установлює точну випущену версію Gateway із зафіксованою цілісністю. `npm` вимагає, щоб Gateway запускався з пакетного випуску.                                                      |
| `settings` | JSON, яким керує провайдер. Для crabbox: `provider` (бекенд), `class` (клас машини), `ttl`, `idleTimeout` (тривалості Go), необов’язковий `setup` та абсолютний шлях `binary`. OpenClaw примусово використовує загальнодоступний SSH і вимикає керований Tailscale для цих оренд. |
| `lifetime` | Необов’язкова збережена політика (`idleTimeoutMinutes`, `maxLifetimeMinutes`).                                                                                                                                                                           |

### Команда налаштування

`settings.setup` виконується на орендованій машині після готовності SSH і до встановлення OpenClaw. Вона виконується під час **кожної** спроби підготовки (зокрема повторних спроб після перерваного надсилання), тому має бути ідемпотентною — захищайте встановлення перевіркою `command -v`/`test -x`, як у прикладі. Якщо налаштування завершується невдало, провайдер зупиняє оренду, а надсилання безпечно завершується помилкою; частково налаштована машина не залишається запущеною.

### Канали встановлення

- **`bundle`** пакує `dist` запущеного Gateway, скорочений `package.json` і всі пакети робочого простору, на які посилається збірка; усе це захищається хешем вмісту. Машина перевіряє незмінений пакет за цим хешем, а потім установлює виробничі залежності npm (сценарії вимкнено). Так запускається збірка для розробки в робочому середовищі.
- **`npm`** перевіряє наявність випуску в загальнодоступному реєстрі, фіксує його цілісність SHA-512 та встановлює `openclaw@<version>`, що точно відповідає Gateway.

## Надсилання сеансу

У Control UI відкрийте **New Session**, виберіть агента, налаштованим середовищем виконання якого є OpenClaw, у меню **Where** виберіть налаштовану ціль **Cloud · profile** і запустіть завдання. Вибір хмари автоматично вмикає потрібне кероване робоче дерево; Gateway створює сеанс, завершує надсилання й лише після цього надсилає перший хід. Значок сервера на бічній панелі сеансу показує стійкий стан розміщення. Хмарні цілі не пропонуються для каталогів сеансів зовнішнього CLI.

Еквівалентна послідовність RPC:

Створіть сеанс із керованим робочим деревом, а потім надішліть його (RPC вимагає `operator.admin` й існує лише за наявності налаштованих профілів):

Хмарні робочі середовища запускають середовище виконання агента OpenClaw. Виберіть `openai/*` або іншу модель, що зіставляється з цим середовищем виконання; сеанси, налаштовані для зовнішнього середовища виконання CLI, як-от `claude-cli`, не можна надіслати.

```bash
openclaw gateway call sessions.create \
  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}'

openclaw gateway call sessions.dispatch \
  --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'
```

`sessions.dispatch` припиняє локальний прийом ходів, очікує завершення активної роботи, готує оренду, виконує налаштування, завантажує OpenClaw, синхронізує робочий простір і повертає керування, коли розміщення переходить до стану володіння робочим середовищем `active`. Закладайте кілька хвилин на перше надсилання; оренди й установлення кешуються, якщо провайдер це підтримує. Після цього взаємодійте із сеансом як зазвичай — ходи автоматично спрямовуються до робочого середовища.

Після завершення ходів робочого середовища придатні файли робочого простору обмеженого розміру узгоджуються назад із керованим робочим деревом сеансу до звільнення заявки на хід. Термінальна подія робочого середовища створює стійкий бар’єр очікуваного результату до підтвердження, тому під час відновлення після перезапуску Gateway віддалений робочий простір завантажується назад до того, як очищення застарілого ходу зможе знищити його власника. Узгодження автентифікує маніфест робочого середовища й зупиняється в разі локального розходження замість перезапису будь-якої зі сторін. Перед зміною файлів Gateway зберігає обмежений журнал відкочування у своїй базі даних стану SQLite; повторна спроба відновлює цей журнал після переривання процесу Gateway. Результати робочого простору використовують файлову семантику Git: звичайні файли, біти виконання, символічні посилання, додавання, зміни й видалення зберігаються, а порожні каталоги та інші режими каталогів — ні. Віддалені об’єкти комітів не зберігаються; отримані зміни файлів залишаються в керованому робочому дереві для звичайної перевірки й коміту.

Коли роботу завершено й жоден хід не виконується, відкрийте меню сеансу та виберіть **Stop cloud worker…**. Gateway виконує остаточне узгодження робочого простору перед знищенням середовища. Розміщення, що вже перебуває в `draining` або `reconciling`, завершує демонтаж; перш ніж видаляти сеанс, зачекайте, доки його значок не зміниться на `reclaimed`.

Для несправного або некерованого підключеного робочого середовища оператор може як крайній захід викликати `environments.destroy` із `{ "force": true }`. Примусовий демонтаж стійко позначає розміщення як невдале та відкидає всі неузгоджені віддалені результати перед знищенням середовища.

Еквівалентний адміністративний RPC:

```bash
openclaw gateway call sessions.reclaim \
  --timeout 600000 \
  --params '{"key":"agent:main:big-refactor"}'
```

Розміщення проходить через стійкий скінченний автомат (`local → requested → provisioning → syncing → starting → active`), тому після перезапуску Gateway посеред надсилання виконується узгодження, а не залишаються невивільнені машини. Невдалий хід моделі залишає активне розміщення доступним для повторної спроби. Якщо вхідне узгодження робочого простору завершується невдало, робоче середовище також залишається активним, щоб оператор міг усунути локальний конфлікт і повторити спробу без втрати віддаленого результату; натомість помилки життєвого циклу переводять розміщення в стан помилки або повернення й зберігають завершальну частину діагностичних даних.

## Модель безпеки

- **Закритий вхідний доступ до робочого середовища.** Робочі середовища взаємодіють через спеціальний протокол у тунельованому сокеті із закритим списком дозволених методів — робоче середовище не може викликати операторські RPC.
- **Створені облікові дані, хешовані під час зберігання.** Кожне надсилання створює облікові дані робочого середовища; Gateway зберігає лише їхній хеш. Ротація облікових даних і відсікання за епохою власника гарантують не більше одного активного власника на сеанс — застаріле робоче середовище, що повторно підключається, відсікається й ніколи не об’єднується.
- **Фіксація ключа хоста.** Провайдер має надати ключ SSH-хоста машини під час підготовки; початкове завантаження підключається зі строгою фіксацією ключа й безпечно завершується помилкою за його відсутності.
- **На машині немає постійних облікових даних моделі, платформи розробки чи хмари.** Автентифікація моделі залишається в Gateway (виведення передається за посиланням `{provider, model}`), Git-коміти робочого простору створюються без облікових даних платформи розробки, а метадані оренди Crabbox AWS авторитетно перевіряються на наявність ролі екземпляра до налаштування. Команди налаштування також не повинні містити облікових даних.
- **Вихідний трафік під керуванням провайдера.** Зворотний тунель усуває потребу OpenClaw у прямому доступі до моделі, але OpenClaw не змінює правила брандмауера провайдера. Обмежуйте вихідний трафік у провайдері робочого середовища, коли цього потребує завдання.
- **Стійкі транскрипти з рівно одноразовим записом.** Робоче середовище фіксує пакети транскрипту через протокол порівняння й заміни відносно кінцевого вузла сеансу; застаріла база аварійно зупиняє виконання замість дублювання або перебазування оплачуваного виводу.

## Усунення несправностей

- **`sessions.dispatch` — невідомий метод** — не налаштовано жодного `cloudWorkers.profiles` або викликач не має `operator.admin`.
- **«Хмарні запуски воркера потребують середовища виконання OpenClaw»** — виберіть модель, налаштованим середовищем виконання якої є OpenClaw. Зовнішні середовища виконання CLI, як-от `claude-cli`, не підтримують інференс воркера.
- **«Для початкового завантаження воркера потрібен Node.js на орендованому хості»** — додайте встановлення Node до `settings.setup` (див. вище).
- **Атестація ролі екземпляра AWS завершується помилкою** — очистьте `aws.instanceProfile` (і `CRABBOX_AWS_INSTANCE_PROFILE`, якщо задано). Установіть Crabbox 0.38.1 або новішої версії; старіші двійкові файли не надають авторитетного контракту `providerMetadata.instanceProfileAttached`, потрібного для допуску AWS.
- **Диспетчеризація завершується помилкою постачальника** — запис розміщення та `environments.list` зберігають останню помилку, зокрема кінцеву частину stderr налаштування/початкового завантаження. У разі помилки бокси знищуються, тому ця кінцева частина є основним джерелом для розслідування.
- **Час очікування клієнта спливає під час диспетчеризації** — `openclaw gateway call` типово має час очікування 10s; задавайте `--timeout` із достатнім запасом (диспетчеризація в будь-якому разі продовжує виконуватися на сервері, а повторна спроба під час підготовки відхиляється з `session cannot dispatch from placement provisioning`).
- **Обслуговування оренд** — `crabbox list --provider <backend>` показує активні оренди; `crabbox stop --provider <backend> --id <lease>` вивільняє одну з них вручну. Неактивні оренди завершуються після закінчення визначеного в профілі `idleTimeout`.

## Пов’язані матеріали

- [Ізоляція](/uk/gateway/sandboxing) — зменшення радіуса ураження під час локального виконання інструментів
- [CLI сеансів](/uk/cli/sessions) — перевірка збережених сеансів
- [Довідник із конфігурації](/uk/gateway/configuration-reference)