Tools

Aragosta

Lobster è una shell per workflow che consente a OpenClaw di eseguire sequenze di strumenti in più passaggi come un'unica operazione deterministica, con checkpoint di approvazione espliciti.

Lobster è un livello di authoring sopra il lavoro in background distaccato. Per l'orchestrazione dei flussi sopra i singoli task, vedi Task Flow (openclaw tasks flow). Per il registro delle attività dei task, vedi openclaw tasks.

Hook

Il tuo assistente può creare gli strumenti che gestiscono se stesso. Chiedi un workflow e, 30 minuti dopo, hai una CLI più pipeline eseguibili con una sola chiamata. Lobster è il tassello mancante: pipeline deterministiche, approvazioni esplicite e stato ripristinabile.

Perché

Oggi, i workflow complessi richiedono molte chiamate di strumenti avanti e indietro. Ogni chiamata costa token e l'LLM deve orchestrare ogni passaggio. Lobster sposta quell'orchestrazione in un runtime tipizzato:

Una chiamata invece di molte: OpenClaw esegue una chiamata allo strumento Lobster e ottiene un risultato strutturato.
Approvazioni integrate: gli effetti collaterali (invio di email, pubblicazione di commenti) interrompono il workflow finché non vengono approvati esplicitamente.
Ripristinabile: i workflow interrotti restituiscono un token; approva e riprendi senza rieseguire tutto.

Perché una DSL invece di programmi normali?

Lobster è intenzionalmente piccolo. L'obiettivo non è "un nuovo linguaggio", ma una specifica di pipeline prevedibile e adatta all'AI, con approvazioni e token di ripresa come funzionalità di prima classe.

Approve/resume è integrato: un programma normale può chiedere conferma a una persona, ma non può mettersi in pausa e riprendere con un token duraturo senza che tu inventi quel runtime.
Determinismo + verificabilità: le pipeline sono dati, quindi sono facili da registrare, confrontare, rieseguire e revisionare.
Superficie vincolata per l'AI: una grammatica minima + piping JSON riduce i percorsi di codice "creativi" e rende realistica la validazione.
Policy di sicurezza incorporata: timeout, limiti di output, controlli sandbox e allowlist sono applicati dal runtime, non da ogni script.
Comunque programmabile: ogni passaggio può chiamare qualsiasi CLI o script. Se vuoi JS/TS, genera file .lobster dal codice.

Come funziona

OpenClaw esegue i workflow Lobster in-process usando un runner incorporato. Non viene generato alcun sottoprocesso CLI esterno; il motore del workflow viene eseguito dentro il processo del Gateway e restituisce direttamente un envelope JSON. Se la pipeline si ferma per l'approvazione, lo strumento restituisce un resumeToken così puoi continuare in seguito.

Pattern: piccola CLI + pipe JSON + approvazioni

Crea comandi piccoli che parlano JSON, poi concatenali in una singola chiamata Lobster. (I nomi dei comandi sotto sono esempi - sostituiscili con i tuoi.)

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
}

Se la pipeline richiede approvazione, riprendi con il token:

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

L'AI avvia il workflow; Lobster esegue i passaggi. I gate di approvazione mantengono gli effetti collaterali espliciti e verificabili.

Esempio: mappare elementi di input in chiamate di strumenti:

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

Passaggi LLM solo JSON (llm-task)

Per workflow che richiedono un passaggio LLM strutturato, abilita lo strumento Plugin opzionale llm-task e chiamalo da Lobster. Questo mantiene il workflow deterministico, consentendoti comunque di classificare, riassumere o redigere con un modello.

Abilita lo strumento:

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

Usalo in una 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
  }
}'

Vedi LLM Task per dettagli e opzioni di configurazione.

File di workflow (.lobster)

Lobster può eseguire file di workflow YAML/JSON con i campi name, args, steps, env, condition e approval. Nelle chiamate degli strumenti OpenClaw, imposta pipeline sul percorso del file.

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

Note:

stdin: $step.stdout e stdin: $step.json passano l'output di un passaggio precedente.
condition (o when) può vincolare i passaggi su $step.approved.

Installare Lobster

I workflow Lobster inclusi vengono eseguiti in-process; non è richiesto alcun binario lobster separato. Il runner incorporato viene fornito con il Plugin Lobster.

Se ti serve la CLI Lobster autonoma per lo sviluppo o per pipeline esterne, installala dal repo Lobster e assicurati che lobster sia in PATH.

Abilitare lo strumento

Lobster è uno strumento Plugin opzionale (non abilitato per impostazione predefinita).

Consigliato (additivo, sicuro):

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

Oppure per agente:

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

Evita di usare tools.allow: ["lobster"] a meno che tu non intenda operare in modalità allowlist restrittiva.

Esempio: triage delle email

Senza 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
}

Restituisce un envelope JSON (troncato):

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

L'utente approva → riprendi:

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

Un workflow. Deterministico. Sicuro.

Parametri dello strumento

`run`

Esegue una pipeline in modalità strumento.

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

Esegui un file di workflow con argomenti:

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

`resume`

Continua un workflow interrotto dopo l'approvazione.

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

Input opzionali

cwd: directory di lavoro relativa per la pipeline (deve restare dentro la directory di lavoro del Gateway).
timeoutMs: interrompe il workflow se supera questa durata (predefinito: 20000).
maxStdoutBytes: interrompe il workflow se l'output supera questa dimensione (predefinito: 512000).
argsJson: stringa JSON passata a lobster run --args-json (solo file di workflow).

Envelope di output

Lobster restituisce un envelope JSON con uno di tre stati:

ok → completato correttamente
needs_approval → in pausa; requiresApproval.resumeToken è richiesto per riprendere
cancelled → negato o annullato esplicitamente

Lo strumento espone l'envelope sia in content (JSON formattato) sia in details (oggetto grezzo).

Approvazioni

Se requiresApproval è presente, ispeziona il prompt e decidi:

approve: true → riprendi e continua gli effetti collaterali
approve: false → annulla e finalizza il workflow

Usa approve --preview-from-stdin --limit N per allegare un'anteprima JSON alle richieste di approvazione senza colla jq/heredoc personalizzata. I token di ripresa ora sono compatti: Lobster archivia lo stato di ripresa del workflow nella propria directory di stato e restituisce una piccola chiave token.

OpenProse

OpenProse si abbina bene a Lobster: usa /prose per orchestrare la preparazione multi-agente, poi esegui una pipeline Lobster per approvazioni deterministiche. Se un programma Prose richiede Lobster, consenti lo strumento lobster per i sub-agenti tramite tools.subagents.tools. Vedi OpenProse.

Sicurezza

Solo locale in-process - i workflow vengono eseguiti dentro il processo del Gateway; nessuna chiamata di rete dal Plugin stesso.
Nessun segreto - Lobster non gestisce OAuth; chiama gli strumenti OpenClaw che lo fanno.
Consapevole della sandbox - disabilitato quando il contesto dello strumento è in sandbox.
Rafforzato - timeout e limiti di output applicati dal runner incorporato.

Risoluzione dei problemi

lobster timed out → aumenta timeoutMs oppure suddividi una pipeline lunga.
lobster output exceeded maxStdoutBytes → aumenta maxStdoutBytes o riduci la dimensione dell'output.
lobster returned invalid JSON → assicurati che la pipeline venga eseguita in modalità strumento e stampi solo JSON.
lobster failed → controlla i log del Gateway per i dettagli dell'errore del runner incorporato.

Per saperne di più

Caso di studio: workflow della community

Un esempio pubblico: una CLI "second brain" + pipeline Lobster che gestiscono tre vault Markdown (personale, partner, condiviso). La CLI emette JSON per statistiche, elenchi inbox e scansioni di elementi obsoleti; Lobster concatena quei comandi in workflow come weekly-review, inbox-triage, memory-consolidation e shared-task-sync, ciascuno con gate di approvazione. L'AI gestisce le valutazioni (categorizzazione) quando disponibile e ripiega su regole deterministiche quando non lo è.

Correlati

Automazione e task - pianificazione dei workflow Lobster
Panoramica sull'automazione - tutti i meccanismi di automazione
Panoramica degli strumenti - tutti gli strumenti agente disponibili

# Hook

# Perché

# Perché una DSL invece di programmi normali?

# Come funziona

# Pattern: piccola CLI + pipe JSON + approvazioni

# Passaggi LLM solo JSON (llm-task)

# File di workflow (.lobster)

# Installare Lobster

# Abilitare lo strumento

# Esempio: triage delle email

# Parametri dello strumento

# run

# resume

# Input opzionali

# Envelope di output

# Approvazioni

# OpenProse

# Sicurezza

# Risoluzione dei problemi

# Per saperne di più

# Caso di studio: workflow della community

# Correlati