Lobster

Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints.

Lobster is one authoring layer above detached background work. For flow orchestration above individual tasks, see Task Flow (

). For the task activity ledger, see

text

Copy

openclaw tasks

.

Hook

Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state.

Why

Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime:

• One call instead of many: OpenClaw runs one Lobster tool call and gets a structured result.
• Approvals built in: Side effects (send email, post comment) halt the workflow until explicitly approved.
• Resumable: Halted workflows return a token; approve and resume without re-running everything.

Why a DSL instead of plain programs?

Lobster is intentionally small. The goal is not "a new language," it's a predictable, AI-friendly pipeline spec with first-class approvals and resume tokens.

• Approve/resume is built in: A normal program can prompt a human, but it can’t pause and resume with a durable token without you inventing that runtime yourself.
• Determinism + auditability: Pipelines are data, so they’re easy to log, diff, replay, and review.
• Constrained surface for AI: A tiny grammar + JSON piping reduces “creative” code paths and makes validation realistic.
• Safety policy baked in: Timeouts, output caps, sandbox checks, and allowlists are enforced by the runtime, not each script.
• Still programmable: Each step can call any CLI or script. If you want JS/TS, generate
  text

  Copy

  .lobster
  files from code.

How it works

OpenClaw runs Lobster workflows in-process using an embedded runner. No external CLI subprocess is spawned; the workflow engine executes inside the gateway process and returns a JSON envelope directly. If the pipeline pauses for approval, the tool returns a

so you can continue later.

Pattern: small CLI + JSON pipes + approvals

Build tiny commands that speak JSON, then chain them into a single Lobster call. (Example command names below — swap in your own.)

bash
Copy
inbox list --json
inbox categorize --json
inbox apply --json

json
Copy
{
  "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
}

If the pipeline requests approval, resume with the token:

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

AI triggers the workflow; Lobster executes the steps. Approval gates keep side effects explicit and auditable.

Example: map input items into tool calls:

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

JSON-only LLM steps (llm-task)

For workflows that need a structured LLM step, enable the optional

plugin tool and call it from Lobster. This keeps the workflow deterministic while still letting you classify/summarize/draft with a model.

Enable the tool:

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

Use it in a pipeline:

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

See LLM Task for details and configuration options.

Workflow files (.lobster)

Lobster can run YAML/JSON workflow files with

, , , , , and fields. In OpenClaw tool calls, set to the file path.

yaml
Copy
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

Notes:

• text

  Copy

  stdin: $step.stdout
  and
  text

  Copy

  stdin: $step.json
  pass a prior step’s output.
• text

  Copy

  condition
  (or
  text

  Copy

  when
  ) can gate steps on
  text

  Copy

  $step.approved
  .

Install Lobster

Bundled Lobster workflows run in-process; no separate

binary is required. The embedded runner ships with the Lobster plugin.

If you need the standalone Lobster CLI for development or external pipelines, install it from the Lobster repo and ensure

is on .

Enable the tool

Lobster is an optional plugin tool (not enabled by default).

Recommended (additive, safe):

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

Or per-agent:

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

Avoid using

unless you intend to run in restrictive allowlist mode.

Example: Email triage

Without Lobster:

text
Copy
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)

With Lobster:

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

Returns a JSON envelope (truncated):

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

User approves → resume:

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

One workflow. Deterministic. Safe.

Tool parameters

text

Copy

run

Run a pipeline in tool mode.

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

Run a workflow file with args:

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

text

Copy

resume

Continue a halted workflow after approval.

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

Optional inputs

• text

  Copy

  cwd
  : Relative working directory for the pipeline (must stay within the gateway working directory).
• text

  Copy

  timeoutMs
  : Abort the workflow if it exceeds this duration (default: 20000).
• text

  Copy

  maxStdoutBytes
  : Abort the workflow if output exceeds this size (default: 512000).
• text

  Copy

  argsJson
  : JSON string passed to
  text

  Copy

  lobster run --args-json
  (workflow files only).

Output envelope

Lobster returns a JSON envelope with one of three statuses:

• text

  Copy

  ok
  → finished successfully
• text

  Copy

  needs_approval
  → paused;
  text

  Copy

  requiresApproval.resumeToken
  is required to resume
• text

  Copy

  cancelled
  → explicitly denied or cancelled

The tool surfaces the envelope in both

(pretty JSON) and (raw object).

Approvals

If

is present, inspect the prompt and decide:

• text

  Copy

  approve: true
  → resume and continue side effects
• text

  Copy

  approve: false
  → cancel and finalize the workflow

Use

to attach a JSON preview to approval requests without custom jq/heredoc glue. Resume tokens are now compact: Lobster stores workflow resume state under its state dir and hands back a small token key.

OpenProse

OpenProse pairs well with Lobster: use

to orchestrate multi-agent prep, then run a Lobster pipeline for deterministic approvals. If a Prose program needs Lobster, allow the tool for sub-agents via . See OpenProse.

Safety

• Local in-process only — workflows execute inside the gateway process; no network calls from the plugin itself.
• No secrets — Lobster doesn't manage OAuth; it calls OpenClaw tools that do.
• Sandbox-aware — disabled when the tool context is sandboxed.
• Hardened — timeouts and output caps enforced by the embedded runner.

Troubleshooting

• text

  Copy

  lobster timed out
  → increase
  text

  Copy

  timeoutMs
  , or split a long pipeline.
• text

  Copy

  lobster output exceeded maxStdoutBytes
  → raise
  text

  Copy

  maxStdoutBytes
  or reduce output size.
• text

  Copy

  lobster returned invalid JSON
  → ensure the pipeline runs in tool mode and prints only JSON.
• text

  Copy

  lobster failed
  → check gateway logs for the embedded runner error details.

Learn more

• Plugins
• Plugin tool authoring

Case study: community workflows

One public example: a “second brain” CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like

, , , and , each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not.

• Thread: https://x.com/plattenschieber/status/2014508656335770033
• Repo: https://github.com/bloomedai/brain-cli

Related

• Automation & Tasks — scheduling Lobster workflows
• Automation Overview — all automation mechanisms
• Tools Overview — all available agent tools