Lobster

Lobster ejecuta pipelines de herramientas de varios pasos como una única llamada determinista a una herramienta, con puntos de control de aprobación explícitos y tokens de reanudación. Se sitúa una capa por encima del trabajo en segundo plano desacoplado: para orquestar flujos entre muchas tareas desacopladas, consulte Task Flow (openclaw tasks flow); para el registro de actividad de tareas, consulte Tareas en segundo plano.

Por qué

Sin Lobster, un trabajo de varios pasos implica muchas llamadas de ida y vuelta a herramientas, con el modelo orquestando cada paso. Lobster traslada esa orquestación a un entorno de ejecución tipado:

• Una llamada en lugar de muchas: una única llamada a la herramienta Lobster devuelve un resultado estructurado para todo el pipeline.
• Aprobaciones integradas: los efectos secundarios (enviar, publicar, eliminar) detienen el flujo de trabajo hasta que se aprueban explícitamente.
• Reanudable: un flujo de trabajo detenido devuelve un token; apruébelo y reanúdelo sin volver a ejecutar los pasos anteriores.

Lobster es un DSL pequeño y restringido, en lugar de un lenguaje de scripting de propósito general: aprobar/reanudar es una primitiva duradera e integrada; los pipelines son datos (fáciles de registrar, comparar, reproducir y revisar); la gramática reducida limita las rutas de código "creativas" para que la validación siga siendo realista; los tiempos de espera, los límites de salida, las comprobaciones del sandbox y las listas de permitidos son aplicados por el entorno de ejecución, no por cada script. Cada paso aún puede llamar a cualquier CLI o script: genere archivos .lobster desde otras herramientas si desea un lenguaje de creación más completo.

Sin Lobster, una clasificación recurrente de correo electrónico tiene este aspecto:

Usuario: "Revisa mi correo electrónico y redacta respuestas"→ openclaw llama a gmail.list→ El LLM resume→ Usuario: "redacta respuestas para los números 2 y 5"→ El LLM redacta→ Usuario: "envía la número 2"→ openclaw llama a gmail.send(se repite a diario, sin memoria de lo que se clasificó)

Con Lobster, el mismo trabajo es una llamada que se detiene para solicitar aprobación y se reanuda:

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

{  "ok": true,  "status": "needs_approval",  "output": [{ "summary": "5 necesitan respuesta, 2 requieren una acción" }],  "requiresApproval": {    "type": "approval_request",    "prompt": "¿Enviar 2 borradores de respuesta?",    "items": [],    "resumeToken": "..."  }}

Cómo funciona

OpenClaw ejecuta los flujos de trabajo de Lobster en el proceso mediante el paquete @clawdbot/lobster incluido como ejecutor integrado. No se genera ningún subproceso externo lobster; la llamada a la herramienta devuelve directamente un sobre JSON. Si el pipeline se detiene para solicitar aprobación, el sobre incluye un token de reanudación (o un ID de aprobación corto) para poder continuar más tarde.

Activación

Lobster es una herramienta de plugin opcional, no habilitada de forma predeterminada. Se distribuye incluida, por lo que no se requiere un paso de instalación independiente; basta con permitir la herramienta:

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

O por agente:

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

La herramienta está completamente deshabilitada en los contextos de herramientas aislados en sandbox.

Si necesita la CLI independiente de Lobster para desarrollo o pipelines externos (fuera del ejecutor integrado del Gateway), instálela desde el repositorio de Lobster y coloque lobster en PATH.

Patrón: CLI pequeña + canalizaciones JSON + aprobaciones

Cree comandos pequeños que se comuniquen mediante JSON y, a continuación, encadénelos en una única llamada a Lobster. (Los nombres de comandos siguientes son ejemplos; sustitúyalos por los suyos).

inbox list --jsoninbox categorize --jsoninbox 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 '¿Aplicar los cambios?'",  "timeoutMs": 30000}

Si el pipeline solicita aprobación, reanúdelo con el token:

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

Ejemplo: asignar elementos de entrada a llamadas a herramientas:

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

Pasos de LLM solo con JSON (llm-task)

Para un paso de LLM estructurado dentro de un flujo de trabajo, habilite la herramienta de plugin opcional llm-task y llámela desde Lobster:

{  "plugins": {    "entries": {      "llm-task": { "enabled": true }    }  },  "agents": {    "list": [      {        "id": "main",        "tools": { "alsoAllow": ["llm-task"] }      }    ]  }}

Limitación importante: Lobster integrado frente a openclaw.invoke

El plugin Lobster incluido ejecuta los flujos de trabajo en el proceso dentro del Gateway. En ese modo integrado, openclaw.invoke no hereda automáticamente un contexto de URL/autenticación del Gateway para las llamadas anidadas a herramientas de la CLI de OpenClaw.

Esto significa que este patrón no es fiable actualmente en el ejecutor integrado:

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

Use el ejemplo siguiente solo cuando ejecute la CLI independiente de Lobster en un entorno donde openclaw.invoke ya esté configurado con el contexto correcto de Gateway/autenticación.

openclaw.invoke --tool llm-task --action json --args-json '{  "prompt": "Dado el correo electrónico de entrada, devuelve la intención y un borrador.",  "thinking": "low",  "input": { "subject": "Hola", "body": "¿Puedes ayudarme?" },  "schema": {    "type": "object",    "properties": {      "intent": { "type": "string" },      "draft": { "type": "string" }    },    "required": ["intent", "draft"],    "additionalProperties": false  }}'

Si actualmente utiliza el plugin Lobster integrado, es preferible usar:

• una llamada directa a la herramienta llm-task fuera de Lobster, o
• pasos que no sean openclaw.invoke dentro del pipeline de Lobster hasta que se añada un puente integrado compatible.

Consulte Tarea de LLM para obtener más información y opciones de configuración.

Archivos de flujo de trabajo (.lobster)

Lobster puede ejecutar archivos de flujo de trabajo YAML/JSON con los campos name, args, steps, env, condition y approval. Establezca pipeline en la ruta del archivo en la llamada a la herramienta.

name: inbox-triageargs:  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

Notas:

• stdin: $step.stdout y stdin: $step.json pasan la salida de un paso anterior.
• condition (o when) puede condicionar los pasos según $step.approved.

Variables de entorno inyectadas

Cada shell de paso hereda el entorno principal, además de estas variables inyectadas por Lobster, para que los comandos puedan hacer referencia a los argumentos resueltos del flujo de trabajo sin insertar valores sin procesar en la cadena del comando:

• LOBSTER_ARG_<NAME>: una por cada argumento del flujo de trabajo. El nombre se convierte a mayúsculas y cada secuencia de caracteres no alfanuméricos se reduce a _, por lo que el argumento user-id se convierte en LOBSTER_ARG_USER_ID.
• LOBSTER_ARGS_JSON: todos los argumentos resueltos como una única cadena JSON.

Ese es el conjunto completo de variables inyectadas. No hay variables de salida por paso como LOBSTER_STEP_<id>_STDOUT o LOBSTER_STEP_<id>_JSON_<field>; los shells tratan esos nombres como no definidos, por lo que los valores predeterminados de expansión de parámetros pueden ocultar el error. En su lugar, lea la salida de un paso anterior mediante referencias a pasos: $step.stdout, $step.json o $step.json.<field>, en un valor stdin:, env: o condition:. (LOBSTER_STATE_DIR es una configuración independiente del entorno de ejecución para el directorio de estado, no un argumento por ejecución).

Parámetros de la herramienta

run

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

Ejecute un archivo de flujo de trabajo con argumentos:

{  "action": "run",  "pipeline": "/path/to/inbox-triage.lobster",  "argsJson": "{\"tag\":\"family\"}"}

resume

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

resume acepta token (el token de reanudación completo de requiresApproval) o approvalId (el ID corto del mismo objeto); use el que haya devuelto la ejecución detenida. approve es obligatorio.

Modo administrado de Task Flow

Pasar flowControllerId y flowGoal en run (o flowId y flowExpectedRevision en resume) dirige la llamada a través de la API administrada de Task Flow del entorno de ejecución del plugin, en lugar de devolver un sobre simple: OpenClaw crea o reanuda un registro de flujo duradero, le aplica el sobre de Lobster (waiting al aprobar, succeeded/failed al completarse) y devuelve { ok, envelope, flow, mutation }. Este modo requiere un entorno de ejecución de Task Flow vinculado y está destinado al código de plugins/controladores que necesita un estado de flujo duradero entre reinicios del Gateway, no al uso ad hoc habitual de los agentes.

Sobre de salida

Lobster devuelve un sobre JSON con uno de tres estados:

• ok: finalizado correctamente
• needs_approval: en pausa; requiresApproval contiene un resumeToken y un approvalId corto, cualquiera de los cuales puede reanudar la ejecución
• cancelled: denegado o cancelado explícitamente

La herramienta expone el sobre tanto en content (JSON formateado) como en details (objeto sin procesar).

Aprobaciones

Si requiresApproval está presente, examine la solicitud y decida:

• approve: true: reanudar y continuar con los efectos secundarios
• approve: false: cancelar y finalizar el flujo de trabajo

Use approve --preview-from-stdin --limit N para adjuntar una vista previa JSON a las solicitudes de aprobación sin código de enlace personalizado con jq/heredoc. El estado de reanudación se almacena como pequeños archivos JSON en el directorio de estado de Lobster (~/.lobster/state de forma predeterminada; sustitúyalo con LOBSTER_STATE_DIR); el propio token solo codifica un puntero a ese estado, no el estado completo del pipeline.

OpenProse

OpenProse funciona bien con Lobster: use /prose para orquestar la preparación de varios agentes y, a continuación, ejecute un pipeline de Lobster para obtener aprobaciones deterministas. Si un programa de Prose necesita Lobster, permita la herramienta lobster para los subagentes mediante tools.subagents.tools. Consulte OpenProse.

Seguridad

• Solo local y dentro del proceso: los flujos de trabajo se ejecutan dentro del proceso del Gateway; el propio plugin no realiza llamadas de red.
• Sin secretos: Lobster no gestiona OAuth; llama a herramientas de OpenClaw que sí lo hacen.
• Compatible con el entorno aislado: se deshabilita cuando el contexto de la herramienta está aislado.
• Reforzado: el ejecutor integrado aplica tiempos de espera y límites de salida.

Solución de problemas

Más información

• Plugins
• Creación de herramientas de Plugin

Caso práctico: flujos de trabajo de la comunidad

Un ejemplo público: una CLI de «segundo cerebro» y Pipelines de Lobster que gestionan tres bóvedas de Markdown (personal, de la pareja y compartida). La CLI genera JSON con estadísticas, listados de la bandeja de entrada y análisis de elementos obsoletos; Lobster encadena esos comandos en flujos de trabajo como weekly-review, inbox-triage, memory-consolidation y shared-task-sync, cada uno con puertas de aprobación. La IA se encarga de las decisiones (categorización) cuando está disponible y recurre a reglas deterministas cuando no lo está.

• Hilo: https://x.com/plattenschieber/status/2014508656335770033
• Repositorio: https://github.com/bloomedai/brain-cli

Relacionado

• Automatización: todos los mecanismos de automatización
• Descripción general de las herramientas: todas las herramientas de agente disponibles