Lobster

Lobster es un shell de workflows que permite a OpenClaw ejecutar secuencias de herramientas en múltiples pasos como una sola operación determinista con puntos de control de aprobación explícitos.

Gancho

Tu asistente puede construir las herramientas que lo gestionan a sí mismo. Pide un workflow y 30 minutos después tienes un CLI más pipelines que se ejecutan como una sola llamada. Lobster es la pieza que faltaba: pipelines deterministas, aprobaciones explícitas y estado reanudable.

Por qué

Hoy, los workflows complejos requieren muchas llamadas de ida y vuelta a herramientas. Cada llamada cuesta tokens, y el LLM tiene que orquestar cada paso. Lobster mueve esa orquestación a un runtime tipado:

  • Una llamada en vez de muchas: OpenClaw ejecuta una sola llamada a la herramienta Lobster y obtiene un resultado estructurado.
  • Aprobaciones integradas: Los efectos secundarios (enviar email, publicar comentario) detienen el workflow hasta que se aprueben explícitamente.
  • Reanudable: Los workflows detenidos devuelven un token; aprueba y reanuda sin volver a ejecutar todo.

Por qué un DSL en lugar de programas normales

Lobster es intencionalmente pequeño. El objetivo no es “un nuevo lenguaje”, sino una especificación de pipeline predecible y amigable para IA con aprobaciones y tokens de reanudación de primera clase.

  • Aprobación/reanudación integradas: Un programa normal puede solicitar confirmación humana, pero no puede pausar y reanudar con un token duradero sin que inventes ese runtime tú mismo.
  • Determinismo + auditabilidad: Los pipelines son datos, así que son fáciles de registrar, comparar, reproducir y revisar.
  • Superficie restringida para IA: Una gramática pequeña + tuberías JSON reduce las rutas de código “creativas” y hace viable la validación.
  • Política de seguridad incorporada: Timeouts, límites de salida, verificaciones de sandbox y listas de permitidos son impuestos por el runtime, no por cada script.
  • Sigue siendo programable: Cada paso puede llamar a cualquier CLI o script. Si prefieres JS/TS, genera archivos .lobster desde código.

Cómo funciona

OpenClaw lanza el CLI local lobster en modo herramienta y parsea un sobre JSON desde stdout. Si el pipeline se pausa para aprobación, la herramienta devuelve un resumeToken para que puedas continuar después.

Patrón: CLI pequeño + tuberías JSON + aprobaciones

Construye comandos pequeños que hablan JSON, luego encadénalos en una sola llamada a Lobster. (Los nombres de comandos de ejemplo son ilustrativos — sustituye por los tuyos.)

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 'Apply changes?'",
  "timeoutMs": 30000
}

Si el pipeline solicita aprobación, reanuda con el token:

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

La IA dispara el workflow; Lobster ejecuta los pasos. Las puertas de aprobación mantienen los efectos secundarios explícitos y auditables.

Ejemplo: mapear elementos de entrada en 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 LLM solo JSON (llm-task)

Para workflows que necesitan un paso LLM estructurado, activa la herramienta de plugin opcional llm-task y llámala desde Lobster. Esto mantiene el workflow determinista mientras te permite clasificar/resumir/redactar con un modelo.

Activa la herramienta:

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

Úsalo en un pipeline:

openclaw.invoke --tool llm-task --action json --args-json '{
  "prompt": "Given the input email, return intent and draft.",
  "thinking": "low",
  "input": { "subject": "Hello", "body": "Can you help?" },
  "schema": {
    "type": "object",
    "properties": {
      "intent": { "type": "string" },
      "draft": { "type": "string" }
    },
    "required": ["intent", "draft"],
    "additionalProperties": false
  }
}'

Consulta LLM Task para detalles y opciones de configuración.

Archivos de workflow (.lobster)

Lobster puede ejecutar archivos de workflow YAML/JSON con campos name, args, steps, env, condition y approval. En las llamadas a herramientas de OpenClaw, configura pipeline con la ruta del archivo.

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

Notas:

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

Instalar Lobster

Instala el CLI de Lobster en el mismo host que ejecuta el Gateway de OpenClaw (consulta el repositorio de Lobster) y asegúrate de que lobster esté en PATH.

Activar la herramienta

Lobster es una herramienta de plugin opcional (no activada por defecto).

Recomendado (aditivo, seguro):

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

O por agente:

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

Evita usar tools.allow: ["lobster"] a menos que tengas la intención de ejecutar en modo restrictivo de lista de permitidos.

Nota: las listas de permitidos son opcionales para plugins opcionales. Si tu lista de permitidos solo nombra herramientas de plugins (como lobster), OpenClaw mantiene las herramientas principales habilitadas. Para restringir herramientas principales, incluye las herramientas o grupos principales que desees en la lista de permitidos también.

Ejemplo: triaje de email

Sin Lobster:

User: "Check my email and draft replies"
-> openclaw calls gmail.list
-> LLM summarizes
-> User: "draft replies to #2 and #5"
-> LLM drafts
-> User: "send #2"
-> openclaw calls gmail.send
(repeat daily, no memory of what was triaged)

Con Lobster:

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

Devuelve un sobre JSON (truncado):

{
  "ok": true,
  "status": "needs_approval",
  "output": [{ "summary": "5 need replies, 2 need action" }],
  "requiresApproval": {
    "type": "approval_request",
    "prompt": "Send 2 draft replies?",
    "items": [],
    "resumeToken": "..."
  }
}

El usuario aprueba -> reanuda:

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

Un workflow. Determinista. Seguro.

Parámetros de la herramienta

run

Ejecuta un pipeline en modo herramienta.

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

Ejecuta un archivo de workflow con argumentos:

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

resume

Continúa un workflow detenido después de la aprobación.

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

Entradas opcionales

  • cwd: Directorio de trabajo relativo para el pipeline (debe permanecer dentro del directorio de trabajo del proceso actual).
  • timeoutMs: Mata el subproceso si excede esta duración (por defecto: 20000).
  • maxStdoutBytes: Mata el subproceso si stdout excede este tamaño (por defecto: 512000).
  • argsJson: Cadena JSON pasada a lobster run --args-json (solo archivos de workflow).

Sobre de salida

Lobster devuelve un sobre JSON con uno de tres estados:

  • ok -> finalizó exitosamente
  • needs_approval -> pausado; requiresApproval.resumeToken es necesario para reanudar
  • cancelled -> explícitamente denegado o cancelado

La herramienta muestra el sobre tanto en content (JSON formateado) como en details (objeto raw).

Aprobaciones

Si requiresApproval está presente, inspecciona el prompt y decide:

  • approve: true -> reanuda y continúa con los efectos secundarios
  • approve: false -> cancela y finaliza el workflow

Usa approve --preview-from-stdin --limit N para adjuntar una vista previa JSON a las solicitudes de aprobación sin necesidad de glue personalizado con jq/heredoc. Los tokens de reanudación son compactos: Lobster almacena el estado de reanudación del workflow en su directorio de estado y devuelve una clave de token pequeña.

OpenProse

OpenProse combina bien con Lobster: usa /prose para orquestar la preparación multi-agente, luego ejecuta un pipeline de Lobster para aprobaciones deterministas. Si un programa Prose necesita Lobster, permite la herramienta lobster para sub-agentes con tools.subagents.tools. Consulta OpenProse.

Seguridad

  • Solo subproceso local — sin llamadas de red desde el plugin en sí.
  • Sin secretos — Lobster no gestiona OAuth; llama a herramientas de OpenClaw que sí lo hacen.
  • Consciente del sandbox — deshabilitado cuando el contexto de la herramienta está en sandbox.
  • Fortalecido — nombre de ejecutable fijo (lobster) en PATH; timeouts y límites de salida impuestos.

Resolución de problemas

  • lobster subprocess timed out -> aumenta timeoutMs, o divide un pipeline largo.
  • lobster output exceeded maxStdoutBytes -> aumenta maxStdoutBytes o reduce el tamaño de la salida.
  • lobster returned invalid JSON -> asegúrate de que el pipeline se ejecuta en modo herramienta y solo imprime JSON.
  • lobster failed (code ...) -> ejecuta el mismo pipeline en una terminal para inspeccionar stderr.

Más información

Caso de estudio: workflows comunitarios

Un ejemplo público: un CLI de “segundo cerebro” + pipelines de Lobster que gestionan tres bóvedas Markdown (personal, pareja, compartida). El CLI emite JSON para estadísticas, listados de bandeja de entrada y escaneos de obsolescencia; Lobster encadena esos comandos en workflows como weekly-review, inbox-triage, memory-consolidation y shared-task-sync, cada uno con puertas de aprobación. La IA maneja el juicio (categorización) cuando está disponible y recurre a reglas deterministas cuando no.

arrow_back
Anterior
LLM Task
Siguiente
Loop Detection
arrow_forward