Lobster

Lobster 是一個工作流程 shell，讓 OpenClaw 能夠以單一確定性操作執行多步驟工具序列，並設有明確的審批檢查點。

核心價值

你的助理可以自行打造管理工具。提出需求，半小時後你就有一套 CLI 加上可一次呼叫執行的流水線。Lobster 正是那塊拼圖：確定性流水線、明確審批、可恢復狀態。

為什麼需要 Lobster

現有的複雜工作流程需要大量來回的工具呼叫，每次呼叫都消耗 token，而且 LLM 必須協調每個步驟。Lobster 將這些協調工作移入型別化執行環境：

  • 一次呼叫取代多次：OpenClaw 執行一次 Lobster 工具呼叫就能取得結構化結果。
  • 內建審批機制：有副作用的操作（寄信、發留言）會暫停工作流程，等待明確核准。
  • 可恢復：暫停的工作流程會回傳 token；核准後即可繼續，無需重頭執行。

為什麼用 DSL 而非一般程式？

Lobster 刻意保持精簡。目標不是「發明新語言」，而是提供一個可預測、對 AI 友善的流水線規格，具備一級審批機制與恢復 token。

  • 審批/恢復是原生功能：一般程式可以向使用者提問，但無法在沒有自建執行環境的情況下以持久 token 暫停與恢復。
  • 確定性加可稽核性：流水線就是資料，容易記錄、比對、重播和審查。
  • 限縮 AI 的操作面：精簡的語法加上 JSON 管道，減少「創意」程式碼路徑，讓驗證變得可行。
  • 安全策略內建：超時、輸出上限、沙箱檢查和允許清單由執行環境統一執行，而非各腳本自行處理。
  • 仍然可程式化：每個步驟都能呼叫任何 CLI 或腳本。想用 JS/TS？從程式碼產生 .lobster 檔案即可。

運作原理

OpenClaw 以工具模式啟動本機的 lobster CLI，並從 stdout 解析 JSON 封包。 如果流水線因審批而暫停，工具會回傳 resumeToken 讓你稍後繼續。

模式：小型 CLI + JSON 管道 + 審批

打造小型指令讓它們輸出 JSON，再串接成單一 Lobster 呼叫。（以下為範例指令名稱，可替換成你自己的。）

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
}

如果流水線需要審批，使用 token 繼續：

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

AI 觸發工作流程；Lobster 執行步驟。審批閘門讓副作用保持明確且可稽核。

範例：將輸入項目對應到工具呼叫：

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

JSON 專用 LLM 步驟（llm-task）

當工作流程需要結構化 LLM 步驟時，啟用選用的 llm-task 外掛工具並從 Lobster 呼叫它。 這樣可以維持工作流程的確定性，同時利用模型進行分類/摘要/草擬。

啟用工具：

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

在流水線中使用：

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

詳情與設定選項請參閱 LLM Task。

工作流程檔案（.lobster）

Lobster 可以執行包含 name、args、steps、env、condition 和 approval 欄位的 YAML/JSON 工作流程檔案。在 OpenClaw 工具呼叫中，將 pipeline 設為檔案路徑。

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

注意事項：

  • stdin: $step.stdout 和 stdin: $step.json 可傳遞前一步驟的輸出。
  • condition（或 when）可根據 $step.approved 控制步驟執行。

安裝 Lobster

在運行 OpenClaw 閘道的同一台主機上安裝 Lobster CLI（請參閱 Lobster 儲存庫），並確保 lobster 在 PATH 中。

啟用工具

Lobster 是選用外掛工具（預設未啟用）。

建議（附加式，安全）：

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

或針對特定代理：

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

除非你想啟用限制性允許清單模式，否則避免使用 tools.allow: ["lobster"]。

注意：允許清單是選用外掛的加入機制。如果你的允許清單只列出外掛工具（如 lobster），OpenClaw 會保持核心工具可用。若要限制核心工具，請在允許清單中一併加入你需要的核心工具或群組。

範例：郵件分流

不使用 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)

使用 Lobster：

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

回傳 JSON 封包（簡化版）：

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

使用者核准 → 繼續：

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

一個工作流程。確定性。安全。

工具參數

run

以工具模式執行流水線。

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

以引數執行工作流程檔案：

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

resume

審批後繼續暫停的工作流程。

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

選填輸入

  • cwd：流水線的相對工作目錄（必須在當前程序工作目錄內）。
  • timeoutMs：子程序超過此時間則終止（預設：20000）。
  • maxStdoutBytes：stdout 超過此大小則終止子程序（預設：512000）。
  • argsJson：傳遞給 lobster run --args-json 的 JSON 字串（僅限工作流程檔案）。

輸出封包

Lobster 回傳的 JSON 封包有三種狀態：

  • ok → 成功完成
  • needs_approval → 已暫停；需要 requiresApproval.resumeToken 才能繼續
  • cancelled → 被明確拒絕或取消

工具會在 content（格式化 JSON）和 details（原始物件）中呈現封包。

審批

如果存在 requiresApproval，請檢視提示並決定：

  • approve: true → 繼續執行副作用
  • approve: false → 取消並結束工作流程

使用 approve --preview-from-stdin --limit N 可將 JSON 預覽附加到審批請求，無需自訂 jq/heredoc。恢復 token 現在更精簡：Lobster 將工作流程恢復狀態儲存在其狀態目錄下，只回傳一個小型 token 鍵值。

OpenProse

OpenProse 與 Lobster 搭配良好：使用 /prose 協調多代理準備工作，再執行 Lobster 流水線進行確定性審批。如果 Prose 程式需要 Lobster，請透過 tools.subagents.tools 為子代理允許 lobster 工具。參閱 OpenProse。

安全性

  • 僅限本機子程序 — 外掛本身不進行網路呼叫。
  • 不管理密鑰 — Lobster 不處理 OAuth；它呼叫有處理 OAuth 的 OpenClaw 工具。
  • 感知沙箱 — 在沙箱化的工具環境中自動停用。
  • 強化防護 — 固定可執行檔名稱（lobster）須在 PATH 中；超時與輸出上限由執行環境強制執行。

疑難排解

  • lobster subprocess timed out → 增加 timeoutMs，或拆分過長的流水線。
  • lobster output exceeded maxStdoutBytes → 提高 maxStdoutBytes 或減少輸出量。
  • lobster returned invalid JSON → 確認流水線以工具模式執行且只輸出 JSON。
  • lobster failed (code …) → 在終端機中執行相同流水線以檢查 stderr。

延伸閱讀

案例研究：社群工作流程

一個公開範例：一套「第二大腦」CLI 搭配 Lobster 流水線，管理三個 Markdown vault（個人、伴侶、共用）。CLI 以 JSON 輸出統計、收件匣清單和過期掃描；Lobster 將這些指令串接成 weekly-review、inbox-triage、memory-consolidation 和 shared-task-sync 等工作流程，每個都設有審批閘門。AI 在可用時處理判斷（分類），不可用時退回確定性規則。

arrow_back
上一頁
LLM Task
下一頁
Loop Detection
arrow_forward