Lobster

Lobster выполняет многошаговые конвейеры инструментов как один детерминированный вызов инструмента с явными контрольными точками подтверждения и токенами возобновления. Он находится на один уровень выше отделённых фоновых задач: для координации потоков из множества отделённых задач см. Task Flow (openclaw tasks flow); журнал активности задач см. в разделе Фоновые задачи.

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

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

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

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

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

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

{ "action": "run", "pipeline": "email.triage --limit 20", "timeoutMs": 30000 }

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

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

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

Включение

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

{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}

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

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}

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

В контекстах инструментов с песочницей этот инструмент полностью отключён. Если для разработки или внешних конвейеров вам нужен автономный CLI Lobster (вне встроенной среды выполнения Gateway), установите его из репозитория Lobster и добавьте lobster в PATH.

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

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

inbox list --json
inbox categorize --json
inbox apply --json

{
  "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
}

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

{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

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

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:

{
  "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. Поэтому этот шаблон в настоящее время ненадёжен во встроенной среде выполнения:

openclaw.invoke --tool llm-task --action json --args-json '{ ... }'

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

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.

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

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

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`

{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
  "cwd": "workspace",
  "timeoutMs": 30000,
  "maxStdoutBytes": 512000
}

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

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

{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

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

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

Передача flowControllerId и flowGoal в run (либо flowId и flowExpectedRevision в resume) направляет вызов через управляемый API Task Flow среды выполнения плагина вместо возврата простого конверта: 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.

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

Только локальное выполнение внутри процесса — рабочие процессы выполняются внутри процесса 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.

Подробнее

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

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

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

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

Автоматизация — все механизмы автоматизации
Обзор инструментов — все доступные инструменты агента

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

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

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

Включение

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

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

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

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

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

`run`

`resume`

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

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

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

OpenProse

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

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

Подробнее

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

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

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

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

​Включение

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

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

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

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

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

​run

​resume

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

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

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

​OpenProse

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

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

​Подробнее

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

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

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

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

Включение

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

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

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

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

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

`run`

`resume`

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

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

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

OpenProse

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

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

Подробнее

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

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