本页内容
本页内容
工具
Lobster
Lobster 将多步骤工具管道作为一个可重复的工具调用来运行,并具有显式的 approval/input 检查点和恢复令牌。检查点属于 Lobster 运行程序,而不是单独的编排注册表。
为什么
如果没有 Lobster,一个多步骤任务就意味着很多次往返的工具调用,由模型来协调每一步。Lobster 将这种编排放进了一个带类型的运行时中:
- 一次调用,而不是多次:一次 Lobster 工具调用即可返回整个流水线的结构化结果。
- 内置审批:有副作用的操作(发送、发布、删除)会暂停工作流,直到明确批准。
- 可恢复:被暂停的工作流会返回一个 token;批准后即可恢复,而无需重新运行之前的步骤。
Lobster 不是通用脚本语言,而是一个小而受限的 DSL:approve/resume 是持久化的、内置的原语;流水线就是数据(便于日志记录、diff、回放和审查);微小的语法限制了“创造性”的代码路径,因此验证仍然切实可行;超时、输出上限、沙箱检查和 allowlist 都由运行时强制执行,而不是由每个脚本各自实现。每一步仍然可以调用任意 CLI 或脚本——如果你想要更丰富的编写语言,也可以从其他工具生成 .lobster 文件。
如果没有 Lobster,一个重复出现的邮件分拣流程会像这样:
使用 Lobster,同样的任务只需一次调用,并会在审批时暂停、之后再恢复:
工作原理
单独安装的官方 @openclaw/lobster 插件使用其嵌入式 @clawdbot/lobster 运行时运行 Lobster 工作流程 in-process。没有产生外部 lobster 子进程;工具调用直接返回 JSON 信封。如果管道因批准或输入而暂停,Lobster 会保存其延续并返回恢复令牌。批准请求还可以带有简短的批准 ID。通话在检查站结束;没有进程等待用户的回答。
启用
Lobster 是一个 可选 插件工具,默认情况下未安装或启用。安装官方插件:
安装自动应用于正在运行的网关;否则下次启动时生效。请参阅 应用更改并检查 。
然后全局允许该工具:
或者按代理单独配置:
在沙箱化的工具上下文中,该工具会被完全禁用。
如果你在开发或外部流水线中需要独立的 Lobster CLI(即不通过内置网关运行器),请从 Lobster 仓库安装它,并将 lobster 放到 PATH 中。
模式:小型 CLI + JSON 管道 + 审批
构建会说 JSON 的小型命令,然后将它们串联成一次 Lobster 调用。 (下面是示例命令名称——请替换为你自己的。)
如果管道请求审批,请使用 token 恢复:
示例:将输入项映射为工具调用:
JSON-仅 LLM 步骤(llm 任务)
对于工作流中的结构化 LLM 步骤,启用可选的 llm-task 插件工具,并从 Lobster 中调用它:
重要限制:嵌入式 Lobster 与 openclaw.invoke
已安装的Lobster插件运行工作流程进行中网关内。在那种嵌入模式下,openclaw.invoke做不是自动继承网关URL/auth嵌套的上下文OpenClaw CLI工具调用。
这意味着以下模式在嵌入式运行器中目前不可靠:
仅当在已使用正确的 gateway/auth 上下文配置 openclaw.invoke 的环境中运行 standalone Lobster CLI 时,才使用下面的示例。
对于 openclaw.invoke 和 clawd.invoke,仅 localhost、127.0.0.1 或 [::1] 目标接受环境 OPENCLAW_TOKEN 或 CLAWD_TOKEN 凭证。要将凭证发送到另一个 HTTP(S) 端点,请显式传递 --token。此规则也适用于显式配置远程连接的嵌入式工作流。此命令参数是远程网关凭据,而不是 Lobster 工具的批准-恢复 token 参数。如果调用超时或调度后失败,Lobster 不会自动重试,因为网关可能已经执行了该操作。
如果你当前使用的是嵌入式 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-injected 变量,因此命令可以引用已解析的工作流参数,而无需将原始值嵌入到命令字符串中:
LOBSTER_ARG_<NAME>- 每个工作流参数对应一个。名称会转换为大写, 并将每一段非字母数字字符折叠为_,因此参数user-id会变成LOBSTER_ARG_USER_ID。LOBSTER_ARGS_JSON- 所有已解析参数组成的单个 JSON 字符串。
这就是完整的注入集。有no每步输出变量如LOBSTER_STEP_<id>_STDOUT或LOBSTER_STEP_<id>_JSON_<field>; shell 将这些名称视为未设置,因此参数扩展默认值可以隐藏错误。通过 stdin:、env: 或 condition: 值中的步骤引用($step.stdout、$step.json 或 $step.json.<field>)读取先前步骤的输出。 (LOBSTER_STATE_DIR 是状态目录的单独运行时设置,而不是每次运行参数。)
工具参数
run
使用参数运行工作流文件:
| 字段 | 默认值 | 笔记 |
|---|---|---|
pipeline |
必填 | 内联管道字符串,或以 .lobster/.yaml/.yml/.json 结尾的工作流文件路径。 |
cwd |
网关CWD | 相对工作目录;必须解析到 gateway 工作目录内(拒绝绝对路径)。 |
timeoutMs |
20000 |
超过此时间则中止运行。 |
maxStdoutBytes |
512000 |
如果捕获的 stdout、stderr 或嵌入的 JSON 结果超过此大小,则中止。 |
argsJson |
- | 工作流文件的参数 JSON 字符串(对内联管道忽略)。 |
resume
对于批准,请使用 requiresApproval 中的 token 或 approvalId 以及布尔值 approve。对于输入,请使用 requiresInput 和 responseJson 中的 token。要取消任一类型的检查点,请使用 cancel: true 而不是决策。准确提供 approve、responseJson 或 cancel: true 之一。
结构化输入
工作流 input 步骤或内联 ask 阶段返回 needs_input 以及问题、JSON 架构和恢复令牌。可选的 defaults 和 subject 提供建议值和要查看的材料。例如:
代理在聊天中提出问题,然后将用户的答案发送为 JSON:
responseJson 可以编码返回模式允许的任何值,而不仅仅是一个对象。 Lobster 在继续之前验证答案。无效的 JSON 或与架构不匹配的答案会使检查点可供更正。简历可以返回另一个问题或批准请求。
这是 chat/tool 交互,而不是收件箱卡或表单。该插件不会列出待处理的检查点;保留返回的令牌以便稍后恢复。与批准令牌一样,拥有输入令牌允许允许使用该工具的调用者恢复;令牌不绑定到 OpenClaw 用户或会话。
输出信封
Lobster 返回具有以下四种状态之一的 JSON 信封:
ok- 成功完成needs_approval- 已暂停;requiresApproval携带一个resumeToken和一个简短的approvalId,二者任意一个都可以恢复运行needs_input- 暂停;requiresInput携带问题、答案模式和resumeTokencancelled- 已明确拒绝或取消
该工具会在 content(格式化的 JSON)和 details (原始对象)中同时展示该信封。
审批
如果存在 requiresApproval,请检查提示并决定:
approve: true- 恢复并继续副作用approve: false- 取消并完成工作流
使用 approve --preview-from-stdin --limit N 将 JSON 预览附加到审批请求,无需自定义 jq/heredoc 胶水。恢复状态以小 JSON 文件形式存储在 Lobster 状态目录下(默认为 ~/.lobster/state,用 LOBSTER_STATE_DIR 覆盖);令牌本身仅编码指向该状态的指针,而不是完整的管道状态。
安全性
- 仅限本地进程内 - 工作流在网关进程内执行;插件本身不发起任何网络调用。
- 无密钥 - Lobster 不管理 OAuth;它调用由 OpenClaw 工具来处理这些内容。
- 感知沙箱 - 当工具上下文处于沙箱中时会被禁用。
- 加固 - 由嵌入式运行器强制执行超时和输出上限。
故障排查
| 错误 | 原因/修复 |
|---|---|
lobster runtime timed out |
Pipeline 超过了 timeoutMs。增大它,或者拆分该流水线。 |
lobster stdout exceeded maxStdoutBytes(或 stderr) |
捕获到的输出超过了上限。提高 maxStdoutBytes,或者减少输出。 |
lobster runtime result exceeded maxStdoutBytes |
JSON 结果超出上限。提高maxStdoutBytes或减少输出。 |
run --args-json must be valid JSON |
argsJson(workflow-file 运行)解析失败。修正 JSON 字符串。 |
lobster runtime failed(或其他 runtime_error 消息) |
内嵌运行时返回了错误封装。请检查网关日志以获取详细信息。 |
了解更多
案例研究:社区工作流
一个公共示例:管理三个 Markdown 金库(个人、合作伙伴、共享)的“第二大脑”CLI + Lobster 管道。 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
相关内容
- Automation - 所有自动化机制
- Tools Overview - 所有可用的代理工具。
- Lobster 插件参考 - 插件的清单、配置和工具参考