Lobster 将多步骤工具流水线作为一次确定性的工具调用运行，并提供明确的审批检查点和恢复令牌。它位于分离式后台工作的上一层：如需编排跨多个分离式任务的流程，请参阅 Task Flow（openclaw tasks flow）；如需查看任务活动账本，请参阅后台任务。
如果没有 Lobster，多步骤作业意味着需要多次往返工具调用，由模型编排每个步骤。Lobster 将这种编排移入类型化运行时：
- 一次调用代替多次调用：一次 Lobster 工具调用即可返回整个流水线的结构化结果。
- 内置审批：副作用操作（发送、发布、删除）会暂停工作流，直至获得明确批准。
- 可恢复：暂停的工作流会返回一个令牌；批准后即可恢复，无需重新运行之前的步骤。
Lobster 是一种小型、受限的 DSL，而不是通用脚本语言：批准/恢复是持久的内置原语；流水线是数据（易于记录、比较差异、重放和审查）；精简的语法限制了“创造性”代码路径，使验证保持切合实际；超时、输出上限、沙箱检查和允许列表均由运行时强制执行，而不是由各个脚本执行。每个步骤仍然可以调用任意 CLI 或脚本——如果需要更丰富的编写语言，可以使用其他工具生成 .lobster 文件。
如果没有 Lobster，重复执行的电子邮件分类流程如下：
使用 Lobster 后，同一作业只需一次调用，该调用会暂停以等待审批，并可在之后恢复：
工作原理
OpenClaw 使用内置的 @clawdbot/lobster 软件包作为嵌入式运行器，在进程内运行 Lobster 工作流。不会生成外部 lobster 子进程；工具调用会直接返回 JSON 信封。如果流水线暂停以等待审批，信封中会携带恢复令牌（或简短的审批 ID），以便稍后继续。
Lobster 是一个可选插件工具，默认未启用。它已内置提供，因此不需要单独安装——只需允许使用该工具：
或按智能体配置：
alsoAllow 会在当前工具配置文件之上添加 lobster，而不会限制其他核心工具。仅当需要限制性允许列表模式时，才改用 tools.allow。
lobster 放入 PATH。
模式：小型 CLI + JSON 管道 + 审批
构建使用 JSON 通信的小型命令，然后将它们链接为一次 Lobster 调用。（以下为示例命令名称——请替换为你自己的命令。）
如果流水线请求审批，请使用令牌恢复：
示例：将输入项映射为工具调用：
仅 JSON 的 LLM 步骤（llm-task）
如需在工作流中使用结构化 LLM 步骤，请启用可选的 llm-task 插件工具，并从 Lobster 调用它：
重要限制：嵌入式 Lobster 与 openclaw.invoke
内置 Lobster 插件在 Gateway 网关内以进程内方式运行工作流。在该嵌入式模式下，openclaw.invoke 不会自动继承用于嵌套 OpenClaw CLI 工具调用的 Gateway 网关 URL/身份验证上下文。
这意味着以下模式目前在嵌入式运行器中并不可靠：
仅当在已使用正确 Gateway 网关/身份验证上下文配置 openclaw.invoke 的环境中运行独立 Lobster CLI 时，才使用以下示例。
如果目前使用的是嵌入式 Lobster 插件，请优先选择以下任一方式：
- 在 Lobster 外部直接调用
llm-task 工具；或者
- 在添加受支持的嵌入式桥接之前，在 Lobster 流水线内使用非
openclaw.invoke 步骤。
有关详细信息和配置选项，请参阅 LLM Task。
工作流文件（.lobster）
Lobster 可以运行包含 name、args、steps、env、condition 和 approval 字段的 YAML/JSON 工作流文件。在工具调用中将 pipeline 设置为文件路径。
注意：
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
使用参数运行工作流文件：
resume
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 在可用时负责判断
（分类），不可用时则回退到确定性规则。
相关内容
