QWE AI Academy You’ve asked your OpenClaw agent to check the database, transform three CSVs, generate a summary, and email the result. It works – once. The second time? Skips the transformation. Third time? Re-processes yesterday’s data because it forgot.
LLM-orchestrated chaos. Every step is a new decision, every run burns tokens, and you’re praying the agent remembers context across 12 back-and-forth tool calls.
Lobster flips this. One YAML file. The whole pipeline. The LLM triggers it once, Lobster executes every step without re-planning, asks for approval before side effects, hands back a resume token if you cancel midway. No token waste. No “oops, it sent 50 emails.”
What Lobster Actually Solves
Most OpenClaw tasks are single-shot: “summarize this,” “send that.” Those work fine with direct tool calls. Chain steps – fetch data, classify it, filter by condition, approve a preview, then act – and you hit three problems.
Token cost. Complex workflows need many back-and-forth tool calls (OpenClaw docs). Each call costs tokens. The LLM orchestrates every step. Lobster moves orchestration into a typed runtime – one call instead of many.
Determinism. Turns out a YAML file with condition, loop, and stdin piping is infinitely more reliable than telling an LLM “if the review is negative, go back to step 2, but only up to 3 times.” A DEV Community user who built a multi-agent dev pipeline said it best. Prompt engineering can’t match declarative logic.
Resumability. Approval gates built in. Halted workflows return a compact resume token (as of Jan 2026, per docs). You approve or reject, then continue without re-running everything.
Think about this: how many times have you watched an agent re-fetch the same API endpoint because it lost track of what it already processed? With Lobster, the workflow state persists. The agent doesn’t have to remember – the YAML does.
Enabling Lobster in OpenClaw
Lobster is an optional plugin (not enabled by default, per official docs). Here’s the config.
{
"plugins": {
"entries": {
"lobster": {
"enabled": true
}
}
},
"agents": {
"list": [
{
"id": "main",
"tools": {
"allow": ["lobster"]
}
}
]
}
}The allowlist trap: Set
tools.allow: ["lobster"]thinking you’re just enabling Lobster? You’ve switched to restrictive allowlist mode. Core tools stay enabled UNLESS you explicitly list them too. Docs warn this (source), but people hit it constantly. Want Lobster plus everything else? Just enable the plugin – skip the allowlist.
As of January 2026, OpenClaw runs Lobster in-process via an embedded runner. No external CLI subprocess. Older tutorials showing CLI install steps? Outdated – the plugin handles it automatically now.
Your First Workflow: Data Pipeline with Error Handling
Real scenario: daily job pulls transaction data from an API, cleans it, checks for anomalies, emails a summary. API down? Fall back to cached file. Anomalies exceed threshold? Halt and ask for review.
Create daily-tx-report.lobster:
name: daily-tx-report
args:
date:
default: "today"
threshold:
default: 5
steps:
- id: fetch
run: curl -s https://api.example.com/tx?date=${date}
when: true
- id: fallback
run: cat /data/tx-cache.json
when: $fetch.exitCode != 0
- id: clean
run: jq '.transactions | map(select(.status == "completed"))'
stdin: $fetch.exitCode == 0 ? $fetch.stdout : $fallback.stdout
- id: detect_anomalies
pipeline: >
llm_task.invoke
--prompt "Count transactions over $10k. Return JSON: {count: number}."
stdin: $clean.stdout
- id: review_gate
approval: "Found {{ $detect_anomalies.json.count }} high-value transactions. Proceed?"
when: $detect_anomalies.json.count > $threshold
- id: send_report
run: >
openclaw.invoke --tool message --action send
--args-json '{"to":"[email protected]","text":"Daily report attached"}'
when: $review_gate.approved || $detect_anomalies.json.count <= $threshold
Six steps chained. API call (fetch) fails (exit code ≠ 0)? Step 2 runs fallback. Step 3 cleans data using whichever source succeeded. Step 4 uses an LLM to classify anomalies (via llm_task.invoke, a Lobster pipeline stage). Step 5 conditionally halts if anomalies exceed threshold. Step 6 sends report only if approved or anomalies under limit.
Step References and Piping
Lobster uses $stepId.stdout, $stepId.json, $stepId.exitCode, $stepId.approved to reference previous step outputs. Each step’s output becomes available to subsequent steps through explicit references (Stanza course docs). You can’t reference a step that hasn’t run yet – Lobster resolves them in order.
.stdout for text, .json for parsed JSON. Step produces plain text and you reference .json? Parse error.
Running the Workflow
Trigger it via the Lobster tool from OpenClaw:
{
"action": "run",
"pipeline": "/path/to/daily-tx-report.lobster",
"argsJson": "{"date":"2026-04-14","threshold":3}",
"timeoutMs": 30000,
"maxStdoutBytes": 512000
}Defaults: 20 seconds timeout, 500KB output cap (per docs). Raise them if your pipeline is slow or outputs large JSON.
Workflow hits the approval gate? Returns a resumeToken. Resume with:
{
"action": "resume",
"token": "",
"approve": true
}Resume tokens are compact keys now. Lobster stores full state in its state directory, hands back a small identifier. Old workflows expecting large token strings? They’ll break after recent updates.
The openclaw.invoke Shell Gotcha
Step 6 uses openclaw.invoke with run:. Shell command. See “bash: openclaw.invoke: command not found”? Missing the npm shim.
Community users hit this constantly. One DEV commenter: “I always get bash command not found, which makes sense because that is not a valid command in bash.” The fix: Lobster’s npm install provides shim executables. Running Lobster via the embedded runner (default as of Jan 2026)? The shims forward to Lobster’s pipeline command.
The rule: run: for real binaries on your PATH (curl, jq, openclaw.invoke). pipeline: for Lobster-native stages (llm.invoke, llm_task.invoke). Don’t mix them up.
Visualizing Workflows Before You Run Them
lobster graph. Almost no tutorial covers it. You can inspect workflow structure before execution (GitHub repo):
lobster graph --file daily-tx-report.lobster --format mermaid
lobster graph --file daily-tx-report.lobster --format asciiMermaid output: flowchart. ASCII: quick terminal preview. Catches step reference errors (like referencing $deploy.stdout from a step that runs before deploy) before you burn tokens running a broken workflow.
When Lobster Isn’t the Answer
Lobster shines when you know the steps in advance. Deterministic execution. Not ideal for exploratory tasks where the agent needs to decide what to do next based on fuzzy context.
“Research this topic and write a report.” The research step might need 3 web searches or 12. The report might need fact-checking or not. Better handled by the LLM directly – not a fixed YAML pipeline. Lobster is a ruler. Great for straight lines, terrible for freehand sketching.
Lobster also doesn’t loop natively (as of early 2026). A community contributor added sub-workflow loop support (PR #20, per DEV Community). Not in stable yet. Need “retry this step up to 5 times”? You’ll have to generate separate workflows or wait for that PR to land.
Another limit: Lobster doesn’t branch into parallel paths. Every step runs sequentially. Need two agents working in parallel and merging results? You’re back to multi-agent orchestration.
Production Hardening
Lobster includes built-in retry logic, fallback paths, error notification for production use (ClawFlows blog, Feb 2026). Configure retries per step, set fallback commands that run only if the primary step fails (like we did with fetch and fallback above).
Recurring jobs? Pair Lobster with OpenClaw’s cron system. The workflow becomes the “what,” cron becomes the “when.” A skill called lobster-jobs can analyze cron jobs and convert them to Lobster workflows, flagging which ones are “fully migratable” vs. “partial.”
FAQ
Can I call other OpenClaw tools from a Lobster workflow?
Yes. openclaw.invoke --tool <tool-name> --action <action> --args-json '...' in a run: step. The invoke shim is installed with Lobster, forwards to OpenClaw’s tool runtime. Just make sure the tool is enabled for the agent running the workflow.
What happens if a workflow times out mid-execution?
Killed. No resume token. Lobster enforces timeoutMs (default 20 seconds) and maxStdoutBytes (default 512KB) at runtime level. Hit the limit? Raise timeoutMs or split the pipeline. Long-running jobs (training a model) should be triggered externally and polled – not run inside a Lobster step.
How do I pass sensitive data into a workflow without hardcoding it in YAML?
Environment variables or runtime args. Every resolved workflow arg is exposed as LOBSTER_ARG_<NAME> (uppercased, non-alphanumeric chars become underscores). The full args object is also available as LOBSTER_ARGS_JSON (GitHub docs). For secrets, pass them via argsJson at invocation time – not in the workflow file itself. Lobster doesn’t manage OAuth or API keys. It calls OpenClaw tools that do. One user shared this setup: API keys live in a .env file, the workflow reads LOBSTER_ARG_API_KEY, and the invoke shim forwards it to the underlying tool. Works, but you’re trusting the agent’s environment. For prod? Use a secrets manager that the OpenClaw tool already integrates with (like AWS Secrets Manager or Vault), then reference it by name in the workflow.
Start with a three-step workflow: fetch, transform, approve. Watch how much cleaner it feels than chaining tool calls through the LLM. Then add conditions, retries, and parallel sub-agents. The YAML is the source of truth. The agent just kicks it off.