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

​

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

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