From 8a66694c5efa9966b78344fc796919ff903c10d5 Mon Sep 17 00:00:00 2001
From: Pincer <pincer.stevenpalmer@tutamail.com>
Date: Wed, 6 May 2026 19:47:05 -0700
Subject: [PATCH] docs(lobster): clarify embedded openclaw.invoke limitation

---
 docs/tools/llm-task.md | 17 +++++++++++++++++
 docs/tools/lobster.md  | 19 ++++++++++++++++++-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/docs/tools/llm-task.md b/docs/tools/llm-task.md
index 02397dd75f1a..4dfc6ad7a71c 100644
--- a/docs/tools/llm-task.md
+++ b/docs/tools/llm-task.md
@@ -85,6 +85,23 @@ Returns `details.json` containing the parsed JSON (and validates against
 
 ## Example: Lobster workflow step
 
+### Important limitation
+
+The example below assumes the **standalone Lobster CLI** is running in an environment where `openclaw.invoke` already has the correct gateway URL/auth context.
+
+For the bundled **embedded** Lobster runner inside OpenClaw, this nested CLI pattern is **not currently reliable**:
+
+```lobster
+openclaw.invoke --tool llm-task --action json --args-json '{ ... }'
+```
+
+Until embedded Lobster has a supported bridge for this flow, prefer either:
+
+- direct `llm-task` tool calls outside Lobster, or
+- Lobster steps that do not rely on nested `openclaw.invoke` calls.
+
+Standalone Lobster CLI example:
+
 ```lobster
 openclaw.invoke --tool llm-task --action json --args-json '{
   "prompt": "Given the input email, return intent and draft.",
diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md
index b60b659b1b09..e8e209ccbca7 100644
--- a/docs/tools/lobster.md
+++ b/docs/tools/lobster.md
@@ -100,7 +100,19 @@ Enable the tool:
 }
 ```
 
-Use it in a pipeline:
+### Important limitation: embedded Lobster vs `openclaw.invoke`
+
+The bundled Lobster plugin runs workflows **in-process** inside the gateway. In that embedded mode, `openclaw.invoke` does **not** automatically inherit a gateway URL/auth context for nested OpenClaw CLI tool calls.
+
+That means this pattern is **not currently reliable in the embedded runner**:
+
+```lobster
+openclaw.invoke --tool llm-task --action json --args-json '{ ... }'
+```
+
+Use the example below only when running the **standalone Lobster CLI** in an environment where `openclaw.invoke` is already configured with the correct gateway/auth context.
+
+Use it in a standalone Lobster CLI pipeline:
 
 ```lobster
 openclaw.invoke --tool llm-task --action json --args-json '{
@@ -119,6 +131,11 @@ openclaw.invoke --tool llm-task --action json --args-json '{
 }'
 ```
 
+If you are using the embedded Lobster plugin today, prefer either:
+
+- a direct `llm-task` tool call outside Lobster, or
+- non-`openclaw.invoke` steps inside the Lobster pipeline until a supported embedded bridge is added.
+
 See [LLM Task](/tools/llm-task) for details and configuration options.
 
 ## Workflow files (.lobster)