---
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-16T16:51:18Z"
    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 принимает коммиты и управляет отправкой/PR |

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

## Требования

- Плагин провайдера воркеров. Встроенный плагин `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` | Идентификатор провайдера воркеров, зарегистрированный плагином (`crabbox` для встроенного плагина).                                                                                                                                     |
| `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.

## Отправка сеанса

В интерфейсе управления откройте **New Session**, выберите агента, для которого в качестве настроенной среды выполнения указан OpenClaw, выберите настроенную цель **Cloud · profile** в меню **Where** и запустите задачу. При выборе облака требуемое управляемое рабочее дерево включается автоматически; 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` профиля.

## Связанные материалы

- [Изоляция](/ru/gateway/sandboxing) — уменьшение области потенциального ущерба при локальном выполнении инструментов
- [CLI сеансов](/ru/cli/sessions) — просмотр сохранённых сеансов
- [Справочник по конфигурации](/ru/gateway/configuration-reference)