Homard

Lobster exécute des pipelines d’outils en plusieurs étapes sous la forme d’un unique appel d’outil déterministe, avec des points de contrôle d’approbation explicites et des jetons de reprise. Il se situe un niveau au-dessus des travaux détachés en arrière-plan : pour orchestrer des flux entre de nombreuses tâches détachées, consultez Task Flow (openclaw tasks flow) ; pour le registre d’activité des tâches, consultez Tâches en arrière-plan.

Pourquoi

Sans Lobster, une tâche en plusieurs étapes implique de nombreux allers-retours d’appels d’outils, le modèle orchestrant chaque étape. Lobster transfère cette orchestration dans un environnement d’exécution typé :

Un seul appel au lieu de plusieurs : un unique appel à l’outil Lobster renvoie un résultat structuré pour l’ensemble du pipeline.
Approbations intégrées : les effets de bord (envoyer, publier, supprimer) interrompent le workflow jusqu’à leur approbation explicite.
Reprise possible : un workflow interrompu renvoie un jeton ; approuvez-le et reprenez-le sans réexécuter les étapes précédentes.

Lobster est un petit DSL contraint plutôt qu’un langage de script généraliste : l’approbation et la reprise constituent une primitive durable et intégrée ; les pipelines sont des données (faciles à journaliser, comparer, rejouer et examiner) ; la grammaire minimale limite les chemins de code « créatifs », ce qui permet de conserver une validation réaliste ; les délais d’expiration, limites de sortie, contrôles du bac à sable et listes d’autorisation sont imposés par l’environnement d’exécution, et non par chaque script. Chaque étape peut néanmoins appeler n’importe quelle CLI ou n’importe quel script ; générez des fichiers .lobster depuis d’autres outils si vous souhaitez disposer d’un langage de création plus riche. Sans Lobster, un tri récurrent des e-mails ressemble à ceci :

Utilisateur : « Vérifie mes e-mails et rédige des réponses »
→ openclaw appelle gmail.list
→ Le LLM résume
→ Utilisateur : « rédige des réponses aux e-mails nº 2 et nº 5 »
→ Le LLM rédige
→ Utilisateur : « envoie le nº 2 »
→ openclaw appelle gmail.send
(répétition quotidienne, sans mémoire des éléments déjà triés)

Avec Lobster, la même tâche tient en un seul appel qui s’interrompt pour approbation et peut ensuite reprendre :

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

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

Fonctionnement

OpenClaw exécute les workflows Lobster dans le processus à l’aide du paquet @clawdbot/lobster intégré, utilisé comme moteur d’exécution embarqué. Aucun sous-processus externe lobster n’est lancé ; l’appel d’outil renvoie directement une enveloppe JSON. Si le pipeline s’interrompt pour approbation, l’enveloppe contient un jeton de reprise (ou un identifiant d’approbation court) permettant de continuer ultérieurement.

Activation

Lobster est un outil de Plugin facultatif, qui n’est pas activé par défaut. Il est fourni avec OpenClaw ; aucune étape d’installation distincte n’est donc requise, il suffit d’autoriser l’outil :

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

Ou pour chaque agent :

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

alsoAllow ajoute lobster au profil d’outils actif sans restreindre les autres outils principaux. Utilisez tools.allow uniquement si vous souhaitez plutôt un mode restrictif fondé sur une liste d’autorisation.

L’outil est entièrement désactivé dans les contextes d’outils placés en bac à sable. Si vous avez besoin de la CLI Lobster autonome pour le développement ou pour des pipelines externes (en dehors du moteur Gateway embarqué), installez-la depuis le dépôt Lobster et ajoutez lobster au PATH.

Modèle : petite CLI, tubes JSON et approbations

Créez de petites commandes qui communiquent en JSON, puis enchaînez-les dans un unique appel à Lobster. (Les noms de commandes ci-dessous sont des exemples ; remplacez-les par les vôtres.)

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 le pipeline demande une approbation, reprenez son exécution avec le jeton :

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

Exemple : convertir les éléments d’entrée en appels d’outils :

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

Étapes LLM exclusivement en JSON (llm-task)

Pour intégrer une étape LLM structurée à un workflow, activez l’outil de Plugin facultatif llm-task et appelez-le depuis Lobster :

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

Limitation importante : Lobster embarqué et `openclaw.invoke`

Le Plugin Lobster fourni exécute les workflows dans le processus, à l’intérieur du Gateway. Dans ce mode embarqué, openclaw.invoke n’hérite pas automatiquement d’un contexte d’URL ou d’authentification du Gateway pour les appels imbriqués aux outils de la CLI OpenClaw. Cela signifie que ce modèle n’est actuellement pas fiable dans le moteur embarqué :

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

N’utilisez l’exemple ci-dessous que lorsque vous exécutez la CLI Lobster autonome dans un environnement où openclaw.invoke est déjà configuré avec le bon contexte de Gateway et d’authentification.

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

Si vous utilisez actuellement le Plugin Lobster embarqué, privilégiez soit :

un appel direct à l’outil llm-task en dehors de Lobster, soit
des étapes n’utilisant pas openclaw.invoke dans le pipeline Lobster, jusqu’à l’ajout d’une passerelle embarquée prise en charge.

Consultez Tâche LLM pour plus de détails et connaître les options de configuration.

Fichiers de workflow (.lobster)

Lobster peut exécuter des fichiers de workflow YAML/JSON comportant les champs name, args, steps, env, condition et approval. Dans l’appel d’outil, définissez pipeline sur le chemin du fichier.

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

Remarques :

stdin: $step.stdout et stdin: $step.json transmettent la sortie d’une étape précédente.
condition (ou when) peut conditionner les étapes à $step.approved.

Paramètres de l’outil

`run`

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

Exécuter un fichier de workflow avec des arguments :

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

Champ	Valeur par défaut	Remarques
`pipeline`	obligatoire	Chaîne de pipeline en ligne, ou chemin se terminant par `.lobster`/`.yaml`/`.yml`/`.json` pour un fichier de workflow.
`cwd`	cwd du Gateway	Répertoire de travail relatif ; il doit être résolu dans le répertoire de travail du Gateway (les chemins absolus sont refusés).
`timeoutMs`	`20000`	Interrompt l’exécution en cas de dépassement.
`maxStdoutBytes`	`512000`	Interrompt l’exécution si la sortie standard ou la sortie d’erreur capturée dépasse cette taille.
`argsJson`	-	Chaîne JSON d’arguments pour un fichier de workflow (ignorée pour les pipelines en ligne).

`resume`

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

resume accepte soit token (le jeton de reprise complet provenant de requiresApproval), soit approvalId (l’identifiant court provenant du même objet) ; utilisez celui que l’exécution interrompue a renvoyé. approve est obligatoire.

Mode Task Flow géré

La transmission de flowControllerId et flowGoal à run (ou de flowId et flowExpectedRevision à resume) fait passer l’appel par l’API Task Flow gérée de l’environnement d’exécution du Plugin, au lieu de renvoyer une enveloppe brute : OpenClaw crée ou reprend un enregistrement de flux durable, lui applique l’enveloppe Lobster (waiting lors d’une approbation, succeeded/failed à la fin) et renvoie { ok, envelope, flow, mutation }. Ce mode nécessite un environnement d’exécution Task Flow associé et s’adresse au code de Plugin ou de contrôleur qui requiert un état de flux durable malgré les redémarrages du Gateway, et non à l’utilisation ponctuelle habituelle d’un agent.

Enveloppe de sortie

Lobster renvoie une enveloppe JSON présentant l’un des trois états suivants :

ok - exécution terminée avec succès
needs_approval - exécution en pause ; requiresApproval contient un resumeToken et un approvalId court, chacun pouvant servir à reprendre l’exécution
cancelled - exécution explicitement refusée ou annulée

L’outil expose l’enveloppe à la fois dans content (JSON mis en forme) et dans details (objet brut).

Approbations

Si requiresApproval est présent, examinez le message et décidez :

approve: true - reprendre l’exécution et poursuivre les effets de bord
approve: false - annuler et terminer le workflow

Utilisez approve --preview-from-stdin --limit N pour joindre un aperçu JSON aux demandes d’approbation sans assemblage personnalisé avec jq ou heredoc. L’état de reprise est stocké sous forme de petits fichiers JSON dans le répertoire d’état de Lobster (~/.lobster/state par défaut, remplaçable avec LOBSTER_STATE_DIR) ; le jeton lui-même encode uniquement un pointeur vers cet état, et non l’état complet du pipeline.

OpenProse

OpenProse s’associe bien à Lobster : utilisez /prose pour orchestrer la préparation multi-agent, puis exécutez un pipeline Lobster pour obtenir des approbations déterministes. Si un programme Prose a besoin de Lobster, autorisez l’outil lobster pour les sous-agents via tools.subagents.tools. Consultez OpenProse.

Sécurité

Uniquement en local et dans le processus - les workflows s’exécutent dans le processus du Gateway ; le Plugin lui-même n’effectue aucun appel réseau.
Aucun secret - Lobster ne gère pas OAuth ; il appelle les outils OpenClaw qui s’en chargent.
Compatible avec le bac à sable - désactivé lorsque le contexte d’outil est placé en bac à sable.
Renforcé - les délais d’expiration et les limites de sortie sont imposés par le moteur embarqué.

Résolution des problèmes

Erreur	Cause / solution
`lobster runtime timed out`	Le pipeline a dépassé `timeoutMs`. Augmentez sa valeur ou divisez le pipeline.
`lobster stdout exceeded maxStdoutBytes` (ou `stderr`)	La sortie capturée a dépassé la limite. Augmentez `maxStdoutBytes` ou réduisez la sortie.
`run --args-json must be valid JSON`	L’analyse de `argsJson` (pour l’exécution d’un fichier de workflow) a échoué. Corrigez la chaîne JSON.
`lobster runtime failed` (ou un autre message `runtime_error`)	L’environnement d’exécution embarqué a renvoyé une enveloppe d’erreur. Consultez les journaux du Gateway pour plus de détails.

En savoir plus

Étude de cas : workflows de la communauté

Un exemple public : une CLI de « second cerveau » et des pipelines Lobster qui gèrent trois coffres Markdown (personnel, partenaire, partagé). La CLI génère du JSON pour les statistiques, les listes de la boîte de réception et les analyses des éléments obsolètes ; Lobster enchaîne ces commandes dans des flux de travail tels que weekly-review, inbox-triage, memory-consolidation et shared-task-sync, chacun comportant des étapes d’approbation. L’IA se charge des décisions (catégorisation) lorsqu’elle est disponible et se rabat sur des règles déterministes dans le cas contraire.

Fil de discussion : https://x.com/plattenschieber/status/2014508656335770033
Dépôt : https://github.com/bloomedai/brain-cli

Ressources connexes

Automatisation - tous les mécanismes d’automatisation
Présentation des outils - tous les outils d’agent disponibles

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Pourquoi

Fonctionnement

Activation

Modèle : petite CLI, tubes JSON et approbations

Étapes LLM exclusivement en JSON (llm-task)

Limitation importante : Lobster embarqué et `openclaw.invoke`

Fichiers de workflow (.lobster)

Paramètres de l’outil

`run`

`resume`

Mode Task Flow géré

Enveloppe de sortie

Approbations

OpenProse

Sécurité

Résolution des problèmes

En savoir plus

Étude de cas : workflows de la communauté

Ressources connexes

​Pourquoi

​Fonctionnement

​Activation

​Modèle : petite CLI, tubes JSON et approbations

​Étapes LLM exclusivement en JSON (llm-task)

​Limitation importante : Lobster embarqué et openclaw.invoke

​Fichiers de workflow (.lobster)

​Paramètres de l’outil

​run

​resume

​Mode Task Flow géré

​Enveloppe de sortie

​Approbations

​OpenProse

​Sécurité

​Résolution des problèmes

​En savoir plus

​Étude de cas : workflows de la communauté

​Ressources connexes

Pourquoi

Fonctionnement

Activation

Modèle : petite CLI, tubes JSON et approbations

Étapes LLM exclusivement en JSON (llm-task)

Limitation importante : Lobster embarqué et `openclaw.invoke`

Fichiers de workflow (.lobster)

Paramètres de l’outil

`run`

`resume`

Mode Task Flow géré

Enveloppe de sortie

Approbations

OpenProse

Sécurité

Résolution des problèmes

En savoir plus

Étude de cas : workflows de la communauté

Ressources connexes