跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Lobster 是一個工作流程 shell，可讓 OpenClaw 將多步驟工具序列作為單一、確定性的操作執行，並具備明確的核准檢查點。 Lobster 是獨立背景工作之上的一層撰寫層。若要了解個別任務之上的流程編排，請參閱 Task Flow（openclaw tasks flow）。若要了解任務活動帳本，請參閱 openclaw tasks。

​
掛鉤

你的助理可以建置管理自身的工具。提出一個工作流程需求，30 分鐘後你就會有一個 CLI 加上可作為一次呼叫執行的管線。Lobster 是缺少的那一塊：確定性管線、明確核准，以及可恢復狀態。

​
為什麼

如今，複雜工作流程需要許多來回工具呼叫。每次呼叫都會消耗 token，而 LLM 必須編排每個步驟。Lobster 會把該編排移入型別化執行環境：
  • 一次呼叫取代多次呼叫：OpenClaw 執行一次 Lobster 工具呼叫，並取得結構化結果。
  • 內建核准：副作用（傳送電子郵件、發布留言）會讓工作流程暫停，直到明確核准。
  • 可恢復：暫停的工作流程會回傳 token；核准後即可恢復，而不必重新執行所有內容。

​
為什麼使用 DSL，而不是普通程式？

Lobster 有意保持小巧。目標不是「一門新語言」，而是一種可預測、AI 友善的管線規格，具備一級核准與恢復 token。
  • 內建核准/恢復：一般程式可以提示人類，但若不自行發明該執行環境，它無法用持久 token 暫停並恢復。
  • 確定性 + 可稽核性：管線是資料，因此容易記錄、差異比較、重播與審查。
  • 受限的 AI 介面：極小的文法 + JSON 管線傳遞可減少「創意」程式碼路徑，並讓驗證變得可行。
  • 內建安全政策：逾時、輸出上限、沙盒檢查與允許清單由執行環境強制執行，而不是由每個指令碼各自處理。
  • 仍然可程式化：每個步驟都可以呼叫任何 CLI 或指令碼。如果你想使用 JS/TS，可從程式碼產生 .lobster 檔案。

​
運作方式

OpenClaw 使用嵌入式執行器在程序內執行 Lobster 工作流程。不會產生外部 CLI 子程序；工作流程引擎會在 gateway 程序內執行，並直接回傳 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 plugin 工具，並從 Lobster 呼叫它。這可讓工作流程保持 確定性，同時仍能使用模型進行分類、摘要與草擬。 啟用工具： 
{
  "plugins": {
    "entries": {
      "llm-task": { "enabled": true }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": { "alsoAllow": ["llm-task"] }
      }
    ]
  }
}

​
重要限制：嵌入式 Lobster 與 openclaw.invoke

內建的 Lobster plugin 會在 gateway 內程序內執行工作流程。在該嵌入式模式中，openclaw.invoke 不會自動繼承 gateway URL/驗證情境以供巢狀 OpenClaw CLI 工具呼叫使用。 這表示此模式目前在嵌入式執行器中並不可靠： 
openclaw.invoke --tool llm-task --action json --args-json '{ ... }'
只有在執行獨立 Lobster CLI，且 openclaw.invoke 已設定正確 gateway/驗證情境的環境中，才使用下方範例。 在獨立 Lobster CLI 管線中使用它： 
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
  }
}'
如果你今天使用的是嵌入式 Lobster plugin，請優先使用以下任一方式：
  • 在 Lobster 外部直接呼叫 llm-task 工具，或
  • 在 Lobster 管線內使用非 openclaw.invoke 步驟，直到加入支援的嵌入式橋接。
請參閱 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

內建 Lobster 工作流程會在程序內執行；不需要單獨的 lobster 二進位檔。嵌入式執行器隨 Lobster plugin 提供。 如果你需要獨立 Lobster CLI 來進行開發或外部管線，請從 Lobster repo 安裝，並確保 lobster 位於 PATH。

​
啟用工具

Lobster 是選用的 plugin 工具（預設未啟用）。 建議方式（加法式、安全）： 
{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}
或依代理程式設定： 
{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}
除非你打算在限制性允許清單模式中執行，否則請避免使用 tools.allow: ["lobster"]。
允許清單對選用 plugins 採用選擇加入。alsoAllow 只會啟用指定的選用 plugin 工具，同時保留一般核心工具集。若要限制核心工具，請使用 tools.allow 搭配你想要的核心工具或群組。

​
範例：電子郵件分類處理

沒有 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
}
使用 args 執行工作流程檔案： 
{
  "action": "run",
  "pipeline": "/path/to/inbox-triage.lobster",
  "argsJson": "{\"tag\":\"family\"}"
}

​
resume

在核准後繼續已暫停的工作流程。 
{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

​
選用輸入

  • cwd：管線的相對工作目錄（必須保留在 gateway 工作目錄內）。
  • timeoutMs：如果工作流程超過此持續時間，則中止（預設：20000）。
  • maxStdoutBytes：如果輸出超過此大小，則中止（預設：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 key。

​
OpenProse

OpenProse 與 Lobster 搭配良好：使用 /prose 編排多代理準備工作，然後執行 Lobster 管線進行確定性核准。如果 Prose 程式需要 Lobster，請透過 tools.subagents.tools 允許子代理使用 lobster 工具。請參閱 OpenProse。

​
安全性

  • 僅限本機程序內 - 工作流程在 gateway 程序內執行；plugin 本身不會發出網路呼叫。
  • 無秘密資訊 - Lobster 不管理 OAuth；它會呼叫處理這些事項的 OpenClaw 工具。
  • 感知沙盒 - 當工具情境位於沙盒中時停用。
  • 強化 - 逾時與輸出上限由嵌入式執行器強制執行。

​
疑難排解

  • lobster timed out → 增加 timeoutMs，或拆分較長的管線。
  • lobster output exceeded maxStdoutBytes → 提高 maxStdoutBytes 或減少輸出大小。
  • lobster returned invalid JSON → 確保管線在工具模式中執行，且只印出 JSON。
  • lobster failed → 檢查 gateway 記錄以取得嵌入式執行器錯誤詳細資訊。

​
深入了解

​
案例研究：社群工作流程

一個公開範例：「第二大腦」CLI + Lobster 管線，用來管理三個 Markdown vault（個人、伴侶、共享）。CLI 會輸出統計資料、收件匣清單與過期掃描的 JSON；Lobster 會將這些指令串接成 weekly-review、inbox-triage、memory-consolidation 與 shared-task-sync 等工作流程，每個都具備核准關卡。可用時由 AI 處理判斷（分類），不可用時則退回確定性規則。

​
相關