> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lobster

Lobster выполняет многошаговые конвейеры инструментов как один детерминированный вызов инструмента с
явными контрольными точками подтверждения и токенами возобновления. Он находится на один уровень выше
отделённых фоновых задач: для координации потоков из множества отделённых задач
см. [Task Flow](https://docs2.openclaw.ai/ru/automation/taskflow.md) (`openclaw tasks flow`); журнал активности задач
см. в разделе [Фоновые задачи](https://docs2.openclaw.ai/ru/automation/tasks.md).

## Зачем это нужно

Без Lobster многошаговое задание требует множества последовательных вызовов инструментов, при этом
модель координирует каждый шаг. Lobster переносит эту координацию в типизированную
среду выполнения:

* **Один вызов вместо множества**: один вызов инструмента Lobster возвращает структурированный
  результат всего конвейера.
* **Встроенные подтверждения**: побочные эффекты (отправка, публикация, удаление) приостанавливают рабочий процесс
  до явного подтверждения.
* **Возможность возобновления**: приостановленный рабочий процесс возвращает токен; подтвердите и возобновите его без
  повторного выполнения предыдущих шагов.

Lobster — это небольшой ограниченный DSL, а не универсальный язык сценариев:
подтверждение и возобновление являются надёжным встроенным примитивом; конвейеры представлены данными (их легко
журналировать, сравнивать, повторно выполнять и проверять); компактная грамматика ограничивает «творческие» пути выполнения кода,
благодаря чему проверка остаётся реалистичной; ограничения времени, размера вывода, проверки песочницы и
списки разрешений применяются средой выполнения, а не каждым сценарием. Каждый шаг при этом может
вызывать любой CLI или сценарий — при необходимости создавайте файлы `.lobster` с помощью других инструментов,
если вам нужен более выразительный язык описания.

Без Lobster регулярная сортировка электронной почты выглядит так:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Пользователь: «Проверь мою почту и подготовь черновики ответов»
→ openclaw вызывает gmail.list
→ LLM формирует сводку
→ Пользователь: «подготовь черновики ответов на сообщения № 2 и № 5»
→ LLM создаёт черновики
→ Пользователь: «отправь № 2»
→ openclaw вызывает gmail.send
(повторяется ежедневно, без сохранения сведений о том, что уже было отсортировано)
```

С Lobster то же задание выполняется одним вызовом, который приостанавливается для подтверждения, а затем возобновляется:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "action": "run", "pipeline": "email.triage --limit 20", "timeoutMs": 30000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "ok": true,
  "status": "needs_approval",
  "output": [{ "summary": "На 5 сообщений нужно ответить, ещё 2 требуют действий" }],
  "requiresApproval": {
    "type": "approval_request",
    "prompt": "Отправить 2 черновика ответов?",
    "items": [],
    "resumeToken": "..."
  }
}
```

## Принцип работы

OpenClaw выполняет рабочие процессы Lobster **внутри процесса**, используя входящий в комплект
пакет `@clawdbot/lobster` как встроенную среду выполнения. Внешний подпроцесс
`lobster` не запускается; вызов инструмента напрямую возвращает JSON-конверт. Если
конвейер приостанавливается для подтверждения, конверт содержит токен возобновления (или короткий
идентификатор подтверждения), позволяющий продолжить выполнение позднее.

## Включение

Lobster — **необязательный** инструмент плагина, по умолчанию отключённый. Он поставляется
в комплекте, поэтому отдельная установка не требуется — достаточно разрешить инструмент:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}
```

Или отдельно для агента:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}
```

> [!NOTE]
>
> `alsoAllow` добавляет `lobster` поверх активного профиля инструментов, не
> ограничивая другие основные инструменты. Используйте `tools.allow`, только если вам нужен режим
> строгого списка разрешений.

В контекстах инструментов с песочницей этот инструмент полностью отключён.

Если для разработки или внешних конвейеров вам нужен автономный CLI Lobster
(вне встроенной среды выполнения Gateway), установите его из
[репозитория Lobster](https://github.com/openclaw/lobster) и добавьте `lobster` в
`PATH`.

## Шаблон: небольшие CLI + каналы JSON + подтверждения

Создавайте небольшие команды, обменивающиеся данными в формате JSON, а затем объединяйте их в один вызов Lobster.
(Имена команд ниже приведены для примера — замените их своими.)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
inbox list --json
inbox categorize --json
inbox apply --json
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "action": "run",
  "pipeline": "exec --json --shell 'inbox list --json' | exec --stdin json --shell 'inbox categorize --json' | exec --stdin json --shell 'inbox apply --json' | approve --preview-from-stdin --limit 5 --prompt 'Применить изменения?'",
  "timeoutMs": 30000
}
```

Если конвейер запрашивает подтверждение, возобновите его с помощью токена:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}
```

Пример: преобразование входных элементов в вызовы инструментов:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
gog.gmail.search --query 'newer_than:1d' \
  | openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
```

## Шаги LLM только с JSON (llm-task)

Чтобы использовать **структурированный шаг LLM** внутри рабочего процесса, включите необязательный
инструмент плагина `llm-task` и вызовите его из Lobster:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "plugins": {
    "entries": {
      "llm-task": { "enabled": true }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": { "alsoAllow": ["llm-task"] }
      }
    ]
  }
}
```

### Важное ограничение: встроенный Lobster и `openclaw.invoke`

Входящий в комплект плагин Lobster выполняет рабочие процессы **внутри процесса** Gateway.
В этом встроенном режиме `openclaw.invoke` **не** наследует автоматически
URL-адрес Gateway и контекст аутентификации для вложенных вызовов инструментов CLI OpenClaw.

Поэтому этот шаблон **в настоящее время ненадёжен во встроенной среде выполнения**:

```lobster theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw.invoke --tool llm-task --action json --args-json '{ ... }'
```

Используйте приведённый ниже пример, только если запускаете **автономный CLI Lobster** в
среде, где `openclaw.invoke` уже настроен с правильным
контекстом Gateway и аутентификации.

```lobster theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw.invoke --tool llm-task --action json --args-json '{
  "prompt": "Получив входящее письмо, верни намерение и черновик.",
  "thinking": "low",
  "input": { "subject": "Здравствуйте", "body": "Можете помочь?" },
  "schema": {
    "type": "object",
    "properties": {
      "intent": { "type": "string" },
      "draft": { "type": "string" }
    },
    "required": ["intent", "draft"],
    "additionalProperties": false
  }
}'
```

Если сейчас вы используете встроенный плагин Lobster, отдавайте предпочтение одному из вариантов:

* прямой вызов инструмента `llm-task` вне Lobster; или
* шаги, не использующие `openclaw.invoke`, внутри конвейера Lobster, пока не будет добавлен поддерживаемый
  встроенный мост.

Подробности и параметры конфигурации см. в разделе [Задача LLM](https://docs2.openclaw.ai/ru/tools/llm-task.md).

## Файлы рабочих процессов (.lobster)

Lobster может выполнять файлы рабочих процессов YAML/JSON с полями `name`, `args`, `steps`, `env`,
`condition` и `approval`. В вызове инструмента задайте в `pipeline` путь к файлу.

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
name: inbox-triage
args:
  tag:
    default: "family"
steps:
  - id: collect
    command: inbox list --json
  - id: categorize
    command: inbox categorize --json
    stdin: $collect.stdout
  - id: approve
    command: inbox apply --approve
    stdin: $categorize.stdout
    approval: required
  - id: execute
    command: inbox apply --execute
    stdin: $categorize.stdout
    condition: $approve.approved
```

Примечания:

* `stdin: $step.stdout` и `stdin: $step.json` передают вывод предыдущего шага.
* `condition` (или `when`) может ограничивать выполнение шагов в зависимости от `$step.approved`.

## Параметры инструмента

### `run`

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
  "cwd": "workspace",
  "timeoutMs": 30000,
  "maxStdoutBytes": 512000
}
```

Запуск файла рабочего процесса с аргументами:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "action": "run",
  "pipeline": "/path/to/inbox-triage.lobster",
  "argsJson": "{\"tag\":\"family\"}"
}
```

| Поле | По умолчанию | Примечания |
| - | - | - |
| `pipeline` | обязательно | Строка встроенного конвейера или путь, заканчивающийся на `.lobster`/`.yaml`/`.yml`/`.json`, для файла рабочего процесса. |
| `cwd` | cwd Gateway | Относительный рабочий каталог; должен разрешаться внутри рабочего каталога Gateway (абсолютные пути отклоняются). |
| `timeoutMs` | `20000` | Прерывает выполнение при превышении этого значения. |
| `maxStdoutBytes` | `512000` | Прерывает выполнение, если захваченный стандартный вывод или поток ошибок превышает этот размер. |
| `argsJson` | - | JSON-строка аргументов для файла рабочего процесса (игнорируется для встроенных конвейеров). |

### `resume`

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}
```

`resume` принимает либо `token` (полный токен возобновления из `requiresApproval`),
либо `approvalId` (короткий идентификатор из того же объекта) — используйте значение, возвращённое
приостановленным выполнением. `approve` является обязательным.

### Режим управляемого Task Flow

Передача `flowControllerId` и `flowGoal` в `run` (либо `flowId` и
`flowExpectedRevision` в `resume`) направляет вызов через управляемый API
[Task Flow](https://docs2.openclaw.ai/ru/automation/taskflow.md) среды выполнения плагина вместо возврата
простого конверта: OpenClaw создаёт или возобновляет постоянную запись потока, применяет к ней
конверт Lobster (`waiting` при подтверждении, `succeeded`/`failed` при
завершении) и возвращает `{ ok, envelope, flow, mutation }`. Для этого режима требуется
привязанная среда выполнения Task Flow; он предназначен для кода плагинов и контроллеров, которому необходимо
сохранять состояние потока после перезапусков Gateway, а не для обычного нерегулярного использования агентом.

## Выходной конверт

Lobster возвращает JSON-конверт с одним из трёх статусов:

* `ok` — успешно завершено
* `needs_approval` — приостановлено; `requiresApproval` содержит `resumeToken` и
  короткий `approvalId`, любой из которых позволяет возобновить выполнение
* `cancelled` — явно отклонено или отменено

Инструмент предоставляет конверт как в `content` (форматированный JSON), так и в `details`
(необработанный объект).

## Подтверждения

Если присутствует `requiresApproval`, изучите запрос и примите решение:

* `approve: true` — возобновить выполнение и продолжить побочные эффекты
* `approve: false` — отменить и завершить рабочий процесс

Используйте `approve --preview-from-stdin --limit N`, чтобы прикрепить предварительный просмотр в формате JSON к
запросам подтверждения без специальной связки jq/heredoc. Состояние возобновления хранится в
небольших JSON-файлах в каталоге состояния Lobster (`~/.lobster/state` по
умолчанию, переопределяется с помощью `LOBSTER_STATE_DIR`); сам токен кодирует только
указатель на это состояние, а не полное состояние конвейера.

## OpenProse

OpenProse хорошо сочетается с Lobster: используйте `/prose` для координации подготовки
несколькими агентами, а затем запускайте конвейер Lobster для детерминированных подтверждений. Если программе Prose
нужен Lobster, разрешите инструмент `lobster` для субагентов через
`tools.subagents.tools`. См. [OpenProse](https://docs2.openclaw.ai/ru/prose.md).

## Безопасность

* **Только локальное выполнение внутри процесса** — рабочие процессы выполняются внутри процесса Gateway; сам
  плагин не выполняет сетевых вызовов.
* **Без секретов** — Lobster не управляет OAuth; он вызывает инструменты OpenClaw,
  которые делают это.
* **Учитывает песочницу** — отключается, когда контекст инструмента находится в песочнице.
* **Усиленная защита** — ограничения времени и размера вывода применяются встроенной средой выполнения.

## Устранение неполадок

| Ошибка | Причина / исправление |
| - | - |
| `lobster runtime timed out` | Конвейер превысил `timeoutMs`. Увеличьте значение или разделите конвейер. |
| `lobster stdout exceeded maxStdoutBytes` (или `stderr`) | Объём перехваченного вывода превысил ограничение. Увеличьте `maxStdoutBytes` или сократите вывод. |
| `run --args-json must be valid JSON` | Не удалось разобрать `argsJson` (запуски из файла рабочего процесса). Исправьте строку JSON. |
| `lobster runtime failed` (или другое сообщение `runtime_error`) | Встроенная среда выполнения вернула контейнер ошибки. Подробности см. в журналах Gateway. |

## Подробнее

* [Плагины](https://docs2.openclaw.ai/ru/tools/plugin.md)
* [Создание инструментов плагина](https://docs2.openclaw.ai/ru/plugins/building-plugins.md#registering-agent-tools)

## Практический пример: рабочие процессы сообщества

Один из общедоступных примеров — CLI «второго мозга» и конвейеры Lobster, управляющие тремя
хранилищами Markdown (личным, партнёра и общим). CLI выводит JSON со статистикой,
списками входящих данных и результатами поиска устаревших элементов; Lobster объединяет эти команды в рабочие процессы,
такие как `weekly-review`, `inbox-triage`, `memory-consolidation` и
`shared-task-sync`, каждый из которых содержит этапы подтверждения. Когда ИИ доступен, он выполняет задачи,
требующие оценки (категоризацию), а при его отсутствии используются детерминированные правила.

* Обсуждение: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
* Репозиторий: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)

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

* [Автоматизация](https://docs2.openclaw.ai/ru/automation.md) — все механизмы автоматизации
* [Обзор инструментов](https://docs2.openclaw.ai/ru/tools.md) — все доступные инструменты агента