Lobster

Lobster 将多步骤工具流水线作为一次确定性的工具调用运行，并提供明确的审批检查点和恢复令牌。它位于分离式后台工作的上一层：如需编排跨多个分离式任务的流程，请参阅 Task Flow（openclaw tasks flow）；如需查看任务活动账本，请参阅后台任务。

原因

如果没有 Lobster，多步骤作业意味着需要多次往返工具调用，由模型编排每个步骤。Lobster 将这种编排移入类型化运行时：

• 一次调用代替多次调用：一次 Lobster 工具调用即可返回整个流水线的结构化结果。
• 内置审批：副作用操作（发送、发布、删除）会暂停工作流，直至获得明确批准。
• 可恢复：暂停的工作流会返回一个令牌；批准后即可恢复，无需重新运行之前的步骤。

Lobster 是一种小型、受限的 DSL，而不是通用脚本语言：批准/恢复是持久的内置原语；流水线是数据（易于记录、比较差异、重放和审查）；精简的语法限制了“创造性”代码路径，使验证保持切合实际；超时、输出上限、沙箱检查和允许列表均由运行时强制执行，而不是由各个脚本执行。每个步骤仍然可以调用任意 CLI 或脚本——如果需要更丰富的编写语言，可以使用其他工具生成 .lobster 文件。

如果没有 Lobster，重复执行的电子邮件分类流程如下：

用户：“检查我的电子邮件并起草回复”→ openclaw 调用 gmail.list→ LLM 进行总结→ 用户：“为第 2 封和第 5 封起草回复”→ LLM 起草回复→ 用户：“发送第 2 封”→ openclaw 调用 gmail.send（每天重复，且不记得已经分类过哪些邮件）

使用 Lobster 后，同一作业只需一次调用，该调用会暂停以等待审批，并可在之后恢复：

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

{  "ok": true,  "status": "needs_approval",  "output": [{ "summary": "5 封需要回复，2 封需要处理" }],  "requiresApproval": {    "type": "approval_request",    "prompt": "发送 2 封回复草稿？",    "items": [],    "resumeToken": "..."  }}

工作原理

OpenClaw 使用内置的 @clawdbot/lobster 软件包作为嵌入式运行器，在进程内运行 Lobster 工作流。不会生成外部 lobster 子进程；工具调用会直接返回 JSON 信封。如果流水线暂停以等待审批，信封中会携带恢复令牌（或简短的审批 ID），以便稍后继续。

启用

Lobster 是一个可选插件工具，默认未启用。它已内置提供，因此不需要单独安装——只需允许使用该工具：

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

或按智能体配置：

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

在沙箱隔离的工具上下文中，该工具会被完全禁用。

如果需要使用独立的 Lobster CLI 进行开发或运行外部流水线（在嵌入式 Gateway 网关运行器之外），请从 Lobster 仓库安装它，并将 lobster 放入 PATH。

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

构建使用 JSON 通信的小型命令，然后将它们链接为一次 Lobster 调用。（以下为示例命令名称——请替换为你自己的命令。）

inbox list --jsoninbox categorize --jsoninbox 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}

如果流水线请求审批，请使用令牌恢复：

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

示例：将输入项映射为工具调用：

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": { "alsoAllow": ["llm-task"] }      }    ]  }}

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

内置 Lobster 插件在 Gateway 网关内以进程内方式运行工作流。在该嵌入式模式下，openclaw.invoke 不会自动继承用于嵌套 OpenClaw CLI 工具调用的 Gateway 网关 URL/身份验证上下文。

这意味着以下模式目前在嵌入式运行器中并不可靠：

openclaw.invoke --tool llm-task --action json --args-json '{ ... }'

仅当在已使用正确 Gateway 网关/身份验证上下文配置 openclaw.invoke 的环境中运行独立 Lobster CLI 时，才使用以下示例。

openclaw.invoke --tool llm-task --action json --args-json '{  "prompt": "根据输入的电子邮件，返回意图和草稿。",  "thinking": "low",  "input": { "subject": "你好", "body": "你能帮忙吗？" },  "schema": {    "type": "object",    "properties": {      "intent": { "type": "string" },      "draft": { "type": "string" }    },    "required": ["intent", "draft"],    "additionalProperties": false  }}'

如果目前使用的是嵌入式 Lobster 插件，请优先选择以下任一方式：

• 在 Lobster 外部直接调用 llm-task 工具；或者
• 在添加受支持的嵌入式桥接之前，在 Lobster 流水线内使用非 openclaw.invoke 步骤。

有关详细信息和配置选项，请参阅 LLM Task。

工作流文件（.lobster）

Lobster 可以运行包含 name、args、steps、env、condition 和 approval 字段的 YAML/JSON 工作流文件。在工具调用中将 pipeline 设置为文件路径。

name: inbox-triageargs:  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 控制步骤是否执行。

注入的环境变量

每个步骤的 shell 都会继承父环境以及以下由 Lobster 注入的变量，因此命令可以引用已解析的工作流参数，而无需将原始值嵌入命令字符串：

• LOBSTER_ARG_<NAME>——每个工作流参数对应一个。名称会转换为大写，并将每一段连续的非字母数字字符折叠为 _，因此参数 user-id 会变为 LOBSTER_ARG_USER_ID。
• LOBSTER_ARGS_JSON——将所有已解析参数表示为单个 JSON 字符串。

以上就是完整的注入变量集合。不存在 LOBSTER_STEP_<id>_STDOUT 或 LOBSTER_STEP_<id>_JSON_<field> 之类的按步骤输出变量；shell 会将这些名称视为未设置，因此参数展开默认值可能会掩盖错误。应改为通过步骤引用读取先前步骤的输出——在 stdin:、env: 或 condition: 值中使用 $step.stdout、$step.json 或 $step.json.<field>。（LOBSTER_STATE_DIR 是用于状态目录的独立运行时设置，并非每次运行的参数。）

工具参数

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}

resume 接受 token（来自 requiresApproval 的完整恢复令牌）或 approvalId（来自同一对象的简短 ID）——使用暂停运行所返回的任一值。approve 为必填项。

托管式 Task Flow 模式

在 run 上传入 flowControllerId 和 flowGoal（或在 resume 上传入 flowId 和 flowExpectedRevision），会通过插件运行时的托管式 Task Flow API 驱动调用，而不是返回裸信封：OpenClaw 会创建或恢复持久化流程记录，将 Lobster 信封应用于该记录（审批时应用 waiting，完成时应用 succeeded/failed），并返回 { ok, envelope, flow, mutation }。此模式需要绑定的 Task Flow 运行时，适用于需要在 Gateway 网关重启后仍保留持久化流程状态的插件/控制器代码，而不适用于典型的临时智能体使用场景。

输出信封

Lobster 返回一个 JSON 信封，其状态为以下三种之一：

• ok——成功完成
• needs_approval——已暂停；requiresApproval 携带 resumeToken 和简短的 approvalId，二者均可用于恢复运行
• cancelled——已明确拒绝或取消

该工具会同时通过 content（格式化 JSON）和 details（原始对象）提供该信封。

审批

如果存在 requiresApproval，请检查提示并作出决定：

• approve: true——恢复并继续执行副作用操作
• approve: false——取消并结束工作流

使用 approve --preview-from-stdin --limit N 可将 JSON 预览附加到审批请求，而无需自定义 jq/heredoc 拼接代码。恢复状态以小型 JSON 文件形式存储在 Lobster 状态目录下（默认为 ~/.lobster/state，可使用 LOBSTER_STATE_DIR 覆盖）；令牌本身仅编码指向该状态的指针，而不包含完整的流水线状态。

OpenProse

OpenProse 与 Lobster 配合良好：使用 /prose 编排多智能体准备工作，然后运行 Lobster 流水线进行确定性审批。如果 Prose 程序需要 Lobster，请通过 tools.subagents.tools 为子智能体允许使用 lobster 工具。请参阅 OpenProse。

安全性

• 仅限本地进程内 - 工作流在 Gateway 网关进程内执行；插件本身不发起 网络调用。
• 无密钥 - Lobster 不管理 OAuth；它调用负责此功能的 OpenClaw 工具。
• 支持沙箱隔离 - 工具上下文处于沙箱隔离状态时禁用。
• 强化保护 - 嵌入式运行器强制执行超时和输出上限。

故障排查

了解更多

• 插件
• 插件工具编写

案例研究：社区工作流

一个公开示例：一个“第二大脑”CLI + Lobster 管道，用于管理三个 Markdown 仓库（个人、伴侣、共享）。该 CLI 输出统计信息、 收件箱列表和陈旧内容扫描的 JSON；Lobster 将这些命令串联成 weekly-review、inbox-triage、memory-consolidation 和 shared-task-sync 等工作流，每个工作流都设有审批关卡。AI 在可用时负责判断 （分类），不可用时则回退到确定性规则。

• 帖子：https://x.com/plattenschieber/status/2014508656335770033
• 仓库：https://github.com/bloomedai/brain-cli

相关内容

• 自动化 - 所有自动化机制
• 工具概览 - 所有可用的智能体工具